diff --git a/.gitattributes b/.gitattributes
index f21efa3b5..2438a4f31 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -9,3 +9,8 @@
 # test/config-schema-generated.test.ts; pin LF so Windows autocrlf
 # checkouts do not produce spurious drift failures.
 config/schema/config.schema.json text eol=lf
+crates/testkit/goldens/** -text
+crates/**/*.rs text eol=lf
+Cargo.toml text eol=lf
+crates/**/Cargo.toml text eol=lf
+Cargo.lock text eol=lf
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
new file mode 100644
index 000000000..93ea4c9d3
--- /dev/null
+++ b/.github/workflows/rust.yml
@@ -0,0 +1,52 @@
+name: Rust
+
+on:
+  push:
+    branches: [main]
+    paths: ["crates/**", "Cargo.toml", "Cargo.lock", ".github/workflows/rust.yml"]
+  pull_request:
+    branches: [main]
+    paths: ["crates/**", "Cargo.toml", "Cargo.lock", ".github/workflows/rust.yml"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: rust-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@b3b07ba8b418998c39fb20f53e8b695cdcc8de1b # stable
+        with:
+          toolchain: "1.96.0"
+          components: clippy, rustfmt
+
+      - name: Cache cargo
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: cargo-${{ matrix.os }}-${{ hashFiles('Cargo.lock') }}
+
+      - name: Check
+        run: cargo check --workspace --all-targets
+
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Test
+        run: cargo test --workspace
diff --git a/.gitignore b/.gitignore
index 8b5979914..275a0d4d8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,3 +35,6 @@ test-results.md
 
 # OMC session scratch (never publish)
 .omc/
+
+# Rust
+/target
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 000000000..a13c66c2b
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,3108 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "alloc-no-stdlib"
+version = "2.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3"
+
+[[package]]
+name = "alloc-stdlib"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195"
+dependencies = [
+ "alloc-no-stdlib",
+]
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "assert-json-diff"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e4f2b81832e72834d7518d8487a0396a28cc408186a2e8854c0f98011faf12"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "async-compression"
+version = "0.4.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "axum"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
+dependencies = [
+ "axum-core",
+ "bytes",
+ "form_urlencoded",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde_core",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "brotli"
+version = "8.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cc91aac060a7a1e25823bdccbfb6af1875b88f17c6daac97894eed8207166b3"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+ "brotli-decompressor",
+]
+
+[[package]]
+name = "brotli-decompressor"
+version = "5.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a32acac15fe1967bc3986b2a6347dffc965602354ea6f450ad07e8bfd253583"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "chacha20"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "windows-link",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "cma-accounts"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-cli-mirror",
+ "cma-core",
+ "cma-rotation",
+ "cma-storage",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+]
+
+[[package]]
+name = "cma-auth"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "axum",
+ "base64",
+ "bytes",
+ "cma-core",
+ "cma-testkit",
+ "futures",
+ "http",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "insta",
+ "proptest",
+ "rand 0.9.5",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "subtle",
+ "tempfile",
+ "thiserror",
+ "tokio",
+ "url",
+ "uuid",
+ "wiremock",
+]
+
+[[package]]
+name = "cma-bin"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-manager",
+ "cma-proxy",
+ "cma-runtime",
+ "cma-testkit",
+ "cma-wrapper",
+ "insta",
+ "proptest",
+ "serial_test",
+ "tempfile",
+ "tokio",
+]
+
+[[package]]
+name = "cma-cli-mirror"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+]
+
+[[package]]
+name = "cma-config"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "tempfile",
+ "thiserror",
+ "tokio",
+ "uuid",
+]
+
+[[package]]
+name = "cma-core"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "base64",
+ "chrono",
+ "futures",
+ "home",
+ "insta",
+ "libc",
+ "proptest",
+ "rand 0.9.5",
+ "regex",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "thiserror",
+ "tokio",
+ "unicode-segmentation",
+ "uuid",
+]
+
+[[package]]
+name = "cma-manager"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "chrono",
+ "clap",
+ "cma-accounts",
+ "cma-auth",
+ "cma-cli-mirror",
+ "cma-config",
+ "cma-core",
+ "cma-quota",
+ "cma-request",
+ "cma-rotation",
+ "cma-runtime",
+ "cma-storage",
+ "cma-testkit",
+ "cma-tui",
+ "cma-usage",
+ "insta",
+ "proptest",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "uuid",
+]
+
+[[package]]
+name = "cma-proxy"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "axum",
+ "base64",
+ "bytes",
+ "cma-accounts",
+ "cma-auth",
+ "cma-cli-mirror",
+ "cma-config",
+ "cma-core",
+ "cma-quota",
+ "cma-request",
+ "cma-rotation",
+ "cma-runtime",
+ "cma-storage",
+ "cma-testkit",
+ "cma-usage",
+ "futures",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "insta",
+ "proptest",
+ "rand 0.9.5",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "subtle",
+ "tempfile",
+ "tokio",
+ "uuid",
+ "wiremock",
+]
+
+[[package]]
+name = "cma-quota"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "chrono",
+ "cma-accounts",
+ "cma-config",
+ "cma-core",
+ "cma-request",
+ "cma-rotation",
+ "cma-storage",
+ "cma-testkit",
+ "cma-usage",
+ "futures",
+ "insta",
+ "notify",
+ "proptest",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "wiremock",
+]
+
+[[package]]
+name = "cma-request"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "base64",
+ "bytes",
+ "chrono",
+ "cma-accounts",
+ "cma-auth",
+ "cma-config",
+ "cma-core",
+ "cma-storage",
+ "cma-testkit",
+ "futures",
+ "http",
+ "insta",
+ "proptest",
+ "regex",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "tokio-util",
+ "url",
+ "wiremock",
+]
+
+[[package]]
+name = "cma-rotation"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "rand 0.9.5",
+ "serde_json",
+ "serial_test",
+ "tempfile",
+ "tokio",
+]
+
+[[package]]
+name = "cma-runtime"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "chrono",
+ "cma-accounts",
+ "cma-auth",
+ "cma-cli-mirror",
+ "cma-config",
+ "cma-core",
+ "cma-quota",
+ "cma-request",
+ "cma-rotation",
+ "cma-storage",
+ "cma-testkit",
+ "cma-usage",
+ "insta",
+ "proptest",
+ "rand 0.9.5",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha1",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "uuid",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "cma-storage"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "thiserror",
+ "tokio",
+]
+
+[[package]]
+name = "cma-testkit"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "insta",
+ "proptest",
+ "serde_json",
+ "serial_test",
+ "tempfile",
+]
+
+[[package]]
+name = "cma-tui"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "chrono",
+ "cma-core",
+ "cma-testkit",
+ "crossterm",
+ "insta",
+ "proptest",
+ "serde_json",
+ "serial_test",
+ "signal-hook",
+ "tempfile",
+ "tokio",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "cma-usage"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "cma-core",
+ "cma-testkit",
+ "insta",
+ "proptest",
+ "rand 0.9.5",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "uuid",
+]
+
+[[package]]
+name = "cma-wrapper"
+version = "3.0.0-alpha.0"
+dependencies = [
+ "chrono",
+ "cma-accounts",
+ "cma-cli-mirror",
+ "cma-config",
+ "cma-core",
+ "cma-proxy",
+ "cma-runtime",
+ "cma-storage",
+ "cma-testkit",
+ "insta",
+ "junction",
+ "proptest",
+ "rand 0.9.5",
+ "serde",
+ "serde_json",
+ "serial_test",
+ "tempfile",
+ "tokio",
+ "uuid",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "compression-codecs"
+version = "0.4.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
+dependencies = [
+ "brotli",
+ "compression-core",
+ "flate2",
+ "memchr",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
+
+[[package]]
+name = "console"
+version = "0.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fe5f465a4f6fee88fad41b85d990f84c835335e85b5d9e6e63e0d06d28cba7c"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "convert_case"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "deadpool"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0be2b1d1d6ec8d846f05e137292d0b89133caf95ef33695424c09568bdd39b1b"
+dependencies = [
+ "deadpool-runtime",
+ "lazy_static",
+ "num_cpus",
+ "tokio",
+]
+
+[[package]]
+name = "deadpool-runtime"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "092966b41edc516079bdf31ec78a2e0588d1d0c08f78b91d8307215928642b2b"
+
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "encode_unicode"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
+
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "fsevent-sys"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76ee7a02da4d231650c7cea31349b889be2f45ddb3ef3032d2ec8185f6313fd2"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "futures"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+
+[[package]]
+name = "futures-task"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+
+[[package]]
+name = "futures-util"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi 6.0.0",
+ "rand_core 0.10.1",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
+[[package]]
+name = "home"
+version = "0.5.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
+name = "hyper"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "httpdate",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+ "webpki-roots",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "inotify"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "153be1941a183ec9ccd095ddbe17a8b8d435ef6c76e9e02451b933c3999af2c8"
+dependencies = [
+ "bitflags",
+ "inotify-sys",
+ "libc",
+]
+
+[[package]]
+name = "inotify-sys"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c033f80b2c113cdf91ab7a33faa9cbc014726dcad99880c8609af2a370edf37d"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "insta"
+version = "1.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
+dependencies = [
+ "console",
+ "once_cell",
+ "serde",
+ "similar",
+ "tempfile",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "junction"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8cfc352a66ba903c23239ef51e809508b6fc2b0f90e3476ac7a9ff47e863ae95"
+dependencies = [
+ "scopeguard",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "kqueue"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "273c0752728918e0ac4976f2b275b6fefb9ecd400585dec929419f3844cd87b5"
+dependencies = [
+ "kqueue-sys",
+ "libc",
+]
+
+[[package]]
+name = "kqueue-sys"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07293a4e297ac234359b510362495713f75ea345d5307140414f20c69ffeb087"
+dependencies = [
+ "bitflags",
+ "libc",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+
+[[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+dependencies = [
+ "libc",
+ "log",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "notify"
+version = "8.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3"
+dependencies = [
+ "bitflags",
+ "fsevent-sys",
+ "inotify",
+ "kqueue",
+ "libc",
+ "log",
+ "mio",
+ "notify-types",
+ "walkdir",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "notify-types"
+version = "2.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "num_cpus"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "proptest"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
+dependencies = [
+ "bit-set",
+ "bit-vec",
+ "bitflags",
+ "num-traits",
+ "rand 0.9.5",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
+[[package]]
+name = "quinn"
+version = "0.11.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560"
+dependencies = [
+ "bytes",
+ "getrandom 0.4.3",
+ "lru-slab",
+ "rand 0.10.2",
+ "rand_pcg",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.3",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rand_pcg"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
+dependencies = [
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "reqwest"
+version = "0.12.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
+dependencies = [
+ "base64",
+ "bytes",
+ "encoding_rs",
+ "futures-core",
+ "futures-util",
+ "h2",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams",
+ "web-sys",
+ "webpki-roots",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+dependencies = [
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error",
+ "tempfile",
+ "wait-timeout",
+]
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "serial_test"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "699f4197115b8a7e7ff19c9a315a4bd6fffec26cc4626ef45ecaea389e081c6d"
+dependencies = [
+ "futures-executor",
+ "futures-util",
+ "log",
+ "once_cell",
+ "parking_lot",
+ "serial_test_derive",
+]
+
+[[package]]
+name = "serial_test_derive"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94e153fc76e1c6a068703d6d29c508a0b15c061c4b7e43da59cc097bc342673c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "sha1"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "similar"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbbb5d9659141646ae647b42fe094daf6c6192d1620870b449d9557f748b2daa"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "tokio"
+version = "1.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "libc",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "async-compression",
+ "bitflags",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "pin-project-lite",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "url",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "uuid"
+version = "1.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c62df1340f32221cb9c54d6a27b030e3dba64361d4a95bed55f9aacb44da291d"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8622dcb61c0bcc9fffa6938bed81210af2da9a7e4a1a834b2e37a59b6dfb6141"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
+[[package]]
+name = "wiremock"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08db1edfb05d9b3c1542e521aea074442088292f00b5f28e435c714a98f85031"
+dependencies = [
+ "assert-json-diff",
+ "base64",
+ "deadpool",
+ "futures",
+ "http",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "log",
+ "once_cell",
+ "regex",
+ "serde",
+ "serde_json",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 000000000..397190ceb
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,77 @@
+[workspace]
+resolver = "3"
+members = [
+  "crates/core",
+  "crates/config",
+  "crates/storage",
+  "crates/rotation",
+  "crates/climirror",
+  "crates/usage",
+  "crates/tui",
+  "crates/auth",
+  "crates/accounts",
+  "crates/request",
+  "crates/quota",
+  "crates/runtime",
+  "crates/proxy",
+  "crates/wrapper",
+  "crates/manager",
+  "crates/bin",
+  "crates/testkit",
+]
+
+[workspace.package]
+version = "3.0.0-alpha.0"
+edition = "2024"
+rust-version = "1.96"
+license = "MIT"
+repository = "https://github.com/ndycode/codex-multi-auth"
+
+[workspace.dependencies]
+# async
+tokio = { version = "1.47", features = ["rt-multi-thread", "macros", "net", "io-util", "fs", "time", "process", "sync", "signal"] }
+tokio-util = { version = "0.7", features = ["io"] }
+futures = "0.3"
+bytes = "1.10"
+async-trait = "0.1"
+# http server
+axum = { version = "0.8", default-features = false, features = ["http1", "json", "tokio", "query", "original-uri"] }
+hyper = { version = "1.7", features = ["http1", "server", "client"] }
+hyper-util = { version = "0.1", features = ["tokio", "server", "http1"] }
+http = "1.3"
+http-body = "1.0"
+http-body-util = "0.1"
+# http client - rustls ONLY, no openssl anywhere
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "stream", "gzip", "brotli", "deflate", "charset", "http2"] }
+url = "2.5"
+# serialization - preserve_order is MANDATORY (JSON key-order byte compat)
+serde = { version = "1.0", features = ["derive"] }
+serde_json = { version = "1.0", features = ["preserve_order"] }
+# cli
+clap = { version = "4.5", features = ["derive"] }
+# terminal
+crossterm = "0.29"
+unicode-segmentation = "1.12"
+# crypto / random
+sha1 = "0.10"
+sha2 = "0.10"
+subtle = "2.6"
+rand = "0.9"
+uuid = { version = "1.18", features = ["v4"] }
+base64 = "0.22"
+# misc
+thiserror = "2.0"
+chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
+home = "0.5"
+notify = { version = "8", default-features = false, features = ["macos_fsevent"] }
+regex = "1.11"
+# dev
+tempfile = "3"
+serial_test = "3"
+proptest = "1"
+wiremock = "0.6"
+insta = { version = "1", features = ["json"] }
+
+[profile.release]
+lto = "thin"
+strip = "symbols"
diff --git a/crates/accounts/Cargo.toml b/crates/accounts/Cargo.toml
new file mode 100644
index 000000000..c36dff063
--- /dev/null
+++ b/crates/accounts/Cargo.toml
@@ -0,0 +1,27 @@
+[package]
+name = "cma-accounts"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-storage = { path = "../storage" }
+cma-rotation = { path = "../rotation" }
+cma-cli-mirror = { path = "../climirror" }
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/accounts/src/account_policy.rs b/crates/accounts/src/account_policy.rs
new file mode 100644
index 000000000..ca846504e
--- /dev/null
+++ b/crates/accounts/src/account_policy.rs
@@ -0,0 +1,635 @@
+//! Port of `lib/account-policy.ts` — persisted per-account policy store.
+//!
+//! Behavior source: specs/03-accounts.md §3 (+ §11 constants, §13 error
+//! contracts, §15 gotchas 22–23). TS source is authoritative.
+//!
+//! On-disk format (`<multiAuthDir>/account-policies.json`, golden fixture
+//! `crates/testkit/goldens/account-policies.json`):
+//! `{ "version": 1, "accounts": { "sha256:<64hex>": { accountKey, tags,
+//! weight, paused, drained, note, updatedAt } } }` — 2-space pretty print,
+//! trailing newline, file mode 0600, dir 0700, field order as listed, map
+//! insertion order preserved.
+//!
+//! Concurrency: NO cross-process lock — atomic temp+rename plus an
+//! in-process write queue (module promise chain in TS; a static tokio
+//! `Mutex` here). Last writer wins across processes (spec §14).
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::{
+    TrailingNewline, WriteJsonOptions, stringify_pretty2, write_json_atomic,
+};
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_storage::identity::AccountIdentityLike;
+use serde::Serialize;
+use serde::ser::{SerializeMap, Serializer};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+/// TS `ACCOUNT_POLICY_FILE_NAME`.
+pub const ACCOUNT_POLICY_FILE_NAME: &str = "account-policies.json";
+
+const TAG_MAX_LEN_UTF16: usize = 64;
+const NOTE_MAX_LEN_UTF16: usize = 500;
+const WEIGHT_MIN: f64 = 0.0;
+const WEIGHT_MAX: f64 = 10.0;
+const WEIGHT_DEFAULT: f64 = 1.0;
+
+/// Retryable read/rename codes (TS `RETRYABLE_FS_CODES`).
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+
+/// In-process write serialization (TS module-level `writeQueue` promise
+/// chain; tokio's Mutex is FIFO-fair, and a failed task never poisons the
+/// queue — matching the `.catch(() => undefined)` chain reset).
+static WRITE_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/// TS `interface AccountPolicy`. Field declaration order == on-disk emission
+/// order (byte compat). `note` serializes as literal `null` when absent
+/// (TS always emits the key).
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountPolicy {
+    /// `"sha256:<64 hex>"` — forced to the map key on normalize.
+    pub account_key: String,
+    /// Normalized, deduped, sorted.
+    pub tags: Vec<String>,
+    /// Clamped to `[0, 10]`, default `1`.
+    pub weight: f64,
+    /// Hard block (request-policy layer excludes the account).
+    pub paused: bool,
+    /// Soft drain (no new sessions).
+    pub drained: bool,
+    /// Trimmed, max 500 UTF-16 units; `None` serializes as `null`.
+    pub note: Option<String>,
+    /// Epoch ms, `0` when unknown.
+    pub updated_at: f64,
+}
+
+/// TS `interface AccountPolicyStore` (`version` is always the literal `1`;
+/// the Rust type omits the field and the serializer emits it).
+///
+/// `accounts` preserves JS-object insertion order: re-assigning an existing
+/// key keeps its position; new keys append.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AccountPolicyStore {
+    entries: Vec<(String, AccountPolicy)>,
+}
+
+impl AccountPolicyStore {
+    /// TS `emptyStore()`.
+    pub fn empty() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn get(&self, key: &str) -> Option<&AccountPolicy> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, policy)| policy)
+    }
+
+    pub fn get_mut(&mut self, key: &str) -> Option<&mut AccountPolicy> {
+        self.entries
+            .iter_mut()
+            .find(|(k, _)| k == key)
+            .map(|(_, policy)| policy)
+    }
+
+    /// JS `store.accounts[key] = policy`: replaces in place (keeping
+    /// position) when the key exists, otherwise appends.
+    pub fn insert(&mut self, key: impl Into<String>, policy: AccountPolicy) {
+        let key = key.into();
+        if let Some(entry) = self.entries.iter_mut().find(|(k, _)| *k == key) {
+            entry.1 = policy;
+        } else {
+            self.entries.push((key, policy));
+        }
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, &AccountPolicy)> {
+        self.entries
+            .iter()
+            .map(|(k, policy)| (k.as_str(), policy))
+    }
+}
+
+impl Serialize for AccountPolicyStore {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        struct Accounts<'a>(&'a [(String, AccountPolicy)]);
+        impl Serialize for Accounts<'_> {
+            fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+                let mut map = serializer.serialize_map(Some(self.0.len()))?;
+                for (key, policy) in self.0 {
+                    map.serialize_entry(key, policy)?;
+                }
+                map.end()
+            }
+        }
+        let mut map = serializer.serialize_map(Some(2))?;
+        map.serialize_entry("version", &1)?;
+        map.serialize_entry("accounts", &Accounts(&self.entries))?;
+        map.end()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Normalization (must match TS byte-for-byte on re-save)
+// ---------------------------------------------------------------------------
+
+/// JS `String.prototype.slice(0, n)` — cuts at `n` UTF-16 code units, never
+/// splitting a surrogate pair (a split pair would be a lone surrogate in JS;
+/// unrepresentable in Rust, so the whole char is dropped instead).
+fn slice_utf16_units(value: &str, max_units: usize) -> String {
+    let mut units = 0usize;
+    let mut end = value.len();
+    for (idx, ch) in value.char_indices() {
+        let width = ch.len_utf16();
+        if units + width > max_units {
+            end = idx;
+            break;
+        }
+        units += width;
+    }
+    value[..end].to_string()
+}
+
+/// JS default `Array.prototype.sort()` comparator over strings — UTF-16
+/// code-unit lexicographic order (differs from Rust's UTF-8 byte order only
+/// for astral-vs-BMP mixes, but stay exact).
+fn js_string_cmp(a: &str, b: &str) -> std::cmp::Ordering {
+    a.encode_utf16().cmp(b.encode_utf16())
+}
+
+/// TS `normalizeTag`: trim, lowercase, collapse runs of `[^a-z0-9._-]` to a
+/// single `-`; empty → `None`; capped at 64 units.
+fn normalize_tag(value: &str) -> Option<String> {
+    let lowered = value.trim().to_lowercase();
+    let mut normalized = String::with_capacity(lowered.len());
+    let mut in_run = false;
+    for ch in lowered.chars() {
+        if ch.is_ascii_lowercase() || ch.is_ascii_digit() || matches!(ch, '.' | '_' | '-') {
+            normalized.push(ch);
+            in_run = false;
+        } else if !in_run {
+            normalized.push('-');
+            in_run = true;
+        }
+    }
+    if normalized.is_empty() {
+        None
+    } else {
+        Some(slice_utf16_units(&normalized, TAG_MAX_LEN_UTF16))
+    }
+}
+
+/// TS `normalizeWeight`: finite number → clamp `[0, 10]`, else `1`.
+fn normalize_weight(value: Option<f64>) -> f64 {
+    match value {
+        Some(v) if v.is_finite() => v.clamp(WEIGHT_MIN, WEIGHT_MAX),
+        _ => WEIGHT_DEFAULT,
+    }
+}
+
+/// Shared tag-list canonicalization: per-tag normalize, drop `None`s,
+/// Set-dedupe, JS-`.sort()`.
+fn normalize_tag_list<'a>(tags: impl Iterator<Item = &'a str>) -> Vec<String> {
+    let mut seen: Vec<String> = Vec::new();
+    for tag in tags {
+        if let Some(normalized) = normalize_tag(tag)
+            && !seen.contains(&normalized)
+        {
+            seen.push(normalized);
+        }
+    }
+    seen.sort_by(|a, b| js_string_cmp(a, b));
+    seen
+}
+
+fn normalize_note(note: Option<&str>) -> Option<String> {
+    let trimmed = note.unwrap_or("").trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(slice_utf16_units(trimmed, NOTE_MAX_LEN_UTF16))
+    }
+}
+
+/// TS `normalizePolicy(key, value)` over a raw JSON value (load path).
+/// Non-record → all defaults.
+fn normalize_policy_value(key: &str, value: Option<&Value>) -> AccountPolicy {
+    let record = value.and_then(Value::as_object);
+    let tags = match record.and_then(|r| r.get("tags")).and_then(Value::as_array) {
+        Some(raw) => normalize_tag_list(raw.iter().filter_map(Value::as_str)),
+        None => Vec::new(),
+    };
+    let note = normalize_note(record.and_then(|r| r.get("note")).and_then(Value::as_str));
+    AccountPolicy {
+        account_key: key.to_string(),
+        tags,
+        weight: normalize_weight(record.and_then(|r| r.get("weight")).and_then(Value::as_f64)),
+        paused: record.and_then(|r| r.get("paused")) == Some(&Value::Bool(true)),
+        drained: record.and_then(|r| r.get("drained")) == Some(&Value::Bool(true)),
+        note,
+        updated_at: record
+            .and_then(|r| r.get("updatedAt"))
+            .and_then(Value::as_f64)
+            .filter(|v| v.is_finite())
+            .unwrap_or(0.0),
+    }
+}
+
+/// TS `normalizePolicy` applied to an in-memory typed policy (save path —
+/// the TS ran the same function over the live object).
+fn normalize_policy_typed(key: &str, policy: &AccountPolicy) -> AccountPolicy {
+    AccountPolicy {
+        account_key: key.to_string(),
+        tags: normalize_tag_list(policy.tags.iter().map(String::as_str)),
+        weight: normalize_weight(Some(policy.weight)),
+        paused: policy.paused,
+        drained: policy.drained,
+        note: normalize_note(policy.note.as_deref()),
+        updated_at: if policy.updated_at.is_finite() {
+            policy.updated_at
+        } else {
+            0.0
+        },
+    }
+}
+
+/// TS `normalizeStore(value)` over raw JSON (load path). Not a record or
+/// `version !== 1` → empty store; only `sha256:`-prefixed keys survive.
+fn normalize_store_value(value: &Value) -> AccountPolicyStore {
+    let Some(record) = value.as_object() else {
+        return AccountPolicyStore::empty();
+    };
+    // JS `value.version !== 1` — both int `1` and float `1.0` compare equal.
+    if record.get("version").and_then(Value::as_f64) != Some(1.0) {
+        return AccountPolicyStore::empty();
+    }
+    let mut store = AccountPolicyStore::empty();
+    if let Some(accounts) = record.get("accounts").and_then(Value::as_object) {
+        for (key, raw) in accounts {
+            if key.starts_with("sha256:") {
+                store.insert(key.clone(), normalize_policy_value(key, Some(raw)));
+            }
+        }
+    }
+    store
+}
+
+/// TS `normalizeStore` applied to a typed store (save path).
+fn normalize_store_typed(store: &AccountPolicyStore) -> AccountPolicyStore {
+    let mut normalized = AccountPolicyStore::empty();
+    for (key, policy) in store.iter() {
+        if key.starts_with("sha256:") {
+            normalized.insert(key.to_string(), normalize_policy_typed(key, policy));
+        }
+    }
+    normalized
+}
+
+// ---------------------------------------------------------------------------
+// Shared IO helpers (identical pattern in routing_profiles.rs)
+// ---------------------------------------------------------------------------
+
+fn sidecar_backoff() -> Backoff {
+    // TS `sleep(10 * 2 ** attempt)` with a 0-based attempt index — for the
+    // 1-based failed-attempt index n this is 10·2^(n-1) → 10/20/40/80 ms.
+    Backoff::from_fn(|failed_attempt| {
+        10u64.saturating_mul(2u64.saturating_pow(failed_attempt.saturating_sub(1)))
+    })
+}
+
+/// TS `readFileWithRetry` — 5 attempts, EBUSY/EPERM only.
+async fn read_file_with_retry(path: &Path) -> io::Result<String> {
+    with_retry(
+        || async { tokio::fs::read_to_string(path).await },
+        RetryOptions::<io::Error>::new(5, sidecar_backoff()).with_codes(RETRYABLE_FS_CODES),
+    )
+    .await
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/// TS `getAccountPolicyPath()`.
+pub fn get_account_policy_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(ACCOUNT_POLICY_FILE_NAME)
+}
+
+/// TS `getAccountPolicyKey(account, _index?)` — `_index` is accepted and
+/// IGNORED (mutable indexes must never become identity; spec gotcha 22).
+/// Only `accountId`/`email` participate: id wins, else lowercased email,
+/// else `"unknown"` (all id-less+email-less accounts collapse to one key).
+pub fn get_account_policy_key(account: &impl AccountIdentityLike, _index: usize) -> String {
+    get_account_policy_key_from_parts(account.identity_account_id(), account.identity_email())
+}
+
+/// [`get_account_policy_key`] over raw identity parts (for callers holding
+/// live-pool accounts rather than storage rows).
+pub fn get_account_policy_key_from_parts(
+    account_id: Option<&str>,
+    email: Option<&str>,
+) -> String {
+    let account_id = account_id.map(str::trim).unwrap_or("");
+    let email_key;
+    let identity = if !account_id.is_empty() {
+        account_id
+    } else {
+        email_key = email.map(|e| e.trim().to_lowercase()).unwrap_or_default();
+        if email_key.is_empty() { "unknown" } else { &email_key }
+    };
+    let digest = Sha256::digest(identity.as_bytes());
+    let mut hex = String::with_capacity(7 + digest.len() * 2);
+    hex.push_str("sha256:");
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(hex, "{byte:02x}");
+    }
+    hex
+}
+
+/// TS `loadAccountPolicyStore()` — NEVER fails: missing file, unreadable
+/// file, malformed JSON, or a wrong-shape payload all yield an empty store
+/// (unreadable/malformed additionally warn).
+pub async fn load_account_policy_store() -> AccountPolicyStore {
+    let path = get_account_policy_path();
+    if !path.exists() {
+        return AccountPolicyStore::empty();
+    }
+    let parsed: Result<Value, String> = match read_file_with_retry(&path).await {
+        Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|error| error.to_string()),
+        Err(error) => Err(error.to_string()),
+    };
+    match parsed {
+        Ok(value) => normalize_store_value(&value),
+        Err(message) => {
+            let basename = path
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_default();
+            log_warn(
+                &format!("Failed to load account policies from {basename}: {message}"),
+                None,
+            );
+            AccountPolicyStore::empty()
+        }
+    }
+}
+
+/// TS `saveAccountPolicyStore(store)` — normalize, then queue an atomic
+/// temp+rename write (dir 0700, file 0600, 2-space pretty + trailing `\n`,
+/// rename retried ×5 on EBUSY/EPERM, temp unlinked on failure). The awaited
+/// task surfaces its own error; queue-level failures never poison later
+/// writes.
+pub async fn save_account_policy_store(store: &AccountPolicyStore) -> io::Result<()> {
+    let path = get_account_policy_path();
+    let payload = normalize_store_typed(store);
+    let content = stringify_pretty2(&payload);
+    let _queue = WRITE_QUEUE.lock().await;
+    write_json_atomic(
+        &path,
+        &content,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::Lf,
+            ensure_parent_dir: true,
+            parent_dir_mode: Some(0o700),
+            rename_max_attempts: 5,
+            ..Default::default()
+        },
+    )
+    .await
+}
+
+/// TS `upsertAccountPolicy(store, accountKey, mutate, now)` — clone the
+/// existing (or default) policy, apply `mutate`, then re-normalize ONLY
+/// `tags` + `weight` and stamp `updatedAt` (note/paused/drained are
+/// re-normalized at save/load, and `accountKey` stays whatever `mutate`
+/// left).
+pub fn upsert_account_policy(
+    store: &mut AccountPolicyStore,
+    account_key: &str,
+    mutate: impl FnOnce(&mut AccountPolicy),
+    now_ms: i64,
+) -> AccountPolicy {
+    let mut next = store
+        .get(account_key)
+        .cloned()
+        .unwrap_or_else(|| normalize_policy_value(account_key, None));
+    mutate(&mut next);
+    next.tags = normalize_tag_list(next.tags.iter().map(String::as_str));
+    next.weight = normalize_weight(Some(next.weight));
+    next.updated_at = now_ms as f64;
+    store.insert(account_key.to_string(), next.clone());
+    next
+}
+
+/// TS `normalizeAccountPolicyTag` — public alias of the tag normalizer.
+pub fn normalize_account_policy_tag(value: &str) -> Option<String> {
+    normalize_tag(value)
+}
+
+/// TS `resetAccountPolicyWriteQueueForTests()` — the tokio-Mutex queue has
+/// no failed-chain state to reset, so this is a parity no-op.
+pub fn reset_account_policy_write_queue_for_tests() {}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/account-policy.test.ts + golden byte round-trip)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    #[test]
+    fn normalize_tag_matches_ts_charset_rules() {
+        assert_eq!(normalize_tag("  Team A  "), Some("team-a".to_string()));
+        assert_eq!(normalize_tag("Fast!!Lane"), Some("fast-lane".to_string()));
+        assert_eq!(normalize_tag("a.b_c-d"), Some("a.b_c-d".to_string()));
+        assert_eq!(normalize_tag("   "), None);
+        assert_eq!(normalize_tag(""), None);
+        // Runs of invalid characters collapse to ONE dash.
+        assert_eq!(normalize_tag("x@# $y"), Some("x-y".to_string()));
+        // 64-unit cap.
+        let long = "a".repeat(100);
+        assert_eq!(normalize_tag(&long).unwrap().len(), 64);
+    }
+
+    #[test]
+    fn normalize_weight_clamps_and_defaults() {
+        assert_eq!(normalize_weight(Some(5.0)), 5.0);
+        assert_eq!(normalize_weight(Some(-3.0)), 0.0);
+        assert_eq!(normalize_weight(Some(11.5)), 10.0);
+        assert_eq!(normalize_weight(Some(f64::NAN)), 1.0);
+        assert_eq!(normalize_weight(Some(f64::INFINITY)), 1.0);
+        assert_eq!(normalize_weight(None), 1.0);
+        assert_eq!(normalize_weight(Some(0.5)), 0.5);
+    }
+
+    #[test]
+    fn policy_key_ignores_indexes_and_collapses_unidentified_accounts() {
+        // TS: "does not use mutable account indexes as policy identity".
+        let unidentified = cma_storage::identity::AccountIdentityRef::from_parts(None, None, None);
+        assert_eq!(
+            get_account_policy_key(&unidentified, 0),
+            get_account_policy_key(&unidentified, 4),
+        );
+        let a = get_account_policy_key_from_parts(None, None);
+        let b = get_account_policy_key_from_parts(Some("  "), Some(""));
+        assert_eq!(a, b);
+        assert_eq!(a, get_account_policy_key(&unidentified, 0));
+        assert!(a.starts_with("sha256:"));
+        assert_eq!(a.len(), "sha256:".len() + 64);
+        // accountId wins over email; email lowercased.
+        assert_eq!(
+            get_account_policy_key_from_parts(None, Some("  Owner@Example.COM ")),
+            get_account_policy_key_from_parts(None, Some("owner@example.com")),
+        );
+        assert_ne!(
+            get_account_policy_key_from_parts(Some("acct_1"), Some("owner@example.com")),
+            get_account_policy_key_from_parts(None, Some("owner@example.com")),
+        );
+    }
+
+    #[test]
+    fn normalize_store_value_drops_bad_versions_and_foreign_keys() {
+        let value: Value = serde_json::json!({
+            "version": 2,
+            "accounts": { "sha256:aa": { "weight": 3 } }
+        });
+        assert!(normalize_store_value(&value).is_empty());
+
+        let value: Value = serde_json::json!({
+            "version": 1,
+            "accounts": {
+                "sha256:aa": { "weight": 3, "tags": ["B", "a", "b"], "paused": 1 },
+                "plain-key": { "weight": 9 }
+            }
+        });
+        let store = normalize_store_value(&value);
+        assert_eq!(store.len(), 1);
+        let policy = store.get("sha256:aa").unwrap();
+        assert_eq!(policy.weight, 3.0);
+        assert_eq!(policy.tags, vec!["a", "b"]);
+        // paused must be literal true, not merely truthy.
+        assert!(!policy.paused);
+        assert_eq!(policy.note, None);
+        assert_eq!(policy.updated_at, 0.0);
+        assert_eq!(policy.account_key, "sha256:aa");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn stores_policy_rows_by_hashed_account_identity() {
+        let _sandbox = EnvSandbox::new();
+        let key =
+            get_account_policy_key_from_parts(Some("acct_sensitive"), Some("owner@example.com"));
+        let mut store = load_account_policy_store().await;
+        upsert_account_policy(
+            &mut store,
+            &key,
+            |policy| {
+                policy.tags.push("Team A".to_string());
+                policy.weight = 2.0;
+                policy.paused = true;
+                policy.note = Some("local note".to_string());
+            },
+            123,
+        );
+        save_account_policy_store(&store).await.unwrap();
+
+        let raw = std::fs::read_to_string(get_account_policy_path()).unwrap();
+        assert!(raw.contains("team-a"));
+        assert!(!raw.contains("acct_sensitive"));
+        assert!(!raw.contains("owner@example.com"));
+        assert!(raw.ends_with('\n'));
+
+        let loaded = load_account_policy_store().await;
+        let policy = loaded.get(&key).unwrap();
+        assert_eq!(policy.tags, vec!["team-a"]);
+        assert_eq!(policy.weight, 2.0);
+        assert!(policy.paused);
+        assert!(!policy.drained);
+        assert_eq!(policy.note.as_deref(), Some("local note"));
+        assert_eq!(policy.updated_at, 123.0);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn missing_file_loads_as_empty_store() {
+        let _sandbox = EnvSandbox::new();
+        assert!(load_account_policy_store().await.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn malformed_json_warns_and_loads_empty() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_account_policy_path(), "{oops").unwrap();
+        assert!(load_account_policy_store().await.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn golden_account_policies_round_trips_byte_exact() {
+        let sandbox = EnvSandbox::new();
+        let golden_path = concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../testkit/goldens/account-policies.json"
+        );
+        let golden = std::fs::read_to_string(golden_path).unwrap();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_account_policy_path(), &golden).unwrap();
+
+        let store = load_account_policy_store().await;
+        assert_eq!(store.len(), 2);
+        save_account_policy_store(&store).await.unwrap();
+
+        let rewritten = std::fs::read_to_string(get_account_policy_path()).unwrap();
+        assert_eq!(rewritten, golden, "canonical file must round-trip byte-exact");
+    }
+
+    #[test]
+    fn upsert_renormalizes_tags_and_weight_but_not_note() {
+        let mut store = AccountPolicyStore::empty();
+        let policy = upsert_account_policy(
+            &mut store,
+            "sha256:aa",
+            |p| {
+                p.tags = vec!["Zed!".into(), "alpha".into(), "alpha".into()];
+                p.weight = 42.0;
+                // note is NOT re-normalized inside upsert — only at save/load.
+                p.note = Some("   ".into());
+            },
+            777,
+        );
+        assert_eq!(policy.tags, vec!["alpha", "zed-"]);
+        assert_eq!(policy.weight, 10.0);
+        assert_eq!(policy.note.as_deref(), Some("   "));
+        assert_eq!(policy.updated_at, 777.0);
+        assert_eq!(store.get("sha256:aa"), Some(&policy));
+        // Save-path normalization then trims the note away.
+        let normalized = normalize_store_typed(&store);
+        assert_eq!(normalized.get("sha256:aa").unwrap().note, None);
+    }
+}
diff --git a/crates/accounts/src/capability_matrix.rs b/crates/accounts/src/capability_matrix.rs
new file mode 100644
index 000000000..518ab7d39
--- /dev/null
+++ b/crates/accounts/src/capability_matrix.rs
@@ -0,0 +1,623 @@
+//! Port of `lib/model-capability-matrix.ts` — pure, read-only builder of a
+//! diagnostic account × model availability matrix (spec 03 §6).
+//!
+//! Behavior contracts (spec 03 §6 + gotchas 19/21/22):
+//! - `account_index` is 1-BASED (display convention); `account_label` is
+//!   literally `"Account {index+1}"` with no email/label enrichment.
+//! - `account_key` comes from `crate::account_policy::get_account_policy_key`
+//!   (`"sha256:…"`); entitlement blocks are probed under BOTH the policy key
+//!   and the entitlement key, in that order (first live block wins).
+//! - quota-forecast-01 fix (deliberate): capability snapshots/boosts are read
+//!   under the ENTITLEMENT key, not the sha256 policy key — the write sites
+//!   (`record_unsupported` etc.) key by `resolve_entitlement_account_key`, so
+//!   the sha256 key would never match. Do not "simplify" back.
+//! - Reasons order: "account disabled" → "entitlement blocked: <reason>" →
+//!   "capability policy has unsupported failures" → "quota cache is
+//!   rate-limited". `available` = no reasons.
+//!
+//! Layering note: the TS imports `MODEL_PROFILES` / `resolveNormalizedModel`
+//! from `request/helpers/model-map.ts` (L3) and the quota-cache lookup from
+//! the quota cluster (L4) — both ABOVE this crate in the DAG. The Rust port
+//! therefore takes them as inputs: a [`ModelProfileProvider`] (implemented by
+//! `cma-request` over its profile tables) and a pre-resolved per-account
+//! quota entry slice (the caller runs `findQuotaCacheEntryForAccount`; the
+//! TS recomputed it per model but the result is model-independent).
+
+use cma_core::constants::ModelReasoningEffort;
+use cma_core::model_family::PromptModelFamily;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::account_policy::get_account_policy_key;
+use crate::capability_policy::{CapabilityPolicySnapshot, CapabilityPolicyStore};
+use crate::entitlement_cache::{
+    EntitlementAccountRef, EntitlementCacheSnapshot, resolve_entitlement_account_key,
+};
+
+/// TS `ModelCapabilities` from `model-map.ts`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModelCapabilitiesInfo {
+    #[serde(rename = "toolSearch")]
+    pub tool_search: bool,
+    #[serde(rename = "computerUse")]
+    pub computer_use: bool,
+    pub compaction: bool,
+}
+
+/// The slice of a `cma-request` model profile the matrix needs.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct MatrixModelProfile {
+    #[serde(rename = "normalizedModel")]
+    pub normalized_model: String,
+    #[serde(rename = "promptFamily")]
+    pub prompt_family: PromptModelFamily,
+    #[serde(rename = "defaultReasoningEffort")]
+    pub default_reasoning_effort: ModelReasoningEffort,
+    #[serde(rename = "supportedReasoningEfforts")]
+    pub supported_reasoning_efforts: Vec<ModelReasoningEffort>,
+    pub capabilities: ModelCapabilitiesInfo,
+}
+
+/// Model-profile catalog seam (production impl lives in
+/// `cma-request::model_map`; see the module docs).
+pub trait ModelProfileProvider {
+    /// `Object.keys(MODEL_PROFILES)` — the default model list, in table
+    /// order.
+    fn default_models(&self) -> Vec<String>;
+    /// TS `resolveNormalizedModel`.
+    fn resolve_normalized_model(&self, model: &str) -> String;
+    /// `MODEL_PROFILES[model]` — exact-key profile lookup.
+    fn profile(&self, model: &str) -> Option<MatrixModelProfile>;
+}
+
+/// TS `ModelCapabilityMatrixEntry`. Serializes with the exact TS field names;
+/// absent `entitlement_reason` / `capability_policy` / `quota` serialize as
+/// `null` (matching `JSON.stringify` of the TS object).
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct ModelCapabilityMatrixEntry {
+    /// 1-BASED (`index + 1`) — display convention (spec gotcha 21).
+    #[serde(rename = "accountIndex")]
+    pub account_index: usize,
+    /// Literally `"Account {index+1}"`.
+    #[serde(rename = "accountLabel")]
+    pub account_label: String,
+    /// `get_account_policy_key` output (`"sha256:…"`).
+    #[serde(rename = "accountKey")]
+    pub account_key: String,
+    /// Normalized model (list element).
+    pub model: String,
+    #[serde(rename = "normalizedModel")]
+    pub normalized_model: String,
+    #[serde(rename = "promptFamily")]
+    pub prompt_family: PromptModelFamily,
+    #[serde(rename = "defaultReasoningEffort")]
+    pub default_reasoning_effort: ModelReasoningEffort,
+    #[serde(rename = "supportedReasoningEfforts")]
+    pub supported_reasoning_efforts: Vec<ModelReasoningEffort>,
+    pub capabilities: ModelCapabilitiesInfo,
+    #[serde(rename = "entitlementBlocked")]
+    pub entitlement_blocked: bool,
+    #[serde(rename = "entitlementReason")]
+    pub entitlement_reason: Option<String>,
+    #[serde(rename = "entitlementWaitMs")]
+    pub entitlement_wait_ms: i64,
+    #[serde(rename = "capabilityPolicy")]
+    pub capability_policy: Option<CapabilityPolicySnapshot>,
+    #[serde(rename = "capabilityBoost", serialize_with = "serialize_js_number")]
+    pub capability_boost: f64,
+    /// Opaque quota-cache entry (`QuotaCacheEntry`-shaped JSON), passed
+    /// through untouched.
+    pub quota: Option<Value>,
+    /// `reasons.is_empty()`.
+    pub available: bool,
+    pub reasons: Vec<String>,
+}
+
+/// TS `ModelCapabilityMatrix`.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct ModelCapabilityMatrix {
+    #[serde(rename = "generatedAt")]
+    pub generated_at: i64,
+    pub models: Vec<String>,
+    pub entries: Vec<ModelCapabilityMatrixEntry>,
+}
+
+/// Inputs for [`build_model_capability_matrix`] (TS single input object).
+#[derive(Default)]
+pub struct ModelCapabilityMatrixInput<'a> {
+    pub storage: Option<&'a AccountStorageV3>,
+    /// Model list; `None`/empty falls back to the provider's default models.
+    pub models: Option<&'a [String]>,
+    pub entitlements: Option<&'a EntitlementCacheSnapshot>,
+    pub capability_policy: Option<&'a CapabilityPolicyStore>,
+    /// Pre-resolved quota-cache entry per STORAGE account position (the TS
+    /// called `findQuotaCacheEntryForAccount(quotaCache, account, accounts)`
+    /// inline; the result is model-independent, so the caller resolves it
+    /// once per account). `None` ⇔ the TS `quotaCache` being absent.
+    pub quota_by_account: Option<&'a [Option<Value>]>,
+    /// Epoch ms; `None` → `cma_core::utils::now_ms()`.
+    pub now: Option<i64>,
+}
+
+struct EntitlementBlockView {
+    blocked: bool,
+    wait_ms: i64,
+    reason: Option<String>,
+}
+
+/// TS `getEntitlementBlock` — for each key IN ORDER, find a block whose
+/// `model` matches; only a live one (`blockedUntil > now`) wins; an expired
+/// first match falls through to the NEXT KEY (not the next block).
+fn get_entitlement_block(
+    snapshot: Option<&EntitlementCacheSnapshot>,
+    account_keys: &[String],
+    normalized_model: &str,
+    now: i64,
+) -> EntitlementBlockView {
+    let not_blocked = EntitlementBlockView {
+        blocked: false,
+        wait_ms: 0,
+        reason: None,
+    };
+    let Some(snapshot) = snapshot else {
+        return not_blocked;
+    };
+    for account_key in account_keys {
+        let blocks = snapshot.get(account_key).unwrap_or(&[]);
+        let block = blocks.iter().find(|entry| entry.model == normalized_model);
+        let Some(block) = block else { continue };
+        if block.blocked_until <= now {
+            continue;
+        }
+        return EntitlementBlockView {
+            blocked: true,
+            wait_ms: (block.blocked_until - now).max(0),
+            reason: Some(block.reason.as_str().to_string()),
+        };
+    }
+    not_blocked
+}
+
+/// TS `buildModelCapabilityMatrix` — pure, read-only join over storage,
+/// entitlements, capability policy and quota cache.
+pub fn build_model_capability_matrix(
+    provider: &dyn ModelProfileProvider,
+    input: &ModelCapabilityMatrixInput<'_>,
+) -> ModelCapabilityMatrix {
+    let now = input.now.unwrap_or_else(cma_core::utils::now_ms);
+
+    let raw_models: Vec<String> = match input.models {
+        Some(models) if !models.is_empty() => models.to_vec(),
+        _ => provider.default_models(),
+    };
+    let mut models: Vec<String> = raw_models
+        .iter()
+        .map(|model| provider.resolve_normalized_model(model))
+        .collect();
+    // Dedup keeping first occurrence, then sort lexicographically (JS default
+    // sort; identical for the ASCII model-id space).
+    let mut seen = std::collections::HashSet::new();
+    models.retain(|model| seen.insert(model.clone()));
+    models.sort();
+
+    let empty: [cma_core::schemas::account_storage::AccountMetadataV3; 0] = [];
+    let accounts = input
+        .storage
+        .map(|storage| storage.accounts.as_slice())
+        .unwrap_or(&empty);
+
+    let mut entries: Vec<ModelCapabilityMatrixEntry> = Vec::new();
+    for (index, account) in accounts.iter().enumerate() {
+        let account_key = get_account_policy_key(account, index);
+        let entitlement_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: account.account_id.clone(),
+            email: account.email.clone(),
+            refresh_token: None,
+            index: Some(index as i64),
+        });
+        let entitlement_keys = [account_key.clone(), entitlement_key.clone()];
+
+        for model in &models {
+            let profile = provider
+                .profile(model)
+                .or_else(|| provider.profile(&provider.resolve_normalized_model(model)));
+            // Skip the entry entirely when no profile resolves.
+            let Some(profile) = profile else { continue };
+
+            let entitlement = get_entitlement_block(
+                input.entitlements,
+                &entitlement_keys,
+                &profile.normalized_model,
+                now,
+            );
+            // quota-forecast-01: read under the ENTITLEMENT key (see module
+            // docs) — the sha256 policy key would never match the write key.
+            let capability_policy = input
+                .capability_policy
+                .and_then(|store| store.get_snapshot(&entitlement_key, &profile.normalized_model));
+            let capability_boost = input
+                .capability_policy
+                .map(|store| store.get_boost(&entitlement_key, &profile.normalized_model, now))
+                .unwrap_or(0.0);
+            let quota = match (input.quota_by_account, input.storage) {
+                (Some(quota_by_account), Some(_)) => {
+                    quota_by_account.get(index).and_then(Clone::clone)
+                }
+                _ => None,
+            };
+
+            let mut reasons: Vec<String> = Vec::new();
+            if account.enabled == Some(false) {
+                reasons.push("account disabled".to_string());
+            }
+            if entitlement.blocked {
+                reasons.push(format!(
+                    "entitlement blocked: {}",
+                    entitlement.reason.as_deref().unwrap_or("unknown")
+                ));
+            }
+            if let Some(snapshot) = &capability_policy
+                && snapshot.unsupported > 0
+            {
+                reasons.push("capability policy has unsupported failures".to_string());
+            }
+            if quota
+                .as_ref()
+                .and_then(|entry| entry.get("status"))
+                .and_then(Value::as_i64)
+                == Some(429)
+            {
+                reasons.push("quota cache is rate-limited".to_string());
+            }
+
+            entries.push(ModelCapabilityMatrixEntry {
+                account_index: index + 1,
+                account_label: format!("Account {}", index + 1),
+                account_key: account_key.clone(),
+                model: model.clone(),
+                normalized_model: profile.normalized_model.clone(),
+                prompt_family: profile.prompt_family,
+                default_reasoning_effort: profile.default_reasoning_effort,
+                supported_reasoning_efforts: profile.supported_reasoning_efforts.clone(),
+                capabilities: profile.capabilities,
+                entitlement_blocked: entitlement.blocked,
+                entitlement_reason: entitlement.reason,
+                entitlement_wait_ms: entitlement.wait_ms,
+                capability_policy,
+                capability_boost,
+                quota,
+                available: reasons.is_empty(),
+                reasons,
+            });
+        }
+    }
+
+    ModelCapabilityMatrix {
+        generated_at: now,
+        models,
+        entries,
+    }
+}
+
+/// Serialize an f64 the way `JSON.stringify` prints a JS number: integral
+/// values emit without a fractional part (`3`, not `3.0`).
+fn serialize_js_number<S: serde::Serializer>(value: &f64, serializer: S) -> Result<S::Ok, S::Error> {
+    if value.fract() == 0.0 && value.abs() < 9_007_199_254_740_992.0 {
+        serializer.serialize_i64(*value as i64)
+    } else {
+        serializer.serialize_f64(*value)
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/model-capability-matrix.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::ModelFamily;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use serde_json::json;
+
+    /// Minimal stand-in for the `cma-request` profile tables covering the ids
+    /// the ported assertions exercise.
+    struct TestProvider;
+
+    fn profile(normalized: &str, family: ModelFamily) -> MatrixModelProfile {
+        MatrixModelProfile {
+            normalized_model: normalized.to_string(),
+            prompt_family: family,
+            default_reasoning_effort: ModelReasoningEffort::Medium,
+            supported_reasoning_efforts: vec![
+                ModelReasoningEffort::Low,
+                ModelReasoningEffort::Medium,
+                ModelReasoningEffort::High,
+            ],
+            capabilities: ModelCapabilitiesInfo {
+                tool_search: true,
+                computer_use: false,
+                compaction: true,
+            },
+        }
+    }
+
+    impl ModelProfileProvider for TestProvider {
+        fn default_models(&self) -> Vec<String> {
+            vec!["gpt-5.3-codex".to_string(), "gpt-5.5".to_string()]
+        }
+
+        fn resolve_normalized_model(&self, model: &str) -> String {
+            match model {
+                "gpt-5.3-codex" | "gpt-5-codex" | "codex" => "gpt-5.3-codex".to_string(),
+                "gpt-5.5" => "gpt-5.5".to_string(),
+                other => other.to_string(),
+            }
+        }
+
+        fn profile(&self, model: &str) -> Option<MatrixModelProfile> {
+            match model {
+                "gpt-5.3-codex" => Some(profile("gpt-5.3-codex", ModelFamily::Gpt5Codex)),
+                "gpt-5.5" => Some(profile("gpt-5.5", ModelFamily::Gpt5_2)),
+                _ => None,
+            }
+        }
+    }
+
+    fn storage() -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        let mut account = AccountMetadataV3::new("refresh", 1, 1);
+        account.email = Some("owner@example.com".to_string());
+        account.account_id = Some("acct_1".to_string());
+        storage.accounts = vec![account];
+        storage
+    }
+
+    fn entitlement_key() -> String {
+        resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: Some("acct_1".to_string()),
+            email: Some("owner@example.com".to_string()),
+            refresh_token: None,
+            index: Some(0),
+        })
+    }
+
+    #[test]
+    fn returns_default_normalized_models_without_entries_when_storage_is_missing() {
+        let models: [String; 0] = [];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: None,
+                models: Some(&models),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        assert_eq!(matrix.generated_at, 100);
+        assert!(!matrix.models.is_empty());
+        assert!(matrix.entries.is_empty());
+    }
+
+    #[test]
+    fn builds_model_account_availability_from_existing_model_profiles() {
+        let storage = storage();
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        assert_eq!(matrix.models, vec!["gpt-5.3-codex".to_string()]);
+        let entry = &matrix.entries[0];
+        assert_eq!(entry.account_index, 1);
+        assert_eq!(entry.account_label, "Account 1");
+        assert_eq!(entry.normalized_model, "gpt-5.3-codex");
+        assert_eq!(entry.prompt_family, ModelFamily::Gpt5Codex);
+        assert!(entry.available);
+        assert!(entry.account_key.starts_with("sha256:"));
+    }
+
+    #[test]
+    fn marks_capability_policy_and_quota_cache_issues_unavailable() {
+        let mut capability_policy = CapabilityPolicyStore::new();
+        capability_policy.record_unsupported(&entitlement_key(), "gpt-5.3-codex", 100);
+
+        let storage = storage();
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let quota = vec![Some(json!({
+            "updatedAt": 100,
+            "status": 429,
+            "model": "gpt-5.3-codex",
+            "primary": {},
+            "secondary": {},
+        }))];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                capability_policy: Some(&capability_policy),
+                quota_by_account: Some(&quota),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        let entry = &matrix.entries[0];
+        assert!(!entry.available);
+        assert!(
+            entry
+                .reasons
+                .contains(&"capability policy has unsupported failures".to_string())
+        );
+        assert!(entry.reasons.contains(&"quota cache is rate-limited".to_string()));
+    }
+
+    #[test]
+    fn surfaces_capability_snapshots_recorded_under_the_entitlement_key() {
+        // quota-forecast-01 regression: recordUnsupported writes under the
+        // entitlement key, so the matrix must read with that same key.
+        let mut capability_policy = CapabilityPolicyStore::new();
+        capability_policy.record_unsupported(&entitlement_key(), "gpt-5.3-codex", 100);
+
+        let storage = storage();
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                capability_policy: Some(&capability_policy),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        let entry = &matrix.entries[0];
+        let snapshot = entry.capability_policy.as_ref().expect("snapshot surfaces");
+        assert!(snapshot.unsupported > 0);
+        assert!(!entry.available);
+        assert!(
+            entry
+                .reasons
+                .contains(&"capability policy has unsupported failures".to_string())
+        );
+    }
+
+    #[test]
+    fn surfaces_a_negative_capability_boost_from_record_failure_under_the_entitlement_key() {
+        let mut capability_policy = CapabilityPolicyStore::new();
+        capability_policy.record_failure(&entitlement_key(), "gpt-5.3-codex", 100);
+
+        let storage = storage();
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                capability_policy: Some(&capability_policy),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        // failurePenalty = 3 (1 failure * 3), no successes → net boost -3.
+        assert!(matrix.entries[0].capability_boost < 0.0);
+    }
+
+    #[test]
+    fn record_success_under_the_entitlement_key_lifts_the_capability_boost_back_positive() {
+        let mut capability_policy = CapabilityPolicyStore::new();
+        capability_policy.record_failure(&entitlement_key(), "gpt-5.3-codex", 100);
+        capability_policy.record_success(&entitlement_key(), "gpt-5.3-codex", 100);
+
+        let storage = storage();
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                capability_policy: Some(&capability_policy),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        assert!(matrix.entries[0].capability_boost > 0.0);
+    }
+
+    #[test]
+    fn marks_disabled_and_entitlement_blocked_accounts_unavailable() {
+        let mut base_storage = storage();
+        base_storage.accounts[0].enabled = Some(false);
+
+        use crate::entitlement_cache::{EntitlementBlock, EntitlementBlockReason};
+        let entitlements = EntitlementCacheSnapshot::new(vec![(
+            entitlement_key(),
+            vec![EntitlementBlock {
+                model: "gpt-5.3-codex".to_string(),
+                blocked_until: 200,
+                reason: EntitlementBlockReason::PlanEntitlement,
+                updated_at: 100,
+            }],
+        )]);
+
+        let models = vec!["gpt-5.3-codex".to_string()];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&base_storage),
+                models: Some(&models),
+                entitlements: Some(&entitlements),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+
+        let entry = &matrix.entries[0];
+        assert!(!entry.available);
+        assert!(entry.entitlement_blocked);
+        assert_eq!(entry.entitlement_reason.as_deref(), Some("plan-entitlement"));
+        assert_eq!(entry.entitlement_wait_ms, 100);
+        assert!(entry.reasons.contains(&"account disabled".to_string()));
+        assert!(
+            entry
+                .reasons
+                .contains(&"entitlement blocked: plan-entitlement".to_string())
+        );
+    }
+
+    #[test]
+    fn dedups_and_sorts_the_model_list() {
+        let storage = storage();
+        let models = vec![
+            "gpt-5.5".to_string(),
+            "gpt-5-codex".to_string(),
+            "gpt-5.3-codex".to_string(),
+        ];
+        let matrix = build_model_capability_matrix(
+            &TestProvider,
+            &ModelCapabilityMatrixInput {
+                storage: Some(&storage),
+                models: Some(&models),
+                now: Some(100),
+                ..Default::default()
+            },
+        );
+        // gpt-5-codex and gpt-5.3-codex both resolve to gpt-5.3-codex →
+        // dedup; sorted ascending.
+        assert_eq!(
+            matrix.models,
+            vec!["gpt-5.3-codex".to_string(), "gpt-5.5".to_string()]
+        );
+        assert_eq!(matrix.entries.len(), 2);
+    }
+
+    #[test]
+    fn capability_boost_serializes_like_a_js_number() {
+        // Integral f64 must serialize without a fractional part.
+        #[derive(Serialize)]
+        struct Probe {
+            #[serde(serialize_with = "super::serialize_js_number")]
+            boost: f64,
+        }
+        assert_eq!(
+            serde_json::to_string(&Probe { boost: -3.0 }).unwrap(),
+            "{\"boost\":-3}"
+        );
+        assert_eq!(
+            serde_json::to_string(&Probe { boost: 2.5 }).unwrap(),
+            "{\"boost\":2.5}"
+        );
+    }
+}
diff --git a/crates/accounts/src/capability_policy.rs b/crates/accounts/src/capability_policy.rs
new file mode 100644
index 000000000..b4036adbb
--- /dev/null
+++ b/crates/accounts/src/capability_policy.rs
@@ -0,0 +1,528 @@
+//! Port of `lib/capability-policy.ts` — in-memory per-(account, model)
+//! capability score store with passive decay (spec 03 §4).
+//!
+//! In-memory ONLY; nothing is ever persisted. Feeds selection boosts.
+//!
+//! Behavior contracts (spec 03 §4 + gotchas 19/20/25):
+//! - LRU cap of 2048 entries; every record does the TS "delete-then-set" so
+//!   eviction order is least-recently-RECORDED, not FIFO.
+//! - Passive decay: failures/unsupported recover 0.5/min since `updated_at`
+//!   at boost-read time (read-only — decay is never written back).
+//! - Boost = clamp(min(12, successes*2) − min(18, recoveredFailures*3)
+//!   − min(24, recoveredUnsupported*6), −30, 20) as floats.
+//! - The account key used by callers is the ENTITLEMENT key
+//!   (`resolve_entitlement_account_key`), NOT the sha256 policy key
+//!   (quota-forecast-01 fix — keep write and read keys aligned).
+//! - Model normalization consults the alias catalog: exact
+//!   `getNormalizedModel` match first, then `resolveNormalizedModel` but ONLY
+//!   when the id looks like a GPT-5/codex model (`/gpt[-_\s]?5|codex/i`);
+//!   unknown non-GPT5/codex models pass through raw. One trailing reasoning
+//!   suffix (`-none|-minimal|-low|-medium|-high|-xhigh`) is stripped.
+//!
+//! Layering note: the alias catalog lives in `cma-request::model_map` (L3),
+//! which depends on this crate (L2). The catalog is therefore injected via
+//! the [`ModelCatalog`] trait — `cma-request` (or the runtime wiring) supplies
+//! the production implementation backed by `getNormalizedModel` /
+//! `resolveNormalizedModel`. A store built without a catalog degrades to raw
+//! pass-through bucketing (still internally consistent, but alias ids no
+//! longer share buckets) — production wiring MUST inject the catalog.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+
+/// TS `MAX_ENTRIES` — map-wide LRU cap.
+pub const MAX_ENTRIES: usize = 2048;
+/// TS `PASSIVE_RECOVERY_PER_MIN` — failure/unsupported decay per minute.
+pub const PASSIVE_RECOVERY_PER_MIN: f64 = 0.5;
+
+/// Model-alias catalog seam (production impl lives in
+/// `cma-request::model_map`; see the module docs).
+pub trait ModelCatalog: Send + Sync {
+    /// TS `getNormalizedModel` — exact alias-table lookup (`None` when
+    /// unknown).
+    fn get_normalized_model(&self, model: &str) -> Option<String>;
+    /// TS `resolveNormalizedModel` — full resolution incl. default-model
+    /// fallback.
+    fn resolve_normalized_model(&self, model: &str) -> String;
+}
+
+/// TS `CapabilityPolicySnapshot` — raw stored counts WITHOUT decay.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CapabilityPolicySnapshot {
+    pub successes: i64,
+    pub failures: i64,
+    pub unsupported: i64,
+    #[serde(
+        rename = "lastSuccessAt",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_success_at: Option<i64>,
+    #[serde(
+        rename = "lastFailureAt",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_failure_at: Option<i64>,
+}
+
+#[derive(Debug, Clone)]
+struct CapabilityEntry {
+    successes: i64,
+    failures: i64,
+    unsupported: i64,
+    last_success_at: Option<i64>,
+    last_failure_at: Option<i64>,
+    updated_at: i64,
+    /// Rust-only: recency counter reproducing the TS Map iteration order
+    /// under delete-then-set (smallest = least recently recorded).
+    seq: u64,
+}
+
+/// The TS regex gate `/gpt[-_\s]?5|codex/i` deciding whether an unknown id
+/// falls back to the alias catalog.
+fn matches_gpt5_or_codex(value: &str) -> bool {
+    let lower = value.to_lowercase();
+    if lower.contains("codex") {
+        return true;
+    }
+    let chars: Vec<char> = lower.chars().collect();
+    for start in 0..chars.len() {
+        if chars[start..].starts_with(&['g', 'p', 't']) {
+            let rest = &chars[start + 3..];
+            match rest.first() {
+                Some('5') => return true,
+                Some(c)
+                    if (*c == '-' || *c == '_' || c.is_whitespace())
+                        && rest.get(1) == Some(&'5') =>
+                {
+                    return true;
+                }
+                _ => {}
+            }
+        }
+    }
+    false
+}
+
+/// Strip exactly ONE trailing reasoning suffix from an already-lowercased id
+/// (TS `replace(/-(none|minimal|low|medium|high|xhigh)$/i, "")`).
+fn strip_one_reasoning_suffix(value: &str) -> String {
+    const SUFFIXES: [&str; 6] = ["-none", "-minimal", "-low", "-medium", "-high", "-xhigh"];
+    for suffix in SUFFIXES {
+        if let Some(stripped) = value.strip_suffix(suffix) {
+            return stripped.to_string();
+        }
+    }
+    value.to_string()
+}
+
+/// TS `normalizeModel` (capability-policy variant — spec gotcha 20: this one
+/// consults the alias catalog; the entitlement-cache variant does not).
+fn normalize_model(catalog: Option<&dyn ModelCatalog>, model: Option<&str>) -> Option<String> {
+    let trimmed_input = model?.trim();
+    if trimmed_input.is_empty() {
+        return None;
+    }
+    let without_provider = if trimmed_input.contains('/') {
+        trimmed_input.rsplit('/').next().unwrap_or(trimmed_input)
+    } else {
+        trimmed_input
+    };
+    let exact_match = catalog.and_then(|c| c.get_normalized_model(without_provider));
+    let should_use_fallback_catalog = matches_gpt5_or_codex(without_provider);
+    let mapped = match exact_match {
+        Some(mapped) => mapped,
+        None => match (should_use_fallback_catalog, catalog) {
+            (true, Some(c)) => c.resolve_normalized_model(without_provider),
+            _ => without_provider.to_string(),
+        },
+    };
+    let trimmed = mapped.trim().to_lowercase();
+    if trimmed.is_empty() {
+        return None;
+    }
+    Some(strip_one_reasoning_suffix(&trimmed))
+}
+
+/// TS `CapabilityPolicyStore`.
+#[derive(Default)]
+pub struct CapabilityPolicyStore {
+    entries: HashMap<String, CapabilityEntry>,
+    next_seq: u64,
+    catalog: Option<Arc<dyn ModelCatalog>>,
+}
+
+impl CapabilityPolicyStore {
+    /// Store without an alias catalog (raw pass-through bucketing — see the
+    /// module docs; production wiring should use [`Self::with_catalog`]).
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Store backed by the production alias catalog.
+    pub fn with_catalog(catalog: Arc<dyn ModelCatalog>) -> Self {
+        Self {
+            entries: HashMap::new(),
+            next_seq: 0,
+            catalog: Some(catalog),
+        }
+    }
+
+    /// TS `makeKey` — `"{accountKey}:{normalizedModel}"`, `None` when either
+    /// part is missing.
+    fn make_key(&self, account_key: &str, model: &str) -> Option<String> {
+        let normalized = normalize_model(self.catalog.as_deref(), Some(model))?;
+        if account_key.is_empty() {
+            return None;
+        }
+        Some(format!("{account_key}:{normalized}"))
+    }
+
+    fn record(
+        &mut self,
+        key: String,
+        now: i64,
+        build: impl FnOnce(Option<&CapabilityEntry>, i64) -> CapabilityEntry,
+    ) {
+        // Delete-then-set so the entry moves to the "end" (max seq), making
+        // eviction LRU (least-recently-recorded) rather than FIFO.
+        let existing = self.entries.remove(&key);
+        self.next_seq += 1;
+        let mut entry = build(existing.as_ref(), now);
+        entry.seq = self.next_seq;
+        self.entries.insert(key, entry);
+        self.evict_if_needed();
+    }
+
+    /// TS `recordSuccess` — `successes+1`, decrements failures/unsupported
+    /// (floored at 0), stamps `lastSuccessAt`/`updatedAt`.
+    pub fn record_success(&mut self, account_key: &str, model: &str, now: i64) {
+        let Some(key) = self.make_key(account_key, model) else {
+            return;
+        };
+        self.record(key, now, |existing, now| CapabilityEntry {
+            successes: existing.map_or(0, |e| e.successes) + 1,
+            failures: (existing.map_or(0, |e| e.failures) - 1).max(0),
+            unsupported: (existing.map_or(0, |e| e.unsupported) - 1).max(0),
+            last_success_at: Some(now),
+            last_failure_at: existing.and_then(|e| e.last_failure_at),
+            updated_at: now,
+            seq: 0,
+        });
+    }
+
+    /// TS `recordFailure` — `failures+1` only.
+    pub fn record_failure(&mut self, account_key: &str, model: &str, now: i64) {
+        let Some(key) = self.make_key(account_key, model) else {
+            return;
+        };
+        self.record(key, now, |existing, now| CapabilityEntry {
+            successes: existing.map_or(0, |e| e.successes),
+            failures: existing.map_or(0, |e| e.failures) + 1,
+            unsupported: existing.map_or(0, |e| e.unsupported),
+            last_success_at: existing.and_then(|e| e.last_success_at),
+            last_failure_at: Some(now),
+            updated_at: now,
+            seq: 0,
+        });
+    }
+
+    /// TS `recordUnsupported` — `failures+1` AND `unsupported+1`.
+    pub fn record_unsupported(&mut self, account_key: &str, model: &str, now: i64) {
+        let Some(key) = self.make_key(account_key, model) else {
+            return;
+        };
+        self.record(key, now, |existing, now| CapabilityEntry {
+            successes: existing.map_or(0, |e| e.successes),
+            failures: existing.map_or(0, |e| e.failures) + 1,
+            unsupported: existing.map_or(0, |e| e.unsupported) + 1,
+            last_success_at: existing.and_then(|e| e.last_success_at),
+            last_failure_at: Some(now),
+            updated_at: now,
+            seq: 0,
+        });
+    }
+
+    /// TS `getBoost` — decayed net score clamped to `[-30, 20]` (floats).
+    /// Read-only: the decay is never persisted back into the entry.
+    pub fn get_boost(&self, account_key: &str, model: &str, now: i64) -> f64 {
+        let Some(key) = self.make_key(account_key, model) else {
+            return 0.0;
+        };
+        let Some(entry) = self.entries.get(&key) else {
+            return 0.0;
+        };
+
+        let minutes_since_update = ((now - entry.updated_at) as f64 / 60_000.0).max(0.0);
+        let recovered_failures =
+            (entry.failures as f64 - minutes_since_update * PASSIVE_RECOVERY_PER_MIN).max(0.0);
+        let recovered_unsupported =
+            (entry.unsupported as f64 - minutes_since_update * PASSIVE_RECOVERY_PER_MIN).max(0.0);
+
+        let success_score = (entry.successes as f64 * 2.0).min(12.0);
+        let failure_penalty = (recovered_failures * 3.0).min(18.0);
+        let unsupported_penalty = (recovered_unsupported * 6.0).min(24.0);
+        let net = success_score - failure_penalty - unsupported_penalty;
+        net.clamp(-30.0, 20.0)
+    }
+
+    /// TS `getSnapshot` — raw stored counts WITHOUT decay.
+    pub fn get_snapshot(&self, account_key: &str, model: &str) -> Option<CapabilityPolicySnapshot> {
+        let key = self.make_key(account_key, model)?;
+        let entry = self.entries.get(&key)?;
+        Some(CapabilityPolicySnapshot {
+            successes: entry.successes,
+            failures: entry.failures,
+            unsupported: entry.unsupported,
+            last_success_at: entry.last_success_at,
+            last_failure_at: entry.last_failure_at,
+        })
+    }
+
+    /// TS `clearAccount` — deletes every entry whose key starts with
+    /// `"{accountKey}:"`; returns the removed count (0 for an empty key).
+    pub fn clear_account(&mut self, account_key: &str) -> usize {
+        if account_key.is_empty() {
+            return 0;
+        }
+        let prefix = format!("{account_key}:");
+        let before = self.entries.len();
+        self.entries.retain(|key, _| !key.starts_with(&prefix));
+        before - self.entries.len()
+    }
+
+    /// TS `evictIfNeeded` — evicts at most ONE entry per call, only when
+    /// `size > MAX_ENTRIES` (strictly greater): the least-recently-recorded
+    /// one (the TS Map's first-iterated key).
+    fn evict_if_needed(&mut self) {
+        if self.entries.len() <= MAX_ENTRIES {
+            return;
+        }
+        if let Some(oldest) = self
+            .entries
+            .iter()
+            .min_by_key(|(_, entry)| entry.seq)
+            .map(|(key, _)| key.clone())
+        {
+            self.entries.remove(&oldest);
+        }
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/capability-policy.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Minimal stand-in for the `cma-request` alias catalog covering the ids
+    /// exercised by the ported TS assertions (the real catalog resolves the
+    /// full alias/profile tables).
+    struct TestCatalog;
+
+    impl ModelCatalog for TestCatalog {
+        fn get_normalized_model(&self, model: &str) -> Option<String> {
+            match model.to_lowercase().as_str() {
+                // gpt-5-codex is an alias of the canonical gpt-5.3-codex id.
+                "gpt-5-codex" | "gpt-5.3-codex" => Some("gpt-5.3-codex".to_string()),
+                "gpt-5.5-pro" => Some("gpt-5.5-pro".to_string()),
+                _ => None,
+            }
+        }
+
+        fn resolve_normalized_model(&self, model: &str) -> String {
+            let lower = model.to_lowercase();
+            let stripped = strip_one_reasoning_suffix(&lower);
+            if let Some(exact) = self.get_normalized_model(&stripped) {
+                return exact;
+            }
+            // Dated release ids resolve to their base model.
+            if stripped.starts_with("gpt-5.5-pro-") {
+                return "gpt-5.5-pro".to_string();
+            }
+            // Unknown GPT-5 ids resolve to the default model.
+            "gpt-5.5".to_string()
+        }
+    }
+
+    fn catalog_store() -> CapabilityPolicyStore {
+        CapabilityPolicyStore::with_catalog(Arc::new(TestCatalog))
+    }
+
+    #[test]
+    fn rewards_repeated_successes() {
+        let mut store = catalog_store();
+        store.record_success("id:acc_1", "gpt-5-codex", 1_000);
+        store.record_success("id:acc_1", "gpt-5-codex", 2_000);
+
+        assert!(store.get_boost("id:acc_1", "gpt-5-codex", 2_500) > 0.0);
+    }
+
+    #[test]
+    fn penalizes_failures_and_unsupported_errors() {
+        let mut store = catalog_store();
+        store.record_failure("id:acc_1", "gpt-5.3-codex", 1_000);
+        store.record_unsupported("id:acc_1", "gpt-5.3-codex", 1_500);
+
+        let boost = store.get_boost("id:acc_1", "gpt-5.3-codex", 1_600);
+        assert!(boost < 0.0);
+    }
+
+    #[test]
+    fn recovers_passively_over_time() {
+        let mut store = catalog_store();
+        store.record_failure("id:acc_2", "gpt-5-codex", 1_000);
+        let early = store.get_boost("id:acc_2", "gpt-5-codex", 2_000);
+        let later = store.get_boost("id:acc_2", "gpt-5-codex", 122_000);
+
+        assert!(later >= early);
+    }
+
+    #[test]
+    fn clears_account_specific_entries() {
+        let mut store = catalog_store();
+        store.record_success("id:acc_a", "gpt-5-codex", 1_000);
+        store.record_failure("id:acc_b", "gpt-5-codex", 1_000);
+
+        assert!(store.clear_account("id:acc_a") > 0);
+        assert!(store.get_snapshot("id:acc_a", "gpt-5-codex").is_none());
+        assert!(store.get_snapshot("id:acc_b", "gpt-5-codex").is_some());
+    }
+
+    #[test]
+    fn uses_canonical_model_normalization_across_aliases() {
+        let mut store = catalog_store();
+        store.record_success("id:acc_alias", "gpt-5.3-codex", 1_000);
+        let boost_from_canonical = store.get_boost("id:acc_alias", "gpt-5-codex", 1_500);
+        assert!(boost_from_canonical > 0.0);
+    }
+
+    #[test]
+    fn shares_capability_buckets_between_aliases_and_dated_release_ids() {
+        let mut store = catalog_store();
+        store.record_unsupported("id:acc_future", "gpt-5.5-pro", 1_000);
+
+        let snapshot = store
+            .get_snapshot("id:acc_future", "gpt-5.5-pro-2026-04-23")
+            .expect("dated release id must share the base bucket");
+        assert_eq!(snapshot.failures, 1);
+        assert_eq!(snapshot.unsupported, 1);
+    }
+
+    #[test]
+    fn returns_zero_boost_null_snapshot_for_missing_or_invalid_keys() {
+        let store = catalog_store();
+        assert_eq!(store.get_boost("", "gpt-5-codex", 1_000), 0.0);
+        assert_eq!(store.get_boost("id:missing", "gpt-5-codex", 1_000), 0.0);
+        assert!(store.get_snapshot("", "gpt-5-codex").is_none());
+        assert!(store.get_snapshot("id:missing", "gpt-5-codex").is_none());
+    }
+
+    #[test]
+    fn normalizes_provider_prefixed_models_and_strips_quality_suffixes() {
+        let mut store = catalog_store();
+        store.record_success("id:acc_norm", "openai/gpt-5-codex-high", 1_000);
+
+        let snapshot = store.get_snapshot("id:acc_norm", "gpt-5-codex");
+        assert!(snapshot.is_some());
+        assert_eq!(snapshot.unwrap().successes, 1);
+    }
+
+    #[test]
+    fn keeps_unknown_model_identifiers_in_separate_capability_buckets() {
+        let mut store = catalog_store();
+        store.record_success("id:acc_unknown", "claude-3-sonnet-high", 1_000);
+
+        let snapshot = store
+            .get_snapshot("id:acc_unknown", "claude-3-sonnet")
+            .expect("non-GPT5/codex ids pass through raw");
+        assert_eq!(snapshot.successes, 1);
+        assert!(store.get_snapshot("id:acc_unknown", "gpt-5.4").is_none());
+    }
+
+    #[test]
+    fn ignores_blank_model_and_blank_account_writes() {
+        let mut store = catalog_store();
+        store.record_success("", "gpt-5-codex", 1_000);
+        store.record_failure("id:acc_blank", "   ", 1_000);
+        store.record_unsupported("", "   ", 1_000);
+
+        assert!(store.get_snapshot("id:acc_blank", "gpt-5-codex").is_none());
+        assert_eq!(store.clear_account(""), 0);
+    }
+
+    #[test]
+    fn evicts_oldest_entries_when_capacity_is_exceeded() {
+        let mut store = catalog_store();
+        for i in 0..2055 {
+            store.record_success(&format!("id:acc_{i}"), "gpt-5-codex", 1_000 + i);
+        }
+
+        assert!(store.get_snapshot("id:acc_0", "gpt-5-codex").is_none());
+        assert!(store.get_snapshot("id:acc_2054", "gpt-5-codex").is_some());
+    }
+
+    #[test]
+    fn lru_eviction_keeps_a_re_recorded_old_entry_over_an_idle_newer_one() {
+        let mut store = catalog_store();
+        // Fill exactly to capacity (MAX_ENTRIES = 2048): acc_0 is the oldest.
+        for i in 0..2048 {
+            store.record_success(&format!("id:acc_{i}"), "gpt-5-codex", 1_000 + i);
+        }
+        // Re-record the oldest entry: this must refresh its position so it is
+        // no longer first in iteration order (FIFO would still evict it next).
+        store.record_success("id:acc_0", "gpt-5-codex", 5_000);
+        // One more distinct insert pushes size over capacity and evicts.
+        store.record_success("id:acc_new", "gpt-5-codex", 6_000);
+
+        assert!(store.get_snapshot("id:acc_0", "gpt-5-codex").is_some());
+        assert!(store.get_snapshot("id:acc_1", "gpt-5-codex").is_none());
+        assert!(store.get_snapshot("id:acc_new", "gpt-5-codex").is_some());
+    }
+
+    #[test]
+    fn clamps_boost_to_score_boundaries() {
+        let mut store = catalog_store();
+        for i in 0..20 {
+            store.record_success("id:acc_hi", "gpt-5-codex", 1_000 + i);
+        }
+        for i in 0..20 {
+            store.record_unsupported("id:acc_lo", "gpt-5-codex", 1_000 + i);
+        }
+
+        assert!(store.get_boost("id:acc_hi", "gpt-5-codex", 2_000) <= 20.0);
+        assert!(store.get_boost("id:acc_lo", "gpt-5-codex", 2_000) >= -30.0);
+    }
+
+    #[test]
+    fn success_decrements_failures_and_unsupported_with_floor() {
+        let mut store = catalog_store();
+        store.record_unsupported("id:acc_heal", "gpt-5-codex", 1_000);
+        store.record_success("id:acc_heal", "gpt-5-codex", 2_000);
+        let snapshot = store.get_snapshot("id:acc_heal", "gpt-5-codex").unwrap();
+        assert_eq!(snapshot.successes, 1);
+        assert_eq!(snapshot.failures, 0);
+        assert_eq!(snapshot.unsupported, 0);
+        // Floors at 0 — a second success cannot go negative.
+        store.record_success("id:acc_heal", "gpt-5-codex", 3_000);
+        let snapshot = store.get_snapshot("id:acc_heal", "gpt-5-codex").unwrap();
+        assert_eq!(snapshot.failures, 0);
+        assert_eq!(snapshot.unsupported, 0);
+    }
+
+    #[test]
+    fn gpt5_regex_gate_matches_separator_variants() {
+        assert!(matches_gpt5_or_codex("gpt5-turbo"));
+        assert!(matches_gpt5_or_codex("gpt-5.2"));
+        assert!(matches_gpt5_or_codex("GPT_5"));
+        assert!(matches_gpt5_or_codex("gpt 5"));
+        assert!(matches_gpt5_or_codex("mycodex"));
+        assert!(!matches_gpt5_or_codex("gpt-4o"));
+        assert!(!matches_gpt5_or_codex("claude-3-sonnet"));
+    }
+}
diff --git a/crates/accounts/src/entitlement_cache.rs b/crates/accounts/src/entitlement_cache.rs
new file mode 100644
index 000000000..eb52e31bc
--- /dev/null
+++ b/crates/accounts/src/entitlement_cache.rs
@@ -0,0 +1,655 @@
+//! Port of `lib/entitlement-cache.ts` — in-memory TTL cache of "this account
+//! can't use this model" blocks (spec 03 §5).
+//!
+//! In-memory ONLY; nothing is ever persisted.
+//!
+//! Behavior contracts (spec 03 §5 + gotchas 20/26):
+//! - Default block TTL 30 min; caller-provided TTLs floor at 1 s.
+//! - At most 512 ACCOUNT buckets; eviction is FIFO of the first-inserted
+//!   bucket and only triggers for NEW keys at the cap.
+//! - Model normalization is the SIMPLE variant (no alias catalog): trim +
+//!   lowercase, last `/` segment, strip ONE trailing reasoning suffix.
+//! - `is_blocked` does lazy expiry (deletes the expired block and, when
+//!   emptied, its bucket).
+//! - `resolve_entitlement_account_key` never serializes refresh tokens.
+//!
+//! All time parameters are explicit epoch-ms values; production callers pass
+//! `cma_core::utils::now_ms()` where the TS defaulted to `Date.now()`.
+
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use cma_core::logger::{ScopedLogger, create_logger};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+
+static LOG: LazyLock<ScopedLogger> = LazyLock::new(|| create_logger("entitlement-cache"));
+
+/// TS `DEFAULT_BLOCK_TTL_MS` = 30 minutes.
+pub const DEFAULT_BLOCK_TTL_MS: i64 = 30 * 60_000;
+/// TS `MAX_ACCOUNT_BUCKETS` (accounts, not blocks).
+pub const MAX_ACCOUNT_BUCKETS: usize = 512;
+
+/// TS `EntitlementBlock["reason"]` union.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EntitlementBlockReason {
+    #[serde(rename = "unsupported-model")]
+    UnsupportedModel,
+    #[serde(rename = "plan-entitlement")]
+    PlanEntitlement,
+}
+
+impl EntitlementBlockReason {
+    /// The exact TS literal.
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            EntitlementBlockReason::UnsupportedModel => "unsupported-model",
+            EntitlementBlockReason::PlanEntitlement => "plan-entitlement",
+        }
+    }
+}
+
+impl std::fmt::Display for EntitlementBlockReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// TS `EntitlementBlock`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct EntitlementBlock {
+    pub model: String,
+    #[serde(rename = "blockedUntil")]
+    pub blocked_until: i64,
+    pub reason: EntitlementBlockReason,
+    #[serde(rename = "updatedAt")]
+    pub updated_at: i64,
+}
+
+/// TS `EntitlementCacheSnapshot` — `{accounts: Record<string, Block[]>}`.
+///
+/// Rust keeps the account buckets as an ordered `Vec` (bucket insertion
+/// order, matching the TS object key order) with a keyed [`Self::get`]
+/// accessor.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct EntitlementCacheSnapshot {
+    pub accounts: Vec<(String, Vec<EntitlementBlock>)>,
+}
+
+impl EntitlementCacheSnapshot {
+    /// Snapshot from pre-built buckets (test/matrix convenience).
+    pub fn new(accounts: Vec<(String, Vec<EntitlementBlock>)>) -> Self {
+        Self { accounts }
+    }
+
+    /// Blocks for `account_key` (the TS `snapshot.accounts[key]`).
+    pub fn get(&self, account_key: &str) -> Option<&[EntitlementBlock]> {
+        self.accounts
+            .iter()
+            .find(|(key, _)| key == account_key)
+            .map(|(_, blocks)| blocks.as_slice())
+    }
+
+    /// `true` when no account has any blocks.
+    pub fn is_empty(&self) -> bool {
+        self.accounts.is_empty()
+    }
+}
+
+/// TS `EntitlementAccountRef`. `refresh_token` exists on the ref but is
+/// deliberately never used in keys. `index: None` models the TS
+/// non-finite-index case.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct EntitlementAccountRef {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: Option<String>,
+    pub index: Option<i64>,
+}
+
+fn normalize_entitlement_email(email: Option<&str>) -> Option<String> {
+    let trimmed = email?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    Some(trimmed.to_lowercase())
+}
+
+/// TS `resolveEntitlementAccountKey` — deterministic account cache key.
+///
+/// Precedence: `account:<id>::email:<email>` → `email:<email>` →
+/// `account:<id>::idx:<n>` → `account:<id>` → `idx:<n>` (index defaults 0).
+/// Forms 1 and 2 intentionally coincide with `getRuntimeAccountIdentityKey`
+/// output for id+email / email-only accounts.
+pub fn resolve_entitlement_account_key(account_ref: &EntitlementAccountRef) -> String {
+    let account_id = account_ref
+        .account_id
+        .as_deref()
+        .map(str::trim)
+        .unwrap_or("");
+    let has_index = account_ref.index.is_some();
+    let index = account_ref.index.map(|value| value.max(0)).unwrap_or(0);
+    let email = normalize_entitlement_email(account_ref.email.as_deref());
+    match (account_id.is_empty(), email) {
+        (false, Some(email)) => format!("account:{account_id}::email:{email}"),
+        (true, Some(email)) => format!("email:{email}"),
+        (false, None) if has_index => format!("account:{account_id}::idx:{index}"),
+        (false, None) => format!("account:{account_id}"),
+        (true, None) => format!("idx:{index}"),
+    }
+}
+
+/// TS `normalizeModel` (entitlement variant — spec gotcha 20: SIMPLER than
+/// capability-policy's, with NO alias-catalog lookup): trim + lowercase, last
+/// `/` segment, strip ONE trailing `-(none|minimal|low|medium|high|xhigh)`.
+fn normalize_model(model: Option<&str>) -> Option<String> {
+    let trimmed = model?.trim().to_lowercase();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let stripped = if trimmed.contains('/') {
+        trimmed.rsplit('/').next().unwrap_or(&trimmed)
+    } else {
+        &trimmed
+    };
+    const SUFFIXES: [&str; 6] = ["-none", "-minimal", "-low", "-medium", "-high", "-xhigh"];
+    for suffix in SUFFIXES {
+        if let Some(base) = stripped.strip_suffix(suffix) {
+            return Some(base.to_string());
+        }
+    }
+    Some(stripped.to_string())
+}
+
+/// Result of [`EntitlementCache::is_blocked`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct EntitlementBlockStatus {
+    pub blocked: bool,
+    pub wait_ms: i64,
+    pub reason: Option<EntitlementBlockReason>,
+}
+
+impl EntitlementBlockStatus {
+    const NOT_BLOCKED: Self = Self {
+        blocked: false,
+        wait_ms: 0,
+        reason: None,
+    };
+}
+
+#[derive(Debug, Clone)]
+struct AccountBucket {
+    /// Bucket insertion order (FIFO eviction; assigned when the key is first
+    /// inserted, preserved on re-set — TS Map semantics).
+    seq: u64,
+    blocks: HashMap<String, EntitlementBlock>,
+}
+
+/// TS `EntitlementCache` (backing store
+/// `Map<accountKey, Map<normalizedModel, EntitlementBlock>>`).
+#[derive(Debug, Default)]
+pub struct EntitlementCache {
+    buckets: HashMap<String, AccountBucket>,
+    next_seq: u64,
+}
+
+impl EntitlementCache {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// TS `markBlocked`. No-op on a falsy key / un-normalizable model.
+    /// `ttl_ms: None` models the TS non-finite/omitted TTL → default 30 min;
+    /// `Some(v)` floors at 1 000 ms. Bucket eviction runs BEFORE insert: at
+    /// the 512 cap a NEW key evicts the first-inserted bucket.
+    pub fn mark_blocked(
+        &mut self,
+        account_key: &str,
+        model: &str,
+        reason: EntitlementBlockReason,
+        ttl_ms: Option<i64>,
+        now: i64,
+    ) {
+        let Some(normalized_model) = normalize_model(Some(model)) else {
+            return;
+        };
+        if account_key.is_empty() {
+            return;
+        }
+        let normalized_ttl_ms = match ttl_ms {
+            Some(value) => value.max(1_000),
+            None => DEFAULT_BLOCK_TTL_MS,
+        };
+        if self.buckets.len() >= MAX_ACCOUNT_BUCKETS
+            && !self.buckets.contains_key(account_key)
+            && let Some(first) = self
+                .buckets
+                .iter()
+                .min_by_key(|(_, bucket)| bucket.seq)
+                .map(|(key, _)| key.clone())
+        {
+            self.buckets.remove(&first);
+        }
+        if !self.buckets.contains_key(account_key) {
+            self.next_seq += 1;
+            self.buckets.insert(
+                account_key.to_string(),
+                AccountBucket {
+                    seq: self.next_seq,
+                    blocks: HashMap::new(),
+                },
+            );
+        }
+        let bucket = self
+            .buckets
+            .get_mut(account_key)
+            .expect("bucket inserted above");
+        bucket.blocks.insert(
+            normalized_model.clone(),
+            EntitlementBlock {
+                model: normalized_model,
+                blocked_until: now + normalized_ttl_ms,
+                reason,
+                updated_at: now,
+            },
+        );
+    }
+
+    /// TS `clear` — no model drops the whole bucket; with a model deletes the
+    /// normalized entry, dropping the bucket when emptied.
+    pub fn clear(&mut self, account_key: &str, model: Option<&str>) {
+        if account_key.is_empty() {
+            return;
+        }
+        let Some(model) = model else {
+            self.buckets.remove(account_key);
+            return;
+        };
+        let Some(normalized_model) = normalize_model(Some(model)) else {
+            return;
+        };
+        let Some(bucket) = self.buckets.get_mut(account_key) else {
+            return;
+        };
+        bucket.blocks.remove(&normalized_model);
+        if bucket.blocks.is_empty() {
+            self.buckets.remove(account_key);
+        }
+    }
+
+    /// TS `isBlocked` — lazy expiry (`blockedUntil <= now` deletes the entry
+    /// and an emptied bucket).
+    pub fn is_blocked(&mut self, account_key: &str, model: &str, now: i64) -> EntitlementBlockStatus {
+        let Some(normalized_model) = normalize_model(Some(model)) else {
+            return EntitlementBlockStatus::NOT_BLOCKED;
+        };
+        if account_key.is_empty() {
+            return EntitlementBlockStatus::NOT_BLOCKED;
+        }
+        let Some(bucket) = self.buckets.get_mut(account_key) else {
+            return EntitlementBlockStatus::NOT_BLOCKED;
+        };
+        let Some(block) = bucket.blocks.get(&normalized_model) else {
+            return EntitlementBlockStatus::NOT_BLOCKED;
+        };
+        if block.blocked_until <= now {
+            bucket.blocks.remove(&normalized_model);
+            if bucket.blocks.is_empty() {
+                self.buckets.remove(account_key);
+            }
+            return EntitlementBlockStatus::NOT_BLOCKED;
+        }
+        EntitlementBlockStatus {
+            blocked: true,
+            wait_ms: (block.blocked_until - now).max(0),
+            reason: Some(block.reason),
+        }
+    }
+
+    /// TS `prune` — removes all expired blocks + empty buckets; debug-logs
+    /// only when something was removed; returns the removed count.
+    pub fn prune(&mut self, now: i64) -> usize {
+        let mut removed = 0usize;
+        self.buckets.retain(|_, bucket| {
+            let before = bucket.blocks.len();
+            bucket.blocks.retain(|_, block| block.blocked_until > now);
+            removed += before - bucket.blocks.len();
+            !bucket.blocks.is_empty()
+        });
+        if removed > 0 {
+            LOG.debug("Pruned entitlement cache", Some(&json!({ "removed": removed })));
+        }
+        removed
+    }
+
+    /// TS `snapshot` — prunes first, then produces cloned block lists sorted
+    /// ascending by normalized model, buckets in insertion order.
+    pub fn snapshot(&mut self, now: i64) -> EntitlementCacheSnapshot {
+        self.prune(now);
+        let mut ordered: Vec<(&String, &AccountBucket)> = self.buckets.iter().collect();
+        ordered.sort_by_key(|(_, bucket)| bucket.seq);
+        let accounts = ordered
+            .into_iter()
+            .map(|(key, bucket)| {
+                let mut blocks: Vec<EntitlementBlock> = bucket.blocks.values().cloned().collect();
+                blocks.sort_by(|a, b| a.model.cmp(&b.model));
+                (key.clone(), blocks)
+            })
+            .collect();
+        EntitlementCacheSnapshot { accounts }
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/entitlement-cache.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn account_ref(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        index: Option<i64>,
+    ) -> EntitlementAccountRef {
+        EntitlementAccountRef {
+            account_id: account_id.map(str::to_string),
+            email: email.map(str::to_string),
+            refresh_token: None,
+            index,
+        }
+    }
+
+    #[test]
+    fn resolves_account_key_priority() {
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(
+                Some("acc_123"),
+                Some("user@example.com"),
+                Some(2)
+            )),
+            "account:acc_123::email:user@example.com"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(None, Some("User@Example.com"), Some(5))),
+            "email:user@example.com"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(None, None, Some(7))),
+            "idx:7"
+        );
+    }
+
+    #[test]
+    fn separates_shared_workspace_ids_by_email_or_index() {
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(
+                Some("shared-workspace"),
+                Some("alpha@example.com"),
+                Some(0)
+            )),
+            "account:shared-workspace::email:alpha@example.com"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(
+                Some("shared-workspace"),
+                Some("beta@example.com"),
+                Some(1)
+            )),
+            "account:shared-workspace::email:beta@example.com"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(Some("shared-workspace"), None, Some(0))),
+            "account:shared-workspace::idx:0"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(Some("shared-workspace"), None, Some(1))),
+            "account:shared-workspace::idx:1"
+        );
+    }
+
+    #[test]
+    fn marks_model_block_and_expires_after_ttl() {
+        let mut cache = EntitlementCache::new();
+        let account_key = "id:acc_1";
+        cache.mark_blocked(
+            account_key,
+            "gpt-5.3-codex",
+            EntitlementBlockReason::UnsupportedModel,
+            Some(500),
+            1_000,
+        );
+
+        let blocked_now = cache.is_blocked(account_key, "gpt-5.3-codex", 1_100);
+        assert!(blocked_now.blocked);
+        assert_eq!(
+            blocked_now.reason,
+            Some(EntitlementBlockReason::UnsupportedModel)
+        );
+        assert!(blocked_now.wait_ms > 0);
+
+        let blocked_later = cache.is_blocked(account_key, "gpt-5.3-codex", 2_200);
+        assert!(!blocked_later.blocked);
+        assert_eq!(blocked_later.wait_ms, 0);
+    }
+
+    #[test]
+    fn clears_model_or_full_account_block() {
+        let mut cache = EntitlementCache::new();
+        let account_key = "email:person@example.com";
+        cache.mark_blocked(
+            account_key,
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(5_000),
+            2_000,
+        );
+        cache.mark_blocked(
+            account_key,
+            "gpt-5.3-codex",
+            EntitlementBlockReason::UnsupportedModel,
+            Some(5_000),
+            2_000,
+        );
+
+        cache.clear(account_key, Some("gpt-5-codex"));
+        assert!(!cache.is_blocked(account_key, "gpt-5-codex", 2_500).blocked);
+        assert!(cache.is_blocked(account_key, "gpt-5.3-codex", 2_500).blocked);
+
+        cache.clear(account_key, None);
+        assert!(!cache.is_blocked(account_key, "gpt-5.3-codex", 2_500).blocked);
+    }
+
+    #[test]
+    fn normalizes_invalid_ttl_values_to_default_minimum_behavior() {
+        // The TS passed Number.NaN; the Rust port models non-finite as None.
+        let mut cache = EntitlementCache::new();
+        let account_key = "id:ttl-invalid";
+        cache.mark_blocked(
+            account_key,
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            None,
+            1_000,
+        );
+
+        let blocked = cache.is_blocked(account_key, "gpt-5-codex", 2_000);
+        assert!(blocked.blocked);
+        assert!(blocked.wait_ms > 0);
+    }
+
+    #[test]
+    fn snapshot_entries_are_clones() {
+        let mut cache = EntitlementCache::new();
+        let account_key = "id:snapshot";
+        cache.mark_blocked(
+            account_key,
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(5_000),
+            1_000,
+        );
+
+        let mut snapshot = cache.snapshot(1_500);
+        assert_eq!(snapshot.get(account_key).map(<[_]>::len), Some(1));
+        snapshot.accounts[0].1[0].model = "tampered-model".to_string();
+
+        let fresh = cache.snapshot(1_500);
+        assert_eq!(fresh.get(account_key).unwrap()[0].model, "gpt-5-codex");
+    }
+
+    #[test]
+    fn handles_trimmed_empty_account_refs_and_non_finite_indexes() {
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(Some("  acc_trim  "), None, None)),
+            "account:acc_trim"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(Some("  acc_trim  "), None, Some(3))),
+            "account:acc_trim::idx:3"
+        );
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(None, Some("  Person@Example.com  "), None)),
+            "email:person@example.com"
+        );
+        // Number.NaN index → non-finite → None.
+        assert_eq!(
+            resolve_entitlement_account_key(&account_ref(None, None, None)),
+            "idx:0"
+        );
+    }
+
+    #[test]
+    fn never_serializes_refresh_tokens_into_entitlement_keys() {
+        let mut with_index = account_ref(None, None, Some(4));
+        with_index.refresh_token = Some("  refresh-token  ".to_string());
+        assert_eq!(resolve_entitlement_account_key(&with_index), "idx:4");
+
+        let mut without_index = account_ref(None, None, None);
+        without_index.refresh_token = Some("  refresh-token  ".to_string());
+        assert_eq!(resolve_entitlement_account_key(&without_index), "idx:0");
+    }
+
+    #[test]
+    fn ignores_invalid_mark_clear_is_blocked_inputs() {
+        let mut cache = EntitlementCache::new();
+        cache.mark_blocked(
+            "",
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(5_000),
+            1_000,
+        );
+        cache.mark_blocked(
+            "id:bad-model",
+            "   ",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(5_000),
+            1_000,
+        );
+        cache.clear("", Some("gpt-5-codex"));
+        cache.clear("id:bad-model", Some("   "));
+
+        assert!(cache.snapshot(1_500).is_empty());
+        assert_eq!(
+            cache.is_blocked("", "gpt-5-codex", 1_500),
+            EntitlementBlockStatus::NOT_BLOCKED
+        );
+        assert_eq!(
+            cache.is_blocked("id:missing", "", 1_500),
+            EntitlementBlockStatus::NOT_BLOCKED
+        );
+    }
+
+    #[test]
+    fn evicts_the_oldest_account_bucket_when_max_buckets_are_exceeded() {
+        let mut cache = EntitlementCache::new();
+        for index in 0..513 {
+            cache.mark_blocked(
+                &format!("id:acc_{index}"),
+                "gpt-5-codex",
+                EntitlementBlockReason::PlanEntitlement,
+                Some(5_000),
+                1_000,
+            );
+        }
+
+        assert!(!cache.is_blocked("id:acc_0", "gpt-5-codex", 1_500).blocked);
+        assert!(cache.is_blocked("id:acc_1", "gpt-5-codex", 1_500).blocked);
+        assert!(cache.is_blocked("id:acc_512", "gpt-5-codex", 1_500).blocked);
+    }
+
+    #[test]
+    fn normalizes_model_names_with_provider_prefix_and_effort_suffix() {
+        let mut cache = EntitlementCache::new();
+        let account_key = "id:model-normalize";
+        cache.mark_blocked(
+            account_key,
+            "OpenAI/GPT-5-CODEX-HIGH",
+            EntitlementBlockReason::UnsupportedModel,
+            Some(5_000),
+            1_000,
+        );
+
+        assert!(cache.is_blocked(account_key, "gpt-5-codex", 1_500).blocked);
+        assert!(
+            cache
+                .is_blocked(account_key, "openai/gpt-5-codex-low", 1_500)
+                .blocked
+        );
+    }
+
+    #[test]
+    fn prunes_expired_blocks_and_removes_empty_account_buckets() {
+        let mut cache = EntitlementCache::new();
+        cache.mark_blocked(
+            "id:prune_a",
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(500),
+            1_000,
+        );
+        cache.mark_blocked(
+            "id:prune_b",
+            "gpt-5.3-codex",
+            EntitlementBlockReason::UnsupportedModel,
+            Some(500),
+            1_000,
+        );
+
+        // TTL floors at 1_000ms → blockedUntil = 2_000; expired at 2_000.
+        let removed = cache.prune(2_000);
+        assert_eq!(removed, 2);
+        assert!(cache.snapshot(2_000).is_empty());
+    }
+
+    #[test]
+    fn sorts_snapshot_blocks_alphabetically_by_normalized_model() {
+        let mut cache = EntitlementCache::new();
+        let account_key = "id:sort";
+        cache.mark_blocked(
+            account_key,
+            "gpt-5.3-codex",
+            EntitlementBlockReason::UnsupportedModel,
+            Some(5_000),
+            1_000,
+        );
+        cache.mark_blocked(
+            account_key,
+            "gpt-5-codex",
+            EntitlementBlockReason::PlanEntitlement,
+            Some(5_000),
+            1_000,
+        );
+
+        let snapshot = cache.snapshot(1_100);
+        let models: Vec<&str> = snapshot
+            .get(account_key)
+            .unwrap()
+            .iter()
+            .map(|entry| entry.model.as_str())
+            .collect();
+        assert_eq!(models, vec!["gpt-5-codex", "gpt-5.3-codex"]);
+    }
+}
diff --git a/crates/accounts/src/lib.rs b/crates/accounts/src/lib.rs
new file mode 100644
index 000000000..3d78691b4
--- /dev/null
+++ b/crates/accounts/src/lib.rs
@@ -0,0 +1,11 @@
+//! cma-accounts - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_policy;
+pub mod capability_matrix;
+pub mod capability_policy;
+pub mod entitlement_cache;
+pub mod manager;
+pub mod manager_persistence;
+pub mod manager_selection;
+pub mod rate_limits;
+pub mod routing_profiles;
+pub mod session_affinity;
diff --git a/crates/accounts/src/manager.rs b/crates/accounts/src/manager.rs
new file mode 100644
index 000000000..ce1c0d01e
--- /dev/null
+++ b/crates/accounts/src/manager.rs
@@ -0,0 +1,2743 @@
+//! Port of `lib/accounts.ts` — CORE STATE half of `AccountManager`:
+//! `ManagedAccount`, construction/hydration, account CRUD, tracker/circuit
+//! keys, removal bookkeeping, `updateFromAuth`, `commitRefreshedAuth`, and
+//! workspace rotation (#491).
+//!
+//! Behavior source: spec 03 §1 (+ gotchas). TS source is authoritative.
+//!
+//! File split within the crate (ARCHITECTURE §6.9): the selection half
+//! (round-robin / sequential / hybrid pickers, availability checks,
+//! min-wait) lives in `manager_selection.rs`; the
+//! persistence half (`build_storage_snapshot`, `reconcile_tokens_from_disk`,
+//! `save_to_disk*`, `mark_rate_limited_with_reason`, cooldown bookkeeping,
+//! formatters) lives in `manager_persistence.rs`. Both add `impl` blocks to
+//! the types defined HERE; struct fields are `pub(crate)` for that reason.
+//!
+//! Never-persist boundary (ARCHITECTURE §8.4): [`ManagedAccount`] wraps the
+//! serde [`AccountMetadataV3`] plus a NON-serde [`RuntimeAccountState`]
+//! (`lastRateLimitReason`, `consecutiveAuthFailures`, cached tracker/circuit
+//! keys). `ManagedAccount` itself derives NO `Serialize`; the persistence
+//! half's `build_storage_snapshot` is the only bridge to disk. For TS-shaped
+//! ergonomics `ManagedAccount` derefs to its `meta` (so `account.email`,
+//! `account.enabled`, `account.last_used` … resolve to the persisted-shape
+//! fields), and the always-present in-memory rate-limit map lives as a
+//! DIRECT field (`rate_limit_reset_times`) — its `meta` slot stays `None`
+//! in memory and is populated only by the snapshot builder.
+
+use std::collections::BTreeSet;
+use std::error::Error as StdError;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use serde_json::json;
+
+use cma_core::constants::ERROR_MESSAGES;
+use cma_core::errors::CodexError;
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::model_family::{MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::{
+    AccountIdSource, AccountMetadataV3, AccountStorageV3, RateLimitReason, RateLimitStateV3,
+    SwitchReason, Workspace,
+};
+use cma_core::token_utils::{
+    extract_account_email, extract_account_id, sanitize_email, should_update_account_id_from_token,
+};
+use cma_core::types::OAuthAuthDetails;
+use cma_core::utils::now_ms;
+
+use cma_cli_mirror::state::{CodexCliTokenCacheEntry, load_codex_cli_state};
+use cma_cli_mirror::sync::sync_account_storage_from_codex_cli;
+use cma_cli_mirror::writer::{ActiveSelection, set_codex_cli_active_selection};
+
+use cma_rotation::circuit_breaker::{remove_circuit_breaker, reset_all_circuit_breakers};
+use cma_rotation::routing_mutex::RoutingMutexMode;
+use cma_rotation::trackers::{TrackerKey, get_health_tracker, get_token_tracker, reset_trackers};
+
+use cma_storage::identity::{
+    AccountIdentityLike, RuntimeAccountIdentityKey, get_account_identity_key,
+    get_runtime_account_identity_key,
+};
+use cma_storage::load::load_accounts;
+use cma_storage::match_utils::AccountRecency;
+use cma_storage::matching::{AccountMatchOptions, find_matching_account_index};
+use cma_storage::path_state::{StoragePathState, get_storage_path_state};
+use cma_storage::save_retry::save_accounts_with_retry;
+use cma_storage::transactions::with_account_storage_transaction;
+
+use crate::rate_limits::{RateLimitedEntity, clamp_non_negative_int_i64};
+
+fn accounts_log() -> ScopedLogger {
+    create_logger("accounts")
+}
+
+/// TS module-global `nextRuntimeCircuitKeyId` (process-wide counter used for
+/// the `circuit:<n>` fallback when an account has no identity key).
+static NEXT_RUNTIME_CIRCUIT_KEY_ID: AtomicU64 = AtomicU64::new(0);
+
+// ============================================================================
+// ManagedAccount — AccountMetadataV3 + runtime-only (never-persisted) state
+// ============================================================================
+
+/// Runtime-only per-account state (spec 03 gotcha 2 / ARCHITECTURE §8.4).
+/// NEVER serialized: this struct has no `Serialize` impl, and the snapshot
+/// builder in `manager_persistence.rs` never reads these fields into the
+/// persisted shape.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RuntimeAccountState {
+    /// TS `lastRateLimitReason?: RateLimitReason` — runtime-only.
+    pub last_rate_limit_reason: Option<RateLimitReason>,
+    /// TS `consecutiveAuthFailures?: number` — runtime-only. `None` means
+    /// "never tracked"; `clearAuthFailures` sets `Some(0)` (NOT `None` —
+    /// the TS assign-0-vs-delete asymmetry, gotcha 13).
+    pub consecutive_auth_failures: Option<u32>,
+    /// TS `_runtimeTrackerKey?: string | number` — sticky cached tracker key
+    /// (see [`get_runtime_tracker_key`]).
+    pub runtime_tracker_key: Option<TrackerKey>,
+    /// TS `circuitKeyId?: string` — sticky cached circuit-breaker key.
+    pub circuit_key_id: Option<String>,
+}
+
+/// TS `interface ManagedAccount` — one account in the in-memory pool.
+///
+/// `meta` carries the persisted fields (TS `access`/`expires` map to
+/// `meta.access_token`/`meta.expires_at`) and is reachable directly via
+/// `Deref`, so `account.email` / `account.enabled` / `account.last_used`
+/// read (and, through `DerefMut`, write) the `meta` fields with TS-shaped
+/// syntax. In-memory invariants that differ from the disk shape:
+/// - `meta.enabled` is always `Some(true)`/`Some(false)` after construction
+///   (TS stores a literal boolean in memory; on disk it is `false`-or-omitted).
+/// - the ALWAYS-PRESENT in-memory rate-limit map is the direct
+///   [`Self::rate_limit_reset_times`] field (TS required field);
+///   `meta.rate_limit_reset_times` stays `None` in memory (dormant slot —
+///   only `build_storage_snapshot` writes the non-empty map into the
+///   persisted shape).
+#[derive(Clone, Debug, PartialEq)]
+pub struct ManagedAccount {
+    /// Position bookkeeping: set from the STORED array position at
+    /// construction (skipped blank-refresh rows leave gaps until the first
+    /// `remove_account*` reindex — spec 03 gotcha 14), rewritten to the array
+    /// position on every removal.
+    pub index: usize,
+    /// In-memory rate-limit windows (`{quotaKey: epochMs}`) — TS required
+    /// field. Shadows the dormant `meta.rate_limit_reset_times` slot.
+    pub rate_limit_reset_times: RateLimitStateV3,
+    /// The persisted account shape (serde struct from `cma-core`), exposed
+    /// through `Deref`/`DerefMut`.
+    pub meta: AccountMetadataV3,
+    /// Runtime-only state — never serialized.
+    pub runtime: RuntimeAccountState,
+}
+
+impl std::ops::Deref for ManagedAccount {
+    type Target = AccountMetadataV3;
+    fn deref(&self) -> &AccountMetadataV3 {
+        &self.meta
+    }
+}
+
+impl std::ops::DerefMut for ManagedAccount {
+    fn deref_mut(&mut self) -> &mut AccountMetadataV3 {
+        &mut self.meta
+    }
+}
+
+impl ManagedAccount {
+    /// TS convention `account.enabled !== false`.
+    pub fn is_enabled(&self) -> bool {
+        self.meta.enabled != Some(false)
+    }
+
+    /// TS `updateFromAuth(account, auth)` — adopt the refreshed token triple;
+    /// accountId only follows the token when
+    /// [`should_update_account_id_from_token`] allows (org/manual selections
+    /// stay stable); email keeps the old value when extraction fails.
+    pub fn update_from_auth(&mut self, auth: &OAuthAuthDetails) {
+        self.meta.refresh_token = auth.refresh.clone();
+        self.meta.access_token = Some(auth.access.clone());
+        self.meta.expires_at = Some(auth.expires);
+        let token_account_id = trim_to_non_empty(extract_account_id(Some(auth.access.as_str())));
+        if let Some(token_account_id) = token_account_id
+            && should_update_account_id_from_token(
+                self.meta.account_id_source.as_ref(),
+                self.meta.account_id.as_deref(),
+            )
+        {
+            self.meta.account_id = Some(token_account_id);
+            self.meta.account_id_source = Some(AccountIdSource::Token);
+        }
+        if let Some(email) =
+            sanitize_email(extract_account_email(Some(auth.access.as_str()), None).as_deref())
+        {
+            self.meta.email = Some(email);
+        }
+    }
+
+    // NOTE: `is_cooling_down` / `clear_cooldown` (TS `isAccountCoolingDown` /
+    // `clearAccountCooldown`) live in `manager_persistence.rs` (cooldown
+    // bookkeeping is the persistence half's row).
+
+    /// TS `incrementAuthFailures(account)` — returns the new count.
+    pub fn increment_auth_failures(&mut self) -> u32 {
+        let next = self.runtime.consecutive_auth_failures.unwrap_or(0) + 1;
+        self.runtime.consecutive_auth_failures = Some(next);
+        next
+    }
+
+    /// TS `clearAuthFailures(account)` — sets `0` (does NOT delete).
+    pub fn clear_auth_failures(&mut self) {
+        self.runtime.consecutive_auth_failures = Some(0);
+    }
+
+    // -- Workspace management (#491) -----------------------------------------
+
+    /// TS private `resetWorkspaces` — re-enable every workspace and point the
+    /// cursor at the default workspace (or index 0 when none is flagged).
+    pub(crate) fn reset_workspaces(&mut self) {
+        let Some(workspaces) = self.meta.workspaces.as_mut() else {
+            return;
+        };
+        if workspaces.is_empty() {
+            return;
+        }
+        let reset_index = workspaces
+            .iter()
+            .position(|workspace| workspace.is_default == Some(true));
+        for workspace in workspaces.iter_mut() {
+            workspace.enabled = true;
+            workspace.disabled_at = None;
+        }
+        self.meta.current_workspace_index = Some(reset_index.unwrap_or(0) as i64);
+    }
+
+    /// TS `getCurrentWorkspace(account)` — `workspaces[currentWorkspaceIndex
+    /// ?? 0] ?? null`; `None` when no workspaces are tracked.
+    pub fn get_current_workspace(&self) -> Option<&Workspace> {
+        let workspaces = self.meta.workspaces.as_ref()?;
+        if workspaces.is_empty() {
+            return None;
+        }
+        let idx = self.meta.current_workspace_index.unwrap_or(0);
+        usize::try_from(idx).ok().and_then(|idx| workspaces.get(idx))
+    }
+
+    /// TS `disableCurrentWorkspace(account, expectedWorkspaceId?)` — CAS
+    /// guard on the workspace id; false when already disabled (gotcha 28).
+    pub fn disable_current_workspace(&mut self, expected_workspace_id: Option<&str>) -> bool {
+        let Some(workspaces) = self.meta.workspaces.as_mut() else {
+            return false;
+        };
+        if workspaces.is_empty() {
+            return false;
+        }
+        let idx = self.meta.current_workspace_index.unwrap_or(0);
+        let Ok(idx) = usize::try_from(idx) else {
+            return false;
+        };
+        if idx >= workspaces.len() {
+            return false;
+        }
+        let Some(workspace) = workspaces.get_mut(idx) else {
+            return false;
+        };
+        if let Some(expected) = expected_workspace_id
+            && workspace.id != expected
+        {
+            return false;
+        }
+        if !workspace.enabled {
+            return false;
+        }
+        workspace.enabled = false;
+        workspace.disabled_at = Some(now_ms());
+        true
+    }
+
+    /// TS `rotateToNextWorkspace(account)` — scans SUCCESSORS only (the
+    /// current slot is never re-selected, gotcha 28); first enabled successor
+    /// becomes current and is returned.
+    pub fn rotate_to_next_workspace(&mut self) -> Option<&Workspace> {
+        let total = self.meta.workspaces.as_ref().map_or(0, Vec::len) as i64;
+        if total == 0 {
+            return None;
+        }
+        let current_idx = self.meta.current_workspace_index.unwrap_or(0);
+        for i in 1..total {
+            // JS `%` keeps sign; a negative currentWorkspaceIndex simply
+            // never resolves to a workspace (same skip behavior as TS).
+            let next_idx = (current_idx + i) % total;
+            let Ok(next) = usize::try_from(next_idx) else {
+                continue;
+            };
+            let enabled = self
+                .meta
+                .workspaces
+                .as_ref()
+                .and_then(|workspaces| workspaces.get(next))
+                .is_some_and(|workspace| workspace.enabled);
+            if enabled {
+                self.meta.current_workspace_index = Some(next_idx);
+                return self
+                    .meta
+                    .workspaces
+                    .as_ref()
+                    .and_then(|workspaces| workspaces.get(next));
+            }
+        }
+        None
+    }
+
+    /// TS `hasEnabledWorkspaces(account)` — TRUE for accounts with NO
+    /// tracked workspaces (legacy implicit single workspace, gotcha 27).
+    pub fn has_enabled_workspaces(&self) -> bool {
+        match self.meta.workspaces.as_ref() {
+            None => true,
+            Some(workspaces) if workspaces.is_empty() => true,
+            Some(workspaces) => workspaces.iter().any(|workspace| workspace.enabled),
+        }
+    }
+
+    /// TS `getWorkspaceCount(account)`.
+    pub fn get_workspace_count(&self) -> usize {
+        self.meta.workspaces.as_ref().map_or(0, Vec::len)
+    }
+
+    /// TS `getEnabledWorkspaceCount(account)` — 0 when no `workspaces` field
+    /// (asymmetric with [`Self::has_enabled_workspaces`], gotcha 27).
+    pub fn get_enabled_workspace_count(&self) -> usize {
+        self.meta.workspaces.as_ref().map_or(0, |workspaces| {
+            workspaces
+                .iter()
+                .filter(|workspace| workspace.enabled)
+                .count()
+        })
+    }
+}
+
+impl AccountIdentityLike for ManagedAccount {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.meta.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.meta.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.meta.refresh_token.as_str())
+    }
+}
+
+impl AccountRecency for ManagedAccount {
+    fn recency_last_used(&self) -> i64 {
+        self.meta.last_used
+    }
+    fn recency_added_at(&self) -> i64 {
+        self.meta.added_at
+    }
+}
+
+impl RateLimitedEntity for ManagedAccount {
+    fn rate_limit_reset_times(&self) -> &RateLimitStateV3 {
+        &self.rate_limit_reset_times
+    }
+    fn rate_limit_reset_times_mut(&mut self) -> &mut RateLimitStateV3 {
+        &mut self.rate_limit_reset_times
+    }
+}
+
+// ============================================================================
+// Tracker / circuit keys
+// ============================================================================
+
+/// TS exported `getRuntimeTrackerKey(account)` — sticky cache on
+/// `_runtimeTrackerKey`: `getRuntimeAccountIdentityKey(account) ??
+/// account.index`. Once cached the key deliberately does NOT change when the
+/// account later gains accountId/email (`updateFromAuth` enrichment) — only
+/// `remove_account*` invalidates NUMERIC cached keys (gotcha 5).
+pub fn get_runtime_tracker_key(account: &mut ManagedAccount) -> TrackerKey {
+    if let Some(key) = account.runtime.runtime_tracker_key.as_ref() {
+        return key.clone();
+    }
+    let key = match get_runtime_account_identity_key(
+        account.meta.account_id.as_deref(),
+        account.meta.email.as_deref(),
+        Some(account.index as i64),
+    ) {
+        Some(RuntimeAccountIdentityKey::Key(key)) => TrackerKey::Text(key),
+        Some(RuntimeAccountIdentityKey::Index(index)) => TrackerKey::Number(index),
+        None => TrackerKey::Number(account.index as i64),
+    };
+    account.runtime.runtime_tracker_key = Some(key.clone());
+    key
+}
+
+/// TS private `getAccountCircuitKey(account)` — sticky cache on
+/// `circuitKeyId`: `getAccountIdentityKey(account) ?? "circuit:<n++>"`.
+/// (An empty cached string is falsy in TS and recomputed.)
+pub(crate) fn get_account_circuit_key(account: &mut ManagedAccount) -> String {
+    if let Some(key) = account.runtime.circuit_key_id.as_ref()
+        && !key.is_empty()
+    {
+        return key.clone();
+    }
+    let key = get_account_identity_key(account).unwrap_or_else(|| {
+        format!(
+            "circuit:{}",
+            NEXT_RUNTIME_CIRCUIT_KEY_ID.fetch_add(1, Ordering::Relaxed)
+        )
+    });
+    account.runtime.circuit_key_id = Some(key.clone());
+    key
+}
+
+// ============================================================================
+// Identity candidates
+// ============================================================================
+
+/// TS `AccountIdentityCandidate` — the `{accountId?, email?, refreshToken,
+/// index?}` shape passed to identity lookups (`getAccountByIdentity`,
+/// `commitRefreshedAuth` source).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AccountIdentityCandidate {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: Option<String>,
+    pub index: Option<i64>,
+}
+
+impl AccountIdentityLike for AccountIdentityCandidate {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        self.refresh_token.as_deref()
+    }
+}
+
+/// TS `getAuthIdentityCandidate(auth)`.
+fn get_auth_identity_candidate(auth: Option<&OAuthAuthDetails>) -> AccountIdentityCandidate {
+    let access = auth.map(|auth| auth.access.as_str());
+    AccountIdentityCandidate {
+        account_id: trim_to_non_empty(extract_account_id(access)),
+        email: sanitize_email(extract_account_email(access, None).as_deref()),
+        refresh_token: auth.map(|auth| auth.refresh.clone()),
+        index: None,
+    }
+}
+
+/// TS `buildAccountIdentityCandidates(source, auth?)` — up to 4 deduped
+/// candidates in this EXACT order (dedup key `"{id}|{email}|{refresh}"`).
+fn build_account_identity_candidates(
+    source: &AccountIdentityCandidate,
+    auth: Option<&OAuthAuthDetails>,
+) -> Vec<AccountIdentityCandidate> {
+    let derived = get_auth_identity_candidate(auth);
+    let mut candidates: Vec<AccountIdentityCandidate> = Vec::new();
+    let mut seen: BTreeSet<String> = BTreeSet::new();
+
+    let mut push_candidate = |candidate: AccountIdentityCandidate| {
+        let key = format!(
+            "{}|{}|{}",
+            candidate.account_id.as_deref().unwrap_or(""),
+            candidate.email.as_deref().unwrap_or(""),
+            candidate.refresh_token.as_deref().unwrap_or("")
+        );
+        if seen.insert(key) {
+            candidates.push(candidate);
+        }
+    };
+
+    push_candidate(source.clone());
+    push_candidate(AccountIdentityCandidate {
+        account_id: source.account_id.clone().or_else(|| derived.account_id.clone()),
+        email: source.email.clone().or_else(|| derived.email.clone()),
+        refresh_token: source.refresh_token.clone(),
+        index: source.index,
+    });
+    push_candidate(AccountIdentityCandidate {
+        account_id: derived.account_id.clone().or_else(|| source.account_id.clone()),
+        email: derived.email.clone().or_else(|| source.email.clone()),
+        refresh_token: source.refresh_token.clone(),
+        index: source.index,
+    });
+    push_candidate(AccountIdentityCandidate {
+        account_id: derived.account_id.clone().or_else(|| source.account_id.clone()),
+        email: derived.email.clone().or_else(|| source.email.clone()),
+        refresh_token: derived
+            .refresh_token
+            .clone()
+            .or_else(|| source.refresh_token.clone()),
+        index: source.index,
+    });
+
+    candidates
+}
+
+/// TS `findAccountIndexByIdentity(accounts, source, auth?)` — first candidate
+/// (in order) that `findMatchingAccountIndex` resolves wins; always uses
+/// `allowUniqueAccountIdFallbackWithoutEmail: true`.
+pub(crate) fn find_account_index_by_identity<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    source: &AccountIdentityCandidate,
+    auth: Option<&OAuthAuthDetails>,
+) -> Option<usize> {
+    for candidate in build_account_identity_candidates(source, auth) {
+        let match_index = find_matching_account_index(
+            accounts,
+            &candidate,
+            AccountMatchOptions {
+                allow_unique_account_id_fallback_without_email: true,
+            },
+        );
+        if match_index.is_some() {
+            return match_index;
+        }
+    }
+    None
+}
+
+/// TS `isRetryableAuthPersistenceError(error)` — code ∈ {EAGAIN, EBUSY,
+/// EPERM} (uppercased), HTTP status 429, or the same recursively on the
+/// cause chain.
+pub(crate) fn is_retryable_auth_persistence_error(error: &(dyn StdError + 'static)) -> bool {
+    let mut current: Option<&(dyn StdError + 'static)> = Some(error);
+    // Depth cap stands in for the TS `cause !== error` self-reference guard.
+    let mut depth = 0;
+    while let Some(err) = current {
+        if depth > 32 {
+            return false;
+        }
+        if let Some(codex) = err.downcast_ref::<CodexError>() {
+            let code = codex.code().to_uppercase();
+            if matches!(code.as_str(), "EAGAIN" | "EBUSY" | "EPERM") {
+                return true;
+            }
+            if codex.status() == Some(429) {
+                return true;
+            }
+        }
+        if let Some(io_error) = err.downcast_ref::<std::io::Error>()
+            && let Some(code) = cma_core::fs_retry::code_of(io_error)
+            && matches!(code, "EAGAIN" | "EBUSY" | "EPERM")
+        {
+            return true;
+        }
+        current = err.source();
+        depth += 1;
+    }
+    false
+}
+
+/// `extractAccountId(...)?.trim() || undefined`.
+fn trim_to_non_empty(value: Option<String>) -> Option<String> {
+    let trimmed = value?.trim().to_string();
+    if trimmed.is_empty() { None } else { Some(trimmed) }
+}
+
+// ============================================================================
+// Per-family state map
+// ============================================================================
+
+/// TS `initFamilyState(defaultValue)` — `Record<ModelFamily, number>` with an
+/// entry for every model family (always fully populated, so `get` returns a
+/// plain `i64`). (Debounced-save state is NOT declared on the manager: the
+/// persistence half implements the TS debounce surface on its
+/// `SharedAccountManager` wrapper.)
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct FamilyStateMap {
+    values: [i64; 5],
+}
+
+impl FamilyStateMap {
+    pub fn new(default_value: i64) -> Self {
+        Self {
+            values: [default_value; 5],
+        }
+    }
+
+    const fn slot(family: ModelFamily) -> usize {
+        match family {
+            ModelFamily::Gpt5Codex => 0,
+            ModelFamily::CodexMax => 1,
+            ModelFamily::Codex => 2,
+            ModelFamily::Gpt5_2 => 3,
+            ModelFamily::Gpt5_1 => 4,
+        }
+    }
+
+    pub fn get(&self, family: ModelFamily) -> i64 {
+        self.values[Self::slot(family)]
+    }
+
+    pub fn set(&mut self, family: ModelFamily, value: i64) {
+        self.values[Self::slot(family)] = value;
+    }
+}
+
+// ============================================================================
+// AccountManager
+// ============================================================================
+
+/// Internal identity-row shape used for fallback matching in the constructor
+/// (TS `storedIdentityRows`; recency fields are absent in TS ⇒ 0 here).
+struct StoredIdentityRow {
+    index: usize,
+    account_id: Option<String>,
+    email: Option<String>,
+    refresh_token: String,
+}
+
+impl AccountIdentityLike for StoredIdentityRow {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.refresh_token.as_str())
+    }
+}
+
+impl AccountRecency for StoredIdentityRow {
+    fn recency_last_used(&self) -> i64 {
+        0
+    }
+    fn recency_added_at(&self) -> i64 {
+        0
+    }
+}
+
+/// TS `class AccountManager` — the in-memory account pool.
+///
+/// Fields are `pub(crate)` so the selection/persistence halves (sibling
+/// modules of this crate) can add `impl` blocks; outside the crate only the
+/// methods are visible.
+pub struct AccountManager {
+    pub(crate) accounts: Vec<ManagedAccount>,
+    /// Round-robin scan start per family (init 0; always fully populated).
+    pub(crate) cursor_by_family: FamilyStateMap,
+    /// Active pointer per family (init -1; always fully populated).
+    pub(crate) current_account_index_by_family: FamilyStateMap,
+    pub(crate) last_toast_account_index: i64,
+    pub(crate) last_toast_time: i64,
+    /// Shallow copy of the ambient storage-path state captured at
+    /// construction; `save_to_disk` re-enters it so a project-scoped manager
+    /// keeps writing to its project-scoped file (spec 03 §14).
+    pub(crate) storage_path_state: StoragePathState,
+    /// Manual pin (#474) — hydrated from disk; NO mutators on the pool.
+    pub(crate) pinned_account_index: Option<i64>,
+    /// Affinity generation (#474) — same hydration path; 0 when absent.
+    pub(crate) affinity_generation: i64,
+    /// PR-N / R4 routing-mutex mode (default `legacy`).
+    pub(crate) routing_mutex_mode: RoutingMutexMode,
+}
+
+impl AccountManager {
+    /// TS `constructor(authFallback?, stored?)`.
+    pub fn new(
+        auth_fallback: Option<&OAuthAuthDetails>,
+        stored: Option<&AccountStorageV3>,
+    ) -> Self {
+        let storage_path_state = get_storage_path_state();
+        let fallback_account_id = trim_to_non_empty(extract_account_id(
+            auth_fallback.map(|auth| auth.access.as_str()),
+        ));
+        let fallback_account_email = sanitize_email(
+            extract_account_email(auth_fallback.map(|auth| auth.access.as_str()), None).as_deref(),
+        );
+
+        // Hydrate pin/gen from the stored snapshot (validation beyond the
+        // schema's non-negative-int guarantees: range check for the pin).
+        let affinity_generation = stored
+            .and_then(|stored| stored.affinity_generation)
+            .filter(|generation| *generation >= 0)
+            .unwrap_or(0);
+        let account_count = stored.map_or(0, |stored| stored.accounts.len());
+        let pinned_account_index = stored
+            .and_then(|stored| stored.pinned_account_index)
+            .filter(|pin| *pin >= 0 && (*pin as usize) < account_count);
+
+        let mut manager = AccountManager {
+            accounts: Vec::new(),
+            cursor_by_family: FamilyStateMap::new(0),
+            current_account_index_by_family: FamilyStateMap::new(-1),
+            last_toast_account_index: -1,
+            last_toast_time: 0,
+            storage_path_state,
+            pinned_account_index,
+            affinity_generation,
+            routing_mutex_mode: RoutingMutexMode::Legacy,
+        };
+
+        if let Some(stored) = stored
+            && !stored.accounts.is_empty()
+        {
+            let stored_identity_rows: Vec<StoredIdentityRow> = stored
+                .accounts
+                .iter()
+                .enumerate()
+                .filter(|(_, account)| !account.refresh_token.trim().is_empty())
+                .map(|(index, account)| StoredIdentityRow {
+                    index,
+                    account_id: account.account_id.clone(),
+                    email: account.email.clone(),
+                    refresh_token: account.refresh_token.clone(),
+                })
+                .collect();
+
+            let fallback_matched_row_index: Option<usize> = match auth_fallback {
+                Some(auth) if !stored_identity_rows.is_empty() => find_matching_account_index(
+                    &stored_identity_rows,
+                    &AccountIdentityCandidate {
+                        account_id: fallback_account_id.clone(),
+                        email: fallback_account_email.clone(),
+                        refresh_token: Some(auth.refresh.clone()),
+                        index: None,
+                    },
+                    AccountMatchOptions {
+                        allow_unique_account_id_fallback_without_email: true,
+                    },
+                )
+                .map(|row| stored_identity_rows[row].index),
+                _ => None,
+            };
+
+            let base_now = now_ms();
+            for (index, account) in stored.accounts.iter().enumerate() {
+                if account.refresh_token.trim().is_empty() {
+                    // Skipped rows keep their ORIGINAL stored positions in the
+                    // surviving accounts' `index` fields (gotcha 14).
+                    continue;
+                }
+                let matches_fallback =
+                    auth_fallback.is_some() && fallback_matched_row_index == Some(index);
+                let meta = AccountMetadataV3 {
+                    account_id: if matches_fallback {
+                        fallback_account_id
+                            .clone()
+                            .or_else(|| account.account_id.clone())
+                    } else {
+                        account.account_id.clone()
+                    },
+                    account_id_source: account.account_id_source,
+                    account_label: account.account_label.clone(),
+                    email: if matches_fallback {
+                        fallback_account_email
+                            .clone()
+                            .or_else(|| sanitize_email(account.email.as_deref()))
+                    } else {
+                        sanitize_email(account.email.as_deref())
+                    },
+                    refresh_token: match (matches_fallback, auth_fallback) {
+                        (true, Some(auth)) => auth.refresh.clone(),
+                        _ => account.refresh_token.clone(),
+                    },
+                    access_token: match (matches_fallback, auth_fallback) {
+                        (true, Some(auth)) => Some(auth.access.clone()),
+                        _ => account.access_token.clone(),
+                    },
+                    expires_at: match (matches_fallback, auth_fallback) {
+                        (true, Some(auth)) => Some(auth.expires),
+                        _ => account.expires_at,
+                    },
+                    enabled: Some(account.is_enabled()),
+                    added_at: clamp_non_negative_int_i64(Some(account.added_at), base_now),
+                    last_used: clamp_non_negative_int_i64(Some(account.last_used), 0),
+                    last_switch_reason: account.last_switch_reason,
+                    // Dormant in memory — the live map is the DIRECT field.
+                    rate_limit_reset_times: None,
+                    cooling_down_until: account.cooling_down_until,
+                    cooldown_reason: account.cooldown_reason,
+                    workspaces: account.workspaces.clone(),
+                    current_workspace_index: account.current_workspace_index,
+                };
+                manager.accounts.push(ManagedAccount {
+                    index,
+                    rate_limit_reset_times: account
+                        .rate_limit_reset_times
+                        .clone()
+                        .unwrap_or_default(),
+                    meta,
+                    runtime: RuntimeAccountState::default(),
+                });
+            }
+
+            let has_matching_fallback =
+                auth_fallback.is_some() && fallback_matched_row_index.is_some();
+
+            if let Some(auth) = auth_fallback
+                && !has_matching_fallback
+            {
+                let now = now_ms();
+                let index = manager.accounts.len();
+                let mut meta = AccountMetadataV3::new(auth.refresh.clone(), now, now);
+                meta.account_id = fallback_account_id.clone();
+                meta.account_id_source = fallback_account_id
+                    .is_some()
+                    .then_some(AccountIdSource::Token);
+                meta.email = fallback_account_email.clone();
+                meta.enabled = Some(true);
+                meta.access_token = Some(auth.access.clone());
+                meta.expires_at = Some(auth.expires);
+                meta.last_switch_reason = Some(SwitchReason::Initial);
+                manager.accounts.push(ManagedAccount {
+                    index,
+                    rate_limit_reset_times: RateLimitStateV3::new(),
+                    meta,
+                    runtime: RuntimeAccountState::default(),
+                });
+            }
+
+            if !manager.accounts.is_empty() {
+                let len = manager.accounts.len() as i64;
+                let default_index = clamp_non_negative_int_i64(Some(stored.active_index), 0) % len;
+                for family in MODEL_FAMILIES {
+                    let raw = stored
+                        .active_index_by_family
+                        .as_ref()
+                        .and_then(|map| map.get(family));
+                    let next_index = clamp_non_negative_int_i64(raw, default_index) % len;
+                    manager
+                        .current_account_index_by_family
+                        .set(family, next_index);
+                    manager.cursor_by_family.set(family, next_index);
+                }
+            }
+            return manager;
+        }
+
+        if let Some(auth) = auth_fallback {
+            let now = now_ms();
+            let mut meta = AccountMetadataV3::new(auth.refresh.clone(), now, 0);
+            meta.account_id = fallback_account_id.clone();
+            meta.account_id_source = fallback_account_id
+                .is_some()
+                .then_some(AccountIdSource::Token);
+            meta.email = fallback_account_email;
+            meta.enabled = Some(true);
+            meta.access_token = Some(auth.access.clone());
+            meta.expires_at = Some(auth.expires);
+            meta.last_switch_reason = Some(SwitchReason::Initial);
+            manager.accounts.push(ManagedAccount {
+                index: 0,
+                rate_limit_reset_times: RateLimitStateV3::new(),
+                meta,
+                runtime: RuntimeAccountState::default(),
+            });
+            for family in MODEL_FAMILIES {
+                manager.current_account_index_by_family.set(family, 0);
+                manager.cursor_by_family.set(family, 0);
+            }
+        }
+
+        manager
+    }
+
+    /// TS `static loadFromDisk(authFallback?)` — load storage, run the Codex
+    /// CLI reconcile, best-effort persist a changed source-of-truth, build
+    /// the pool, then hydrate token gaps from the CLI cache.
+    pub async fn load_from_disk(auth_fallback: Option<&OAuthAuthDetails>) -> AccountManager {
+        let stored = load_accounts().await.map(|loaded| loaded.storage);
+        let synced = sync_account_storage_from_codex_cli(stored.as_ref()).await;
+        let changed = synced.changed;
+        let source_of_truth = synced.storage.or(stored);
+        if changed
+            && let Some(storage) = source_of_truth.as_ref()
+            && let Err(error) = save_accounts_with_retry(storage).await
+        {
+            accounts_log().debug(
+                "Failed to persist Codex CLI source-of-truth sync",
+                Some(&json!({ "error": error.to_string() })),
+            );
+        }
+
+        let mut manager = AccountManager::new(auth_fallback, source_of_truth.as_ref());
+        manager.hydrate_from_codex_cli().await;
+        manager
+    }
+
+    /// TS `hasRefreshToken(refreshToken)` — exact string equality.
+    pub fn has_refresh_token(&self, refresh_token: &str) -> bool {
+        self.accounts
+            .iter()
+            .any(|account| account.meta.refresh_token == refresh_token)
+    }
+
+    /// TS private `hydrateFromCodexCli()` — merge the official Codex CLI
+    /// token cache into accounts whose access token is missing or expired.
+    /// Never overwrites a live token; best-effort persists on change.
+    async fn hydrate_from_codex_cli(&mut self) {
+        let Some(state) = load_codex_cli_state(false).await else {
+            return;
+        };
+        if state.accounts.is_empty() {
+            return;
+        }
+
+        let mut cache: Vec<(String, CodexCliTokenCacheEntry)> = Vec::new();
+        for snapshot in &state.accounts {
+            let Some(email) = sanitize_email(snapshot.email.as_deref()) else {
+                continue;
+            };
+            if snapshot.access_token.is_empty() {
+                continue;
+            }
+            let entry = CodexCliTokenCacheEntry {
+                access_token: snapshot.access_token.clone(),
+                expires_at: snapshot.expires_at,
+                refresh_token: snapshot.refresh_token.clone(),
+                account_id: snapshot.account_id.clone(),
+            };
+            // JS Map#set semantics: last write for a duplicate email wins.
+            if let Some(existing) = cache.iter_mut().find(|(key, _)| *key == email) {
+                existing.1 = entry;
+            } else {
+                cache.push((email, entry));
+            }
+        }
+        if cache.is_empty() {
+            return;
+        }
+
+        let now = now_ms();
+        let mut changed = false;
+
+        for account in &mut self.accounts {
+            let Some(email) = sanitize_email(account.meta.email.as_deref()) else {
+                continue;
+            };
+            let Some((_, cached)) = cache.iter().find(|(key, _)| *key == email) else {
+                continue;
+            };
+
+            if let Some(expires_at) = cached.expires_at
+                && expires_at <= now as f64
+            {
+                continue;
+            }
+
+            let missing_or_expired = account
+                .meta
+                .access_token
+                .as_deref()
+                .is_none_or(str::is_empty)
+                || account.meta.expires_at.is_none_or(|expires| expires <= now);
+            if missing_or_expired {
+                account.meta.access_token = Some(cached.access_token.clone());
+                if let Some(expires_at) = cached.expires_at {
+                    account.meta.expires_at = Some(expires_at as i64);
+                }
+                changed = true;
+            }
+
+            if account.meta.account_id.as_deref().is_none_or(str::is_empty)
+                && cached.account_id.as_deref().is_some_and(|id| !id.is_empty())
+                && should_update_account_id_from_token(
+                    account.meta.account_id_source.as_ref(),
+                    account.meta.account_id.as_deref(),
+                )
+            {
+                account.meta.account_id = cached.account_id.clone();
+                account.meta.account_id_source =
+                    Some(account.meta.account_id_source.unwrap_or(AccountIdSource::Token));
+                changed = true;
+            }
+        }
+
+        if !changed {
+            return;
+        }
+
+        if let Err(error) = self.save_to_disk().await {
+            accounts_log().debug(
+                "Failed to persist Codex CLI cache hydration",
+                Some(&json!({ "error": error.to_string() })),
+            );
+        }
+    }
+
+    /// TS `getAccountCount()`.
+    pub fn get_account_count(&self) -> usize {
+        self.accounts.len()
+    }
+
+    /// TS `getActiveIndex()` = `getActiveIndexForFamily("codex")`.
+    pub fn get_active_index(&self) -> i64 {
+        self.get_active_index_for_family(ModelFamily::Codex)
+    }
+
+    /// TS `getActiveIndexForFamily(family)` — ROUTABLE index contract
+    /// (AUDIT-H10 / oracle F1): `-1` on empty pool; out-of-range pointer
+    /// clamps to 0; disabled slots are walked past; `-1` when every account
+    /// is disabled.
+    pub fn get_active_index_for_family(&self, family: ModelFamily) -> i64 {
+        if self.accounts.is_empty() {
+            return -1;
+        }
+        let index = self.current_account_index_by_family.get(family);
+        let len = self.accounts.len() as i64;
+        let clamped = if index < 0 || index >= len { 0 } else { index };
+        if self.accounts[clamped as usize].is_enabled() {
+            return clamped;
+        }
+        for step in 1..len {
+            let candidate = (clamped + step) % len;
+            if self.accounts[candidate as usize].is_enabled() {
+                return candidate;
+            }
+        }
+        -1
+    }
+
+    /// TS `getAccountsSnapshot()` — WRITE side effect: force-materializes
+    /// `_runtimeTrackerKey` / `circuitKeyId` on the LIVE accounts (gotcha 33)
+    /// before cloning. The Rust clone is a full deep copy (the TS snapshot
+    /// shared the nested `workspaces` array; Rust cannot share without `Rc`,
+    /// so mutations of a snapshot's workspaces do not reach the live pool).
+    pub fn get_accounts_snapshot(&mut self) -> Vec<ManagedAccount> {
+        for account in &mut self.accounts {
+            let _ = get_runtime_tracker_key(account);
+            let _ = get_account_circuit_key(account);
+        }
+        self.accounts.clone()
+    }
+
+    /// TS `getAccountByIndex(index)` — `None` for out-of-range (NaN maps to
+    /// the typed `i64` domain).
+    pub fn get_account_by_index(&self, index: i64) -> Option<&ManagedAccount> {
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return None;
+        }
+        self.accounts.get(index as usize)
+    }
+
+    /// Mutable sibling of [`Self::get_account_by_index`] — the TS API handed
+    /// out live object references; Rust callers mutate through this instead.
+    pub fn get_account_by_index_mut(&mut self, index: i64) -> Option<&mut ManagedAccount> {
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return None;
+        }
+        self.accounts.get_mut(index as usize)
+    }
+
+    /// TS `static resetVolatileRuntimeState()` — clears the process-global
+    /// rotation trackers and circuit breakers ONLY (per-account transient
+    /// state is `clear_account_transient_state`, persistence half / #606).
+    pub fn reset_volatile_runtime_state() {
+        reset_trackers();
+        reset_all_circuit_breakers();
+    }
+
+    /// TS `setActiveIndex(index)` — mutates ALL families' active pointer AND
+    /// cursor to `index` (cursor = index here, NOT index+1 — gotcha 9),
+    /// stamps `lastUsed`/`lastSwitchReason="rotation"`, fire-and-forgets the
+    /// Codex CLI active-selection mirror write, returns the account.
+    pub fn set_active_index(&mut self, index: i64) -> Option<&ManagedAccount> {
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return None;
+        }
+        let idx = index as usize;
+        if !self.accounts[idx].is_enabled() {
+            return None;
+        }
+
+        for family in MODEL_FAMILIES {
+            self.current_account_index_by_family.set(family, index);
+            self.cursor_by_family.set(family, index);
+        }
+
+        let account = &mut self.accounts[idx];
+        account.meta.last_used = now_ms();
+        account.meta.last_switch_reason = Some(SwitchReason::Rotation);
+
+        // TS: `void this.syncCodexCliActiveSelectionForIndex(account.index)`.
+        // Fire-and-forget over captured data; outside a tokio runtime the
+        // advisory mirror write is skipped (best-effort in TS too).
+        let selection = ActiveSelection {
+            account_id: account.meta.account_id.clone(),
+            email: account.meta.email.clone(),
+            access_token: account.meta.access_token.clone(),
+            refresh_token: Some(account.meta.refresh_token.clone()),
+            expires_at: account.meta.expires_at.map(|expires| expires as f64),
+            id_token: None,
+        };
+        if let Ok(handle) = tokio::runtime::Handle::try_current() {
+            handle.spawn(async move {
+                let _ = set_codex_cli_active_selection(&selection).await;
+            });
+        }
+
+        self.accounts.get(idx)
+    }
+
+    /// TS `getCurrentAccount()` = `getCurrentAccountForFamily("codex")`.
+    pub fn get_current_account(&self) -> Option<&ManagedAccount> {
+        self.get_current_account_for_family(ModelFamily::Codex)
+    }
+
+    /// TS `getCurrentAccountForFamily(family)` — `None` when the pointer is
+    /// out of range or the slot is disabled. NO availability checks (rate
+    /// limit / cooldown / circuit are deliberately not consulted).
+    pub fn get_current_account_for_family(&self, family: ModelFamily) -> Option<&ManagedAccount> {
+        let index = self.current_account_index_by_family.get(family);
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return None;
+        }
+        let account = &self.accounts[index as usize];
+        if !account.is_enabled() {
+            return None;
+        }
+        Some(account)
+    }
+
+    /// TS `setRoutingMutexMode(mode)` (PR-N / R4).
+    pub fn set_routing_mutex_mode(&mut self, mode: RoutingMutexMode) {
+        self.routing_mutex_mode = mode;
+    }
+
+    /// TS `getRoutingMutexMode()`.
+    pub fn get_routing_mutex_mode(&self) -> RoutingMutexMode {
+        self.routing_mutex_mode
+    }
+
+    /// TS `getAccountByIdentity(candidate, auth?)` — index-returning form
+    /// (the TS method returned the live object reference).
+    pub fn get_account_index_by_identity(
+        &self,
+        candidate: &AccountIdentityCandidate,
+        auth: Option<&OAuthAuthDetails>,
+    ) -> Option<usize> {
+        find_account_index_by_identity(&self.accounts, candidate, auth)
+    }
+
+    /// TS `getAccountByIdentity(candidate, auth?)`.
+    pub fn get_account_by_identity(
+        &self,
+        candidate: &AccountIdentityCandidate,
+        auth: Option<&OAuthAuthDetails>,
+    ) -> Option<&ManagedAccount> {
+        let index = self.get_account_index_by_identity(candidate, auth)?;
+        self.accounts.get(index)
+    }
+
+    /// TS `shouldShowAccountToast(accountIndex, debounceMs = 30000)` — only
+    /// the SAME index within the window is debounced; a different index
+    /// always toasts (gotcha 30).
+    pub fn should_show_account_toast(&self, account_index: i64, debounce_ms: Option<i64>) -> bool {
+        let debounce_ms = debounce_ms.unwrap_or(30_000);
+        let now = now_ms();
+        !(account_index == self.last_toast_account_index
+            && now - self.last_toast_time < debounce_ms)
+    }
+
+    /// TS `markToastShown(accountIndex)`.
+    pub fn mark_toast_shown(&mut self, account_index: i64) {
+        self.last_toast_account_index = account_index;
+        self.last_toast_time = now_ms();
+    }
+
+    /// TS `commitRefreshedAuth(source, auth)` — persist a refreshed token
+    /// triple transactionally and mirror it onto the live account.
+    ///
+    /// Returns the LIVE account index (the TS method returned the account
+    /// object) — `Ok(None)` when no matching account resolves (the stored
+    /// row, when found, is still persisted in that case). Every escaping
+    /// error is wrapped as `CodexAuthError` with the FROZEN message
+    /// `"Failed to refresh token, authentication required"` and `retryable`
+    /// derived from EAGAIN/EBUSY/EPERM/429 across the cause chain.
+    pub async fn commit_refreshed_auth(
+        &mut self,
+        source: &AccountIdentityCandidate,
+        auth: &OAuthAuthDetails,
+    ) -> Result<Option<usize>, CodexError> {
+        let next_account_id = trim_to_non_empty(extract_account_id(Some(auth.access.as_str())));
+        let next_email =
+            sanitize_email(extract_account_email(Some(auth.access.as_str()), None).as_deref());
+
+        let this = &mut *self;
+        let result = with_account_storage_transaction(move |_current, persist| async move {
+            // Snapshot the live in-memory pool under the storage lock so
+            // refresh persistence merges against the latest account state
+            // (TS `structuredClone(this.buildStorageSnapshot())`).
+            let mut next_storage: AccountStorageV3 = this.build_storage_snapshot();
+            let storage_index =
+                find_account_index_by_identity(&next_storage.accounts, source, Some(auth));
+            let Some(storage_index) = storage_index else {
+                accounts_log().warn(
+                    "Unable to resolve refreshed account for persistence",
+                    Some(&json!({ "sourceIndex": source.index })),
+                );
+                return Ok(None);
+            };
+
+            let Some(stored_account) = next_storage.accounts.get_mut(storage_index) else {
+                return Ok(None);
+            };
+
+            stored_account.refresh_token = auth.refresh.clone();
+            stored_account.access_token = Some(auth.access.clone());
+            stored_account.expires_at = Some(auth.expires);
+            if let Some(account_id) = next_account_id.as_ref()
+                && should_update_account_id_from_token(
+                    stored_account.account_id_source.as_ref(),
+                    stored_account.account_id.as_deref(),
+                )
+            {
+                stored_account.account_id = Some(account_id.clone());
+                stored_account.account_id_source = Some(AccountIdSource::Token);
+            }
+            if let Some(email) = next_email.as_ref() {
+                stored_account.email = Some(email.clone());
+            }
+            // Re-enable on disk: `enabled = undefined` (omitted).
+            stored_account.enabled = None;
+            stored_account.cooling_down_until = None;
+            stored_account.cooldown_reason = None;
+
+            let live_index = find_account_index_by_identity(&this.accounts, source, Some(auth));
+            if let Some(live_index) = live_index {
+                let previous = {
+                    let live = &this.accounts[live_index];
+                    (
+                        live.meta.access_token.clone(),
+                        live.meta.refresh_token.clone(),
+                        live.meta.expires_at,
+                        live.meta.account_id.clone(),
+                        live.meta.account_id_source,
+                        live.meta.email.clone(),
+                        live.meta.enabled,
+                        live.meta.cooling_down_until,
+                        live.meta.cooldown_reason,
+                        live.runtime.consecutive_auth_failures,
+                    )
+                };
+
+                {
+                    let live = &mut this.accounts[live_index];
+                    live.update_from_auth(auth);
+                    live.meta.enabled = Some(true);
+                    live.clear_cooldown();
+                    live.clear_auth_failures();
+                }
+
+                if let Err(error) = persist.persist(&next_storage).await {
+                    // Roll back every live-account field exactly.
+                    let live = &mut this.accounts[live_index];
+                    live.meta.access_token = previous.0;
+                    live.meta.refresh_token = previous.1;
+                    live.meta.expires_at = previous.2;
+                    live.meta.account_id = previous.3;
+                    live.meta.account_id_source = previous.4;
+                    live.meta.email = previous.5;
+                    live.meta.enabled = previous.6;
+                    live.meta.cooling_down_until = previous.7;
+                    live.meta.cooldown_reason = previous.8;
+                    live.runtime.consecutive_auth_failures = previous.9;
+                    return Err(error);
+                }
+
+                return Ok(Some(live_index));
+            }
+
+            persist.persist(&next_storage).await?;
+            accounts_log().warn(
+                "Unable to resolve refreshed live account after persistence",
+                Some(&json!({ "sourceIndex": source.index })),
+            );
+            Ok(None)
+        })
+        .await;
+
+        match result {
+            Ok(live_index) => Ok(live_index),
+            Err(error) => {
+                let retryable = is_retryable_auth_persistence_error(&error);
+                Err(CodexError::auth(ERROR_MESSAGES.token_refresh_failed)
+                    .with_retryable(retryable)
+                    .with_cause(error))
+            }
+        }
+    }
+
+    /// TS private `findNextEnabled(start)` — negative-safe wrap-around scan
+    /// (start inclusive); `-1` when the pool is empty or fully disabled.
+    fn find_next_enabled(&self, start: i64) -> i64 {
+        let count = self.accounts.len() as i64;
+        if count == 0 {
+            return -1;
+        }
+        let base = ((start % count) + count) % count;
+        for step in 0..count {
+            let candidate = (base + step) % count;
+            if self.accounts[candidate as usize].is_enabled() {
+                return candidate;
+            }
+        }
+        -1
+    }
+
+    /// Core of TS `removeAccount(account)` (object-identity lookup becomes an
+    /// array-position parameter in Rust) — splice, tracker/circuit cleanup
+    /// under BOTH the stable cached key and the recomputed identity key
+    /// (accounts-02), numeric-range tracker clears, reindex + numeric-cache
+    /// invalidation (HI-01), cursor/active fixups, and the
+    /// `lastSwitchReason="rotation"` retarget stamp (HI-04).
+    fn remove_account_at(&mut self, idx: usize) -> bool {
+        if idx >= self.accounts.len() {
+            return false;
+        }
+
+        // Snapshot family pointers before the splice.
+        let prior_cursor = self.cursor_by_family;
+        let prior_active = self.current_account_index_by_family;
+
+        let mut account = self.accounts.remove(idx);
+
+        // Clear identity-keyed tracker + circuit state for the removed
+        // account. Tracker state is WRITTEN under the pinned (stable)
+        // getRuntimeTrackerKey; the recomputed runtime identity key can
+        // DIFFER after identity enrichment — clear the stable key first
+        // (required), then the recomputed key when it differs (defensive).
+        let removed_tracker_key = get_runtime_tracker_key(&mut account);
+        let health_tracker = get_health_tracker(None);
+        let token_tracker = get_token_tracker(None);
+        health_tracker.clear_account_key(removed_tracker_key.clone());
+        token_tracker.clear_account_key(removed_tracker_key.clone());
+        let removed_identity_key = get_runtime_account_identity_key(
+            account.meta.account_id.as_deref(),
+            account.meta.email.as_deref(),
+            Some(account.index as i64),
+        )
+        .map(|key| match key {
+            RuntimeAccountIdentityKey::Key(key) => TrackerKey::Text(key),
+            RuntimeAccountIdentityKey::Index(index) => TrackerKey::Number(index),
+        });
+        if let Some(identity_key) = removed_identity_key
+            && identity_key != removed_tracker_key
+        {
+            health_tracker.clear_account_key(identity_key.clone());
+            token_tracker.clear_account_key(identity_key);
+        }
+        if let Some(circuit_key_id) = account.runtime.circuit_key_id.as_deref()
+            && !circuit_key_id.is_empty()
+        {
+            remove_circuit_breaker(circuit_key_id);
+        }
+
+        // Numeric-range clear for the shifted survivors, then reindex and
+        // invalidate cached NUMERIC tracker keys (position-encoding); string
+        // identity keys survive (HI-01).
+        health_tracker.clear_numeric_keys_at_or_above(idx);
+        token_tracker.clear_numeric_keys_at_or_above(idx);
+        for (i, acc) in self.accounts.iter_mut().enumerate() {
+            acc.index = i;
+            if matches!(acc.runtime.runtime_tracker_key, Some(TrackerKey::Number(_))) {
+                acc.runtime.runtime_tracker_key = None;
+            }
+        }
+
+        if self.accounts.is_empty() {
+            for family in MODEL_FAMILIES {
+                self.cursor_by_family.set(family, 0);
+                self.current_account_index_by_family.set(family, -1);
+            }
+            return true;
+        }
+
+        let len = self.accounts.len() as i64;
+        let idx_i = idx as i64;
+        let mut retargeted_successors: BTreeSet<i64> = BTreeSet::new();
+
+        for family in MODEL_FAMILIES {
+            // Cursor: shift down when past the removed index, then normalize
+            // into [0, len).
+            let mut cursor = prior_cursor.get(family);
+            if cursor > idx_i {
+                cursor = (cursor - 1).max(0);
+            }
+            if cursor >= len {
+                cursor = 0;
+            }
+            if cursor < 0 {
+                cursor = 0;
+            }
+            self.cursor_by_family.set(family, cursor);
+
+            // Active pointer: shift down when strictly past; when AT the
+            // removed slot advance to the next enabled account; dangling
+            // pointers re-resolve from 0; -1 only when nothing is enabled.
+            let mut active = prior_active.get(family);
+            let active_was_removed = active == idx_i;
+            if active > idx_i {
+                active -= 1;
+            } else if active_was_removed {
+                active = self.find_next_enabled(idx_i.min(len - 1));
+            }
+            if active >= len {
+                active = self.find_next_enabled(0);
+            }
+            self.current_account_index_by_family.set(family, active);
+            if active_was_removed && active >= 0 && active < len {
+                retargeted_successors.insert(active);
+            }
+        }
+
+        // HI-04: stamp the retarget signal (deduped — the field is
+        // per-account, not per-family).
+        for successor_idx in retargeted_successors {
+            if let Some(successor) = self.accounts.get_mut(successor_idx as usize) {
+                successor.meta.last_switch_reason = Some(SwitchReason::Rotation);
+            }
+        }
+
+        true
+    }
+
+    /// TS `removeAccountByIndex(index)` — bounds-checked wrapper.
+    pub fn remove_account_by_index(&mut self, index: i64) -> bool {
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return false;
+        }
+        self.remove_account_at(index as usize)
+    }
+
+    /// TS `setAccountEnabled(index, enabled)` — stores the literal boolean;
+    /// re-enabling resets workspaces; disabling repairs BOTH the active
+    /// pointer and the cursor for every family whose pointer references the
+    /// just-disabled index (AUDIT-H10 / oracle F2). Does NOT save to disk.
+    pub fn set_account_enabled(&mut self, index: i64, enabled: bool) -> Option<&ManagedAccount> {
+        if index < 0 || index >= self.accounts.len() as i64 {
+            return None;
+        }
+        let idx = index as usize;
+        let was_enabled = self.accounts[idx].is_enabled();
+        self.accounts[idx].meta.enabled = Some(enabled);
+        if enabled && !was_enabled {
+            self.accounts[idx].reset_workspaces();
+        }
+        if !enabled {
+            let len = self.accounts.len() as i64;
+            // Local scan starts at start+1 (never re-checks the start slot),
+            // unlike the private findNextEnabled — port both verbatim.
+            let find_next_enabled = |accounts: &[ManagedAccount], start: i64| -> i64 {
+                for step in 1..len {
+                    let candidate = (start + step) % len;
+                    if accounts[candidate as usize].is_enabled() {
+                        return candidate;
+                    }
+                }
+                -1
+            };
+            for family in MODEL_FAMILIES {
+                if self.current_account_index_by_family.get(family) == index {
+                    let next = find_next_enabled(&self.accounts, index);
+                    if next != -1 {
+                        self.current_account_index_by_family.set(family, next);
+                    }
+                }
+                if self.cursor_by_family.get(family) == index {
+                    let next = find_next_enabled(&self.accounts, index);
+                    if next != -1 {
+                        self.cursor_by_family.set(family, next);
+                    }
+                }
+            }
+        }
+        self.accounts.get(idx)
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/accounts.test.ts (state / constructor / removal /
+// tracker-key suites) and test/accounts-load-from-disk.test.ts (hydration).
+// Selection- and persistence-half suites are ported by their owning modules.
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::json_io::stringify_pretty2;
+    use cma_rotation::circuit_breaker::{clear_circuit_breakers, get_circuit_breaker};
+    use cma_rotation::trackers::DEFAULT_TOKEN_BUCKET_CONFIG;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serde_json::{Value, json};
+    use serial_test::serial;
+
+    /// Minimal base64url (no padding) encoder so the test JWTs need no
+    /// external dev-dependency (the crate's Cargo.toml is foundation-frozen).
+    fn base64url_no_pad(input: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut out = String::with_capacity(input.len().div_ceil(3) * 4);
+        for chunk in input.chunks(3) {
+            let b0 = chunk[0] as u32;
+            let b1 = chunk.get(1).copied().unwrap_or(0) as u32;
+            let b2 = chunk.get(2).copied().unwrap_or(0) as u32;
+            let triple = (b0 << 16) | (b1 << 8) | b2;
+            out.push(ALPHABET[(triple >> 18) as usize & 0x3f] as char);
+            out.push(ALPHABET[(triple >> 12) as usize & 0x3f] as char);
+            if chunk.len() > 1 {
+                out.push(ALPHABET[(triple >> 6) as usize & 0x3f] as char);
+            }
+            if chunk.len() > 2 {
+                out.push(ALPHABET[triple as usize & 0x3f] as char);
+            }
+        }
+        out
+    }
+
+    fn make_jwt(payload: &Value) -> String {
+        format!(
+            "{}.{}.signature",
+            base64url_no_pad(b"{\"alg\":\"none\"}"),
+            base64url_no_pad(payload.to_string().as_bytes())
+        )
+    }
+
+    fn auth(access: &str, refresh: &str, expires: i64) -> OAuthAuthDetails {
+        OAuthAuthDetails {
+            access: access.to_string(),
+            refresh: refresh.to_string(),
+            expires,
+        }
+    }
+
+    fn stored_account(refresh: &str, now: i64) -> AccountMetadataV3 {
+        AccountMetadataV3::new(refresh, now, now)
+    }
+
+    fn storage_of(accounts: Vec<AccountMetadataV3>, active_index: i64) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage.active_index = active_index;
+        storage
+    }
+
+    fn reset_volatile() {
+        reset_trackers();
+        clear_circuit_breakers();
+    }
+
+    // -- constructor ---------------------------------------------------------
+
+    #[test]
+    fn seeds_from_fallback_auth_when_no_storage_exists() {
+        let auth = auth("access-token", "refresh-token", now_ms() + 60_000);
+        let manager = AccountManager::new(Some(&auth), None);
+        assert_eq!(manager.get_account_count(), 1);
+        let account = manager.get_current_account().expect("current account");
+        assert_eq!(account.meta.refresh_token, "refresh-token");
+        // Fresh-pool fallback gets lastUsed = 0 (NOT now — gotcha 14).
+        assert_eq!(account.meta.last_used, 0);
+        assert_eq!(account.meta.last_switch_reason, Some(SwitchReason::Initial));
+        assert!(account.is_enabled());
+        assert_eq!(manager.get_active_index(), 0);
+    }
+
+    #[test]
+    fn returns_account_by_index_and_rejects_invalid_indexes() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            0,
+        );
+        let manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(
+            manager
+                .get_account_by_index(0)
+                .map(|a| a.meta.refresh_token.as_str()),
+            Some("token-1")
+        );
+        assert_eq!(
+            manager
+                .get_account_by_index(1)
+                .map(|a| a.meta.refresh_token.as_str()),
+            Some("token-2")
+        );
+        assert!(manager.get_account_by_index(-1).is_none());
+        assert!(manager.get_account_by_index(9).is_none());
+    }
+
+    #[test]
+    fn filters_out_accounts_with_blank_refresh_token_keeping_stored_positions() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("valid-token", now),
+                stored_account("", now),
+                stored_account("   ", now),
+                stored_account("another-valid", now),
+            ],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(manager.get_account_count(), 2);
+        let accounts = manager.get_accounts_snapshot();
+        assert_eq!(accounts[0].meta.refresh_token, "valid-token");
+        assert_eq!(accounts[1].meta.refresh_token, "another-valid");
+        // Gotcha 14: surviving rows keep their ORIGINAL stored positions in
+        // `index` until the first removal reindex.
+        assert_eq!(accounts[0].index, 0);
+        assert_eq!(accounts[1].index, 3);
+    }
+
+    #[test]
+    fn merges_fallback_auth_when_matching_by_account_id() {
+        let now = now_ms();
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "matching-account-id" },
+            "email": "fallback@example.com",
+        }));
+        let mut account = stored_account("stored-token", now);
+        account.account_id = Some("matching-account-id".to_string());
+        let stored = storage_of(vec![account], 0);
+        let auth = auth(&access, "new-refresh-token", now + 60_000);
+
+        let manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 1);
+        let account = manager.get_current_account().expect("account");
+        assert_eq!(account.meta.refresh_token, "new-refresh-token");
+        assert_eq!(account.meta.access_token.as_deref(), Some(access.as_str()));
+    }
+
+    #[test]
+    fn trims_fallback_account_id_before_matching_and_persisting_it() {
+        let now = now_ms();
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "  matching-account-id  " },
+        }));
+        let mut account = stored_account("stored-token", now);
+        account.account_id = Some("matching-account-id".to_string());
+        let stored = storage_of(vec![account], 0);
+        let auth = auth(&access, "new-refresh-token", now + 60_000);
+
+        let manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 1);
+        let account = manager.get_current_account().expect("account");
+        assert_eq!(account.meta.refresh_token, "new-refresh-token");
+        assert_eq!(
+            account.meta.account_id.as_deref(),
+            Some("matching-account-id")
+        );
+    }
+
+    #[test]
+    fn ignores_malformed_stored_rows_when_matching_fallback_by_shared_account_id() {
+        let now = now_ms();
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "matching-account-id" },
+        }));
+        let make = |refresh: &str| {
+            let mut account = stored_account(refresh, now);
+            account.account_id = Some("matching-account-id".to_string());
+            account
+        };
+        let stored = storage_of(vec![make("stored-token"), make(""), make("   ")], 0);
+        let auth = auth(&access, "new-refresh-token", now + 60_000);
+
+        let manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 1);
+        let account = manager.get_current_account().expect("account");
+        assert_eq!(account.meta.refresh_token, "new-refresh-token");
+        assert_eq!(
+            account.meta.account_id.as_deref(),
+            Some("matching-account-id")
+        );
+    }
+
+    #[test]
+    fn merges_fallback_auth_when_matching_by_email_without_duplicating() {
+        let now = now_ms();
+        let access = make_jwt(&json!({ "email": "fallback@example.com" }));
+        let mut account = stored_account("stored-token", now);
+        account.email = Some("fallback@example.com".to_string());
+        let stored = storage_of(vec![account], 0);
+        let auth = auth(&access, "different-refresh-token", now + 60_000);
+
+        let manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 1);
+        let account = manager.get_current_account().expect("account");
+        assert_eq!(account.meta.refresh_token, "different-refresh-token");
+        assert_eq!(
+            account.meta.email.as_deref(),
+            Some("fallback@example.com")
+        );
+    }
+
+    #[test]
+    fn adds_fallback_as_distinct_account_when_same_email_spans_multiple_account_ids() {
+        let now = now_ms();
+        let access = make_jwt(&json!({ "email": "shared@example.com" }));
+        let make = |id: &str, refresh: &str| {
+            let mut account = stored_account(refresh, now);
+            account.account_id = Some(id.to_string());
+            account.email = Some("shared@example.com".to_string());
+            account
+        };
+        let stored = storage_of(
+            vec![
+                make("workspace-alpha", "refresh-alpha"),
+                make("workspace-beta", "refresh-beta"),
+            ],
+            0,
+        );
+        let auth = auth(&access, "refresh-gamma", now + 60_000);
+
+        let mut manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 3);
+        let refreshes: Vec<String> = manager
+            .get_accounts_snapshot()
+            .iter()
+            .map(|account| account.meta.refresh_token.clone())
+            .collect();
+        assert_eq!(refreshes, vec!["refresh-alpha", "refresh-beta", "refresh-gamma"]);
+    }
+
+    #[test]
+    fn adds_fallback_as_new_account_when_no_match_found() {
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("existing-token", now)], 0);
+        let auth = auth("new-access", "new-refresh", now + 60_000);
+
+        let mut manager = AccountManager::new(Some(&auth), Some(&stored));
+        assert_eq!(manager.get_account_count(), 2);
+        let accounts = manager.get_accounts_snapshot();
+        assert_eq!(accounts[0].meta.refresh_token, "existing-token");
+        assert_eq!(accounts[1].meta.refresh_token, "new-refresh");
+        // Appended fallback gets lastUsed = now (differs from the fresh-pool
+        // case, gotcha 14) and lastSwitchReason = "initial".
+        assert!(accounts[1].meta.last_used >= now);
+        assert_eq!(
+            accounts[1].meta.last_switch_reason,
+            Some(SwitchReason::Initial)
+        );
+        // Opaque access token carries no accountId → source stays unset.
+        assert_eq!(accounts[1].meta.account_id_source, None);
+    }
+
+    #[test]
+    fn sets_account_id_source_to_token_when_fallback_account_id_exists() {
+        let now = now_ms();
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_new" },
+        }));
+        let auth = auth(&access, "refresh-new", now + 60_000);
+        let manager = AccountManager::new(Some(&auth), None);
+        let account = manager.get_current_account().expect("account");
+        assert_eq!(account.meta.account_id.as_deref(), Some("acc_new"));
+        assert_eq!(
+            account.meta.account_id_source,
+            Some(AccountIdSource::Token)
+        );
+    }
+
+    #[test]
+    fn pointer_init_uses_active_index_by_family_modulo_pool_size() {
+        let now = now_ms();
+        let mut stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            1,
+        );
+        let mut by_family = cma_core::schemas::account_storage::ActiveIndexByFamily::default();
+        by_family.set(ModelFamily::Gpt5_2, Some(5)); // 5 % 2 == 1
+        by_family.set(ModelFamily::Codex, Some(0));
+        stored.active_index_by_family = Some(by_family);
+
+        let manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(manager.get_active_index_for_family(ModelFamily::Codex), 0);
+        assert_eq!(manager.get_active_index_for_family(ModelFamily::Gpt5_2), 1);
+        // Families without an entry fall back to activeIndex (1).
+        assert_eq!(manager.get_active_index_for_family(ModelFamily::CodexMax), 1);
+        assert_eq!(manager.cursor_by_family.get(ModelFamily::Gpt5_2), 1);
+    }
+
+    // -- hasRefreshToken -----------------------------------------------------
+
+    #[test]
+    fn has_refresh_token_exact_equality() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            0,
+        );
+        let manager = AccountManager::new(None, Some(&stored));
+        assert!(manager.has_refresh_token("token-1"));
+        assert!(manager.has_refresh_token("token-2"));
+        assert!(!manager.has_refresh_token("non-existent"));
+        assert!(!manager.has_refresh_token(""));
+    }
+
+    // -- workspaces (#491) ---------------------------------------------------
+
+    fn workspace(id: &str, name: &str, enabled: bool, is_default: Option<bool>) -> Workspace {
+        Workspace {
+            id: id.to_string(),
+            name: Some(name.to_string()),
+            enabled,
+            disabled_at: None,
+            is_default,
+        }
+    }
+
+    #[test]
+    fn does_not_disable_a_different_current_workspace_after_rotation() {
+        let now = now_ms();
+        let mut account = stored_account("token-1", now);
+        account.workspaces = Some(vec![
+            workspace("workspace-1", "Workspace 1", true, None),
+            workspace("workspace-2", "Workspace 2", true, None),
+        ]);
+        account.current_workspace_index = Some(0);
+        let stored = storage_of(vec![account], 0);
+
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.get_account_by_index_mut(0).expect("account");
+
+        assert!(account.disable_current_workspace(Some("workspace-1")));
+        assert_eq!(
+            account.rotate_to_next_workspace().map(|w| w.id.as_str()),
+            Some("workspace-2")
+        );
+        // CAS guard: the current workspace is now workspace-2.
+        assert!(!account.disable_current_workspace(Some("workspace-1")));
+        assert!(account.is_enabled());
+        assert!(account.has_enabled_workspaces());
+        assert_eq!(account.get_enabled_workspace_count(), 1);
+        assert_eq!(
+            account.get_current_workspace().map(|w| w.id.as_str()),
+            Some("workspace-2")
+        );
+        let states: Vec<bool> = account
+            .meta
+            .workspaces
+            .as_ref()
+            .unwrap()
+            .iter()
+            .map(|w| w.enabled)
+            .collect();
+        assert_eq!(states, vec![false, true]);
+    }
+
+    #[test]
+    fn re_enabling_an_exhausted_account_restores_its_workspaces() {
+        let now = now_ms();
+        let mut account = stored_account("token-1", now);
+        account.workspaces = Some(vec![
+            workspace("workspace-1", "One", false, None),
+            workspace("workspace-2", "Two", false, Some(true)),
+        ]);
+        account.current_workspace_index = Some(0);
+        account.enabled = Some(false);
+        let stored = storage_of(vec![account], 0);
+
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.set_account_enabled(0, true).expect("account");
+        assert!(account.is_enabled());
+        // All workspaces re-enabled; cursor points at the DEFAULT workspace.
+        assert!(account.has_enabled_workspaces());
+        assert_eq!(account.get_enabled_workspace_count(), 2);
+        assert_eq!(account.meta.current_workspace_index, Some(1));
+        assert!(
+            account
+                .meta
+                .workspaces
+                .as_ref()
+                .unwrap()
+                .iter()
+                .all(|w| w.enabled && w.disabled_at.is_none())
+        );
+    }
+
+    #[test]
+    fn re_enabling_without_default_workspace_resets_to_first() {
+        let now = now_ms();
+        let mut account = stored_account("token-1", now);
+        account.workspaces = Some(vec![
+            workspace("workspace-1", "One", false, None),
+            workspace("workspace-2", "Two", false, None),
+        ]);
+        account.current_workspace_index = Some(1);
+        account.enabled = Some(false);
+        let stored = storage_of(vec![account], 0);
+
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.set_account_enabled(0, true).expect("account");
+        assert_eq!(account.meta.current_workspace_index, Some(0));
+    }
+
+    #[test]
+    fn workspace_less_legacy_accounts_count_as_implicitly_enabled() {
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("token-1", now)], 0);
+        let manager = AccountManager::new(None, Some(&stored));
+        let account = manager.get_account_by_index(0).expect("account");
+        assert!(account.has_enabled_workspaces());
+        assert_eq!(account.get_workspace_count(), 0);
+        assert_eq!(account.get_enabled_workspace_count(), 0);
+        assert!(account.get_current_workspace().is_none());
+    }
+
+    // -- getActiveIndexForFamily (AUDIT-H10 / oracle F1) ---------------------
+
+    #[test]
+    fn active_index_normalizes_to_next_enabled_slot_when_active_disabled() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+            ],
+            1,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(manager.get_active_index(), 1);
+        manager.set_account_enabled(1, false);
+        // Pointer repair moved the active pointer; the read-side walk also
+        // guarantees a routable index.
+        let active = manager.get_active_index();
+        assert!(active == 2 || active == 0);
+        assert!(
+            manager
+                .get_account_by_index(active)
+                .expect("account")
+                .is_enabled()
+        );
+    }
+
+    #[test]
+    fn active_index_returns_minus_one_when_all_disabled() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager.set_account_enabled(0, false);
+        manager.set_account_enabled(1, false);
+        assert_eq!(manager.get_active_index(), -1);
+        assert!(manager.get_current_account().is_none());
+    }
+
+    #[test]
+    fn active_index_is_minus_one_on_empty_pool() {
+        let manager = AccountManager::new(None, None);
+        assert_eq!(manager.get_active_index(), -1);
+    }
+
+    // -- setActiveIndex ------------------------------------------------------
+
+    #[test]
+    fn set_active_index_sets_all_families_and_returns_account() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.set_active_index(1).expect("account");
+        assert_eq!(account.meta.refresh_token, "token-2");
+        assert_eq!(account.meta.last_switch_reason, Some(SwitchReason::Rotation));
+        for family in MODEL_FAMILIES {
+            assert_eq!(manager.current_account_index_by_family.get(family), 1);
+            // Gotcha 9: setActiveIndex sets cursor = index (NOT index+1).
+            assert_eq!(manager.cursor_by_family.get(family), 1);
+        }
+    }
+
+    #[test]
+    fn set_active_index_rejects_invalid_or_disabled() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![stored_account("token-1", now), stored_account("token-2", now)],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert!(manager.set_active_index(-1).is_none());
+        assert!(manager.set_active_index(2).is_none());
+        manager.set_account_enabled(1, false);
+        assert!(manager.set_active_index(1).is_none());
+    }
+
+    // -- toast debounce ------------------------------------------------------
+
+    #[test]
+    fn debounces_account_toasts_for_the_same_index_only() {
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("token-1", now)], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert!(manager.should_show_account_toast(0, None));
+        manager.mark_toast_shown(0);
+        assert!(!manager.should_show_account_toast(0, None));
+        // A DIFFERENT index always toasts (gotcha 30).
+        assert!(manager.should_show_account_toast(1, None));
+        // A zero window never debounces.
+        assert!(manager.should_show_account_toast(0, Some(0)));
+    }
+
+    // -- updateFromAuth ------------------------------------------------------
+
+    #[test]
+    fn update_from_auth_updates_tokens_and_token_sourced_account_id() {
+        let now = now_ms();
+        let mut stored_row = stored_account("old-refresh", now);
+        stored_row.account_id = Some("old-account".to_string());
+        stored_row.account_id_source = Some(AccountIdSource::Token);
+        let stored = storage_of(vec![stored_row], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        let access = make_jwt(&json!({
+            "email": "new@example.com",
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_new" },
+        }));
+        let auth = auth(&access, "new-refresh", now + 3_600_000);
+        let account = manager.get_account_by_index_mut(0).expect("account");
+        account.update_from_auth(&auth);
+
+        assert_eq!(account.meta.refresh_token, "new-refresh");
+        assert_eq!(account.meta.access_token.as_deref(), Some(access.as_str()));
+        assert_eq!(account.meta.expires_at, Some(now + 3_600_000));
+        assert_eq!(account.meta.account_id.as_deref(), Some("acc_new"));
+        assert_eq!(account.meta.account_id_source, Some(AccountIdSource::Token));
+        assert_eq!(account.meta.email.as_deref(), Some("new@example.com"));
+    }
+
+    #[test]
+    fn update_from_auth_preserves_org_selected_account_id() {
+        let now = now_ms();
+        let mut stored_row = stored_account("old-refresh", now);
+        stored_row.account_id = Some("org-selected".to_string());
+        stored_row.account_id_source = Some(AccountIdSource::Org);
+        let stored = storage_of(vec![stored_row], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_token" },
+        }));
+        let auth = auth(&access, "new-refresh", now + 3_600_000);
+        let account = manager.get_account_by_index_mut(0).expect("account");
+        account.update_from_auth(&auth);
+
+        // Org selection is sticky across refreshes.
+        assert_eq!(account.meta.account_id.as_deref(), Some("org-selected"));
+        assert_eq!(account.meta.account_id_source, Some(AccountIdSource::Org));
+        // Email extraction failed (no email claim) → old value kept (None).
+        assert_eq!(account.meta.email, None);
+    }
+
+    // -- auth-failure primitives ---------------------------------------------
+    // (Cooldown set/clear/self-expiry lives in manager_persistence.rs and is
+    // tested there.)
+
+    #[test]
+    fn auth_failures_increment_and_clear_to_zero_not_none() {
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("token-1", now)], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.get_account_by_index_mut(0).expect("account");
+
+        assert_eq!(account.runtime.consecutive_auth_failures, None);
+        assert_eq!(account.increment_auth_failures(), 1);
+        assert_eq!(account.increment_auth_failures(), 2);
+        account.clear_auth_failures();
+        // Sets 0, does NOT delete (gotcha 13).
+        assert_eq!(account.runtime.consecutive_auth_failures, Some(0));
+    }
+
+    // -- tracker keys --------------------------------------------------------
+
+    #[test]
+    fn runtime_tracker_key_prefers_identity_and_falls_back_to_index() {
+        let now = now_ms();
+        let mut with_id = stored_account("tok-a", now);
+        with_id.account_id = Some("acc_stable".to_string());
+        let anonymous = stored_account("tok-b", now);
+        let stored = storage_of(vec![with_id, anonymous], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(0).unwrap()),
+            TrackerKey::Text("account:acc_stable".to_string())
+        );
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(1).unwrap()),
+            TrackerKey::Number(1)
+        );
+    }
+
+    #[test]
+    fn runtime_tracker_key_is_sticky_across_identity_enrichment() {
+        let now = now_ms();
+        let mut email_only = stored_account("tok-enrich", now);
+        email_only.email = Some("stale@example.com".to_string());
+        let stored = storage_of(vec![email_only], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        let account = manager.get_account_by_index_mut(0).expect("account");
+
+        let stable = get_runtime_tracker_key(account);
+        assert_eq!(stable, TrackerKey::Text("email:stale@example.com".to_string()));
+
+        let access = make_jwt(&json!({
+            "email": "stale@example.com",
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_enriched" },
+        }));
+        account.update_from_auth(&auth(&access, "tok-enrich-rotated", now + 3_600_000));
+        assert_eq!(account.meta.account_id.as_deref(), Some("acc_enriched"));
+        // The pinned key does NOT change (gotcha 5)...
+        assert_eq!(get_runtime_tracker_key(account), stable);
+        // ...while the recomputed identity key now DIVERGES.
+        let recomputed = get_runtime_account_identity_key(
+            account.meta.account_id.as_deref(),
+            account.meta.email.as_deref(),
+            Some(account.index as i64),
+        )
+        .expect("identity key");
+        assert_ne!(
+            recomputed,
+            RuntimeAccountIdentityKey::Key("email:stale@example.com".to_string())
+        );
+    }
+
+    #[test]
+    fn snapshot_materializes_keys_and_deep_copies_rate_limit_map() {
+        let now = now_ms();
+        let mut with_id = stored_account("tok-a", now);
+        with_id.account_id = Some("acc_snap".to_string());
+        let stored = storage_of(vec![with_id], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        let mut snapshot = manager.get_accounts_snapshot();
+        assert_eq!(
+            snapshot[0].runtime.runtime_tracker_key,
+            Some(TrackerKey::Text("account:acc_snap".to_string()))
+        );
+        assert_eq!(
+            snapshot[0].runtime.circuit_key_id.as_deref(),
+            Some("account:acc_snap")
+        );
+        // Side effect: the LIVE account's caches were materialized too.
+        assert!(
+            manager.accounts[0].runtime.runtime_tracker_key.is_some()
+                && manager.accounts[0].runtime.circuit_key_id.is_some()
+        );
+        // Deep copy: mutating the snapshot's map does not touch the live one.
+        snapshot[0]
+            .rate_limit_reset_times
+            .insert("codex", now + 60_000);
+        assert!(manager.accounts[0].rate_limit_reset_times.is_empty());
+    }
+
+    // -- removeAccount -------------------------------------------------------
+
+    #[test]
+    #[serial(volatile)]
+    fn removes_an_account_and_updates_indices() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+            ],
+            1,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(
+            manager
+                .get_current_account()
+                .map(|a| a.meta.refresh_token.clone()),
+            Some("token-2".to_string())
+        );
+
+        assert!(manager.remove_account_by_index(1));
+        assert_eq!(manager.get_account_count(), 2);
+        let remaining = manager.get_accounts_snapshot();
+        assert_eq!(remaining[0].meta.refresh_token, "token-1");
+        assert_eq!(remaining[1].meta.refresh_token, "token-3");
+        assert_eq!(remaining[0].index, 0);
+        assert_eq!(remaining[1].index, 1);
+        // HI-04: the successor that replaced the removed "current" pointer is
+        // stamped with lastSwitchReason = "rotation".
+        assert_eq!(
+            remaining[1].meta.last_switch_reason,
+            Some(SwitchReason::Rotation)
+        );
+        assert_eq!(manager.get_active_index(), 1);
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn clears_identity_keyed_tracker_and_circuit_state_on_removal() {
+        reset_volatile();
+        let now = now_ms();
+        let mut stable = stored_account("tok-a", now);
+        stable.account_id = Some("acc_stable".to_string());
+        let mut other = stored_account("tok-b", now);
+        other.account_id = Some("acc_other".to_string());
+        let stored = storage_of(vec![stable, other], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        // Materialize keys on the live accounts (snapshot side effect).
+        let _ = manager.get_accounts_snapshot();
+        let identity_key = TrackerKey::Text("account:acc_stable".to_string());
+
+        let health_tracker = get_health_tracker(None);
+        let token_tracker = get_token_tracker(None);
+        assert!(token_tracker.try_consume(identity_key.clone(), Some("codex")));
+        assert!(
+            token_tracker.get_tokens(identity_key.clone(), Some("codex"))
+                < DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+        let breaker = get_circuit_breaker("account:acc_stable", None);
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.record_failure();
+        assert!(!breaker.is_available());
+        for _ in 0..5 {
+            health_tracker.record_failure(identity_key.clone(), Some("codex"));
+        }
+        assert!(health_tracker.get_score(identity_key.clone(), Some("codex")) < 100.0);
+
+        assert!(manager.remove_account_by_index(0));
+
+        assert_eq!(
+            health_tracker.get_score(identity_key.clone(), Some("codex")),
+            100.0
+        );
+        assert_eq!(
+            token_tracker.get_tokens(identity_key, Some("codex")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+        assert!(get_circuit_breaker("account:acc_stable", None).is_available());
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn clears_stable_tracker_key_after_identity_enrichment_on_removal() {
+        reset_volatile();
+        let now = now_ms();
+        let mut email_only = stored_account("tok-enrich", now);
+        email_only.email = Some("stale@example.com".to_string());
+        let mut other = stored_account("tok-other", now);
+        other.account_id = Some("acc_other".to_string());
+        let stored = storage_of(vec![email_only, other], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        let stable_key = get_runtime_tracker_key(manager.get_account_by_index_mut(0).unwrap());
+        assert_eq!(stable_key, TrackerKey::Text("email:stale@example.com".to_string()));
+
+        let health_tracker = get_health_tracker(None);
+        let token_tracker = get_token_tracker(None);
+        assert!(token_tracker.try_consume(stable_key.clone(), Some("codex")));
+        for _ in 0..5 {
+            health_tracker.record_failure(stable_key.clone(), Some("codex"));
+        }
+        assert!(health_tracker.get_score(stable_key.clone(), Some("codex")) < 100.0);
+
+        // Enrich the identity so the recomputed key diverges from the pinned
+        // one.
+        let access = make_jwt(&json!({
+            "email": "stale@example.com",
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_enriched" },
+        }));
+        manager
+            .get_account_by_index_mut(0)
+            .unwrap()
+            .update_from_auth(&auth(&access, "tok-enrich-rotated", now + 3_600_000));
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(0).unwrap()),
+            stable_key
+        );
+
+        assert!(manager.remove_account_by_index(0));
+
+        // The STABLE key's state was cleared (the buggy variant cleared only
+        // the recomputed key).
+        assert_eq!(
+            health_tracker.get_score(stable_key.clone(), Some("codex")),
+            100.0
+        );
+        assert_eq!(
+            token_tracker.get_tokens(stable_key, Some("codex")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn invalidates_numeric_runtime_tracker_keys_after_reindex_hi_01() {
+        reset_volatile();
+        let now = now_ms();
+        // Refresh-only accounts: tracker keys fall back to numeric indexes.
+        let stored = storage_of(
+            vec![
+                stored_account("tok-0", now),
+                stored_account("tok-1", now),
+                stored_account("tok-2", now),
+            ],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(1).unwrap()),
+            TrackerKey::Number(1)
+        );
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(2).unwrap()),
+            TrackerKey::Number(2)
+        );
+
+        assert!(manager.remove_account_by_index(0));
+
+        // Cached numeric keys were invalidated and re-derive from the NEW
+        // positions.
+        assert_eq!(manager.accounts[0].runtime.runtime_tracker_key, None);
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(0).unwrap()),
+            TrackerKey::Number(0)
+        );
+        assert_eq!(
+            get_runtime_tracker_key(manager.get_account_by_index_mut(1).unwrap()),
+            TrackerKey::Number(1)
+        );
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn remove_returns_false_for_out_of_range_index() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("token-1", now)], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert!(!manager.remove_account_by_index(999));
+        assert!(!manager.remove_account_by_index(-1));
+        assert_eq!(manager.get_account_count(), 1);
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn handles_removing_the_last_account() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("token-1", now)], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert!(manager.remove_account_by_index(0));
+        assert_eq!(manager.get_account_count(), 0);
+        assert!(manager.get_current_account().is_none());
+        for family in MODEL_FAMILIES {
+            assert_eq!(manager.cursor_by_family.get(family), 0);
+            assert_eq!(manager.current_account_index_by_family.get(family), -1);
+        }
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn adjusts_cursor_when_removing_account_before_cursor_position() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+            ],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        for family in MODEL_FAMILIES {
+            manager.cursor_by_family.set(family, 2);
+            manager.current_account_index_by_family.set(family, 2);
+        }
+
+        assert!(manager.remove_account_by_index(0));
+
+        for family in MODEL_FAMILIES {
+            assert_eq!(manager.cursor_by_family.get(family), 1);
+            assert_eq!(manager.current_account_index_by_family.get(family), 1);
+        }
+        assert_eq!(
+            manager
+                .get_current_account()
+                .map(|a| a.meta.refresh_token.clone()),
+            Some("token-3".to_string())
+        );
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn advances_active_pointer_to_next_enabled_when_active_slot_removed_at_end() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+            ],
+            2,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        assert_eq!(
+            manager
+                .get_current_account()
+                .map(|a| a.meta.refresh_token.clone()),
+            Some("token-3".to_string())
+        );
+        assert!(manager.remove_account_by_index(2));
+        assert_eq!(manager.get_account_count(), 2);
+        // Pointer references a valid enabled account, not -1: the removed
+        // slot re-resolves via findNextEnabled(min(idx, len-1)) → index 1.
+        let after = manager.get_active_index();
+        assert_eq!(after, 1);
+        assert_eq!(
+            manager
+                .get_current_account()
+                .map(|a| a.meta.refresh_token.clone()),
+            Some("token-2".to_string())
+        );
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn yields_no_routable_account_when_every_remaining_account_is_disabled() {
+        reset_volatile();
+        let now = now_ms();
+        let mut disabled_1 = stored_account("token-1", now);
+        disabled_1.enabled = Some(false);
+        let active = stored_account("token-2", now);
+        let mut disabled_2 = stored_account("token-3", now);
+        disabled_2.enabled = Some(false);
+        let stored = storage_of(vec![disabled_1, active, disabled_2], 1);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        assert!(manager.remove_account_by_index(1));
+        assert_eq!(manager.get_active_index(), -1);
+        // No successor is stamped when nothing is enabled (HI-04 sibling
+        // assertion).
+        assert!(
+            manager
+                .get_accounts_snapshot()
+                .iter()
+                .all(|account| account.meta.last_switch_reason != Some(SwitchReason::Rotation))
+        );
+    }
+
+    #[test]
+    #[serial(volatile)]
+    fn does_not_perturb_unrelated_family_pointers_on_removal() {
+        reset_volatile();
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+                stored_account("token-4", now),
+            ],
+            0,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        // codex points at the removed slot; gpt-5.2 points past it; gpt-5.1
+        // points before it.
+        manager
+            .current_account_index_by_family
+            .set(ModelFamily::Codex, 1);
+        manager
+            .current_account_index_by_family
+            .set(ModelFamily::Gpt5_2, 3);
+        manager
+            .current_account_index_by_family
+            .set(ModelFamily::Gpt5_1, 0);
+
+        assert!(manager.remove_account_by_index(1));
+
+        let active = |family: ModelFamily| manager.current_account_index_by_family.get(family);
+        assert_eq!(active(ModelFamily::Codex), 1);
+        // Past the removed index: shifted down by one.
+        assert_eq!(active(ModelFamily::Gpt5_2), 2);
+        // Before the removed index: untouched.
+        assert_eq!(active(ModelFamily::Gpt5_1), 0);
+    }
+
+    // -- setAccountEnabled pointer repair (oracle F2) ------------------------
+
+    #[test]
+    fn disabling_repairs_active_and_cursor_pointers_in_lockstep() {
+        let now = now_ms();
+        let stored = storage_of(
+            vec![
+                stored_account("token-1", now),
+                stored_account("token-2", now),
+                stored_account("token-3", now),
+            ],
+            1,
+        );
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager.set_account_enabled(1, false);
+        for family in MODEL_FAMILIES {
+            assert_eq!(manager.current_account_index_by_family.get(family), 2);
+            assert_eq!(manager.cursor_by_family.get(family), 2);
+        }
+        // Families whose pointers did NOT reference the disabled index stay
+        // put when only one family matched (multi-family variant).
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager
+            .current_account_index_by_family
+            .set(ModelFamily::Gpt5_1, 0);
+        manager.set_account_enabled(1, false);
+        assert_eq!(
+            manager
+                .current_account_index_by_family
+                .get(ModelFamily::Gpt5_1),
+            0
+        );
+    }
+
+    // -- is_retryable_auth_persistence_error ---------------------------------
+
+    #[test]
+    fn retryable_auth_persistence_classification() {
+        let ebusy = CodexError::storage("save failed", "EBUSY", "/x/a.json", "hint", None);
+        assert!(is_retryable_auth_persistence_error(&ebusy));
+        let enospc = CodexError::storage("save failed", "ENOSPC", "/x/a.json", "hint", None);
+        assert!(!is_retryable_auth_persistence_error(&enospc));
+        let rate_limited = CodexError::api("too many requests", 429);
+        assert!(is_retryable_auth_persistence_error(&rate_limited));
+        // Cause chain: an outer non-retryable error wrapping EPERM.
+        let wrapped = CodexError::new("outer").with_cause(CodexError::storage(
+            "inner", "EPERM", "/x/a.json", "hint", None,
+        ));
+        assert!(is_retryable_auth_persistence_error(&wrapped));
+        let plain = CodexError::new("plain failure");
+        assert!(!is_retryable_auth_persistence_error(&plain));
+    }
+
+    // -- commitRefreshedAuth (sandboxed storage transaction) -----------------
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn commit_refreshed_auth_persists_and_updates_the_live_account() {
+        let _sandbox = EnvSandbox::new();
+        let now = now_ms();
+        let mut stored_row = stored_account("old-refresh", now);
+        stored_row.email = Some("user@example.com".to_string());
+        stored_row.enabled = Some(false);
+        stored_row.cooling_down_until = Some(now + 60_000);
+        stored_row.cooldown_reason =
+            Some(cma_core::schemas::account_storage::CooldownReason::AuthFailure);
+        let stored = storage_of(vec![stored_row], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager.get_account_by_index_mut(0).unwrap().increment_auth_failures();
+
+        let access = make_jwt(&json!({
+            "email": "user@example.com",
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_refreshed" },
+        }));
+        let auth = auth(&access, "rotated-refresh", now + 3_600_000);
+        let source = AccountIdentityCandidate {
+            account_id: None,
+            email: Some("user@example.com".to_string()),
+            refresh_token: Some("old-refresh".to_string()),
+            index: Some(0),
+        };
+
+        let live_index = manager
+            .commit_refreshed_auth(&source, &auth)
+            .await
+            .expect("commit succeeds");
+        assert_eq!(live_index, Some(0));
+
+        let account = manager.get_account_by_index(0).expect("account");
+        assert_eq!(account.meta.refresh_token, "rotated-refresh");
+        assert_eq!(account.meta.access_token.as_deref(), Some(access.as_str()));
+        assert_eq!(account.meta.expires_at, Some(now + 3_600_000));
+        assert_eq!(account.meta.account_id.as_deref(), Some("acc_refreshed"));
+        assert_eq!(account.meta.enabled, Some(true));
+        assert_eq!(account.meta.cooling_down_until, None);
+        assert_eq!(account.meta.cooldown_reason, None);
+        assert_eq!(account.runtime.consecutive_auth_failures, Some(0));
+
+        // The refreshed row reached disk (re-enabled: `enabled` omitted).
+        let on_disk = load_accounts().await.expect("storage on disk").storage;
+        assert_eq!(on_disk.accounts.len(), 1);
+        assert_eq!(on_disk.accounts[0].refresh_token, "rotated-refresh");
+        assert_eq!(on_disk.accounts[0].enabled, None);
+        assert_eq!(on_disk.accounts[0].cooling_down_until, None);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn commit_refreshed_auth_returns_none_for_unresolvable_source() {
+        let _sandbox = EnvSandbox::new();
+        let now = now_ms();
+        let stored = storage_of(vec![stored_account("some-refresh", now)], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+
+        let auth = auth("opaque-access", "rotated-refresh", now + 3_600_000);
+        let source = AccountIdentityCandidate {
+            account_id: Some("acc_missing".to_string()),
+            email: Some("missing@example.com".to_string()),
+            refresh_token: Some("unknown-refresh".to_string()),
+            index: Some(7),
+        };
+        let result = manager
+            .commit_refreshed_auth(&source, &auth)
+            .await
+            .expect("commit resolves");
+        assert_eq!(result, None);
+        // The live pool is untouched.
+        assert_eq!(
+            manager.get_account_by_index(0).unwrap().meta.refresh_token,
+            "some-refresh"
+        );
+    }
+
+    // -- hydrateFromCodexCli / loadFromDisk (sandboxed) ----------------------
+
+    fn write_cli_accounts(path: &std::path::Path, value: &Value) {
+        std::fs::write(path, stringify_pretty2(value)).unwrap();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn hydrates_missing_access_tokens_from_codex_cli_cache() {
+        let mut sandbox = EnvSandbox::new();
+        let accounts_path = sandbox.root().join("cli-accounts.json");
+        let auth_path = sandbox.root().join("cli-auth.json");
+        let config_path = sandbox.root().join("cli-config.toml");
+        sandbox.set_var("CODEX_CLI_ACCOUNTS_PATH", &accounts_path);
+        sandbox.set_var("CODEX_CLI_AUTH_PATH", &auth_path);
+        sandbox.set_var("CODEX_CLI_CONFIG_PATH", &config_path);
+        sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "1");
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+
+        let now = now_ms();
+        let fresh_expiry = now + 3_600_000;
+        write_cli_accounts(
+            &accounts_path,
+            &json!({
+                "accounts": [
+                    {
+                        "accountId": "acc_cli",
+                        "email": "cli@example.com",
+                        "auth": { "tokens": {
+                            "access_token": "cli-access",
+                            "refresh_token": "cli-refresh",
+                        }},
+                        "expiresAt": fresh_expiry,
+                    },
+                    {
+                        "accountId": "acc_stale",
+                        "email": "stale@example.com",
+                        "auth": { "tokens": {
+                            "access_token": "stale-access",
+                            "refresh_token": "stale-refresh",
+                        }},
+                        "expiresAt": now - 1_000,
+                    },
+                ],
+            }),
+        );
+
+        // Managed pool: one account missing its access token, one whose cache
+        // entry is expired.
+        let mut needs_token = stored_account("local-refresh", now);
+        needs_token.email = Some("cli@example.com".to_string());
+        let mut stale = stored_account("stale-local-refresh", now);
+        stale.email = Some("stale@example.com".to_string());
+        let stored = storage_of(vec![needs_token, stale], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager.hydrate_from_codex_cli().await;
+
+        let hydrated = manager.get_account_by_index(0).expect("account");
+        assert_eq!(hydrated.meta.access_token.as_deref(), Some("cli-access"));
+        assert_eq!(hydrated.meta.expires_at, Some(fresh_expiry));
+        assert_eq!(hydrated.meta.account_id.as_deref(), Some("acc_cli"));
+        assert_eq!(
+            hydrated.meta.account_id_source,
+            Some(AccountIdSource::Token)
+        );
+        // Expired cache entries are ignored entirely.
+        let untouched = manager.get_account_by_index(1).expect("account");
+        assert_eq!(untouched.meta.access_token, None);
+        assert_eq!(untouched.meta.account_id, None);
+
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn hydrate_never_overwrites_a_live_token() {
+        let mut sandbox = EnvSandbox::new();
+        let accounts_path = sandbox.root().join("cli-accounts.json");
+        sandbox.set_var("CODEX_CLI_ACCOUNTS_PATH", &accounts_path);
+        sandbox.set_var("CODEX_CLI_AUTH_PATH", sandbox.root().join("cli-auth.json"));
+        sandbox.set_var(
+            "CODEX_CLI_CONFIG_PATH",
+            sandbox.root().join("cli-config.toml"),
+        );
+        sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "1");
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+
+        let now = now_ms();
+        write_cli_accounts(
+            &accounts_path,
+            &json!({
+                "accounts": [{
+                    "email": "live@example.com",
+                    "auth": { "tokens": {
+                        "access_token": "cli-access",
+                        "refresh_token": "cli-refresh",
+                    }},
+                    "expiresAt": now + 3_600_000,
+                }],
+            }),
+        );
+
+        let mut live = stored_account("live-refresh", now);
+        live.email = Some("live@example.com".to_string());
+        live.access_token = Some("live-access".to_string());
+        live.expires_at = Some(now + 1_800_000);
+        let stored = storage_of(vec![live], 0);
+        let mut manager = AccountManager::new(None, Some(&stored));
+        manager.hydrate_from_codex_cli().await;
+
+        let account = manager.get_account_by_index(0).expect("account");
+        assert_eq!(account.meta.access_token.as_deref(), Some("live-access"));
+        assert_eq!(account.meta.expires_at, Some(now + 1_800_000));
+
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn load_from_disk_with_empty_dir_yields_empty_or_seeded_manager() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var(
+            "CODEX_CLI_ACCOUNTS_PATH",
+            sandbox.root().join("cli-accounts.json"),
+        );
+        sandbox.set_var("CODEX_CLI_AUTH_PATH", sandbox.root().join("cli-auth.json"));
+        sandbox.set_var(
+            "CODEX_CLI_CONFIG_PATH",
+            sandbox.root().join("cli-config.toml"),
+        );
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+
+        let manager = AccountManager::load_from_disk(None).await;
+        assert_eq!(manager.get_account_count(), 0);
+        assert_eq!(manager.get_active_index(), -1);
+
+        let seeded_auth = auth("access-token", "seed-refresh", now_ms() + 60_000);
+        let manager = AccountManager::load_from_disk(Some(&seeded_auth)).await;
+        assert_eq!(manager.get_account_count(), 1);
+        assert_eq!(
+            manager.get_current_account().unwrap().meta.refresh_token,
+            "seed-refresh"
+        );
+
+        cma_cli_mirror::state::clear_codex_cli_state_cache();
+    }
+}
diff --git a/crates/accounts/src/manager_persistence.rs b/crates/accounts/src/manager_persistence.rs
new file mode 100644
index 000000000..93e54dacd
--- /dev/null
+++ b/crates/accounts/src/manager_persistence.rs
@@ -0,0 +1,1912 @@
+//! Port of the persistence half of `lib/accounts.ts`:
+//! `buildStorageSnapshot` / `reconcileTokensFromDisk` / `saveToDisk` /
+//! debounced save + `flushPendingSave` / `syncCodexCliActiveSelection*` /
+//! `clearAccountTransientState` / `markRateLimited*` + cooldown bookkeeping
+//! / `formatAccountLabel` / `formatWorkspaceLines` / `formatCooldown` /
+//! `toAuthDetails`.
+//!
+//! Behavior source: specs/03-accounts.md §1.6–1.7 (+ §14 concurrency, §15
+//! gotchas 1–4, 11–17, 31). TS source is authoritative.
+//!
+//! ARCHITECTURE §8.4: [`AccountManager::build_storage_snapshot`] is THE ONLY
+//! bridge from manager state to [`AccountStorageV3`] — it clones the
+//! persisted `meta` shape only, so runtime-only state
+//! (`runtime.last_rate_limit_reason`, `runtime.consecutive_auth_failures`,
+//! cached tracker/circuit keys, health/token trackers) can never reach disk.
+//!
+//! Debounce model: the TS `setTimeout` + `pendingSave` promise chain needs
+//! autonomous firing, which in Rust requires shared ownership of the
+//! manager. [`SharedAccountManager`] (defined here) wraps
+//! `Arc<tokio::sync::Mutex<AccountManager>>` plus the debounce bookkeeping;
+//! the spawned timer task holds only `Weak` handles so a dropped pool
+//! cancels its pending save.
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex as StdMutex, Weak};
+
+use cma_cli_mirror::writer::{ActiveSelection, set_codex_cli_active_selection};
+use cma_core::constants::MAX_RATE_LIMIT_DELAY_MS;
+use cma_core::errors::CodexError;
+use cma_core::logger::create_logger;
+use cma_core::model_family::{MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::{
+    AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily, CooldownReason, RateLimitReason,
+    RateLimitStateV3, Workspace,
+};
+use cma_core::types::OAuthAuthDetails;
+use cma_core::utils::now_ms;
+use cma_storage::facade::get_storage_path;
+use cma_storage::identity::get_account_identity_key;
+use cma_storage::load::{PinAndGen, read_pin_and_gen_from_disk};
+use cma_storage::path_state::run_with_storage_path_state;
+use cma_storage::transactions::with_account_storage_transaction;
+use serde_json::json;
+
+use crate::manager::{AccountManager, ManagedAccount};
+use crate::rate_limits::{RateLimitedEntity, clear_all_rate_limits, format_wait_time, get_quota_key};
+
+/// TS `saveToDiskDebounced(delayMs = 500)` default.
+pub const SAVE_DEBOUNCE_DEFAULT_MS: u64 = 500;
+
+// ===========================================================================
+// Pure helpers (unit-tested standalone)
+// ===========================================================================
+
+/// The pin/gen race-protection core of `buildStorageSnapshot` (#474, spec
+/// gotcha 16):
+/// - the disk pin is adopted ONLY when the disk `affinityGeneration` is
+///   STRICTLY greater than the in-memory one (pin+gen are written atomically
+///   by the CLI, so a greater gen marks the disk pin authoritative);
+/// - the effective pin is then re-validated against the live account count
+///   (out of range → `None`).
+///
+/// Returns `(effective_pin, effective_gen)` — callers cache both back onto
+/// the manager instance.
+pub fn resolve_effective_pin_and_gen(
+    memory_pin: Option<i64>,
+    memory_gen: i64,
+    on_disk: PinAndGen,
+    accounts_len: usize,
+) -> (Option<i64>, i64) {
+    let mut pin = memory_pin;
+    let mut generation = memory_gen;
+    if on_disk.affinity_generation > generation {
+        generation = on_disk.affinity_generation;
+        pin = on_disk.pinned_account_index;
+    }
+    if let Some(p) = pin
+        && (p < 0 || p >= accounts_len as i64)
+    {
+        pin = None;
+    }
+    (pin, generation)
+}
+
+/// TS `reconcileTokensFromDisk(snapshot, current)` (stress audit H3, spec
+/// gotcha 17): for each snapshot account whose identity also exists on
+/// disk, adopt the DISK token material (refreshToken + accessToken +
+/// expiresAt together) only when the disk expiry is STRICTLY greater and
+/// the disk row has a refresh token. Equal expiries keep the in-memory
+/// copy; our own fresh refresh (newest expiry) always wins — a routine save
+/// can never clobber a token another process just rotated.
+pub fn reconcile_tokens_from_disk(
+    snapshot: &mut AccountStorageV3,
+    current: Option<&AccountStorageV3>,
+) {
+    let Some(current) = current else {
+        return;
+    };
+    let mut disk_by_identity: HashMap<String, &AccountMetadataV3> = HashMap::new();
+    for disk_account in &current.accounts {
+        if let Some(key) = get_account_identity_key(disk_account) {
+            // Later duplicates overwrite earlier ones (TS `Map.set`).
+            disk_by_identity.insert(key, disk_account);
+        }
+    }
+    for account in snapshot.accounts.iter_mut() {
+        let Some(key) = get_account_identity_key(&*account) else {
+            continue;
+        };
+        let Some(disk) = disk_by_identity.get(&key) else {
+            continue;
+        };
+        let disk_expires = disk.expires_at.unwrap_or(0);
+        let memory_expires = account.expires_at.unwrap_or(0);
+        if disk_expires > memory_expires && !disk.refresh_token.is_empty() {
+            account.refresh_token = disk.refresh_token.clone();
+            account.access_token = disk.access_token.clone();
+            account.expires_at = disk.expires_at;
+        }
+    }
+}
+
+/// The rate-limit write matrix of TS `markRateLimitedWithReason` (spec
+/// gotcha 1), factored pure for testability:
+/// - clamp `retry_after_ms` to `[0, MAX_RATE_LIMIT_DELAY_MS]` (7 days —
+///   stress audit H1);
+/// - base-key write when there is no model OR the reason is
+///   `quota`/`unknown`;
+/// - model-key write when a model is given AND the reason is
+///   `tokens`/`concurrent`/`unknown` (so `unknown`+model writes BOTH keys;
+///   `tokens`/`concurrent` leave the base key clear for other models);
+/// - every write is a monotone max-merge — a shorter later retry-after can
+///   never shrink an existing window.
+///
+/// An empty-string model counts as "no model" (JS falsiness).
+pub fn apply_rate_limit_with_reason(
+    times: &mut RateLimitStateV3,
+    now: i64,
+    retry_after_ms: i64,
+    family: ModelFamily,
+    reason: RateLimitReason,
+    model: Option<&str>,
+) {
+    let model = model.filter(|m| !m.is_empty());
+    let retry_ms = retry_after_ms.clamp(0, MAX_RATE_LIMIT_DELAY_MS);
+    let reset_at = now + retry_ms;
+
+    if model.is_none() || matches!(reason, RateLimitReason::Quota | RateLimitReason::Unknown) {
+        let base_key = get_quota_key(family, None);
+        let current = times.get(&base_key).unwrap_or(0);
+        times.insert(base_key, current.max(reset_at));
+    }
+
+    if let Some(model) = model
+        && matches!(
+            reason,
+            RateLimitReason::Tokens | RateLimitReason::Concurrent | RateLimitReason::Unknown
+        )
+    {
+        let model_key = get_quota_key(family, Some(model));
+        let current = times.get(&model_key).unwrap_or(0);
+        times.insert(model_key, current.max(reset_at));
+    }
+}
+
+// ===========================================================================
+// ManagedAccount — rate-limit / cooldown bookkeeping + toAuthDetails
+// (auth-failure tracking lives in manager.rs with the struct definition)
+// ===========================================================================
+
+impl ManagedAccount {
+    /// TS `markRateLimited(account, retryAfterMs, family, model?)` —
+    /// delegates with reason `"unknown"`.
+    pub fn mark_rate_limited(
+        &mut self,
+        retry_after_ms: i64,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) {
+        self.mark_rate_limited_with_reason(retry_after_ms, family, RateLimitReason::Unknown, model);
+    }
+
+    /// TS `markRateLimitedWithReason` — see
+    /// [`apply_rate_limit_with_reason`] for the key matrix; additionally
+    /// records the runtime-only `lastRateLimitReason` (never persisted).
+    pub fn mark_rate_limited_with_reason(
+        &mut self,
+        retry_after_ms: i64,
+        family: ModelFamily,
+        reason: RateLimitReason,
+        model: Option<&str>,
+    ) {
+        apply_rate_limit_with_reason(
+            self.rate_limit_reset_times_mut(),
+            now_ms(),
+            retry_after_ms,
+            family,
+            reason,
+            model,
+        );
+        self.runtime.last_rate_limit_reason = Some(reason);
+    }
+
+    /// TS `markAccountCoolingDown(account, cooldownMs, reason)` —
+    /// `coolingDownUntil = now + max(0, floor(ms))`.
+    pub fn mark_cooling_down(&mut self, cooldown_ms: i64, reason: CooldownReason) {
+        let ms = cooldown_ms.max(0);
+        self.meta.cooling_down_until = Some(now_ms() + ms);
+        self.meta.cooldown_reason = Some(reason);
+    }
+
+    /// TS `isAccountCoolingDown(account)` — false when no cooldown is set;
+    /// SELF-CLEARS an expired cooldown as a side effect (spec gotcha 12;
+    /// `recordSuccess` healing must observe the metadata BEFORE calling
+    /// this).
+    pub fn is_cooling_down(&mut self) -> bool {
+        let Some(until) = self.meta.cooling_down_until else {
+            return false;
+        };
+        if now_ms() >= until {
+            self.clear_cooldown();
+            return false;
+        }
+        true
+    }
+
+    /// TS `clearAccountCooldown(account)` — removes BOTH fields (TS
+    /// `delete`, not `= undefined` — matters for `hadCooldownMetadata`
+    /// checks and JSON output, spec gotcha 13).
+    pub fn clear_cooldown(&mut self) {
+        self.meta.cooling_down_until = None;
+        self.meta.cooldown_reason = None;
+    }
+
+    /// TS `toAuthDetails(account)` — `{type: "oauth", access: access ?? "",
+    /// refresh, expires: expires ?? 0}`.
+    pub fn to_auth_details(&self) -> OAuthAuthDetails {
+        OAuthAuthDetails {
+            access: self.meta.access_token.clone().unwrap_or_default(),
+            refresh: self.meta.refresh_token.clone(),
+            expires: self.meta.expires_at.unwrap_or(0),
+        }
+    }
+}
+
+// ===========================================================================
+// AccountManager — persistence half
+// ===========================================================================
+
+impl AccountManager {
+    /// TS-named index-based wrapper over
+    /// [`ManagedAccount::mark_rate_limited`]. Returns `false` when the
+    /// index is out of range.
+    pub fn mark_rate_limited(
+        &mut self,
+        account_index: i64,
+        retry_after_ms: i64,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> bool {
+        self.mark_rate_limited_with_reason(
+            account_index,
+            retry_after_ms,
+            family,
+            RateLimitReason::Unknown,
+            model,
+        )
+    }
+
+    /// TS-named index-based wrapper over
+    /// [`ManagedAccount::mark_rate_limited_with_reason`].
+    pub fn mark_rate_limited_with_reason(
+        &mut self,
+        account_index: i64,
+        retry_after_ms: i64,
+        family: ModelFamily,
+        reason: RateLimitReason,
+        model: Option<&str>,
+    ) -> bool {
+        let Some(account) = self.get_account_by_index_mut(account_index) else {
+            return false;
+        };
+        account.mark_rate_limited_with_reason(retry_after_ms, family, reason, model);
+        true
+    }
+
+    /// TS-named index-based wrapper over
+    /// [`ManagedAccount::mark_cooling_down`].
+    pub fn mark_account_cooling_down(
+        &mut self,
+        account_index: i64,
+        cooldown_ms: i64,
+        reason: CooldownReason,
+    ) -> bool {
+        let Some(account) = self.get_account_by_index_mut(account_index) else {
+            return false;
+        };
+        account.mark_cooling_down(cooldown_ms, reason);
+        true
+    }
+
+    /// TS-named index-based wrapper over
+    /// [`ManagedAccount::is_cooling_down`] (mutating lazy expiry).
+    pub fn is_account_cooling_down(&mut self, account_index: i64) -> bool {
+        match self.get_account_by_index_mut(account_index) {
+            Some(account) => account.is_cooling_down(),
+            None => false,
+        }
+    }
+
+    /// TS-named index-based wrapper over
+    /// [`ManagedAccount::clear_cooldown`].
+    pub fn clear_account_cooldown(&mut self, account_index: i64) -> bool {
+        let Some(account) = self.get_account_by_index_mut(account_index) else {
+            return false;
+        };
+        account.clear_cooldown();
+        true
+    }
+
+    /// TS `clearAccountTransientState()` — in-memory half (issue #606):
+    /// wipe active cooldowns, ALL rate-limit reset windows (including
+    /// still-future ones) and the runtime `lastRateLimitReason` on every
+    /// account. Returns `true` when the pool was non-empty, i.e. when the
+    /// caller should schedule the debounced persist
+    /// ([`SharedAccountManager::clear_account_transient_state`] does both;
+    /// callers needing durability must
+    /// [`SharedAccountManager::flush_pending_save`]).
+    pub fn clear_account_transient_state(&mut self) -> bool {
+        if self.accounts.is_empty() {
+            return false;
+        }
+        for account in self.accounts.iter_mut() {
+            account.clear_cooldown();
+            clear_all_rate_limits(account);
+            account.runtime.last_rate_limit_reason = None;
+        }
+        true
+    }
+
+    /// TS `syncCodexCliActiveSelectionForIndex(index)` — bounds-checked
+    /// mirror write of the given account into the official Codex CLI files
+    /// (result deliberately ignored, matching the TS `await` of a
+    /// best-effort writer).
+    pub async fn sync_codex_cli_active_selection_for_index(&self, index: i64) {
+        if index < 0 || index as usize >= self.accounts.len() {
+            return;
+        }
+        let Some(account) = self.accounts.get(index as usize) else {
+            return;
+        };
+        let selection = ActiveSelection {
+            account_id: account.meta.account_id.clone(),
+            email: account.meta.email.clone(),
+            access_token: account.meta.access_token.clone(),
+            refresh_token: Some(account.meta.refresh_token.clone()),
+            expires_at: account.meta.expires_at.map(|expires| expires as f64),
+            id_token: None,
+        };
+        let _ = set_codex_cli_active_selection(&selection).await;
+    }
+
+    /// TS `buildStorageSnapshot()` — THE ONLY manager → [`AccountStorageV3`]
+    /// bridge (ARCHITECTURE §8.4).
+    ///
+    /// 1. `activeIndexByFamily[f] = clamp(current pointer, ≥0)` for every
+    ///    family (a `-1` pointer serializes as `0` — spec gotcha 15);
+    ///    `activeIndex` = the codex family value.
+    /// 2. Pin/gen race protection (#474): re-read pin+gen from disk and
+    ///    adopt via [`resolve_effective_pin_and_gen`]; cache the refreshed
+    ///    values back onto the instance. (The Rust disk reader never fails —
+    ///    it returns `{None, 0}` on any problem, which the strictly-greater
+    ///    rule treats exactly like the TS catch-and-keep-memory branch.)
+    /// 3. Serialize accounts in pool order with the EXACT allow-listed field
+    ///    mapping: `enabled` is `false` or omitted (never `true` on disk),
+    ///    empty `rateLimitResetTimes` is omitted, runtime-only fields are
+    ///    never copied.
+    /// 4. `pinnedAccountIndex` only when defined; `affinityGeneration` only
+    ///    when `> 0`.
+    pub fn build_storage_snapshot(&mut self) -> AccountStorageV3 {
+        let mut by_family = ActiveIndexByFamily::default();
+        for family in MODEL_FAMILIES {
+            let raw = self.current_account_index_by_family.get(family);
+            by_family.set(family, Some(raw.max(0)));
+        }
+        let active_index = by_family.get(ModelFamily::Codex).unwrap_or(0);
+
+        let on_disk = read_pin_and_gen_from_disk(get_storage_path());
+        let (effective_pin, effective_gen) = resolve_effective_pin_and_gen(
+            self.pinned_account_index,
+            self.affinity_generation,
+            on_disk,
+            self.accounts.len(),
+        );
+        self.pinned_account_index = effective_pin;
+        self.affinity_generation = effective_gen;
+
+        let mut snapshot = AccountStorageV3::empty();
+        snapshot.accounts = self
+            .accounts
+            .iter()
+            .map(managed_account_to_metadata)
+            .collect();
+        snapshot.active_index = active_index;
+        snapshot.active_index_by_family = Some(by_family);
+        snapshot.pinned_account_index = effective_pin;
+        snapshot.affinity_generation = if effective_gen > 0 {
+            Some(effective_gen)
+        } else {
+            None
+        };
+        snapshot
+    }
+
+    /// TS `saveToDisk()` — re-enter the storage-path state captured at
+    /// construction (a project-scoped manager keeps writing to its
+    /// project-scoped file), then, under the account-storage transaction
+    /// (cross-process lock + load-current + atomic persist), snapshot the
+    /// live pool and reconcile against the just-loaded disk state so a
+    /// routine save cannot clobber a token another process rotated (H3).
+    pub async fn save_to_disk(&mut self) -> Result<(), CodexError> {
+        let path_state = self.storage_path_state.clone();
+        let this: &mut AccountManager = self;
+        run_with_storage_path_state(path_state, async move {
+            with_account_storage_transaction(move |current, persist| async move {
+                let mut snapshot = this.build_storage_snapshot();
+                reconcile_tokens_from_disk(&mut snapshot, current.as_ref());
+                persist.persist(&snapshot).await
+            })
+            .await
+        })
+        .await
+    }
+
+}
+
+/// The `buildStorageSnapshot` per-account field mapping (spec §1.6 step 3):
+/// clone the persisted `meta` shape, then apply the on-disk omission rules.
+/// Runtime-only state lives in `account.runtime` and is structurally
+/// excluded.
+fn managed_account_to_metadata(account: &ManagedAccount) -> AccountMetadataV3 {
+    let mut meta = account.meta.clone();
+    // Never `Some(true)` on disk — enabled accounts omit the field
+    // (spec gotcha 3).
+    meta.enabled = if account.meta.enabled == Some(false) {
+        Some(false)
+    } else {
+        None
+    };
+    // The live windows are the DIRECT `rate_limit_reset_times` field (the
+    // `meta` slot is dormant in memory); empty maps are omitted on disk
+    // (spec gotcha 4).
+    meta.rate_limit_reset_times = if account.rate_limit_reset_times.is_empty() {
+        None
+    } else {
+        Some(account.rate_limit_reset_times.clone())
+    };
+    meta
+}
+
+// ===========================================================================
+// SharedAccountManager — debounced save + flush (TS saveToDiskDebounced /
+// flushPendingSave / clearAccountTransientState scheduling). The debounce
+// bookkeeping lives HERE, beside the pool mutex — `AccountManager` itself
+// carries no timer state (manager.rs defers the TS debounce surface to
+// this wrapper).
+// ===========================================================================
+
+/// Completion latch for one in-flight save (TS `pendingSave` promise). The
+/// failure message is stored so `flush_pending_save` can re-surface it,
+/// mirroring TS awaiting the same rejected promise.
+struct PendingSave {
+    done: AtomicBool,
+    notify: tokio::sync::Notify,
+    error: StdMutex<Option<String>>,
+}
+
+impl PendingSave {
+    fn new() -> Self {
+        Self {
+            done: AtomicBool::new(false),
+            notify: tokio::sync::Notify::new(),
+            error: StdMutex::new(None),
+        }
+    }
+
+    async fn wait(&self) {
+        loop {
+            if self.done.load(Ordering::Acquire) {
+                return;
+            }
+            let notified = self.notify.notified();
+            tokio::pin!(notified);
+            notified.as_mut().enable();
+            // Close the race between the check and registering.
+            if self.done.load(Ordering::Acquire) {
+                return;
+            }
+            notified.await;
+        }
+    }
+
+    fn complete(&self, error: Option<String>) {
+        *self.error.lock().expect("pending-save error poisoned") = error;
+        self.done.store(true, Ordering::Release);
+        self.notify.notify_waiters();
+    }
+
+    fn error_message(&self) -> Option<String> {
+        self.error
+            .lock()
+            .expect("pending-save error poisoned")
+            .clone()
+    }
+}
+
+/// TS `saveDebounceTimer` + `pendingSave` bookkeeping.
+#[derive(Default)]
+struct DebounceState {
+    /// Bumped on every schedule/cancel; a sleeping timer task only fires
+    /// while its generation is still the armed one (TS `clearTimeout`
+    /// equivalence).
+    generation: u64,
+    /// `Some(gen)` while a timer for `gen` is armed
+    /// (⇔ TS `saveDebounceTimer !== null`).
+    armed: Option<u64>,
+    /// The in-flight save latch (⇔ TS `pendingSave !== null`).
+    pending: Option<Arc<PendingSave>>,
+}
+
+/// Shared handle around an [`AccountManager`] providing the TS debounced
+/// persistence surface. Runtime layers (manager cache, proxy pipeline) hold
+/// the pool through this handle.
+#[derive(Clone)]
+pub struct SharedAccountManager {
+    manager: Arc<tokio::sync::Mutex<AccountManager>>,
+    debounce: Arc<StdMutex<DebounceState>>,
+}
+
+impl SharedAccountManager {
+    pub fn new(manager: AccountManager) -> Self {
+        Self::from_arc(Arc::new(tokio::sync::Mutex::new(manager)))
+    }
+
+    pub fn from_arc(manager: Arc<tokio::sync::Mutex<AccountManager>>) -> Self {
+        Self {
+            manager,
+            debounce: Arc::new(StdMutex::new(DebounceState::default())),
+        }
+    }
+
+    /// The underlying pool mutex (for direct method access).
+    pub fn manager(&self) -> &Arc<tokio::sync::Mutex<AccountManager>> {
+        &self.manager
+    }
+
+    pub async fn lock(&self) -> tokio::sync::MutexGuard<'_, AccountManager> {
+        self.manager.lock().await
+    }
+
+    /// TS `saveToDiskDebounced(delayMs = 500)` — trailing-edge debounce
+    /// with single-flight coalescing: every call re-arms the timer (the
+    /// LAST call's delay governs); when it fires, the worker first awaits
+    /// any in-flight save, then runs `saveToDisk`, logging (never
+    /// propagating) failures. Synchronous like the TS method; must be
+    /// called from within a tokio runtime.
+    pub fn save_to_disk_debounced(&self, delay_ms: u64) {
+        let my_generation = {
+            let mut state = self.debounce.lock().expect("debounce state poisoned");
+            state.generation = state.generation.wrapping_add(1);
+            state.armed = Some(state.generation);
+            state.generation
+        };
+        let manager = Arc::downgrade(&self.manager);
+        let debounce = Arc::downgrade(&self.debounce);
+        tokio::spawn(async move {
+            cma_core::utils::sleep(delay_ms).await;
+            run_debounced_save(manager, debounce, my_generation).await;
+        });
+    }
+
+    /// TS `flushPendingSave()` — cancel a pending timer and save
+    /// immediately (propagating that save's error), then await any
+    /// in-flight background save (re-surfacing its stored failure message).
+    pub async fn flush_pending_save(&self) -> Result<(), CodexError> {
+        let had_timer = {
+            let mut state = self.debounce.lock().expect("debounce state poisoned");
+            if state.armed.is_some() {
+                // Cancel the sleeping timer task (generation supersession).
+                state.armed = None;
+                state.generation = state.generation.wrapping_add(1);
+                true
+            } else {
+                false
+            }
+        };
+        if had_timer {
+            save_to_disk_shared(&self.manager).await?;
+        }
+        let pending = {
+            self.debounce
+                .lock()
+                .expect("debounce state poisoned")
+                .pending
+                .clone()
+        };
+        if let Some(pending) = pending {
+            pending.wait().await;
+            if let Some(message) = pending.error_message() {
+                return Err(CodexError::new(message));
+            }
+        }
+        Ok(())
+    }
+
+    /// TS `clearAccountTransientState()` — full-fidelity variant: immediate
+    /// in-memory clear (that is what unblocks the live pool), then a
+    /// debounced persist of the cleared pool. No-op on an empty pool.
+    pub async fn clear_account_transient_state(&self) {
+        let should_save = {
+            let mut manager = self.manager.lock().await;
+            manager.clear_account_transient_state()
+        };
+        if should_save {
+            self.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        }
+    }
+
+    /// TS `recordSuccess(account, family, model?)` — full-fidelity variant:
+    /// run the tracker/healing half ([`AccountManager::record_success`]) and,
+    /// when cooldown/auth-failure healing occurred, schedule the debounced
+    /// persist (the TS method's `saveToDiskDebounced()` call). Same
+    /// plain-method/shared-wrapper split as `clear_account_transient_state`.
+    pub async fn record_success(&self, index: i64, family: ModelFamily, model: Option<&str>) {
+        let healed = {
+            let mut manager = self.manager.lock().await;
+            manager.record_success(index, family, model)
+        };
+        if healed {
+            self.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        }
+    }
+}
+
+/// `saveToDisk` over a shared handle: identical pipeline to
+/// [`AccountManager::save_to_disk`], but the manager lock is held only
+/// while snapshotting — the pool stays usable during the file IO, matching
+/// the TS event-loop interleaving.
+pub async fn save_to_disk_shared(
+    manager: &Arc<tokio::sync::Mutex<AccountManager>>,
+) -> Result<(), CodexError> {
+    let path_state = {
+        let manager = manager.lock().await;
+        manager.storage_path_state.clone()
+    };
+    run_with_storage_path_state(path_state, async move {
+        with_account_storage_transaction(move |current, persist| async move {
+            let mut snapshot = {
+                let mut manager = manager.lock().await;
+                manager.build_storage_snapshot()
+            };
+            reconcile_tokens_from_disk(&mut snapshot, current.as_ref());
+            persist.persist(&snapshot).await
+        })
+        .await
+    })
+    .await
+}
+
+/// The timer body of the debounced save (TS `doSave`).
+async fn run_debounced_save(
+    manager: Weak<tokio::sync::Mutex<AccountManager>>,
+    debounce: Weak<StdMutex<DebounceState>>,
+    my_generation: u64,
+) {
+    let Some(debounce) = debounce.upgrade() else {
+        return;
+    };
+    let Some(manager) = manager.upgrade() else {
+        return;
+    };
+    // Claim the fired timer; abort when superseded (a newer schedule) or
+    // flushed (TS clearTimeout). Install our latch as the new pendingSave.
+    let (previous, mine) = {
+        let mut state = debounce.lock().expect("debounce state poisoned");
+        if state.armed != Some(my_generation) {
+            return;
+        }
+        state.armed = None;
+        let previous = state.pending.take();
+        let mine = Arc::new(PendingSave::new());
+        state.pending = Some(Arc::clone(&mine));
+        (previous, mine)
+    };
+    // TS: `if (this.pendingSave) await this.pendingSave;` — single-flight
+    // ordering. Never while holding any lock.
+    if let Some(previous) = previous {
+        previous.wait().await;
+    }
+    let result = save_to_disk_shared(&manager).await;
+    let error_message = match result {
+        Ok(()) => None,
+        Err(error) => {
+            let message = error.message().to_string();
+            create_logger("accounts").warn(
+                "Debounced save failed",
+                Some(&json!({ "error": message })),
+            );
+            Some(message)
+        }
+    };
+    mine.complete(error_message);
+    // TS `.finally(() => { this.pendingSave = null; })` — clear the slot
+    // only if it is still ours.
+    let mut state = debounce.lock().expect("debounce state poisoned");
+    if let Some(pending) = &state.pending
+        && Arc::ptr_eq(pending, &mine)
+    {
+        state.pending = None;
+    }
+}
+
+// ===========================================================================
+// Module-level formatters (TS exports of lib/accounts.ts)
+// ===========================================================================
+
+/// Field access needed by [`format_account_label`] /
+/// [`format_workspace_lines`]. Implemented for [`ManagedAccount`] and
+/// [`AccountMetadataV3`] so both live-pool and storage rows format
+/// identically.
+pub trait AccountLabelSource {
+    fn label_email(&self) -> Option<&str>;
+    fn label_account_id(&self) -> Option<&str>;
+    fn label_account_label(&self) -> Option<&str>;
+    fn label_workspaces(&self) -> Option<&[Workspace]>;
+    fn label_current_workspace_index(&self) -> Option<i64>;
+}
+
+impl AccountLabelSource for AccountMetadataV3 {
+    fn label_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn label_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn label_account_label(&self) -> Option<&str> {
+        self.account_label.as_deref()
+    }
+    fn label_workspaces(&self) -> Option<&[Workspace]> {
+        self.workspaces.as_deref()
+    }
+    fn label_current_workspace_index(&self) -> Option<i64> {
+        self.current_workspace_index
+    }
+}
+
+impl AccountLabelSource for ManagedAccount {
+    fn label_email(&self) -> Option<&str> {
+        self.meta.email.as_deref()
+    }
+    fn label_account_id(&self) -> Option<&str> {
+        self.meta.account_id.as_deref()
+    }
+    fn label_account_label(&self) -> Option<&str> {
+        self.meta.account_label.as_deref()
+    }
+    fn label_workspaces(&self) -> Option<&[Workspace]> {
+        self.meta.workspaces.as_deref()
+    }
+    fn label_current_workspace_index(&self) -> Option<i64> {
+        self.meta.current_workspace_index
+    }
+}
+
+/// JS `id.slice(-6)` (whole id when ≤ 6 chars).
+fn last_six_chars(value: &str) -> &str {
+    let count = value.chars().count();
+    if count <= 6 {
+        return value;
+    }
+    let (idx, _) = value.char_indices().nth(count - 6).expect("count > 6");
+    &value[idx..]
+}
+
+/// TS private `activeWorkspaceName(account)` — the active workspace's
+/// trimmed name (`currentWorkspaceIndex ?? 0`, out-of-range falls back to
+/// the first workspace), `None` when empty/untracked.
+fn active_workspace_name(account: &dyn AccountLabelSource) -> Option<String> {
+    let workspaces = account.label_workspaces()?;
+    if workspaces.is_empty() {
+        return None;
+    }
+    let idx = account.label_current_workspace_index().unwrap_or(0);
+    let workspace = usize::try_from(idx)
+        .ok()
+        .and_then(|idx| workspaces.get(idx))
+        .or_else(|| workspaces.first())?;
+    let name = workspace.name.as_deref()?.trim();
+    if name.is_empty() {
+        None
+    } else {
+        Some(name.to_string())
+    }
+}
+
+/// TS `formatAccountLabel(account, index)` — 1-based display label.
+/// Segments in order: manual `accountLabel`; `[workspaceName]` (skipped
+/// when it repeats the label — #491); `email`; accountId 6-char suffix
+/// (`id:<suffix>` when other segments precede, bare otherwise). No
+/// segments → `"Account N"`.
+pub fn format_account_label(account: Option<&dyn AccountLabelSource>, index: usize) -> String {
+    let account_label = account
+        .and_then(|a| a.label_account_label())
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+    let workspace_name = account.and_then(active_workspace_name);
+    let email = account
+        .and_then(|a| a.label_email())
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+    let account_id = account
+        .and_then(|a| a.label_account_id())
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+    let id_suffix = account_id.map(last_six_chars);
+
+    let mut segments: Vec<String> = Vec::new();
+    if let Some(label) = account_label {
+        segments.push(label.to_string());
+    }
+    if let Some(workspace_name) = &workspace_name
+        && account_label != Some(workspace_name.as_str())
+    {
+        segments.push(format!("[{workspace_name}]"));
+    }
+    if let Some(email) = email {
+        segments.push(email.to_string());
+    }
+    if let Some(suffix) = id_suffix {
+        if segments.is_empty() {
+            segments.push(suffix.to_string());
+        } else {
+            segments.push(format!("id:{suffix}"));
+        }
+    }
+
+    if segments.is_empty() {
+        format!("Account {}", index + 1)
+    } else {
+        format!("Account {} ({})", index + 1, segments.join(", "))
+    }
+}
+
+/// Default indent of TS `formatWorkspaceLines`.
+pub const WORKSPACE_LINE_DEFAULT_INDENT: &str = "   ";
+
+/// TS `formatWorkspaceLines(account, indent = "   ")` — one display line
+/// per tracked workspace, the active one marked with `*` (issue #491).
+pub fn format_workspace_lines(
+    account: Option<&dyn AccountLabelSource>,
+    indent: &str,
+) -> Vec<String> {
+    let Some(workspaces) = account.and_then(|a| a.label_workspaces()) else {
+        return Vec::new();
+    };
+    if workspaces.is_empty() {
+        return Vec::new();
+    }
+    let active_index = account
+        .and_then(|a| a.label_current_workspace_index())
+        .unwrap_or(0);
+    workspaces
+        .iter()
+        .enumerate()
+        .map(|(idx, workspace)| {
+            let is_active = idx as i64 == active_index;
+            let name = workspace
+                .name
+                .as_deref()
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .unwrap_or("(unnamed)");
+            let id = workspace.id.trim();
+            let id_suffix = last_six_chars(id);
+            let mut tags: Vec<&str> = Vec::new();
+            if is_active {
+                tags.push("active");
+            }
+            if !workspace.enabled {
+                tags.push("disabled");
+            }
+            let tag_label = if tags.is_empty() {
+                String::new()
+            } else {
+                format!(" ({})", tags.join(", "))
+            };
+            let id_label = if id_suffix.is_empty() {
+                String::new()
+            } else {
+                format!(" id:{id_suffix}")
+            };
+            format!(
+                "{indent}{} {}. [{name}]{id_label}{tag_label}",
+                if is_active { "*" } else { "-" },
+                idx + 1,
+            )
+        })
+        .collect()
+}
+
+/// TS `formatCooldown(account, now = nowMs())` — `None` when not cooling
+/// down or already expired; otherwise `"<wait>"` or `"<wait> (<reason>)"`
+/// (`formatWaitTime` floors — spec gotcha 31).
+pub fn format_cooldown(
+    cooling_down_until: Option<i64>,
+    cooldown_reason: Option<&str>,
+    now: i64,
+) -> Option<String> {
+    let until = cooling_down_until?;
+    let remaining = until - now;
+    if remaining <= 0 {
+        return None;
+    }
+    let wait = format_wait_time(remaining);
+    Some(match cooldown_reason {
+        Some(reason) => format!("{wait} ({reason})"),
+        None => wait,
+    })
+}
+
+// ===========================================================================
+// Tests (ported from test/accounts.test.ts persistence/snapshot suites)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::manager::RuntimeAccountState;
+    use cma_storage::facade::set_storage_path;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn metadata(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        refresh: &str,
+        access: Option<&str>,
+        expires_at: Option<i64>,
+    ) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh.to_string(), 1, 0);
+        account.account_id = account_id.map(str::to_string);
+        account.email = email.map(str::to_string);
+        account.access_token = access.map(str::to_string);
+        account.expires_at = expires_at;
+        account
+    }
+
+    fn storage_with(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage
+    }
+
+    fn managed(refresh: &str) -> ManagedAccount {
+        ManagedAccount {
+            index: 0,
+            rate_limit_reset_times: RateLimitStateV3::new(),
+            meta: AccountMetadataV3::new(refresh.to_string(), 1, 0),
+            runtime: RuntimeAccountState::default(),
+        }
+    }
+
+    // ---- apply_rate_limit_with_reason (markRateLimitedWithReason suite) ----
+
+    #[test]
+    fn marks_rate_limited_with_quota_reason_on_base_key() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        assert_eq!(times.get("codex"), Some(61_000));
+    }
+
+    #[test]
+    fn h1_clamps_absurd_retry_after_to_seven_days() {
+        let now = 1_775_000_000_000_i64;
+        let mut times = RateLimitStateV3::new();
+        // Hostile/buggy upstream: ~31 years in ms.
+        apply_rate_limit_with_reason(
+            &mut times,
+            now,
+            999_999_999_999,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        let seven_days_ms = 7 * 24 * 60 * 60 * 1000;
+        assert_eq!(MAX_RATE_LIMIT_DELAY_MS, seven_days_ms);
+        assert_eq!(times.get("codex"), Some(now + seven_days_ms));
+    }
+
+    #[test]
+    fn negative_retry_after_clamps_to_zero() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            5_000,
+            -60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        assert_eq!(times.get("codex"), Some(5_000));
+    }
+
+    #[test]
+    fn scopes_token_rate_limits_to_the_model_specific_key() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Tokens,
+            Some("gpt-5.2"),
+        );
+        assert_eq!(times.get("codex"), None);
+        assert_eq!(times.get("codex:gpt-5.2"), Some(61_000));
+    }
+
+    #[test]
+    fn concurrent_with_model_writes_model_key_only() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            30_000,
+            ModelFamily::Gpt5_2,
+            RateLimitReason::Concurrent,
+            Some("gpt-5.2-pro"),
+        );
+        assert_eq!(times.get("gpt-5.2"), None);
+        assert_eq!(times.get("gpt-5.2:gpt-5.2-pro"), Some(31_000));
+    }
+
+    #[test]
+    fn unknown_with_model_writes_both_keys() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Unknown,
+            Some("gpt-5.2"),
+        );
+        assert_eq!(times.get("codex"), Some(61_000));
+        assert_eq!(times.get("codex:gpt-5.2"), Some(61_000));
+    }
+
+    #[test]
+    fn quota_with_model_writes_base_key_only() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            Some("gpt-5.2"),
+        );
+        assert_eq!(times.get("codex"), Some(61_000));
+        assert_eq!(times.get("codex:gpt-5.2"), None);
+    }
+
+    #[test]
+    fn empty_model_string_counts_as_no_model() {
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            1_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Tokens,
+            Some(""),
+        );
+        // JS falsiness: `!model` → base-key branch; model branch skipped.
+        assert_eq!(times.get("codex"), Some(61_000));
+        assert_eq!(times.len(), 1);
+    }
+
+    #[test]
+    fn does_not_shorten_an_existing_reset_when_later_window_is_smaller() {
+        let start = 1_775_000_000_000_i64;
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            start,
+            90 * 60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        let expected_reset_at = start + 90 * 60_000;
+        // 30 minutes later a SHORTER window arrives — max-merge keeps the
+        // original.
+        apply_rate_limit_with_reason(
+            &mut times,
+            start + 30 * 60_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        assert_eq!(times.get("codex"), Some(expected_reset_at));
+    }
+
+    #[test]
+    fn does_not_shorten_an_existing_model_scoped_reset() {
+        let start = 1_775_000_000_000_i64;
+        let mut times = RateLimitStateV3::new();
+        apply_rate_limit_with_reason(
+            &mut times,
+            start,
+            90 * 60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Tokens,
+            Some("gpt-5.2"),
+        );
+        let expected_reset_at = start + 90 * 60_000;
+        apply_rate_limit_with_reason(
+            &mut times,
+            start + 30 * 60_000,
+            60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Tokens,
+            Some("gpt-5.2"),
+        );
+        assert_eq!(times.get("codex:gpt-5.2"), Some(expected_reset_at));
+    }
+
+    // ---- ManagedAccount marking / cooldown / toAuthDetails ----
+
+    #[test]
+    fn managed_account_marking_records_runtime_reason_and_map() {
+        let mut account = managed("token-1");
+        account.mark_rate_limited_with_reason(60_000, ModelFamily::Codex, RateLimitReason::Quota, None);
+        assert_eq!(
+            account.runtime.last_rate_limit_reason,
+            Some(RateLimitReason::Quota)
+        );
+        assert!(account.rate_limit_reset_times.get("codex").is_some());
+        // The meta slot stays dormant — only the snapshot builder fills it.
+        assert!(account.meta.rate_limit_reset_times.is_none());
+    }
+
+    #[test]
+    fn cooldown_marking_and_lazy_expiry() {
+        let mut account = managed("token-1");
+        account.mark_cooling_down(30_000, CooldownReason::AuthFailure);
+        assert!(account.is_cooling_down());
+        assert_eq!(
+            account.meta.cooldown_reason,
+            Some(CooldownReason::AuthFailure)
+        );
+        // Manual clear removes both fields.
+        account.clear_cooldown();
+        assert!(!account.is_cooling_down());
+        assert_eq!(account.meta.cooldown_reason, None);
+        // Expired cooldowns self-clear on inspection (gotcha 12).
+        account.meta.cooling_down_until = Some(now_ms() - 1_000);
+        account.meta.cooldown_reason = Some(CooldownReason::NetworkError);
+        assert!(!account.is_cooling_down());
+        assert_eq!(account.meta.cooling_down_until, None);
+        assert_eq!(account.meta.cooldown_reason, None);
+        // Negative cooldown clamps to 0 → immediately expired.
+        account.mark_cooling_down(-5_000, CooldownReason::ServerError);
+        assert!(!account.is_cooling_down());
+    }
+
+    #[test]
+    fn to_auth_details_defaults_missing_access_and_expiry() {
+        let mut account = managed("refresh-1");
+        assert_eq!(
+            account.to_auth_details(),
+            OAuthAuthDetails {
+                access: String::new(),
+                refresh: "refresh-1".to_string(),
+                expires: 0,
+            }
+        );
+        account.meta.access_token = Some("access-1".to_string());
+        account.meta.expires_at = Some(42);
+        assert_eq!(
+            account.to_auth_details(),
+            OAuthAuthDetails {
+                access: "access-1".to_string(),
+                refresh: "refresh-1".to_string(),
+                expires: 42,
+            }
+        );
+    }
+
+    #[test]
+    fn clear_account_transient_state_wipes_every_account() {
+        let storage = storage_with(vec![
+            metadata(Some("a1"), None, "token-1", None, None),
+            metadata(Some("a2"), None, "token-2", None, None),
+        ]);
+        let mut manager = AccountManager::new(None, Some(&storage));
+        manager.mark_account_cooling_down(0, 60_000, CooldownReason::RateLimit);
+        manager.mark_rate_limited_with_reason(
+            0,
+            90 * 60_000,
+            ModelFamily::Codex,
+            RateLimitReason::Quota,
+            None,
+        );
+        manager.mark_rate_limited_with_reason(
+            1,
+            90 * 60_000,
+            ModelFamily::Gpt5_2,
+            RateLimitReason::Tokens,
+            Some("gpt-5.2-pro"),
+        );
+
+        assert!(manager.clear_account_transient_state());
+
+        for index in 0..2 {
+            let account = manager.get_account_by_index(index).unwrap();
+            assert_eq!(account.meta.cooling_down_until, None);
+            assert_eq!(account.meta.cooldown_reason, None);
+            assert!(account.rate_limit_reset_times.is_empty());
+            assert_eq!(account.runtime.last_rate_limit_reason, None);
+        }
+    }
+
+    #[test]
+    fn clear_account_transient_state_is_a_noop_on_empty_pool() {
+        let mut manager = AccountManager::new(None, None);
+        assert!(!manager.clear_account_transient_state());
+    }
+
+    // ---- resolve_effective_pin_and_gen (#474) ----
+
+    #[test]
+    fn adopts_disk_pin_only_when_disk_generation_strictly_greater() {
+        // Strictly greater → adopt both.
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                Some(1),
+                2,
+                PinAndGen {
+                    pinned_account_index: Some(0),
+                    affinity_generation: 3
+                },
+                4,
+            ),
+            (Some(0), 3),
+        );
+        // Equal → keep memory pin.
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                Some(1),
+                3,
+                PinAndGen {
+                    pinned_account_index: Some(0),
+                    affinity_generation: 3
+                },
+                4,
+            ),
+            (Some(1), 3),
+        );
+        // Disk-read failure shape ({None, 0}) → keep memory values.
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                Some(2),
+                5,
+                PinAndGen {
+                    pinned_account_index: None,
+                    affinity_generation: 0
+                },
+                4,
+            ),
+            (Some(2), 5),
+        );
+    }
+
+    #[test]
+    fn validates_effective_pin_against_live_account_count() {
+        // Adopted disk pin out of range → cleared (gen still adopted).
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                None,
+                0,
+                PinAndGen {
+                    pinned_account_index: Some(7),
+                    affinity_generation: 2
+                },
+                3,
+            ),
+            (None, 2),
+        );
+        // Memory pin invalidated by a shrunken pool.
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                Some(3),
+                1,
+                PinAndGen {
+                    pinned_account_index: None,
+                    affinity_generation: 0
+                },
+                3,
+            ),
+            (None, 1),
+        );
+        // Disk gen strictly greater with an UNSET disk pin clears the pin
+        // (pin+gen are one atomic CLI write).
+        assert_eq!(
+            resolve_effective_pin_and_gen(
+                Some(1),
+                1,
+                PinAndGen {
+                    pinned_account_index: None,
+                    affinity_generation: 2
+                },
+                3,
+            ),
+            (None, 2),
+        );
+    }
+
+    // ---- reconcile_tokens_from_disk (H3) ----
+
+    #[test]
+    fn adopts_strictly_newer_disk_tokens() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            Some("a@example.com"),
+            "mem-refresh",
+            Some("mem-access"),
+            Some(1_000),
+        )]);
+        let disk = storage_with(vec![metadata(
+            Some("acc1"),
+            Some("a@example.com"),
+            "disk-refresh",
+            Some("disk-access"),
+            Some(2_000),
+        )]);
+        reconcile_tokens_from_disk(&mut snapshot, Some(&disk));
+        let account = &snapshot.accounts[0];
+        assert_eq!(account.refresh_token, "disk-refresh");
+        assert_eq!(account.access_token.as_deref(), Some("disk-access"));
+        assert_eq!(account.expires_at, Some(2_000));
+    }
+
+    #[test]
+    fn equal_expiries_keep_the_memory_copy() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "mem-refresh",
+            Some("mem-access"),
+            Some(2_000),
+        )]);
+        let disk = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "disk-refresh",
+            Some("disk-access"),
+            Some(2_000),
+        )]);
+        reconcile_tokens_from_disk(&mut snapshot, Some(&disk));
+        assert_eq!(snapshot.accounts[0].refresh_token, "mem-refresh");
+        assert_eq!(
+            snapshot.accounts[0].access_token.as_deref(),
+            Some("mem-access")
+        );
+    }
+
+    #[test]
+    fn newer_memory_copy_wins_our_own_refresh() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "mem-refresh",
+            Some("mem-access"),
+            Some(3_000),
+        )]);
+        let disk = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "disk-refresh",
+            Some("disk-access"),
+            Some(2_000),
+        )]);
+        reconcile_tokens_from_disk(&mut snapshot, Some(&disk));
+        assert_eq!(snapshot.accounts[0].refresh_token, "mem-refresh");
+    }
+
+    #[test]
+    fn newer_disk_row_without_refresh_token_is_ignored() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "mem-refresh",
+            None,
+            Some(1_000),
+        )]);
+        // Zod forbids empty refresh tokens on load, but reconcile guards
+        // anyway (TS truthiness check on disk.refreshToken).
+        let mut disk_row = metadata(Some("acc1"), None, "x", Some("disk-access"), Some(9_000));
+        disk_row.refresh_token = String::new();
+        let disk = storage_with(vec![disk_row]);
+        reconcile_tokens_from_disk(&mut snapshot, Some(&disk));
+        assert_eq!(snapshot.accounts[0].refresh_token, "mem-refresh");
+        assert_eq!(snapshot.accounts[0].expires_at, Some(1_000));
+    }
+
+    #[test]
+    fn missing_current_storage_is_a_noop() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "mem-refresh",
+            None,
+            Some(1_000),
+        )]);
+        reconcile_tokens_from_disk(&mut snapshot, None);
+        assert_eq!(snapshot.accounts[0].refresh_token, "mem-refresh");
+    }
+
+    #[test]
+    fn non_matching_identities_are_untouched() {
+        let mut snapshot = storage_with(vec![metadata(
+            Some("acc1"),
+            None,
+            "mem-refresh",
+            None,
+            Some(1_000),
+        )]);
+        let disk = storage_with(vec![metadata(
+            Some("acc2"),
+            None,
+            "disk-refresh",
+            Some("disk-access"),
+            Some(9_000),
+        )]);
+        reconcile_tokens_from_disk(&mut snapshot, Some(&disk));
+        assert_eq!(snapshot.accounts[0].refresh_token, "mem-refresh");
+    }
+
+    // ---- build_storage_snapshot / save_to_disk (sandboxed) ----
+
+    #[test]
+    #[serial(env, storage_path_state)]
+    fn snapshot_clamps_pointers_and_applies_omission_rules() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        // Empty pool: -1 pointers serialize as 0 (gotcha 15).
+        let mut empty = AccountManager::new(None, None);
+        let snapshot = empty.build_storage_snapshot();
+        assert_eq!(snapshot.active_index, 0);
+        let by_family = snapshot.active_index_by_family.as_ref().unwrap();
+        for family in MODEL_FAMILIES {
+            assert_eq!(by_family.get(family), Some(0));
+        }
+        assert_eq!(snapshot.pinned_account_index, None);
+        assert_eq!(snapshot.affinity_generation, None);
+
+        // Enabled account: `enabled` and empty rateLimitResetTimes OMITTED.
+        let storage = storage_with(vec![metadata(Some("a1"), None, "token-1", None, None)]);
+        let mut manager = AccountManager::new(None, Some(&storage));
+        let snapshot = manager.build_storage_snapshot();
+        let row = serde_json::to_value(&snapshot.accounts[0]).unwrap();
+        let object = row.as_object().unwrap();
+        assert!(!object.contains_key("enabled"));
+        assert!(!object.contains_key("rateLimitResetTimes"));
+        assert!(!object.contains_key("coolingDownUntil"));
+        assert_eq!(object.get("refreshToken").unwrap(), "token-1");
+    }
+
+    #[test]
+    #[serial(env, storage_path_state)]
+    fn snapshot_adopts_disk_pin_when_disk_generation_is_newer() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let storage = storage_with(vec![metadata(Some("a1"), None, "token-1", None, None)]);
+        let mut manager = AccountManager::new(None, Some(&storage));
+
+        let path = std::path::PathBuf::from(get_storage_path());
+        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+        std::fs::write(&path, r#"{"pinnedAccountIndex":0,"affinityGeneration":5}"#).unwrap();
+
+        let snapshot = manager.build_storage_snapshot();
+        assert_eq!(snapshot.pinned_account_index, Some(0));
+        assert_eq!(snapshot.affinity_generation, Some(5));
+        // Refreshed values are cached back onto the instance: a second
+        // snapshot with the file gone keeps them.
+        std::fs::remove_file(&path).unwrap();
+        let snapshot = manager.build_storage_snapshot();
+        assert_eq!(snapshot.pinned_account_index, Some(0));
+        assert_eq!(snapshot.affinity_generation, Some(5));
+    }
+
+    #[tokio::test]
+    #[serial(env, storage_path_state)]
+    async fn save_to_disk_persists_the_pool_and_reconciles_disk_tokens() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let path = std::path::PathBuf::from(get_storage_path());
+        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+        // Another process rotated this token to a NEWER expiry.
+        std::fs::write(
+            &path,
+            concat!(
+                r#"{"version":3,"accounts":[{"accountId":"acc1","refreshToken":"disk-refresh","#,
+                r#""accessToken":"disk-access","expiresAt":9000,"addedAt":1,"lastUsed":0}],"activeIndex":0}"#,
+            ),
+        )
+        .unwrap();
+
+        let mut mem_row = metadata(Some("acc1"), None, "mem-refresh", Some("mem-access"), Some(100));
+        mem_row.rate_limit_reset_times = None;
+        let storage = storage_with(vec![mem_row]);
+        let mut manager = AccountManager::new(None, Some(&storage));
+        manager.save_to_disk().await.unwrap();
+
+        let written: serde_json::Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert_eq!(written["version"], 3);
+        // H3: the routine save must NOT clobber the newer disk token.
+        assert_eq!(written["accounts"][0]["refreshToken"], "disk-refresh");
+        assert_eq!(written["accounts"][0]["accessToken"], "disk-access");
+        assert_eq!(written["accounts"][0]["expiresAt"], 9000);
+    }
+
+    // ---- debounced save + flush ----
+
+    #[tokio::test]
+    #[serial(env, storage_path_state)]
+    async fn debounced_save_coalesces_and_only_the_last_timer_fires() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let storage = storage_with(vec![metadata(Some("a1"), None, "token-1", None, None)]);
+        let shared = SharedAccountManager::new(AccountManager::new(None, Some(&storage)));
+
+        shared.save_to_disk_debounced(50);
+        shared.save_to_disk_debounced(50);
+        shared.save_to_disk_debounced(50);
+        tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+        shared.flush_pending_save().await.unwrap();
+
+        let path = std::path::PathBuf::from(get_storage_path());
+        assert!(path.exists(), "debounced save must have fired");
+
+        // Prove the superseded timers never fire: remove the file and let
+        // any stale workers wake — none may re-create it.
+        std::fs::remove_file(&path).unwrap();
+        tokio::time::sleep(std::time::Duration::from_millis(300)).await;
+        assert!(!path.exists(), "superseded debounce timers must not save");
+    }
+
+    #[tokio::test]
+    #[serial(env, storage_path_state)]
+    async fn flush_pending_save_cancels_the_timer_and_saves_immediately() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let storage = storage_with(vec![metadata(Some("a1"), None, "token-1", None, None)]);
+        let shared = SharedAccountManager::new(AccountManager::new(None, Some(&storage)));
+
+        shared.save_to_disk_debounced(400);
+        // Flush long before the timer deadline: must save NOW.
+        shared.flush_pending_save().await.unwrap();
+        let path = std::path::PathBuf::from(get_storage_path());
+        assert!(path.exists(), "flush must save immediately");
+
+        // The cancelled worker must not fire later.
+        std::fs::remove_file(&path).unwrap();
+        tokio::time::sleep(std::time::Duration::from_millis(800)).await;
+        assert!(!path.exists(), "cancelled debounce timer must not save");
+    }
+
+    #[tokio::test]
+    #[serial(env, storage_path_state)]
+    async fn clear_account_transient_state_persists_the_cleared_pool() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let mut row = metadata(Some("a1"), None, "token-1", None, None);
+        row.cooling_down_until = Some(now_ms() + 3_600_000);
+        row.cooldown_reason = Some(CooldownReason::RateLimit);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", now_ms() + 3_600_000);
+        row.rate_limit_reset_times = Some(times);
+        let storage = storage_with(vec![row]);
+        let shared = SharedAccountManager::new(AccountManager::new(None, Some(&storage)));
+
+        shared.clear_account_transient_state().await;
+        shared.flush_pending_save().await.unwrap();
+
+        let path = std::path::PathBuf::from(get_storage_path());
+        let written: serde_json::Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let account = &written["accounts"][0];
+        assert_eq!(account.get("coolingDownUntil"), None);
+        assert_eq!(account.get("cooldownReason"), None);
+        assert_eq!(account.get("rateLimitResetTimes"), None);
+    }
+
+    #[tokio::test]
+    #[serial(env, storage_path_state, volatile)]
+    async fn record_success_persists_cooldown_healing_via_debounced_save() {
+        let _sandbox = EnvSandbox::new();
+        set_storage_path(None);
+        let mut row = metadata(Some("a1"), None, "token-1", None, None);
+        // EXPIRED cooldown: metadata still present, but the account is no
+        // longer cooling down — recordSuccess must heal (clear both fields)
+        // and schedule the debounced persist (TS `saveToDiskDebounced()`).
+        row.cooling_down_until = Some(now_ms() - 1_000);
+        row.cooldown_reason = Some(CooldownReason::RateLimit);
+        let storage = storage_with(vec![row]);
+        let shared = SharedAccountManager::new(AccountManager::new(None, Some(&storage)));
+
+        shared.record_success(0, ModelFamily::Codex, None).await;
+        shared.flush_pending_save().await.unwrap();
+
+        let path = std::path::PathBuf::from(get_storage_path());
+        let written: serde_json::Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let account = &written["accounts"][0];
+        assert_eq!(account.get("coolingDownUntil"), None);
+        assert_eq!(account.get("cooldownReason"), None);
+    }
+
+    // ---- formatters ----
+
+    #[derive(Default)]
+    struct TestAccount {
+        email: Option<String>,
+        account_id: Option<String>,
+        account_label: Option<String>,
+        workspaces: Option<Vec<Workspace>>,
+        current_workspace_index: Option<i64>,
+    }
+
+    impl AccountLabelSource for TestAccount {
+        fn label_email(&self) -> Option<&str> {
+            self.email.as_deref()
+        }
+        fn label_account_id(&self) -> Option<&str> {
+            self.account_id.as_deref()
+        }
+        fn label_account_label(&self) -> Option<&str> {
+            self.account_label.as_deref()
+        }
+        fn label_workspaces(&self) -> Option<&[Workspace]> {
+            self.workspaces.as_deref()
+        }
+        fn label_current_workspace_index(&self) -> Option<i64> {
+            self.current_workspace_index
+        }
+    }
+
+    fn workspace(id: &str, name: Option<&str>, enabled: bool) -> Workspace {
+        Workspace {
+            id: id.to_string(),
+            name: name.map(str::to_string),
+            enabled,
+            disabled_at: None,
+            is_default: None,
+        }
+    }
+
+    #[test]
+    fn formats_account_label_preferring_email_and_id_suffix() {
+        let account = TestAccount {
+            email: Some("user@example.com".into()),
+            account_id: Some("abcdef123456".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&account), 0),
+            "Account 1 (user@example.com, id:123456)"
+        );
+        let email_only = TestAccount {
+            email: Some("user@example.com".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&email_only), 1),
+            "Account 2 (user@example.com)"
+        );
+        let id_only = TestAccount {
+            account_id: Some("abcdef123456".into()),
+            ..Default::default()
+        };
+        assert_eq!(format_account_label(Some(&id_only), 2), "Account 3 (123456)");
+        assert_eq!(format_account_label(None, 3), "Account 4");
+    }
+
+    #[test]
+    fn formats_account_label_with_account_label_variations() {
+        let label_only = TestAccount {
+            account_label: Some("Work".into()),
+            ..Default::default()
+        };
+        assert_eq!(format_account_label(Some(&label_only), 0), "Account 1 (Work)");
+        let label_email = TestAccount {
+            account_label: Some("Work".into()),
+            email: Some("work@co.com".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&label_email), 0),
+            "Account 1 (Work, work@co.com)"
+        );
+        let label_id = TestAccount {
+            account_label: Some("Work".into()),
+            account_id: Some("abcdef123456".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&label_id), 0),
+            "Account 1 (Work, id:123456)"
+        );
+        let all = TestAccount {
+            account_label: Some("Work".into()),
+            email: Some("work@co.com".into()),
+            account_id: Some("abcdef123456".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&all), 0),
+            "Account 1 (Work, work@co.com, id:123456)"
+        );
+    }
+
+    #[test]
+    fn formats_account_label_with_short_account_id() {
+        let short = TestAccount {
+            account_id: Some("abc".into()),
+            ..Default::default()
+        };
+        assert_eq!(format_account_label(Some(&short), 0), "Account 1 (abc)");
+        let exact = TestAccount {
+            account_id: Some("123456".into()),
+            ..Default::default()
+        };
+        assert_eq!(format_account_label(Some(&exact), 0), "Account 1 (123456)");
+    }
+
+    #[test]
+    fn surfaces_the_active_workspace_to_distinguish_same_email_accounts() {
+        let personal = TestAccount {
+            email: Some("user@gmail.com".into()),
+            account_id: Some("org-AAAA".into()),
+            workspaces: Some(vec![workspace("org-AAAA", Some("Personal Plus"), true)]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&personal), 0),
+            "Account 1 ([Personal Plus], user@gmail.com, id:g-AAAA)"
+        );
+        let business = TestAccount {
+            email: Some("user@gmail.com".into()),
+            account_id: Some("org-BBBB".into()),
+            workspaces: Some(vec![workspace("org-BBBB", Some("GkTech Business"), true)]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&business), 1),
+            "Account 2 ([GkTech Business], user@gmail.com, id:g-BBBB)"
+        );
+    }
+
+    #[test]
+    fn follows_current_workspace_index_when_picking_the_workspace_tag() {
+        let account = TestAccount {
+            email: Some("user@gmail.com".into()),
+            workspaces: Some(vec![
+                workspace("org-AAAA", Some("Personal Plus"), true),
+                workspace("org-BBBB", Some("GkTech Business"), true),
+            ]),
+            current_workspace_index: Some(1),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&account), 0),
+            "Account 1 ([GkTech Business], user@gmail.com)"
+        );
+    }
+
+    #[test]
+    fn omits_the_workspace_tag_when_it_duplicates_the_account_label() {
+        let account = TestAccount {
+            account_label: Some("Personal Plus".into()),
+            email: Some("user@gmail.com".into()),
+            workspaces: Some(vec![workspace("org-AAAA", Some("Personal Plus"), true)]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&account), 0),
+            "Account 1 (Personal Plus, user@gmail.com)"
+        );
+    }
+
+    #[test]
+    fn ignores_empty_or_unnamed_workspaces_in_the_label() {
+        let unnamed = TestAccount {
+            email: Some("user@gmail.com".into()),
+            workspaces: Some(vec![workspace("org-AAAA", None, true)]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&unnamed), 0),
+            "Account 1 (user@gmail.com)"
+        );
+        let empty = TestAccount {
+            email: Some("user@gmail.com".into()),
+            workspaces: Some(vec![]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_account_label(Some(&empty), 0),
+            "Account 1 (user@gmail.com)"
+        );
+    }
+
+    #[test]
+    fn lists_workspaces_with_the_active_one_marked() {
+        let account = TestAccount {
+            workspaces: Some(vec![
+                workspace("org-AAAA", Some("Personal Plus"), true),
+                workspace("org-BBBB", Some("GkTech Business"), true),
+            ]),
+            current_workspace_index: Some(1),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_workspace_lines(Some(&account), WORKSPACE_LINE_DEFAULT_INDENT),
+            vec![
+                "   - 1. [Personal Plus] id:g-AAAA",
+                "   * 2. [GkTech Business] id:g-BBBB (active)",
+            ]
+        );
+    }
+
+    #[test]
+    fn marks_disabled_workspaces_and_honors_a_custom_indent() {
+        let mut disabled = workspace("org-BBBB", None, false);
+        disabled.disabled_at = Some(1);
+        let account = TestAccount {
+            workspaces: Some(vec![
+                workspace("org-AAAA", Some("Personal Plus"), true),
+                disabled,
+            ]),
+            current_workspace_index: Some(0),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_workspace_lines(Some(&account), "  "),
+            vec![
+                "  * 1. [Personal Plus] id:g-AAAA (active)",
+                "  - 2. [(unnamed)] id:g-BBBB (disabled)",
+            ]
+        );
+    }
+
+    #[test]
+    fn returns_no_workspace_lines_when_none_are_tracked() {
+        assert!(format_workspace_lines(None, WORKSPACE_LINE_DEFAULT_INDENT).is_empty());
+        let no_field = TestAccount::default();
+        assert!(format_workspace_lines(Some(&no_field), WORKSPACE_LINE_DEFAULT_INDENT).is_empty());
+        let empty = TestAccount {
+            workspaces: Some(vec![]),
+            ..Default::default()
+        };
+        assert!(format_workspace_lines(Some(&empty), WORKSPACE_LINE_DEFAULT_INDENT).is_empty());
+    }
+
+    #[test]
+    fn format_cooldown_matches_ts_cases() {
+        let now = 1_775_000_000_000_i64;
+        assert_eq!(format_cooldown(None, None, now), None);
+        assert_eq!(format_cooldown(Some(now - 1_000), None, now), None);
+        assert_eq!(format_cooldown(Some(now), None, now), None);
+        assert_eq!(
+            format_cooldown(Some(now + 30_000), None, now),
+            Some("30s".to_string())
+        );
+        assert_eq!(
+            format_cooldown(Some(now + 60_000), Some("auth-failure"), now),
+            Some("1m 0s (auth-failure)".to_string())
+        );
+        assert_eq!(
+            format_cooldown(Some(now + 150_000), Some("network-error"), now),
+            Some("2m 30s (network-error)".to_string())
+        );
+    }
+}
diff --git a/crates/accounts/src/manager_selection.rs b/crates/accounts/src/manager_selection.rs
new file mode 100644
index 000000000..7aa283208
--- /dev/null
+++ b/crates/accounts/src/manager_selection.rs
@@ -0,0 +1,1740 @@
+//! Port of the SELECTION half of `lib/accounts.ts` (spec 03 §1.6):
+//! round-robin (`get_current_or_next_for_family` / `get_next_for_family`),
+//! sequential drain-first with policy block-sets (#509), hybrid delegation to
+//! `cma_rotation::selector`, availability checks (with MUTATING lazy expiry of
+//! rate limits), runtime skip reasons, and per-family minimum wait times.
+//!
+//! Extends `crate::manager::AccountManager` (state + core half live there;
+//! persistence half in `crate::manager_persistence`). Rate-limit primitives
+//! come from `crate::rate_limits` via the [`RateLimitedEntity`] trait that
+//! `ManagedAccount` implements.
+//!
+//! # Selection contracts (spec 03 gotchas 6–11)
+//!
+//! - `get_next_for_family` is IDENTICAL to `get_current_or_next_for_family`
+//!   except it does NOT commit `current_account_index_by_family` (peek-next).
+//!   Deliberate — do not merge the two (gotcha 7).
+//! - The sequential selector NEVER advances on every pick (#509): it sticks
+//!   to the active account while usable, and its recovery scan starts AT the
+//!   active index (not active+1) so a recovered earlier account reclaims the
+//!   slot on wrap-around. `blocked_indexes` (the request's policy block set)
+//!   is treated as unusable so the sticky pointer never anchors on a
+//!   policy-blocked account (#509 review P1).
+//! - Cursor lockstep (HI-02): every commit here sets
+//!   `cursor = (index + 1) % count`.
+//! - Availability checks MUTATE: expired rate-limit windows are deleted and
+//!   expired cooldowns self-clear during evaluation (gotchas 11/12). The
+//!   `&&`/`||` chains short-circuit exactly like the TS (`is_cooling_down` is
+//!   not consulted — and does not self-clear — when the account is already
+//!   rate-limited).
+//! - Hybrid selection delegates scoring to
+//!   `cma_rotation::selector::select_hybrid_account` and returns `None` when
+//!   nothing is available (AUDIT-H2/D-01).
+
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{CooldownReason, SwitchReason};
+use cma_core::utils::now_ms;
+use cma_rotation::circuit_breaker::get_circuit_breaker;
+use cma_rotation::routing_mutex::{SelectionRecord, with_routing_mutex};
+use cma_rotation::selector::{
+    AccountWithMetrics, HybridSelectionOptions, SelectHybridAccountParams, select_hybrid_account,
+};
+use cma_rotation::trackers::{DEFAULT_DRAIN_AMOUNT, get_health_tracker, get_token_tracker};
+use std::collections::HashSet;
+
+use crate::manager::{
+    AccountManager, FamilyStateMap, ManagedAccount, get_account_circuit_key,
+    get_runtime_tracker_key,
+};
+use crate::rate_limits::{self, RateLimitedEntity};
+
+/// Circuit availability for an account (pure read on the breaker; the key
+/// itself is the sticky cached circuit key from `crate::manager`).
+fn circuit_is_available(account: &mut ManagedAccount) -> bool {
+    get_circuit_breaker(&get_account_circuit_key(account), None).is_available()
+}
+
+/// The shared usable-account predicate of the round-robin selectors and the
+/// availability check: enabled → workspaces → (MUTATING) expired-window clear
+/// → not rate-limited && not cooling down && circuit available.
+fn account_selectable(
+    account: &mut ManagedAccount,
+    family: ModelFamily,
+    model: Option<&str>,
+) -> bool {
+    if !account.is_enabled() {
+        return false;
+    }
+    if !account.has_enabled_workspaces() {
+        return false;
+    }
+    rate_limits::clear_expired_rate_limits(account);
+    !rate_limits::is_rate_limited_for_family(account, family, model)
+        && !account.is_cooling_down()
+        && circuit_is_available(account)
+}
+
+/// The sequential selector's `isUsable` (#509): like [`account_selectable`]
+/// but with the policy block-set consulted between the enabled and workspace
+/// checks (TS order). Uses `account.index` — the ORIGINAL storage position —
+/// not the array slot (spec gotcha 14).
+fn sequential_usable(
+    account: &mut ManagedAccount,
+    family: ModelFamily,
+    model: Option<&str>,
+    blocked_indexes: Option<&HashSet<usize>>,
+) -> bool {
+    if !account.is_enabled() {
+        return false;
+    }
+    if let Some(blocked) = blocked_indexes
+        && blocked.contains(&account.index)
+    {
+        return false;
+    }
+    if !account.has_enabled_workspaces() {
+        return false;
+    }
+    rate_limits::clear_expired_rate_limits(account);
+    !rate_limits::is_rate_limited_for_family(account, family, model)
+        && !account.is_cooling_down()
+        && circuit_is_available(account)
+}
+
+/// Family-map access seams (TS `Record<ModelFamily, number>`): keep every
+/// read/write in this file behind these two helpers plus `FamilyStateMap::set`
+/// so a change to the manager's family-state representation touches only this
+/// spot.
+fn family_cursor(map: &FamilyStateMap, family: ModelFamily) -> i64 {
+    map.get(family)
+}
+
+fn family_active(map: &FamilyStateMap, family: ModelFamily) -> i64 {
+    map.get(family)
+}
+
+/// The TS quota-key expression `` model ? `${family}:${model}` : family ``
+/// used by every tracker interaction (an empty model string is FALSY in TS →
+/// base key).
+fn selection_quota_key(family: ModelFamily, model: Option<&str>) -> String {
+    match model {
+        Some(model) if !model.is_empty() => format!("{}:{model}", family.as_str()),
+        _ => family.as_str().to_string(),
+    }
+}
+
+/// Bounds-checked pool array slot for an `i64` index (the TS methods take the
+/// live account OBJECT; the Rust port addresses pool members by position,
+/// matching `get_account_by_index`).
+fn pool_slot(index: i64, count: usize) -> Option<usize> {
+    if index < 0 || index as usize >= count {
+        None
+    } else {
+        Some(index as usize)
+    }
+}
+
+/// Optional context threaded into [`AccountManager::mark_switched_locked`]
+/// (TS `{ trackerKeyQuota?: string; score?: number }`).
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct MarkSwitchedContext {
+    /// Quota tracker key (e.g. `"codex"` or `"codex:gpt-5-codex"`).
+    pub tracker_key_quota: Option<String>,
+    /// Final hybrid score used during selection.
+    pub score: Option<f64>,
+}
+
+impl AccountManager {
+    /// TS `isAccountAvailableForFamily` — `false` for missing/disabled/
+    /// workspace-less/rate-limited/cooling/circuit-open accounts. MUTATES:
+    /// clears expired rate-limit windows (spec gotcha 11).
+    pub fn is_account_available_for_family(
+        &mut self,
+        index: i64,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> bool {
+        if index < 0 || index as usize >= self.accounts.len() {
+            return false;
+        }
+        let account = &mut self.accounts[index as usize];
+        account_selectable(account, family, model)
+    }
+
+    /// TS `getAccountRuntimeSkipReason` — first of `"missing"`, `"disabled"`,
+    /// `"workspace-disabled"`, `"rate-limited"`,
+    /// `"cooling-down:<reason>"`/`"cooling-down"`, `"circuit-open"`, else
+    /// `None`. The strings are a de-facto contract with observability/UI
+    /// (spec 03 §13). Also mutates via the expired-window clear.
+    pub fn get_account_runtime_skip_reason(
+        &mut self,
+        index: i64,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> Option<String> {
+        if index < 0 || index as usize >= self.accounts.len() {
+            return Some("missing".to_string());
+        }
+        let account = &mut self.accounts[index as usize];
+        if !account.is_enabled() {
+            return Some("disabled".to_string());
+        }
+        if !account.has_enabled_workspaces() {
+            return Some("workspace-disabled".to_string());
+        }
+        rate_limits::clear_expired_rate_limits(account);
+        if rate_limits::is_rate_limited_for_family(account, family, model) {
+            return Some("rate-limited".to_string());
+        }
+        if account.is_cooling_down() {
+            return Some(match account.meta.cooldown_reason {
+                Some(reason) => format!("cooling-down:{}", reason.as_str()),
+                None => "cooling-down".to_string(),
+            });
+        }
+        if !circuit_is_available(account) {
+            return Some("circuit-open".to_string());
+        }
+        None
+    }
+
+    /// TS `getCurrentOrNext` = `getCurrentOrNextForFamily("codex")`.
+    pub fn get_current_or_next(&mut self) -> Option<&ManagedAccount> {
+        self.get_current_or_next_for_family(ModelFamily::Codex, None)
+    }
+
+    /// TS `getCurrentOrNextForFamily` — round-robin from the family cursor:
+    /// the first selectable account wins; on pick the cursor advances to
+    /// `idx+1`, the active pointer commits to `idx`, and `last_used` stamps.
+    pub fn get_current_or_next_for_family(
+        &mut self,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> Option<&ManagedAccount> {
+        let count = self.accounts.len();
+        if count == 0 {
+            return None;
+        }
+        let cursor = family_cursor(&self.cursor_by_family, family).rem_euclid(count as i64) as usize;
+        for i in 0..count {
+            let idx = (cursor + i) % count;
+            let account = &mut self.accounts[idx];
+            if !account_selectable(account, family, model) {
+                continue;
+            }
+            self.cursor_by_family.set(family, ((idx + 1) % count) as i64);
+            self.current_account_index_by_family.set(family, idx as i64);
+            self.accounts[idx].meta.last_used = now_ms();
+            return self.accounts.get(idx);
+        }
+        None
+    }
+
+    /// TS `getNextForFamily` — IDENTICAL loop to
+    /// [`Self::get_current_or_next_for_family`] except it does NOT update the
+    /// active pointer (only cursor + `last_used`). Deliberate: peek-next
+    /// without committing (spec gotcha 7).
+    pub fn get_next_for_family(
+        &mut self,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> Option<&ManagedAccount> {
+        let count = self.accounts.len();
+        if count == 0 {
+            return None;
+        }
+        let cursor = family_cursor(&self.cursor_by_family, family).rem_euclid(count as i64) as usize;
+        for i in 0..count {
+            let idx = (cursor + i) % count;
+            let account = &mut self.accounts[idx];
+            if !account_selectable(account, family, model) {
+                continue;
+            }
+            self.cursor_by_family.set(family, ((idx + 1) % count) as i64);
+            self.accounts[idx].meta.last_used = now_ms();
+            return self.accounts.get(idx);
+        }
+        None
+    }
+
+    /// TS `getCurrentOrNextForFamilySequential` — drain-first (#509).
+    ///
+    /// Sticky phase: while the family's active account is usable it is
+    /// returned WITHOUT moving cursor or pointer. Scan phase: only when the
+    /// active account is exhausted, scan forward FROM the active index
+    /// (wrapping) for the next usable account and pin it as the new active
+    /// account. `blocked_indexes` is the request's policy block set (paused /
+    /// drained / capability-blocked account indexes from
+    /// `RuntimePolicyDecision.blockedAccountIndexes`).
+    pub fn get_current_or_next_for_family_sequential(
+        &mut self,
+        family: ModelFamily,
+        model: Option<&str>,
+        blocked_indexes: Option<&HashSet<usize>>,
+    ) -> Option<&ManagedAccount> {
+        let count = self.accounts.len();
+        if count == 0 {
+            return None;
+        }
+
+        // Sticky: stay on the current active account while it is still usable
+        // so we drain it fully before moving on.
+        let active_index = family_active(&self.current_account_index_by_family, family);
+        if active_index >= 0 && (active_index as usize) < count {
+            let idx = active_index as usize;
+            let account = &mut self.accounts[idx];
+            if sequential_usable(account, family, model, blocked_indexes) {
+                account.meta.last_used = now_ms();
+                return self.accounts.get(idx);
+            }
+        }
+
+        // Active account is exhausted (or none set): scan forward from the
+        // active index, wrapping, and pin the first usable account. Starting
+        // AT the active index (not active+1) lets a recovered earlier account
+        // reclaim the active slot on wrap-around.
+        let start = if active_index >= 0 && (active_index as usize) < count {
+            active_index as usize
+        } else {
+            0
+        };
+        for i in 0..count {
+            let idx = (start + i) % count;
+            let account = &mut self.accounts[idx];
+            if !sequential_usable(account, family, model, blocked_indexes) {
+                continue;
+            }
+            self.current_account_index_by_family.set(family, idx as i64);
+            self.cursor_by_family.set(family, ((idx + 1) % count) as i64);
+            self.accounts[idx].meta.last_used = now_ms();
+            return self.accounts.get(idx);
+        }
+
+        None
+    }
+
+    /// TS `getCurrentOrNextForFamilyHybrid` — builds `AccountWithMetrics`
+    /// from ALL enabled/workspace-eligible accounts (unavailable ones are
+    /// included with `is_available: false`) and delegates the scoring to
+    /// `cma_rotation::selector::select_hybrid_account`.
+    pub fn get_current_or_next_for_family_hybrid(
+        &mut self,
+        family: ModelFamily,
+        model: Option<&str>,
+        options: Option<HybridSelectionOptions>,
+    ) -> Option<&ManagedAccount> {
+        let count = self.accounts.len();
+        if count == 0 {
+            return None;
+        }
+
+        let quota_key = selection_quota_key(family, model);
+        let health_tracker = get_health_tracker(None);
+        let token_tracker = get_token_tracker(None);
+
+        let mut accounts_with_metrics: Vec<AccountWithMetrics> = Vec::new();
+        for account in self.accounts.iter_mut() {
+            if !account.is_enabled() {
+                continue;
+            }
+            if !account.has_enabled_workspaces() {
+                continue;
+            }
+            rate_limits::clear_expired_rate_limits(account);
+            let is_available = !rate_limits::is_rate_limited_for_family(account, family, model)
+                && !account.is_cooling_down()
+                && circuit_is_available(account);
+            accounts_with_metrics.push(AccountWithMetrics {
+                index: account.index,
+                tracker_key: Some(get_runtime_tracker_key(account)),
+                is_available,
+                last_used: account.meta.last_used,
+            });
+        }
+
+        let selected = select_hybrid_account(SelectHybridAccountParams {
+            accounts: &accounts_with_metrics,
+            health_tracker,
+            token_tracker,
+            quota_key: Some(&quota_key),
+            config: Default::default(),
+            options: options.unwrap_or_default(),
+        })?;
+
+        // TS looks up `this.accounts[selected.index]` (the pool-index FIELD)
+        // and commits pointers from `account.index` — port verbatim.
+        let account = self.accounts.get_mut(selected.index)?;
+        let account_index = account.index;
+        account.meta.last_used = now_ms();
+        self.current_account_index_by_family
+            .set(family, account_index as i64);
+        self.cursor_by_family
+            .set(family, ((account_index + 1) % count) as i64);
+        self.accounts.get(selected.index)
+    }
+
+    /// TS `getMinWaitTime` = `getMinWaitTimeForFamily("codex")`.
+    pub fn get_min_wait_time(&mut self) -> i64 {
+        self.get_min_wait_time_for_family(ModelFamily::Codex, None)
+    }
+
+    /// TS `getMinWaitTimeForFamily` — `0` when any enabled account is
+    /// available (or when none are enabled); otherwise the minimum over
+    /// enabled accounts of each account's LAST blocker to clear
+    /// (max of base-window, model-window, cooldown remainder, breaker wait).
+    pub fn get_min_wait_time_for_family(
+        &mut self,
+        family: ModelFamily,
+        model: Option<&str>,
+    ) -> i64 {
+        let now = now_ms();
+
+        // Availability pass — evaluated for EVERY enabled account (the TS
+        // `.filter` runs the mutating predicate on each; no early exit).
+        let mut any_enabled = false;
+        let mut any_available = false;
+        for account in self.accounts.iter_mut() {
+            if !account.is_enabled() {
+                continue;
+            }
+            any_enabled = true;
+            rate_limits::clear_expired_rate_limits(account);
+            let available = !rate_limits::is_rate_limited_for_family(account, family, model)
+                && !account.is_cooling_down()
+                && circuit_is_available(account);
+            if available {
+                any_available = true;
+            }
+        }
+        if any_available {
+            return 0;
+        }
+        if !any_enabled {
+            return 0;
+        }
+
+        let base_key = rate_limits::get_quota_key(family, None);
+        let model_key = model.map(|model| rate_limits::get_quota_key(family, Some(model)));
+
+        let mut wait_times: Vec<i64> = Vec::new();
+        for account in self.accounts.iter_mut() {
+            if !account.is_enabled() {
+                continue;
+            }
+            let mut per_account_wait_times: Vec<i64> = Vec::new();
+            if let Some(base_reset_at) = account.rate_limit_reset_times().get(&base_key) {
+                per_account_wait_times.push((base_reset_at - now).max(0));
+            }
+            if let Some(model_key) = &model_key
+                && let Some(model_reset_at) = account.rate_limit_reset_times().get(model_key)
+            {
+                per_account_wait_times.push((model_reset_at - now).max(0));
+            }
+            if let Some(cooling_down_until) = account.meta.cooling_down_until {
+                per_account_wait_times.push((cooling_down_until - now).max(0));
+            }
+            let breaker_wait = get_circuit_breaker(&get_account_circuit_key(account), None)
+                .get_time_until_available();
+            if breaker_wait > 0 {
+                per_account_wait_times.push(breaker_wait);
+            }
+            if let Some(max_wait) = per_account_wait_times.iter().copied().max() {
+                wait_times.push(max_wait);
+            }
+        }
+
+        wait_times.into_iter().min().unwrap_or(0)
+    }
+}
+
+// ============================================================================
+// Tracker interactions + routing-mutex wrappers (TS recordSuccess /
+// recordRateLimit / recordFailure / consumeToken / refundToken /
+// markSwitched / markSwitchedLocked / markAccountCoolingDownLocked /
+// setActiveIndexLocked)
+// ============================================================================
+
+impl AccountManager {
+    /// TS `recordSuccess(account, family, model?)` — health `+1` under the
+    /// quota key, cooldown/auth-failure healing, circuit-breaker success.
+    ///
+    /// Healing (spec 03 §1.6): the pre-check metadata is captured BEFORE
+    /// `is_cooling_down` (which may itself lazily clear an expired cooldown);
+    /// only a NOT-currently-cooling account heals.
+    ///
+    /// Returns `true` when healing occurred. The TS method then called
+    /// `saveToDiskDebounced()`; in the Rust split the debounce surface lives
+    /// on `SharedAccountManager` (manager_persistence.rs), so callers holding
+    /// the shared handle schedule `save_to_disk_debounced(500)` when this
+    /// returns `true` — the same plain-method/shared-wrapper split already
+    /// used by `clear_account_transient_state`.
+    pub fn record_success(&mut self, index: i64, family: ModelFamily, model: Option<&str>) -> bool {
+        let Some(idx) = pool_slot(index, self.accounts.len()) else {
+            return false;
+        };
+        let quota_key = selection_quota_key(family, model);
+        let account = &mut self.accounts[idx];
+        get_health_tracker(None).record_success(get_runtime_tracker_key(account), Some(&quota_key));
+
+        let had_cooldown_metadata =
+            account.meta.cooling_down_until.is_some() || account.meta.cooldown_reason.is_some();
+        let had_auth_failures = account.runtime.consecutive_auth_failures.unwrap_or(0) > 0;
+        let is_cooling_down = account.is_cooling_down();
+        let mut healed = false;
+
+        if !is_cooling_down && had_cooldown_metadata {
+            account.clear_cooldown();
+            healed = true;
+        }
+        if !is_cooling_down && had_auth_failures {
+            account.clear_auth_failures();
+            healed = true;
+        }
+
+        get_circuit_breaker(&get_account_circuit_key(account), None).record_success();
+        healed
+    }
+
+    /// TS `recordRateLimit(account, family, model?)` — health `-10` and a
+    /// token-bucket drain under the quota key. No circuit interaction, no
+    /// persistence.
+    pub fn record_rate_limit(&mut self, index: i64, family: ModelFamily, model: Option<&str>) {
+        let Some(idx) = pool_slot(index, self.accounts.len()) else {
+            return;
+        };
+        let quota_key = selection_quota_key(family, model);
+        let tracker_key = get_runtime_tracker_key(&mut self.accounts[idx]);
+        get_health_tracker(None).record_rate_limit(tracker_key.clone(), Some(&quota_key));
+        get_token_tracker(None).drain(tracker_key, Some(&quota_key), DEFAULT_DRAIN_AMOUNT);
+    }
+
+    /// TS `recordFailure(account, family, model?)` — health `-20` under the
+    /// quota key plus a circuit-breaker failure.
+    pub fn record_failure(&mut self, index: i64, family: ModelFamily, model: Option<&str>) {
+        let Some(idx) = pool_slot(index, self.accounts.len()) else {
+            return;
+        };
+        let quota_key = selection_quota_key(family, model);
+        let account = &mut self.accounts[idx];
+        get_health_tracker(None).record_failure(get_runtime_tracker_key(account), Some(&quota_key));
+        get_circuit_breaker(&get_account_circuit_key(account), None).record_failure();
+    }
+
+    /// TS `consumeToken(account, family, model?)` — try-consume from the
+    /// per-process token bucket; when the account's circuit is OPEN
+    /// (`can_execute` errors) the token is refunded and the call reports
+    /// `false`. Token buckets are per-process and MUST NOT be persisted
+    /// (spec gotcha 2 / the 6.4.0 regression).
+    pub fn consume_token(&mut self, index: i64, family: ModelFamily, model: Option<&str>) -> bool {
+        let Some(idx) = pool_slot(index, self.accounts.len()) else {
+            return false;
+        };
+        let quota_key = selection_quota_key(family, model);
+        let (tracker_key, circuit_key) = {
+            let account = &mut self.accounts[idx];
+            (
+                get_runtime_tracker_key(account),
+                get_account_circuit_key(account),
+            )
+        };
+        let token_tracker = get_token_tracker(None);
+        if !token_tracker.try_consume(tracker_key.clone(), Some(&quota_key)) {
+            return false;
+        }
+        match get_circuit_breaker(&circuit_key, None).can_execute() {
+            Ok(_) => true,
+            Err(_) => {
+                token_tracker.refund_token(tracker_key, Some(&quota_key));
+                false
+            }
+        }
+    }
+
+    /// TS `refundToken(account, family, model?)` — refund a token consumed
+    /// within the refund window. For network errors, not rate limits.
+    /// Returns `true` when a valid in-window consumption was refunded.
+    pub fn refund_token(&mut self, index: i64, family: ModelFamily, model: Option<&str>) -> bool {
+        let Some(idx) = pool_slot(index, self.accounts.len()) else {
+            return false;
+        };
+        let quota_key = selection_quota_key(family, model);
+        let tracker_key = get_runtime_tracker_key(&mut self.accounts[idx]);
+        get_token_tracker(None).refund_token(tracker_key, Some(&quota_key))
+    }
+
+    /// TS `markSwitched(account, reason, family)` — stamp
+    /// `lastSwitchReason`, commit the family's active pointer to
+    /// `account.index` and (HI-02) keep the cursor in lockstep at
+    /// `(account.index + 1) % count` so round-robin resumes AFTER the
+    /// just-switched account. Returns `false` for an out-of-range index.
+    pub fn mark_switched(&mut self, index: i64, reason: SwitchReason, family: ModelFamily) -> bool {
+        let count = self.accounts.len();
+        let Some(idx) = pool_slot(index, count) else {
+            return false;
+        };
+        let account = &mut self.accounts[idx];
+        account.meta.last_switch_reason = Some(reason);
+        let account_index = account.index;
+        self.current_account_index_by_family
+            .set(family, account_index as i64);
+        if count > 0 {
+            self.cursor_by_family
+                .set(family, ((account_index + 1) % count) as i64);
+        }
+        true
+    }
+
+    /// TS `markSwitchedLocked(account, reason, family, context?)` — the
+    /// mutex-serialized variant of [`Self::mark_switched`] (PR-N / R4).
+    /// Serialized through the shared routing mutex when the pool's mode is
+    /// `enabled`; `legacy` runs inline. Returns a [`SelectionRecord`]
+    /// describing the decision (`None` only for an out-of-range index, which
+    /// the TS could not express).
+    pub async fn mark_switched_locked(
+        &mut self,
+        index: i64,
+        reason: SwitchReason,
+        family: ModelFamily,
+        context: Option<MarkSwitchedContext>,
+    ) -> Option<SelectionRecord> {
+        let mode = self.routing_mutex_mode;
+        let this = &mut *self;
+        with_routing_mutex(mode, move || async move {
+            let count = this.accounts.len();
+            let idx = pool_slot(index, count)?;
+            let account = &mut this.accounts[idx];
+            account.meta.last_switch_reason = Some(reason);
+            let account_index = account.index;
+            this.current_account_index_by_family
+                .set(family, account_index as i64);
+            // HI-02: cursor lockstep, matching the legacy `mark_switched`.
+            if count > 0 {
+                this.cursor_by_family
+                    .set(family, ((account_index + 1) % count) as i64);
+            }
+            let tracker_key = get_runtime_tracker_key(&mut this.accounts[idx]);
+            let account = &this.accounts[idx];
+            let account_id = account
+                .meta
+                .account_id
+                .clone()
+                .or_else(|| account.meta.email.clone())
+                .unwrap_or_else(|| tracker_key.normalized());
+            let tracker_key_quota = context
+                .as_ref()
+                .and_then(|context| context.tracker_key_quota.clone());
+            let health =
+                get_health_tracker(None).get_score(tracker_key.clone(), tracker_key_quota.as_deref());
+            let tokens =
+                get_token_tracker(None).get_tokens(tracker_key, tracker_key_quota.as_deref());
+            Some(SelectionRecord {
+                account_index,
+                account_id,
+                reason,
+                timestamp: now_ms(),
+                tracker_key_quota,
+                health: Some(health),
+                tokens: Some(tokens),
+                score: context.and_then(|context| context.score),
+            })
+        })
+        .await
+    }
+
+    /// TS `markAccountCoolingDownLocked(account, cooldownMs, reason)` — the
+    /// mutex-serialized variant of `mark_account_cooling_down` (PR-N / R4).
+    /// Returns `false` for an out-of-range index.
+    pub async fn mark_account_cooling_down_locked(
+        &mut self,
+        index: i64,
+        cooldown_ms: i64,
+        reason: CooldownReason,
+    ) -> bool {
+        let mode = self.routing_mutex_mode;
+        let this = &mut *self;
+        with_routing_mutex(mode, move || async move {
+            let Some(idx) = pool_slot(index, this.accounts.len()) else {
+                return false;
+            };
+            this.accounts[idx].mark_cooling_down(cooldown_ms, reason);
+            true
+        })
+        .await
+    }
+
+    /// TS `setActiveIndexLocked(index)` — the mutex-serialized variant of
+    /// `set_active_index` (PR-N / R4). Returns the newly active account on
+    /// success, or `None` when the index is out of range / disabled
+    /// (matching the sync semantics).
+    pub async fn set_active_index_locked(&mut self, index: i64) -> Option<&ManagedAccount> {
+        let mode = self.routing_mutex_mode;
+        let selected = {
+            let this = &mut *self;
+            with_routing_mutex(mode, move || async move {
+                this.set_active_index(index).is_some()
+            })
+            .await
+        };
+        if selected {
+            self.accounts.get(index as usize)
+        } else {
+            None
+        }
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/accounts.test.ts (selection + availability +
+// min-wait + #509 sequential suites). All tests touch the process-global
+// tracker/circuit singletons → #[serial].
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::MODEL_FAMILIES;
+    use cma_core::schemas::account_storage::{
+        AccountMetadataV3, AccountStorageV3, CooldownReason, RateLimitStateV3, Workspace,
+    };
+    use cma_rotation::circuit_breaker::clear_circuit_breakers;
+    use cma_rotation::trackers::reset_trackers;
+    use serial_test::serial;
+
+    fn stored_account(refresh: &str, now: i64) -> AccountMetadataV3 {
+        AccountMetadataV3::new(refresh, now, now)
+    }
+
+    fn storage_with(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage
+    }
+
+    fn manager_from(accounts: Vec<AccountMetadataV3>) -> AccountManager {
+        AccountManager::new(None, Some(&storage_with(accounts)))
+    }
+
+    fn rate_limits_map(entries: &[(&str, i64)]) -> RateLimitStateV3 {
+        let mut map = RateLimitStateV3::new();
+        for (key, value) in entries {
+            map.insert(*key, *value);
+        }
+        map
+    }
+
+    fn reset_globals() {
+        reset_trackers();
+        clear_circuit_breakers();
+    }
+
+    fn active(manager: &AccountManager, family: ModelFamily) -> i64 {
+        family_active(&manager.current_account_index_by_family, family)
+    }
+
+    fn cursor(manager: &AccountManager, family: ModelFamily) -> i64 {
+        family_cursor(&manager.cursor_by_family, family)
+    }
+
+    #[test]
+    #[serial]
+    fn checks_account_availability_by_enabled_rate_limit_cooldown_state() {
+        reset_globals();
+        let now = now_ms();
+        let mut disabled = stored_account("token-1", now);
+        disabled.enabled = Some(false);
+        let mut rate_limited = stored_account("token-2", now);
+        rate_limited.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now + 60_000)]));
+        let mut cooling = stored_account("token-3", now);
+        cooling.cooling_down_until = Some(now + 60_000);
+        cooling.cooldown_reason = Some(CooldownReason::NetworkError);
+        let free = stored_account("token-4", now);
+
+        let mut manager = manager_from(vec![disabled, rate_limited, cooling, free]);
+
+        assert!(!manager.is_account_available_for_family(0, ModelFamily::Codex, None));
+        assert!(!manager.is_account_available_for_family(1, ModelFamily::Codex, None));
+        assert!(!manager.is_account_available_for_family(2, ModelFamily::Codex, None));
+        assert!(manager.is_account_available_for_family(3, ModelFamily::Codex, None));
+    }
+
+    #[test]
+    #[serial]
+    fn skip_reasons_match_the_contract_strings() {
+        reset_globals();
+        let now = now_ms();
+        let mut disabled = stored_account("skip-1", now);
+        disabled.enabled = Some(false);
+        let mut rate_limited = stored_account("skip-2", now);
+        rate_limited.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now + 60_000)]));
+        let mut cooling = stored_account("skip-3", now);
+        cooling.cooling_down_until = Some(now + 60_000);
+        cooling.cooldown_reason = Some(CooldownReason::AuthFailure);
+        let mut workspace_disabled = stored_account("skip-4", now);
+        workspace_disabled.workspaces = Some(vec![Workspace {
+            id: "ws-1".to_string(),
+            name: None,
+            enabled: false,
+            disabled_at: None,
+            is_default: None,
+        }]);
+        let free = stored_account("skip-5", now);
+
+        let mut manager =
+            manager_from(vec![disabled, rate_limited, cooling, workspace_disabled, free]);
+
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(-1, ModelFamily::Codex, None),
+            Some("missing".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(99, ModelFamily::Codex, None),
+            Some("missing".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(0, ModelFamily::Codex, None),
+            Some("disabled".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(1, ModelFamily::Codex, None),
+            Some("rate-limited".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(2, ModelFamily::Codex, None),
+            Some("cooling-down:auth-failure".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(3, ModelFamily::Codex, None),
+            Some("workspace-disabled".to_string())
+        );
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(4, ModelFamily::Codex, None),
+            None
+        );
+
+        // circuit-open: trip the free account's breaker (3 failures).
+        let key = get_account_circuit_key(&mut manager.accounts[4]);
+        let breaker = get_circuit_breaker(&key, None);
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.record_failure();
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(4, ModelFamily::Codex, None),
+            Some("circuit-open".to_string())
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn treats_accounts_with_all_tracked_workspaces_disabled_as_unavailable() {
+        reset_globals();
+        let now = now_ms();
+        let mut workspace_disabled = stored_account("token-workspace-disabled", now);
+        workspace_disabled.workspaces = Some(vec![
+            Workspace {
+                id: "workspace-1".to_string(),
+                name: Some("Workspace 1".to_string()),
+                enabled: false,
+                disabled_at: None,
+                is_default: None,
+            },
+            Workspace {
+                id: "workspace-2".to_string(),
+                name: Some("Workspace 2".to_string()),
+                enabled: false,
+                disabled_at: None,
+                is_default: None,
+            },
+        ]);
+        workspace_disabled.current_workspace_index = Some(0);
+        let mut ready = stored_account("token-ready", now);
+        ready.last_used = now - 10_000;
+
+        let mut manager = manager_from(vec![workspace_disabled, ready]);
+
+        assert!(!manager.is_account_available_for_family(0, ModelFamily::Codex, None));
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family(ModelFamily::Codex, None)
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-ready")
+        );
+        assert_eq!(
+            manager
+                .get_next_for_family(ModelFamily::Codex, None)
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-ready")
+        );
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_hybrid(ModelFamily::Codex, None, None)
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-ready")
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn keeps_workspace_less_legacy_accounts_eligible_for_selection() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("token-legacy", now)]);
+
+        assert!(manager.accounts[0].has_enabled_workspaces());
+        assert!(manager.is_account_available_for_family(0, ModelFamily::Codex, None));
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family(ModelFamily::Codex, None)
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-legacy")
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn returns_false_for_invalid_account_index_in_availability_checks() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("token-1", now)]);
+        assert!(!manager.is_account_available_for_family(-1, ModelFamily::Codex, None));
+        assert!(!manager.is_account_available_for_family(99, ModelFamily::Codex, None));
+    }
+
+    #[test]
+    #[serial]
+    fn clears_expired_rate_limit_windows_before_availability_check() {
+        reset_globals();
+        let now = now_ms();
+        let mut expired = stored_account("token-1", now);
+        expired.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now - 1_000)]));
+        let mut manager = manager_from(vec![expired]);
+
+        assert!(manager.is_account_available_for_family(0, ModelFamily::Codex, None));
+        // MUTATING lazy expiry: the expired key is gone from the live map.
+        assert_eq!(manager.accounts[0].rate_limit_reset_times().get("codex"), None);
+    }
+
+    #[test]
+    #[serial]
+    fn rotates_when_the_active_account_is_rate_limited() {
+        reset_globals();
+        let now = now_ms();
+        let mut limited = stored_account("token-1", now);
+        limited.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now + 60_000)]));
+        let mut manager = manager_from(vec![limited, stored_account("token-2", now)]);
+
+        assert_eq!(
+            manager
+                .get_current_or_next()
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-2")
+        );
+        assert_eq!(manager.get_min_wait_time(), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn skips_accounts_that_are_cooling_down() {
+        reset_globals();
+        let now = now_ms();
+        let mut cooling = stored_account("token-1", now);
+        cooling.cooling_down_until = Some(now + 60_000);
+        cooling.cooldown_reason = Some(CooldownReason::AuthFailure);
+        let mut manager = manager_from(vec![cooling, stored_account("token-2", now)]);
+
+        assert_eq!(
+            manager
+                .get_current_or_next()
+                .map(|account| account.meta.refresh_token.as_str()),
+            Some("token-2")
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+    }
+
+    #[test]
+    #[serial]
+    fn returns_min_wait_time_when_all_accounts_are_blocked() {
+        reset_globals();
+        let now = now_ms();
+        let mut cooling = stored_account("token-1", now);
+        cooling.cooling_down_until = Some(now + 60_000);
+        cooling.cooldown_reason = Some(CooldownReason::NetworkError);
+        let mut limited = stored_account("token-2", now);
+        limited.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now + 120_000)]));
+        let mut manager = manager_from(vec![cooling, limited]);
+
+        let wait_ms = manager.get_min_wait_time();
+        assert!(wait_ms > 0);
+        assert!(wait_ms <= 60_000);
+    }
+
+    #[test]
+    #[serial]
+    fn min_wait_is_zero_when_no_accounts_are_enabled() {
+        reset_globals();
+        let now = now_ms();
+        let mut disabled = stored_account("token-1", now);
+        disabled.enabled = Some(false);
+        let mut manager = manager_from(vec![disabled]);
+        assert_eq!(manager.get_min_wait_time(), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn min_wait_uses_the_last_blocker_per_account_and_min_across_accounts() {
+        reset_globals();
+        let now = now_ms();
+        // One account, blocked by BOTH a base window (30s) and a model window
+        // (90s): the account waits for its LAST blocker (90s).
+        let mut both = stored_account("token-both", now);
+        both.rate_limit_reset_times = Some(rate_limits_map(&[
+            ("codex", now + 30_000),
+            ("codex:m1", now + 90_000),
+        ]));
+        let mut manager = manager_from(vec![both]);
+        let wait = manager.get_min_wait_time_for_family(ModelFamily::Codex, Some("m1"));
+        assert!(wait > 60_000, "expected ~90s wait, got {wait}");
+        assert!(wait <= 90_000);
+    }
+
+    #[test]
+    #[serial]
+    fn performs_true_round_robin_rotation_across_multiple_requests() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+            stored_account("token-3", now),
+        ]);
+
+        let picks: Vec<String> = (0..4)
+            .map(|_| {
+                manager
+                    .get_current_or_next()
+                    .map(|account| account.meta.refresh_token.clone())
+                    .unwrap()
+            })
+            .collect();
+        assert_eq!(picks, vec!["token-1", "token-2", "token-3", "token-1"]);
+    }
+
+    #[test]
+    #[serial]
+    fn skips_rate_limited_accounts_during_rotation() {
+        reset_globals();
+        let now = now_ms();
+        let mut limited = stored_account("token-2", now);
+        limited.rate_limit_reset_times = Some(rate_limits_map(&[("codex", now + 60_000)]));
+        let mut manager = manager_from(vec![
+            stored_account("token-1", now),
+            limited,
+            stored_account("token-3", now),
+        ]);
+
+        let picks: Vec<String> = (0..3)
+            .map(|_| {
+                manager
+                    .get_current_or_next()
+                    .map(|account| account.meta.refresh_token.clone())
+                    .unwrap()
+            })
+            .collect();
+        assert_eq!(picks, vec!["token-1", "token-3", "token-1"]);
+    }
+
+    #[test]
+    #[serial]
+    fn uses_independent_cursors_per_model_family() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+        ]);
+
+        let codex_first = manager
+            .get_current_or_next_for_family(ModelFamily::Codex, None)
+            .map(|account| account.meta.refresh_token.clone());
+        let gpt51_first = manager
+            .get_current_or_next_for_family(ModelFamily::Gpt5_1, None)
+            .map(|account| account.meta.refresh_token.clone());
+        let codex_second = manager
+            .get_current_or_next_for_family(ModelFamily::Codex, None)
+            .map(|account| account.meta.refresh_token.clone());
+        let gpt51_second = manager
+            .get_current_or_next_for_family(ModelFamily::Gpt5_1, None)
+            .map(|account| account.meta.refresh_token.clone());
+
+        assert_eq!(codex_first.as_deref(), Some("token-1"));
+        assert_eq!(gpt51_first.as_deref(), Some("token-1"));
+        assert_eq!(codex_second.as_deref(), Some("token-2"));
+        assert_eq!(gpt51_second.as_deref(), Some("token-2"));
+    }
+
+    #[test]
+    #[serial]
+    fn get_next_for_family_does_not_commit_the_active_pointer() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+        ]);
+        // Constructor pointer init: both cursor and active start at 0.
+        let first = manager
+            .get_next_for_family(ModelFamily::Codex, None)
+            .map(|account| account.meta.refresh_token.clone());
+        assert_eq!(first.as_deref(), Some("token-1"));
+        // Cursor advanced, active pointer untouched (gotcha 7).
+        assert_eq!(cursor(&manager, ModelFamily::Codex), 1);
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+
+        let second = manager
+            .get_next_for_family(ModelFamily::Codex, None)
+            .map(|account| account.meta.refresh_token.clone());
+        assert_eq!(second.as_deref(), Some("token-2"));
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn hybrid_selection_prefers_the_healthier_candidate_over_the_active_index() {
+        reset_globals();
+        let now = now_ms();
+        let mut stale = stored_account("token-1", now);
+        stale.last_used = 0; // very stale → high freshness score
+        let mut fresh = stored_account("token-2", now);
+        fresh.last_used = now; // just used → low freshness score
+        let mut storage = storage_with(vec![stale, fresh]);
+        storage.active_index = 1;
+        let mut manager = AccountManager::new(None, Some(&storage));
+
+        let selected =
+            manager.get_current_or_next_for_family_hybrid(ModelFamily::Codex, None, None);
+        let selected = selected.expect("hybrid must select an available account");
+        assert_eq!(selected.meta.refresh_token, "token-1");
+        assert_eq!(selected.index, 0);
+    }
+
+    #[test]
+    #[serial]
+    fn hybrid_returns_none_when_pool_is_empty() {
+        reset_globals();
+        let mut manager = AccountManager::new(None, Some(&AccountStorageV3::empty()));
+        assert!(
+            manager
+                .get_current_or_next_for_family_hybrid(ModelFamily::Codex, None, None)
+                .is_none()
+        );
+    }
+
+    // ------------------------------------------------------------------
+    // getCurrentOrNextForFamilySequential (issue #509 drain-first)
+    // ------------------------------------------------------------------
+
+    fn sequential_pool(count: usize) -> AccountManager {
+        let now = now_ms();
+        let accounts = (0..count)
+            .map(|i| {
+                let mut account = stored_account(&format!("token-{i}"), now);
+                account.last_used = now - (i as i64) * 1_000;
+                account
+            })
+            .collect();
+        // activeIndexByFamily.codex = 0 in the TS fixture; the plain
+        // activeIndex 0 default produces the same pointer init.
+        manager_from(accounts)
+    }
+
+    fn rate_limit_account(manager: &mut AccountManager, idx: usize, now: i64) {
+        manager.accounts[idx]
+            .rate_limit_reset_times_mut()
+            .insert("codex", now + 60_000);
+    }
+
+    #[test]
+    #[serial]
+    fn sticks_to_the_active_account_across_calls_while_it_stays_available() {
+        reset_globals();
+        let mut manager = sequential_pool(2);
+
+        for _ in 0..3 {
+            let picked = manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index);
+            assert_eq!(picked, Some(0));
+        }
+        // Pointer never advanced while draining the active account.
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn advances_to_the_next_account_only_once_the_active_one_is_exhausted() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+
+        // Drain account 0 (rate-limited): selector must move to account 1.
+        rate_limit_account(&mut manager, 0, now);
+
+        let after_drain = manager
+            .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+            .map(|account| (account.index, account.meta.refresh_token.clone()));
+        assert_eq!(after_drain, Some((1, "token-1".to_string())));
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+
+        // And it now sticks to account 1.
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn wraps_back_to_a_recovered_earlier_account_when_the_current_one_drains() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+
+        // A drains -> switch to B.
+        rate_limit_account(&mut manager, 0, now);
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+
+        // A's quota window recovers; B then drains.
+        manager.accounts[0].rate_limit_reset_times_mut().clear();
+        rate_limit_account(&mut manager, 1, now);
+
+        // Sequential wraps forward from B (index 1) and reclaims recovered A.
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn returns_none_when_every_account_is_exhausted() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+        rate_limit_account(&mut manager, 0, now);
+        rate_limit_account(&mut manager, 1, now);
+
+        assert!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .is_none()
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn advances_when_the_active_account_is_cooling_down_then_reclaims_on_recovery() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+
+        // Cooldown is a non-rate-limit exhaustion path: must advance.
+        manager.accounts[0].meta.cooling_down_until = Some(now + 30_000);
+        manager.accounts[0].meta.cooldown_reason = Some(CooldownReason::AuthFailure);
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+
+        // Account 0 recovers; account 1 then cools down -> wrap back to 0.
+        manager.accounts[0].clear_cooldown();
+        manager.accounts[1].meta.cooling_down_until = Some(now + 30_000);
+        manager.accounts[1].meta.cooldown_reason = Some(CooldownReason::NetworkError);
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn advances_when_the_active_accounts_circuit_is_open() {
+        reset_globals();
+        let mut manager = sequential_pool(2);
+
+        // Trip the circuit breaker on the active account (3 failures).
+        let key = get_account_circuit_key(&mut manager.accounts[0]);
+        let breaker = get_circuit_breaker(&key, None);
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.record_failure();
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+    }
+
+    #[test]
+    #[serial]
+    fn drains_a_3_account_pool_in_order_and_wraps_to_a_recovered_account() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(3);
+
+        // A is primary.
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+
+        // A drains -> B.
+        rate_limit_account(&mut manager, 0, now);
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+
+        // B drains -> C (forward scan past A which is still down).
+        rate_limit_account(&mut manager, 1, now);
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(2)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 2);
+
+        // A recovers; C drains -> wrap forward from C reclaims A.
+        manager.accounts[0].rate_limit_reset_times_mut().clear();
+        rate_limit_account(&mut manager, 2, now);
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn skips_a_disabled_active_account_and_advances() {
+        reset_globals();
+        let mut manager = sequential_pool(2);
+        manager.accounts[0].meta.enabled = Some(false);
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn selects_the_first_usable_account_when_active_index_is_unset() {
+        reset_globals();
+        let mut manager = sequential_pool(2);
+        // Simulate an unset (-1) active pointer.
+        manager
+            .current_account_index_by_family
+            .set(ModelFamily::Codex, -1);
+
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn advances_each_model_family_independently() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+
+        // Exhaust account 0 for the codex family ONLY.
+        rate_limit_account(&mut manager, 0, now);
+
+        // codex must advance to account 1...
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+
+        // ...but gpt-5.1 is unaffected and still drains account 0.
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Gpt5_1, None, None)
+                .map(|account| account.index),
+            Some(0)
+        );
+        assert_eq!(active(&manager, ModelFamily::Gpt5_1), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn never_anchors_the_active_pointer_on_a_policy_blocked_account() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = sequential_pool(2);
+        // Account 0 is exhausted; account 1 is otherwise usable but
+        // policy-blocked (e.g. paused/drained) for this request.
+        rate_limit_account(&mut manager, 0, now);
+        let blocked: HashSet<usize> = [1].into_iter().collect();
+
+        // Selector must NOT commit the active pointer to the blocked account.
+        assert!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, Some(&blocked))
+                .is_none()
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 0);
+
+        // Once the block clears, account 1 becomes selectable normally.
+        let empty: HashSet<usize> = HashSet::new();
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, Some(&empty))
+                .map(|account| account.index),
+            Some(1)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn all_families_share_the_constructor_pointer_init() {
+        reset_globals();
+        let now = now_ms();
+        let mut storage = storage_with(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+        ]);
+        storage.active_index = 1;
+        let manager = AccountManager::new(None, Some(&storage));
+        for family in MODEL_FAMILIES {
+            assert_eq!(active(&manager, family), 1);
+            assert_eq!(cursor(&manager, family), 1);
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Tracker interactions (recordSuccess / recordRateLimit / recordFailure /
+    // consumeToken / refundToken) + markSwitched + locked variants
+    // ------------------------------------------------------------------
+
+    #[test]
+    #[serial]
+    fn record_rate_limit_lowers_health_and_drains_the_token_bucket() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("rl-token", now)]);
+        let tracker_key = get_runtime_tracker_key(&mut manager.accounts[0]);
+
+        manager.record_rate_limit(0, ModelFamily::Codex, None);
+
+        let health = get_health_tracker(None).get_score(tracker_key.clone(), Some("codex"));
+        let tokens = get_token_tracker(None).get_tokens(tracker_key, Some("codex"));
+        assert_eq!(health, 90.0); // 100 - 10 (rate-limit event)
+        assert_eq!(tokens, 40.0); // 50 - DEFAULT_DRAIN_AMOUNT
+    }
+
+    #[test]
+    #[serial]
+    fn record_failure_lowers_health_and_trips_the_circuit_after_three() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![
+            stored_account("fail-token", now),
+            stored_account("ok-token", now),
+        ]);
+        let tracker_key = get_runtime_tracker_key(&mut manager.accounts[0]);
+
+        manager.record_failure(0, ModelFamily::Codex, None);
+        manager.record_failure(0, ModelFamily::Codex, None);
+        manager.record_failure(0, ModelFamily::Codex, None);
+
+        let health = get_health_tracker(None).get_score(tracker_key, Some("codex"));
+        assert_eq!(health, 40.0); // 100 - 3*20
+        assert_eq!(
+            manager.get_account_runtime_skip_reason(0, ModelFamily::Codex, None),
+            Some("circuit-open".to_string())
+        );
+        // Sequential selection now advances past the tripped account.
+        assert_eq!(
+            manager
+                .get_current_or_next_for_family_sequential(ModelFamily::Codex, None, None)
+                .map(|account| account.index),
+            Some(1)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn consume_token_consumes_and_refunds_when_the_circuit_is_open() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("consume-token", now)]);
+        let tracker_key = get_runtime_tracker_key(&mut manager.accounts[0]);
+
+        assert!(manager.consume_token(0, ModelFamily::Codex, None));
+        assert_eq!(
+            get_token_tracker(None).get_tokens(tracker_key.clone(), Some("codex")),
+            49.0
+        );
+
+        // Trip the circuit: consume must fail AND refund the consumed token.
+        manager.record_failure(0, ModelFamily::Codex, None);
+        manager.record_failure(0, ModelFamily::Codex, None);
+        manager.record_failure(0, ModelFamily::Codex, None);
+        assert!(!manager.consume_token(0, ModelFamily::Codex, None));
+        assert_eq!(
+            get_token_tracker(None).get_tokens(tracker_key, Some("codex")),
+            49.0
+        );
+        // Out-of-range index never consumes.
+        assert!(!manager.consume_token(99, ModelFamily::Codex, None));
+    }
+
+    #[test]
+    #[serial]
+    fn refund_token_refunds_an_in_window_consumption() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("refund-token", now)]);
+        let tracker_key = get_runtime_tracker_key(&mut manager.accounts[0]);
+
+        assert!(manager.consume_token(0, ModelFamily::Codex, None));
+        assert!(manager.refund_token(0, ModelFamily::Codex, None));
+        assert_eq!(
+            get_token_tracker(None).get_tokens(tracker_key, Some("codex")),
+            50.0
+        );
+        // Nothing left to refund.
+        assert!(!manager.refund_token(0, ModelFamily::Codex, None));
+    }
+
+    #[test]
+    #[serial]
+    fn record_success_heals_expired_cooldown_metadata_and_auth_failures() {
+        reset_globals();
+        let now = now_ms();
+        let mut expired = stored_account("heal-token", now);
+        expired.cooling_down_until = Some(now - 1_000); // EXPIRED metadata
+        expired.cooldown_reason = Some(CooldownReason::AuthFailure);
+        let mut manager = manager_from(vec![expired]);
+        manager.accounts[0].runtime.consecutive_auth_failures = Some(2);
+
+        let healed = manager.record_success(0, ModelFamily::Codex, None);
+
+        assert!(healed, "expired metadata + auth failures must heal");
+        assert_eq!(manager.accounts[0].meta.cooling_down_until, None);
+        assert_eq!(manager.accounts[0].meta.cooldown_reason, None);
+        // clearAuthFailures sets 0 (does NOT delete) — spec gotcha 13.
+        assert_eq!(
+            manager.accounts[0].runtime.consecutive_auth_failures,
+            Some(0)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn record_success_does_not_heal_while_actively_cooling() {
+        reset_globals();
+        let now = now_ms();
+        let mut cooling = stored_account("cooling-token", now);
+        cooling.cooling_down_until = Some(now + 60_000); // ACTIVE cooldown
+        cooling.cooldown_reason = Some(CooldownReason::NetworkError);
+        let mut manager = manager_from(vec![cooling]);
+        manager.accounts[0].runtime.consecutive_auth_failures = Some(1);
+
+        let healed = manager.record_success(0, ModelFamily::Codex, None);
+
+        assert!(!healed);
+        assert!(manager.accounts[0].meta.cooling_down_until.is_some());
+        assert_eq!(
+            manager.accounts[0].meta.cooldown_reason,
+            Some(CooldownReason::NetworkError)
+        );
+        assert_eq!(
+            manager.accounts[0].runtime.consecutive_auth_failures,
+            Some(1)
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn mark_switched_sets_reason_and_keeps_the_cursor_in_lockstep() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+        ]);
+
+        assert!(manager.mark_switched(1, SwitchReason::RateLimit, ModelFamily::Codex));
+
+        assert_eq!(
+            manager.accounts[1].meta.last_switch_reason,
+            Some(SwitchReason::RateLimit)
+        );
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+        // HI-02: cursor = (index + 1) % count.
+        assert_eq!(cursor(&manager, ModelFamily::Codex), 0);
+        // Other families untouched.
+        assert_eq!(active(&manager, ModelFamily::Gpt5_1), 0);
+        // Out-of-range is a no-op.
+        assert!(!manager.mark_switched(9, SwitchReason::Manual, ModelFamily::Codex));
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn mark_switched_locked_returns_a_selection_record() {
+        reset_globals();
+        let now = now_ms();
+        let mut with_email = stored_account("token-1", now);
+        with_email.email = Some("user@example.com".to_string());
+        let mut manager = manager_from(vec![stored_account("token-0", now), with_email]);
+
+        let record = manager
+            .mark_switched_locked(
+                1,
+                SwitchReason::RateLimit,
+                ModelFamily::Codex,
+                Some(MarkSwitchedContext {
+                    tracker_key_quota: Some("codex".to_string()),
+                    score: Some(12.5),
+                }),
+            )
+            .await
+            .expect("in-range index yields a record");
+
+        assert_eq!(record.account_index, 1);
+        // accountId ?? email ?? String(trackerKey) — email wins here.
+        assert_eq!(record.account_id, "user@example.com");
+        assert_eq!(record.reason, SwitchReason::RateLimit);
+        assert_eq!(record.tracker_key_quota.as_deref(), Some("codex"));
+        assert_eq!(record.health, Some(100.0));
+        assert_eq!(record.tokens, Some(50.0));
+        assert_eq!(record.score, Some(12.5));
+        // Pointer + cursor lockstep committed under the mutex.
+        assert_eq!(active(&manager, ModelFamily::Codex), 1);
+        assert_eq!(cursor(&manager, ModelFamily::Codex), 0);
+        assert_eq!(
+            manager.accounts[1].meta.last_switch_reason,
+            Some(SwitchReason::RateLimit)
+        );
+
+        // Identity-less account falls back to String(trackerKey).
+        let record = manager
+            .mark_switched_locked(0, SwitchReason::Rotation, ModelFamily::Codex, None)
+            .await
+            .expect("record");
+        assert_eq!(record.account_id, "0");
+        assert_eq!(record.score, None);
+
+        // Out-of-range yields no record (defensive; unreachable in TS).
+        assert!(
+            manager
+                .mark_switched_locked(9, SwitchReason::Manual, ModelFamily::Codex, None)
+                .await
+                .is_none()
+        );
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn mark_account_cooling_down_locked_clamps_and_sets_both_fields() {
+        reset_globals();
+        let now = now_ms();
+        let mut manager = manager_from(vec![stored_account("cool-token", now)]);
+
+        assert!(
+            manager
+                .mark_account_cooling_down_locked(0, 30_000, CooldownReason::ServerError)
+                .await
+        );
+        let until = manager.accounts[0].meta.cooling_down_until.unwrap();
+        assert!(until >= now + 30_000);
+        assert_eq!(
+            manager.accounts[0].meta.cooldown_reason,
+            Some(CooldownReason::ServerError)
+        );
+
+        // Negative durations clamp to 0 (coolingDownUntil = now).
+        assert!(
+            manager
+                .mark_account_cooling_down_locked(0, -500, CooldownReason::RateLimit)
+                .await
+        );
+        let until = manager.accounts[0].meta.cooling_down_until.unwrap();
+        assert!(until <= now_ms());
+
+        assert!(
+            !manager
+                .mark_account_cooling_down_locked(9, 1_000, CooldownReason::RateLimit)
+                .await
+        );
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn set_active_index_locked_delegates_to_set_active_index() {
+        // set_active_index fire-and-forgets a Codex-CLI mirror write when a
+        // tokio runtime is present — sandbox the env so it targets a tempdir.
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        reset_globals();
+        let now = now_ms();
+        let mut disabled = stored_account("locked-1", now);
+        disabled.enabled = Some(false);
+        let mut manager = manager_from(vec![stored_account("locked-0", now), disabled]);
+
+        let selected = manager.set_active_index_locked(0).await;
+        assert_eq!(selected.map(|account| account.index), Some(0));
+        for family in MODEL_FAMILIES {
+            assert_eq!(active(&manager, family), 0);
+            // Gotcha 9: setActiveIndex sets cursor = index (NOT index + 1).
+            assert_eq!(cursor(&manager, family), 0);
+        }
+
+        // Disabled / out-of-range → None (matching sync semantics).
+        assert!(manager.set_active_index_locked(1).await.is_none());
+        assert!(manager.set_active_index_locked(99).await.is_none());
+    }
+}
diff --git a/crates/accounts/src/rate_limits.rs b/crates/accounts/src/rate_limits.rs
new file mode 100644
index 000000000..e22459a28
--- /dev/null
+++ b/crates/accounts/src/rate_limits.rs
@@ -0,0 +1,437 @@
+//! Port of `lib/accounts/rate-limits.ts` — pure rate-limit helpers (quota
+//! keys, expiry clearing, wait-time formatting).
+//!
+//! Behavior source: spec 03 §2 + gotchas 1/11/31. TS source is authoritative.
+//!
+//! Key contracts:
+//! - [`get_quota_key`] builds `family` or `family:model` keys; the model
+//!   string is used RAW (no normalization here).
+//! - [`is_rate_limited_for_family`] has a deliberate SIDE EFFECT: it prunes
+//!   expired windows via [`clear_expired_rate_limits`] before answering
+//!   (gotcha 11 — persisted snapshots include the cleaned map).
+//! - [`clear_all_rate_limits`] drops still-future windows too (issue #606
+//!   stale-runtime recovery).
+//! - [`format_wait_time`] floors: 59.9 s → `"59s"`; `"Xm Ys"` without
+//!   zero-padding (gotcha 31). Strings are user-visible — FROZEN.
+
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{RateLimitReason, RateLimitStateV3};
+use cma_core::utils::now_ms;
+
+/// TS `type BaseQuotaKey = ModelFamily`.
+pub type BaseQuotaKey = ModelFamily;
+
+/// TS `type QuotaKey = BaseQuotaKey | `${BaseQuotaKey}:${string}``.
+///
+/// Quota keys are plain strings in the persisted `rateLimitResetTimes` map,
+/// so the Rust port models them as `String` built via [`get_quota_key`].
+pub type QuotaKey = String;
+
+/// TS `parseRateLimitReason(code)` — classify an upstream error-code string.
+///
+/// Empty/absent → `"unknown"`. Lowercased substring checks IN ORDER (a code
+/// containing both "quota" and "token" is `"quota"`):
+/// 1. `"quota"` / `"usage_limit"` → [`RateLimitReason::Quota`]
+/// 2. `"token"` / `"tpm"` / `"rpm"` → [`RateLimitReason::Tokens`]
+/// 3. `"concurrent"` / `"parallel"` → [`RateLimitReason::Concurrent`]
+/// 4. else → [`RateLimitReason::Unknown`]
+pub fn parse_rate_limit_reason(code: Option<&str>) -> RateLimitReason {
+    let Some(code) = code else {
+        return RateLimitReason::Unknown;
+    };
+    if code.is_empty() {
+        return RateLimitReason::Unknown;
+    }
+    let lc = code.to_lowercase();
+    if lc.contains("quota") || lc.contains("usage_limit") {
+        return RateLimitReason::Quota;
+    }
+    if lc.contains("token") || lc.contains("tpm") || lc.contains("rpm") {
+        return RateLimitReason::Tokens;
+    }
+    if lc.contains("concurrent") || lc.contains("parallel") {
+        return RateLimitReason::Concurrent;
+    }
+    RateLimitReason::Unknown
+}
+
+/// TS `getQuotaKey(family, model?)` — `` `${family}:${model}` `` when a
+/// (truthy = non-empty) model is given, else the bare family literal.
+pub fn get_quota_key(family: ModelFamily, model: Option<&str>) -> QuotaKey {
+    match model {
+        Some(model) if !model.is_empty() => format!("{}:{model}", family.as_str()),
+        _ => family.as_str().to_string(),
+    }
+}
+
+/// TS `clampNonNegativeInt(value, fallback)` — non-number / non-finite →
+/// `fallback` (fallback NOT validated); negative → `0`; else `Math.floor`.
+///
+/// The TS `unknown` input maps to `Option<f64>`: `None` covers
+/// undefined/non-number values, non-finite floats cover NaN/±Infinity.
+pub fn clamp_non_negative_int(value: Option<f64>, fallback: i64) -> i64 {
+    let Some(value) = value else {
+        return fallback;
+    };
+    if !value.is_finite() {
+        return fallback;
+    }
+    if value < 0.0 {
+        return 0;
+    }
+    value.floor() as i64
+}
+
+/// Integer convenience over [`clamp_non_negative_int`] for call sites whose
+/// inputs are already `i64` (schema-validated epochs/indexes): `None` →
+/// `fallback`; negative → `0`; else the value (floor is the identity).
+pub fn clamp_non_negative_int_i64(value: Option<i64>, fallback: i64) -> i64 {
+    match value {
+        None => fallback,
+        Some(value) if value < 0 => 0,
+        Some(value) => value,
+    }
+}
+
+/// TS `interface RateLimitedEntity { rateLimitResetTimes: RateLimitState }` —
+/// anything carrying a mutable quota-key → epoch-ms reset-time map.
+pub trait RateLimitedEntity {
+    fn rate_limit_reset_times(&self) -> &RateLimitStateV3;
+    fn rate_limit_reset_times_mut(&mut self) -> &mut RateLimitStateV3;
+}
+
+/// A bare map is its own rate-limited entity.
+impl RateLimitedEntity for RateLimitStateV3 {
+    fn rate_limit_reset_times(&self) -> &RateLimitStateV3 {
+        self
+    }
+    fn rate_limit_reset_times_mut(&mut self) -> &mut RateLimitStateV3 {
+        self
+    }
+}
+
+/// TS `clearExpiredRateLimits(entity)` — delete every key whose reset time
+/// has arrived (`now >= resetTime`). Mutates the entity.
+pub fn clear_expired_rate_limits(entity: &mut impl RateLimitedEntity) {
+    let now = now_ms();
+    entity
+        .rate_limit_reset_times_mut()
+        .retain(|_, reset_time| now < reset_time);
+}
+
+/// TS `clearAllRateLimits(entity)` — remove EVERY entry, including
+/// still-future windows (issue #606 recovery clean slate).
+pub fn clear_all_rate_limits(entity: &mut impl RateLimitedEntity) {
+    entity.rate_limit_reset_times_mut().clear();
+}
+
+/// TS `isRateLimitedForQuotaKey(entity, key)` — limited while a reset time
+/// exists and lies strictly in the future. Pure (no pruning).
+pub fn is_rate_limited_for_quota_key(entity: &impl RateLimitedEntity, key: &str) -> bool {
+    match entity.rate_limit_reset_times().get(key) {
+        Some(reset_time) => now_ms() < reset_time,
+        None => false,
+    }
+}
+
+/// TS `isRateLimitedForFamily(entity, family, model?)`.
+///
+/// SIDE EFFECT: prunes expired windows first (gotcha 11). Then, when a model
+/// is given, the model-scoped key is checked first; the base family key is
+/// ALWAYS checked afterwards — limited if either hits.
+pub fn is_rate_limited_for_family(
+    entity: &mut impl RateLimitedEntity,
+    family: ModelFamily,
+    model: Option<&str>,
+) -> bool {
+    clear_expired_rate_limits(entity);
+
+    if let Some(model) = model
+        && !model.is_empty()
+    {
+        let model_key = get_quota_key(family, Some(model));
+        if is_rate_limited_for_quota_key(entity, &model_key) {
+            return true;
+        }
+    }
+
+    let base_key = get_quota_key(family, None);
+    is_rate_limited_for_quota_key(entity, &base_key)
+}
+
+/// TS `formatWaitTime(ms)` — `totalSeconds = max(0, floor(ms/1000))`;
+/// `"Xm Ys"` when minutes > 0 else `"Xs"`. FROZEN user-visible strings.
+pub fn format_wait_time(ms: i64) -> String {
+    let total_seconds = (ms.div_euclid(1000)).max(0);
+    let minutes = total_seconds / 60;
+    let seconds = total_seconds % 60;
+    if minutes > 0 {
+        format!("{minutes}m {seconds}s")
+    } else {
+        format!("{seconds}s")
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/account-rate-limits.test.ts (+ the
+// parseRateLimitReason / formatWaitTime suites of test/accounts.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn state_of(entries: &[(&str, i64)]) -> RateLimitStateV3 {
+        let mut state = RateLimitStateV3::new();
+        for (key, value) in entries {
+            state.insert(*key, *value);
+        }
+        state
+    }
+
+    // -- parseRateLimitReason ------------------------------------------------
+
+    #[test]
+    fn parse_returns_quota_for_quota_related_codes() {
+        assert_eq!(
+            parse_rate_limit_reason(Some("insufficient_quota")),
+            RateLimitReason::Quota
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("usage_limit_reached")),
+            RateLimitReason::Quota
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("QUOTA_EXCEEDED")),
+            RateLimitReason::Quota
+        );
+    }
+
+    #[test]
+    fn parse_returns_tokens_for_token_related_codes() {
+        assert_eq!(
+            parse_rate_limit_reason(Some("tokens_exhausted")),
+            RateLimitReason::Tokens
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("tpm_limit")),
+            RateLimitReason::Tokens
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("rpm_exceeded")),
+            RateLimitReason::Tokens
+        );
+    }
+
+    #[test]
+    fn parse_returns_concurrent_for_concurrency_codes() {
+        assert_eq!(
+            parse_rate_limit_reason(Some("concurrent_requests")),
+            RateLimitReason::Concurrent
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("too_many_parallel")),
+            RateLimitReason::Concurrent
+        );
+    }
+
+    #[test]
+    fn parse_returns_unknown_for_absent_or_empty() {
+        assert_eq!(parse_rate_limit_reason(None), RateLimitReason::Unknown);
+        assert_eq!(parse_rate_limit_reason(Some("")), RateLimitReason::Unknown);
+    }
+
+    #[test]
+    fn parse_returns_unknown_for_unrecognized_codes() {
+        assert_eq!(
+            parse_rate_limit_reason(Some("server_error")),
+            RateLimitReason::Unknown
+        );
+        assert_eq!(
+            parse_rate_limit_reason(Some("something_else")),
+            RateLimitReason::Unknown
+        );
+    }
+
+    #[test]
+    fn parse_order_matters_quota_wins_over_tokens() {
+        // A code containing both "quota" and "token" classifies as quota.
+        assert_eq!(
+            parse_rate_limit_reason(Some("token_quota_exceeded")),
+            RateLimitReason::Quota
+        );
+    }
+
+    // -- getQuotaKey ---------------------------------------------------------
+
+    #[test]
+    fn quota_key_returns_bare_family_when_no_model() {
+        assert_eq!(get_quota_key(ModelFamily::Codex, None), "codex");
+        assert_eq!(get_quota_key(ModelFamily::Gpt5_2, None), "gpt-5.2");
+        // TS falsy model ("" or null) also yields the bare family.
+        assert_eq!(get_quota_key(ModelFamily::Codex, Some("")), "codex");
+    }
+
+    #[test]
+    fn quota_key_scopes_to_model_when_given() {
+        assert_eq!(
+            get_quota_key(ModelFamily::Codex, Some("gpt-5.3-codex")),
+            "codex:gpt-5.3-codex"
+        );
+        assert_eq!(
+            get_quota_key(ModelFamily::Gpt5_2, Some("gpt-5.2-pro")),
+            "gpt-5.2:gpt-5.2-pro"
+        );
+    }
+
+    // -- clampNonNegativeInt -------------------------------------------------
+
+    #[test]
+    fn clamp_falls_back_for_non_numbers_and_non_finite() {
+        assert_eq!(clamp_non_negative_int(None, 42), 42);
+        assert_eq!(clamp_non_negative_int(Some(f64::NAN), 42), 42);
+        assert_eq!(clamp_non_negative_int(Some(f64::INFINITY), 42), 42);
+        assert_eq!(clamp_non_negative_int(Some(f64::NEG_INFINITY), 42), 42);
+        // Fallback is NOT validated.
+        assert_eq!(clamp_non_negative_int(None, -7), -7);
+    }
+
+    #[test]
+    fn clamp_zeroes_negatives_and_floors_fractions() {
+        assert_eq!(clamp_non_negative_int(Some(-5.0), 42), 0);
+        assert_eq!(clamp_non_negative_int(Some(-0.5), 42), 0);
+        assert_eq!(clamp_non_negative_int(Some(3.9), 42), 3);
+        assert_eq!(clamp_non_negative_int(Some(0.0), 42), 0);
+        assert_eq!(clamp_non_negative_int(Some(7.0), 42), 7);
+    }
+
+    #[test]
+    fn clamp_i64_convenience_matches_semantics() {
+        assert_eq!(clamp_non_negative_int_i64(None, 9), 9);
+        assert_eq!(clamp_non_negative_int_i64(Some(-3), 9), 0);
+        assert_eq!(clamp_non_negative_int_i64(Some(4), 9), 4);
+    }
+
+    // -- clearExpiredRateLimits / clearAllRateLimits -------------------------
+
+    #[test]
+    fn clear_expired_removes_due_entries_and_keeps_future_ones() {
+        let now = now_ms();
+        let mut state = state_of(&[
+            ("codex", now - 1_000),
+            ("codex:gpt-5.3-codex", now + 60_000),
+            ("gpt-5.2", now), // exactly-now counts as expired (now >= reset)
+        ]);
+        clear_expired_rate_limits(&mut state);
+        assert!(!state.contains_key("codex"));
+        assert!(!state.contains_key("gpt-5.2"));
+        assert_eq!(state.get("codex:gpt-5.3-codex"), Some(now + 60_000));
+        assert_eq!(state.len(), 1);
+    }
+
+    #[test]
+    fn clear_all_drops_future_windows_too_issue_606() {
+        let now = now_ms();
+        let mut state = state_of(&[
+            ("codex", now + 600_000),
+            ("gpt-5.2:gpt-5.2-pro", now + 3_600_000),
+        ]);
+        clear_all_rate_limits(&mut state);
+        assert!(state.is_empty());
+    }
+
+    // -- isRateLimitedForQuotaKey --------------------------------------------
+
+    #[test]
+    fn limited_for_quota_key_only_while_reset_in_future() {
+        let now = now_ms();
+        let state = state_of(&[("codex", now + 30_000), ("gpt-5.2", now - 30_000)]);
+        assert!(is_rate_limited_for_quota_key(&state, "codex"));
+        assert!(!is_rate_limited_for_quota_key(&state, "gpt-5.2"));
+        assert!(!is_rate_limited_for_quota_key(&state, "codex-max"));
+    }
+
+    // -- isRateLimitedForFamily ----------------------------------------------
+
+    #[test]
+    fn family_check_treats_missing_model_as_family_key_only() {
+        let now = now_ms();
+        let mut state = state_of(&[("codex", now + 30_000)]);
+        assert!(is_rate_limited_for_family(&mut state, ModelFamily::Codex, None));
+        let mut clear = state_of(&[("codex:gpt-5.3-codex", now + 30_000)]);
+        // Family-only check ignores model-scoped entries.
+        assert!(!is_rate_limited_for_family(
+            &mut clear,
+            ModelFamily::Codex,
+            None
+        ));
+    }
+
+    #[test]
+    fn family_check_honors_model_scoped_limit_when_family_clear() {
+        let now = now_ms();
+        let mut state = state_of(&[("codex:gpt-5.3-codex", now + 30_000)]);
+        assert!(is_rate_limited_for_family(
+            &mut state,
+            ModelFamily::Codex,
+            Some("gpt-5.3-codex")
+        ));
+        // A different model in the same family stays routable.
+        assert!(!is_rate_limited_for_family(
+            &mut state,
+            ModelFamily::Codex,
+            Some("codex-mini")
+        ));
+    }
+
+    #[test]
+    fn family_wide_limit_applies_to_every_model_in_the_family() {
+        let now = now_ms();
+        let mut state = state_of(&[("codex", now + 30_000)]);
+        assert!(is_rate_limited_for_family(
+            &mut state,
+            ModelFamily::Codex,
+            Some("gpt-5.3-codex")
+        ));
+        assert!(is_rate_limited_for_family(
+            &mut state,
+            ModelFamily::Codex,
+            Some("codex-mini")
+        ));
+        assert!(is_rate_limited_for_family(&mut state, ModelFamily::Codex, None));
+    }
+
+    #[test]
+    fn family_check_prunes_expired_entries_as_a_side_effect() {
+        let now = now_ms();
+        let mut state = state_of(&[
+            ("codex", now - 1_000),
+            ("codex:gpt-5.3-codex", now - 2_000),
+            ("gpt-5.1", now + 60_000),
+        ]);
+        assert!(!is_rate_limited_for_family(
+            &mut state,
+            ModelFamily::Codex,
+            Some("gpt-5.3-codex")
+        ));
+        // Expired entries were deleted; the future one survives.
+        assert!(!state.contains_key("codex"));
+        assert!(!state.contains_key("codex:gpt-5.3-codex"));
+        assert!(state.contains_key("gpt-5.1"));
+    }
+
+    // -- formatWaitTime ------------------------------------------------------
+
+    #[test]
+    fn format_wait_time_exact_strings() {
+        assert_eq!(format_wait_time(0), "0s");
+        assert_eq!(format_wait_time(-5_000), "0s");
+        assert_eq!(format_wait_time(1_000), "1s");
+        assert_eq!(format_wait_time(59_000), "59s");
+        assert_eq!(format_wait_time(59_900), "59s"); // floors partial seconds
+        assert_eq!(format_wait_time(60_000), "1m 0s");
+        assert_eq!(format_wait_time(90_000), "1m 30s");
+        assert_eq!(format_wait_time(3_661_000), "61m 1s");
+        assert_eq!(format_wait_time(125_500), "2m 5s");
+    }
+}
diff --git a/crates/accounts/src/routing_profiles.rs b/crates/accounts/src/routing_profiles.rs
new file mode 100644
index 000000000..e391228eb
--- /dev/null
+++ b/crates/accounts/src/routing_profiles.rs
@@ -0,0 +1,716 @@
+//! Port of `lib/routing-profiles.ts` — persisted per-project routing
+//! profile store (`routing-profiles.json`): tag preferences, model
+//! allow/deny lists, per-account weights, budget key.
+//!
+//! Behavior source: specs/03-accounts.md §8 (+ §11 constants, §13 error
+//! contracts, §15 gotcha 23). TS source is authoritative.
+//!
+//! On-disk format (golden fixture
+//! `crates/testkit/goldens/routing-profiles.json`):
+//! `{ "version": 1, "profiles": { "<key>": { projectKey, projectName,
+//! identityRoot, preferredTags, avoidTags, modelAllowlist, modelDenylist,
+//! accountWeightByKey, budgetKey, updatedAt } } }` — 2-space pretty print,
+//! trailing newline, 0600/0700 modes, field order as listed.
+//!
+//! Concurrency: same model as `account_policy.rs` — NO cross-process lock;
+//! atomic temp+rename + in-process write queue; last writer wins.
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::{
+    TrailingNewline, WriteJsonOptions, stringify_pretty2, write_json_atomic,
+};
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_storage::paths::{
+    find_project_root, get_project_storage_key, resolve_project_storage_identity_root,
+};
+use serde::Serialize;
+use serde::ser::{SerializeMap, Serializer};
+use serde_json::Value;
+
+/// TS `ROUTING_PROFILES_FILE_NAME`.
+pub const ROUTING_PROFILES_FILE_NAME: &str = "routing-profiles.json";
+
+const PROJECT_NAME_MAX_LEN_UTF16: usize = 80;
+const BUDGET_KEY_MAX_LEN_UTF16: usize = 80;
+const WEIGHT_MIN: f64 = 0.0;
+const WEIGHT_MAX: f64 = 10.0;
+
+/// Retryable read/rename codes (TS `RETRYABLE_FS_CODES`).
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+
+/// In-process write serialization (TS module-level `writeQueue`; see
+/// `account_policy.rs` for the pattern rationale).
+static WRITE_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/// Ordered `Record<string, number>` with JS-object insertion semantics.
+/// Keys MUST start `"sha256:"`; values are clamped `[0, 10]` on normalize.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AccountWeightMap {
+    entries: Vec<(String, f64)>,
+}
+
+impl AccountWeightMap {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn get(&self, key: &str) -> Option<f64> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, weight)| *weight)
+    }
+
+    /// JS `map[key] = weight`: replaces in place (keeping position) when the
+    /// key exists, otherwise appends.
+    pub fn insert(&mut self, key: impl Into<String>, weight: f64) {
+        let key = key.into();
+        if let Some(entry) = self.entries.iter_mut().find(|(k, _)| *k == key) {
+            entry.1 = weight;
+        } else {
+            self.entries.push((key, weight));
+        }
+    }
+
+    pub fn remove(&mut self, key: &str) -> Option<f64> {
+        let index = self.entries.iter().position(|(k, _)| k == key)?;
+        Some(self.entries.remove(index).1)
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, f64)> {
+        self.entries.iter().map(|(k, weight)| (k.as_str(), *weight))
+    }
+}
+
+impl Serialize for AccountWeightMap {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let mut map = serializer.serialize_map(Some(self.entries.len()))?;
+        for (key, weight) in &self.entries {
+            map.serialize_entry(key, weight)?;
+        }
+        map.end()
+    }
+}
+
+/// TS `interface RoutingProfile`. Field declaration order == on-disk
+/// emission order (byte compat). `budgetKey` serializes as literal `null`
+/// when absent.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RoutingProfile {
+    /// `"<sanitized-name≤40>-<12hex sha256>"` — forced to the map key on
+    /// normalize.
+    pub project_key: String,
+    /// Trimmed, ≤80 UTF-16 units, fallback `"project"`.
+    pub project_name: String,
+    /// Worktree-resolved project root path (`""` when missing).
+    pub identity_root: String,
+    pub preferred_tags: Vec<String>,
+    pub avoid_tags: Vec<String>,
+    pub model_allowlist: Vec<String>,
+    pub model_denylist: Vec<String>,
+    pub account_weight_by_key: AccountWeightMap,
+    /// Trimmed, ≤80 units, else `None` (serialized `null`).
+    pub budget_key: Option<String>,
+    /// Epoch ms, `0` when unknown.
+    pub updated_at: f64,
+}
+
+/// TS `interface RoutingProfileStore` (`version` always the literal `1`).
+/// `profiles` preserves JS-object insertion order.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct RoutingProfileStore {
+    entries: Vec<(String, RoutingProfile)>,
+}
+
+impl RoutingProfileStore {
+    /// TS `emptyStore()`.
+    pub fn empty() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn get(&self, key: &str) -> Option<&RoutingProfile> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, profile)| profile)
+    }
+
+    pub fn get_mut(&mut self, key: &str) -> Option<&mut RoutingProfile> {
+        self.entries
+            .iter_mut()
+            .find(|(k, _)| k == key)
+            .map(|(_, profile)| profile)
+    }
+
+    /// JS `store.profiles[key] = profile` (insertion-order preserving).
+    pub fn insert(&mut self, key: impl Into<String>, profile: RoutingProfile) {
+        let key = key.into();
+        if let Some(entry) = self.entries.iter_mut().find(|(k, _)| *k == key) {
+            entry.1 = profile;
+        } else {
+            self.entries.push((key, profile));
+        }
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, &RoutingProfile)> {
+        self.entries
+            .iter()
+            .map(|(k, profile)| (k.as_str(), profile))
+    }
+}
+
+impl Serialize for RoutingProfileStore {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        struct Profiles<'a>(&'a [(String, RoutingProfile)]);
+        impl Serialize for Profiles<'_> {
+            fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+                let mut map = serializer.serialize_map(Some(self.0.len()))?;
+                for (key, profile) in self.0 {
+                    map.serialize_entry(key, profile)?;
+                }
+                map.end()
+            }
+        }
+        let mut map = serializer.serialize_map(Some(2))?;
+        map.serialize_entry("version", &1)?;
+        map.serialize_entry("profiles", &Profiles(&self.entries))?;
+        map.end()
+    }
+}
+
+/// TS `interface ProjectRoutingProfileContext`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProjectRoutingProfileContext {
+    pub start_dir: PathBuf,
+    pub project_root: Option<PathBuf>,
+    pub identity_root: Option<PathBuf>,
+    pub project_key: Option<String>,
+    pub profile: Option<RoutingProfile>,
+}
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+/// JS `String.prototype.slice(0, n)` — see `account_policy.rs`.
+fn slice_utf16_units(value: &str, max_units: usize) -> String {
+    let mut units = 0usize;
+    let mut end = value.len();
+    for (idx, ch) in value.char_indices() {
+        let width = ch.len_utf16();
+        if units + width > max_units {
+            end = idx;
+            break;
+        }
+        units += width;
+    }
+    value[..end].to_string()
+}
+
+/// JS default `.sort()` comparator (UTF-16 code-unit order).
+fn js_string_cmp(a: &str, b: &str) -> std::cmp::Ordering {
+    a.encode_utf16().cmp(b.encode_utf16())
+}
+
+/// TS `normalizeTokenList`: strings only, trim + lowercase, drop empty,
+/// Set-dedupe, `.sort()`. (Unlike account-policy tags, NO charset
+/// replacement — `"Team A"` becomes `"team a"`.)
+fn normalize_token_list_iter<'a>(tokens: impl Iterator<Item = &'a str>) -> Vec<String> {
+    let mut seen: Vec<String> = Vec::new();
+    for token in tokens {
+        let normalized = token.trim().to_lowercase();
+        if !normalized.is_empty() && !seen.contains(&normalized) {
+            seen.push(normalized);
+        }
+    }
+    seen.sort_by(|a, b| js_string_cmp(a, b));
+    seen
+}
+
+fn normalize_token_list_value(value: Option<&Value>) -> Vec<String> {
+    match value.and_then(Value::as_array) {
+        Some(raw) => normalize_token_list_iter(raw.iter().filter_map(Value::as_str)),
+        None => Vec::new(),
+    }
+}
+
+/// TS `normalizeWeightMap`: keys must start `"sha256:"`, values finite,
+/// clamped `[0, 10]`.
+fn normalize_weight_map_value(value: Option<&Value>) -> AccountWeightMap {
+    let mut result = AccountWeightMap::new();
+    if let Some(record) = value.and_then(Value::as_object) {
+        for (key, raw) in record {
+            if !key.starts_with("sha256:") {
+                continue;
+            }
+            let Some(weight) = raw.as_f64().filter(|w| w.is_finite()) else {
+                continue;
+            };
+            result.insert(key.clone(), weight.clamp(WEIGHT_MIN, WEIGHT_MAX));
+        }
+    }
+    result
+}
+
+fn normalize_weight_map_typed(map: &AccountWeightMap) -> AccountWeightMap {
+    let mut result = AccountWeightMap::new();
+    for (key, weight) in map.iter() {
+        if !key.starts_with("sha256:") || !weight.is_finite() {
+            continue;
+        }
+        result.insert(key.to_string(), weight.clamp(WEIGHT_MIN, WEIGHT_MAX));
+    }
+    result
+}
+
+fn normalize_project_name(value: Option<&str>) -> String {
+    let trimmed = value.unwrap_or("").trim();
+    if trimmed.is_empty() {
+        "project".to_string()
+    } else {
+        slice_utf16_units(trimmed, PROJECT_NAME_MAX_LEN_UTF16)
+    }
+}
+
+fn normalize_budget_key(value: Option<&str>) -> Option<String> {
+    let trimmed = value.unwrap_or("").trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(slice_utf16_units(trimmed, BUDGET_KEY_MAX_LEN_UTF16))
+    }
+}
+
+/// TS `normalizeProfile(key, value)` over a raw JSON value (load path) —
+/// `None` when the value is not a record (the entry is dropped).
+fn normalize_profile_value(key: &str, value: &Value) -> Option<RoutingProfile> {
+    let record = value.as_object()?;
+    Some(RoutingProfile {
+        // TS: `value.projectKey` only when it string-equals `key`, else
+        // forced to `key` — either way the result IS `key`.
+        project_key: key.to_string(),
+        project_name: normalize_project_name(record.get("projectName").and_then(Value::as_str)),
+        identity_root: record
+            .get("identityRoot")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .unwrap_or("")
+            .to_string(),
+        preferred_tags: normalize_token_list_value(record.get("preferredTags")),
+        avoid_tags: normalize_token_list_value(record.get("avoidTags")),
+        model_allowlist: normalize_token_list_value(record.get("modelAllowlist")),
+        model_denylist: normalize_token_list_value(record.get("modelDenylist")),
+        account_weight_by_key: normalize_weight_map_value(record.get("accountWeightByKey")),
+        budget_key: normalize_budget_key(record.get("budgetKey").and_then(Value::as_str)),
+        updated_at: record
+            .get("updatedAt")
+            .and_then(Value::as_f64)
+            .filter(|v| v.is_finite())
+            .unwrap_or(0.0),
+    })
+}
+
+/// TS `normalizeProfile` applied to a typed profile (save/upsert path). A
+/// typed profile is always a record, so this never drops the entry.
+fn normalize_profile_typed(key: &str, profile: &RoutingProfile) -> RoutingProfile {
+    RoutingProfile {
+        project_key: key.to_string(),
+        project_name: normalize_project_name(Some(&profile.project_name)),
+        identity_root: profile.identity_root.trim().to_string(),
+        preferred_tags: normalize_token_list_iter(profile.preferred_tags.iter().map(String::as_str)),
+        avoid_tags: normalize_token_list_iter(profile.avoid_tags.iter().map(String::as_str)),
+        model_allowlist: normalize_token_list_iter(
+            profile.model_allowlist.iter().map(String::as_str),
+        ),
+        model_denylist: normalize_token_list_iter(
+            profile.model_denylist.iter().map(String::as_str),
+        ),
+        account_weight_by_key: normalize_weight_map_typed(&profile.account_weight_by_key),
+        budget_key: normalize_budget_key(profile.budget_key.as_deref()),
+        updated_at: if profile.updated_at.is_finite() {
+            profile.updated_at
+        } else {
+            0.0
+        },
+    }
+}
+
+/// TS `normalizeStore(value)` over raw JSON (load path).
+fn normalize_store_value(value: &Value) -> RoutingProfileStore {
+    let Some(record) = value.as_object() else {
+        return RoutingProfileStore::empty();
+    };
+    if record.get("version").and_then(Value::as_f64) != Some(1.0) {
+        return RoutingProfileStore::empty();
+    }
+    let mut store = RoutingProfileStore::empty();
+    if let Some(profiles) = record.get("profiles").and_then(Value::as_object) {
+        for (key, raw) in profiles {
+            if let Some(profile) = normalize_profile_value(key, raw) {
+                store.insert(key.clone(), profile);
+            }
+        }
+    }
+    store
+}
+
+/// TS `normalizeStore` applied to a typed store (save path).
+fn normalize_store_typed(store: &RoutingProfileStore) -> RoutingProfileStore {
+    let mut normalized = RoutingProfileStore::empty();
+    for (key, profile) in store.iter() {
+        normalized.insert(key.to_string(), normalize_profile_typed(key, profile));
+    }
+    normalized
+}
+
+// ---------------------------------------------------------------------------
+// IO helpers
+// ---------------------------------------------------------------------------
+
+fn sidecar_backoff() -> Backoff {
+    // TS `sleep(10 * 2 ** attempt)` (0-based) → 10/20/40/80 ms for the
+    // 1-based failed-attempt index.
+    Backoff::from_fn(|failed_attempt| {
+        10u64.saturating_mul(2u64.saturating_pow(failed_attempt.saturating_sub(1)))
+    })
+}
+
+/// TS `readFileWithRetry` — 5 attempts, EBUSY/EPERM only.
+async fn read_file_with_retry(path: &Path) -> io::Result<String> {
+    with_retry(
+        || async { tokio::fs::read_to_string(path).await },
+        RetryOptions::<io::Error>::new(5, sidecar_backoff()).with_codes(RETRYABLE_FS_CODES),
+    )
+    .await
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/// TS `getRoutingProfilesPath()`.
+pub fn get_routing_profiles_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(ROUTING_PROFILES_FILE_NAME)
+}
+
+/// TS `loadRoutingProfileStore()` — NEVER fails (warn + empty store on any
+/// read/parse problem).
+pub async fn load_routing_profile_store() -> RoutingProfileStore {
+    let path = get_routing_profiles_path();
+    if !path.exists() {
+        return RoutingProfileStore::empty();
+    }
+    let parsed: Result<Value, String> = match read_file_with_retry(&path).await {
+        Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|error| error.to_string()),
+        Err(error) => Err(error.to_string()),
+    };
+    match parsed {
+        Ok(value) => normalize_store_value(&value),
+        Err(message) => {
+            let basename = path
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_default();
+            log_warn(
+                &format!("Failed to load routing profiles from {basename}: {message}"),
+                None,
+            );
+            RoutingProfileStore::empty()
+        }
+    }
+}
+
+/// TS `saveRoutingProfileStore(store)` — identical atomic write-queue
+/// pattern as `save_account_policy_store` (mkdir 0700, temp write 0600,
+/// 2-space pretty + trailing `\n`, rename retried ×5 on EBUSY/EPERM, temp
+/// unlinked on failure).
+pub async fn save_routing_profile_store(store: &RoutingProfileStore) -> io::Result<()> {
+    let path = get_routing_profiles_path();
+    let payload = normalize_store_typed(store);
+    let content = stringify_pretty2(&payload);
+    let _queue = WRITE_QUEUE.lock().await;
+    write_json_atomic(
+        &path,
+        &content,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::Lf,
+            ensure_parent_dir: true,
+            parent_dir_mode: Some(0o700),
+            rename_max_attempts: 5,
+            ..Default::default()
+        },
+    )
+    .await
+}
+
+/// Input for [`create_default_routing_profile`].
+#[derive(Debug, Clone)]
+pub struct DefaultRoutingProfileInput {
+    pub project_key: String,
+    pub project_name: String,
+    pub identity_root: String,
+    /// Epoch ms; `None` → caller-side `Date.now()` equivalent.
+    pub now_ms: Option<i64>,
+}
+
+/// TS `createDefaultRoutingProfile(input)`.
+pub fn create_default_routing_profile(input: DefaultRoutingProfileInput) -> RoutingProfile {
+    RoutingProfile {
+        project_key: input.project_key,
+        project_name: input.project_name,
+        identity_root: input.identity_root,
+        preferred_tags: Vec::new(),
+        avoid_tags: Vec::new(),
+        model_allowlist: Vec::new(),
+        model_denylist: Vec::new(),
+        account_weight_by_key: AccountWeightMap::new(),
+        budget_key: None,
+        updated_at: input.now_ms.unwrap_or_else(cma_core::utils::now_ms) as f64,
+    }
+}
+
+/// TS `upsertRoutingProfile(store, profile, mutate?, now)` without a mutate
+/// callback.
+pub fn upsert_routing_profile(
+    store: &mut RoutingProfileStore,
+    profile: &RoutingProfile,
+    now_ms: i64,
+) -> RoutingProfile {
+    upsert_routing_profile_with(store, profile, |_| {}, now_ms)
+}
+
+/// TS `upsertRoutingProfile(store, profile, mutate, now)` — clone the
+/// stored (or given) profile, apply `mutate`, stamp `updatedAt`, then fully
+/// re-normalize under `profile.projectKey`.
+///
+/// The TS `throw new Error("Invalid routing profile")` branch fired only
+/// when `mutate` replaced the object with a non-record — unrepresentable in
+/// Rust, so this function is infallible.
+pub fn upsert_routing_profile_with(
+    store: &mut RoutingProfileStore,
+    profile: &RoutingProfile,
+    mutate: impl FnOnce(&mut RoutingProfile),
+    now_ms: i64,
+) -> RoutingProfile {
+    let mut next = store
+        .get(&profile.project_key)
+        .cloned()
+        .unwrap_or_else(|| profile.clone());
+    mutate(&mut next);
+    next.updated_at = now_ms as f64;
+    let normalized = normalize_profile_typed(&profile.project_key, &next);
+    store.insert(profile.project_key.clone(), normalized.clone());
+    normalized
+}
+
+/// TS `resolveProjectRoutingProfile(startDir, storeLoader?)` with the
+/// default loader.
+pub async fn resolve_project_routing_profile(start_dir: &Path) -> ProjectRoutingProfileContext {
+    resolve_project_routing_profile_with_loader(start_dir, load_routing_profile_store()).await
+}
+
+/// Loader-injectable variant (TS `storeLoader` default parameter). The
+/// loader future is only awaited when a project root is found — the TS
+/// short-circuits before touching the store.
+pub async fn resolve_project_routing_profile_with_loader(
+    start_dir: &Path,
+    store_loader: impl Future<Output = RoutingProfileStore>,
+) -> ProjectRoutingProfileContext {
+    let Some(project_root) = find_project_root(start_dir) else {
+        return ProjectRoutingProfileContext {
+            start_dir: start_dir.to_path_buf(),
+            project_root: None,
+            identity_root: None,
+            project_key: None,
+            profile: None,
+        };
+    };
+    let identity_root = resolve_project_storage_identity_root(&project_root);
+    let project_key = get_project_storage_key(&identity_root);
+    let store = store_loader.await;
+    let profile = store.get(&project_key).cloned();
+    ProjectRoutingProfileContext {
+        start_dir: start_dir.to_path_buf(),
+        project_root: Some(project_root),
+        identity_root: Some(identity_root),
+        project_key: Some(project_key),
+        profile,
+    }
+}
+
+/// TS `resetRoutingProfileWriteQueueForTests()` — parity no-op (see
+/// `reset_account_policy_write_queue_for_tests`).
+pub fn reset_routing_profile_write_queue_for_tests() {}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/routing-profiles.test.ts + golden round-trip)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    #[test]
+    fn token_lists_lowercase_trim_dedupe_and_sort_without_charset_rewrite() {
+        assert_eq!(
+            normalize_token_list_iter(["  Team A ", "team a", "B!"].into_iter()),
+            vec!["b!", "team a"],
+        );
+        assert_eq!(normalize_token_list_iter(["   ", ""].into_iter()), Vec::<String>::new());
+    }
+
+    #[test]
+    fn weight_maps_drop_foreign_keys_and_clamp() {
+        let value = serde_json::json!({
+            "sha256:aa": 12,
+            "sha256:bb": -1,
+            "sha256:cc": 0.5,
+            "plain": 3,
+            "sha256:dd": "9"
+        });
+        let map = normalize_weight_map_value(Some(&value));
+        assert_eq!(map.len(), 3);
+        assert_eq!(map.get("sha256:aa"), Some(10.0));
+        assert_eq!(map.get("sha256:bb"), Some(0.0));
+        assert_eq!(map.get("sha256:cc"), Some(0.5));
+        assert_eq!(map.get("plain"), None);
+        assert_eq!(map.get("sha256:dd"), None);
+    }
+
+    #[test]
+    fn profile_normalization_defaults_and_caps() {
+        let value = serde_json::json!({
+            "projectKey": "other-key",
+            "projectName": "   ",
+            "identityRoot": "  /x  ",
+            "budgetKey": "",
+            "updatedAt": "not-a-number"
+        });
+        let profile = normalize_profile_value("the-key", &value).unwrap();
+        assert_eq!(profile.project_key, "the-key");
+        assert_eq!(profile.project_name, "project");
+        assert_eq!(profile.identity_root, "/x");
+        assert_eq!(profile.budget_key, None);
+        assert_eq!(profile.updated_at, 0.0);
+        // Non-record entries are dropped entirely.
+        assert!(normalize_profile_value("k", &serde_json::json!(42)).is_none());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn resolves_profile_identity_through_project_storage_helpers() {
+        let sandbox = EnvSandbox::new();
+        let project_dir = sandbox.root().join("project");
+        std::fs::create_dir_all(&project_dir).unwrap();
+        std::fs::write(project_dir.join("package.json"), "{}").unwrap();
+
+        let initial = resolve_project_routing_profile(&project_dir).await;
+        assert_eq!(initial.project_root.as_deref(), Some(project_dir.as_path()));
+        assert_eq!(initial.identity_root.as_deref(), Some(project_dir.as_path()));
+        let project_key = initial.project_key.clone().unwrap();
+        assert!(project_key.starts_with("project-"), "got {project_key}");
+        assert!(initial.profile.is_none());
+
+        let mut store = load_routing_profile_store().await;
+        let profile = create_default_routing_profile(DefaultRoutingProfileInput {
+            project_key: project_key.clone(),
+            project_name: "project".to_string(),
+            identity_root: project_dir.to_string_lossy().into_owned(),
+            now_ms: Some(100),
+        });
+        upsert_routing_profile_with(
+            &mut store,
+            &profile,
+            |next| {
+                next.preferred_tags.push("Team A".to_string());
+                next.model_allowlist.push("GPT-5.3-Codex".to_string());
+                next.account_weight_by_key.insert("sha256:abc", 3.0);
+                next.budget_key = Some("default".to_string());
+            },
+            200,
+        );
+        save_routing_profile_store(&store).await.unwrap();
+
+        let resolved = resolve_project_routing_profile(&project_dir).await;
+        let profile = resolved.profile.unwrap();
+        assert_eq!(profile.project_key, project_key);
+        assert_eq!(profile.preferred_tags, vec!["team a"]);
+        assert_eq!(profile.model_allowlist, vec!["gpt-5.3-codex"]);
+        assert_eq!(profile.account_weight_by_key.get("sha256:abc"), Some(3.0));
+        assert_eq!(profile.budget_key.as_deref(), Some("default"));
+        assert_eq!(profile.updated_at, 200.0);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_null_profile_when_none_stored_for_project() {
+        let sandbox = EnvSandbox::new();
+        let project_dir = sandbox.root().join("project");
+        std::fs::create_dir_all(&project_dir).unwrap();
+        std::fs::write(project_dir.join("package.json"), "{}").unwrap();
+
+        let context = resolve_project_routing_profile(&project_dir).await;
+        assert!(context.project_key.unwrap().starts_with("project-"));
+        assert!(context.profile.is_none());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn golden_routing_profiles_round_trips_byte_exact() {
+        let sandbox = EnvSandbox::new();
+        let golden_path = concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../testkit/goldens/routing-profiles.json"
+        );
+        let golden = std::fs::read_to_string(golden_path).unwrap();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_routing_profiles_path(), &golden).unwrap();
+
+        let store = load_routing_profile_store().await;
+        assert_eq!(store.len(), 1);
+        // Golden carries fractional weights (0.5) — must survive.
+        assert_eq!(
+            store
+                .get("my-app-0123456789ab")
+                .unwrap()
+                .account_weight_by_key
+                .iter()
+                .map(|(_, w)| w)
+                .collect::<Vec<_>>(),
+            vec![2.0, 0.5],
+        );
+        save_routing_profile_store(&store).await.unwrap();
+
+        let rewritten = std::fs::read_to_string(get_routing_profiles_path()).unwrap();
+        assert_eq!(rewritten, golden, "canonical file must round-trip byte-exact");
+    }
+}
diff --git a/crates/accounts/src/session_affinity.rs b/crates/accounts/src/session_affinity.rs
new file mode 100644
index 000000000..ffb984513
--- /dev/null
+++ b/crates/accounts/src/session_affinity.rs
@@ -0,0 +1,627 @@
+//! Port of `lib/session-affinity.ts` — in-memory session-key → account-index
+//! affinity store (spec 03 §7).
+//!
+//! Tracks the preferred account index per session so follow-up turns stay on
+//! the same account until it becomes unhealthy or stale. In-memory ONLY —
+//! nothing here is ever persisted.
+//!
+//! Behavior contracts (spec 03 §7 + gotchas 24/25):
+//! - 20-min default TTL (floor 1 s), 512-entry default cap (floor 1).
+//! - Session keys are trimmed and truncated to 256 characters.
+//! - Write-version conflict control: an existing LIVE entry with a strictly
+//!   greater `write_version` blocks a write; an EQUAL version overwrites.
+//!   Explicit versions ratchet the shared counter up (`max`).
+//! - `update_last_response_id` never creates entries but DOES slide the TTL.
+//! - `remember` preserves the existing `last_response_id`.
+//! - Eviction is by smallest `updated_at` (oldest), NOT insertion order.
+//! - `clear_all` implements the generation-based full drop (#474): the CLI
+//!   bumps `affinityGeneration` on `switch`/`unpin`/`best` and the proxy drops
+//!   every sticky entry so manual changes take effect mid-thread.
+//!
+//! All time parameters are explicit epoch-ms values (`now`); production
+//! callers pass `cma_core::utils::now_ms()` where the TS defaulted to
+//! `Date.now()`.
+
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use cma_core::logger::{ScopedLogger, create_logger};
+use serde_json::json;
+
+static LOG: LazyLock<ScopedLogger> = LazyLock::new(|| create_logger("session-affinity"));
+
+/// TS `DEFAULT_TTL_MS` = 20 minutes.
+pub const DEFAULT_TTL_MS: i64 = 20 * 60 * 1000;
+/// TS `DEFAULT_MAX_ENTRIES`.
+pub const DEFAULT_MAX_ENTRIES: i64 = 512;
+/// TS `MAX_SESSION_KEY_LENGTH` (characters, post-trim).
+pub const MAX_SESSION_KEY_LENGTH: usize = 256;
+
+/// TS `SessionAffinityOptions`.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct SessionAffinityOptions {
+    /// Entry time-to-live in ms (default 20 min, floored at 1 000 ms).
+    pub ttl_ms: Option<i64>,
+    /// Maximum tracked sessions (default 512, floored at 1).
+    pub max_entries: Option<i64>,
+}
+
+#[derive(Debug, Clone)]
+struct SessionAffinityEntry {
+    account_index: i64,
+    expires_at: i64,
+    last_response_id: Option<String>,
+    updated_at: i64,
+    write_version: i64,
+    /// Rust-only: deterministic tie-break for oldest-entry eviction. The TS
+    /// `findOldestKey` resolves `updated_at` ties by Map insertion order
+    /// (strict `<` keeps the first-iterated key); this sequence number
+    /// reproduces that order over a `HashMap`.
+    seq: u64,
+}
+
+/// Normalize a session key: trim, reject empty, truncate to
+/// [`MAX_SESSION_KEY_LENGTH`] characters (TS `normalizeSessionKey`).
+fn normalize_session_key(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    if trimmed.chars().count() <= MAX_SESSION_KEY_LENGTH {
+        return Some(trimmed.to_string());
+    }
+    Some(trimmed.chars().take(MAX_SESSION_KEY_LENGTH).collect())
+}
+
+/// TS `SessionAffinityStore` — tracks preferred account index per session.
+pub struct SessionAffinityStore {
+    ttl_ms: i64,
+    max_entries: usize,
+    entries: HashMap<String, SessionAffinityEntry>,
+    write_version_counter: i64,
+    next_seq: u64,
+}
+
+impl Default for SessionAffinityStore {
+    fn default() -> Self {
+        Self::new(SessionAffinityOptions::default())
+    }
+}
+
+impl SessionAffinityStore {
+    /// TS constructor: `ttlMs = max(1_000, floor(options.ttlMs ?? DEFAULT))`,
+    /// `maxEntries = max(1, floor(options.maxEntries ?? DEFAULT))`.
+    pub fn new(options: SessionAffinityOptions) -> Self {
+        let ttl_ms = options.ttl_ms.unwrap_or(DEFAULT_TTL_MS).max(1_000);
+        let max_entries = options.max_entries.unwrap_or(DEFAULT_MAX_ENTRIES).max(1) as usize;
+        Self {
+            ttl_ms,
+            max_entries,
+            entries: HashMap::new(),
+            write_version_counter: 0,
+            next_seq: 0,
+        }
+    }
+
+    /// TS `getPreferredAccountIndex` — lazy expiry (`expiresAt <= now`
+    /// deletes), returns the remembered account index while fresh.
+    pub fn get_preferred_account_index(
+        &mut self,
+        session_key: Option<&str>,
+        now: i64,
+    ) -> Option<i64> {
+        let key = normalize_session_key(session_key)?;
+        let entry = self.entries.get(&key)?;
+        if entry.expires_at <= now {
+            self.entries.remove(&key);
+            return None;
+        }
+        Some(entry.account_index)
+    }
+
+    /// TS `remember` — delegates to [`Self::remember_with_version`] with an
+    /// implicit (auto-incremented) write version.
+    pub fn remember(&mut self, session_key: Option<&str>, account_index: i64, now: i64) {
+        self.remember_with_version(session_key, account_index, now, None);
+    }
+
+    /// TS `rememberWithVersion`. No-op on a bad key or negative index. An
+    /// existing LIVE entry with a strictly greater `write_version` blocks the
+    /// write (equal overwrites). Preserves the existing `last_response_id`.
+    pub fn remember_with_version(
+        &mut self,
+        session_key: Option<&str>,
+        account_index: i64,
+        now: i64,
+        write_version: Option<i64>,
+    ) {
+        let Some(key) = normalize_session_key(session_key) else {
+            return;
+        };
+        if account_index < 0 {
+            return;
+        }
+        let normalized_write_version = self.normalize_write_version(write_version);
+
+        let existing = self.entries.get(&key);
+        if let Some(existing_entry) = existing
+            && existing_entry.expires_at > now
+            && existing_entry.write_version > normalized_write_version
+        {
+            return;
+        }
+
+        let last_response_id = existing.and_then(|entry| entry.last_response_id.clone());
+        let entry = SessionAffinityEntry {
+            account_index,
+            expires_at: now + self.ttl_ms,
+            last_response_id,
+            updated_at: now,
+            write_version: normalized_write_version,
+            seq: 0, // assigned by set_entry
+        };
+        self.set_entry(key, entry);
+    }
+
+    /// TS `getLastResponseId` — lazy expiry; returns the trimmed response id
+    /// or `None` when empty/absent.
+    pub fn get_last_response_id(&mut self, session_key: Option<&str>, now: i64) -> Option<String> {
+        let key = normalize_session_key(session_key)?;
+        let entry = self.entries.get(&key)?;
+        if entry.expires_at <= now {
+            self.entries.remove(&key);
+            return None;
+        }
+        let last_response_id = entry
+            .last_response_id
+            .as_deref()
+            .map(str::trim)
+            .unwrap_or("");
+        if last_response_id.is_empty() {
+            None
+        } else {
+            Some(last_response_id.to_string())
+        }
+    }
+
+    /// TS `rememberLastResponseId` — alias of
+    /// [`Self::update_last_response_id`] with an implicit version.
+    pub fn remember_last_response_id(
+        &mut self,
+        session_key: Option<&str>,
+        response_id: Option<&str>,
+        now: i64,
+    ) {
+        self.update_last_response_id(session_key, response_id, now, None);
+    }
+
+    /// TS `updateLastResponseId`. Does NOT create entries: a missing entry is
+    /// a no-op; an expired entry is deleted (no-op). A strictly greater
+    /// existing `write_version` blocks the write. On success the entry's TTL
+    /// slides (`expires_at = now + ttl`).
+    pub fn update_last_response_id(
+        &mut self,
+        session_key: Option<&str>,
+        response_id: Option<&str>,
+        now: i64,
+        write_version: Option<i64>,
+    ) {
+        let key = normalize_session_key(session_key);
+        let normalized_response_id = response_id.map(str::trim).unwrap_or("");
+        let Some(key) = key else { return };
+        if normalized_response_id.is_empty() {
+            return;
+        }
+        // The TS normalizes the write version only after the guards above, so
+        // the implicit counter is not consumed on invalid input.
+        let normalized_write_version = self.normalize_write_version(write_version);
+
+        let Some(entry) = self.entries.get(&key) else {
+            return;
+        };
+        if entry.expires_at <= now {
+            self.entries.remove(&key);
+            return;
+        }
+        if entry.write_version > normalized_write_version {
+            return;
+        }
+
+        let updated = SessionAffinityEntry {
+            expires_at: now + self.ttl_ms,
+            last_response_id: Some(normalized_response_id.to_string()),
+            updated_at: now,
+            write_version: normalized_write_version,
+            ..entry.clone()
+        };
+        self.set_entry(key, updated);
+    }
+
+    /// TS `forgetSession`.
+    pub fn forget_session(&mut self, session_key: Option<&str>) {
+        let Some(key) = normalize_session_key(session_key) else {
+            return;
+        };
+        self.entries.remove(&key);
+    }
+
+    /// TS `forgetAccount` — drops every entry pinned to `account_index`;
+    /// returns the removed count. `0` for negative indexes.
+    pub fn forget_account(&mut self, account_index: i64) -> usize {
+        if account_index < 0 {
+            return 0;
+        }
+        let before = self.entries.len();
+        self.entries
+            .retain(|_, entry| entry.account_index != account_index);
+        let removed = before - self.entries.len();
+        if removed > 0 {
+            LOG.debug(
+                "Cleared session affinity entries for account",
+                Some(&json!({
+                    "accountIndex": account_index,
+                    "removed": removed,
+                })),
+            );
+        }
+        removed
+    }
+
+    /// TS `reindexAfterRemoval` — shifts every entry with
+    /// `account_index > removed_index` down by one; returns the shifted count.
+    /// Entries pointing AT the removed index are untouched (callers use
+    /// [`Self::forget_account`] first).
+    pub fn reindex_after_removal(&mut self, removed_index: i64) -> usize {
+        if removed_index < 0 {
+            return 0;
+        }
+        let mut shifted = 0;
+        for entry in self.entries.values_mut() {
+            if entry.account_index > removed_index {
+                entry.account_index -= 1;
+                shifted += 1;
+            }
+        }
+        shifted
+    }
+
+    /// TS `prune` — deletes expired entries; returns the removed count.
+    pub fn prune(&mut self, now: i64) -> usize {
+        let before = self.entries.len();
+        self.entries.retain(|_, entry| entry.expires_at > now);
+        before - self.entries.len()
+    }
+
+    /// TS `clearAll` — drop every entry. Used when the CLI bumps
+    /// `affinityGeneration` (`switch`/`unpin`/`best`, #474) so manual changes
+    /// take effect even mid-thread.
+    pub fn clear_all(&mut self) {
+        if self.entries.is_empty() {
+            return;
+        }
+        self.entries.clear();
+    }
+
+    /// TS `size`.
+    pub fn size(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// TS `normalizeWriteVersion`: explicit finite version → `max(0, floor)`
+    /// AND ratchets the shared counter up; implicit → `++counter`.
+    fn normalize_write_version(&mut self, write_version: Option<i64>) -> i64 {
+        match write_version {
+            Some(version) => {
+                let normalized = version.max(0);
+                self.write_version_counter = self.write_version_counter.max(normalized);
+                normalized
+            }
+            None => {
+                self.write_version_counter += 1;
+                self.write_version_counter
+            }
+        }
+    }
+
+    /// TS `setEntry` — evicts the oldest entry (smallest `updated_at`, ties
+    /// broken by insertion order) when inserting a NEW key at capacity.
+    fn set_entry(&mut self, key: String, mut entry: SessionAffinityEntry) {
+        let existing_seq = self.entries.get(&key).map(|existing| existing.seq);
+        if self.entries.len() >= self.max_entries
+            && existing_seq.is_none()
+            && let Some(oldest) = self.find_oldest_key()
+        {
+            self.entries.remove(&oldest);
+        }
+        entry.seq = existing_seq.unwrap_or_else(|| {
+            self.next_seq += 1;
+            self.next_seq
+        });
+        self.entries.insert(key, entry);
+    }
+
+    /// TS `findOldestKey` — full linear scan for the smallest `updated_at`
+    /// (strict `<`, so ties keep the earliest-inserted entry).
+    fn find_oldest_key(&self) -> Option<String> {
+        self.entries
+            .iter()
+            .min_by_key(|(_, entry)| (entry.updated_at, entry.seq))
+            .map(|(key, _)| key.clone())
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/session-affinity.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn store(ttl_ms: i64, max_entries: i64) -> SessionAffinityStore {
+        SessionAffinityStore::new(SessionAffinityOptions {
+            ttl_ms: Some(ttl_ms),
+            max_entries: Some(max_entries),
+        })
+    }
+
+    #[test]
+    fn returns_remembered_account_while_entry_is_fresh() {
+        let mut store = store(10_000, DEFAULT_MAX_ENTRIES);
+        store.remember(Some("session-a"), 2, 1_000);
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 5_000),
+            Some(2)
+        );
+    }
+
+    #[test]
+    fn expires_entries_after_ttl() {
+        let mut store = store(1_000, DEFAULT_MAX_ENTRIES);
+        store.remember(Some("session-a"), 1, 1_000);
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 2_500),
+            None
+        );
+        assert_eq!(store.size(), 0);
+    }
+
+    #[test]
+    fn evicts_oldest_entry_when_max_size_is_reached() {
+        let mut store = store(60_000, 2);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 1, 2_000);
+        store.remember(Some("s3"), 2, 3_000);
+
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 3_100), None);
+        assert_eq!(store.get_preferred_account_index(Some("s2"), 3_100), Some(1));
+        assert_eq!(store.get_preferred_account_index(Some("s3"), 3_100), Some(2));
+    }
+
+    #[test]
+    fn forgets_all_sessions_mapped_to_account() {
+        let mut store = store(60_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 1, 1_000);
+        store.remember(Some("s3"), 1, 1_000);
+
+        let removed = store.forget_account(1);
+        assert_eq!(removed, 2);
+        assert_eq!(store.get_preferred_account_index(Some("s2"), 1_500), None);
+        assert_eq!(store.get_preferred_account_index(Some("s3"), 1_500), None);
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 1_500), Some(0));
+    }
+
+    #[test]
+    fn reindexes_sessions_after_account_removal() {
+        let mut store = store(60_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 2, 1_000);
+        store.remember(Some("s3"), 3, 1_000);
+
+        let shifted = store.reindex_after_removal(1);
+        assert_eq!(shifted, 2);
+        assert_eq!(store.get_preferred_account_index(Some("s2"), 1_500), Some(1));
+        assert_eq!(store.get_preferred_account_index(Some("s3"), 1_500), Some(2));
+    }
+
+    #[test]
+    fn rejects_invalid_session_keys_and_invalid_account_indices() {
+        let mut store = store(10_000, 4);
+        store.remember(Some("   "), 1, 1_000);
+        store.remember(Some("session-y"), -1, 1_000);
+
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-y"), 2_000),
+            None
+        );
+        assert_eq!(store.get_preferred_account_index(None, 2_000), None);
+        assert_eq!(store.size(), 0);
+    }
+
+    #[test]
+    fn truncates_oversized_session_keys_and_retrieves_by_truncated_form() {
+        let mut store = store(10_000, 8);
+        let long_key = format!("  {}  ", "x".repeat(300));
+        let truncated = "x".repeat(256);
+        store.remember(Some(&long_key), 3, 1_000);
+
+        assert_eq!(
+            store.get_preferred_account_index(Some(&truncated), 2_000),
+            Some(3)
+        );
+    }
+
+    #[test]
+    fn does_not_evict_when_updating_an_existing_key_at_capacity() {
+        let mut store = store(60_000, 2);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 1, 2_000);
+        store.remember(Some("s2"), 2, 3_000);
+
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 3_500), Some(0));
+        assert_eq!(store.get_preferred_account_index(Some("s2"), 3_500), Some(2));
+        assert_eq!(store.size(), 2);
+    }
+
+    #[test]
+    fn forgets_a_specific_session_and_noops_on_blank_session_key() {
+        let mut store = store(60_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+        store.forget_session(Some("   "));
+        store.forget_session(Some("s1"));
+
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 2_000), None);
+        assert_eq!(store.size(), 0);
+    }
+
+    #[test]
+    fn returns_zero_for_invalid_forget_reindex_requests() {
+        let mut store = store(60_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+
+        assert_eq!(store.forget_account(-1), 0);
+        assert_eq!(store.reindex_after_removal(-1), 0);
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 2_000), Some(0));
+    }
+
+    #[test]
+    fn prunes_expired_sessions_and_keeps_non_expired_entries() {
+        let mut store = store(1_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 1, 2_000);
+
+        assert_eq!(store.prune(2_001), 1);
+        assert_eq!(store.get_preferred_account_index(Some("s1"), 2_001), None);
+        assert_eq!(store.get_preferred_account_index(Some("s2"), 2_001), Some(1));
+    }
+
+    #[test]
+    fn updates_and_retrieves_the_last_response_id_for_a_live_session() {
+        let mut store = store(10_000, 4);
+        store.remember(Some("session-a"), 1, 1_000);
+        store.update_last_response_id(Some("session-a"), Some("resp_123"), 2_000, None);
+
+        assert_eq!(
+            store.get_last_response_id(Some("session-a"), 2_500),
+            Some("resp_123".to_string())
+        );
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 2_500),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn does_not_persist_response_ids_for_missing_or_expired_sessions() {
+        let mut store = store(1_000, 4);
+        store.update_last_response_id(Some("missing"), Some("resp_missing"), 1_000, None);
+        assert_eq!(store.get_last_response_id(Some("missing"), 1_500), None);
+
+        store.remember(Some("session-a"), 1, 1_000);
+        store.update_last_response_id(Some("session-a"), Some("resp_123"), 2_500, None);
+        assert_eq!(store.get_last_response_id(Some("session-a"), 2_500), None);
+        assert_eq!(store.size(), 0);
+    }
+
+    #[test]
+    fn preserves_response_id_when_account_index_is_updated_via_remember() {
+        let mut store = store(10_000, 4);
+        store.remember(Some("session-a"), 1, 1_000);
+        store.update_last_response_id(Some("session-a"), Some("resp_123"), 2_000, None);
+        store.remember(Some("session-a"), 2, 3_000);
+
+        assert_eq!(
+            store.get_last_response_id(Some("session-a"), 3_500),
+            Some("resp_123".to_string())
+        );
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 3_500),
+            Some(2)
+        );
+    }
+
+    #[test]
+    fn ignores_stale_response_id_writes_from_older_overlapping_requests() {
+        let mut store = store(10_000, 4);
+        store.remember_with_version(Some("session-a"), 1, 1_000, Some(1));
+        store.update_last_response_id(Some("session-a"), Some("resp_first"), 2_000, Some(1));
+        store.remember_with_version(Some("session-a"), 2, 3_000, Some(2));
+        store.update_last_response_id(Some("session-a"), Some("resp_second"), 4_000, Some(2));
+
+        store.remember_with_version(Some("session-a"), 1, 5_000, Some(1));
+        store.update_last_response_id(Some("session-a"), Some("resp_stale"), 5_000, Some(1));
+
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 5_500),
+            Some(2)
+        );
+        assert_eq!(
+            store.get_last_response_id(Some("session-a"), 5_500),
+            Some("resp_second".to_string())
+        );
+    }
+
+    #[test]
+    fn generates_distinct_default_write_versions_for_same_timestamp_overlaps() {
+        let mut store = store(10_000, 4);
+        store.remember_with_version(Some("session-a"), 0, 1_000, None);
+        store.remember_with_version(Some("session-a"), 1, 1_000, None);
+
+        assert_eq!(
+            store.get_preferred_account_index(Some("session-a"), 1_500),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn equal_write_version_overwrites_but_strictly_greater_blocks() {
+        // Spec gotcha 24: strictly-greater blocks; EQUAL overwrites.
+        let mut store = store(10_000, 4);
+        store.remember_with_version(Some("s"), 1, 1_000, Some(5));
+        store.remember_with_version(Some("s"), 2, 2_000, Some(5));
+        assert_eq!(store.get_preferred_account_index(Some("s"), 2_500), Some(2));
+        store.remember_with_version(Some("s"), 3, 3_000, Some(4));
+        assert_eq!(store.get_preferred_account_index(Some("s"), 3_500), Some(2));
+        // An EXPIRED higher-version entry no longer blocks.
+        let mut expired = self::tests_store_expired();
+        expired.remember_with_version(Some("s"), 1, 1_000, Some(9));
+        expired.remember_with_version(Some("s"), 2, 5_000, Some(3));
+        assert_eq!(expired.get_preferred_account_index(Some("s"), 5_500), Some(2));
+    }
+
+    fn tests_store_expired() -> SessionAffinityStore {
+        SessionAffinityStore::new(SessionAffinityOptions {
+            ttl_ms: Some(1_000),
+            max_entries: Some(4),
+        })
+    }
+
+    #[test]
+    fn explicit_versions_ratchet_the_shared_counter() {
+        let mut store = store(10_000, 4);
+        store.remember_with_version(Some("a"), 1, 1_000, Some(10));
+        // Implicit version continues ABOVE the ratcheted counter.
+        store.remember_with_version(Some("a"), 2, 2_000, None);
+        assert_eq!(store.get_preferred_account_index(Some("a"), 2_500), Some(2));
+    }
+
+    #[test]
+    fn clear_all_drops_every_entry() {
+        let mut store = store(60_000, 10);
+        store.remember(Some("s1"), 0, 1_000);
+        store.remember(Some("s2"), 1, 1_000);
+        store.clear_all();
+        assert_eq!(store.size(), 0);
+    }
+
+    #[test]
+    fn negative_ttl_and_max_entries_clamp_to_floors() {
+        let mut store = store(-5, -3); // ttl → 1_000, max_entries → 1
+        store.remember(Some("a"), 0, 1_000);
+        store.remember(Some("b"), 1, 2_000);
+        assert_eq!(store.size(), 1);
+        assert_eq!(store.get_preferred_account_index(Some("b"), 2_500), Some(1));
+        assert_eq!(store.get_preferred_account_index(Some("b"), 3_000), None);
+    }
+}
diff --git a/crates/auth/Cargo.toml b/crates/auth/Cargo.toml
new file mode 100644
index 000000000..9754cc401
--- /dev/null
+++ b/crates/auth/Cargo.toml
@@ -0,0 +1,39 @@
+[package]
+name = "cma-auth"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde.workspace = true
+serde_json.workspace = true
+reqwest.workspace = true
+axum.workspace = true
+hyper.workspace = true
+hyper-util.workspace = true
+http.workspace = true
+http-body-util.workspace = true
+sha2.workspace = true
+subtle.workspace = true
+base64.workspace = true
+rand.workspace = true
+uuid.workspace = true
+url.workspace = true
+tokio.workspace = true
+futures.workspace = true
+bytes.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+wiremock.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/auth/assets/oauth-success.html b/crates/auth/assets/oauth-success.html
new file mode 100644
index 000000000..11a8c6f5f
--- /dev/null
+++ b/crates/auth/assets/oauth-success.html
@@ -0,0 +1,126 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Codex Sign-In Complete</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #0b0b0b;
+      --panel: #111111;
+      --text: #f2f2f2;
+      --muted: #a3a3a3;
+      --line: #232323;
+      --ok: #7cf0a6;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      background: var(--bg);
+      color: var(--text);
+      font-family: "Geist Mono", "GeistMono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+      padding: 24px;
+    }
+
+    main {
+      width: min(520px, 100%);
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      padding: 20px;
+      display: grid;
+      gap: 14px;
+    }
+
+    h1 {
+      margin: 0;
+      font-size: 20px;
+      font-weight: 600;
+      letter-spacing: -0.02em;
+    }
+
+    p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    .status {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      color: var(--ok);
+      font-size: 13px;
+    }
+
+    .dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: currentColor;
+    }
+
+    dl {
+      margin: 0;
+      display: grid;
+      grid-template-columns: 120px 1fr;
+      gap: 8px 12px;
+      font-size: 13px;
+    }
+
+    dt {
+      color: var(--muted);
+    }
+
+    dd {
+      margin: 0;
+      color: var(--text);
+      word-break: break-word;
+    }
+
+    code {
+      background: #171717;
+      border: 1px solid var(--line);
+      border-radius: 6px;
+      padding: 2px 6px;
+      font-family: inherit;
+      font-size: 12px;
+    }
+
+    @media (max-width: 520px) {
+      dl {
+        grid-template-columns: 1fr;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main role="main" aria-label="OAuth callback received">
+    <h1>Sign-in complete</h1>
+    <p>Return to your terminal to finish Codex login.</p>
+
+    <div class="status" aria-live="polite">
+      <span class="dot" aria-hidden="true"></span>
+      Callback received
+    </div>
+
+    <dl>
+      <dt>Endpoint</dt>
+      <dd><code>localhost:1455</code></dd>
+      <dt>Flow</dt>
+      <dd>OAuth callback captured</dd>
+      <dt>Next</dt>
+      <dd>Close this tab and continue in terminal</dd>
+    </dl>
+  </main>
+</body>
+</html>
\ No newline at end of file
diff --git a/crates/auth/src/auth_rate_limit.rs b/crates/auth/src/auth_rate_limit.rs
new file mode 100644
index 000000000..b26e961b2
--- /dev/null
+++ b/crates/auth/src/auth_rate_limit.rs
@@ -0,0 +1,504 @@
+//! Port of `lib/auth-rate-limit.ts` — in-memory sliding-window limiter for
+//! interactive auth (login) attempts.
+//!
+//! Behavior source: specs/04-rotation.md §3.
+//!
+//! Module-level mutable state (a map and a config object) — process-wide
+//! singleton semantics, exactly like the TS module. Keys are
+//! `accountId.toLowerCase().trim()`. Timestamps strictly greater than
+//! `now - windowMs` are kept by the prune (`> cutoff`).
+//!
+//! NEVER persisted; in-memory only.
+
+use std::collections::HashMap;
+use std::sync::{LazyLock, Mutex, MutexGuard};
+
+use cma_core::utils::now_ms;
+
+/// `AuthRateLimitConfig` — `{ maxAttempts, windowMs }`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct AuthRateLimitConfig {
+    pub max_attempts: u32,
+    pub window_ms: i64,
+}
+
+/// Private default `{ maxAttempts: 5, windowMs: 60_000 }`.
+const DEFAULT_CONFIG: AuthRateLimitConfig = AuthRateLimitConfig {
+    max_attempts: 5,
+    window_ms: 60_000,
+};
+
+/// Partial-config patch for [`configure_auth_rate_limit`] (TS
+/// `Partial<AuthRateLimitConfig>`).
+#[derive(Clone, Copy, Debug, Default)]
+pub struct AuthRateLimitConfigPatch {
+    pub max_attempts: Option<u32>,
+    pub window_ms: Option<i64>,
+}
+
+struct LimiterState {
+    config: AuthRateLimitConfig,
+    /// `attemptsByAccount` — timestamps of recorded attempts per lowercased
+    /// account key.
+    attempts_by_account: HashMap<String, Vec<i64>>,
+}
+
+static STATE: LazyLock<Mutex<LimiterState>> = LazyLock::new(|| {
+    Mutex::new(LimiterState {
+        config: DEFAULT_CONFIG,
+        attempts_by_account: HashMap::new(),
+    })
+});
+
+fn lock_state() -> MutexGuard<'static, LimiterState> {
+    STATE.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// `configureAuthRateLimit(newConfig)` — merges into the current config.
+/// Persists across calls; NOT reset by [`reset_all_auth_rate_limits`].
+pub fn configure_auth_rate_limit(patch: AuthRateLimitConfigPatch) {
+    let mut state = lock_state();
+    if let Some(max_attempts) = patch.max_attempts {
+        state.config.max_attempts = max_attempts;
+    }
+    if let Some(window_ms) = patch.window_ms {
+        state.config.window_ms = window_ms;
+    }
+}
+
+/// `getAuthRateLimitConfig()` — returns a copy.
+pub fn get_auth_rate_limit_config() -> AuthRateLimitConfig {
+    lock_state().config
+}
+
+/// `getAccountKey` — `accountId.toLowerCase().trim()`.
+fn account_key(account_id: &str) -> String {
+    account_id.to_lowercase().trim().to_string()
+}
+
+/// `pruneOldAttempts` — keep only timestamps strictly greater than
+/// `now - windowMs` (mutates the stored record, as in TS).
+fn prune_old_attempts(timestamps: &mut Vec<i64>, window_ms: i64, now: i64) {
+    let cutoff = now - window_ms;
+    timestamps.retain(|ts| *ts > cutoff);
+}
+
+/// `canAttemptAuth(accountId)` — unknown key ⇒ true; else prune, then
+/// `count < maxAttempts`.
+pub fn can_attempt_auth(account_id: &str) -> bool {
+    can_attempt_auth_at(account_id, now_ms())
+}
+
+/// [`can_attempt_auth`] with an injectable clock (tests).
+pub fn can_attempt_auth_at(account_id: &str, now: i64) -> bool {
+    let key = account_key(account_id);
+    let mut state = lock_state();
+    let LimiterState {
+        config,
+        attempts_by_account,
+    } = &mut *state;
+    let Some(record) = attempts_by_account.get_mut(&key) else {
+        return true;
+    };
+    prune_old_attempts(record, config.window_ms, now);
+    (record.len() as u32) < config.max_attempts
+}
+
+/// `recordAuthAttempt(accountId)` — prune then push `now`. No cap enforcement
+/// here; callers should check first.
+pub fn record_auth_attempt(account_id: &str) {
+    record_auth_attempt_at(account_id, now_ms());
+}
+
+/// [`record_auth_attempt`] with an injectable clock (tests).
+pub fn record_auth_attempt_at(account_id: &str, now: i64) {
+    let key = account_key(account_id);
+    let mut state = lock_state();
+    let LimiterState {
+        config,
+        attempts_by_account,
+    } = &mut *state;
+    let record = attempts_by_account.entry(key).or_default();
+    prune_old_attempts(record, config.window_ms, now);
+    record.push(now);
+}
+
+/// `getAttemptsRemaining(accountId)` — `max(0, maxAttempts - count)` after
+/// prune; unknown key ⇒ `maxAttempts`.
+pub fn get_attempts_remaining(account_id: &str) -> u32 {
+    get_attempts_remaining_at(account_id, now_ms())
+}
+
+/// [`get_attempts_remaining`] with an injectable clock (tests).
+pub fn get_attempts_remaining_at(account_id: &str, now: i64) -> u32 {
+    let key = account_key(account_id);
+    let mut state = lock_state();
+    let LimiterState {
+        config,
+        attempts_by_account,
+    } = &mut *state;
+    let Some(record) = attempts_by_account.get_mut(&key) else {
+        return config.max_attempts;
+    };
+    prune_old_attempts(record, config.window_ms, now);
+    config.max_attempts.saturating_sub(record.len() as u32)
+}
+
+/// `getTimeUntilReset(accountId)` — 0 when no live attempts; else
+/// `max(0, min(timestamps) + windowMs - now)` after prune.
+pub fn get_time_until_reset(account_id: &str) -> i64 {
+    get_time_until_reset_at(account_id, now_ms())
+}
+
+/// [`get_time_until_reset`] with an injectable clock (tests).
+pub fn get_time_until_reset_at(account_id: &str, now: i64) -> i64 {
+    let key = account_key(account_id);
+    let mut state = lock_state();
+    let LimiterState {
+        config,
+        attempts_by_account,
+    } = &mut *state;
+    let Some(record) = attempts_by_account.get_mut(&key) else {
+        return 0;
+    };
+    if record.is_empty() {
+        return 0;
+    }
+    prune_old_attempts(record, config.window_ms, now);
+    if record.is_empty() {
+        return 0;
+    }
+    let oldest_attempt = record.iter().copied().min().unwrap_or(now);
+    let reset_time = oldest_attempt + config.window_ms;
+    (reset_time - now).max(0)
+}
+
+/// `resetAuthRateLimit(accountId)` — delete the account's record.
+pub fn reset_auth_rate_limit(account_id: &str) {
+    let key = account_key(account_id);
+    lock_state().attempts_by_account.remove(&key);
+}
+
+/// `resetAllAuthRateLimits()` — clear the map (config untouched).
+pub fn reset_all_auth_rate_limits() {
+    lock_state().attempts_by_account.clear();
+}
+
+/// `AuthRateLimitError` — message deliberately omits the accountId:
+/// `` `Auth rate limit exceeded for account. Retry after ${ceil(resetAfterMs/1000)}s` ``.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AuthRateLimitError {
+    pub account_id: String,
+    pub attempts_remaining: u32,
+    pub reset_after_ms: i64,
+    message: String,
+}
+
+impl AuthRateLimitError {
+    pub fn new(account_id: impl Into<String>, attempts_remaining: u32, reset_after_ms: i64) -> Self {
+        let reset_seconds = (reset_after_ms as f64 / 1000.0).ceil() as i64;
+        Self {
+            account_id: account_id.into(),
+            attempts_remaining,
+            reset_after_ms,
+            message: format!(
+                "Auth rate limit exceeded for account. Retry after {reset_seconds}s"
+            ),
+        }
+    }
+
+    /// TS `error.name`.
+    pub fn name(&self) -> &'static str {
+        "AuthRateLimitError"
+    }
+
+    /// TS `error.message`.
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl std::fmt::Display for AuthRateLimitError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for AuthRateLimitError {}
+
+/// `checkAuthRateLimit(accountId)` — Err(`AuthRateLimitError`) when
+/// `!canAttemptAuth(accountId)`.
+pub fn check_auth_rate_limit(account_id: &str) -> Result<(), AuthRateLimitError> {
+    check_auth_rate_limit_at(account_id, now_ms())
+}
+
+/// [`check_auth_rate_limit`] with an injectable clock (tests).
+pub fn check_auth_rate_limit_at(account_id: &str, now: i64) -> Result<(), AuthRateLimitError> {
+    if can_attempt_auth_at(account_id, now) {
+        return Ok(());
+    }
+    Err(AuthRateLimitError::new(
+        account_id,
+        get_attempts_remaining_at(account_id, now),
+        get_time_until_reset_at(account_id, now),
+    ))
+}
+
+// ============================================================================
+// Tests (ported from test/auth-rate-limit.test.ts)
+//
+// Module state is process-global, so every test takes the shared `serial_test`
+// key `auth_rate_limit` and re-applies the TS beforeEach (reset + default
+// config). Fake timers are ported via the `_at` clock-injection variants,
+// with epoch 0 as the vitest `setSystemTime(new Date(0))` baseline.
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    /// vitest beforeEach: `resetAllAuthRateLimits()` +
+    /// `configureAuthRateLimit({ maxAttempts: 5, windowMs: 60_000 })`.
+    fn before_each() {
+        reset_all_auth_rate_limits();
+        configure_auth_rate_limit(AuthRateLimitConfigPatch {
+            max_attempts: Some(5),
+            window_ms: Some(60_000),
+        });
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn can_attempt_auth_allows_first_attempt() {
+        before_each();
+        assert!(can_attempt_auth_at("user@example.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn can_attempt_auth_allows_attempts_up_to_limit() {
+        before_each();
+        for _ in 0..4 {
+            record_auth_attempt_at("user@example.com", 0);
+        }
+        assert!(can_attempt_auth_at("user@example.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn can_attempt_auth_denies_after_limit_reached() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user@example.com", 0);
+        }
+        assert!(!can_attempt_auth_at("user@example.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn can_attempt_auth_is_case_insensitive() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("User@Example.COM", 0);
+        }
+        assert!(!can_attempt_auth_at("user@example.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn record_auth_attempt_records_attempts() {
+        before_each();
+        assert_eq!(get_attempts_remaining_at("user@test.com", 0), 5);
+        record_auth_attempt_at("user@test.com", 0);
+        assert_eq!(get_attempts_remaining_at("user@test.com", 0), 4);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn record_auth_attempt_tracks_accounts_separately() {
+        before_each();
+        record_auth_attempt_at("user1@test.com", 0);
+        record_auth_attempt_at("user1@test.com", 0);
+        record_auth_attempt_at("user2@test.com", 0);
+
+        assert_eq!(get_attempts_remaining_at("user1@test.com", 0), 3);
+        assert_eq!(get_attempts_remaining_at("user2@test.com", 0), 4);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn sliding_window_expires_old_attempts() {
+        before_each();
+        record_auth_attempt_at("user@test.com", 0);
+        record_auth_attempt_at("user@test.com", 0);
+
+        // vi.setSystemTime(new Date(61_000))
+        assert_eq!(get_attempts_remaining_at("user@test.com", 61_000), 5);
+        assert!(can_attempt_auth_at("user@test.com", 61_000));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn sliding_window_allows_new_attempts_after_window_expires() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user@test.com", 0);
+        }
+        assert!(!can_attempt_auth_at("user@test.com", 0));
+
+        assert!(can_attempt_auth_at("user@test.com", 61_000));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn get_time_until_reset_returns_zero_for_new_accounts() {
+        before_each();
+        assert_eq!(get_time_until_reset_at("new@test.com", 0), 0);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn get_time_until_reset_returns_remaining_window_time() {
+        before_each();
+        record_auth_attempt_at("user@test.com", 0);
+        assert_eq!(get_time_until_reset_at("user@test.com", 30_000), 30_000);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn get_time_until_reset_returns_zero_after_window_expires() {
+        before_each();
+        record_auth_attempt_at("user@test.com", 0);
+        assert_eq!(get_time_until_reset_at("user@test.com", 61_000), 0);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn reset_auth_rate_limit_clears_attempts_for_specific_account() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user@test.com", 0);
+        }
+        assert!(!can_attempt_auth_at("user@test.com", 0));
+
+        reset_auth_rate_limit("user@test.com");
+
+        assert!(can_attempt_auth_at("user@test.com", 0));
+        assert_eq!(get_attempts_remaining_at("user@test.com", 0), 5);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn reset_all_auth_rate_limits_clears_all_accounts() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user1@test.com", 0);
+            record_auth_attempt_at("user2@test.com", 0);
+        }
+
+        reset_all_auth_rate_limits();
+
+        assert!(can_attempt_auth_at("user1@test.com", 0));
+        assert!(can_attempt_auth_at("user2@test.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn check_auth_rate_limit_does_not_throw_when_under_limit() {
+        before_each();
+        assert!(check_auth_rate_limit_at("user@test.com", 0).is_ok());
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn check_auth_rate_limit_throws_when_over_limit() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user@test.com", 0);
+        }
+        assert!(check_auth_rate_limit_at("user@test.com", 0).is_err());
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn check_auth_rate_limit_includes_reset_time_in_error() {
+        before_each();
+        for _ in 0..5 {
+            record_auth_attempt_at("user@test.com", 0);
+        }
+
+        let error = check_auth_rate_limit_at("user@test.com", 0)
+            .expect_err("should have thrown");
+        assert_eq!(error.reset_after_ms, 60_000);
+        assert_eq!(error.attempts_remaining, 0);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn configure_updates_max_attempts() {
+        before_each();
+        configure_auth_rate_limit(AuthRateLimitConfigPatch {
+            max_attempts: Some(3),
+            window_ms: None,
+        });
+
+        for _ in 0..3 {
+            record_auth_attempt_at("user@test.com", 0);
+        }
+        assert!(!can_attempt_auth_at("user@test.com", 0));
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn configure_updates_window_duration() {
+        before_each();
+        configure_auth_rate_limit(AuthRateLimitConfigPatch {
+            max_attempts: None,
+            window_ms: Some(30_000),
+        });
+
+        record_auth_attempt_at("user@test.com", 0);
+        assert_eq!(get_attempts_remaining_at("user@test.com", 31_000), 5);
+    }
+
+    #[test]
+    #[serial(auth_rate_limit)]
+    fn configure_preserves_other_config_values() {
+        before_each();
+        configure_auth_rate_limit(AuthRateLimitConfigPatch {
+            max_attempts: Some(10),
+            window_ms: None,
+        });
+        let config = get_auth_rate_limit_config();
+
+        assert_eq!(config.max_attempts, 10);
+        assert_eq!(config.window_ms, 60_000);
+    }
+
+    #[test]
+    fn auth_rate_limit_error_has_correct_name() {
+        let error = AuthRateLimitError::new("test@test.com", 0, 30_000);
+        assert_eq!(error.name(), "AuthRateLimitError");
+    }
+
+    #[test]
+    fn auth_rate_limit_error_includes_account_and_timing_info() {
+        let error = AuthRateLimitError::new("test@test.com", 0, 30_000);
+        assert_eq!(error.account_id, "test@test.com");
+        assert_eq!(error.attempts_remaining, 0);
+        assert_eq!(error.reset_after_ms, 30_000);
+    }
+
+    #[test]
+    fn auth_rate_limit_error_has_human_readable_message() {
+        let error = AuthRateLimitError::new("test@test.com", 0, 30_000);
+        assert!(error.message().contains("30s"), "{}", error.message());
+        // Exact frozen text (message deliberately omits the accountId).
+        assert_eq!(
+            error.message(),
+            "Auth rate limit exceeded for account. Retry after 30s"
+        );
+        assert!(!error.message().contains("test@test.com"));
+    }
+}
diff --git a/crates/auth/src/browser.rs b/crates/auth/src/browser.rs
new file mode 100644
index 000000000..6ceba1102
--- /dev/null
+++ b/crates/auth/src/browser.rs
@@ -0,0 +1,498 @@
+//! Port of `lib/auth/browser.ts` — best-effort cross-platform browser open +
+//! clipboard copy, including WSL interop (spec 07 §6).
+//!
+//! Key contracts (spec 07 gotchas 9–10):
+//! - `CODEX_AUTH_NO_BROWSER` non-empty decides ALONE — `CODEX_AUTH_NO_BROWSER=0`
+//!   explicitly re-enables launching even with `BROWSER=none`.
+//! - Windows goes through `powershell.exe -NoLogo -NoProfile -Command` (never
+//!   `cmd start`, which breaks on `&`/`:` in URLs) with backtick/`$`/`"`
+//!   escaping.
+//! - WSL prefers `wslview` (wslu → Windows default browser), then PowerShell
+//!   interop, then falls through to the Linux opener (an in-distro X/Wayland
+//!   browser is possible). Clipboard: `clip.exe` → PowerShell → Linux tools.
+//! - All spawns are fire-and-forget; spawn/stdin errors are swallowed. The
+//!   return value means "a launch was ATTEMPTED", not "it worked".
+//! - Callers must redact sensitive tokens from `url`/`text` beforehand;
+//!   nothing here logs or redacts.
+
+use std::io::Write;
+use std::path::Path;
+use std::process::{Command, Stdio};
+
+use cma_core::constants::PLATFORM_OPENERS;
+use cma_core::wsl::is_wsl;
+
+/// `$BROWSER` values that disable launching (TS `BROWSER_DISABLED_VALUES`).
+const BROWSER_DISABLED_VALUES: [&str; 5] = ["0", "false", "no", "off", "none"];
+/// `$CODEX_AUTH_NO_BROWSER` values that suppress launching
+/// (TS `NO_BROWSER_TRUTHY_VALUES`).
+const NO_BROWSER_TRUTHY_VALUES: [&str; 4] = ["1", "true", "yes", "on"];
+
+/// Gets the platform-specific command to open a URL in the default browser
+/// (TS `getBrowserOpener`).
+pub fn get_browser_opener() -> &'static str {
+    if cfg!(target_os = "macos") {
+        PLATFORM_OPENERS.darwin
+    } else if cfg!(windows) {
+        PLATFORM_OPENERS.win32
+    } else {
+        PLATFORM_OPENERS.linux
+    }
+}
+
+/// Whether browser launching is suppressed by the environment
+/// (TS `isBrowserLaunchSuppressed`).
+pub fn is_browser_launch_suppressed() -> bool {
+    let no_browser = std::env::var("CODEX_AUTH_NO_BROWSER").ok();
+    let browser = std::env::var("BROWSER").ok();
+    is_browser_launch_suppressed_from(no_browser.as_deref(), browser.as_deref())
+}
+
+/// Pure decision core for [`is_browser_launch_suppressed`] (injected env
+/// values — the TS tests mutate `process.env`; Rust tests inject).
+fn is_browser_launch_suppressed_from(no_browser: Option<&str>, browser: Option<&str>) -> bool {
+    let explicit_no_browser = no_browser.unwrap_or("").trim().to_lowercase();
+    if !explicit_no_browser.is_empty() {
+        // Non-empty, it alone decides — `0`/`false` explicitly UN-suppress.
+        return NO_BROWSER_TRUTHY_VALUES.contains(&explicit_no_browser.as_str());
+    }
+
+    let browser_setting = browser.unwrap_or("").trim().to_lowercase();
+    BROWSER_DISABLED_VALUES.contains(&browser_setting.as_str())
+}
+
+/// Whether the trailing path component of `command` carries an extension
+/// (TS regex `/\.[^\\/]+$/`).
+fn has_extension(command: &str) -> bool {
+    match command.rfind('.') {
+        Some(index) => {
+            let suffix = &command[index + 1..];
+            !suffix.is_empty() && !suffix.contains('/') && !suffix.contains('\\')
+        }
+        None => false,
+    }
+}
+
+/// Determines whether a given command name exists on the system PATH
+/// (TS `commandExists`). Windows resolves via PATHEXT (default
+/// `.EXE;.CMD;.BAT;.COM`); POSIX requires a regular file with ≥1 exec bit.
+fn command_exists(command: &str) -> bool {
+    if command.is_empty() {
+        return false;
+    }
+
+    // Unreachable from openBrowserUrl on win32 (PowerShell is used instead),
+    // kept for parity: `start` is a cmd builtin, not a PATH entry.
+    if cfg!(windows) && command.eq_ignore_ascii_case("start") {
+        return true;
+    }
+
+    let path_value = std::env::var("PATH").unwrap_or_default();
+    let delimiter = if cfg!(windows) { ';' } else { ':' };
+    let entries: Vec<&str> = path_value
+        .split(delimiter)
+        .filter(|entry| !entry.is_empty())
+        .collect();
+    if entries.is_empty() {
+        return false;
+    }
+
+    if cfg!(windows) {
+        let pathext = std::env::var("PATHEXT").unwrap_or_default();
+        let pathext = if pathext.is_empty() {
+            ".EXE;.CMD;.BAT;.COM".to_string()
+        } else {
+            pathext
+        };
+        let exts: Vec<&str> = pathext.split(';').filter(|ext| !ext.is_empty()).collect();
+        let direct = has_extension(command);
+        for entry in entries {
+            if direct {
+                if Path::new(entry).join(command).exists() {
+                    return true;
+                }
+                continue;
+            }
+            for ext in &exts {
+                if Path::new(entry).join(format!("{command}{ext}")).exists() {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    for entry in entries {
+        let candidate = Path::new(entry).join(command);
+        let Ok(metadata) = std::fs::metadata(&candidate) else {
+            continue;
+        };
+        if !metadata.is_file() {
+            continue;
+        }
+        // On POSIX, ensure at least one executable bit is set.
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            if metadata.permissions().mode() & 0o111 == 0 {
+                continue;
+            }
+        }
+        return true;
+    }
+    false
+}
+
+/// Escape a value for safe interpolation into a double-quoted PowerShell
+/// string: neutralizes backticks, `$` sub-expression injection, and embedded
+/// double quotes (TS `escapeForPowerShell` — same replacement ORDER).
+fn escape_for_powershell(value: &str) -> String {
+    value
+        .replace('`', "``")
+        .replace('$', "`$")
+        .replace('"', "\"\"")
+}
+
+/// Spawn a child fire-and-forget: stdout/stderr discarded, optional text
+/// piped to stdin, all errors (spawn, EPIPE on a dead child's stdin)
+/// swallowed. Returns once the spawn was ATTEMPTED — mirroring the TS
+/// contract where `spawn()` errors surface asynchronously and are ignored.
+fn spawn_fire_and_forget(program: &str, args: &[&str], stdin_text: Option<&str>) -> bool {
+    let mut command = Command::new(program);
+    command
+        .args(args)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .stdin(if stdin_text.is_some() {
+            Stdio::piped()
+        } else {
+            Stdio::null()
+        });
+    match command.spawn() {
+        Ok(mut child) => {
+            if let Some(text) = stdin_text
+                && let Some(mut stdin) = child.stdin.take()
+            {
+                // A child that dies before draining stdin yields EPIPE
+                // here — swallowed, matching the TS stdin error handler.
+                let _ = stdin.write_all(text.as_bytes());
+            }
+            // Detach: reap in a background thread so no zombie lingers
+            // (Node's libuv reaps automatically; std Rust does not).
+            std::thread::spawn(move || {
+                let _ = child.wait();
+            });
+            true
+        }
+        // TS parity: spawn failures are emitted async and swallowed; the
+        // launch still counts as attempted.
+        Err(_) => true,
+    }
+}
+
+/// Run a PowerShell command, fire-and-forget (TS `spawnPowerShell`).
+/// Reachable from Windows and from WSL, where `powershell.exe` resolves
+/// through Windows/Linux PATH interop. Returns `false` when PowerShell is
+/// unavailable.
+fn spawn_powershell(command: &str, stdin_text: Option<&str>) -> bool {
+    if !command_exists("powershell.exe") {
+        return false;
+    }
+    spawn_fire_and_forget(
+        "powershell.exe",
+        &["-NoLogo", "-NoProfile", "-Command", command],
+        stdin_text,
+    )
+}
+
+/// Launch the user's default browser on `url` using a platform-appropriate
+/// command (TS `openBrowserUrl`). Best-effort fire-and-forget; returns
+/// whether a launch was *attempted*. Callers must redact sensitive tokens
+/// from `url` before calling.
+pub fn open_browser_url(url: &str) -> bool {
+    if is_browser_launch_suppressed() {
+        return false;
+    }
+
+    // Windows: PowerShell Start-Process avoids cmd/start quirks with URLs
+    // containing '&' or ':'.
+    if cfg!(windows) {
+        return spawn_powershell(
+            &format!("Start-Process \"{}\"", escape_for_powershell(url)),
+            None,
+        );
+    }
+
+    if is_wsl() {
+        // wslu's browser shim: hands the URL to the Windows default browser.
+        if command_exists("wslview") {
+            return spawn_fire_and_forget("wslview", &[url], None);
+        }
+        if spawn_powershell(
+            &format!("Start-Process \"{}\"", escape_for_powershell(url)),
+            None,
+        ) {
+            return true;
+        }
+        // Fall through: an X/Wayland browser inside the distro is possible.
+    }
+
+    let opener = get_browser_opener();
+    if !command_exists(opener) {
+        return false;
+    }
+    spawn_fire_and_forget(opener, &[url], None)
+}
+
+/// Copy `text` into the system clipboard using a best-effort platform command
+/// (TS `copyTextToClipboard`). Clipboard contents are not redacted or logged
+/// — callers must mask sensitive tokens beforehand. Returns whether a
+/// clipboard command was launched.
+pub fn copy_text_to_clipboard(text: &str) -> bool {
+    if text.is_empty() {
+        return false;
+    }
+
+    if cfg!(windows) {
+        return spawn_powershell(
+            &format!("Set-Clipboard -Value \"{}\"", escape_for_powershell(text)),
+            None,
+        );
+    }
+
+    if is_wsl() {
+        // The clipboard the user pastes from is the Windows one, not the
+        // distro's.
+        if command_exists("clip.exe") {
+            return spawn_fire_and_forget("clip.exe", &[], Some(text));
+        }
+        if spawn_powershell(
+            &format!("Set-Clipboard -Value \"{}\"", escape_for_powershell(text)),
+            None,
+        ) {
+            return true;
+        }
+        // Fall through to the Linux clipboard tools.
+    }
+
+    if cfg!(target_os = "macos") {
+        if !command_exists("pbcopy") {
+            return false;
+        }
+        return spawn_fire_and_forget("pbcopy", &[], Some(text));
+    }
+
+    let linux_clipboard_commands: [(&str, &[&str]); 3] = [
+        ("wl-copy", &[]),
+        ("xclip", &["-selection", "clipboard"]),
+        ("xsel", &["--clipboard", "--input"]),
+    ];
+    for (command, args) in linux_clipboard_commands {
+        if !command_exists(command) {
+            continue;
+        }
+        return spawn_fire_and_forget(command, args, Some(text));
+    }
+    false
+}
+
+// ===========================================================================
+// Tests (ported from test/browser.test.ts — the TS suite mocks
+// process.platform/child_process/fs; here the pure cores (suppression table,
+// PowerShell escaping, PATH probing) carry the assertions, plus env-driven
+// suppression through EnvSandbox)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    // ----- suppression decision table ---------------------------------------
+
+    #[test]
+    fn no_browser_truthy_values_suppress() {
+        for value in ["1", "true", "yes", "on", " TRUE ", "Yes"] {
+            assert!(
+                is_browser_launch_suppressed_from(Some(value), None),
+                "{value:?} should suppress"
+            );
+        }
+    }
+
+    #[test]
+    fn no_browser_false_like_values_opt_in() {
+        for value in ["0", "false", "no", "off", "whatever"] {
+            assert!(
+                !is_browser_launch_suppressed_from(Some(value), None),
+                "{value:?} should not suppress"
+            );
+        }
+    }
+
+    #[test]
+    fn explicit_false_like_no_browser_overrides_disabling_browser_value() {
+        // CODEX_AUTH_NO_BROWSER=0 / false re-enable launching even with
+        // BROWSER=none (spec 07 gotcha 9).
+        assert!(!is_browser_launch_suppressed_from(Some("0"), Some("none")));
+        assert!(!is_browser_launch_suppressed_from(
+            Some("false"),
+            Some("none")
+        ));
+    }
+
+    #[test]
+    fn browser_disabled_values_suppress_when_no_browser_unset() {
+        for value in ["0", "false", "no", "off", "none", " None "] {
+            assert!(
+                is_browser_launch_suppressed_from(None, Some(value)),
+                "BROWSER={value:?} should suppress"
+            );
+        }
+        assert!(!is_browser_launch_suppressed_from(None, Some("firefox")));
+        assert!(!is_browser_launch_suppressed_from(None, None));
+        // Empty CODEX_AUTH_NO_BROWSER does not decide; BROWSER still applies.
+        assert!(is_browser_launch_suppressed_from(Some("  "), Some("none")));
+    }
+
+    #[test]
+    fn truthy_no_browser_keeps_suppression_even_with_disabled_browser() {
+        assert!(is_browser_launch_suppressed_from(Some("true"), Some("none")));
+    }
+
+    // ----- PowerShell escaping ----------------------------------------------
+
+    #[test]
+    fn escapes_powershell_metacharacters() {
+        // From test/browser.test.ts "escapes PowerShell metacharacters".
+        assert_eq!(
+            format!(
+                "Start-Process \"{}\"",
+                escape_for_powershell("https://example.com/?a=$x&b=`y\"z")
+            ),
+            "Start-Process \"https://example.com/?a=`$x&b=``y\"\"z\""
+        );
+        assert_eq!(escape_for_powershell("https://example.com/$var"), "https://example.com/`$var");
+        assert_eq!(escape_for_powershell("hello$world"), "hello`$world");
+    }
+
+    // ----- has_extension (the /\.[^\\/]+$/ test) ----------------------------
+
+    #[test]
+    fn extension_detection_matches_the_ts_regex() {
+        assert!(has_extension("powershell.exe"));
+        assert!(has_extension("foo.bar.cmd"));
+        assert!(!has_extension("cmd"));
+        assert!(!has_extension("dir.name/cmd"));
+        assert!(!has_extension("dir.name\\cmd"));
+        assert!(!has_extension("trailing."));
+    }
+
+    // ----- platform opener --------------------------------------------------
+
+    #[test]
+    fn returns_platform_opener_command() {
+        let expected = if cfg!(target_os = "macos") {
+            PLATFORM_OPENERS.darwin
+        } else if cfg!(windows) {
+            PLATFORM_OPENERS.win32
+        } else {
+            PLATFORM_OPENERS.linux
+        };
+        assert_eq!(get_browser_opener(), expected);
+    }
+
+    // ----- command_exists ---------------------------------------------------
+
+    #[test]
+    fn command_exists_rejects_empty_and_nonexistent_commands() {
+        assert!(!command_exists(""));
+        assert!(!command_exists("definitely-not-a-real-command-xyz-123"));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn command_exists_treats_start_as_builtin_on_windows() {
+        assert!(command_exists("start"));
+        assert!(command_exists("START"));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn command_exists_finds_powershell_on_windows_path() {
+        // powershell.exe ships with every supported Windows.
+        assert!(command_exists("powershell.exe"));
+        // PATHEXT resolution: the bare name resolves too.
+        assert!(command_exists("powershell"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn command_exists_is_false_with_empty_path() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("PATH", "");
+        assert!(!command_exists("xdg-open"));
+        assert!(!command_exists("wslview"));
+    }
+
+    // ----- open/copy env-driven suppression ---------------------------------
+
+    #[test]
+    #[serial(env)]
+    fn open_browser_url_returns_false_when_suppressed_by_environment() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("CODEX_AUTH_NO_BROWSER", "1");
+        assert!(is_browser_launch_suppressed());
+        assert!(!open_browser_url("https://example.com"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn browser_none_suppresses_launch() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("CODEX_AUTH_NO_BROWSER");
+        sandbox.set_var("BROWSER", "none");
+        assert!(is_browser_launch_suppressed());
+        assert!(!open_browser_url("https://example.com"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn truthy_no_browser_beats_disabled_browser_in_env() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("CODEX_AUTH_NO_BROWSER", "true");
+        sandbox.set_var("BROWSER", "none");
+        assert!(is_browser_launch_suppressed());
+        assert!(!open_browser_url("https://example.com"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn explicit_zero_unsuppresses_but_launch_needs_an_opener() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("CODEX_AUTH_NO_BROWSER", "0");
+        sandbox.set_var("BROWSER", "none");
+        assert!(!is_browser_launch_suppressed());
+        // With an empty PATH no opener resolves, so no launch is attempted —
+        // exercising the not-suppressed → opener-missing path without ever
+        // opening a real browser from the test suite.
+        sandbox.set_var("PATH", "");
+        assert!(!open_browser_url("https://example.com"));
+    }
+
+    #[test]
+    fn copy_text_to_clipboard_returns_false_for_empty_text() {
+        assert!(!copy_text_to_clipboard(""));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn copy_text_to_clipboard_returns_false_when_no_tool_resolves() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("PATH", "");
+        // With an empty PATH neither powershell.exe (win32), pbcopy (darwin),
+        // nor the Linux tools resolve → no spawn, false.
+        assert!(!copy_text_to_clipboard("hello"));
+    }
+}
diff --git a/crates/auth/src/callback_guidance.rs b/crates/auth/src/callback_guidance.rs
new file mode 100644
index 000000000..8882371b2
--- /dev/null
+++ b/crates/auth/src/callback_guidance.rs
@@ -0,0 +1,422 @@
+//! Port of `lib/auth/callback-guidance.ts` — operator-facing guidance for
+//! OAuth callback failures on the fixed callback port (spec 07 §7).
+//!
+//! The redirect URI is registered with the provider, so the port cannot be
+//! negotiated away when it is contended. The best the CLI can do is name the
+//! likely conflict and point at a flow that does not need the port at all.
+//!
+//! Windows and WSL contend for that port as far as a browser running on the
+//! Windows host is concerned, so a listener on either side can swallow a
+//! callback intended for the other. From inside the distro this is invisible:
+//! the WSL listener binds cleanly and simply never receives the redirect.
+//!
+//! Contention is only *asserted* when it was actually observed — that is, the
+//! listen failed with `EADDRINUSE`. A callback that never arrives is far more
+//! often a cancelled or abandoned sign-in than a stolen redirect, so that case
+//! is phrased as a conditional rather than a diagnosis (spec 07 gotcha 7).
+//! All user-visible strings below are FROZEN copies of the TS texts.
+
+use cma_core::wsl::{get_wsl_distro_name, is_wsl};
+
+use crate::oauth::AUTH_REDIRECT;
+
+/// Why the browser callback did not produce an authorization code.
+///
+/// - `BindFailed`: the local listener could not take the callback port at all.
+/// - `CallbackTimeout`: the listener bound, but no redirect ever arrived.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum CallbackFailureReason {
+    BindFailed,
+    CallbackTimeout,
+}
+
+impl CallbackFailureReason {
+    /// The TS string literal for this reason.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::BindFailed => "bind-failed",
+            Self::CallbackTimeout => "callback-timeout",
+        }
+    }
+}
+
+/// Extra detail from the failed bind, when available (TS
+/// `CallbackFailureContext`, `@internal`).
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct CallbackFailureContext {
+    /// `errno` code from a failed listen, when one is known.
+    pub bind_error_code: Option<String>,
+}
+
+const USE_DEVICE_AUTH: &str =
+    "  Or sign in without the callback port: codex-multi-auth login --device-auth";
+
+fn inspect_windows() -> String {
+    format!(
+        "  Windows (PowerShell):  Get-NetTCPConnection -LocalPort {}",
+        AUTH_REDIRECT.port
+    )
+}
+
+fn inspect_linux() -> String {
+    format!(
+        "  Linux / WSL:           ss -lptn 'sport = :{}'",
+        AUTH_REDIRECT.port
+    )
+}
+
+fn inspect_darwin() -> String {
+    format!(
+        "  macOS:                 lsof -nP -iTCP:{} -sTCP:LISTEN",
+        AUTH_REDIRECT.port
+    )
+}
+
+/// Platform seam (TS reads `process.platform`; Rust compiles the current
+/// platform in but keeps the decision table injectable for tests).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum HostPlatform {
+    Win32,
+    Darwin,
+    Linux,
+}
+
+fn current_platform() -> HostPlatform {
+    if cfg!(windows) {
+        HostPlatform::Win32
+    } else if cfg!(target_os = "macos") {
+        HostPlatform::Darwin
+    } else {
+        HostPlatform::Linux
+    }
+}
+
+/// WSL context seam (`isWsl()` / `getWslDistroName()`).
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+struct WslContext {
+    is_wsl: bool,
+    distro: Option<String>,
+}
+
+fn current_wsl_context() -> WslContext {
+    let inside = is_wsl();
+    WslContext {
+        is_wsl: inside,
+        distro: if inside { get_wsl_distro_name() } else { None },
+    }
+}
+
+/// The commands that would reveal a listener on the callback port here.
+///
+/// Inside WSL both sides of the boundary are worth checking, because the
+/// offending listener is usually the one on the Windows host.
+fn inspect_commands(platform: HostPlatform, wsl: &WslContext) -> Vec<String> {
+    if wsl.is_wsl {
+        return vec![inspect_windows(), inspect_linux()];
+    }
+    match platform {
+        HostPlatform::Win32 => vec![inspect_windows()],
+        HostPlatform::Darwin => vec![inspect_darwin()],
+        HostPlatform::Linux => vec![inspect_linux()],
+    }
+}
+
+/// Why a listener on the other side of the Windows/WSL boundary may be at
+/// fault. Empty when no WSL boundary is in play.
+fn cross_boundary_note(platform: HostPlatform, wsl: &WslContext) -> Vec<String> {
+    if wsl.is_wsl {
+        let where_label = match &wsl.distro {
+            Some(distro) => format!("WSL ({distro})"),
+            None => "WSL".to_string(),
+        };
+        return vec![
+            format!(
+                "You are running inside {where_label}, but the browser opens on the Windows host."
+            ),
+            format!(
+                "Windows and {where_label} contend for localhost:{}, so a codex-multi-auth",
+                AUTH_REDIRECT.port
+            ),
+            "or Codex login or proxy on the Windows side can take the callback meant for this one."
+                .to_string(),
+        ];
+    }
+    if platform == HostPlatform::Win32 {
+        return vec![format!(
+            "A codex-multi-auth login or proxy running inside WSL can also hold port {}.",
+            AUTH_REDIRECT.port
+        )];
+    }
+    Vec::new()
+}
+
+fn describe_callback_failure_on(
+    reason: CallbackFailureReason,
+    context: &CallbackFailureContext,
+    platform: HostPlatform,
+    wsl: &WslContext,
+) -> Vec<String> {
+    let port = AUTH_REDIRECT.port;
+
+    if reason == CallbackFailureReason::BindFailed {
+        // A failed listen is hard evidence: something is on the port right now.
+        if context.bind_error_code.as_deref() == Some("EADDRINUSE") {
+            let mut lines = vec![format!(
+                "Could not listen on port {port} for the OAuth callback — another process already holds it."
+            )];
+            lines.extend(cross_boundary_note(platform, wsl));
+            lines.push(String::new());
+            lines.push("Find the listener:".to_string());
+            lines.extend(inspect_commands(platform, wsl));
+            lines.push(String::new());
+            lines.push("Close it, then retry.".to_string());
+            lines.push(USE_DEVICE_AUTH.to_string());
+            return lines;
+        }
+
+        let code_suffix = match &context.bind_error_code {
+            Some(code) => format!(" ({code})"),
+            None => String::new(),
+        };
+        return vec![
+            format!("Could not listen on port {port} for the OAuth callback{code_suffix}."),
+            String::new(),
+            "The callback port is fixed by the provider and cannot be changed.".to_string(),
+            USE_DEVICE_AUTH.to_string(),
+        ];
+    }
+
+    // The listener bound cleanly and nothing arrived. Usually the sign-in was
+    // simply cancelled or abandoned — say so first, and do not misdiagnose it.
+    let mut lines = vec![
+        format!("No OAuth callback arrived on port {port} before the sign-in window closed."),
+        String::new(),
+        "If you closed or cancelled the browser sign-in, just run login again.".to_string(),
+        String::new(),
+        "If you completed sign-in in the browser and still landed here, something else".to_string(),
+        format!("may have taken the callback on port {port}:"),
+    ];
+    lines.extend(cross_boundary_note(platform, wsl));
+    lines.extend(inspect_commands(platform, wsl));
+    lines.push(String::new());
+    lines.push(USE_DEVICE_AUTH.to_string());
+    lines
+}
+
+/// Build the lines shown to the user when a browser OAuth callback fails
+/// (TS `describeCallbackFailure`). Empty strings are intentional blank
+/// separators.
+pub fn describe_callback_failure(
+    reason: CallbackFailureReason,
+    context: &CallbackFailureContext,
+) -> Vec<String> {
+    describe_callback_failure_on(reason, context, current_platform(), &current_wsl_context())
+}
+
+// ===========================================================================
+// Tests (ported from test/callback-guidance.test.ts — the TS suite mocks
+// process.platform and lib/wsl; here the injected decision-table core is
+// exercised directly)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn native(platform: HostPlatform) -> WslContext {
+        let _ = platform;
+        WslContext::default()
+    }
+
+    fn wsl(distro: Option<&str>) -> WslContext {
+        WslContext {
+            is_wsl: true,
+            distro: distro.map(String::from),
+        }
+    }
+
+    fn as_text(lines: &[String]) -> String {
+        lines.join("\n")
+    }
+
+    fn describe(
+        reason: CallbackFailureReason,
+        context: &CallbackFailureContext,
+        platform: HostPlatform,
+        wsl_ctx: &WslContext,
+    ) -> String {
+        as_text(&describe_callback_failure_on(
+            reason, context, platform, wsl_ctx,
+        ))
+    }
+
+    #[test]
+    fn always_offers_the_device_code_flow() {
+        for reason in [
+            CallbackFailureReason::BindFailed,
+            CallbackFailureReason::CallbackTimeout,
+        ] {
+            let text = describe(
+                reason,
+                &CallbackFailureContext::default(),
+                HostPlatform::Linux,
+                &native(HostPlatform::Linux),
+            );
+            assert!(text.contains("--device-auth"), "{reason:?} lacks device auth");
+        }
+    }
+
+    #[test]
+    fn asserts_contention_on_eaddrinuse_hard_evidence() {
+        let text = describe(
+            CallbackFailureReason::BindFailed,
+            &CallbackFailureContext {
+                bind_error_code: Some("EADDRINUSE".to_string()),
+            },
+            HostPlatform::Linux,
+            &native(HostPlatform::Linux),
+        );
+        assert!(text.contains("another process already holds it"));
+        assert!(text.contains(&format!("port {}", AUTH_REDIRECT.port)));
+    }
+
+    #[test]
+    fn does_not_claim_contention_for_unrelated_bind_errors() {
+        let text = describe(
+            CallbackFailureReason::BindFailed,
+            &CallbackFailureContext {
+                bind_error_code: Some("EACCES".to_string()),
+            },
+            HostPlatform::Linux,
+            &native(HostPlatform::Linux),
+        );
+        assert!(text.contains("EACCES"));
+        assert!(!text.contains("already holds it"));
+        assert!(!text.contains("ss -lptn"));
+        assert!(text.contains("The callback port is fixed by the provider and cannot be changed."));
+    }
+
+    #[test]
+    fn bind_failed_without_code_omits_the_parenthetical() {
+        let lines = describe_callback_failure_on(
+            CallbackFailureReason::BindFailed,
+            &CallbackFailureContext::default(),
+            HostPlatform::Linux,
+            &native(HostPlatform::Linux),
+        );
+        assert_eq!(
+            lines[0],
+            format!(
+                "Could not listen on port {} for the OAuth callback.",
+                AUTH_REDIRECT.port
+            )
+        );
+    }
+
+    #[test]
+    fn does_not_diagnose_a_cancelled_sign_in_as_port_contention() {
+        let text = describe(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+            HostPlatform::Linux,
+            &native(HostPlatform::Linux),
+        );
+        assert!(text.contains("If you closed or cancelled the browser sign-in"));
+        assert!(!text.contains("another process already holds it"));
+        // The contention explanation is offered conditionally, not asserted.
+        assert!(text.contains("If you completed sign-in in the browser"));
+    }
+
+    #[test]
+    fn gives_macos_lsof_never_the_linux_only_ss() {
+        let text = describe(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+            HostPlatform::Darwin,
+            &native(HostPlatform::Darwin),
+        );
+        assert!(text.contains("lsof -nP -iTCP:1455"));
+        assert!(!text.contains("ss -lptn"));
+        assert!(!text.contains("Get-NetTCPConnection"));
+    }
+
+    #[test]
+    fn gives_native_linux_ss_and_no_wsl_narrative() {
+        let text = describe(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+            HostPlatform::Linux,
+            &native(HostPlatform::Linux),
+        );
+        assert!(text.contains("ss -lptn"));
+        assert!(!text.contains("Get-NetTCPConnection"));
+        // The `ss` line is labelled "Linux / WSL", so assert the absence of
+        // the explanatory narrative rather than of the substring "WSL".
+        assert!(!text.contains("the browser opens on the Windows host"));
+        assert!(!text.contains("can also hold port"));
+    }
+
+    #[test]
+    fn tells_a_windows_host_that_a_wsl_listener_can_also_hold_the_port() {
+        let text = describe(
+            CallbackFailureReason::BindFailed,
+            &CallbackFailureContext {
+                bind_error_code: Some("EADDRINUSE".to_string()),
+            },
+            HostPlatform::Win32,
+            &native(HostPlatform::Win32),
+        );
+        assert!(text.contains("Get-NetTCPConnection"));
+        assert!(text.contains("inside WSL can also hold port"));
+        assert!(!text.contains("lsof"));
+    }
+
+    #[test]
+    fn inside_wsl_explains_the_split_and_offers_both_inspection_commands() {
+        let text = describe(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+            HostPlatform::Linux,
+            &wsl(Some("Debian")),
+        );
+        assert!(text.contains("WSL (Debian)"));
+        assert!(text.contains("the browser opens on the Windows host"));
+        // The offending listener is usually on the other side of the
+        // boundary, so both sides are worth checking.
+        assert!(text.contains("Get-NetTCPConnection"));
+        assert!(text.contains("ss -lptn"));
+    }
+
+    #[test]
+    fn still_explains_the_split_when_the_distro_name_is_unknown() {
+        let text = describe(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+            HostPlatform::Linux,
+            &wsl(None),
+        );
+        assert!(text.contains("WSL"));
+        assert!(!text.contains("WSL ()"));
+    }
+
+    #[test]
+    fn reason_string_literals_match_the_ts_union() {
+        assert_eq!(CallbackFailureReason::BindFailed.as_str(), "bind-failed");
+        assert_eq!(
+            CallbackFailureReason::CallbackTimeout.as_str(),
+            "callback-timeout"
+        );
+    }
+
+    #[test]
+    fn public_entry_uses_the_current_platform_without_panicking() {
+        // Smoke: the env-reading wrapper produces a non-empty guidance block
+        // ending in the device-auth escape hatch on every platform.
+        let lines = describe_callback_failure(
+            CallbackFailureReason::CallbackTimeout,
+            &CallbackFailureContext::default(),
+        );
+        assert!(!lines.is_empty());
+        assert_eq!(lines.last().map(String::as_str), Some(USE_DEVICE_AUTH));
+    }
+}
diff --git a/crates/auth/src/callback_server.rs b/crates/auth/src/callback_server.rs
new file mode 100644
index 000000000..63db896e8
--- /dev/null
+++ b/crates/auth/src/callback_server.rs
@@ -0,0 +1,799 @@
+//! Port of `lib/auth/server.ts` — the localhost HTTP server that captures the
+//! OAuth authorization code redirected to `/auth/callback` (spec 07 §8).
+//!
+//! Behavior contract (verified against the TS source):
+//! - [`start_local_oauth_server`] **never fails**: a bind error resolves to a
+//!   handle with `ready = false` + `bind_error_code` so the caller can fall
+//!   back to manual paste (spec 07 gotcha 7). The callback port is the
+//!   provider-registered [`AUTH_REDIRECT`] port 1455 and is immovable
+//!   (spec 07 gotcha 8).
+//! - Captured code/state live in **per-call state** ([`Shared`]), never on a
+//!   process-global — two concurrent logins in one process must not cross-bind
+//!   (spec 07 gotcha 6; a prior bug shared `server._lastCode`).
+//! - The first valid code wins; later callbacks still get the success page but
+//!   are ignored with a warning. The success page is written *before* the
+//!   duplicate check.
+//! - `wait_for_code` polls the closure every 100 ms for up to 5 minutes.
+//! - The success page is embedded from `crates/auth/assets/oauth-success.html`
+//!   via `include_str!` (spec 07 gotcha 22 — the TS module reads it at load).
+//!
+//! Implementation note (deviation): the TS server is a raw `node:http` server
+//! with one handler. Rust serves it with `hyper` 1.x `http1::serve_connection`
+//! over a self-bound `tokio::net::TcpListener`. This is the same "bind our own
+//! listener so bind-failure is observable, never-reject" shape ARCHITECTURE
+//! §5.2 calls for; a full `axum::Router` would add extractor machinery for a
+//! single route with no behavioral gain. Node's `server.listen(port,
+//! "localhost")` binds ONE resolved address — the Rust port mirrors that
+//! (single-address bind), which also keeps the contended-port contract
+//! deterministic.
+
+use std::convert::Infallible;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+
+use bytes::Bytes;
+use http_body_util::Full;
+use hyper::service::service_fn;
+use hyper::{Request, Response, StatusCode};
+use hyper_util::rt::TokioIo;
+use tokio::net::TcpListener;
+use tokio::sync::Notify;
+
+use cma_core::fs_retry::code_of;
+use cma_core::logger::{log_error, log_warn};
+
+pub use cma_core::types::OAuthServerInfo;
+
+use crate::oauth::AUTH_REDIRECT;
+
+/// The OAuth success page shown to the browser after a valid callback. Embedded
+/// at build time so the binary is self-contained (TS reads the sibling
+/// `lib/oauth-success.html` synchronously at module load).
+const SUCCESS_HTML: &str = include_str!("../assets/oauth-success.html");
+
+/// The exact `Content-Security-Policy` the success page is served with — locks
+/// the page down to inline styles only (FROZEN copy of the TS header).
+const SUCCESS_CSP: &str = "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; \
+     font-src 'self' data:; script-src 'none'; base-uri 'none'; form-action 'none'; \
+     frame-ancestors 'none'";
+
+/// `waitForCode` poll cadence (TS `POLL_INTERVAL_MS`).
+const POLL_INTERVAL_MS: u64 = 100;
+/// `waitForCode` total budget: 5 minutes (TS `TIMEOUT_MS`).
+const TIMEOUT_MS: u64 = 5 * 60 * 1000;
+/// Poll iterations before timing out (TS `maxIterations = floor(TIMEOUT/POLL)`).
+const MAX_ITERATIONS: u32 = (TIMEOUT_MS / POLL_INTERVAL_MS) as u32;
+
+/// The code + state captured from the first valid callback. Kept in per-call
+/// [`Shared`] state, not on a global (spec 07 gotcha 6).
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Captured {
+    code: String,
+    state: String,
+}
+
+/// Result of [`LocalOAuthServer::wait_for_code`] — mirrors the TS
+/// `{ code: string }` resolution shape.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CapturedCode {
+    pub code: String,
+}
+
+/// Per-server state shared between the accept loop, the request handler, and
+/// the [`LocalOAuthServer`] handle. One instance per `start_local_oauth_server`
+/// call keeps concurrent logins isolated.
+#[derive(Default)]
+struct Shared {
+    /// The first captured code/state; `None` until a valid callback arrives.
+    captured: Mutex<Option<Captured>>,
+    /// Set by `close()` — an in-flight `wait_for_code` returns `None` on its
+    /// next poll (TS `pollAborted`).
+    poll_aborted: AtomicBool,
+    /// Set by `close()` — the accept loop stops and releases the port
+    /// (TS `server.close()`).
+    shutdown: AtomicBool,
+    /// Wakes the accept loop's `select!` so `close()` takes effect immediately.
+    notify: Notify,
+}
+
+/// Handle over a running (or failed-to-bind) OAuth callback server. Combines the
+/// TS `OAuthServerInfo` data (`port`/`ready`/`bindErrorCode`) with its behavior
+/// (`close`/`waitForCode`).
+pub struct LocalOAuthServer {
+    port: u16,
+    ready: bool,
+    bind_error_code: Option<String>,
+    shared: Arc<Shared>,
+}
+
+impl LocalOAuthServer {
+    /// The callback port (always [`AUTH_REDIRECT`]`.port` = 1455).
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// Whether the listener bound successfully. `false` signals the caller to
+    /// use the manual-paste fallback.
+    pub fn ready(&self) -> bool {
+        self.ready
+    }
+
+    /// The `errno`-style code from a failed bind (for example `"EADDRINUSE"`),
+    /// or `None` when [`ready`](Self::ready) is `true`. Feeds
+    /// `describe_callback_failure`.
+    pub fn bind_error_code(&self) -> Option<&str> {
+        self.bind_error_code.as_deref()
+    }
+
+    /// Data-only snapshot matching the serializable TS `OAuthServerInfo`.
+    pub fn info(&self) -> OAuthServerInfo {
+        OAuthServerInfo {
+            port: self.port,
+            ready: self.ready,
+            bind_error_code: self.bind_error_code.clone(),
+        }
+    }
+
+    /// Abort any in-flight [`wait_for_code`](Self::wait_for_code) and stop the
+    /// server, releasing the callback port. Idempotent and infallible
+    /// (TS `close()`).
+    pub fn close(&self) {
+        self.shared.poll_aborted.store(true, Ordering::SeqCst);
+        self.shared.shutdown.store(true, Ordering::SeqCst);
+        self.shared.notify.notify_waiters();
+    }
+
+    /// Wait for a captured authorization code whose state matches
+    /// `expected_state`, polling every 100 ms for up to 5 minutes.
+    ///
+    /// Returns `None` on abort (`close()`), a captured state that does not match
+    /// `expected_state`, timeout, or when the server never bound
+    /// (`ready == false` returns immediately — a failed server must not strand
+    /// the caller).
+    pub async fn wait_for_code(&self, expected_state: &str) -> Option<CapturedCode> {
+        if !self.ready {
+            // TS bind-failure handle: `waitForCode: () => Promise.resolve(null)`.
+            return None;
+        }
+        poll_captured(
+            &self.shared,
+            expected_state,
+            Duration::from_millis(POLL_INTERVAL_MS),
+            MAX_ITERATIONS,
+        )
+        .await
+    }
+}
+
+/// Poll [`Shared::captured`] for a code matching `expected_state`. Factored out
+/// of [`LocalOAuthServer::wait_for_code`] so the abort/mismatch/timeout wiring
+/// is testable without the 5-minute wall clock or binding port 1455.
+async fn poll_captured(
+    shared: &Shared,
+    expected_state: &str,
+    interval: Duration,
+    max_iterations: u32,
+) -> Option<CapturedCode> {
+    for _ in 0..max_iterations {
+        if shared.poll_aborted.load(Ordering::SeqCst) {
+            return None;
+        }
+        // Clone out of the lock so it is released before we sleep (no lock held
+        // across an await).
+        let last = shared.captured.lock().unwrap().clone();
+        if let Some(captured) = last {
+            if captured.state != expected_state {
+                log_warn(
+                    "Discarding OAuth callback due to state mismatch in waitForCode",
+                    None,
+                );
+                return None;
+            }
+            return Some(CapturedCode {
+                code: captured.code,
+            });
+        }
+        tokio::time::sleep(interval).await;
+    }
+    log_warn("OAuth poll timeout after 5 minutes", None);
+    None
+}
+
+/// Start a local server that captures the OAuth authorization code redirected to
+/// `/auth/callback`. **Never fails** — a bind error yields a handle with
+/// `ready == false` and the bind `errno` code for the manual-paste fallback.
+pub async fn start_local_oauth_server(state: &str) -> LocalOAuthServer {
+    let shared = Arc::new(Shared::default());
+    match bind_callback_listener().await {
+        Ok(listener) => {
+            spawn_accept_loop(listener, shared.clone(), state.to_string());
+            LocalOAuthServer {
+                port: AUTH_REDIRECT.port,
+                ready: true,
+                bind_error_code: None,
+                shared,
+            }
+        }
+        Err(error) => {
+            let code = code_of(&error).map(String::from);
+            let shown = code.as_deref().unwrap_or("unknown");
+            log_error(
+                &format!(
+                    "Failed to bind {} ({shown}). Falling back to manual paste.",
+                    AUTH_REDIRECT.origin
+                ),
+                None,
+            );
+            LocalOAuthServer {
+                port: AUTH_REDIRECT.port,
+                ready: false,
+                bind_error_code: code,
+                shared,
+            }
+        }
+    }
+}
+
+/// Bind the callback listener on the first resolved address of
+/// `localhost:1455`, mirroring Node's single-address `server.listen(port,
+/// "localhost")`. Binding one concrete address (rather than every resolved
+/// family) keeps the contended-port contract deterministic — whoever holds that
+/// address wins.
+async fn bind_callback_listener() -> std::io::Result<TcpListener> {
+    let mut addrs = tokio::net::lookup_host((AUTH_REDIRECT.host, AUTH_REDIRECT.port)).await?;
+    let addr = addrs.next().ok_or_else(|| {
+        std::io::Error::new(
+            std::io::ErrorKind::AddrNotAvailable,
+            "no socket address resolved for the OAuth callback host",
+        )
+    })?;
+    TcpListener::bind(addr).await
+}
+
+/// Spawn the accept loop: serve each connection with the single-route handler
+/// until `close()` flips [`Shared::shutdown`]. Dropping the listener on exit
+/// releases the fixed callback port.
+fn spawn_accept_loop(listener: TcpListener, shared: Arc<Shared>, state: String) {
+    tokio::spawn(async move {
+        let state = Arc::new(state);
+        loop {
+            if shared.shutdown.load(Ordering::SeqCst) {
+                break;
+            }
+            tokio::select! {
+                _ = shared.notify.notified() => break,
+                accepted = listener.accept() => {
+                    let stream = match accepted {
+                        Ok((stream, _peer)) => stream,
+                        // Transient accept errors are ignored (parity with the
+                        // TS server, which keeps listening).
+                        Err(_) => continue,
+                    };
+                    let conn_shared = shared.clone();
+                    let conn_state = state.clone();
+                    tokio::spawn(async move {
+                        let io = TokioIo::new(stream);
+                        let service = service_fn(move |req: Request<hyper::body::Incoming>| {
+                            let response =
+                                handle_request(&req, conn_shared.as_ref(), conn_state.as_str());
+                            async move { Ok::<_, Infallible>(response) }
+                        });
+                        // Client-side errors (disconnects) are expected; the
+                        // capture already happened in `handle_request`.
+                        let _ = hyper::server::conn::http1::Builder::new()
+                            .serve_connection(io, service)
+                            .await;
+                    });
+                }
+            }
+        }
+        drop(listener);
+    });
+}
+
+/// Handle one callback request. Pure over [`Shared`] (records the first valid
+/// code as a side effect) — no I/O — so it is unit-testable without a socket.
+fn handle_request<B>(req: &Request<B>, shared: &Shared, expected_state: &str) -> Response<Full<Bytes>> {
+    // Parse relative to the fixed callback origin, matching TS
+    // `new URL(req.url, AUTH_REDIRECT.origin)`. hyper has already validated the
+    // request target, so this parse effectively never fails; the 500 branch
+    // mirrors the TS try/catch (no throwing equivalent exists in Rust).
+    let path_and_query = req
+        .uri()
+        .path_and_query()
+        .map(|pq| pq.as_str())
+        .unwrap_or("/");
+    let Ok(url) = url::Url::parse(&format!("{}{}", AUTH_REDIRECT.origin, path_and_query)) else {
+        log_error("Request handler error: could not parse request URL", None);
+        return text_response(StatusCode::INTERNAL_SERVER_ERROR, "Internal error");
+    };
+
+    if url.path() != AUTH_REDIRECT.path {
+        return text_response(StatusCode::NOT_FOUND, "Not found");
+    }
+
+    let query_state = url
+        .query_pairs()
+        .find(|(k, _)| k == "state")
+        .map(|(_, v)| v.into_owned());
+    if query_state.as_deref() != Some(expected_state) {
+        return text_response(StatusCode::BAD_REQUEST, "State mismatch");
+    }
+
+    // TS `if (!code)` treats both a missing param and an empty string as
+    // "missing".
+    let code = url
+        .query_pairs()
+        .find(|(k, _)| k == "code")
+        .map(|(_, v)| v.into_owned());
+    let code = match code {
+        Some(code) if !code.is_empty() => code,
+        _ => return text_response(StatusCode::BAD_REQUEST, "Missing authorization code"),
+    };
+
+    // Build the success response first — the TS handler writes the page before
+    // the duplicate check, so a duplicate callback also gets the success page —
+    // then record the capture (first code wins).
+    let response = success_response();
+    {
+        let mut guard = shared.captured.lock().unwrap();
+        if guard.is_some() {
+            log_warn(
+                "Duplicate OAuth callback received; preserving first authorization code",
+                None,
+            );
+        } else {
+            *guard = Some(Captured {
+                code,
+                state: expected_state.to_string(),
+            });
+        }
+    }
+    response
+}
+
+/// A plain-text response with a static body (the 404/400/500 error pages — the
+/// TS handler sets a status and `res.end(text)` with no content type).
+fn text_response(status: StatusCode, body: &'static str) -> Response<Full<Bytes>> {
+    Response::builder()
+        .status(status)
+        .body(Full::new(Bytes::from_static(body.as_bytes())))
+        .expect("static text response is always valid")
+}
+
+/// The 200 success response: the embedded HTML page plus the FROZEN security
+/// header set.
+fn success_response() -> Response<Full<Bytes>> {
+    Response::builder()
+        .status(StatusCode::OK)
+        .header("Content-Type", "text/html; charset=utf-8")
+        .header("X-Frame-Options", "DENY")
+        .header("X-Content-Type-Options", "nosniff")
+        .header("Content-Security-Policy", SUCCESS_CSP)
+        .body(Full::new(Bytes::from_static(SUCCESS_HTML.as_bytes())))
+        .expect("success response is always valid")
+}
+
+// ===========================================================================
+// Tests — ported from test/server.unit.test.ts,
+// test/oauth-server.integration.test.ts, and
+// test/oauth-server-port-conflict.test.ts.
+//
+// Port-1455 tests carry #[serial(oauth_1455)] and release the port before
+// returning (ARCHITECTURE §9.4 / cma-testkit::port1455). Handler and poll
+// wiring are exercised directly without a socket, so those tests need no serial
+// guard and no 5-minute wall clock.
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::SocketAddr;
+
+    use cma_testkit::port1455::serial;
+
+    // ----- pure request-handler tests (no socket) --------------------------
+
+    fn request(uri: &str) -> Request<()> {
+        Request::builder().uri(uri).body(()).unwrap()
+    }
+
+    #[test]
+    fn handler_returns_404_for_non_callback_paths() {
+        let shared = Shared::default();
+        let resp = handle_request(&request("/other-path"), &shared, "test-state");
+        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+        assert!(shared.captured.lock().unwrap().is_none());
+    }
+
+    #[test]
+    fn handler_returns_400_for_state_mismatch() {
+        let shared = Shared::default();
+        let resp = handle_request(
+            &request("/auth/callback?code=abc&state=wrong-state"),
+            &shared,
+            "test-state",
+        );
+        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+        assert!(shared.captured.lock().unwrap().is_none());
+    }
+
+    #[test]
+    fn handler_returns_400_for_missing_code() {
+        let shared = Shared::default();
+        let resp = handle_request(
+            &request("/auth/callback?state=test-state"),
+            &shared,
+            "test-state",
+        );
+        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+        assert!(shared.captured.lock().unwrap().is_none());
+    }
+
+    #[test]
+    fn handler_returns_400_for_empty_code() {
+        // TS `if (!code)` — a present-but-empty `code=` is still "missing".
+        let shared = Shared::default();
+        let resp = handle_request(
+            &request("/auth/callback?code=&state=test-state"),
+            &shared,
+            "test-state",
+        );
+        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+        assert!(shared.captured.lock().unwrap().is_none());
+    }
+
+    #[test]
+    fn handler_returns_200_with_html_and_security_headers() {
+        let shared = Shared::default();
+        let resp = handle_request(
+            &request("/auth/callback?code=test-code&state=test-state"),
+            &shared,
+            "test-state",
+        );
+        assert_eq!(resp.status(), StatusCode::OK);
+        assert_eq!(
+            resp.headers().get("content-type").unwrap(),
+            "text/html; charset=utf-8"
+        );
+        assert_eq!(resp.headers().get("x-frame-options").unwrap(), "DENY");
+        assert_eq!(
+            resp.headers().get("x-content-type-options").unwrap(),
+            "nosniff"
+        );
+        assert_eq!(
+            resp.headers().get("content-security-policy").unwrap(),
+            SUCCESS_CSP
+        );
+    }
+
+    #[test]
+    fn handler_captures_first_code_via_shared_state() {
+        let shared = Shared::default();
+        handle_request(
+            &request("/auth/callback?code=captured-code&state=test-state"),
+            &shared,
+            "test-state",
+        );
+        assert_eq!(
+            shared.captured.lock().unwrap().as_ref().map(|c| c.code.clone()),
+            Some("captured-code".to_string())
+        );
+    }
+
+    #[test]
+    fn handler_keeps_first_code_when_duplicate_callbacks_arrive() {
+        let shared = Shared::default();
+        handle_request(
+            &request("/auth/callback?code=first-code&state=test-state"),
+            &shared,
+            "test-state",
+        );
+        let second = handle_request(
+            &request("/auth/callback?code=second-code&state=test-state"),
+            &shared,
+            "test-state",
+        );
+        // The duplicate still receives the success page…
+        assert_eq!(second.status(), StatusCode::OK);
+        // …but the first code is preserved.
+        assert_eq!(shared.captured.lock().unwrap().as_ref().unwrap().code, "first-code");
+    }
+
+    #[test]
+    fn handler_keeps_capture_state_isolated_between_instances() {
+        // Mirrors the TS "keeps capture state isolated between two concurrent
+        // server instances": capture lives on per-call `Shared`, not a global.
+        let a = Shared::default();
+        let b = Shared::default();
+        handle_request(
+            &request("/auth/callback?code=code-a&state=state-a"),
+            &a,
+            "state-a",
+        );
+        handle_request(
+            &request("/auth/callback?code=code-b&state=state-b"),
+            &b,
+            "state-b",
+        );
+        assert_eq!(a.captured.lock().unwrap().as_ref().unwrap().code, "code-a");
+        assert_eq!(b.captured.lock().unwrap().as_ref().unwrap().code, "code-b");
+    }
+
+    // ----- poll wiring tests (no socket, no 5-minute wall clock) -----------
+
+    #[tokio::test]
+    async fn poll_returns_captured_code_when_state_matches() {
+        let shared = Shared::default();
+        *shared.captured.lock().unwrap() = Some(Captured {
+            code: "the-code".to_string(),
+            state: "test-state".to_string(),
+        });
+        let out = poll_captured(&shared, "test-state", Duration::from_millis(1), MAX_ITERATIONS).await;
+        assert_eq!(out, Some(CapturedCode { code: "the-code".to_string() }));
+    }
+
+    #[tokio::test]
+    async fn poll_discards_code_on_state_mismatch() {
+        let shared = Shared::default();
+        *shared.captured.lock().unwrap() = Some(Captured {
+            code: "the-code".to_string(),
+            state: "other-state".to_string(),
+        });
+        let out = poll_captured(&shared, "expected-state", Duration::from_millis(1), MAX_ITERATIONS).await;
+        assert_eq!(out, None);
+    }
+
+    #[tokio::test]
+    async fn poll_returns_none_immediately_when_aborted() {
+        let shared = Shared::default();
+        shared.poll_aborted.store(true, Ordering::SeqCst);
+        // Even with a code present, an aborted poll returns None.
+        *shared.captured.lock().unwrap() = Some(Captured {
+            code: "x".to_string(),
+            state: "expected".to_string(),
+        });
+        let out = poll_captured(&shared, "expected", Duration::from_millis(1), MAX_ITERATIONS).await;
+        assert_eq!(out, None);
+    }
+
+    #[tokio::test]
+    async fn poll_times_out_to_none_without_a_code() {
+        // Exercises the timeout branch (returns None + warn log) with a tiny
+        // iteration budget instead of the real 3000 × 100 ms.
+        let shared = Shared::default();
+        let out = poll_captured(&shared, "test-state", Duration::from_millis(1), 3).await;
+        assert_eq!(out, None);
+    }
+
+    #[test]
+    fn timeout_constants_match_ts() {
+        // Guards the REAL 5-minute / 100 ms budget without waiting for it.
+        assert_eq!(POLL_INTERVAL_MS, 100);
+        assert_eq!(TIMEOUT_MS, 5 * 60 * 1000);
+        assert_eq!(MAX_ITERATIONS, 3000);
+    }
+
+    // ----- handle-level behavior (no socket) -------------------------------
+
+    #[tokio::test]
+    async fn wait_for_code_is_none_when_not_ready() {
+        let server = LocalOAuthServer {
+            port: 1455,
+            ready: false,
+            bind_error_code: Some("EADDRINUSE".to_string()),
+            shared: Arc::new(Shared::default()),
+        };
+        assert_eq!(server.wait_for_code("test-state").await, None);
+    }
+
+    #[test]
+    fn close_sets_abort_and_shutdown_flags() {
+        let server = LocalOAuthServer {
+            port: 1455,
+            ready: true,
+            bind_error_code: None,
+            shared: Arc::new(Shared::default()),
+        };
+        server.close();
+        assert!(server.shared.poll_aborted.load(Ordering::SeqCst));
+        assert!(server.shared.shutdown.load(Ordering::SeqCst));
+    }
+
+    #[test]
+    fn info_reflects_bind_failure_shape() {
+        let server = LocalOAuthServer {
+            port: 1455,
+            ready: false,
+            bind_error_code: Some("EADDRINUSE".to_string()),
+            shared: Arc::new(Shared::default()),
+        };
+        let info = server.info();
+        assert_eq!(info.port, 1455);
+        assert!(!info.ready);
+        assert_eq!(info.bind_error_code.as_deref(), Some("EADDRINUSE"));
+    }
+
+    #[test]
+    fn bind_error_code_feeds_contention_guidance() {
+        // Mirrors the TS port-conflict "feeds the bind error into guidance"
+        // test: EADDRINUSE selects the assertive branch. Pure — no socket.
+        use crate::callback_guidance::{
+            CallbackFailureContext, CallbackFailureReason, describe_callback_failure,
+        };
+        let ctx = CallbackFailureContext {
+            bind_error_code: Some("EADDRINUSE".to_string()),
+        };
+        let guidance = describe_callback_failure(CallbackFailureReason::BindFailed, &ctx).join("\n");
+        assert!(guidance.contains("another process already holds it"));
+        assert!(guidance.contains(&AUTH_REDIRECT.port.to_string()));
+        assert!(guidance.contains("--device-auth"));
+    }
+
+    // ----- live integration tests (bind port 1455) -------------------------
+
+    /// Resolve the single address the server will bind (same first-address rule
+    /// as `bind_callback_listener`), so test clients hit exactly that socket —
+    /// deterministic on dual-stack hosts.
+    async fn callback_addr() -> SocketAddr {
+        tokio::net::lookup_host((AUTH_REDIRECT.host, AUTH_REDIRECT.port))
+            .await
+            .expect("resolve localhost:1455")
+            .next()
+            .expect("at least one address for localhost:1455")
+    }
+
+    /// Poll-bind `addr` until it is free (or fail loudly), mirroring the TS
+    /// integration suite's awaited port release. `close()` drops the listener
+    /// asynchronously, so the next binder must wait for the socket to clear.
+    async fn wait_for_addr_free(addr: SocketAddr) {
+        let deadline = std::time::Instant::now() + Duration::from_secs(5);
+        loop {
+            match std::net::TcpListener::bind(addr) {
+                Ok(listener) => {
+                    drop(listener);
+                    return;
+                }
+                Err(_) if std::time::Instant::now() < deadline => {
+                    tokio::time::sleep(Duration::from_millis(25)).await;
+                }
+                Err(error) => {
+                    panic!("callback port {addr} did not free during teardown: {error}")
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    #[serial(oauth_1455)]
+    async fn captures_authorization_code_from_valid_callback() {
+        let addr = callback_addr().await;
+        wait_for_addr_free(addr).await;
+
+        let state = "test-state-12345";
+        let server = start_local_oauth_server(state).await;
+        assert!(server.ready());
+        assert_eq!(server.port(), 1455);
+        assert_eq!(server.bind_error_code(), None);
+
+        let code = "auth-code-67890";
+        let response = reqwest::get(format!("http://{addr}/auth/callback?code={code}&state={state}"))
+            .await
+            .expect("callback request succeeds");
+        assert_eq!(response.status(), 200);
+        let content_type = response
+            .headers()
+            .get("content-type")
+            .and_then(|v| v.to_str().ok())
+            .unwrap_or_default();
+        assert!(content_type.contains("text/html"), "content-type was {content_type:?}");
+        let body = response.text().await.expect("body");
+        assert!(body.contains("Sign-in complete"), "unexpected success page body");
+
+        let captured = server.wait_for_code(state).await;
+        assert_eq!(captured, Some(CapturedCode { code: code.to_string() }));
+
+        server.close();
+        wait_for_addr_free(addr).await;
+    }
+
+    #[tokio::test]
+    #[serial(oauth_1455)]
+    async fn first_code_wins_when_duplicate_callbacks_arrive() {
+        let addr = callback_addr().await;
+        wait_for_addr_free(addr).await;
+
+        let state = "dup-state";
+        let server = start_local_oauth_server(state).await;
+        assert!(server.ready());
+
+        // The capture is recorded before the response is sent, so once the first
+        // request returns 200 the code is already stored.
+        let first = reqwest::get(format!("http://{addr}/auth/callback?code=first-code&state={state}"))
+            .await
+            .expect("first callback");
+        assert_eq!(first.status(), 200);
+        let second = reqwest::get(format!("http://{addr}/auth/callback?code=second-code&state={state}"))
+            .await
+            .expect("second callback");
+        assert_eq!(second.status(), 200);
+
+        let captured = server.wait_for_code(state).await;
+        assert_eq!(captured, Some(CapturedCode { code: "first-code".to_string() }));
+
+        server.close();
+        wait_for_addr_free(addr).await;
+    }
+
+    #[tokio::test]
+    #[serial(oauth_1455)]
+    async fn rejects_invalid_callbacks_over_the_wire() {
+        let addr = callback_addr().await;
+        wait_for_addr_free(addr).await;
+
+        let state = "reject-state";
+        let server = start_local_oauth_server(state).await;
+        assert!(server.ready());
+
+        let not_found = reqwest::get(format!("http://{addr}/other-path")).await.unwrap();
+        assert_eq!(not_found.status(), 404);
+        assert!(not_found.text().await.unwrap().contains("Not found"));
+
+        let mismatch = reqwest::get(format!("http://{addr}/auth/callback?code=x&state=wrong"))
+            .await
+            .unwrap();
+        assert_eq!(mismatch.status(), 400);
+        assert!(mismatch.text().await.unwrap().contains("State mismatch"));
+
+        let missing = reqwest::get(format!("http://{addr}/auth/callback?state={state}"))
+            .await
+            .unwrap();
+        assert_eq!(missing.status(), 400);
+        assert!(missing.text().await.unwrap().contains("Missing authorization code"));
+
+        server.close();
+        wait_for_addr_free(addr).await;
+    }
+
+    #[tokio::test]
+    #[serial(oauth_1455)]
+    async fn bind_conflict_reports_not_ready_with_eaddrinuse() {
+        let addr = callback_addr().await;
+        wait_for_addr_free(addr).await;
+
+        // Occupy the exact address the server will attempt to bind, forcing the
+        // never-reject fallback (spec 07 gotcha 7).
+        let squatter = std::net::TcpListener::bind(addr).expect("squat callback port");
+
+        let server = start_local_oauth_server("test-state").await;
+        assert!(!server.ready());
+        assert_eq!(server.port(), 1455);
+        assert_eq!(server.bind_error_code(), Some("EADDRINUSE"));
+        // A server that never bound must not strand the caller.
+        assert_eq!(server.wait_for_code("test-state").await, None);
+        server.close();
+
+        drop(squatter);
+        wait_for_addr_free(addr).await;
+    }
+
+    #[tokio::test]
+    #[serial(oauth_1455)]
+    async fn close_releases_the_callback_port() {
+        let addr = callback_addr().await;
+        wait_for_addr_free(addr).await;
+
+        let server = start_local_oauth_server("cleanup").await;
+        assert!(server.ready());
+        server.close();
+        wait_for_addr_free(addr).await;
+
+        // The port must be free for the next login to bind cleanly.
+        let again = start_local_oauth_server("cleanup-2").await;
+        assert!(again.ready(), "callback port should rebind after close");
+        again.close();
+        wait_for_addr_free(addr).await;
+    }
+}
diff --git a/crates/auth/src/device_auth.rs b/crates/auth/src/device_auth.rs
new file mode 100644
index 000000000..34b2db00f
--- /dev/null
+++ b/crates/auth/src/device_auth.rs
@@ -0,0 +1,1829 @@
+//! Port of `lib/auth/device-auth.ts` — the non-RFC-8628 device-code login
+//! flow against `auth.openai.com` (spec 07 §2).
+//!
+//! CRITICAL semantics (spec 07 gotchas 1–2):
+//! - On the *usercode* request a 404 is TERMINAL ("Device auth login is not
+//!   enabled…"); on the *token poll* bare 403/404 are NORMAL pending states
+//!   (403 = user hasn't approved yet, 404 = device_auth_id propagation lag).
+//! - 403/404 poll delays use the exact server interval with NO jitter; only
+//!   transient statuses {408, 429, 502, 503, 504} get ±10 % jitter.
+//! - A parseable `Retry-After` (seconds or HTTP-date) overrides both, floored
+//!   at 1000 ms.
+//! - Total budget 15 min, clamped further by the server `expires_at`.
+//! - The poll response carries the PKCE verifier with the authorization code;
+//!   it is never persisted and never logged (spec 07 gotcha 5).
+//!
+//! The TS `keepAlive` option (timer `unref` control) has no Rust equivalent —
+//! tokio timers never hold or release a process the way Node's event loop
+//! does — and is intentionally not ported (spec 07 §2 notes it is irrelevant
+//! for a blocking runtime).
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use serde::Serialize;
+use serde_json::{Value, json};
+use tokio::sync::Notify;
+
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult};
+
+use crate::oauth::{
+    CLIENT_ID, TOKEN_URL, exchange_authorization_code_at, sanitize_oauth_response_body_for_log,
+};
+
+// ---------------------------------------------------------------------------
+// Constants (exact values, spec 07 §2)
+// ---------------------------------------------------------------------------
+
+const DEVICE_AUTH_BASE_URL: &str = "https://auth.openai.com";
+pub const DEVICE_AUTH_VERIFICATION_URL: &str = "https://auth.openai.com/codex/device";
+pub const DEVICE_AUTH_REDIRECT_URI: &str = "https://auth.openai.com/deviceauth/callback";
+pub const DEVICE_AUTH_TIMEOUT_MS: i64 = 15 * 60 * 1000;
+pub const DEVICE_AUTH_DEFAULT_INTERVAL_MS: i64 = 5_000;
+const DEVICE_AUTH_ABORTED_MESSAGE: &str = "aborted";
+const DEVICE_AUTH_TRANSIENT_PENDING_STATUSES: [u16; 5] = [408, 429, 502, 503, 504];
+
+// ---------------------------------------------------------------------------
+// Abort signal (AbortSignal analogue for this flow)
+// ---------------------------------------------------------------------------
+
+/// Minimal `AbortSignal` analogue: an abort flag plus a notifier so pending
+/// sleeps/polls can be woken. Cloneable via `Arc`.
+#[derive(Debug, Default)]
+pub struct AbortSignal {
+    aborted: AtomicBool,
+    notify: Notify,
+}
+
+impl AbortSignal {
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self::default())
+    }
+
+    /// Trip the signal; all current and future waiters resolve immediately.
+    pub fn abort(&self) {
+        self.aborted.store(true, Ordering::SeqCst);
+        self.notify.notify_waiters();
+    }
+
+    pub fn is_aborted(&self) -> bool {
+        self.aborted.load(Ordering::SeqCst)
+    }
+
+    /// Resolve once the signal is aborted (immediately when already aborted).
+    pub async fn cancelled(&self) {
+        loop {
+            if self.is_aborted() {
+                return;
+            }
+            let notified = self.notify.notified();
+            // Re-check after registering to close the store/notify race.
+            if self.is_aborted() {
+                return;
+            }
+            notified.await;
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Options (TS `DeviceAuthFlowOptions` — injectable for tests)
+// ---------------------------------------------------------------------------
+
+pub type NowFn = Arc<dyn Fn() -> i64 + Send + Sync>;
+pub type SleepFn = Arc<dyn Fn(i64) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync>;
+pub type RandomFn = Arc<dyn Fn() -> f64 + Send + Sync>;
+pub type LogFn = Arc<dyn Fn(&str) + Send + Sync>;
+
+/// Injectable seams for the device auth flow. All optional; defaults match
+/// production behavior. `base_url` / `token_url` replace the TS `fetchImpl`
+/// stub as the test seam (point them at a mock server).
+#[derive(Clone, Default)]
+pub struct DeviceAuthFlowOptions {
+    /// Base URL for the device-auth endpoints (default `https://auth.openai.com`).
+    pub base_url: Option<String>,
+    /// Token endpoint for the final code exchange (default the production
+    /// `TOKEN_URL`).
+    pub token_url: Option<String>,
+    /// Clock (default wall clock, epoch ms).
+    pub now: Option<NowFn>,
+    /// Sleep implementation (default `tokio::time::sleep`).
+    pub sleep: Option<SleepFn>,
+    /// Abort signal.
+    pub signal: Option<Arc<AbortSignal>>,
+    /// Total wait budget (default 15 min).
+    pub timeout_ms: Option<i64>,
+    /// Prompt sink (default stdout `println!`).
+    pub log: Option<LogFn>,
+    /// Jitter source in `[0, 1)` (default `rand`).
+    pub random: Option<RandomFn>,
+}
+
+fn now_of(options: &DeviceAuthFlowOptions) -> i64 {
+    match &options.now {
+        Some(f) => f(),
+        None => cma_core::utils::now_ms(),
+    }
+}
+
+fn random_of(options: &DeviceAuthFlowOptions) -> f64 {
+    match &options.random {
+        Some(f) => f(),
+        None => rand::random::<f64>(),
+    }
+}
+
+fn log_line(options: &DeviceAuthFlowOptions, message: &str) {
+    match &options.log {
+        Some(f) => f(message),
+        None => println!("{message}"),
+    }
+}
+
+fn is_aborted(options: &DeviceAuthFlowOptions) -> bool {
+    options
+        .signal
+        .as_ref()
+        .is_some_and(|signal| signal.is_aborted())
+}
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/// The parsed usercode-request payload (TS `DeviceAuthCode`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DeviceAuthCode {
+    pub verification_url: String,
+    pub user_code: String,
+    pub device_auth_id: String,
+    pub interval_ms: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_at_ms: Option<i64>,
+}
+
+/// The parsed token-poll completion payload. The server intentionally
+/// returns the PKCE verifier with the issued authorization code (mirrors the
+/// upstream Codex CLI); the verifier is never persisted and never logged —
+/// it is handed straight to the token exchange.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeviceAuthCompletion {
+    pub authorization_code: String,
+    pub code_verifier: String,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum DeviceAuthCodeResult {
+    Success { device_code: DeviceAuthCode },
+    Failed(TokenFailure),
+}
+
+impl DeviceAuthCodeResult {
+    pub fn as_success(&self) -> Option<&DeviceAuthCode> {
+        match self {
+            Self::Success { device_code } => Some(device_code),
+            Self::Failed(_) => None,
+        }
+    }
+    pub fn as_failure(&self) -> Option<&TokenFailure> {
+        match self {
+            Self::Success { .. } => None,
+            Self::Failed(failure) => Some(failure),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum DeviceAuthCompletionResult {
+    Success { completion: DeviceAuthCompletion },
+    Failed(TokenFailure),
+}
+
+impl DeviceAuthCompletionResult {
+    pub fn as_success(&self) -> Option<&DeviceAuthCompletion> {
+        match self {
+            Self::Success { completion } => Some(completion),
+            Self::Failed(_) => None,
+        }
+    }
+    pub fn as_failure(&self) -> Option<&TokenFailure> {
+        match self {
+            Self::Success { .. } => None,
+            Self::Failed(failure) => Some(failure),
+        }
+    }
+}
+
+fn failed_result(
+    reason: TokenFailureReason,
+    message: String,
+    status_code: Option<i64>,
+) -> TokenFailure {
+    TokenFailure {
+        reason: Some(reason),
+        status_code,
+        message: Some(message),
+    }
+}
+
+fn aborted_failure() -> TokenFailure {
+    failed_result(
+        TokenFailureReason::NetworkError,
+        DEVICE_AUTH_ABORTED_MESSAGE.to_string(),
+        None,
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Sleep with abort
+// ---------------------------------------------------------------------------
+
+struct Aborted;
+
+async fn sleep_with_abort(ms: i64, options: &DeviceAuthFlowOptions) -> Result<(), Aborted> {
+    let sleep_future: Pin<Box<dyn Future<Output = ()> + Send>> = match &options.sleep {
+        Some(sleep) => sleep(ms),
+        None => Box::pin(tokio::time::sleep(std::time::Duration::from_millis(
+            ms.max(0) as u64,
+        ))),
+    };
+    match &options.signal {
+        None => {
+            sleep_future.await;
+            Ok(())
+        }
+        Some(signal) => {
+            if signal.is_aborted() {
+                return Err(Aborted);
+            }
+            let signal = Arc::clone(signal);
+            tokio::select! {
+                _ = sleep_future => Ok(()),
+                _ = signal.cancelled() => Err(Aborted),
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// JS-compatible parsing helpers
+// ---------------------------------------------------------------------------
+
+fn is_pending_status(status: u16) -> bool {
+    status == 403 || status == 404 || DEVICE_AUTH_TRANSIENT_PENDING_STATUSES.contains(&status)
+}
+
+/// `Number.parseFloat` prefix semantics: parse the longest leading float.
+fn js_parse_float(input: &str) -> Option<f64> {
+    let s = input.trim_start();
+    let bytes = s.as_bytes();
+    let mut i = 0usize;
+    if i < bytes.len() && (bytes[i] == b'+' || bytes[i] == b'-') {
+        i += 1;
+    }
+    let int_start = i;
+    while i < bytes.len() && bytes[i].is_ascii_digit() {
+        i += 1;
+    }
+    let has_int = i > int_start;
+    let mut has_frac = false;
+    if i < bytes.len() && bytes[i] == b'.' {
+        let frac_start = i + 1;
+        let mut j = frac_start;
+        while j < bytes.len() && bytes[j].is_ascii_digit() {
+            j += 1;
+        }
+        if has_int || j > frac_start {
+            has_frac = true;
+            i = j;
+        }
+    }
+    if !has_int && !has_frac {
+        return None;
+    }
+    // Optional exponent.
+    let mantissa_end = i;
+    if i < bytes.len() && (bytes[i] == b'e' || bytes[i] == b'E') {
+        let mut j = i + 1;
+        if j < bytes.len() && (bytes[j] == b'+' || bytes[j] == b'-') {
+            j += 1;
+        }
+        let digit_start = j;
+        while j < bytes.len() && bytes[j].is_ascii_digit() {
+            j += 1;
+        }
+        if j > digit_start {
+            i = j;
+        } else {
+            i = mantissa_end;
+        }
+    }
+    s[..i].parse::<f64>().ok()
+}
+
+/// JS `Number(str)` strict semantics for the subset that matters here:
+/// finite decimal numbers (the whole trimmed string — no prefix parsing).
+fn js_number(input: &str) -> Option<f64> {
+    let t = input.trim();
+    if t.is_empty() {
+        return None;
+    }
+    match t.parse::<f64>() {
+        Ok(v) if v.is_finite() => Some(v),
+        _ => None,
+    }
+}
+
+/// `^\d+(?:\.\d+)?$`
+fn is_plain_numeric_string(s: &str) -> bool {
+    let bytes = s.as_bytes();
+    if bytes.is_empty() {
+        return false;
+    }
+    let mut i = 0usize;
+    let int_start = i;
+    while i < bytes.len() && bytes[i].is_ascii_digit() {
+        i += 1;
+    }
+    if i == int_start {
+        return false;
+    }
+    if i == bytes.len() {
+        return true;
+    }
+    if bytes[i] != b'.' {
+        return false;
+    }
+    i += 1;
+    let frac_start = i;
+    while i < bytes.len() && bytes[i].is_ascii_digit() {
+        i += 1;
+    }
+    i > frac_start && i == bytes.len()
+}
+
+/// Days since 1970-01-01 for a civil date (Howard Hinnant's algorithm).
+fn days_from_civil(year: i64, month: u32, day: u32) -> i64 {
+    let y = year - if month <= 2 { 1 } else { 0 };
+    let era = if y >= 0 { y } else { y - 399 } / 400;
+    let yoe = y - era * 400;
+    let mp = if month > 2 { month - 3 } else { month + 9 } as i64;
+    let doy = (153 * mp + 2) / 5 + day as i64 - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    era * 146_097 + doe - 719_468
+}
+
+fn parse_u32(s: &str) -> Option<u32> {
+    if s.is_empty() || !s.bytes().all(|b| b.is_ascii_digit()) {
+        return None;
+    }
+    s.parse().ok()
+}
+
+/// ISO 8601 subset: `YYYY-MM-DD[THH:MM[:SS[.fff]]][Z|±HH:MM|±HHMM]`.
+/// A missing offset is treated as UTC (JS treats date-times without offsets
+/// as LOCAL time; UTC is the deterministic choice for server payloads).
+fn parse_iso_8601_ms(s: &str) -> Option<i64> {
+    let (date_part, rest) = match s.find(['T', 't']) {
+        Some(pos) => (&s[..pos], Some(&s[pos + 1..])),
+        None => (s, None),
+    };
+    let mut date_it = date_part.split('-');
+    let year: i64 = {
+        let y = date_it.next()?;
+        if y.len() != 4 {
+            return None;
+        }
+        parse_u32(y)? as i64
+    };
+    let month = parse_u32(date_it.next()?)?;
+    let day = parse_u32(date_it.next()?)?;
+    if date_it.next().is_some() || !(1..=12).contains(&month) || !(1..=31).contains(&day) {
+        return None;
+    }
+
+    let mut hour = 0u32;
+    let mut minute = 0u32;
+    let mut second = 0u32;
+    let mut frac_ms = 0i64;
+    let mut offset_min = 0i64;
+
+    if let Some(time_str) = rest {
+        // Split off the zone designator.
+        let (clock, zone): (&str, Option<&str>) =
+            if let Some(stripped) = time_str.strip_suffix(['Z', 'z']) {
+                (stripped, Some("Z"))
+            } else if let Some(pos) = time_str.rfind(['+', '-']) {
+                if pos > 0 {
+                    (&time_str[..pos], Some(&time_str[pos..]))
+                } else {
+                    (time_str, None)
+                }
+            } else {
+                (time_str, None)
+            };
+
+        let mut clock_it = clock.split(':');
+        hour = parse_u32(clock_it.next()?)?;
+        minute = parse_u32(clock_it.next()?)?;
+        if let Some(sec_part) = clock_it.next() {
+            let (sec_str, frac_str) = match sec_part.split_once('.') {
+                Some((sec, frac)) => (sec, Some(frac)),
+                None => (sec_part, None),
+            };
+            second = parse_u32(sec_str)?;
+            if let Some(frac) = frac_str {
+                if frac.is_empty() || !frac.bytes().all(|b| b.is_ascii_digit()) {
+                    return None;
+                }
+                let padded = format!("{frac:0<3}");
+                frac_ms = parse_u32(&padded[..3])? as i64;
+            }
+        }
+        if clock_it.next().is_some() || hour > 23 || minute > 59 || second > 60 {
+            return None;
+        }
+
+        if let Some(zone) = zone
+            && zone != "Z"
+        {
+            let sign: i64 = if zone.starts_with('-') { -1 } else { 1 };
+            let digits = &zone[1..];
+            let (oh, om) = match digits.split_once(':') {
+                Some((h, m)) => (parse_u32(h)?, parse_u32(m)?),
+                None => match digits.len() {
+                    4 => (parse_u32(&digits[..2])?, parse_u32(&digits[2..])?),
+                    2 => (parse_u32(digits)?, 0),
+                    _ => return None,
+                },
+            };
+            offset_min = sign * (oh as i64 * 60 + om as i64);
+        }
+    }
+
+    let days = days_from_civil(year, month, day);
+    let ms = days * 86_400_000
+        + hour as i64 * 3_600_000
+        + minute as i64 * 60_000
+        + second as i64 * 1_000
+        + frac_ms
+        - offset_min * 60_000;
+    Some(ms)
+}
+
+/// RFC 1123 / RFC 2822 HTTP dates: `[Www, ]DD Mon YYYY HH:MM:SS GMT`.
+fn parse_http_date_ms(s: &str) -> Option<i64> {
+    const MONTHS: [&str; 12] = [
+        "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec",
+    ];
+    let s = s.trim();
+    // Strip an optional leading weekday ("Sun, ").
+    let rest = match s.split_once(',') {
+        Some((_, tail)) => tail.trim_start(),
+        None => s,
+    };
+    let tokens: Vec<&str> = rest.split_whitespace().collect();
+    if tokens.len() < 4 {
+        return None;
+    }
+    let day = parse_u32(tokens[0])?;
+    let month = MONTHS
+        .iter()
+        .position(|m| m.eq_ignore_ascii_case(tokens[1]))? as u32
+        + 1;
+    let year: i64 = parse_u32(tokens[2])? as i64;
+    let mut clock_it = tokens[3].split(':');
+    let hour = parse_u32(clock_it.next()?)?;
+    let minute = parse_u32(clock_it.next()?)?;
+    let second = parse_u32(clock_it.next()?)?;
+    if clock_it.next().is_some()
+        || !(1..=31).contains(&day)
+        || hour > 23
+        || minute > 59
+        || second > 60
+    {
+        return None;
+    }
+    // Zone: only UTC spellings are supported.
+    if let Some(zone) = tokens.get(4)
+        && !matches!(
+            zone.to_ascii_uppercase().as_str(),
+            "GMT" | "UT" | "UTC" | "+0000"
+        )
+    {
+        return None;
+    }
+    let days = days_from_civil(year, month, day);
+    Some(
+        days * 86_400_000
+            + hour as i64 * 3_600_000
+            + minute as i64 * 60_000
+            + second as i64 * 1_000,
+    )
+}
+
+/// `Date.parse` for the formats that occur in this flow (ISO 8601 and HTTP
+/// dates). Anything else → `None` (NaN in JS).
+fn js_date_parse_ms(input: &str) -> Option<i64> {
+    let s = input.trim();
+    if s.is_empty() {
+        return None;
+    }
+    parse_iso_8601_ms(s).or_else(|| parse_http_date_ms(s))
+}
+
+fn parse_retry_after_ms(value: Option<&str>, now_ms: i64) -> Option<i64> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    if let Some(seconds) = js_number(trimmed) {
+        if seconds >= 0.0 {
+            return Some((seconds * 1000.0).ceil() as i64);
+        }
+        return None;
+    }
+    js_date_parse_ms(trimmed).map(|date_ms| (date_ms - now_ms).max(0))
+}
+
+fn apply_light_jitter(delay_ms: i64, options: &DeviceAuthFlowOptions) -> i64 {
+    let jitter_ratio = 1.0 + (random_of(options) - 0.5) * 0.2;
+    ((delay_ms as f64 * jitter_ratio).round() as i64).max(1_000)
+}
+
+fn resolve_poll_delay_ms(
+    status: u16,
+    retry_after: Option<&str>,
+    device_code: &DeviceAuthCode,
+    now_ms: i64,
+    options: &DeviceAuthFlowOptions,
+) -> i64 {
+    if let Some(retry_after_ms) = parse_retry_after_ms(retry_after, now_ms) {
+        return retry_after_ms.max(1_000);
+    }
+    if status == 403 || status == 404 {
+        return device_code.interval_ms;
+    }
+    apply_light_jitter(device_code.interval_ms, options)
+}
+
+fn parse_interval_ms(value: Option<&Value>) -> i64 {
+    match value {
+        Some(Value::Number(n)) => {
+            if let Some(v) = n.as_f64()
+                && v.is_finite()
+                && v > 0.0
+            {
+                return (v * 1000.0).trunc() as i64;
+            }
+            DEVICE_AUTH_DEFAULT_INTERVAL_MS
+        }
+        Some(Value::String(s)) => {
+            if let Some(parsed) = js_parse_float(s.trim())
+                && parsed.is_finite()
+                && parsed > 0.0
+            {
+                return (parsed * 1000.0).trunc() as i64;
+            }
+            DEVICE_AUTH_DEFAULT_INTERVAL_MS
+        }
+        _ => DEVICE_AUTH_DEFAULT_INTERVAL_MS,
+    }
+}
+
+/// `expires_at`: absolute — epoch seconds when `< 1e10`, else epoch ms;
+/// numeric strings the same; other strings via `Date.parse`.
+fn parse_absolute_expiration_ms(value: Option<&Value>) -> Option<i64> {
+    match value? {
+        Value::Number(n) => {
+            let v = n.as_f64()?;
+            if v.is_finite() && v > 0.0 {
+                Some(if v < 10_000_000_000.0 {
+                    (v * 1000.0) as i64
+                } else {
+                    v as i64
+                })
+            } else {
+                None
+            }
+        }
+        Value::String(s) => {
+            let trimmed = s.trim();
+            if is_plain_numeric_string(trimmed) {
+                let n = js_parse_float(trimmed)?;
+                Some(if n < 10_000_000_000.0 {
+                    (n * 1000.0) as i64
+                } else {
+                    n as i64
+                })
+            } else {
+                js_date_parse_ms(trimmed)
+            }
+        }
+        _ => None,
+    }
+}
+
+/// `expires_in`: relative seconds (`now + trunc(seconds*1000)`); numeric
+/// strings the same; other strings via `Date.parse` as absolute.
+fn parse_expiration_ms(value: Option<&Value>, now_ms: i64) -> Option<i64> {
+    match value? {
+        Value::Number(n) => {
+            let v = n.as_f64()?;
+            if v.is_finite() && v > 0.0 {
+                Some(now_ms + (v * 1000.0).trunc() as i64)
+            } else {
+                None
+            }
+        }
+        Value::String(s) => {
+            let trimmed = s.trim();
+            if is_plain_numeric_string(trimmed) {
+                let seconds = js_parse_float(trimmed)?;
+                Some(now_ms + (seconds * 1000.0).trunc() as i64)
+            } else {
+                js_date_parse_ms(trimmed)
+            }
+        }
+        _ => None,
+    }
+}
+
+fn parse_non_empty_string(value: Option<&Value>) -> Option<String> {
+    let s = value?.as_str()?;
+    let trimmed = s.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn parse_device_code_payload(
+    payload: &serde_json::Map<String, Value>,
+    now_ms: i64,
+) -> Option<DeviceAuthCode> {
+    let device_auth_id = parse_non_empty_string(payload.get("device_auth_id"))?;
+    let user_code = parse_non_empty_string(payload.get("user_code"))
+        .or_else(|| parse_non_empty_string(payload.get("usercode")))?;
+    let expires_at_ms = parse_absolute_expiration_ms(payload.get("expires_at"))
+        .or_else(|| parse_expiration_ms(payload.get("expires_in"), now_ms));
+    Some(DeviceAuthCode {
+        verification_url: DEVICE_AUTH_VERIFICATION_URL.to_string(),
+        user_code,
+        device_auth_id,
+        interval_ms: parse_interval_ms(payload.get("interval")),
+        expires_at_ms,
+    })
+}
+
+fn parse_completion_payload(
+    payload: &serde_json::Map<String, Value>,
+) -> Option<DeviceAuthCompletion> {
+    let authorization_code = parse_non_empty_string(payload.get("authorization_code"))?;
+    let code_verifier = parse_non_empty_string(payload.get("code_verifier"))?;
+    Some(DeviceAuthCompletion {
+        authorization_code,
+        code_verifier,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+// ---------------------------------------------------------------------------
+
+fn api_base(options: &DeviceAuthFlowOptions) -> String {
+    let base = options
+        .base_url
+        .as_deref()
+        .unwrap_or(DEVICE_AUTH_BASE_URL)
+        .trim_end_matches('/')
+        .to_string();
+    format!("{base}/api/accounts")
+}
+
+async fn post_json_with_abort(
+    url: &str,
+    body: Value,
+    options: &DeviceAuthFlowOptions,
+) -> Result<Result<reqwest::Response, reqwest::Error>, Aborted> {
+    let client = reqwest::Client::new();
+    let request = client
+        .post(url)
+        .header("Content-Type", "application/json")
+        .body(body.to_string())
+        .send();
+    match &options.signal {
+        None => Ok(request.await),
+        Some(signal) => {
+            if signal.is_aborted() {
+                return Err(Aborted);
+            }
+            let signal = Arc::clone(signal);
+            tokio::select! {
+                result = request => Ok(result),
+                _ = signal.cancelled() => Err(Aborted),
+            }
+        }
+    }
+}
+
+async fn read_json_record(response: reqwest::Response) -> Option<serde_json::Map<String, Value>> {
+    let text = response.text().await.unwrap_or_default();
+    if text.trim().is_empty() {
+        return None;
+    }
+    let value: Value = serde_json::from_str(&text).ok()?;
+    match value {
+        Value::Object(map) => Some(map),
+        _ => None,
+    }
+}
+
+async fn read_failure_text(response: reqwest::Response) -> String {
+    let text = response.text().await.unwrap_or_default();
+    sanitize_oauth_response_body_for_log(&text)
+}
+
+fn format_wait_budget(timeout_ms: i64) -> String {
+    let total_seconds = ((timeout_ms as f64) / 1000.0).ceil().max(1.0) as i64;
+    if total_seconds < 60 {
+        return format!(
+            "{total_seconds} second{}",
+            if total_seconds == 1 { "" } else { "s" }
+        );
+    }
+    let total_minutes = ((total_seconds as f64) / 60.0).ceil() as i64;
+    format!(
+        "{total_minutes} minute{}",
+        if total_minutes == 1 { "" } else { "s" }
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/// Request a device-auth user code (TS `requestDeviceAuthorization`).
+///
+/// A 404 HERE is terminal — the server does not offer device auth (spec 07
+/// gotcha 2). Contrast with the token poll, where 404 is a pending state.
+pub async fn request_device_authorization(options: &DeviceAuthFlowOptions) -> DeviceAuthCodeResult {
+    if is_aborted(options) {
+        return DeviceAuthCodeResult::Failed(aborted_failure());
+    }
+    let url = format!("{}/deviceauth/usercode", api_base(options));
+    let response =
+        match post_json_with_abort(&url, json!({ "client_id": CLIENT_ID }), options).await {
+            Err(Aborted) => return DeviceAuthCodeResult::Failed(aborted_failure()),
+            Ok(Err(error)) => {
+                if is_aborted(options) {
+                    return DeviceAuthCodeResult::Failed(aborted_failure());
+                }
+                return DeviceAuthCodeResult::Failed(failed_result(
+                    TokenFailureReason::NetworkError,
+                    error.to_string(),
+                    None,
+                ));
+            }
+            Ok(Ok(response)) => response,
+        };
+    let status = response.status().as_u16();
+    if !(200..300).contains(&status) {
+        if status == 404 {
+            return DeviceAuthCodeResult::Failed(failed_result(
+                TokenFailureReason::HttpError,
+                "Device auth login is not enabled for this Codex server. Use browser login or --manual."
+                    .to_string(),
+                Some(404),
+            ));
+        }
+        let safe_text = read_failure_text(response).await;
+        let message = if safe_text.is_empty() {
+            format!("Device code request failed with status {status}")
+        } else {
+            safe_text
+        };
+        return DeviceAuthCodeResult::Failed(failed_result(
+            TokenFailureReason::HttpError,
+            message,
+            Some(status as i64),
+        ));
+    }
+
+    let payload = read_json_record(response).await;
+    let device_code = payload
+        .as_ref()
+        .and_then(|record| parse_device_code_payload(record, now_of(options)));
+    match device_code {
+        Some(device_code) => DeviceAuthCodeResult::Success { device_code },
+        None => DeviceAuthCodeResult::Failed(failed_result(
+            TokenFailureReason::InvalidResponse,
+            "Device code request response failed schema validation".to_string(),
+            None,
+        )),
+    }
+}
+
+fn print_device_authorization_prompt(
+    device_code: &DeviceAuthCode,
+    options: &DeviceAuthFlowOptions,
+    timeout_ms: i64,
+    now_ms: i64,
+) {
+    let effective_timeout_ms = match device_code.expires_at_ms {
+        None => timeout_ms,
+        Some(expires_at_ms) => timeout_ms.min((expires_at_ms - now_ms).max(0)),
+    };
+    log_line(options, "Device auth login");
+    log_line(options, &format!("Open: {}", device_code.verification_url));
+    log_line(options, &format!("Code: {}", device_code.user_code));
+    log_line(
+        options,
+        &format!(
+            "This code expires in {}. Never share it.",
+            format_wait_budget(effective_timeout_ms)
+        ),
+    );
+}
+
+/// Poll the device-auth token endpoint until the user approves, the budget
+/// runs out, or a terminal error arrives (TS `pollDeviceAuthorization`).
+///
+/// Bare 403/404 are PENDING (deliberate non-RFC behavior — see the module
+/// docs); only 408/429/502/503/504 receive ±10 % jitter; `Retry-After`
+/// overrides with a 1000 ms floor.
+pub async fn poll_device_authorization(
+    device_code: &DeviceAuthCode,
+    options: &DeviceAuthFlowOptions,
+) -> DeviceAuthCompletionResult {
+    let start_ms = now_of(options);
+    let timeout_ms = options.timeout_ms.unwrap_or(DEVICE_AUTH_TIMEOUT_MS);
+    let deadline = match device_code.expires_at_ms {
+        Some(expires_at_ms) => (start_ms + timeout_ms).min(expires_at_ms),
+        None => start_ms + timeout_ms,
+    };
+    let effective_timeout_ms = (deadline - start_ms).max(0);
+    let url = format!("{}/deviceauth/token", api_base(options));
+
+    loop {
+        if is_aborted(options) {
+            return DeviceAuthCompletionResult::Failed(aborted_failure());
+        }
+        let body = json!({
+            "device_auth_id": device_code.device_auth_id,
+            "user_code": device_code.user_code,
+        });
+        let response = match post_json_with_abort(&url, body, options).await {
+            Err(Aborted) => return DeviceAuthCompletionResult::Failed(aborted_failure()),
+            Ok(Err(error)) => {
+                if is_aborted(options) {
+                    return DeviceAuthCompletionResult::Failed(aborted_failure());
+                }
+                return DeviceAuthCompletionResult::Failed(failed_result(
+                    TokenFailureReason::NetworkError,
+                    error.to_string(),
+                    None,
+                ));
+            }
+            Ok(Ok(response)) => response,
+        };
+
+        let status = response.status().as_u16();
+        if (200..300).contains(&status) {
+            let payload = read_json_record(response).await;
+            let completion = payload.as_ref().and_then(parse_completion_payload);
+            return match completion {
+                Some(completion) => DeviceAuthCompletionResult::Success { completion },
+                None => DeviceAuthCompletionResult::Failed(failed_result(
+                    TokenFailureReason::InvalidResponse,
+                    "Device auth token response failed schema validation".to_string(),
+                    None,
+                )),
+            };
+        }
+
+        if is_pending_status(status) {
+            let now_ms = now_of(options);
+            let remaining_ms = deadline - now_ms;
+            if remaining_ms <= 0 {
+                return DeviceAuthCompletionResult::Failed(failed_result(
+                    TokenFailureReason::Timeout,
+                    format!(
+                        "Device auth timed out after {}",
+                        format_wait_budget(effective_timeout_ms)
+                    ),
+                    None,
+                ));
+            }
+            let retry_after = response
+                .headers()
+                .get("retry-after")
+                .and_then(|v| v.to_str().ok())
+                .map(str::to_string);
+            let delay_ms =
+                resolve_poll_delay_ms(status, retry_after.as_deref(), device_code, now_ms, options);
+            if sleep_with_abort(delay_ms.min(remaining_ms), options)
+                .await
+                .is_err()
+            {
+                return DeviceAuthCompletionResult::Failed(aborted_failure());
+            }
+            continue;
+        }
+
+        let safe_text = read_failure_text(response).await;
+        let message = if safe_text.is_empty() {
+            format!("Device auth failed with status {status}")
+        } else {
+            safe_text
+        };
+        return DeviceAuthCompletionResult::Failed(failed_result(
+            TokenFailureReason::HttpError,
+            message,
+            Some(status as i64),
+        ));
+    }
+}
+
+/// Full device auth flow: usercode request → user prompt → poll → code
+/// exchange with the DEVICE redirect URI (not the localhost one) — TS
+/// `runDeviceAuthFlow`, the only function the TS barrel re-exports.
+pub async fn run_device_auth_flow(options: &DeviceAuthFlowOptions) -> TokenResult {
+    let device_code_result = request_device_authorization(options).await;
+    let device_code = match device_code_result {
+        DeviceAuthCodeResult::Failed(failure) => return TokenResult::Failed(failure),
+        DeviceAuthCodeResult::Success { device_code } => device_code,
+    };
+    if is_aborted(options) {
+        return TokenResult::Failed(aborted_failure());
+    }
+
+    print_device_authorization_prompt(
+        &device_code,
+        options,
+        options.timeout_ms.unwrap_or(DEVICE_AUTH_TIMEOUT_MS),
+        now_of(options),
+    );
+
+    let completion_result = poll_device_authorization(&device_code, options).await;
+    let completion = match completion_result {
+        DeviceAuthCompletionResult::Failed(failure) => return TokenResult::Failed(failure),
+        DeviceAuthCompletionResult::Success { completion } => completion,
+    };
+
+    exchange_authorization_code_at(
+        options.token_url.as_deref().unwrap_or(TOKEN_URL),
+        &completion.authorization_code,
+        &completion.code_verifier,
+        Some(DEVICE_AUTH_REDIRECT_URI),
+    )
+    .await
+}
+
+// ===========================================================================
+// Tests (ported from test/device-auth.test.ts)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+    use std::sync::atomic::AtomicI64;
+    use wiremock::matchers::{body_json, header, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    // Pinned epochs (independently computed) so a js_date_parse_ms bug cannot
+    // silently pass its own round-trip.
+    const T_2026_04_26: i64 = 1_777_161_600_000; // 2026-04-26T00:00:00Z
+    const T_2026_05_15_NOON: i64 = 1_778_846_400_000; // 2026-05-15T12:00:00Z
+
+    fn fixed_now(now_ms: i64) -> NowFn {
+        Arc::new(move || now_ms)
+    }
+
+    fn recording_sleep() -> (SleepFn, Arc<Mutex<Vec<i64>>>) {
+        let calls: Arc<Mutex<Vec<i64>>> = Arc::new(Mutex::new(Vec::new()));
+        let calls_clone = Arc::clone(&calls);
+        let sleep: SleepFn = Arc::new(move |ms| {
+            calls_clone.lock().unwrap().push(ms);
+            Box::pin(async {})
+        });
+        (sleep, calls)
+    }
+
+    /// Sleep that advances an injected clock (the TS `nowMs += ms` mock).
+    fn advancing_clock() -> (NowFn, SleepFn, Arc<Mutex<Vec<i64>>>) {
+        let now = Arc::new(AtomicI64::new(0));
+        let calls: Arc<Mutex<Vec<i64>>> = Arc::new(Mutex::new(Vec::new()));
+        let now_reader = Arc::clone(&now);
+        let now_fn: NowFn = Arc::new(move || now_reader.load(Ordering::SeqCst));
+        let calls_clone = Arc::clone(&calls);
+        let sleep: SleepFn = Arc::new(move |ms| {
+            now.fetch_add(ms, Ordering::SeqCst);
+            calls_clone.lock().unwrap().push(ms);
+            Box::pin(async {})
+        });
+        (now_fn, sleep, calls)
+    }
+
+    fn recording_log() -> (LogFn, Arc<Mutex<Vec<String>>>) {
+        let lines: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+        let lines_clone = Arc::clone(&lines);
+        let log: LogFn = Arc::new(move |message| {
+            lines_clone.lock().unwrap().push(message.to_string());
+        });
+        (log, lines)
+    }
+
+    fn sample_device_code(interval_ms: i64, expires_at_ms: Option<i64>) -> DeviceAuthCode {
+        DeviceAuthCode {
+            verification_url: DEVICE_AUTH_VERIFICATION_URL.to_string(),
+            user_code: "ABCD-1234".to_string(),
+            device_auth_id: "device-auth-1".to_string(),
+            interval_ms,
+            expires_at_ms,
+        }
+    }
+
+    async fn mount_usercode(server: &MockServer, body: Value) {
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/usercode"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(body))
+            .mount(server)
+            .await;
+    }
+
+    #[test]
+    fn date_parser_pins() {
+        assert_eq!(js_date_parse_ms("2026-04-26T00:00:00Z"), Some(T_2026_04_26));
+        assert_eq!(
+            js_date_parse_ms("2026-05-15T12:00:00Z"),
+            Some(T_2026_05_15_NOON)
+        );
+        assert_eq!(
+            js_date_parse_ms("Sun, 26 Apr 2026 00:00:04 GMT"),
+            Some(T_2026_04_26 + 4_000)
+        );
+        assert_eq!(js_date_parse_ms("not-a-date"), None);
+    }
+
+    #[tokio::test]
+    async fn requests_user_code_and_parses_string_interval_and_iso_expiry() {
+        let now_ms = T_2026_04_26;
+        let expires_at_ms = now_ms + 15 * 60 * 1000;
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/usercode"))
+            .and(header("Content-Type", "application/json"))
+            .and(body_json(
+                json!({ "client_id": "app_EMoamEEZ73f0CkXaXp7hrann" }),
+            ))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "device_auth_id": "device-auth-1",
+                "user_code": "ABCD-1234",
+                "interval": "7.5",
+                "expires_at": "2026-04-26T00:15:00.000Z",
+            })))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(now_ms)),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        assert_eq!(
+            result.as_success(),
+            Some(&DeviceAuthCode {
+                verification_url: DEVICE_AUTH_VERIFICATION_URL.to_string(),
+                user_code: "ABCD-1234".to_string(),
+                device_auth_id: "device-auth-1".to_string(),
+                interval_ms: 7_500,
+                expires_at_ms: Some(expires_at_ms),
+            })
+        );
+    }
+
+    #[tokio::test]
+    async fn accepts_usercode_alias_and_numeric_interval() {
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({ "device_auth_id": "device-auth-2", "usercode": "WXYZ-9876", "interval": 3 }),
+        )
+        .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let device_code = result.as_success().expect("success");
+        assert_eq!(device_code.user_code, "WXYZ-9876");
+        assert_eq!(device_code.device_auth_id, "device-auth-2");
+        assert_eq!(device_code.interval_ms, 3_000);
+        assert_eq!(device_code.expires_at_ms, None);
+    }
+
+    #[tokio::test]
+    async fn parses_expires_at_as_epoch_seconds_absolute() {
+        let now_ms = T_2026_04_26;
+        let expires_at_seconds = T_2026_05_15_NOON / 1000;
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({
+                "device_auth_id": "d",
+                "user_code": "ABCD-1111",
+                "interval": 5,
+                "expires_at": expires_at_seconds,
+            }),
+        )
+        .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(now_ms)),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        assert_eq!(
+            result.as_success().unwrap().expires_at_ms,
+            Some(expires_at_seconds * 1000)
+        );
+    }
+
+    #[tokio::test]
+    async fn parses_expires_at_as_epoch_ms_above_boundary() {
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({
+                "device_auth_id": "d",
+                "user_code": "ABCD-2222",
+                "interval": 5,
+                "expires_at": T_2026_05_15_NOON,
+            }),
+        )
+        .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(T_2026_04_26)),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        assert_eq!(
+            result.as_success().unwrap().expires_at_ms,
+            Some(T_2026_05_15_NOON)
+        );
+    }
+
+    #[tokio::test]
+    async fn parses_expires_at_as_numeric_string_of_seconds() {
+        let expires_at_seconds = T_2026_05_15_NOON / 1000;
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({
+                "device_auth_id": "d",
+                "user_code": "ABCD-3333",
+                "interval": 5,
+                "expires_at": expires_at_seconds.to_string(),
+            }),
+        )
+        .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(T_2026_04_26)),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        assert_eq!(
+            result.as_success().unwrap().expires_at_ms,
+            Some(expires_at_seconds * 1000)
+        );
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_expires_in_when_expires_at_unparseable() {
+        let now_ms = T_2026_04_26;
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({
+                "device_auth_id": "d",
+                "user_code": "ABCD-4444",
+                "interval": 5,
+                "expires_at": "not-a-date",
+                "expires_in": 600,
+            }),
+        )
+        .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(now_ms)),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        assert_eq!(
+            result.as_success().unwrap().expires_at_ms,
+            Some(now_ms + 600_000)
+        );
+    }
+
+    #[tokio::test]
+    async fn usercode_404_is_terminal_with_clear_message() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/usercode"))
+            .respond_with(ResponseTemplate::new(404).set_body_string("not found"))
+            .mount(&server)
+            .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(404));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some(
+                "Device auth login is not enabled for this Codex server. Use browser login or --manual."
+            )
+        );
+    }
+
+    #[tokio::test]
+    async fn usercode_network_failure_is_network_error() {
+        let options = DeviceAuthFlowOptions {
+            base_url: Some("http://127.0.0.1:1".to_string()),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+    }
+
+    #[tokio::test]
+    async fn pre_aborted_signal_skips_usercode_request() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/usercode"))
+            .respond_with(ResponseTemplate::new(200))
+            .expect(0)
+            .mount(&server)
+            .await;
+        let signal = AbortSignal::new();
+        signal.abort();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            signal: Some(signal),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert_eq!(failure.message.as_deref(), Some("aborted"));
+    }
+
+    #[tokio::test]
+    async fn usercode_fails_on_invalid_success_payload() {
+        let server = MockServer::start().await;
+        mount_usercode(&server, json!({ "user_code": "ABCD-1234", "interval": "5" })).await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Device code request response failed schema validation")
+        );
+    }
+
+    #[tokio::test]
+    async fn usercode_failures_are_sanitized() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/usercode"))
+            .respond_with(ResponseTemplate::new(500).set_body_string("server unavailable"))
+            .mount(&server)
+            .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = request_device_authorization(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(500));
+        assert_eq!(failure.message.as_deref(), Some("server unavailable"));
+    }
+
+    #[tokio::test]
+    async fn treats_403_and_404_poll_responses_as_pending_before_success() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .up_to_n_times(1)
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(404))
+            .up_to_n_times(1)
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .and(body_json(json!({
+                "device_auth_id": "device-auth-1",
+                "user_code": "ABCD-1234",
+            })))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+                "code_challenge": "code-challenge",
+            })))
+            .mount(&server)
+            .await;
+
+        let (sleep, calls) = recording_sleep();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            sleep: Some(sleep),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(2_000, None), &options).await;
+        assert_eq!(
+            result.as_success(),
+            Some(&DeviceAuthCompletion {
+                authorization_code: "authorization-code".to_string(),
+                code_verifier: "code-verifier".to_string(),
+            })
+        );
+        // 403/404 use the exact server interval — NO jitter.
+        assert_eq!(*calls.lock().unwrap(), vec![2_000, 2_000]);
+    }
+
+    #[tokio::test]
+    async fn honors_retry_after_seconds_for_429() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(429).insert_header("Retry-After", "7"))
+            .up_to_n_times(1)
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+            })))
+            .mount(&server)
+            .await;
+        let (sleep, calls) = recording_sleep();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            sleep: Some(sleep),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(2_000, None), &options).await;
+        assert!(result.as_success().is_some());
+        assert_eq!(*calls.lock().unwrap(), vec![7_000]);
+    }
+
+    #[tokio::test]
+    async fn honors_retry_after_http_dates_for_transient_statuses() {
+        let now_ms = T_2026_04_26;
+        // now + 4000 ms as an HTTP date (2026-04-26 is a Sunday).
+        let retry_at = "Sun, 26 Apr 2026 00:00:04 GMT";
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(503).insert_header("Retry-After", retry_at))
+            .up_to_n_times(1)
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+            })))
+            .mount(&server)
+            .await;
+        let (sleep, calls) = recording_sleep();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(fixed_now(now_ms)),
+            sleep: Some(sleep),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(2_000, None), &options).await;
+        assert!(result.as_success().is_some());
+        assert_eq!(*calls.lock().unwrap(), vec![4_000]);
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_jittered_interval_for_429_without_retry_after() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(429))
+            .up_to_n_times(1)
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+            })))
+            .mount(&server)
+            .await;
+        let (sleep, calls) = recording_sleep();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            sleep: Some(sleep),
+            // random() = 0.5 → jitter ratio exactly 1.0
+            random: Some(Arc::new(|| 0.5)),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(3_000, None), &options).await;
+        assert!(result.as_success().is_some());
+        assert_eq!(*calls.lock().unwrap(), vec![3_000]);
+    }
+
+    #[tokio::test]
+    async fn aborts_polling_without_issuing_another_token_request() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .expect(1)
+            .mount(&server)
+            .await;
+        let signal = AbortSignal::new();
+        // Sleep never resolves on its own; the abort must win the race.
+        let pending_sleep: SleepFn = Arc::new(|_| Box::pin(std::future::pending()));
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            signal: Some(Arc::clone(&signal)),
+            sleep: Some(pending_sleep),
+            timeout_ms: Some(10_000),
+            ..Default::default()
+        };
+        let device_code = sample_device_code(5_000, None);
+        let poll = tokio::spawn({
+            let options = options.clone();
+            async move { poll_device_authorization(&device_code, &options).await }
+        });
+        // Give the poll a moment to reach the sleep, then abort.
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        signal.abort();
+        let result = poll.await.unwrap();
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert_eq!(failure.message.as_deref(), Some("aborted"));
+    }
+
+    #[tokio::test]
+    async fn uses_server_expiration_as_polling_deadline() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .expect(3)
+            .mount(&server)
+            .await;
+        let (now_fn, sleep, calls) = advancing_clock();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(now_fn),
+            sleep: Some(sleep),
+            timeout_ms: Some(15_000),
+            ..Default::default()
+        };
+        let result =
+            poll_device_authorization(&sample_device_code(5_000, Some(6_000)), &options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::Timeout));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Device auth timed out after 6 seconds")
+        );
+        assert_eq!(*calls.lock().unwrap(), vec![5_000, 1_000]);
+    }
+
+    #[tokio::test]
+    async fn times_out_after_configured_wait_budget() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .expect(3)
+            .mount(&server)
+            .await;
+        let (now_fn, sleep, calls) = advancing_clock();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(now_fn),
+            sleep: Some(sleep),
+            timeout_ms: Some(10_000),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(5_000, None), &options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::Timeout));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Device auth timed out after 10 seconds")
+        );
+        assert_eq!(calls.lock().unwrap().len(), 2);
+    }
+
+    #[tokio::test]
+    async fn fails_polling_on_hard_non_pending_responses() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(400).set_body_string("bad request"))
+            .mount(&server)
+            .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(5_000, None), &options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(400));
+        assert_eq!(failure.message.as_deref(), Some("bad request"));
+    }
+
+    #[tokio::test]
+    async fn fails_polling_on_invalid_completion_payloads() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({ "authorization_code": "missing-verifier" })),
+            )
+            .mount(&server)
+            .await;
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            ..Default::default()
+        };
+        let result = poll_device_authorization(&sample_device_code(5_000, None), &options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Device auth token response failed schema validation")
+        );
+    }
+
+    #[tokio::test]
+    async fn exchanges_authorization_code_with_device_redirect_uri() {
+        let now_ms = T_2026_04_26;
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({
+                "device_auth_id": "device-auth-1",
+                "user_code": "ABCD-1234",
+                "interval": "1",
+                "expires_in": "600",
+            }),
+        )
+        .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+                "code_challenge": "code-challenge",
+            })))
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "access_token": "access-token",
+                "refresh_token": "refresh-token",
+                "expires_in": 3600,
+                "id_token": "id-token",
+            })))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let (log, lines) = recording_log();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            token_url: Some(format!("{}/oauth/token", server.uri())),
+            log: Some(log),
+            now: Some(fixed_now(now_ms)),
+            ..Default::default()
+        };
+        let result = run_device_auth_flow(&options).await;
+        let success = result.as_success().expect("success");
+        assert_eq!(success.access, "access-token");
+        assert_eq!(success.refresh, "refresh-token");
+        assert_eq!(success.id_token.as_deref(), Some("id-token"));
+        assert_eq!(success.multi_account, Some(true));
+
+        let lines = lines.lock().unwrap().clone();
+        assert!(lines.contains(&"Device auth login".to_string()));
+        assert!(lines.contains(&format!("Open: {DEVICE_AUTH_VERIFICATION_URL}")));
+        assert!(lines.contains(&"Code: ABCD-1234".to_string()));
+        assert!(lines.contains(&"This code expires in 10 minutes. Never share it.".to_string()));
+        let joined = lines.join("\n");
+        for secret in [
+            "access-token",
+            "refresh-token",
+            "id-token",
+            "code-verifier",
+            "code_verifier",
+        ] {
+            assert!(!joined.contains(secret), "log leaked {secret}");
+        }
+
+        // The exchange used the DEVICE redirect URI (not localhost).
+        let requests = server.received_requests().await.unwrap();
+        let exchange = requests
+            .iter()
+            .find(|r| r.url.path() == "/oauth/token")
+            .expect("token exchange request");
+        let form: Vec<(String, String)> = url::form_urlencoded::parse(&exchange.body)
+            .map(|(k, v)| (k.into_owned(), v.into_owned()))
+            .collect();
+        let get = |key: &str| form.iter().find(|(k, _)| k == key).map(|(_, v)| v.clone());
+        assert_eq!(get("grant_type").as_deref(), Some("authorization_code"));
+        assert_eq!(
+            get("client_id").as_deref(),
+            Some("app_EMoamEEZ73f0CkXaXp7hrann")
+        );
+        assert_eq!(get("code").as_deref(), Some("authorization-code"));
+        assert_eq!(get("code_verifier").as_deref(), Some("code-verifier"));
+        assert_eq!(
+            get("redirect_uri").as_deref(),
+            Some(DEVICE_AUTH_REDIRECT_URI)
+        );
+    }
+
+    #[tokio::test]
+    async fn does_not_print_or_poll_when_aborted_after_usercode_response() {
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({ "device_auth_id": "device-auth-1", "user_code": "ABCD-1234", "interval": "1" }),
+        )
+        .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .expect(0)
+            .mount(&server)
+            .await;
+        let signal = AbortSignal::new();
+        // The TS test aborts from inside the fetch mock; here the injected
+        // clock (called while parsing the usercode payload) trips the signal
+        // after the request succeeded but before the abort check.
+        let abort_now: NowFn = {
+            let signal = Arc::clone(&signal);
+            Arc::new(move || {
+                signal.abort();
+                0
+            })
+        };
+        let (log, lines) = recording_log();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            signal: Some(signal),
+            now: Some(abort_now),
+            log: Some(log),
+            ..Default::default()
+        };
+        let result = run_device_auth_flow(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert_eq!(failure.message.as_deref(), Some("aborted"));
+        assert!(
+            lines.lock().unwrap().is_empty(),
+            "prompt must not print after abort"
+        );
+    }
+
+    #[tokio::test]
+    async fn does_not_leak_tokens_through_device_auth_logs_on_timeout() {
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({ "device_auth_id": "device-auth-1", "user_code": "ABCD-1234", "interval": "1" }),
+        )
+        .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(403))
+            .mount(&server)
+            .await;
+        let (now_fn, sleep, _calls) = advancing_clock();
+        let (log, lines) = recording_log();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            now: Some(now_fn),
+            sleep: Some(sleep),
+            log: Some(log),
+            timeout_ms: Some(2_000),
+            ..Default::default()
+        };
+        let result = run_device_auth_flow(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::Timeout));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Device auth timed out after 2 seconds")
+        );
+        let joined = lines.lock().unwrap().join("\n");
+        for secret in [
+            "access-token",
+            "refresh-token",
+            "id-token",
+            "code-verifier",
+            "code_verifier",
+        ] {
+            assert!(!joined.contains(secret), "log leaked {secret}");
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_token_exchange_failures_from_device_auth_flow() {
+        let server = MockServer::start().await;
+        mount_usercode(
+            &server,
+            json!({ "device_auth_id": "device-auth-1", "user_code": "ABCD-1234", "interval": "1" }),
+        )
+        .await;
+        Mock::given(method("POST"))
+            .and(path("/api/accounts/deviceauth/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "authorization_code": "authorization-code",
+                "code_verifier": "code-verifier",
+            })))
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(400).set_body_string("bad token"))
+            .mount(&server)
+            .await;
+        let (log, lines) = recording_log();
+        let options = DeviceAuthFlowOptions {
+            base_url: Some(server.uri()),
+            token_url: Some(format!("{}/oauth/token", server.uri())),
+            log: Some(log),
+            ..Default::default()
+        };
+        let result = run_device_auth_flow(&options).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(400));
+        assert_eq!(failure.message.as_deref(), Some("bad token"));
+        let joined = lines.lock().unwrap().join("\n");
+        for secret in [
+            "access-token",
+            "refresh-token",
+            "id-token",
+            "code-verifier",
+            "code_verifier",
+        ] {
+            assert!(!joined.contains(secret), "log leaked {secret}");
+        }
+    }
+
+    #[test]
+    fn format_wait_budget_matches_ts() {
+        assert_eq!(format_wait_budget(500), "1 second");
+        assert_eq!(format_wait_budget(1_000), "1 second");
+        assert_eq!(format_wait_budget(6_000), "6 seconds");
+        assert_eq!(format_wait_budget(59_000), "59 seconds");
+        assert_eq!(format_wait_budget(60_000), "1 minute");
+        assert_eq!(format_wait_budget(600_000), "10 minutes");
+        assert_eq!(format_wait_budget(900_000), "15 minutes");
+        assert_eq!(format_wait_budget(0), "1 second");
+    }
+}
diff --git a/crates/auth/src/lib.rs b/crates/auth/src/lib.rs
new file mode 100644
index 000000000..3587605fb
--- /dev/null
+++ b/crates/auth/src/lib.rs
@@ -0,0 +1,11 @@
+//! cma-auth - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod auth_rate_limit;
+pub mod browser;
+pub mod callback_guidance;
+pub mod callback_server;
+pub mod device_auth;
+pub mod local_client_tokens;
+pub mod oauth;
+pub mod org_override;
+pub mod refresh_lease;
+pub mod refresh_queue;
diff --git a/crates/auth/src/local_client_tokens.rs b/crates/auth/src/local_client_tokens.rs
new file mode 100644
index 000000000..379d207f2
--- /dev/null
+++ b/crates/auth/src/local_client_tokens.rs
@@ -0,0 +1,751 @@
+//! Port of `lib/local-client-tokens.ts` — persisted hashed bearer tokens for
+//! the local bridge (`local-client-tokens.json`).
+//!
+//! Behavior source: specs/07-auth.md §9 (+ gotchas 11–13).
+//!
+//! **Only SHA-256 hashes are stored; the plaintext (`cma_local_*`) is shown
+//! once at creation.** On-disk format is byte-compatible:
+//! `JSON.stringify(store, null, 2) + "\n"` with record field order
+//! `id, label, prefix, tokenHash, createdAt, lastUsedAt, revokedAt`
+//! (`null` literals, never absent).
+//!
+//! Write discipline (gotcha 11): a module-level write queue serializes the
+//! ENTIRE read-modify-write of every mutation; temp file (0600) + fsync +
+//! rename with 5×(10·2^n ms) retries on {EBUSY, EPERM, EAGAIN, ENOTEMPTY,
+//! EACCES}; dir mkdir 0700 + POSIX re-chmod 0700 (best-effort).
+//!
+//! `lastUsedAt` debounce (gotcha 12): advance in-memory on every verify;
+//! flush to disk only when never persisted or ≥ 60 s past the persisted value.
+
+use std::io;
+use std::path::PathBuf;
+use std::sync::LazyLock;
+
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use rand::TryRngCore;
+use rand::rngs::OsRng;
+use serde::Serialize;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use tokio::sync::Mutex as TokioMutex;
+
+use cma_core::fs_retry::{Backoff, FILE_RETRY_CODES, RetryOptions, with_retry};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::temp_path::temp_path_for;
+use cma_core::utils::{is_record, now_ms};
+
+/// One stored token record. Field order = serialization order (byte compat).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct LocalClientTokenRecord {
+    pub id: String,
+    pub label: String,
+    pub prefix: String,
+    #[serde(rename = "tokenHash")]
+    pub token_hash: String,
+    #[serde(rename = "createdAt")]
+    pub created_at: i64,
+    /// Serialized as a `null` literal when absent (never omitted).
+    #[serde(rename = "lastUsedAt")]
+    pub last_used_at: Option<i64>,
+    /// Serialized as a `null` literal when absent (never omitted).
+    #[serde(rename = "revokedAt")]
+    pub revoked_at: Option<i64>,
+}
+
+/// `{ "version": 1, "tokens": [...] }`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct LocalClientTokenStore {
+    pub version: u32,
+    pub tokens: Vec<LocalClientTokenRecord>,
+}
+
+/// `{ plainToken, record }` — the plaintext exists ONLY here, at creation.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CreatedLocalClientToken {
+    pub plain_token: String,
+    pub record: LocalClientTokenRecord,
+}
+
+const TOKEN_FILE_NAME: &str = "local-client-tokens.json";
+const TOKEN_PREFIX: &str = "cma_local";
+/// Debounce window for persisting a record's lastUsedAt: bearer verification
+/// is on the auth hot path of every authenticated bridge request, so we
+/// coalesce updates instead of temp-write+renaming per request. lastUsedAt is
+/// informational only (`bridge token list`).
+const LAST_USED_PERSIST_THRESHOLD_MS: i64 = 60_000;
+
+// The retryable code set {EBUSY, EPERM, EAGAIN, ENOTEMPTY, EACCES} is exactly
+// cma_core::fs_retry::FILE_RETRY_CODES; passed explicitly below so a change to
+// the shared default can never silently alter this call site's contract.
+const RETRYABLE_FS_CODES: &[&str] = FILE_RETRY_CODES;
+
+/// Module-level write queue: each queued task runs only after the previous one
+/// has fully settled (tokio Mutex = fair FIFO; errors cannot poison it).
+/// Routing the ENTIRE read-modify-write through here prevents lost updates
+/// between concurrent public ops.
+static WRITE_QUEUE: LazyLock<TokioMutex<()>> = LazyLock::new(|| TokioMutex::new(()));
+
+/// 5 attempts, `10 * 2^n` ms backoff (10/20/40/80) on the retryable code set.
+fn fs_retry_options() -> RetryOptions<io::Error> {
+    // `Backoff` gets the 1-based failed-attempt index: 10 * 2^(n-1).
+    RetryOptions::new(
+        5,
+        Backoff::from_fn(|failed_attempt| {
+            10u64.saturating_mul(1u64 << (failed_attempt.saturating_sub(1)).min(62))
+        }),
+    )
+    .with_codes(RETRYABLE_FS_CODES)
+}
+
+/// `normalizeLabel` — trim, non-empty, first 80 chars, default `"local-client"`.
+fn normalize_label(value: Option<&str>) -> String {
+    let trimmed = value.map(str::trim).unwrap_or("");
+    if trimmed.is_empty() {
+        "local-client".to_string()
+    } else {
+        trimmed.chars().take(80).collect()
+    }
+}
+
+/// `hashToken` — `"sha256:" + hex(sha256(utf8 token))`.
+fn hash_token(token: &str) -> String {
+    let digest = Sha256::digest(token.as_bytes());
+    let mut out = String::with_capacity(7 + 64);
+    out.push_str("sha256:");
+    for byte in digest {
+        use std::fmt::Write;
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+/// `createPlainToken` — `cma_local_<base64url(32 CSPRNG bytes)>` (53 chars).
+fn create_plain_token() -> String {
+    let mut bytes = [0u8; 32];
+    OsRng
+        .try_fill_bytes(&mut bytes)
+        .expect("CSPRNG unavailable: cannot generate local client token");
+    format!("{TOKEN_PREFIX}_{}", URL_SAFE_NO_PAD.encode(bytes))
+}
+
+/// `tokenPrefix` — first 18 chars (`"cma_local_" + 8`).
+fn token_prefix(token: &str) -> String {
+    token.chars().take(18).collect()
+}
+
+fn empty_store() -> LocalClientTokenStore {
+    LocalClientTokenStore {
+        version: 1,
+        tokens: Vec::new(),
+    }
+}
+
+/// JS "finite number" check on a JSON value.
+fn finite_number(value: Option<&Value>) -> Option<f64> {
+    value.and_then(Value::as_f64).filter(|number| number.is_finite())
+}
+
+/// `normalizeRecord` — drop records missing a non-blank `id` or a
+/// `sha256:`-prefixed `tokenHash`; normalize the rest.
+fn normalize_record(value: &Value) -> Option<LocalClientTokenRecord> {
+    if !is_record(value) {
+        return None;
+    }
+    let id = value.get("id").and_then(Value::as_str)?;
+    if id.trim().is_empty() {
+        return None;
+    }
+    let token_hash = value.get("tokenHash").and_then(Value::as_str)?;
+    if !token_hash.starts_with("sha256:") {
+        return None;
+    }
+    Some(LocalClientTokenRecord {
+        id: id.trim().to_string(),
+        label: normalize_label(value.get("label").and_then(Value::as_str)),
+        prefix: value
+            .get("prefix")
+            .and_then(Value::as_str)
+            .map(|prefix| prefix.chars().take(32).collect())
+            .unwrap_or_default(),
+        token_hash: token_hash.to_string(),
+        created_at: finite_number(value.get("createdAt")).map_or(0, |number| number as i64),
+        last_used_at: finite_number(value.get("lastUsedAt")).map(|number| number as i64),
+        revoked_at: finite_number(value.get("revokedAt")).map(|number| number as i64),
+    })
+}
+
+/// `normalizeStore` — non-record, `version !== 1`, or non-array `tokens` ⇒
+/// empty store; per-record normalization drops invalid entries.
+fn normalize_store(value: &Value) -> LocalClientTokenStore {
+    // JS `value.version !== 1` compares as a double: a JSON `1.0` passes.
+    if !is_record(value)
+        || value.get("version").and_then(Value::as_f64) != Some(1.0)
+        || !value.get("tokens").is_some_and(Value::is_array)
+    {
+        return empty_store();
+    }
+    let tokens = value
+        .get("tokens")
+        .and_then(Value::as_array)
+        .map(|entries| entries.iter().filter_map(normalize_record).collect())
+        .unwrap_or_default();
+    LocalClientTokenStore { version: 1, tokens }
+}
+
+/// `readFileWithRetry` — 5 attempts, retryable codes, 10·2^n backoff.
+async fn read_file_with_retry(path: &std::path::Path) -> io::Result<String> {
+    let path = path.to_path_buf();
+    with_retry(
+        || {
+            let path = path.clone();
+            async move { std::fs::read_to_string(&path) }
+        },
+        fs_retry_options(),
+    )
+    .await
+}
+
+/// `getLocalClientTokenPath()`.
+pub fn get_local_client_token_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(TOKEN_FILE_NAME)
+}
+
+/// `loadLocalClientTokenStore()` — NOT queued (snapshot read). Load errors are
+/// fail-open to an empty store with a warning, never a crash.
+pub async fn load_local_client_token_store() -> LocalClientTokenStore {
+    let path = get_local_client_token_path();
+    if !path.exists() {
+        return empty_store();
+    }
+    let loaded: Result<Value, String> = match read_file_with_retry(&path).await {
+        Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|error| error.to_string()),
+        Err(error) => Err(error.to_string()),
+    };
+    match loaded {
+        Ok(value) => normalize_store(&value),
+        Err(message) => {
+            let basename = path
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_else(|| path.to_string_lossy().into_owned());
+            log_warn(
+                &format!("Failed to load local client tokens from {basename}: {message}"),
+                None,
+            );
+            empty_store()
+        }
+    }
+}
+
+/// `writeStoreToDisk` — re-normalize, 0700 dir (+ best-effort POSIX chmod for
+/// pre-existing dirs), temp file 0600 + **fsync before rename** (a crash after
+/// the rename must not leave a truncated store), rename with retries, temp
+/// unlinked when never moved.
+async fn write_store_to_disk(store: &LocalClientTokenStore) -> io::Result<()> {
+    let path = get_local_client_token_path();
+    let payload = normalize_store(&serde_json::to_value(store).unwrap_or(Value::Null));
+    let dir = get_codex_multi_auth_dir();
+    // This store holds token hashes: keep the directory owner-only on POSIX
+    // (mode is a no-op on win32 / ACL-based).
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        let mut builder = std::fs::DirBuilder::new();
+        builder.recursive(true);
+        builder.mode(0o700);
+        builder.create(&dir)?;
+        // mkdir's mode only applies to a freshly-created dir; re-assert 0700
+        // so upgrades constrain a pre-existing multi-auth dir. Best-effort.
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700));
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::create_dir_all(&dir)?;
+    }
+
+    let temp_path = temp_path_for(&path);
+    let mut moved = false;
+    let outcome: io::Result<()> = async {
+        // Stage the payload at 0600 and fsync before rename (stress audit L3).
+        {
+            use std::io::Write;
+            let mut options = std::fs::OpenOptions::new();
+            options.write(true).create(true).truncate(true);
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::OpenOptionsExt;
+                options.mode(0o600);
+            }
+            let mut file = options.open(&temp_path)?;
+            file.write_all(format!("{}\n", stringify_pretty2(&payload)).as_bytes())?;
+            file.sync_all()?;
+        }
+        with_retry(
+            || {
+                let temp_path = temp_path.clone();
+                let path = path.clone();
+                async move { std::fs::rename(&temp_path, &path) }
+            },
+            fs_retry_options(),
+        )
+        .await?;
+        moved = true;
+        Ok(())
+    }
+    .await;
+    if !moved {
+        // Best-effort temp cleanup.
+        let _ = std::fs::remove_file(&temp_path);
+    }
+    outcome
+}
+
+/// `saveLocalClientTokenStore(store)` — queued write.
+pub async fn save_local_client_token_store(store: &LocalClientTokenStore) -> io::Result<()> {
+    let _queue = WRITE_QUEUE.lock().await;
+    write_store_to_disk(store).await
+}
+
+/// `createLocalClientTokenRecord({label?, now?})` — pure; the plaintext is
+/// returned exactly once.
+pub fn create_local_client_token_record(
+    label: Option<&str>,
+    now: Option<i64>,
+) -> CreatedLocalClientToken {
+    let plain_token = create_plain_token();
+    let record = LocalClientTokenRecord {
+        id: uuid::Uuid::new_v4().to_string(),
+        label: normalize_label(label),
+        prefix: token_prefix(&plain_token),
+        token_hash: hash_token(&plain_token),
+        created_at: now.unwrap_or_else(now_ms),
+        last_used_at: None,
+        revoked_at: None,
+    };
+    CreatedLocalClientToken {
+        plain_token,
+        record,
+    }
+}
+
+/// `addLocalClientToken({label?, now?})` — queued load→create→push→write.
+pub async fn add_local_client_token(
+    label: Option<&str>,
+    now: Option<i64>,
+) -> io::Result<CreatedLocalClientToken> {
+    let _queue = WRITE_QUEUE.lock().await;
+    let mut store = load_local_client_token_store().await;
+    let created = create_local_client_token_record(label, now);
+    store.tokens.push(created.record.clone());
+    write_store_to_disk(&store).await?;
+    Ok(created)
+}
+
+/// `rotateLocalClientToken({id, label?, now?})` — queued; missing or already
+/// revoked ⇒ None; else revoke the old record and append a new one (label
+/// defaults to the old label) in ONE write.
+pub async fn rotate_local_client_token(
+    id: &str,
+    label: Option<&str>,
+    now: Option<i64>,
+) -> io::Result<Option<CreatedLocalClientToken>> {
+    let _queue = WRITE_QUEUE.lock().await;
+    let mut store = load_local_client_token_store().await;
+    let Some(position) = store.tokens.iter().position(|record| record.id == id) else {
+        return Ok(None);
+    };
+    if store.tokens[position].revoked_at.is_some() {
+        return Ok(None);
+    }
+    let now = now.unwrap_or_else(now_ms);
+    store.tokens[position].revoked_at = Some(now);
+    let existing_label = store.tokens[position].label.clone();
+    let created = create_local_client_token_record(
+        Some(label.unwrap_or(existing_label.as_str())),
+        Some(now),
+    );
+    store.tokens.push(created.record.clone());
+    write_store_to_disk(&store).await?;
+    Ok(Some(created))
+}
+
+/// `revokeLocalClientToken(id, now?)` — queued; false when missing/already
+/// revoked; else set `revokedAt`, write, true.
+pub async fn revoke_local_client_token(id: &str, now: Option<i64>) -> io::Result<bool> {
+    let _queue = WRITE_QUEUE.lock().await;
+    let mut store = load_local_client_token_store().await;
+    let Some(existing) = store.tokens.iter_mut().find(|record| record.id == id) else {
+        return Ok(false);
+    };
+    if existing.revoked_at.is_some() {
+        return Ok(false);
+    }
+    existing.revoked_at = Some(now.unwrap_or_else(now_ms));
+    write_store_to_disk(&store).await?;
+    Ok(true)
+}
+
+/// `/^Bearer\s+(.+)$/i` + trim, hand-rolled (same accept/reject set): the
+/// scheme is case-insensitive, at least one whitespace separator is required,
+/// and the remainder must be a non-empty single line.
+fn parse_bearer_token(authorization_header: &str) -> Option<String> {
+    let header = authorization_header;
+    if header.len() < 6 || !header.is_char_boundary(6) {
+        return None;
+    }
+    let (scheme, rest) = header.split_at(6);
+    if !scheme.eq_ignore_ascii_case("Bearer") {
+        return None;
+    }
+    let after_ws = rest.trim_start();
+    // `\s+` requires at least one whitespace char between scheme and token.
+    if after_ws.len() == rest.len() {
+        return None;
+    }
+    // JS `.` never matches line terminators, so any embedded newline fails
+    // the anchored match.
+    if after_ws.is_empty()
+        || after_ws.contains(['\n', '\r', '\u{2028}', '\u{2029}'])
+    {
+        return None;
+    }
+    let token = after_ws.trim();
+    if token.is_empty() {
+        return None;
+    }
+    Some(token.to_string())
+}
+
+/// `verifyLocalClientBearerToken(authorizationHeader, now?)` — queued lookup
+/// on hash AND `revokedAt === null`. Always advances `lastUsedAt` in-memory;
+/// flushes to disk only when never persisted or ≥ 60 s past the persisted
+/// value (hot-path debounce). Token match never depends on `lastUsedAt`.
+pub async fn verify_local_client_bearer_token(
+    authorization_header: Option<&str>,
+    now: Option<i64>,
+) -> io::Result<Option<LocalClientTokenRecord>> {
+    let Some(token) = authorization_header.and_then(parse_bearer_token) else {
+        return Ok(None);
+    };
+    let token_hash = hash_token(&token);
+    let now = now.unwrap_or_else(now_ms);
+
+    let _queue = WRITE_QUEUE.lock().await;
+    let mut store = load_local_client_token_store().await;
+    let Some(record) = store
+        .tokens
+        .iter_mut()
+        .find(|entry| entry.revoked_at.is_none() && entry.token_hash == token_hash)
+    else {
+        return Ok(None);
+    };
+    let persisted = record.last_used_at;
+    record.last_used_at = Some(now);
+    let fresh = record.clone();
+    let should_flush = match persisted {
+        None => true,
+        Some(persisted) => now - persisted >= LAST_USED_PERSIST_THRESHOLD_MS,
+    };
+    if should_flush {
+        write_store_to_disk(&store).await?;
+    }
+    Ok(Some(fresh))
+}
+
+/// `resetLocalClientTokenWriteQueueForTests()` — the TS seam reset a promise
+/// chain; the tokio mutex queue cannot be poisoned, so this is a no-op kept
+/// for API parity.
+pub fn reset_local_client_token_write_queue_for_tests() {}
+
+// ============================================================================
+// Tests (ported from test/local-client-tokens.test.ts + golden byte gate)
+//
+// All tests redirect CODEX_MULTI_AUTH_DIR through EnvSandbox ⇒ #[serial(env)].
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::goldens::{assert_golden_str, read_golden_string};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn stores_hashes_and_verifies_bearer_tokens_without_persisting_plaintext() {
+        let _sandbox = EnvSandbox::new();
+
+        let created = add_local_client_token(Some("OpenCode"), Some(100))
+            .await
+            .unwrap();
+        assert!(created.plain_token.starts_with("cma_local_"));
+        assert!(created.record.token_hash.starts_with("sha256:"));
+        assert_eq!(
+            created.record.prefix,
+            created.plain_token.chars().take(18).collect::<String>()
+        );
+
+        let raw = std::fs::read_to_string(get_local_client_token_path()).unwrap();
+        assert!(!raw.contains(&created.plain_token));
+        assert!(raw.contains(&created.record.prefix));
+
+        let verified = verify_local_client_bearer_token(
+            Some(&format!("Bearer {}", created.plain_token)),
+            Some(200),
+        )
+        .await
+        .unwrap();
+        assert_eq!(verified.as_ref().map(|record| record.id.as_str()), Some(created.record.id.as_str()));
+        let loaded = load_local_client_token_store().await;
+        assert_eq!(loaded.tokens[0].last_used_at, Some(200));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn rotates_and_revokes_tokens() {
+        let _sandbox = EnvSandbox::new();
+
+        let created = add_local_client_token(Some("client"), Some(100)).await.unwrap();
+        let rotated = rotate_local_client_token(&created.record.id, None, Some(200))
+            .await
+            .unwrap()
+            .expect("rotation succeeds");
+        assert!(rotated.plain_token.starts_with("cma_local_"));
+        assert_eq!(rotated.record.label, "client");
+
+        assert!(
+            verify_local_client_bearer_token(
+                Some(&format!("Bearer {}", created.plain_token)),
+                Some(300),
+            )
+            .await
+            .unwrap()
+            .is_none()
+        );
+        let verified_rotated = verify_local_client_bearer_token(
+            Some(&format!("Bearer {}", rotated.plain_token)),
+            Some(300),
+        )
+        .await
+        .unwrap();
+        assert_eq!(
+            verified_rotated.as_ref().map(|record| record.id.as_str()),
+            Some(rotated.record.id.as_str())
+        );
+
+        assert!(revoke_local_client_token(&rotated.record.id, Some(400)).await.unwrap());
+        assert!(
+            verify_local_client_bearer_token(
+                Some(&format!("Bearer {}", rotated.plain_token)),
+                Some(500),
+            )
+            .await
+            .unwrap()
+            .is_none()
+        );
+        let store = load_local_client_token_store().await;
+        assert_eq!(
+            store
+                .tokens
+                .iter()
+                .filter(|token| token.revoked_at.is_some())
+                .count(),
+            2
+        );
+        // Rotating or revoking an already-revoked token is refused.
+        assert!(
+            rotate_local_client_token(&rotated.record.id, None, Some(600))
+                .await
+                .unwrap()
+                .is_none()
+        );
+        assert!(!revoke_local_client_token(&rotated.record.id, Some(600)).await.unwrap());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn debounces_last_used_at_persistence_across_rapid_verifies() {
+        let _sandbox = EnvSandbox::new();
+
+        let created = add_local_client_token(Some("hot-path"), Some(100)).await.unwrap();
+        let bearer = format!("Bearer {}", created.plain_token);
+
+        // Seed a persisted lastUsedAt so subsequent rapid verifies fall inside
+        // the debounce window rather than the "never persisted" branch.
+        verify_local_client_bearer_token(Some(&bearer), Some(1_000))
+            .await
+            .unwrap();
+
+        // Every verify within the threshold stays in-memory: no write per
+        // request on the auth hot path. (The TS test spies on fs.rename; the
+        // observable here is the persisted value staying put.)
+        for i in 1..=5 {
+            let verified = verify_local_client_bearer_token(Some(&bearer), Some(1_000 + i))
+                .await
+                .unwrap()
+                .expect("verifies");
+            assert_eq!(verified.id, created.record.id);
+            assert_eq!(verified.last_used_at, Some(1_000 + i));
+        }
+
+        // On disk it is still the last persisted value (debounced).
+        let debounced = load_local_client_token_store().await;
+        assert_eq!(debounced.tokens[0].last_used_at, Some(1_000));
+
+        // Once past the threshold, the next verify flushes to disk.
+        let flushed = verify_local_client_bearer_token(Some(&bearer), Some(1_000 + 60_000))
+            .await
+            .unwrap()
+            .expect("verifies");
+        assert_eq!(flushed.last_used_at, Some(1_000 + 60_000));
+
+        let persisted = load_local_client_token_store().await;
+        assert_eq!(persisted.tokens[0].last_used_at, Some(1_000 + 60_000));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn does_not_lose_mutations_when_revoke_and_add_run_concurrently() {
+        let _sandbox = EnvSandbox::new();
+
+        // Before the read-modify-write was serialized through the write
+        // queue, add and revoke each loaded the same base store and the later
+        // write clobbered the earlier one (lost update).
+        let seeded = add_local_client_token(Some("seed"), Some(100)).await.unwrap();
+
+        let (added, revoked) = tokio::join!(
+            add_local_client_token(Some("added-concurrently"), Some(200)),
+            revoke_local_client_token(&seeded.record.id, Some(300)),
+        );
+        added.unwrap();
+        assert!(revoked.unwrap());
+
+        let store = load_local_client_token_store().await;
+        assert_eq!(store.tokens.len(), 2);
+        let seed_record = store
+            .tokens
+            .iter()
+            .find(|token| token.id == seeded.record.id)
+            .expect("seed present");
+        assert_eq!(seed_record.revoked_at, Some(300));
+        let added_record = store
+            .tokens
+            .iter()
+            .find(|token| token.label == "added-concurrently")
+            .expect("concurrent add present");
+        assert_eq!(added_record.revoked_at, None);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn load_fails_open_to_an_empty_store_on_corrupt_json() {
+        let sandbox = EnvSandbox::new();
+        let dir = sandbox.codex_multi_auth_dir();
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(dir.join(TOKEN_FILE_NAME), "{ not json").unwrap();
+
+        let store = load_local_client_token_store().await;
+        assert_eq!(store, empty_store());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn normalize_drops_invalid_records_and_rejects_wrong_versions() {
+        let _sandbox = EnvSandbox::new();
+        // Wrong version ⇒ empty store.
+        assert_eq!(
+            normalize_store(&serde_json::json!({ "version": 2, "tokens": [] })),
+            empty_store()
+        );
+        // Array root ⇒ empty store (isRecord contract).
+        assert_eq!(normalize_store(&serde_json::json!([])), empty_store());
+        // Records without id / with un-prefixed hashes are dropped; label,
+        // prefix, and timestamps are normalized.
+        let store = normalize_store(&serde_json::json!({
+            "version": 1,
+            "tokens": [
+                { "id": "  keeper  ", "label": "  ", "prefix": 7, "tokenHash": "sha256:abc",
+                  "createdAt": "soon", "lastUsedAt": 5, "revokedAt": null },
+                { "id": "", "tokenHash": "sha256:abc" },
+                { "id": "x", "tokenHash": "md5:nope" },
+                "not-a-record"
+            ]
+        }));
+        assert_eq!(store.tokens.len(), 1);
+        let record = &store.tokens[0];
+        assert_eq!(record.id, "keeper");
+        assert_eq!(record.label, "local-client");
+        assert_eq!(record.prefix, "");
+        assert_eq!(record.created_at, 0);
+        assert_eq!(record.last_used_at, Some(5));
+        assert_eq!(record.revoked_at, None);
+    }
+
+    #[test]
+    fn bearer_parsing_is_case_insensitive_and_trims() {
+        assert_eq!(parse_bearer_token("Bearer abc").as_deref(), Some("abc"));
+        assert_eq!(parse_bearer_token("bearer abc").as_deref(), Some("abc"));
+        assert_eq!(parse_bearer_token("BEARER   abc  ").as_deref(), Some("abc"));
+        assert_eq!(parse_bearer_token("Bearer\tabc").as_deref(), Some("abc"));
+        assert_eq!(parse_bearer_token("Bearer"), None);
+        assert_eq!(parse_bearer_token("Bearer "), None);
+        assert_eq!(parse_bearer_token("Bearerabc"), None);
+        assert_eq!(parse_bearer_token("Basic abc"), None);
+        assert_eq!(parse_bearer_token("Bearer a\nb"), None);
+        assert_eq!(parse_bearer_token(""), None);
+    }
+
+    #[test]
+    fn plain_tokens_have_the_documented_shape() {
+        let created = create_local_client_token_record(None, Some(0));
+        // `cma_local_` + 43 chars of base64url(32 bytes) = 53 chars.
+        assert_eq!(created.plain_token.len(), 53);
+        assert!(created.plain_token.starts_with("cma_local_"));
+        assert_eq!(created.record.prefix.len(), 18);
+        assert_eq!(created.record.label, "local-client");
+        assert_eq!(created.record.token_hash.len(), 7 + 64);
+        assert_eq!(created.record.created_at, 0);
+        assert_eq!(created.record.last_used_at, None);
+        assert_eq!(created.record.revoked_at, None);
+    }
+
+    // ---- golden byte-compat gate ----
+
+    #[test]
+    fn golden_store_reserializes_byte_identically() {
+        let raw = read_golden_string("local-client-tokens.json");
+        let value: Value = serde_json::from_str(&raw).unwrap();
+        let store = normalize_store(&value);
+        assert_golden_str(
+            "local-client-tokens.json",
+            &format!("{}\n", stringify_pretty2(&store)),
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn save_writes_the_golden_bytes_to_disk() {
+        let _sandbox = EnvSandbox::new();
+        let store = LocalClientTokenStore {
+            version: 1,
+            tokens: vec![LocalClientTokenRecord {
+                id: "00000000-0000-4000-8000-000000000001".to_string(),
+                label: "workstation".to_string(),
+                prefix: "cma_local_AAECAwQF".to_string(),
+                token_hash:
+                    "sha256:7de937f6bef93e60a3f6fa9074d756f2b62a7c0b9c5621cef751b47fdf84480f"
+                        .to_string(),
+                created_at: 1_750_000_000_000,
+                last_used_at: None,
+                revoked_at: None,
+            }],
+        };
+        save_local_client_token_store(&store).await.unwrap();
+        let written = std::fs::read_to_string(get_local_client_token_path()).unwrap();
+        assert_golden_str("local-client-tokens.json", &written);
+    }
+}
diff --git a/crates/auth/src/oauth.rs b/crates/auth/src/oauth.rs
new file mode 100644
index 000000000..9b7db10d0
--- /dev/null
+++ b/crates/auth/src/oauth.rs
@@ -0,0 +1,1415 @@
+//! Port of `lib/auth/auth.ts` — OAuth core: constants, PKCE flow builder,
+//! code→token exchange, refresh, log redaction (spec 07 §1).
+//!
+//! - `CLIENT_ID` / `REDIRECT_URI` (port 1455) are provider-registered and
+//!   IMMOVABLE (spec 07 gotcha 8).
+//! - PKCE S256 is self-implemented (sha2 + base64 URL_SAFE_NO_PAD) — no
+//!   external OAuth dependency (spec 07 gotcha 23).
+//! - The authorization-code exchange REQUIRES a `refresh_token` in the
+//!   response; refresh keeps the input token when the response omits one
+//!   (spec 07 gotcha 3).
+//! - Never log token material: bodies pass through
+//!   [`sanitize_oauth_response_body_for_log`], URLs through
+//!   [`redact_oauth_url_for_log`], schema-failure logs carry only shape
+//!   metadata (spec 07 gotcha 5).
+
+use std::sync::LazyLock;
+
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use rand::RngCore;
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+
+use cma_core::logger::log_error;
+use cma_core::schemas::parse::safe_parse_oauth_token_response;
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult, TokenSuccess};
+use cma_core::types::{AuthorizationFlow, PKCEPair, ParsedAuthInput};
+use cma_core::utils::now_ms;
+
+// Re-exports (ARCHITECTURE §4 note 2: `decodeJWT`/token-utils live in core;
+// `cma-auth` re-exports them so auth-cluster callers keep the TS import shape).
+pub use cma_core::jwt::{decode_jwt, decode_jwt_value};
+pub use cma_core::token_utils;
+
+// ---------------------------------------------------------------------------
+// OAuth constants (from openai/codex) — exact values, spec 07 §1.
+// ---------------------------------------------------------------------------
+
+pub const CLIENT_ID: &str = "app_EMoamEEZ73f0CkXaXp7hrann";
+pub const AUTHORIZE_URL: &str = "https://auth.openai.com/oauth/authorize";
+pub const TOKEN_URL: &str = "https://auth.openai.com/oauth/token";
+pub const REDIRECT_URI: &str = "http://localhost:1455/auth/callback";
+pub const SCOPE: &str = "openid profile email offline_access";
+
+/// Parsed representation of [`REDIRECT_URI`]. Single source of truth for the
+/// OAuth callback origin so the local server bind, user-facing copy, and the
+/// success page never drift from each other (TS `AUTH_REDIRECT`, frozen).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AuthRedirect {
+    pub host: &'static str,
+    pub port: u16,
+    pub path: &'static str,
+    pub origin: &'static str,
+    pub url: &'static str,
+}
+
+/// The provider registers the exact string in [`REDIRECT_URI`]; these fields
+/// are derived from it (a unit test asserts they cannot drift).
+pub const AUTH_REDIRECT: AuthRedirect = AuthRedirect {
+    host: "localhost",
+    port: 1455,
+    path: "/auth/callback",
+    origin: "http://localhost:1455",
+    url: REDIRECT_URI,
+};
+
+const OAUTH_SENSITIVE_QUERY_PARAMS: [&str; 4] = ["state", "code", "code_challenge", "code_verifier"];
+
+const OAUTH_SENSITIVE_BODY_KEYS: [&str; 10] = [
+    "refresh_token",
+    "refreshToken",
+    "access_token",
+    "accessToken",
+    "id_token",
+    "idToken",
+    "codeVerifier",
+    "token",
+    "code",
+    "code_verifier",
+];
+
+const REDACTED: &str = "***REDACTED***";
+
+// ---------------------------------------------------------------------------
+// Log scrubbing (hand-rolled ports of the TS regexes — the `regex` crate is
+// not a dependency of this crate; the matchers below reproduce the exact
+// pattern semantics, including JS `\b` = [A-Za-z0-9_] word boundaries).
+// ---------------------------------------------------------------------------
+
+fn is_word_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || c == '_'
+}
+
+fn match_literal_ci(chars: &[char], start: usize, literal: &str) -> Option<usize> {
+    let mut j = start;
+    for lc in literal.chars() {
+        let c = *chars.get(j)?;
+        if c.to_ascii_lowercase() != lc {
+            return None;
+        }
+        j += 1;
+    }
+    Some(j)
+}
+
+/// `(\b(?:refresh|access|id)[_-]?token\s*[:=]\s*)([^\s,;"'}]{8,})` (flags gi):
+/// returns `(prefix_end, value_end)` when the pattern matches at `start`.
+fn match_token_assignment(chars: &[char], start: usize) -> Option<(usize, usize)> {
+    if start > 0 && is_word_char(chars[start - 1]) {
+        return None; // no word boundary before the keyword
+    }
+    // (?:refresh|access|id) — alternatives in order, case-insensitive.
+    let mut j = ["refresh", "access", "id"]
+        .iter()
+        .find_map(|kw| match_literal_ci(chars, start, kw))?;
+    // [_-]?
+    if matches!(chars.get(j), Some('_') | Some('-')) {
+        j += 1;
+    }
+    // token
+    j = match_literal_ci(chars, j, "token")?;
+    // \s*
+    while chars.get(j).is_some_and(|c| c.is_whitespace()) {
+        j += 1;
+    }
+    // [:=]
+    if !matches!(chars.get(j), Some(':') | Some('=')) {
+        return None;
+    }
+    j += 1;
+    // \s*
+    while chars.get(j).is_some_and(|c| c.is_whitespace()) {
+        j += 1;
+    }
+    let prefix_end = j;
+    // [^\s,;"'}]{8,}
+    let mut k = j;
+    while chars
+        .get(k)
+        .is_some_and(|c| !c.is_whitespace() && !matches!(c, ',' | ';' | '"' | '\'' | '}'))
+    {
+        k += 1;
+    }
+    if k - prefix_end >= 8 {
+        Some((prefix_end, k))
+    } else {
+        None
+    }
+}
+
+/// `\b(?:RT|AT)_ch_[A-Za-z0-9_-]{20,}\b` (flag g, case-sensitive): returns
+/// the end index of the match when it matches at `start`.
+fn match_opaque_token(chars: &[char], start: usize) -> Option<usize> {
+    if start > 0 && is_word_char(chars[start - 1]) {
+        return None;
+    }
+    let lead: String = chars.get(start..start + 6)?.iter().collect();
+    if lead != "RT_ch_" && lead != "AT_ch_" {
+        return None;
+    }
+    let run_start = start + 6;
+    let mut k = run_start;
+    while chars
+        .get(k)
+        .is_some_and(|c| c.is_ascii_alphanumeric() || *c == '_' || *c == '-')
+    {
+        k += 1;
+    }
+    // Trailing `\b`: the char after the maximal run is never a word char, so
+    // the last matched char must BE one — backtrack over trailing hyphens.
+    let mut end = k;
+    while end > run_start && chars[end - 1] == '-' {
+        end -= 1;
+    }
+    if end - run_start >= 20 { Some(end) } else { None }
+}
+
+fn scrub_token_like_substrings(value: &str) -> String {
+    // Pass 1: keyed assignments (refresh_token: xxx / access-token=xxx …).
+    let chars: Vec<char> = value.chars().collect();
+    let mut out = String::with_capacity(value.len());
+    let mut i = 0usize;
+    while i < chars.len() {
+        if let Some((prefix_end, value_end)) = match_token_assignment(&chars, i) {
+            out.extend(&chars[i..prefix_end]);
+            out.push_str(REDACTED);
+            i = value_end;
+        } else {
+            out.push(chars[i]);
+            i += 1;
+        }
+    }
+    // Pass 2: bare opaque ChatGPT tokens (RT_ch_… / AT_ch_…).
+    let chars: Vec<char> = out.chars().collect();
+    let mut scrubbed = String::with_capacity(out.len());
+    let mut i = 0usize;
+    while i < chars.len() {
+        if let Some(end) = match_opaque_token(&chars, i) {
+            scrubbed.push_str(REDACTED);
+            i = end;
+        } else {
+            scrubbed.push(chars[i]);
+            i += 1;
+        }
+    }
+    scrubbed
+}
+
+fn redact_sensitive_fields(value: &Value) -> Value {
+    match value {
+        Value::Array(items) => Value::Array(items.iter().map(redact_sensitive_fields).collect()),
+        Value::Object(map) => {
+            let mut out = serde_json::Map::new();
+            for (k, v) in map {
+                if OAUTH_SENSITIVE_BODY_KEYS.contains(&k.as_str()) {
+                    out.insert(k.clone(), Value::String(REDACTED.to_string()));
+                } else {
+                    out.insert(k.clone(), redact_sensitive_fields(v));
+                }
+            }
+            Value::Object(out)
+        }
+        Value::String(s) => Value::String(scrub_token_like_substrings(s)),
+        other => other.clone(),
+    }
+}
+
+fn matches_at(chars: &[char], start: usize, needle: &[char]) -> bool {
+    chars
+        .get(start..start + needle.len())
+        .is_some_and(|window| window == needle)
+}
+
+/// `("key"\s*:\s*)"[^"]*"` (flag g) → `$1"***REDACTED***"`.
+fn scrub_json_style(input: &str, key: &str) -> String {
+    let chars: Vec<char> = input.chars().collect();
+    let needle: Vec<char> = format!("\"{key}\"").chars().collect();
+    let mut out = String::with_capacity(input.len());
+    let mut i = 0usize;
+    while i < chars.len() {
+        if chars[i] == '"' && matches_at(&chars, i, &needle) {
+            let mut k = i + needle.len();
+            while chars.get(k).is_some_and(|c| c.is_whitespace()) {
+                k += 1;
+            }
+            if matches!(chars.get(k), Some(':')) {
+                k += 1;
+                while chars.get(k).is_some_and(|c| c.is_whitespace()) {
+                    k += 1;
+                }
+                if matches!(chars.get(k), Some('"')) {
+                    // consume [^"]* then the closing quote
+                    let mut v = k + 1;
+                    while chars.get(v).is_some_and(|c| *c != '"') {
+                        v += 1;
+                    }
+                    if v < chars.len() {
+                        out.extend(&chars[i..k]); // `$1` = "key"\s*:\s*
+                        out.push('"');
+                        out.push_str(REDACTED);
+                        out.push('"');
+                        i = v + 1;
+                        continue;
+                    }
+                }
+            }
+        }
+        out.push(chars[i]);
+        i += 1;
+    }
+    out
+}
+
+/// `(^|[?&\s])(key=)[^&\s]+` (flag g) → `$1$2***REDACTED***`.
+fn scrub_url_style(input: &str, key: &str) -> String {
+    let chars: Vec<char> = input.chars().collect();
+    let needle: Vec<char> = format!("{key}=").chars().collect();
+    let mut out = String::with_capacity(input.len());
+    let mut i = 0usize;
+    while i < chars.len() {
+        let boundary_ok =
+            i == 0 || matches!(chars[i - 1], '?' | '&') || chars[i - 1].is_whitespace();
+        if boundary_ok && matches_at(&chars, i, &needle) {
+            let value_start = i + needle.len();
+            let mut k = value_start;
+            while chars
+                .get(k)
+                .is_some_and(|c| *c != '&' && !c.is_whitespace())
+            {
+                k += 1;
+            }
+            if k > value_start {
+                out.extend(&chars[i..value_start]);
+                out.push_str(REDACTED);
+                i = k;
+                continue;
+            }
+        }
+        out.push(chars[i]);
+        i += 1;
+    }
+    out
+}
+
+/// Scrub opaque tokens from a raw OAuth token-endpoint response body before
+/// interpolating it into a log message (TS `sanitizeOAuthResponseBodyForLog`).
+///
+/// ChatGPT refresh tokens are opaque high-entropy strings that do NOT match
+/// the logger's generic TOKEN_PATTERNS, so without this they would be written
+/// verbatim to disk log files (LIB-HIGH-001).
+pub fn sanitize_oauth_response_body_for_log(raw_body: &str) -> String {
+    if raw_body.is_empty() {
+        return raw_body.to_string();
+    }
+    let trimmed = raw_body.trim();
+    if trimmed.is_empty() {
+        return raw_body.to_string();
+    }
+
+    // Malformed JSON falls through to the regex scrub below.
+    if (trimmed.starts_with('{') || trimmed.starts_with('['))
+        && let Ok(parsed) = serde_json::from_str::<Value>(trimmed)
+    {
+        let redacted = redact_sensitive_fields(&parsed);
+        // Compact JSON.stringify of the redacted structure.
+        return serde_json::to_string(&redacted).unwrap_or_else(|_| raw_body.to_string());
+    }
+
+    let mut scrubbed = raw_body.to_string();
+    for key in OAUTH_SENSITIVE_BODY_KEYS {
+        scrubbed = scrub_json_style(&scrubbed, key);
+        scrubbed = scrub_url_style(&scrubbed, key);
+    }
+    scrubbed
+}
+
+/// Redacts sensitive OAuth query parameters (`state`, `code`,
+/// `code_challenge`, `code_verifier`) for safe logging. Returns the original
+/// string when parsing fails (TS `redactOAuthUrlForLog`).
+pub fn redact_oauth_url_for_log(raw_url: &str) -> String {
+    let Ok(mut parsed) = url::Url::parse(raw_url) else {
+        return raw_url.to_string();
+    };
+    let pairs: Vec<(String, String)> = parsed
+        .query_pairs()
+        .map(|(k, v)| (k.into_owned(), v.into_owned()))
+        .collect();
+    let any_sensitive = pairs
+        .iter()
+        .any(|(k, _)| OAUTH_SENSITIVE_QUERY_PARAMS.contains(&k.as_str()));
+    if !any_sensitive {
+        // No mutation → the query is serialized untouched (URLSearchParams
+        // only re-serializes once `set` is called — same here).
+        return parsed.to_string();
+    }
+    // `searchParams.set` semantics: first occurrence replaced in place, later
+    // duplicates of the same key removed; full query re-serialized.
+    let mut replaced: Vec<String> = Vec::new();
+    let mut rebuilt: Vec<(String, String)> = Vec::new();
+    for (k, v) in pairs {
+        if OAUTH_SENSITIVE_QUERY_PARAMS.contains(&k.as_str()) {
+            if replaced.contains(&k) {
+                continue;
+            }
+            replaced.push(k.clone());
+            rebuilt.push((k, "<redacted>".to_string()));
+        } else {
+            rebuilt.push((k, v));
+        }
+    }
+    parsed.query_pairs_mut().clear().extend_pairs(rebuilt);
+    parsed.to_string()
+}
+
+// ---------------------------------------------------------------------------
+// State / PKCE / input parsing
+// ---------------------------------------------------------------------------
+
+/// Generate a random state value for the OAuth flow: 16 CSPRNG bytes as 32
+/// lowercase hex chars (TS `createState`).
+pub fn create_state() -> String {
+    let mut bytes = [0u8; 16];
+    rand::rng().fill_bytes(&mut bytes);
+    let mut out = String::with_capacity(32);
+    for b in bytes {
+        out.push_str(&format!("{b:02x}"));
+    }
+    out
+}
+
+/// Generate a PKCE S256 pair: verifier = base64url(32 CSPRNG bytes) (43
+/// chars, RFC 7636), challenge = base64url(SHA-256(verifier)).
+pub fn generate_pkce() -> PKCEPair {
+    let mut bytes = [0u8; 32];
+    rand::rng().fill_bytes(&mut bytes);
+    let verifier = URL_SAFE_NO_PAD.encode(bytes);
+    let challenge = URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes()));
+    PKCEPair {
+        challenge,
+        verifier,
+    }
+}
+
+/// Parse authorization code and state from user input: a full URL, a
+/// `code#state` pair, a query string, or a raw code (TS
+/// `parseAuthorizationInput`).
+pub fn parse_authorization_input(input: &str) -> ParsedAuthInput {
+    let value = input.trim();
+    if value.is_empty() {
+        return ParsedAuthInput::default();
+    }
+
+    if let Ok(parsed) = url::Url::parse(value) {
+        let mut code = parsed
+            .query_pairs()
+            .find(|(k, _)| k == "code")
+            .map(|(_, v)| v.into_owned());
+        let mut state = parsed
+            .query_pairs()
+            .find(|(k, _)| k == "state")
+            .map(|(_, v)| v.into_owned());
+
+        // Fallback: check the fragment if not found in searchParams
+        // (`#code=…` format).
+        if let Some(hash) = parsed.fragment()
+            && !hash.is_empty()
+            && (code.is_none() || state.is_none())
+        {
+            let hash_pairs: Vec<(String, String)> = url::form_urlencoded::parse(hash.as_bytes())
+                .map(|(k, v)| (k.into_owned(), v.into_owned()))
+                .collect();
+            if code.is_none() {
+                code = hash_pairs
+                    .iter()
+                    .find(|(k, _)| k == "code")
+                    .map(|(_, v)| v.clone());
+            }
+            if state.is_none() {
+                state = hash_pairs
+                    .iter()
+                    .find(|(k, _)| k == "state")
+                    .map(|(_, v)| v.clone());
+            }
+        }
+
+        if code.is_some() || state.is_some() {
+            return ParsedAuthInput { code, state };
+        }
+        // Invalid/hollow URL — fall through to the other parsing methods.
+    }
+
+    if value.contains('#') {
+        // TS `value.split("#", 2)` — first two segments.
+        let mut parts = value.splitn(3, '#');
+        let code = parts.next().unwrap_or_default().to_string();
+        let state = parts.next().unwrap_or_default().to_string();
+        return ParsedAuthInput {
+            code: Some(code),
+            state: Some(state),
+        };
+    }
+    if value.contains("code=") {
+        let pairs: Vec<(String, String)> = url::form_urlencoded::parse(value.as_bytes())
+            .map(|(k, v)| (k.into_owned(), v.into_owned()))
+            .collect();
+        return ParsedAuthInput {
+            code: pairs
+                .iter()
+                .find(|(k, _)| k == "code")
+                .map(|(_, v)| v.clone()),
+            state: pairs
+                .iter()
+                .find(|(k, _)| k == "state")
+                .map(|(_, v)| v.clone()),
+        };
+    }
+    ParsedAuthInput {
+        code: Some(value.to_string()),
+        state: None,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Token endpoint calls
+// ---------------------------------------------------------------------------
+
+static HTTP_CLIENT: LazyLock<reqwest::Client> = LazyLock::new(reqwest::Client::new);
+
+fn failed(
+    reason: TokenFailureReason,
+    status_code: Option<i64>,
+    message: Option<String>,
+) -> TokenResult {
+    TokenResult::Failed(TokenFailure {
+        reason: Some(reason),
+        status_code,
+        message,
+    })
+}
+
+/// Shape-only log metadata for schema failures — key/item counts, never keys
+/// or values (TS `getOAuthResponseLogMetadata`).
+fn oauth_response_log_metadata(raw: &Value) -> Value {
+    match raw {
+        Value::Array(items) => json!({ "responseType": "array", "itemCount": items.len() }),
+        Value::Object(map) => json!({ "responseType": "object", "keyCount": map.len() }),
+        // JS `typeof null === "object"`.
+        Value::Null => json!({ "responseType": "object" }),
+        Value::Bool(_) => json!({ "responseType": "boolean" }),
+        Value::Number(_) => json!({ "responseType": "number" }),
+        Value::String(_) => json!({ "responseType": "string" }),
+    }
+}
+
+/// Exchange an authorization code for tokens against the production
+/// [`TOKEN_URL`]. `redirect_uri` defaults to [`REDIRECT_URI`] when `None`.
+pub async fn exchange_authorization_code(
+    code: &str,
+    verifier: &str,
+    redirect_uri: Option<&str>,
+) -> TokenResult {
+    exchange_authorization_code_at(TOKEN_URL, code, verifier, redirect_uri).await
+}
+
+/// [`exchange_authorization_code`] against an explicit token endpoint (test
+/// seam — the TS tests stub global `fetch`; Rust points at a mock server).
+pub async fn exchange_authorization_code_at(
+    token_url: &str,
+    code: &str,
+    verifier: &str,
+    redirect_uri: Option<&str>,
+) -> TokenResult {
+    let redirect_uri = redirect_uri.unwrap_or(REDIRECT_URI);
+    let form: [(&str, &str); 5] = [
+        ("grant_type", "authorization_code"),
+        ("client_id", CLIENT_ID),
+        ("code", code),
+        ("code_verifier", verifier),
+        ("redirect_uri", redirect_uri),
+    ];
+    let response = match HTTP_CLIENT.post(token_url).form(&form).send().await {
+        Ok(response) => response,
+        // TS lets transport errors throw out of exchangeAuthorizationCode;
+        // the Rust port folds them into a network_error failure so
+        // `runDeviceAuthFlow`-style callers stay total.
+        Err(error) => {
+            return failed(
+                TokenFailureReason::NetworkError,
+                None,
+                Some(error.to_string()),
+            );
+        }
+    };
+    let status = response.status().as_u16();
+    if !(200..300).contains(&status) {
+        let text = response.text().await.unwrap_or_default();
+        let safe_text = sanitize_oauth_response_body_for_log(&text);
+        log_error(&format!("code->token failed: {status} {safe_text}"), None);
+        let message = if safe_text.is_empty() {
+            None
+        } else {
+            Some(safe_text)
+        };
+        return failed(TokenFailureReason::HttpError, Some(status as i64), message);
+    }
+    let raw_json: Value = match response.json().await {
+        Ok(value) => value,
+        Err(error) => {
+            return failed(
+                TokenFailureReason::NetworkError,
+                None,
+                Some(error.to_string()),
+            );
+        }
+    };
+    let Some(json) = safe_parse_oauth_token_response(&raw_json) else {
+        log_error(
+            "token response validation failed",
+            Some(&oauth_response_log_metadata(&raw_json)),
+        );
+        return failed(
+            TokenFailureReason::InvalidResponse,
+            None,
+            Some("Response failed schema validation".to_string()),
+        );
+    };
+    let refresh_token = json.refresh_token.as_deref().unwrap_or("").trim();
+    if refresh_token.is_empty() {
+        log_error(
+            "token response missing refresh token",
+            Some(&oauth_response_log_metadata(&raw_json)),
+        );
+        return failed(
+            TokenFailureReason::InvalidResponse,
+            None,
+            Some("Missing refresh token in authorization code exchange response".to_string()),
+        );
+    }
+    TokenResult::Success(TokenSuccess {
+        access: json.access_token,
+        refresh: refresh_token.to_string(),
+        expires: now_ms() + json.expires_in * 1000,
+        id_token: json.id_token,
+        multi_account: Some(true),
+    })
+}
+
+/// Refresh an access token against the production [`TOKEN_URL`].
+///
+/// Refresh-token ROTATION: the next refresh token is the response value when
+/// present, else the input token; both trimmed; empty → `missing_refresh`.
+pub async fn refresh_access_token(refresh_token: &str) -> TokenResult {
+    refresh_access_token_at(TOKEN_URL, refresh_token).await
+}
+
+/// [`refresh_access_token`] against an explicit token endpoint (test seam).
+pub async fn refresh_access_token_at(token_url: &str, refresh_token: &str) -> TokenResult {
+    let form: [(&str, &str); 3] = [
+        ("grant_type", "refresh_token"),
+        ("refresh_token", refresh_token),
+        ("client_id", CLIENT_ID),
+    ];
+    let response = match HTTP_CLIENT.post(token_url).form(&form).send().await {
+        Ok(response) => response,
+        Err(error) => {
+            // TS catch branch: abort → reason "unknown" without logging;
+            // other errors → logged network_error. Rust has no AbortSignal
+            // on this path, so every transport failure is a network_error.
+            log_error(
+                "Token refresh error",
+                Some(&json!({ "message": error.to_string() })),
+            );
+            return failed(
+                TokenFailureReason::NetworkError,
+                None,
+                Some(error.to_string()),
+            );
+        }
+    };
+    let status = response.status().as_u16();
+    if !(200..300).contains(&status) {
+        let text = response.text().await.unwrap_or_default();
+        let safe_text = sanitize_oauth_response_body_for_log(&text);
+        log_error(&format!("Token refresh failed: {status} {safe_text}"), None);
+        let message = if safe_text.is_empty() {
+            None
+        } else {
+            Some(safe_text)
+        };
+        return failed(TokenFailureReason::HttpError, Some(status as i64), message);
+    }
+    let raw_json: Value = match response.json().await {
+        Ok(value) => value,
+        Err(error) => {
+            log_error(
+                "Token refresh error",
+                Some(&json!({ "message": error.to_string() })),
+            );
+            return failed(
+                TokenFailureReason::NetworkError,
+                None,
+                Some(error.to_string()),
+            );
+        }
+    };
+    let Some(json) = safe_parse_oauth_token_response(&raw_json) else {
+        log_error(
+            "Token refresh response validation failed",
+            Some(&oauth_response_log_metadata(&raw_json)),
+        );
+        return failed(
+            TokenFailureReason::InvalidResponse,
+            None,
+            Some("Response failed schema validation".to_string()),
+        );
+    };
+    // Refresh-token rotation: response value wins, else the input token.
+    let next_refresh_raw = json.refresh_token.as_deref().unwrap_or(refresh_token);
+    let next_refresh = next_refresh_raw.trim();
+    if next_refresh.is_empty() {
+        log_error("Token refresh missing refresh token", None);
+        return failed(
+            TokenFailureReason::MissingRefresh,
+            None,
+            Some("No refresh token in response or input".to_string()),
+        );
+    }
+    TokenResult::Success(TokenSuccess {
+        access: json.access_token,
+        refresh: next_refresh.to_string(),
+        expires: now_ms() + json.expires_in * 1000,
+        id_token: json.id_token,
+        multi_account: Some(true),
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Authorization flow builder
+// ---------------------------------------------------------------------------
+
+/// Options for [`create_authorization_flow`] (TS `AuthorizationFlowOptions`).
+#[derive(Debug, Clone, Copy, Default)]
+pub struct AuthorizationFlowOptions {
+    /// Force a fresh login screen instead of using a cached browser session.
+    /// Use when adding multiple accounts to ensure different credentials.
+    pub force_new_login: bool,
+}
+
+/// Create the OAuth authorization flow: PKCE pair, state, and the authorize
+/// URL with the exact parameter set/order of the TS implementation
+/// (including `id_token_add_organizations` / `codex_cli_simplified_flow` /
+/// `originator=codex_cli_rs`, and `prompt=login` only when forcing a new
+/// login — spec 07 gotcha 23).
+pub fn create_authorization_flow(options: AuthorizationFlowOptions) -> AuthorizationFlow {
+    let pkce = generate_pkce();
+    let state = create_state();
+
+    let mut url = url::Url::parse(AUTHORIZE_URL).expect("AUTHORIZE_URL is a valid URL");
+    {
+        let mut qp = url.query_pairs_mut();
+        qp.append_pair("response_type", "code");
+        qp.append_pair("client_id", CLIENT_ID);
+        qp.append_pair("redirect_uri", REDIRECT_URI);
+        qp.append_pair("scope", SCOPE);
+        qp.append_pair("code_challenge", &pkce.challenge);
+        qp.append_pair("code_challenge_method", "S256");
+        qp.append_pair("state", &state);
+        qp.append_pair("id_token_add_organizations", "true");
+        qp.append_pair("codex_cli_simplified_flow", "true");
+        qp.append_pair("originator", "codex_cli_rs");
+        // Force a fresh login screen when adding multiple accounts. This
+        // helps prevent the browser from auto-using an existing session.
+        if options.force_new_login {
+            qp.append_pair("prompt", "login");
+        }
+    }
+
+    AuthorizationFlow {
+        pkce,
+        state,
+        url: url.to_string(),
+    }
+}
+
+// ===========================================================================
+// Tests (ported from test/auth.test.ts)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    const OPAQUE_REFRESH: &str = "RT_ch_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOP0123456789";
+    const OPAQUE_ACCESS: &str = "AT_ch_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz";
+
+    fn is_lower_hex_32(s: &str) -> bool {
+        s.len() == 32 && s.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
+    }
+
+    // ----- createState -----------------------------------------------------
+
+    #[test]
+    fn create_state_generates_32_char_hex() {
+        let state = create_state();
+        assert!(is_lower_hex_32(&state), "state {state:?} should be 32 hex chars");
+    }
+
+    #[test]
+    fn create_state_generates_unique_states() {
+        assert_ne!(create_state(), create_state());
+    }
+
+    // ----- parseAuthorizationInput -----------------------------------------
+
+    fn parsed(code: Option<&str>, state: Option<&str>) -> ParsedAuthInput {
+        ParsedAuthInput {
+            code: code.map(String::from),
+            state: state.map(String::from),
+        }
+    }
+
+    #[test]
+    fn parses_full_oauth_callback_url() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback?code=abc123&state=xyz789"),
+            parsed(Some("abc123"), Some("xyz789"))
+        );
+    }
+
+    #[test]
+    fn parses_localhost_callback_url() {
+        assert_eq!(
+            parse_authorization_input("http://localhost:1455/auth/callback?code=abc123&state=xyz789"),
+            parsed(Some("abc123"), Some("xyz789"))
+        );
+    }
+
+    #[test]
+    fn parses_code_hash_state_format() {
+        assert_eq!(
+            parse_authorization_input("abc123#xyz789"),
+            parsed(Some("abc123"), Some("xyz789"))
+        );
+    }
+
+    #[test]
+    fn parses_query_string_format() {
+        assert_eq!(
+            parse_authorization_input("code=abc123&state=xyz789"),
+            parsed(Some("abc123"), Some("xyz789"))
+        );
+    }
+
+    #[test]
+    fn parses_query_string_with_code_only() {
+        assert_eq!(
+            parse_authorization_input("code=abc123"),
+            parsed(Some("abc123"), None)
+        );
+    }
+
+    #[test]
+    fn parses_url_with_fragment_parameters() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback#code=abc123&state=xyz789"),
+            parsed(Some("abc123"), Some("xyz789"))
+        );
+    }
+
+    #[test]
+    fn prefers_query_params_over_hash_params() {
+        assert_eq!(
+            parse_authorization_input(
+                "http://127.0.0.1:1455/auth/callback?code=querycode&state=querystate#code=hashcode&state=hashstate"
+            ),
+            parsed(Some("querycode"), Some("querystate"))
+        );
+    }
+
+    #[test]
+    fn falls_back_to_hash_for_missing_state_in_query() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback?code=querycode#state=hashstate"),
+            parsed(Some("querycode"), Some("hashstate"))
+        );
+    }
+
+    #[test]
+    fn falls_back_to_hash_for_missing_code_in_query() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback?state=querystate#code=hashcode"),
+            parsed(Some("hashcode"), Some("querystate"))
+        );
+    }
+
+    #[test]
+    fn handles_url_with_hash_code_only() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback#code=abc123"),
+            parsed(Some("abc123"), None)
+        );
+    }
+
+    #[test]
+    fn returns_state_only_when_only_state_in_hash() {
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback#state=hashstate"),
+            parsed(None, Some("hashstate"))
+        );
+    }
+
+    #[test]
+    fn parses_code_only() {
+        assert_eq!(parse_authorization_input("abc123"), parsed(Some("abc123"), None));
+    }
+
+    #[test]
+    fn returns_empty_for_empty_input() {
+        assert_eq!(parse_authorization_input(""), ParsedAuthInput::default());
+    }
+
+    #[test]
+    fn handles_whitespace() {
+        assert_eq!(parse_authorization_input("  "), ParsedAuthInput::default());
+    }
+
+    #[test]
+    fn falls_through_to_hash_split_when_url_hash_has_no_params() {
+        // URL parses successfully but the hash has no code=/state= params →
+        // falls through to the `#` split.
+        assert_eq!(
+            parse_authorization_input("http://127.0.0.1:1455/auth/callback#invalid"),
+            parsed(Some("http://127.0.0.1:1455/auth/callback"), Some("invalid"))
+        );
+    }
+
+    // ----- createAuthorizationFlow -----------------------------------------
+
+    #[test]
+    fn creates_authorization_flow_with_pkce() {
+        let flow = create_authorization_flow(AuthorizationFlowOptions::default());
+        assert!(!flow.pkce.challenge.is_empty());
+        assert!(!flow.pkce.verifier.is_empty());
+        assert_eq!(flow.pkce.verifier.len(), 43, "RFC 7636 base64url of 32 bytes");
+        assert!(is_lower_hex_32(&flow.state));
+        // S256: challenge = base64url(sha256(verifier))
+        let expected = URL_SAFE_NO_PAD.encode(Sha256::digest(flow.pkce.verifier.as_bytes()));
+        assert_eq!(flow.pkce.challenge, expected);
+    }
+
+    #[test]
+    fn generates_url_with_correct_parameters() {
+        let flow = create_authorization_flow(AuthorizationFlowOptions::default());
+        let url = url::Url::parse(&flow.url).expect("flow url parses");
+        assert_eq!(
+            format!(
+                "{}://{}{}",
+                url.scheme(),
+                url.host_str().unwrap(),
+                url.path()
+            ),
+            AUTHORIZE_URL
+        );
+        let get = |key: &str| {
+            url.query_pairs()
+                .find(|(k, _)| k == key)
+                .map(|(_, v)| v.into_owned())
+        };
+        assert_eq!(get("response_type").as_deref(), Some("code"));
+        assert_eq!(get("client_id").as_deref(), Some(CLIENT_ID));
+        assert_eq!(get("redirect_uri").as_deref(), Some(REDIRECT_URI));
+        assert_eq!(get("scope").as_deref(), Some(SCOPE));
+        assert_eq!(get("code_challenge_method").as_deref(), Some("S256"));
+        assert_eq!(get("code_challenge").as_deref(), Some(flow.pkce.challenge.as_str()));
+        assert_eq!(get("state").as_deref(), Some(flow.state.as_str()));
+        assert_eq!(get("id_token_add_organizations").as_deref(), Some("true"));
+        assert_eq!(get("codex_cli_simplified_flow").as_deref(), Some("true"));
+        assert_eq!(get("originator").as_deref(), Some("codex_cli_rs"));
+        assert_eq!(get("prompt"), None);
+    }
+
+    #[test]
+    fn includes_prompt_login_when_force_new_login() {
+        let flow = create_authorization_flow(AuthorizationFlowOptions {
+            force_new_login: true,
+        });
+        let url = url::Url::parse(&flow.url).unwrap();
+        let prompt = url
+            .query_pairs()
+            .find(|(k, _)| k == "prompt")
+            .map(|(_, v)| v.into_owned());
+        assert_eq!(prompt.as_deref(), Some("login"));
+    }
+
+    #[test]
+    fn generates_unique_flows() {
+        let flow1 = create_authorization_flow(AuthorizationFlowOptions::default());
+        let flow2 = create_authorization_flow(AuthorizationFlowOptions::default());
+        assert_ne!(flow1.state, flow2.state);
+        assert_ne!(flow1.pkce.verifier, flow2.pkce.verifier);
+        assert_ne!(flow1.url, flow2.url);
+    }
+
+    // ----- AUTH_REDIRECT ---------------------------------------------------
+
+    #[test]
+    fn auth_redirect_derives_from_redirect_uri_without_drift() {
+        let parsed = url::Url::parse(REDIRECT_URI).unwrap();
+        assert_eq!(AUTH_REDIRECT.host, parsed.host_str().unwrap());
+        assert_eq!(AUTH_REDIRECT.path, parsed.path());
+        assert_eq!(AUTH_REDIRECT.url, REDIRECT_URI);
+        assert_eq!(AUTH_REDIRECT.port, parsed.port().unwrap_or(1455));
+        assert_eq!(
+            AUTH_REDIRECT.origin,
+            format!("{}://{}", parsed.scheme(), &parsed[url::Position::BeforeHost..url::Position::AfterPort])
+        );
+    }
+
+    #[test]
+    fn locks_callback_port_at_1455() {
+        // The OpenAI app registration pins this exact callback. If anyone
+        // changes REDIRECT_URI without updating the registration, login
+        // breaks; this assertion fails loudly before that ships.
+        assert_eq!(AUTH_REDIRECT.port, 1455);
+        assert_eq!(AUTH_REDIRECT.path, "/auth/callback");
+    }
+
+    // ----- redactOAuthUrlForLog --------------------------------------------
+
+    #[test]
+    fn redacts_sensitive_oauth_params_in_urls() {
+        let raw = "https://auth.openai.com/oauth/authorize?state=abc123&code=xyz&code_challenge=foo&response_type=code";
+        let redacted = redact_oauth_url_for_log(raw);
+        assert!(!redacted.contains("abc123"));
+        assert!(!redacted.contains("xyz"));
+        assert!(!redacted.contains("foo"));
+        assert!(redacted.contains("state=%3Credacted%3E"));
+        assert!(redacted.contains("code=%3Credacted%3E"));
+        assert!(redacted.contains("code_challenge=%3Credacted%3E"));
+        assert!(redacted.contains("response_type=code"));
+    }
+
+    #[test]
+    fn returns_original_input_when_url_parsing_fails() {
+        assert_eq!(redact_oauth_url_for_log("not-a-url"), "not-a-url");
+    }
+
+    // ----- exchangeAuthorizationCode (wiremock) ----------------------------
+
+    async fn token_server(body: Value, status: u16) -> MockServer {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(status).set_body_json(body))
+            .mount(&server)
+            .await;
+        server
+    }
+
+    fn token_url(server: &MockServer) -> String {
+        format!("{}/oauth/token", server.uri())
+    }
+
+    async fn last_form_body(server: &MockServer) -> Vec<(String, String)> {
+        let requests = server.received_requests().await.unwrap();
+        let body = requests.last().expect("at least one request").body.clone();
+        url::form_urlencoded::parse(&body)
+            .map(|(k, v)| (k.into_owned(), v.into_owned()))
+            .collect()
+    }
+
+    #[tokio::test]
+    async fn exchange_returns_success_with_tokens() {
+        let server = token_server(
+            json!({
+                "access_token": "access-123",
+                "refresh_token": "refresh-456",
+                "expires_in": 3600,
+                "id_token": "id-token-789",
+            }),
+            200,
+        )
+        .await;
+        let before = now_ms();
+        let result =
+            exchange_authorization_code_at(&token_url(&server), "auth-code", "verifier-123", None)
+                .await;
+        let after = now_ms();
+        let success = result.as_success().expect("success");
+        assert_eq!(success.access, "access-123");
+        assert_eq!(success.refresh, "refresh-456");
+        assert_eq!(success.id_token.as_deref(), Some("id-token-789"));
+        assert_eq!(success.multi_account, Some(true));
+        assert!(success.expires >= before + 3_600_000 && success.expires <= after + 3_600_000);
+
+        // Verify the form body (grant_type / client_id / code / verifier /
+        // default redirect_uri) exactly.
+        let form = last_form_body(&server).await;
+        assert_eq!(
+            form,
+            vec![
+                ("grant_type".to_string(), "authorization_code".to_string()),
+                ("client_id".to_string(), CLIENT_ID.to_string()),
+                ("code".to_string(), "auth-code".to_string()),
+                ("code_verifier".to_string(), "verifier-123".to_string()),
+                ("redirect_uri".to_string(), REDIRECT_URI.to_string()),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn exchange_fails_when_refresh_token_missing() {
+        let server = token_server(json!({ "access_token": "access-123", "expires_in": 3600 }), 200).await;
+        let result =
+            exchange_authorization_code_at(&token_url(&server), "auth-code", "verifier-123", None)
+                .await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert!(failure.message.as_deref().unwrap().contains("Missing refresh token"));
+    }
+
+    #[tokio::test]
+    async fn exchange_fails_when_refresh_token_whitespace_only() {
+        let server = token_server(
+            json!({ "access_token": "access-123", "refresh_token": "   ", "expires_in": 3600 }),
+            200,
+        )
+        .await;
+        let result =
+            exchange_authorization_code_at(&token_url(&server), "auth-code", "verifier-123", None)
+                .await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert!(failure.message.as_deref().unwrap().contains("Missing refresh token"));
+    }
+
+    #[tokio::test]
+    async fn exchange_fails_for_http_error_response() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(400).set_body_string("Bad Request"))
+            .mount(&server)
+            .await;
+        let result =
+            exchange_authorization_code_at(&token_url(&server), "bad-code", "verifier", None).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(400));
+        assert_eq!(failure.message.as_deref(), Some("Bad Request"));
+    }
+
+    #[tokio::test]
+    async fn exchange_fails_for_invalid_response_schema() {
+        let server = token_server(json!({ "wrong": "schema" }), 200).await;
+        let result =
+            exchange_authorization_code_at(&token_url(&server), "code", "verifier", None).await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Response failed schema validation")
+        );
+    }
+
+    #[tokio::test]
+    async fn exchange_uses_custom_redirect_uri() {
+        let server = token_server(json!({ "access_token": "access", "expires_in": 3600 }), 200).await;
+        let _ = exchange_authorization_code_at(
+            &token_url(&server),
+            "code",
+            "verifier",
+            Some("http://custom:8080/callback"),
+        )
+        .await;
+        let form = last_form_body(&server).await;
+        let redirect = form
+            .iter()
+            .find(|(k, _)| k == "redirect_uri")
+            .map(|(_, v)| v.clone());
+        assert_eq!(redirect.as_deref(), Some("http://custom:8080/callback"));
+    }
+
+    // ----- refreshAccessToken (wiremock) -----------------------------------
+
+    #[tokio::test]
+    async fn refresh_keeps_existing_refresh_token_when_missing_in_response() {
+        let server = token_server(json!({ "access_token": "new-access", "expires_in": 60 }), 200).await;
+        let before = now_ms();
+        let result = refresh_access_token_at(&token_url(&server), "existing-refresh").await;
+        let after = now_ms();
+        let success = result.as_success().expect("success");
+        assert_eq!(success.access, "new-access");
+        assert_eq!(success.refresh, "existing-refresh");
+        assert_eq!(success.id_token, None);
+        assert_eq!(success.multi_account, Some(true));
+        assert!(success.expires >= before + 60_000 && success.expires <= after + 60_000);
+
+        let form = last_form_body(&server).await;
+        assert_eq!(
+            form,
+            vec![
+                ("grant_type".to_string(), "refresh_token".to_string()),
+                ("refresh_token".to_string(), "existing-refresh".to_string()),
+                ("client_id".to_string(), CLIENT_ID.to_string()),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_for_http_400_invalid_grant() {
+        let server = token_server(json!({ "error": "invalid_grant" }), 400).await;
+        let result = refresh_access_token_at(&token_url(&server), "bad-token").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(400));
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_for_invalid_response_schema() {
+        let server = token_server(json!({ "wrong": "schema" }), 200).await;
+        let result = refresh_access_token_at(&token_url(&server), "some-token").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_for_network_errors() {
+        // Nothing listens on this endpoint → transport error.
+        let result = refresh_access_token_at("http://127.0.0.1:1/oauth/token", "some-token").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert!(failure.message.is_some());
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_when_response_refresh_token_whitespace_only() {
+        let server = token_server(
+            json!({ "access_token": "new-access", "refresh_token": "   ", "expires_in": 60 }),
+            200,
+        )
+        .await;
+        let result = refresh_access_token_at(&token_url(&server), "existing-refresh").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::MissingRefresh));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("No refresh token in response or input")
+        );
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_when_input_whitespace_and_response_omits_refresh() {
+        let server = token_server(json!({ "access_token": "new-access", "expires_in": 60 }), 200).await;
+        let result = refresh_access_token_at(&token_url(&server), "   ").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::MissingRefresh));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("No refresh token in response or input")
+        );
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_when_both_response_and_input_empty() {
+        let server = token_server(json!({ "access_token": "new-access", "expires_in": 60 }), 200).await;
+        let result = refresh_access_token_at(&token_url(&server), "").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::MissingRefresh));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("No refresh token in response or input")
+        );
+    }
+
+    #[tokio::test]
+    async fn refresh_http_error_with_empty_body_has_no_message() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(500))
+            .mount(&server)
+            .await;
+        let result = refresh_access_token_at(&token_url(&server), "some-token").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(500));
+        assert_eq!(failure.message, None);
+    }
+
+    #[tokio::test]
+    async fn refresh_returns_success_with_new_refresh_token_from_response() {
+        let server = token_server(
+            json!({
+                "access_token": "new-access",
+                "refresh_token": "new-refresh",
+                "expires_in": 60,
+                "id_token": "new-id-token",
+            }),
+            200,
+        )
+        .await;
+        let result = refresh_access_token_at(&token_url(&server), "old-refresh").await;
+        let success = result.as_success().expect("success");
+        assert_eq!(success.access, "new-access");
+        assert_eq!(success.refresh, "new-refresh");
+        assert_eq!(success.id_token.as_deref(), Some("new-id-token"));
+        assert_eq!(success.multi_account, Some(true));
+    }
+
+    #[tokio::test]
+    async fn refresh_http_error_message_does_not_leak_tokens() {
+        // LIB-HIGH-001: the failure message (and log line) must not carry the
+        // opaque refresh token from the error body.
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/oauth/token"))
+            .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+                "error": "invalid_grant",
+                "error_description": "refresh_token expired",
+                "refresh_token": OPAQUE_REFRESH,
+            })))
+            .mount(&server)
+            .await;
+        let result = refresh_access_token_at(&token_url(&server), "input-token").await;
+        let failure = result.as_failure().expect("failed");
+        assert_eq!(failure.status_code, Some(400));
+        let message = failure.message.as_deref().expect("message");
+        assert!(!message.contains(OPAQUE_REFRESH));
+        assert!(message.contains("invalid_grant"));
+    }
+
+    // ----- sanitizeOAuthResponseBodyForLog (LIB-HIGH-001 regression) -------
+
+    #[test]
+    fn masks_refresh_and_access_token_in_json_error_body() {
+        let body = json!({
+            "error": "invalid_grant",
+            "error_description": "bad refresh",
+            "refresh_token": OPAQUE_REFRESH,
+            "access_token": OPAQUE_ACCESS,
+            "id_token": "some.id.token",
+        })
+        .to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(!out.contains(OPAQUE_ACCESS));
+        assert!(out.contains(REDACTED));
+        assert!(out.contains("invalid_grant"));
+    }
+
+    #[test]
+    fn masks_nested_sensitive_fields_in_json_body() {
+        let body = json!({
+            "error": "invalid_grant",
+            "debug": { "refresh_token": OPAQUE_REFRESH, "reason": "x" },
+        })
+        .to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(out.contains("invalid_grant"));
+        assert!(out.contains("x"));
+    }
+
+    #[test]
+    fn masks_urlencoded_refresh_token_value_form() {
+        let body = format!("error=invalid_grant&refresh_token={OPAQUE_REFRESH}&other=safe");
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(out.contains("refresh_token=***REDACTED***"));
+        assert!(out.contains("other=safe"));
+    }
+
+    #[test]
+    fn does_not_over_redact_longer_parameter_names_ending_in_code() {
+        let body =
+            format!("error=invalid_grant&device_code=device-safe&refresh_token={OPAQUE_REFRESH}&other=safe");
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(out.contains("device_code=device-safe"));
+        assert!(out.contains("refresh_token=***REDACTED***"));
+        assert!(out.contains("other=safe"));
+    }
+
+    #[test]
+    fn masks_refresh_token_in_malformed_json_via_fallback() {
+        let body = format!("{{\"error\":\"invalid_grant\",\"refresh_token\":\"{OPAQUE_REFRESH}\",");
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(out.contains("\"refresh_token\":\"***REDACTED***\""));
+    }
+
+    #[test]
+    fn returns_non_token_plain_text_unchanged() {
+        assert_eq!(sanitize_oauth_response_body_for_log("Bad Request"), "Bad Request");
+        assert_eq!(sanitize_oauth_response_body_for_log(""), "");
+    }
+
+    #[test]
+    fn preserves_structure_and_non_sensitive_json_fields() {
+        let body = json!({
+            "error": "invalid_grant",
+            "status": 400,
+            "refresh_token": OPAQUE_REFRESH,
+        })
+        .to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        let parsed: Value = serde_json::from_str(&out).expect("valid JSON");
+        assert_eq!(parsed["error"], json!("invalid_grant"));
+        assert_eq!(parsed["status"], json!(400));
+        assert_eq!(parsed["refresh_token"], json!(REDACTED));
+    }
+
+    #[test]
+    fn masks_camel_case_variants() {
+        let body = json!({ "refreshToken": OPAQUE_REFRESH, "accessToken": OPAQUE_ACCESS }).to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(!out.contains(OPAQUE_ACCESS));
+    }
+
+    #[test]
+    fn masks_code_verifier_camel_case_variant() {
+        let body = json!({ "codeVerifier": OPAQUE_REFRESH, "status": 400 }).to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(out.contains(REDACTED));
+        assert!(out.contains("400"));
+    }
+
+    #[test]
+    fn scrubs_token_like_substrings_inside_parsed_json_string_values() {
+        let body =
+            json!({ "error_description": format!("refresh failed for token {OPAQUE_REFRESH}") })
+                .to_string();
+        let out = sanitize_oauth_response_body_for_log(&body);
+        assert!(!out.contains(OPAQUE_REFRESH));
+        assert!(out.contains(REDACTED));
+    }
+
+    #[test]
+    fn scrubs_keyed_assignment_substrings() {
+        // Regex 1 semantics: keep the `refresh_token: ` prefix, mask the value.
+        let input = "failure: refresh_token: abcdefgh12345678 next";
+        let out = scrub_token_like_substrings(input);
+        assert_eq!(out, "failure: refresh_token: ***REDACTED*** next");
+        // Values shorter than 8 chars are NOT masked.
+        assert_eq!(
+            scrub_token_like_substrings("refresh_token: short"),
+            "refresh_token: short"
+        );
+    }
+}
diff --git a/crates/auth/src/org_override.rs b/crates/auth/src/org_override.rs
new file mode 100644
index 000000000..43e02f499
--- /dev/null
+++ b/crates/auth/src/org_override.rs
@@ -0,0 +1,133 @@
+//! Port of `lib/auth/org-override.ts` — resolve the effective account-id
+//! override for a login (spec 07 §4).
+//!
+//! Precedence: an explicit `login --org <id>` argument wins over the ambient
+//! `CODEX_AUTH_ACCOUNT_ID` env var, for that call only. A blank/whitespace
+//! explicit org is treated as absent so an empty `--org ""` does NOT suppress
+//! the env fallback (spec 07 gotcha 19).
+//!
+//! Concurrency contract (spec 07 gotcha 19): the login launcher must NOT
+//! mutate the process environment for the duration of a login — the previous
+//! implementation raced on re-entry / reused test workers. This function only
+//! READS the environment (or an injected value) and never writes it.
+//!
+//! Deliberately not re-exported from the CLI entrypoint surface in TS; kept a
+//! plain internal-style module here as well.
+
+/// Environment variable carrying the ambient account-id override.
+pub const CODEX_AUTH_ACCOUNT_ID_ENV: &str = "CODEX_AUTH_ACCOUNT_ID";
+
+/// Resolve the effective org/account-id override from an explicit `--org`
+/// value and the ambient `CODEX_AUTH_ACCOUNT_ID` environment variable
+/// (TS `resolveOrgOverride` with the default `process.env`).
+///
+/// Returns the trimmed effective override, or `None` when neither source
+/// provides one.
+pub fn resolve_org_override(explicit_org: Option<&str>) -> Option<String> {
+    let env_value = std::env::var(CODEX_AUTH_ACCOUNT_ID_ENV).ok();
+    resolve_org_override_in(explicit_org, env_value.as_deref())
+}
+
+/// [`resolve_org_override`] with the environment value injected (TS
+/// `resolveOrgOverride(explicitOrg, env)` — the injectable-env test seam).
+///
+/// Semantics mirror the TS falsy-empty-string chain exactly:
+/// `((explicitOrg?.trim() || env.CODEX_AUTH_ACCOUNT_ID) || "").trim()`,
+/// `None` when the result is empty.
+pub fn resolve_org_override_in(
+    explicit_org: Option<&str>,
+    env_account_id: Option<&str>,
+) -> Option<String> {
+    // `explicitOrg?.trim()` — an all-whitespace explicit value trims to the
+    // empty string, which is falsy in TS and therefore falls through to env.
+    let explicit = explicit_org.map(str::trim).filter(|value| !value.is_empty());
+    let chosen = explicit.or(env_account_id).unwrap_or("");
+    let trimmed = chosen.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+// ===========================================================================
+// Tests (ported from test/codex-manager-org-override.test.ts)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    #[test]
+    fn explicit_org_argument_wins_over_env_override() {
+        assert_eq!(
+            resolve_org_override_in(Some("explicit-org-wins"), Some("env-org-should-lose")),
+            Some("explicit-org-wins".to_string())
+        );
+    }
+
+    #[test]
+    fn falls_back_to_env_override_when_no_explicit_org() {
+        assert_eq!(
+            resolve_org_override_in(None, Some("env-org-used")),
+            Some("env-org-used".to_string())
+        );
+    }
+
+    #[test]
+    fn ignores_blank_explicit_org_and_uses_env_override() {
+        assert_eq!(
+            resolve_org_override_in(Some("   "), Some("env-org-fallback")),
+            Some("env-org-fallback".to_string())
+        );
+    }
+
+    #[test]
+    fn returns_none_when_neither_source_is_set() {
+        assert_eq!(resolve_org_override_in(None, None), None);
+        assert_eq!(resolve_org_override_in(Some("   "), None), None);
+        // Env set but empty is also absent (falsy chain + final trim).
+        assert_eq!(resolve_org_override_in(None, Some("")), None);
+        assert_eq!(resolve_org_override_in(None, Some("   ")), None);
+    }
+
+    #[test]
+    fn trims_surrounding_whitespace_from_the_chosen_value() {
+        assert_eq!(
+            resolve_org_override_in(Some("  org-padded  "), None),
+            Some("org-padded".to_string())
+        );
+        assert_eq!(
+            resolve_org_override_in(None, Some("  env-padded ")),
+            Some("env-padded".to_string())
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn env_reading_variant_does_not_mutate_the_environment() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var(CODEX_AUTH_ACCOUNT_ID_ENV, "env-stays-put");
+
+        // Explicit wins for this call only; the env var is untouched.
+        assert_eq!(
+            resolve_org_override(Some("explicit-org")),
+            Some("explicit-org".to_string())
+        );
+        assert_eq!(
+            std::env::var(CODEX_AUTH_ACCOUNT_ID_ENV).as_deref(),
+            Ok("env-stays-put")
+        );
+
+        // And the env fallback works through the reading variant.
+        assert_eq!(
+            resolve_org_override(None),
+            Some("env-stays-put".to_string())
+        );
+
+        sandbox.remove_var(CODEX_AUTH_ACCOUNT_ID_ENV);
+        assert_eq!(resolve_org_override(None), None);
+    }
+}
diff --git a/crates/auth/src/refresh_lease.rs b/crates/auth/src/refresh_lease.rs
new file mode 100644
index 000000000..7cc13dce6
--- /dev/null
+++ b/crates/auth/src/refresh_lease.rs
@@ -0,0 +1,1534 @@
+//! Port of `lib/refresh-lease.ts` — cross-**process** refresh lease.
+//!
+//! Behavior source: specs/04-rotation.md §5.
+//!
+//! Prevents two processes from concurrently refreshing the same OAuth refresh
+//! token (OpenAI rotates the token on first use ⇒ the second refresh gets
+//! `invalid_grant`). The mutual-exclusion primitive is O_CREAT|O_EXCL on
+//! `<leaseDir>/<sha256(token)>.lock` (0600 under a 0700 dir); ownership is a
+//! per-owner uuid nonce (stress audit H2); successful refresh results are
+//! cached in `<sha256>.result.json` for `resultTtlMs` so followers reuse them.
+//!
+//! On-disk formats are byte-compatible with TS: single-line compact JSON plus
+//! a trailing `\n` (`{"tokenHash":…,"pid":…,"acquiredAt":…,"expiresAt":…,"nonce":…}`
+//! and `{"tokenHash":…,"createdAt":…,"result":{…}}`).
+
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::UNIX_EPOCH;
+
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+
+use cma_core::env_parsing::parse_boolean_env;
+use cma_core::fs_retry::code_of;
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::schemas::parse::safe_parse_token_result;
+use cma_core::schemas::token::TokenResult;
+use cma_core::utils::{is_record, now_ms, sleep};
+
+fn log() -> ScopedLogger {
+    create_logger("refresh-lease")
+}
+
+const DEFAULT_LEASE_TTL_MS: i64 = 30_000;
+/// Exported so the refresh queue can size its acquire-stage eviction threshold
+/// above the maximum time a lease `acquire()` may legitimately block waiting.
+pub const DEFAULT_WAIT_TIMEOUT_MS: i64 = 35_000;
+const DEFAULT_POLL_INTERVAL_MS: i64 = 150;
+const DEFAULT_RESULT_TTL_MS: i64 = 20_000;
+const RETRYABLE_IO_ERRORS: [&str; 4] = ["EBUSY", "EPERM", "EMFILE", "ENFILE"];
+
+/// Parsed `LeaseFilePayload` (lock file).
+#[derive(Clone, Debug, PartialEq)]
+struct LeaseFilePayload {
+    token_hash: String,
+    #[allow(dead_code)]
+    pid: i64,
+    #[allow(dead_code)]
+    acquired_at: i64,
+    expires_at: i64,
+    /// Per-owner identity; `""` for locks written before H2 (best-effort
+    /// unlink fallback on release).
+    nonce: String,
+}
+
+/// Injectable fs operations (the TS `fsOps` seam). Sync methods — every
+/// underlying operation is a small local file op; async-ness in the
+/// coordinator comes only from the poll sleeps.
+pub trait LeaseFs: Send + Sync {
+    /// `mkdir(dir, { recursive: true, mode })` — succeeds when the dir exists.
+    fn mkdir_recursive(&self, dir: &Path, mode: u32) -> io::Result<()>;
+    /// Best-effort `chmod` (POSIX hardening; no-op impls are fine). Return
+    /// `false` from [`LeaseFs::has_chmod`] to model a fsOps without `chmod`.
+    fn chmod(&self, path: &Path, mode: u32) -> io::Result<()>;
+    fn has_chmod(&self) -> bool {
+        true
+    }
+    /// `open(path, "wx", mode)` + write `contents` through the handle. MUST
+    /// fail with an `EEXIST`-coded error when the file already exists.
+    fn open_excl_write(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()>;
+    /// `writeFile(path, contents, { mode })` (create/truncate).
+    fn write_file(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()>;
+    fn rename(&self, from: &Path, to: &Path) -> io::Result<()>;
+    fn unlink(&self, path: &Path) -> io::Result<()>;
+    fn read_to_string(&self, path: &Path) -> io::Result<String>;
+    /// `stat(path).mtimeMs`.
+    fn mtime_ms(&self, path: &Path) -> io::Result<f64>;
+    /// `readdir(dir, { withFileTypes: true })` filtered to regular files —
+    /// returns file names only.
+    fn read_dir_files(&self, dir: &Path) -> io::Result<Vec<String>>;
+}
+
+/// Real filesystem implementation (the default, `fs.promises` in TS).
+#[derive(Debug, Default, Clone, Copy)]
+pub struct RealLeaseFs;
+
+impl LeaseFs for RealLeaseFs {
+    fn mkdir_recursive(&self, dir: &Path, mode: u32) -> io::Result<()> {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::DirBuilderExt;
+            let mut builder = std::fs::DirBuilder::new();
+            builder.recursive(true);
+            builder.mode(mode);
+            builder.create(dir)
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = mode; // POSIX modes are a no-op on Windows (Node parity)
+            std::fs::create_dir_all(dir)
+        }
+    }
+
+    fn chmod(&self, path: &Path, mode: u32) -> io::Result<()> {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(path, std::fs::Permissions::from_mode(mode))
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = (path, mode);
+            Ok(())
+        }
+    }
+
+    fn open_excl_write(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+        use std::io::Write;
+        let mut options = std::fs::OpenOptions::new();
+        options.write(true).create_new(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            options.mode(mode);
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = mode;
+        }
+        let mut file = options.open(path)?;
+        file.write_all(contents.as_bytes())
+    }
+
+    fn write_file(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+        use std::io::Write;
+        let mut options = std::fs::OpenOptions::new();
+        options.write(true).create(true).truncate(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            options.mode(mode);
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = mode;
+        }
+        let mut file = options.open(path)?;
+        file.write_all(contents.as_bytes())
+    }
+
+    fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+        std::fs::rename(from, to)
+    }
+
+    fn unlink(&self, path: &Path) -> io::Result<()> {
+        std::fs::remove_file(path)
+    }
+
+    fn read_to_string(&self, path: &Path) -> io::Result<String> {
+        std::fs::read_to_string(path)
+    }
+
+    fn mtime_ms(&self, path: &Path) -> io::Result<f64> {
+        let metadata = std::fs::metadata(path)?;
+        let modified = metadata.modified()?;
+        Ok(match modified.duration_since(UNIX_EPOCH) {
+            Ok(duration) => duration.as_secs_f64() * 1000.0,
+            // Pre-epoch mtimes (clock weirdness): negative ms like Node.
+            Err(error) => -(error.duration().as_secs_f64() * 1000.0),
+        })
+    }
+
+    fn read_dir_files(&self, dir: &Path) -> io::Result<Vec<String>> {
+        let mut names = Vec::new();
+        for entry in std::fs::read_dir(dir)? {
+            let entry = entry?;
+            let is_file = entry.file_type().map(|ft| ft.is_file()).unwrap_or(false);
+            if !is_file {
+                continue;
+            }
+            if let Some(name) = entry.file_name().to_str() {
+                names.push(name.to_string());
+            }
+        }
+        Ok(names)
+    }
+}
+
+/// `RefreshLeaseCoordinatorOptions`.
+#[derive(Default)]
+pub struct RefreshLeaseCoordinatorOptions {
+    pub enabled: Option<bool>,
+    pub lease_dir: Option<PathBuf>,
+    pub lease_ttl_ms: Option<i64>,
+    pub wait_timeout_ms: Option<i64>,
+    pub poll_interval_ms: Option<i64>,
+    pub result_ttl_ms: Option<i64>,
+    pub fs_ops: Option<Arc<dyn LeaseFs>>,
+}
+
+/// Lease handle role.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LeaseRole {
+    Owner,
+    Follower,
+    Bypass,
+}
+
+enum HandleInner {
+    /// Bypass and follower handles: `release()` is a no-op.
+    Noop,
+    Owner {
+        token_hash: String,
+        lock_path: PathBuf,
+        result_path: PathBuf,
+        nonce: String,
+        fs: Arc<dyn LeaseFs>,
+        released: AtomicBool,
+    },
+}
+
+/// `RefreshLeaseHandle` — `{ role, result?, release(result?) }`.
+pub struct RefreshLeaseHandle {
+    pub role: LeaseRole,
+    pub result: Option<TokenResult>,
+    inner: HandleInner,
+}
+
+impl RefreshLeaseHandle {
+    pub(crate) fn bypass() -> Self {
+        Self {
+            role: LeaseRole::Bypass,
+            result: None,
+            inner: HandleInner::Noop,
+        }
+    }
+
+    pub(crate) fn follower(result: TokenResult) -> Self {
+        Self {
+            role: LeaseRole::Follower,
+            result: Some(result),
+            inner: HandleInner::Noop,
+        }
+    }
+
+    pub(crate) fn owner(
+        token_hash: String,
+        lock_path: PathBuf,
+        result_path: PathBuf,
+        nonce: String,
+        fs: Arc<dyn LeaseFs>,
+    ) -> Self {
+        Self {
+            role: LeaseRole::Owner,
+            result: None,
+            inner: HandleInner::Owner {
+                token_hash,
+                lock_path,
+                result_path,
+                nonce,
+                fs,
+                released: AtomicBool::new(false),
+            },
+        }
+    }
+
+    /// Owner `release(result?)`: idempotent. Only a SUCCESSFUL refresh result
+    /// is cached for followers — a failed result carries no token material and
+    /// caching it would serve the failure verbatim to every follower for the
+    /// whole result TTL, blocking a real retry. The lock is unlinked only when
+    /// still owned (nonce match, H2); otherwise it is left for the current
+    /// owner with a warning. Follower/bypass handles: no-op.
+    ///
+    /// The `io::Result` mirrors the TS promise: writing the result file can
+    /// fail (callers warn and continue); the unlink path never errors.
+    pub async fn release(&self, result: Option<&TokenResult>) -> io::Result<()> {
+        let HandleInner::Owner {
+            token_hash,
+            lock_path,
+            result_path,
+            nonce,
+            fs,
+            released,
+        } = &self.inner
+        else {
+            return Ok(());
+        };
+        if released.swap(true, Ordering::SeqCst) {
+            return Ok(());
+        }
+        let write_outcome = match result {
+            Some(result @ TokenResult::Success(_)) => {
+                write_result(fs, result_path, token_hash, result).await
+            }
+            _ => Ok(()),
+        };
+        // finally: unlink the lock only if it is still OURS (stress audit H2).
+        if owns_lock(fs, lock_path, token_hash, nonce) {
+            safe_unlink(fs, lock_path, None, None).await;
+        } else {
+            log().warn(
+                "Refresh lease no longer owned at release; leaving lock for current owner",
+                Some(&json!({ "lockPath": lock_path.to_string_lossy() })),
+            );
+        }
+        write_outcome
+    }
+}
+
+/// `parseEnvInt` — JS `Number.parseInt(value, 10)` semantics: leading
+/// whitespace skipped, optional sign, longest digit prefix; no digits ⇒ None.
+fn parse_env_int(value: Option<&str>) -> Option<i64> {
+    let value = value?;
+    let trimmed = value.trim_start();
+    let (sign, digits_part) = match trimmed.strip_prefix('-') {
+        Some(rest) => (-1i64, rest),
+        None => (1i64, trimmed.strip_prefix('+').unwrap_or(trimmed)),
+    };
+    let digits: String = digits_part.chars().take_while(|c| c.is_ascii_digit()).collect();
+    if digits.is_empty() {
+        return None;
+    }
+    let magnitude: i64 = digits.parse().unwrap_or(i64::MAX);
+    Some(sign * magnitude)
+}
+
+fn hash_refresh_token(refresh_token: &str) -> String {
+    let digest = Sha256::digest(refresh_token.as_bytes());
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        use std::fmt::Write;
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+fn parse_lease_payload(raw: &Value) -> Option<LeaseFilePayload> {
+    if !is_record(raw) {
+        return None;
+    }
+    let token_hash = raw
+        .get("tokenHash")
+        .and_then(Value::as_str)
+        .unwrap_or("")
+        .to_string();
+    let pid = raw.get("pid").and_then(Value::as_f64);
+    let acquired_at = raw.get("acquiredAt").and_then(Value::as_f64);
+    let expires_at = raw.get("expiresAt").and_then(Value::as_f64);
+    // nonce is optional for backward-compat with locks written before H2.
+    let nonce = raw
+        .get("nonce")
+        .and_then(Value::as_str)
+        .unwrap_or("")
+        .to_string();
+    let (Some(pid), Some(acquired_at), Some(expires_at)) = (pid, acquired_at, expires_at) else {
+        return None;
+    };
+    if token_hash.is_empty()
+        || !pid.is_finite()
+        || !acquired_at.is_finite()
+        || !expires_at.is_finite()
+    {
+        return None;
+    }
+    Some(LeaseFilePayload {
+        token_hash,
+        pid: pid.floor() as i64,
+        acquired_at: acquired_at.floor() as i64,
+        expires_at: expires_at.floor() as i64,
+        nonce,
+    })
+}
+
+/// Parsed `ResultFilePayload` — `result` validated with the shared
+/// `TokenResult` schema; invalid ⇒ None (file ignored).
+fn parse_result_payload(raw: &Value) -> Option<(String, i64, TokenResult)> {
+    if !is_record(raw) {
+        return None;
+    }
+    let token_hash = raw
+        .get("tokenHash")
+        .and_then(Value::as_str)
+        .unwrap_or("")
+        .to_string();
+    let created_at = raw.get("createdAt").and_then(Value::as_f64);
+    let result = raw.get("result").and_then(safe_parse_token_result);
+    let (Some(created_at), Some(result)) = (created_at, result) else {
+        return None;
+    };
+    if token_hash.is_empty() || !created_at.is_finite() {
+        return None;
+    }
+    Some((token_hash, created_at.floor() as i64, result))
+}
+
+/// `readJson` — read + parse, any error ⇒ None.
+fn read_json(fs: &Arc<dyn LeaseFs>, path: &Path) -> Option<Value> {
+    let content = fs.read_to_string(path).ok()?;
+    serde_json::from_str::<Value>(&content).ok()
+}
+
+/// `safeUnlink` — up to 4 attempts, base delay 15 ms doubling
+/// (`15 * 2^attempt`), retrying only {EBUSY, EPERM, EMFILE, ENFILE};
+/// ENOENT counts as success. Never errors.
+async fn safe_unlink(
+    fs: &Arc<dyn LeaseFs>,
+    path: &Path,
+    attempts: Option<i64>,
+    base_delay_ms: Option<i64>,
+) -> bool {
+    let attempts = attempts.unwrap_or(4).max(1);
+    let base_delay_ms = base_delay_ms.unwrap_or(15).max(5);
+    for attempt in 0..attempts {
+        match fs.unlink(path) {
+            Ok(()) => return true,
+            Err(error) => {
+                let code = code_of(&error);
+                if code == Some("ENOENT") {
+                    return true;
+                }
+                let can_retry = matches!(code, Some(code) if RETRYABLE_IO_ERRORS.contains(&code));
+                if can_retry && attempt + 1 < attempts {
+                    sleep((base_delay_ms as u64).saturating_mul(1u64 << attempt.min(62))).await;
+                    continue;
+                }
+                log().debug(
+                    "Failed to remove lease artifact",
+                    Some(&json!({
+                        "path": path.to_string_lossy(),
+                        "error": error.to_string(),
+                        "code": code,
+                    })),
+                );
+                return false;
+            }
+        }
+    }
+    false
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum LockState {
+    Stale,
+    Active,
+    Unknown,
+}
+
+fn is_retryable_fs_code(code: Option<&str>) -> bool {
+    matches!(code, Some(code) if RETRYABLE_IO_ERRORS.contains(&code))
+}
+
+/// `ownsLock` — unreadable/absent lock ⇒ true (nothing of ours to protect);
+/// tokenHash mismatch ⇒ false; empty on-disk nonce (pre-H2) ⇒ true; else
+/// nonce equality.
+fn owns_lock(fs: &Arc<dyn LeaseFs>, lock_path: &Path, token_hash: &str, nonce: &str) -> bool {
+    let Some(raw) = read_json(fs, lock_path) else {
+        return true;
+    };
+    let Some(parsed) = parse_lease_payload(&raw) else {
+        return true;
+    };
+    if parsed.token_hash != token_hash {
+        return false;
+    }
+    if parsed.nonce.is_empty() {
+        return true;
+    }
+    parsed.nonce == nonce
+}
+
+/// `writeResult` — atomic temp+rename, temp mode 0600 (the payload embeds the
+/// refreshed access + refresh tokens); temp unlinked in `finally` either way.
+async fn write_result(
+    fs: &Arc<dyn LeaseFs>,
+    result_path: &Path,
+    token_hash: &str,
+    result: &TokenResult,
+) -> io::Result<()> {
+    let payload = json!({
+        "tokenHash": token_hash,
+        "createdAt": now_ms(),
+        "result": result,
+    });
+    let temp_path = PathBuf::from(format!(
+        "{}.{}.{}.tmp",
+        result_path.to_string_lossy(),
+        std::process::id(),
+        now_ms(),
+    ));
+    let outcome = async {
+        fs.write_file(&temp_path, &format!("{}\n", stringify_compact(&payload)), 0o600)?;
+        fs.rename(&temp_path, result_path)
+    }
+    .await;
+    safe_unlink(fs, &temp_path, None, None).await;
+    outcome
+}
+
+/// `RefreshLeaseCoordinator`.
+pub struct RefreshLeaseCoordinator {
+    enabled: bool,
+    lease_dir: PathBuf,
+    lease_ttl_ms: i64,
+    wait_timeout_ms: i64,
+    poll_interval_ms: i64,
+    result_ttl_ms: i64,
+    fs: Arc<dyn LeaseFs>,
+}
+
+impl RefreshLeaseCoordinator {
+    pub fn new(options: RefreshLeaseCoordinatorOptions) -> Self {
+        Self {
+            enabled: options.enabled.unwrap_or(true),
+            lease_dir: options
+                .lease_dir
+                .unwrap_or_else(|| get_codex_multi_auth_dir().join("refresh-leases")),
+            lease_ttl_ms: options.lease_ttl_ms.unwrap_or(DEFAULT_LEASE_TTL_MS).max(1_000),
+            wait_timeout_ms: options.wait_timeout_ms.unwrap_or(DEFAULT_WAIT_TIMEOUT_MS).max(0),
+            poll_interval_ms: options
+                .poll_interval_ms
+                .unwrap_or(DEFAULT_POLL_INTERVAL_MS)
+                .max(50),
+            result_ttl_ms: options.result_ttl_ms.unwrap_or(DEFAULT_RESULT_TTL_MS).max(1_000),
+            fs: options.fs_ops.unwrap_or_else(|| Arc::new(RealLeaseFs)),
+        }
+    }
+
+    /// Resolved maximum time `acquire()` may block waiting for a lease.
+    ///
+    /// Exposed so the refresh queue can size its acquire-stage eviction
+    /// threshold against the budget this coordinator ACTUALLY uses (it is
+    /// configurable via constructor option / `CODEX_AUTH_REFRESH_LEASE_WAIT_MS`).
+    pub fn configured_wait_timeout_ms(&self) -> i64 {
+        self.wait_timeout_ms
+    }
+
+    /// `fromEnvironment()` — `enabled = parseBooleanEnv(CODEX_AUTH_REFRESH_LEASE)
+    /// ?? (testMode ? false : true)` where testMode = `VITEST === "true" ||
+    /// NODE_ENV === "test"`. Empty/whitespace `CODEX_AUTH_REFRESH_LEASE_DIR` is
+    /// treated as unset; numeric tunables via parseInt semantics.
+    pub fn from_environment() -> Self {
+        let env = |key: &str| std::env::var(key).ok();
+        let test_mode = env("VITEST").as_deref() == Some("true")
+            || env("NODE_ENV").as_deref() == Some("test");
+        let enabled = parse_boolean_env(env("CODEX_AUTH_REFRESH_LEASE").as_deref())
+            .unwrap_or(!test_mode);
+        let lease_dir = env("CODEX_AUTH_REFRESH_LEASE_DIR")
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from);
+        Self::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(enabled),
+            lease_dir,
+            lease_ttl_ms: parse_env_int(env("CODEX_AUTH_REFRESH_LEASE_TTL_MS").as_deref()),
+            wait_timeout_ms: parse_env_int(env("CODEX_AUTH_REFRESH_LEASE_WAIT_MS").as_deref()),
+            poll_interval_ms: parse_env_int(env("CODEX_AUTH_REFRESH_LEASE_POLL_MS").as_deref()),
+            result_ttl_ms: parse_env_int(env("CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS").as_deref()),
+            fs_ops: None,
+        })
+    }
+
+    /// `acquire(refreshToken)`.
+    ///
+    /// The only error path is the initial lease-dir `mkdir` (uncaught in TS
+    /// too — the refresh queue catches it and falls back to a local refresh).
+    /// Everything else resolves to a handle: owner, follower (cached result),
+    /// or bypass (disabled / empty-token / wait-timeout / acquire-error —
+    /// bypass = proceed with the refresh WITHOUT cross-process protection,
+    /// never fail the refresh).
+    pub async fn acquire(&self, refresh_token: &str) -> io::Result<RefreshLeaseHandle> {
+        if !self.enabled {
+            return Ok(self.create_bypass_handle("disabled"));
+        }
+        if refresh_token.trim().is_empty() {
+            return Ok(self.create_bypass_handle("empty-token"));
+        }
+
+        let token_hash = hash_refresh_token(refresh_token);
+        let lock_path = self.lease_dir.join(format!("{token_hash}.lock"));
+        let result_path = self.lease_dir.join(format!("{token_hash}.result.json"));
+        // Lease artifacts hold full OAuth token material; restrict the
+        // directory to the owner (0600 files under a 0700 dir).
+        self.fs.mkdir_recursive(&self.lease_dir, 0o700)?;
+        // mkdir(recursive) only applies mode to dirs it actually creates;
+        // tighten explicitly on POSIX so upgrades also constrain a
+        // pre-existing dir. No-op on Windows, best-effort everywhere.
+        #[cfg(unix)]
+        if self.fs.has_chmod() {
+            let _ = self.fs.chmod(&self.lease_dir, 0o700);
+        }
+        // Fire-and-forget prune (TS `void this.pruneExpiredArtifacts()`).
+        {
+            let fs = Arc::clone(&self.fs);
+            let lease_dir = self.lease_dir.clone();
+            let lease_ttl_ms = self.lease_ttl_ms;
+            let result_ttl_ms = self.result_ttl_ms;
+            tokio::spawn(async move {
+                prune_expired_artifacts_in(&fs, &lease_dir, lease_ttl_ms, result_ttl_ms).await;
+            });
+        }
+
+        let deadline = now_ms() + self.wait_timeout_ms;
+        loop {
+            if let Some(cached) = self.read_fresh_result(&result_path, &token_hash).await {
+                return Ok(RefreshLeaseHandle::follower(cached));
+            }
+
+            let nonce = uuid::Uuid::new_v4().to_string();
+            let now = now_ms();
+            let payload = json!({
+                "tokenHash": token_hash,
+                "pid": std::process::id(),
+                "acquiredAt": now,
+                "expiresAt": now + self.lease_ttl_ms,
+                "nonce": nonce,
+            });
+            match self.fs.open_excl_write(
+                &lock_path,
+                &format!("{}\n", stringify_compact(&payload)),
+                0o600,
+            ) {
+                Ok(()) => {
+                    return Ok(RefreshLeaseHandle::owner(
+                        token_hash,
+                        lock_path,
+                        result_path,
+                        nonce,
+                        Arc::clone(&self.fs),
+                    ));
+                }
+                Err(error) => {
+                    let code = code_of(&error);
+                    if code != Some("EEXIST") {
+                        log().warn(
+                            "Refresh lease acquisition failed; proceeding without lease",
+                            Some(&json!({ "error": error.to_string() })),
+                        );
+                        return Ok(self.create_bypass_handle("acquire-error"));
+                    }
+
+                    let (state, _reason) = self.assess_lock_staleness(&lock_path, &token_hash);
+                    if state == LockState::Stale {
+                        let removed = safe_unlink(&self.fs, &lock_path, None, None).await;
+                        if removed {
+                            continue;
+                        }
+                        if now_ms() >= deadline {
+                            log().warn(
+                                "Refresh lease wait timeout while stale lock could not be removed",
+                                Some(&json!({ "waitTimeoutMs": self.wait_timeout_ms })),
+                            );
+                            return Ok(self.create_bypass_handle("wait-timeout"));
+                        }
+                        sleep(self.poll_interval_ms.max(0) as u64).await;
+                        continue;
+                    }
+
+                    // active / unknown
+                    if now_ms() >= deadline {
+                        log().warn(
+                            "Refresh lease wait timeout; proceeding without lease",
+                            Some(&json!({ "waitTimeoutMs": self.wait_timeout_ms })),
+                        );
+                        return Ok(self.create_bypass_handle("wait-timeout"));
+                    }
+                    sleep(self.poll_interval_ms.max(0) as u64).await;
+                }
+            }
+        }
+    }
+
+    fn create_bypass_handle(&self, reason: &str) -> RefreshLeaseHandle {
+        log().debug("Bypassing refresh lease", Some(&json!({ "reason": reason })));
+        RefreshLeaseHandle::bypass()
+    }
+
+    /// `readFreshResult` — parsed + tokenHash match + `now - createdAt <=
+    /// resultTtlMs` ⇒ Some(result); expired result is unlinked and treated as
+    /// absent.
+    async fn read_fresh_result(&self, result_path: &Path, token_hash: &str) -> Option<TokenResult> {
+        // TS uses (uninjected) existsSync here.
+        if !result_path.exists() {
+            return None;
+        }
+        let raw = read_json(&self.fs, result_path)?;
+        let (parsed_hash, created_at, result) = parse_result_payload(&raw)?;
+        if parsed_hash != token_hash {
+            return None;
+        }
+        let age_ms = now_ms() - created_at;
+        if age_ms > self.result_ttl_ms {
+            safe_unlink(&self.fs, result_path, None, None).await;
+            return None;
+        }
+        Some(result)
+    }
+
+    /// `assessLockStaleness` — see spec 04 §5 for the full decision table.
+    fn assess_lock_staleness(&self, lock_path: &Path, token_hash: &str) -> (LockState, String) {
+        let raw = read_json(&self.fs, lock_path);
+        let Some(raw) = raw else {
+            // TS uses (uninjected) existsSync here.
+            if !lock_path.exists() {
+                return (LockState::Stale, "missing".to_string());
+            }
+            return (LockState::Unknown, "unreadable".to_string());
+        };
+
+        let Some(parsed) = parse_lease_payload(&raw) else {
+            return (LockState::Unknown, "invalid-payload".to_string());
+        };
+        if parsed.token_hash != token_hash {
+            return (LockState::Unknown, "token-mismatch".to_string());
+        }
+        if parsed.expires_at <= now_ms() {
+            return (LockState::Stale, "expired".to_string());
+        }
+
+        match self.fs.mtime_ms(lock_path) {
+            Ok(mtime_ms) => {
+                if now_ms() as f64 - mtime_ms > self.lease_ttl_ms as f64 {
+                    (LockState::Stale, "mtime-expired".to_string())
+                } else {
+                    (LockState::Active, "fresh".to_string())
+                }
+            }
+            Err(error) => {
+                let code = code_of(&error);
+                if code == Some("ENOENT") {
+                    return (LockState::Stale, "missing".to_string());
+                }
+                if is_retryable_fs_code(code) || code == Some("EACCES") {
+                    return (
+                        LockState::Unknown,
+                        format!("stat-{}", code.unwrap_or("").to_lowercase()),
+                    );
+                }
+                (LockState::Unknown, "stat-error".to_string())
+            }
+        }
+    }
+
+    /// `pruneExpiredArtifacts` — delete `.lock`/`.result.json` files whose
+    /// mtime is older than `max(leaseTtlMs, resultTtlMs) * 2`; every error is
+    /// swallowed (best effort). Public for test parity (the TS suite invokes
+    /// it directly).
+    pub async fn prune_expired_artifacts(&self) {
+        prune_expired_artifacts_in(&self.fs, &self.lease_dir, self.lease_ttl_ms, self.result_ttl_ms)
+            .await;
+    }
+}
+
+async fn prune_expired_artifacts_in(
+    fs: &Arc<dyn LeaseFs>,
+    lease_dir: &Path,
+    lease_ttl_ms: i64,
+    result_ttl_ms: i64,
+) {
+    let Ok(entries) = fs.read_dir_files(lease_dir) else {
+        return; // Best effort.
+    };
+    let now = now_ms();
+    let max_age_ms = lease_ttl_ms.max(result_ttl_ms) * 2;
+    for name in entries {
+        if !name.ends_with(".lock") && !name.ends_with(".result.json") {
+            continue;
+        }
+        let full_path = lease_dir.join(&name);
+        match fs.mtime_ms(&full_path) {
+            Ok(mtime_ms) => {
+                if now as f64 - mtime_ms > max_age_ms as f64 {
+                    safe_unlink(fs, &full_path, None, None).await;
+                }
+            }
+            Err(_) => {
+                // Best effort.
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/refresh-lease.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::{TokenSuccess, TokenResult};
+    use serial_test::serial;
+    use std::sync::atomic::AtomicU32;
+
+    fn sample_success_result() -> TokenResult {
+        TokenResult::Success(TokenSuccess {
+            access: "access-token".to_string(),
+            refresh: "refresh-token-next".to_string(),
+            expires: now_ms() + 60_000,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    fn temp_lease_dir() -> tempfile::TempDir {
+        tempfile::Builder::new()
+            .prefix("codex-refresh-lease-")
+            .tempdir()
+            .expect("lease tempdir")
+    }
+
+    fn coordinator(dir: &Path, opts: RefreshLeaseCoordinatorOptions) -> RefreshLeaseCoordinator {
+        RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.to_path_buf()),
+            ..opts
+        })
+    }
+
+    #[tokio::test]
+    async fn returns_owner_then_follower_with_shared_result() {
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(5_000),
+                wait_timeout_ms: Some(500),
+                poll_interval_ms: Some(25),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+        let sample = sample_success_result();
+
+        let owner = coordinator.acquire("token-a").await.unwrap();
+        assert_eq!(owner.role, LeaseRole::Owner);
+        owner.release(Some(&sample)).await.unwrap();
+
+        let follower = coordinator.acquire("token-a").await.unwrap();
+        assert_eq!(follower.role, LeaseRole::Follower);
+        assert_eq!(follower.result, Some(sample));
+    }
+
+    #[tokio::test]
+    async fn does_not_cache_a_failed_refresh_result() {
+        // Regression: a `failed` result carries no token material; caching it
+        // would serve the failure to every follower for the whole result TTL.
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(5_000),
+                wait_timeout_ms: Some(500),
+                poll_interval_ms: Some(25),
+                result_ttl_ms: Some(5_000),
+                ..Default::default()
+            },
+        );
+        let failed_result = TokenResult::Failed(cma_core::schemas::token::TokenFailure {
+            reason: Some(cma_core::schemas::token::TokenFailureReason::NetworkError),
+            status_code: None,
+            message: Some("boom".to_string()),
+        });
+        let sample = sample_success_result();
+
+        let owner = coordinator.acquire("token-fail").await.unwrap();
+        assert_eq!(owner.role, LeaseRole::Owner);
+        owner.release(Some(&failed_result)).await.unwrap();
+
+        // A failure was NOT cached: the next caller acquires as owner.
+        let after_failure = coordinator.acquire("token-fail").await.unwrap();
+        assert_eq!(after_failure.role, LeaseRole::Owner);
+        assert_eq!(after_failure.result, None);
+        after_failure.release(Some(&sample)).await.unwrap();
+
+        // Happy path intact: a success IS served to a subsequent follower.
+        let follower = coordinator.acquire("token-fail").await.unwrap();
+        assert_eq!(follower.role, LeaseRole::Follower);
+        assert_eq!(follower.result, Some(sample));
+    }
+
+    #[tokio::test]
+    async fn recovers_from_stale_lock_payload() {
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(2_000),
+                wait_timeout_ms: Some(300),
+                poll_interval_ms: Some(20),
+                ..Default::default()
+            },
+        );
+
+        // Different tokenHash than "token-stale" would be token-mismatch; the
+        // TS test writes the REAL hash of a fixed value with an expired lease.
+        let token_hash = hash_refresh_token("token-stale");
+        std::fs::create_dir_all(dir.path()).unwrap();
+        std::fs::write(
+            dir.path().join(format!("{token_hash}.lock")),
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "pid": 9999,
+                "acquiredAt": now_ms() - 10_000,
+                "expiresAt": now_ms() - 1_000,
+            })),
+        )
+        .unwrap();
+
+        let handle = coordinator.acquire("token-stale").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Owner);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn supports_bypass_mode() {
+        let dir = temp_lease_dir();
+        let coordinator = RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(false),
+            lease_dir: Some(dir.path().to_path_buf()),
+            ..Default::default()
+        });
+        let handle = coordinator.acquire("token-b").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn does_not_delete_unreadable_lock_payloads() {
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(10_000),
+                wait_timeout_ms: Some(120),
+                poll_interval_ms: Some(25),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+        std::fs::create_dir_all(dir.path()).unwrap();
+        let token_hash = hash_refresh_token("token-partial");
+        let lock_path = dir.path().join(format!("{token_hash}.lock"));
+        std::fs::write(&lock_path, "{").unwrap();
+
+        let handle = coordinator.acquire("token-partial").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+        assert_eq!(std::fs::read_to_string(&lock_path).unwrap(), "{");
+    }
+
+    /// fsOps wrapper that fails `.lock` unlinks with EBUSY a fixed number of
+    /// times before delegating to the real fs.
+    struct BusyUnlinkFs {
+        inner: RealLeaseFs,
+        busy_count: AtomicU32,
+        max_busy: u32,
+        unlink_calls: AtomicU32,
+    }
+
+    impl LeaseFs for BusyUnlinkFs {
+        fn mkdir_recursive(&self, dir: &Path, mode: u32) -> io::Result<()> {
+            self.inner.mkdir_recursive(dir, mode)
+        }
+        fn chmod(&self, path: &Path, mode: u32) -> io::Result<()> {
+            self.inner.chmod(path, mode)
+        }
+        fn open_excl_write(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+            self.inner.open_excl_write(path, contents, mode)
+        }
+        fn write_file(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+            self.inner.write_file(path, contents, mode)
+        }
+        fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+            self.inner.rename(from, to)
+        }
+        fn unlink(&self, path: &Path) -> io::Result<()> {
+            self.unlink_calls.fetch_add(1, Ordering::SeqCst);
+            if path.to_string_lossy().ends_with(".lock")
+                && self.busy_count.load(Ordering::SeqCst) < self.max_busy
+            {
+                self.busy_count.fetch_add(1, Ordering::SeqCst);
+                return Err(cma_core::fs_retry::io_error_with_code("EBUSY", "busy"));
+            }
+            self.inner.unlink(path)
+        }
+        fn read_to_string(&self, path: &Path) -> io::Result<String> {
+            self.inner.read_to_string(path)
+        }
+        fn mtime_ms(&self, path: &Path) -> io::Result<f64> {
+            self.inner.mtime_ms(path)
+        }
+        fn read_dir_files(&self, dir: &Path) -> io::Result<Vec<String>> {
+            self.inner.read_dir_files(dir)
+        }
+    }
+
+    #[tokio::test]
+    async fn retries_stale_lock_cleanup_when_unlink_is_temporarily_busy() {
+        let dir = temp_lease_dir();
+        let token_hash = hash_refresh_token("token-retry");
+        let fs = Arc::new(BusyUnlinkFs {
+            inner: RealLeaseFs,
+            busy_count: AtomicU32::new(0),
+            max_busy: 2,
+            unlink_calls: AtomicU32::new(0),
+        });
+        let coordinator = RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.path().to_path_buf()),
+            lease_ttl_ms: Some(2_000),
+            wait_timeout_ms: Some(400),
+            poll_interval_ms: Some(20),
+            result_ttl_ms: Some(2_000),
+            fs_ops: Some(fs.clone()),
+        });
+
+        std::fs::create_dir_all(dir.path()).unwrap();
+        std::fs::write(
+            dir.path().join(format!("{token_hash}.lock")),
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "pid": 1111,
+                "acquiredAt": now_ms() - 10_000,
+                "expiresAt": now_ms() - 5_000,
+            })),
+        )
+        .unwrap();
+
+        let handle = coordinator.acquire("token-retry").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Owner);
+        assert!(fs.unlink_calls.load(Ordering::SeqCst) > 0);
+        assert_eq!(fs.busy_count.load(Ordering::SeqCst), 2);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn times_out_to_bypass_when_stale_lock_cannot_be_deleted() {
+        let dir = temp_lease_dir();
+        let token_hash = hash_refresh_token("token-timeout");
+        let fs = Arc::new(BusyUnlinkFs {
+            inner: RealLeaseFs,
+            busy_count: AtomicU32::new(0),
+            max_busy: u32::MAX, // .lock unlinks always fail EBUSY
+            unlink_calls: AtomicU32::new(0),
+        });
+        let coordinator = RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.path().to_path_buf()),
+            lease_ttl_ms: Some(2_000),
+            wait_timeout_ms: Some(140),
+            poll_interval_ms: Some(25),
+            result_ttl_ms: Some(2_000),
+            fs_ops: Some(fs.clone()),
+        });
+
+        std::fs::create_dir_all(dir.path()).unwrap();
+        std::fs::write(
+            dir.path().join(format!("{token_hash}.lock")),
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "pid": 2222,
+                "acquiredAt": now_ms() - 10_000,
+                "expiresAt": now_ms() - 5_000,
+            })),
+        )
+        .unwrap();
+
+        let handle = coordinator.acquire("token-timeout").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+        assert!(fs.unlink_calls.load(Ordering::SeqCst) > 0);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn treats_empty_refresh_token_as_bypass() {
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(dir.path(), RefreshLeaseCoordinatorOptions::default());
+        let handle = coordinator.acquire("   ").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn parses_environment_toggle_values_in_from_environment() {
+        let dir = temp_lease_dir();
+        let mut sandbox = cma_testkit::sandbox::EnvSandbox::new();
+
+        sandbox.set_var("VITEST", "false");
+        sandbox.set_var("NODE_ENV", "production");
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE", "yes");
+        sandbox.set_var(
+            "CODEX_AUTH_REFRESH_LEASE_DIR",
+            format!("{}\n", dir.path().to_string_lossy()),
+        );
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE_TTL_MS", "2500");
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE_WAIT_MS", "900");
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE_POLL_MS", "60");
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS", "2500");
+
+        let enabled_coordinator = RefreshLeaseCoordinator::from_environment();
+        assert_eq!(enabled_coordinator.configured_wait_timeout_ms(), 900);
+        let enabled_handle = enabled_coordinator.acquire("token-env-enabled").await.unwrap();
+        assert_eq!(enabled_handle.role, LeaseRole::Owner);
+        enabled_handle
+            .release(Some(&sample_success_result()))
+            .await
+            .unwrap();
+
+        sandbox.set_var("VITEST", "true");
+        sandbox.set_var("NODE_ENV", "test");
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE", "maybe");
+        let invalid_value_coordinator = RefreshLeaseCoordinator::from_environment();
+        let invalid_handle = invalid_value_coordinator
+            .acquire("token-env-invalid")
+            .await
+            .unwrap();
+        assert_eq!(invalid_handle.role, LeaseRole::Bypass);
+
+        sandbox.set_var("CODEX_AUTH_REFRESH_LEASE", "no");
+        let disabled_coordinator = RefreshLeaseCoordinator::from_environment();
+        let disabled_handle = disabled_coordinator
+            .acquire("token-env-disabled")
+            .await
+            .unwrap();
+        assert_eq!(disabled_handle.role, LeaseRole::Bypass);
+    }
+
+    /// fsOps whose exclusive open always fails EACCES.
+    struct OpenFailFs {
+        inner: RealLeaseFs,
+        open_calls: AtomicU32,
+    }
+
+    impl LeaseFs for OpenFailFs {
+        fn mkdir_recursive(&self, dir: &Path, mode: u32) -> io::Result<()> {
+            self.inner.mkdir_recursive(dir, mode)
+        }
+        fn chmod(&self, path: &Path, mode: u32) -> io::Result<()> {
+            self.inner.chmod(path, mode)
+        }
+        fn open_excl_write(&self, _path: &Path, _contents: &str, _mode: u32) -> io::Result<()> {
+            self.open_calls.fetch_add(1, Ordering::SeqCst);
+            Err(cma_core::fs_retry::io_error_with_code("EACCES", "permission"))
+        }
+        fn write_file(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+            self.inner.write_file(path, contents, mode)
+        }
+        fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+            self.inner.rename(from, to)
+        }
+        fn unlink(&self, path: &Path) -> io::Result<()> {
+            self.inner.unlink(path)
+        }
+        fn read_to_string(&self, path: &Path) -> io::Result<String> {
+            self.inner.read_to_string(path)
+        }
+        fn mtime_ms(&self, path: &Path) -> io::Result<f64> {
+            self.inner.mtime_ms(path)
+        }
+        fn read_dir_files(&self, dir: &Path) -> io::Result<Vec<String>> {
+            self.inner.read_dir_files(dir)
+        }
+    }
+
+    #[tokio::test]
+    async fn bypasses_when_lock_open_fails_with_non_eexist_error() {
+        let dir = temp_lease_dir();
+        let fs = Arc::new(OpenFailFs {
+            inner: RealLeaseFs,
+            open_calls: AtomicU32::new(0),
+        });
+        let coordinator = RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.path().to_path_buf()),
+            wait_timeout_ms: Some(80),
+            poll_interval_ms: Some(20),
+            fs_ops: Some(fs.clone()),
+            ..Default::default()
+        });
+
+        let handle = coordinator.acquire("token-open-error").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+        assert!(fs.open_calls.load(Ordering::SeqCst) > 0);
+    }
+
+    #[tokio::test]
+    async fn ignores_mismatched_result_payload_and_stale_results() {
+        let dir = temp_lease_dir();
+        let token_hash = hash_refresh_token("token-result-paths");
+        let result_path = dir.path().join(format!("{token_hash}.result.json"));
+        std::fs::create_dir_all(dir.path()).unwrap();
+        std::fs::write(
+            &result_path,
+            stringify_compact(&json!({
+                "tokenHash": "different-hash",
+                "createdAt": now_ms(),
+                "result": sample_success_result(),
+            })),
+        )
+        .unwrap();
+
+        let c1 = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                wait_timeout_ms: Some(120),
+                poll_interval_ms: Some(20),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+        let handle = c1.acquire("token-result-paths").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Owner);
+        handle.release(None).await.unwrap();
+
+        std::fs::write(
+            &result_path,
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "createdAt": now_ms() - 10_000,
+                "result": sample_success_result(),
+            })),
+        )
+        .unwrap();
+
+        let c2 = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                wait_timeout_ms: Some(120),
+                poll_interval_ms: Some(20),
+                result_ttl_ms: Some(500),
+                ..Default::default()
+            },
+        );
+        let handle = c2.acquire("token-result-paths").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Owner);
+        handle.release(None).await.unwrap();
+        // The stale result was unlinked while reading.
+        assert!(!result_path.exists());
+    }
+
+    /// fsOps whose stat of the lock path fails EACCES.
+    struct StatEaccesFs {
+        inner: RealLeaseFs,
+        lock_path: PathBuf,
+    }
+
+    impl LeaseFs for StatEaccesFs {
+        fn mkdir_recursive(&self, dir: &Path, mode: u32) -> io::Result<()> {
+            self.inner.mkdir_recursive(dir, mode)
+        }
+        fn chmod(&self, path: &Path, mode: u32) -> io::Result<()> {
+            self.inner.chmod(path, mode)
+        }
+        fn open_excl_write(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+            self.inner.open_excl_write(path, contents, mode)
+        }
+        fn write_file(&self, path: &Path, contents: &str, mode: u32) -> io::Result<()> {
+            self.inner.write_file(path, contents, mode)
+        }
+        fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+            self.inner.rename(from, to)
+        }
+        fn unlink(&self, path: &Path) -> io::Result<()> {
+            self.inner.unlink(path)
+        }
+        fn read_to_string(&self, path: &Path) -> io::Result<String> {
+            self.inner.read_to_string(path)
+        }
+        fn mtime_ms(&self, path: &Path) -> io::Result<f64> {
+            if path == self.lock_path {
+                return Err(cma_core::fs_retry::io_error_with_code(
+                    "EACCES",
+                    "access denied",
+                ));
+            }
+            self.inner.mtime_ms(path)
+        }
+        fn read_dir_files(&self, dir: &Path) -> io::Result<Vec<String>> {
+            self.inner.read_dir_files(dir)
+        }
+    }
+
+    #[tokio::test]
+    async fn handles_lock_staleness_edge_cases_from_stat_and_payload_validation() {
+        let dir = temp_lease_dir();
+        let token_hash = hash_refresh_token("token-staleness-cases");
+        let lock_path = dir.path().join(format!("{token_hash}.lock"));
+        std::fs::create_dir_all(dir.path()).unwrap();
+
+        // Invalid payload (pid: "bad") ⇒ unknown ⇒ never stolen ⇒ bypass.
+        std::fs::write(
+            &lock_path,
+            stringify_compact(&json!({ "tokenHash": token_hash, "pid": "bad" })),
+        )
+        .unwrap();
+        let c1 = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(2_000),
+                wait_timeout_ms: Some(120),
+                poll_interval_ms: Some(20),
+                ..Default::default()
+            },
+        );
+        let handle = c1.acquire("token-staleness-cases").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+
+        // Fresh expiresAt but ancient mtime ⇒ mtime-expired ⇒ stolen ⇒ owner.
+        std::fs::write(
+            &lock_path,
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "pid": std::process::id(),
+                "acquiredAt": now_ms(),
+                "expiresAt": now_ms() + 5_000,
+            })),
+        )
+        .unwrap();
+        set_file_mtime_secs_ago(&lock_path, 10);
+        let c2 = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(1_000),
+                wait_timeout_ms: Some(160),
+                poll_interval_ms: Some(20),
+                ..Default::default()
+            },
+        );
+        let handle = c2.acquire("token-staleness-cases").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Owner);
+        handle.release(Some(&sample_success_result())).await.unwrap();
+        let _ = std::fs::remove_file(dir.path().join(format!("{token_hash}.result.json")));
+
+        // stat EACCES ⇒ unknown ⇒ bypass after the wait budget.
+        std::fs::write(
+            &lock_path,
+            stringify_compact(&json!({
+                "tokenHash": token_hash,
+                "pid": std::process::id(),
+                "acquiredAt": now_ms(),
+                "expiresAt": now_ms() + 5_000,
+            })),
+        )
+        .unwrap();
+        let fs = Arc::new(StatEaccesFs {
+            inner: RealLeaseFs,
+            lock_path: lock_path.clone(),
+        });
+        let c3 = RefreshLeaseCoordinator::new(RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.path().to_path_buf()),
+            lease_ttl_ms: Some(5_000),
+            wait_timeout_ms: Some(120),
+            poll_interval_ms: Some(20),
+            fs_ops: Some(fs),
+            ..Default::default()
+        });
+        let handle = c3.acquire("token-staleness-cases").await.unwrap();
+        assert_eq!(handle.role, LeaseRole::Bypass);
+    }
+
+    #[tokio::test]
+    async fn rejects_array_json_payloads_in_result_and_lock_files() {
+        // Pins the canonical isRecord contract: a top-level JSON array must
+        // never be treated as a lease or result record.
+        let dir = temp_lease_dir();
+        let token_hash = hash_refresh_token("token-array-payload");
+        let lock_path = dir.path().join(format!("{token_hash}.lock"));
+        let result_path = dir.path().join(format!("{token_hash}.result.json"));
+        std::fs::create_dir_all(dir.path()).unwrap();
+
+        // An array result file must not turn the caller into a follower.
+        std::fs::write(&result_path, "[]\n").unwrap();
+        let c = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(2_000),
+                wait_timeout_ms: Some(120),
+                poll_interval_ms: Some(20),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+        let owner = c.acquire("token-array-payload").await.unwrap();
+        assert_eq!(owner.role, LeaseRole::Owner);
+        owner.release(None).await.unwrap();
+
+        // An array lock file is an invalid payload: never owned, never stale,
+        // so the acquire times out and bypasses instead of stealing the lock.
+        std::fs::write(&lock_path, "[]\n").unwrap();
+        let blocked = c.acquire("token-array-payload").await.unwrap();
+        assert_eq!(blocked.role, LeaseRole::Bypass);
+        blocked.release(None).await.unwrap();
+        assert_eq!(std::fs::read_to_string(&lock_path).unwrap(), "[]\n");
+    }
+
+    fn set_file_mtime_secs_ago(path: &Path, secs_ago: u64) {
+        // No utimes in std: rewrite the mtime via filetime-free fallback —
+        // sleep-based aging is too slow, so use the OS-level API through
+        // `std::fs::File::set_times` (stable since 1.75).
+        let file = std::fs::OpenOptions::new().append(true).open(path).unwrap();
+        let target = std::time::SystemTime::now() - std::time::Duration::from_secs(secs_ago);
+        let times = std::fs::FileTimes::new()
+            .set_accessed(target)
+            .set_modified(target);
+        file.set_times(times).unwrap();
+    }
+
+    #[tokio::test]
+    async fn prunes_stale_artifacts_while_keeping_non_file_entries() {
+        let dir = temp_lease_dir();
+        std::fs::create_dir_all(dir.path()).unwrap();
+        let stale_lock = dir.path().join("stale.lock");
+        let stale_result = dir.path().join("stale.result.json");
+        let live_other = dir.path().join("ignore.txt");
+        let nested_dir = dir.path().join("nested-dir");
+        std::fs::write(&stale_lock, "{}").unwrap();
+        std::fs::write(&stale_result, "{}").unwrap();
+        std::fs::write(&live_other, "keep").unwrap();
+        std::fs::create_dir_all(&nested_dir).unwrap();
+        set_file_mtime_secs_ago(&stale_lock, 60);
+        set_file_mtime_secs_ago(&stale_result, 60);
+
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(2_000),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+        coordinator.prune_expired_artifacts().await;
+
+        assert!(!stale_lock.exists());
+        assert!(!stale_result.exists());
+        assert_eq!(std::fs::read_to_string(&live_other).unwrap(), "keep");
+        assert!(nested_dir.is_dir());
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn creates_lease_dir_0700_and_token_result_lock_files_0600() {
+        use std::os::unix::fs::MetadataExt;
+        let dir = temp_lease_dir();
+        let own_lease_dir = dir.path().join("perm-check");
+        let coordinator = coordinator(
+            &own_lease_dir,
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(5_000),
+                wait_timeout_ms: Some(500),
+                poll_interval_ms: Some(25),
+                result_ttl_ms: Some(5_000),
+                ..Default::default()
+            },
+        );
+
+        let owner = coordinator.acquire("token-perms").await.unwrap();
+        assert_eq!(owner.role, LeaseRole::Owner);
+
+        let token_hash = hash_refresh_token("token-perms");
+        let lock_path = own_lease_dir.join(format!("{token_hash}.lock"));
+        let result_path = own_lease_dir.join(format!("{token_hash}.result.json"));
+
+        assert_eq!(std::fs::metadata(&own_lease_dir).unwrap().mode() & 0o777, 0o700);
+        assert_eq!(std::fs::metadata(&lock_path).unwrap().mode() & 0o777, 0o600);
+
+        owner.release(Some(&sample_success_result())).await.unwrap();
+
+        assert_eq!(std::fs::metadata(&result_path).unwrap().mode() & 0o777, 0o600);
+    }
+
+    #[tokio::test]
+    async fn h2_slow_owner_release_does_not_delete_a_stolen_lock() {
+        // Owner A acquires with a very short TTL; its lease expires; owner B
+        // steals the lock. When A finally releases, it must NOT unlink B's
+        // lock (stress audit H2).
+        let dir = temp_lease_dir();
+        let coordinator = coordinator(
+            dir.path(),
+            RefreshLeaseCoordinatorOptions {
+                lease_ttl_ms: Some(1_000), // clamp floor; TS used 30 but 1_000 is the min
+                wait_timeout_ms: Some(4_000),
+                poll_interval_ms: Some(50),
+                result_ttl_ms: Some(2_000),
+                ..Default::default()
+            },
+        );
+
+        let owner_a = coordinator.acquire("token-steal").await.unwrap();
+        assert_eq!(owner_a.role, LeaseRole::Owner);
+
+        // Let A's lease go stale (both expiresAt and mtime), then B steals it.
+        let token_hash = hash_refresh_token("token-steal");
+        let lock_path = dir.path().join(format!("{token_hash}.lock"));
+        // Age the lock artificially instead of sleeping past the 1 s TTL:
+        // rewrite expiresAt into the past (keeping A's nonce) + age the mtime.
+        let payload: Value =
+            serde_json::from_str(&std::fs::read_to_string(&lock_path).unwrap()).unwrap();
+        let mut aged = payload.clone();
+        aged["acquiredAt"] = json!(now_ms() - 10_000);
+        aged["expiresAt"] = json!(now_ms() - 5_000);
+        std::fs::write(&lock_path, format!("{}\n", stringify_compact(&aged))).unwrap();
+        set_file_mtime_secs_ago(&lock_path, 10);
+
+        let owner_b = coordinator.acquire("token-steal").await.unwrap();
+        assert_eq!(owner_b.role, LeaseRole::Owner);
+
+        let b_payload: Value =
+            serde_json::from_str(&std::fs::read_to_string(&lock_path).unwrap()).unwrap();
+
+        // A releases late — must leave B's lock intact.
+        owner_a.release(Some(&sample_success_result())).await.unwrap();
+
+        let after_payload: Value =
+            serde_json::from_str(&std::fs::read_to_string(&lock_path).unwrap()).unwrap();
+        assert_eq!(after_payload["nonce"], b_payload["nonce"]);
+        assert_ne!(after_payload["nonce"], payload["nonce"]);
+    }
+
+    #[test]
+    fn parse_env_int_matches_js_parse_int() {
+        assert_eq!(parse_env_int(None), None);
+        assert_eq!(parse_env_int(Some("2500")), Some(2500));
+        assert_eq!(parse_env_int(Some(" 900 ")), Some(900));
+        assert_eq!(parse_env_int(Some("60x")), Some(60));
+        assert_eq!(parse_env_int(Some("-15")), Some(-15));
+        assert_eq!(parse_env_int(Some("+15")), Some(15));
+        assert_eq!(parse_env_int(Some("abc")), None);
+        assert_eq!(parse_env_int(Some("")), None);
+    }
+}
diff --git a/crates/auth/src/refresh_queue.rs b/crates/auth/src/refresh_queue.rs
new file mode 100644
index 000000000..4f53e10b0
--- /dev/null
+++ b/crates/auth/src/refresh_queue.rs
@@ -0,0 +1,1933 @@
+//! Port of `lib/refresh-queue.ts` — in-process refresh dedup.
+//!
+//! Behavior source: specs/04-rotation.md §6.
+//!
+//! Prevents race conditions when multiple concurrent requests try to refresh
+//! the same account's token simultaneously: subsequent callers await the
+//! existing in-flight refresh (a [`futures::future::Shared`] here, standing in
+//! for the shared TS promise). The body is `tokio::spawn`ed — the Rust
+//! equivalent of the TS eagerly-executing async IIFE: it ALWAYS runs to
+//! completion even when every awaiter is dropped (e.g. a client disconnect
+//! drops the request future mid-refresh), so an in-flight OAuth exchange is
+//! never suspended after the POST was sent (which would burn the rotated
+//! refresh token) and the pending-entry cleanup always runs (a lazily polled
+//! future would wedge the token's refresh lane forever — refresh-stage
+//! entries are deliberately never evicted).
+//!
+//! Token-rotation handling: when OpenAI rotates the refresh token during a
+//! refresh, a mapping `oldToken → newToken` lets requests arriving with either
+//! token find the same in-flight refresh. Generation counters guard against a
+//! stale evicted attempt racing a newer one (supersession: the stale attempt
+//! joins the newer generation's future instead of double-refreshing).
+
+use std::collections::HashMap;
+use std::io;
+use std::sync::{Arc, LazyLock, Mutex as StdMutex, MutexGuard};
+use std::time::Duration;
+
+use futures::FutureExt;
+use futures::future::{BoxFuture, Shared};
+use serde_json::json;
+use sha2::{Digest, Sha256};
+
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult};
+use cma_core::utils::now_ms;
+
+use crate::refresh_lease::{
+    DEFAULT_WAIT_TIMEOUT_MS, LeaseRole, RefreshLeaseCoordinator, RefreshLeaseHandle,
+};
+
+fn log() -> ScopedLogger {
+    create_logger("refresh-queue")
+}
+
+/// Extra headroom beyond the lease wait budget before an acquire-stage entry
+/// is treated as genuinely stuck (a lease `acquire()` polls on an interval and
+/// does filesystem work, so it can overshoot its wait deadline slightly).
+const ACQUIRE_EVICTION_SLACK_MS: i64 = 5_000;
+
+/// Non-reversible correlation fingerprint for a token, for logs.
+///
+/// Logging trailing characters of a refresh token (`token.slice(-6)`) would
+/// leak recoverable secret material into 0600 log files; a short SHA-256
+/// prefix gives the same cross-log correlation without exposing the token.
+fn token_fingerprint(token: &str) -> String {
+    if token.is_empty() {
+        return "none".to_string();
+    }
+    let digest = Sha256::digest(token.as_bytes());
+    let mut out = String::with_capacity(8);
+    for byte in digest.iter().take(4) {
+        use std::fmt::Write;
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+/// Coordinator seam the queue depends on (implemented by
+/// [`RefreshLeaseCoordinator`]; test doubles model throwing/never-resolving
+/// acquires).
+pub trait LeaseCoordinatorApi: Send + Sync {
+    fn acquire<'a>(
+        &'a self,
+        refresh_token: &'a str,
+    ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>>;
+    /// The wait budget the coordinator was ACTUALLY configured with; `None`
+    /// models a test double without the getter (falls back to
+    /// [`DEFAULT_WAIT_TIMEOUT_MS`]).
+    fn configured_wait_timeout_ms(&self) -> Option<i64>;
+}
+
+impl LeaseCoordinatorApi for RefreshLeaseCoordinator {
+    fn acquire<'a>(
+        &'a self,
+        refresh_token: &'a str,
+    ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+        RefreshLeaseCoordinator::acquire(self, refresh_token).boxed()
+    }
+
+    fn configured_wait_timeout_ms(&self) -> Option<i64> {
+        Some(RefreshLeaseCoordinator::configured_wait_timeout_ms(self))
+    }
+}
+
+/// Error surface of the refresh executor, mirroring the TS `refreshAccessToken`
+/// throw paths: `is_abort` maps `isAbortError` (name `AbortError` / code
+/// `ABORT_ERR`); everything else is treated as a network-class exception.
+#[derive(Clone, Debug)]
+pub struct RefreshExecError {
+    pub message: Option<String>,
+    pub is_abort: bool,
+}
+
+/// The actual token-refresh call (`refreshAccessToken` in TS). Injectable for
+/// tests; the default calls `crate::oauth::refresh_access_token`.
+pub type RefreshExecutor =
+    Arc<dyn Fn(String) -> BoxFuture<'static, Result<TokenResult, RefreshExecError>> + Send + Sync>;
+
+fn default_refresh_executor() -> RefreshExecutor {
+    Arc::new(|token: String| async move { Ok(default_refresh(token).await) }.boxed())
+}
+
+/// Production path: delegate to the OAuth module's `refresh_access_token`
+/// (which never throws — failures come back as `TokenResult::Failed`). The
+/// abort/timeout race lives in [`execute_refresh`] via `tokio::time::timeout`,
+/// replacing the TS AbortController.
+#[cfg(not(test))]
+async fn default_refresh(token: String) -> TokenResult {
+    crate::oauth::refresh_access_token(&token).await
+}
+
+/// Unit tests always inject an executor via [`RefreshQueue::with_parts`]; this
+/// stub keeps the test build compiling independently of the oauth module.
+#[cfg(test)]
+async fn default_refresh(_token: String) -> TokenResult {
+    unreachable!("tests must inject a refresh executor via RefreshQueue::with_parts")
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum Stage {
+    Acquire,
+    Refresh,
+}
+
+type SharedRefresh = Shared<BoxFuture<'static, TokenResult>>;
+
+/// Entry representing an in-flight token refresh operation.
+struct RefreshEntry {
+    future: SharedRefresh,
+    started_at: i64,
+    stage: Stage,
+    generation: u64,
+    stale_warning_logged: bool,
+}
+
+struct QueueState {
+    pending: HashMap<String, RefreshEntry>,
+    /// `oldToken → newToken` after rotation, insertion-ordered (TS Map).
+    token_rotation_map: Vec<(String, String)>,
+    next_generation: u64,
+}
+
+struct QueueInner {
+    max_entry_age_ms: i64,
+    coordinator: Arc<dyn LeaseCoordinatorApi>,
+    executor: RefreshExecutor,
+    state: StdMutex<QueueState>,
+}
+
+impl QueueInner {
+    fn lock(&self) -> MutexGuard<'_, QueueState> {
+        self.state.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+}
+
+/// `RefreshQueue` — cheaply cloneable handle over the shared queue state.
+#[derive(Clone)]
+pub struct RefreshQueue {
+    inner: Arc<QueueInner>,
+}
+
+impl RefreshQueue {
+    /// `new RefreshQueue(maxEntryAgeMs = 30_000)` with the environment lease
+    /// coordinator and the real refresh executor.
+    pub fn new(max_entry_age_ms: Option<i64>) -> Self {
+        Self::with_parts(
+            max_entry_age_ms.unwrap_or(30_000),
+            Arc::new(RefreshLeaseCoordinator::from_environment()),
+            default_refresh_executor(),
+        )
+    }
+
+    /// `new RefreshQueue(maxEntryAgeMs, leaseCoordinator)`.
+    pub fn with_coordinator(
+        max_entry_age_ms: i64,
+        coordinator: Arc<dyn LeaseCoordinatorApi>,
+    ) -> Self {
+        Self::with_parts(max_entry_age_ms, coordinator, default_refresh_executor())
+    }
+
+    /// Full-injection constructor (tests).
+    pub fn with_parts(
+        max_entry_age_ms: i64,
+        coordinator: Arc<dyn LeaseCoordinatorApi>,
+        executor: RefreshExecutor,
+    ) -> Self {
+        Self {
+            inner: Arc::new(QueueInner {
+                max_entry_age_ms,
+                coordinator,
+                executor,
+                state: StdMutex::new(QueueState {
+                    pending: HashMap::new(),
+                    token_rotation_map: Vec::new(),
+                    next_generation: 0,
+                }),
+            }),
+        }
+    }
+
+    /// `refresh(refreshToken)` — dedupes concurrent requests for the same
+    /// refresh token; all concurrent callers get the same result.
+    pub async fn refresh(&self, refresh_token: &str) -> TokenResult {
+        let token = refresh_token.to_string();
+        let future: SharedRefresh = {
+            let mut state = self.inner.lock();
+            cleanup(&self.inner, &mut state);
+
+            // Direct match on an existing in-flight refresh.
+            if let Some(existing) = state.pending.get(&token) {
+                log().info(
+                    "Reusing in-flight refresh for token",
+                    Some(&json!({
+                        "tokenSuffix": token_fingerprint(&token),
+                        "waitingMs": now_ms() - existing.started_at,
+                    })),
+                );
+                existing.future.clone()
+            } else if let Some(rotated_from) = find_original_token(&state, &token)
+                && let Some(original_entry) = state.pending.get(&rotated_from)
+            {
+                // This token was rotated FROM another token that is still
+                // refreshing (request A got newToken while its refresh of
+                // oldToken is in flight; request B arrives with newToken).
+                log().info(
+                    "Reusing in-flight refresh via rotation mapping",
+                    Some(&json!({
+                        "newTokenSuffix": token_fingerprint(&token),
+                        "originalTokenSuffix": token_fingerprint(&rotated_from),
+                        "waitingMs": now_ms() - original_entry.started_at,
+                    })),
+                );
+                original_entry.future.clone()
+            } else {
+                // Start a new refresh immediately so local state reflects
+                // "in-flight" without waiting on cross-process lease checks.
+                state.next_generation += 1;
+                let generation = state.next_generation;
+                let started_at = now_ms();
+                // Eager execution (TS async-IIFE parity, refresh-queue.ts:172):
+                // the body is `tokio::spawn`ed so it ALWAYS runs to completion
+                // even when every awaiter is dropped (e.g. a client disconnect
+                // drops the creating request mid-refresh). A lazily polled
+                // Shared future would (1) suspend an already-sent OAuth POST —
+                // OpenAI rotates the refresh token server-side, so the stored
+                // token is burned and the next refresh gets invalid_grant —
+                // and (2) never run the `finally` cleanup below, wedging this
+                // token's refresh lane on a stale cached failure forever
+                // (refresh-stage entries are deliberately never evicted).
+                let body = {
+                    let inner = Arc::clone(&self.inner);
+                    let token = token.clone();
+                    async move {
+                        let result =
+                            run_refresh_body(Arc::clone(&inner), token.clone(), generation).await;
+                        // TS `finally` (refresh-queue.ts:229-237), moved into
+                        // the spawned wrapper so it runs even when the
+                        // creating caller died: delete the pending entry only
+                        // if it is still our generation (or absent), and
+                        // clean the rotation mapping.
+                        let mut state = inner.lock();
+                        let still_ours = state
+                            .pending
+                            .get(&token)
+                            .is_none_or(|entry| entry.generation == generation);
+                        if still_ours {
+                            state.pending.remove(&token);
+                            cleanup_rotation_mapping(&mut state, &token);
+                        }
+                        result
+                    }
+                };
+                let future: SharedRefresh = tokio::spawn(body)
+                    .map(|joined| {
+                        joined.unwrap_or_else(|join_error| {
+                            TokenResult::Failed(TokenFailure {
+                                reason: Some(TokenFailureReason::Unknown),
+                                status_code: None,
+                                message: Some(format!("Refresh task failed: {join_error}")),
+                            })
+                        })
+                    })
+                    .boxed()
+                    .shared();
+                state.pending.insert(
+                    token.clone(),
+                    RefreshEntry {
+                        future: future.clone(),
+                        started_at,
+                        stage: Stage::Acquire,
+                        generation,
+                        stale_warning_logged: false,
+                    },
+                );
+                future
+            }
+        };
+        future.await
+    }
+
+    /// `isRefreshing(token)` — true while a refresh is in flight.
+    pub fn is_refreshing(&self, refresh_token: &str) -> bool {
+        self.inner.lock().pending.contains_key(refresh_token)
+    }
+
+    /// `pendingCount` — number of pending refresh operations.
+    pub fn pending_count(&self) -> usize {
+        self.inner.lock().pending.len()
+    }
+
+    /// `clear()` — pending entries + rotation map (primarily for testing).
+    pub fn clear(&self) {
+        let mut state = self.inner.lock();
+        state.pending.clear();
+        state.token_rotation_map.clear();
+    }
+}
+
+/// `findOriginalToken(newToken)` — first rotation-map entry whose VALUE equals
+/// the new token (insertion order).
+fn find_original_token(state: &QueueState, new_token: &str) -> Option<String> {
+    state
+        .token_rotation_map
+        .iter()
+        .find(|(_, mapped_new)| mapped_new == new_token)
+        .map(|(old, _)| old.clone())
+}
+
+/// `cleanupRotationMapping(token)` — removes `token` as an old-token key AND
+/// any mapping whose value equals `token`.
+fn cleanup_rotation_mapping(state: &mut QueueState, token: &str) {
+    state
+        .token_rotation_map
+        .retain(|(old, new)| old != token && new != token);
+}
+
+/// `markStage(stage)` — only mutates the entry if its generation still equals
+/// ours; resets `startedAt` so each stage gets its own age budget.
+fn mark_stage(inner: &QueueInner, token: &str, generation: u64, stage: Stage) {
+    let mut state = inner.lock();
+    let Some(entry) = state.pending.get_mut(token) else {
+        return;
+    };
+    if entry.generation != generation {
+        return;
+    }
+    entry.stage = stage;
+    entry.started_at = now_ms();
+    entry.stale_warning_logged = false;
+}
+
+/// `getSupersedingPromise` — when a NEWER generation replaced our map entry,
+/// join its future instead of double-refreshing.
+fn superseding_future(inner: &QueueInner, token: &str, generation: u64) -> Option<SharedRefresh> {
+    let state = inner.lock();
+    let current = state.pending.get(token)?;
+    if current.generation == generation {
+        return None;
+    }
+    log().info(
+        "Refresh generation superseded; joining newer in-flight refresh",
+        Some(&json!({
+            "tokenSuffix": token_fingerprint(token),
+            "staleGeneration": generation,
+            "activeGeneration": current.generation,
+        })),
+    );
+    Some(current.future.clone())
+}
+
+/// The per-generation async body (the TS async IIFE).
+async fn run_refresh_body(inner: Arc<QueueInner>, token: String, generation: u64) -> TokenResult {
+    let lease = match inner.coordinator.acquire(&token).await {
+        Ok(lease) => lease,
+        Err(error) => {
+            log().warn(
+                "Refresh lease acquire failed; falling back to local refresh",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(&token),
+                    "error": error.to_string(),
+                })),
+            );
+            if let Some(superseding) = superseding_future(&inner, &token, generation) {
+                return superseding.await;
+            }
+            mark_stage(&inner, &token, generation, Stage::Refresh);
+            return execute_refresh_with_rotation_tracking(&inner, &token).await;
+        }
+    };
+    if lease.role == LeaseRole::Follower
+        && let Some(result) = lease.result.clone()
+    {
+        log().info(
+            "Using refresh result from cross-process lease",
+            Some(&json!({ "tokenSuffix": token_fingerprint(&token) })),
+        );
+        return result;
+    }
+
+    // try
+    if let Some(superseding) = superseding_future(&inner, &token, generation) {
+        // TS `return supersedingPromise;` triggers the
+        // `finally { await lease.release(); }` BEFORE the async function's
+        // promise adopts the returned promise (finally-before-adoption), so
+        // the on-disk lock is unlinked BEFORE the newer generation's refresh
+        // runs. Releasing only after `superseding.await` would hold the
+        // freshly-acquired Active lock for the whole superseding refresh —
+        // the successor's `acquire` would poll it until its wait budget
+        // (default 35 s) expires and then BYPASS, refreshing without
+        // cross-process single-flight protection.
+        release_lease_quietly(&lease, &token).await;
+        return superseding.await;
+    }
+    mark_stage(&inner, &token, generation, Stage::Refresh);
+    let outcome = execute_refresh_with_rotation_tracking(&inner, &token).await;
+    // Publish the success to cross-process followers; publish errors are
+    // warn-only.
+    if let Err(error) = lease.release(Some(&outcome)).await {
+        log().warn(
+            "Failed to publish lease refresh result",
+            Some(&json!({
+                "tokenSuffix": token_fingerprint(&token),
+                "error": error.to_string(),
+            })),
+        );
+    }
+    // finally: idempotent unlock; errors warn-only.
+    release_lease_quietly(&lease, &token).await;
+    outcome
+}
+
+/// The TS `finally { await lease.release(); }` — idempotent unlock with
+/// warn-only error handling.
+async fn release_lease_quietly(lease: &RefreshLeaseHandle, token: &str) {
+    if let Err(error) = lease.release(None).await {
+        log().warn(
+            "Failed to release refresh lease",
+            Some(&json!({
+                "tokenSuffix": token_fingerprint(token),
+                "error": error.to_string(),
+            })),
+        );
+    }
+}
+
+/// `executeRefreshWithRotationTracking` — record `old → new` after a rotating
+/// success so lookups with either token find the same entry.
+async fn execute_refresh_with_rotation_tracking(
+    inner: &Arc<QueueInner>,
+    refresh_token: &str,
+) -> TokenResult {
+    let result = execute_refresh(inner, refresh_token).await;
+
+    if let TokenResult::Success(success) = &result
+        && success.refresh != refresh_token
+    {
+        {
+            let mut state = inner.lock();
+            // Map.set semantics: replace the value when the key exists.
+            if let Some(entry) = state
+                .token_rotation_map
+                .iter_mut()
+                .find(|(old, _)| old == refresh_token)
+            {
+                entry.1 = success.refresh.clone();
+            } else {
+                state
+                    .token_rotation_map
+                    .push((refresh_token.to_string(), success.refresh.clone()));
+            }
+        }
+        log().info(
+            "Token rotated during refresh",
+            Some(&json!({
+                "oldTokenSuffix": token_fingerprint(refresh_token),
+                "newTokenSuffix": token_fingerprint(&success.refresh),
+            })),
+        );
+    }
+
+    result
+}
+
+/// `executeRefresh` — the actual refresh call raced against a
+/// `max(1_000, maxEntryAgeMs)` timeout. **Never throws**: aborts/timeouts map
+/// to `failed/unknown`, other exceptions to `failed/network_error`.
+async fn execute_refresh(inner: &Arc<QueueInner>, refresh_token: &str) -> TokenResult {
+    let start_time = now_ms();
+    log().info(
+        "Starting token refresh",
+        Some(&json!({ "tokenSuffix": token_fingerprint(refresh_token) })),
+    );
+    let timeout_ms = inner.max_entry_age_ms.max(1_000);
+
+    let refresh_future = (inner.executor)(refresh_token.to_string());
+    let raced =
+        tokio::time::timeout(Duration::from_millis(timeout_ms as u64), refresh_future).await;
+    let duration = now_ms() - start_time;
+
+    match raced {
+        Ok(Ok(result)) => {
+            match &result {
+                TokenResult::Success(_) => log().info(
+                    "Token refresh succeeded",
+                    Some(&json!({
+                        "tokenSuffix": token_fingerprint(refresh_token),
+                        "durationMs": duration,
+                    })),
+                ),
+                TokenResult::Failed(failure) => log().warn(
+                    "Token refresh failed",
+                    Some(&json!({
+                        "tokenSuffix": token_fingerprint(refresh_token),
+                        "reason": failure.reason.map(|reason| reason.as_str()),
+                        "durationMs": duration,
+                    })),
+                ),
+            }
+            result
+        }
+        Ok(Err(error)) if error.is_abort => {
+            log().warn(
+                "Token refresh aborted",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(refresh_token),
+                    "error": error.message.clone(),
+                    "durationMs": duration,
+                })),
+            );
+            TokenResult::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::Unknown),
+                status_code: None,
+                message: Some(error.message.unwrap_or_else(|| "Refresh aborted".to_string())),
+            })
+        }
+        Ok(Err(error)) => {
+            log().error(
+                "Token refresh threw exception",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(refresh_token),
+                    "error": error.message.clone(),
+                    "durationMs": duration,
+                })),
+            );
+            TokenResult::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::NetworkError),
+                status_code: None,
+                message: Some(
+                    error
+                        .message
+                        .unwrap_or_else(|| "Unknown error during refresh".to_string()),
+                ),
+            })
+        }
+        Err(_elapsed) => {
+            // The TS timeout path rejects with an AbortError carrying this
+            // exact message; isAbortError routes it to reason "unknown"
+            // (deliberately NOT "timeout").
+            let message = format!("Refresh timeout after {timeout_ms}ms");
+            log().warn(
+                "Token refresh aborted",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(refresh_token),
+                    "error": message,
+                    "durationMs": duration,
+                })),
+            );
+            TokenResult::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::Unknown),
+                status_code: None,
+                message: Some(message),
+            })
+        }
+    }
+}
+
+/// `cleanup()` — evict genuinely-stuck acquire-stage entries; warn ONCE for
+/// stale refresh-stage entries (never evicted — a duplicate refresh against a
+/// token OpenAI already rotated would hit `invalid_grant`).
+fn cleanup(inner: &QueueInner, state: &mut QueueState) {
+    let now = now_ms();
+    // Read the budget the coordinator was actually CONFIGURED with (constructor
+    // option / CODEX_AUTH_REFRESH_LEASE_WAIT_MS) rather than the static
+    // default: under a larger configured budget the default would evict too
+    // early. A test double without the getter falls back to the default.
+    let lease_wait_timeout_ms = inner
+        .coordinator
+        .configured_wait_timeout_ms()
+        .unwrap_or(DEFAULT_WAIT_TIMEOUT_MS);
+    let acquire_eviction_age_ms = inner
+        .max_entry_age_ms
+        .max(lease_wait_timeout_ms + ACQUIRE_EVICTION_SLACK_MS);
+
+    let mut evicted: Vec<String> = Vec::new();
+    for (token, entry) in state.pending.iter_mut() {
+        let age_ms = now - entry.started_at;
+        if entry.stage == Stage::Acquire {
+            if age_ms <= acquire_eviction_age_ms {
+                continue;
+            }
+            log().warn(
+                "Evicting stale refresh entry during lease acquire stage",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(token),
+                    "ageMs": age_ms,
+                })),
+            );
+            evicted.push(token.clone());
+            continue;
+        }
+        if age_ms <= inner.max_entry_age_ms {
+            continue;
+        }
+        if !entry.stale_warning_logged {
+            log().warn(
+                "Refresh entry exceeded stale warning threshold",
+                Some(&json!({
+                    "tokenSuffix": token_fingerprint(token),
+                    "ageMs": age_ms,
+                })),
+            );
+            entry.stale_warning_logged = true;
+        }
+    }
+    for token in evicted {
+        state.pending.remove(&token);
+        cleanup_rotation_mapping(state, &token);
+    }
+}
+
+// ============================================================================
+// Singleton
+// ============================================================================
+
+static REFRESH_QUEUE_SINGLETON: LazyLock<StdMutex<Option<RefreshQueue>>> =
+    LazyLock::new(|| StdMutex::new(None));
+
+/// `getRefreshQueue(maxEntryAgeMs?)` — lazy singleton; the argument is honored
+/// only on first call.
+pub fn get_refresh_queue(max_entry_age_ms: Option<i64>) -> RefreshQueue {
+    let mut slot = REFRESH_QUEUE_SINGLETON
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    slot.get_or_insert_with(|| RefreshQueue::new(max_entry_age_ms))
+        .clone()
+}
+
+/// `resetRefreshQueue()` — `clear()` then drop the singleton.
+pub fn reset_refresh_queue() {
+    let mut slot = REFRESH_QUEUE_SINGLETON
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Some(queue) = slot.take() {
+        queue.clear();
+    }
+}
+
+/// `queuedRefresh(refreshToken)` — THE entry point used by proactive-refresh
+/// and rotation-token-refresh.
+pub async fn queued_refresh(refresh_token: &str) -> TokenResult {
+    get_refresh_queue(None).refresh(refresh_token).await
+}
+
+// ============================================================================
+// Tests (ported from test/refresh-queue.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::refresh_lease::{LeaseFs, RefreshLeaseCoordinatorOptions};
+    use cma_core::schemas::token::TokenSuccess;
+    use std::path::Path;
+    use std::sync::atomic::{AtomicU32, Ordering};
+    use tokio::sync::Semaphore;
+
+    fn success(access: &str, refresh: &str) -> TokenResult {
+        TokenResult::Success(TokenSuccess {
+            access: access.to_string(),
+            refresh: refresh.to_string(),
+            expires: now_ms() + 3_600_000,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    fn failed(
+        reason: TokenFailureReason,
+        status_code: Option<i64>,
+        message: Option<&str>,
+    ) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: Some(reason),
+            status_code,
+            message: message.map(str::to_string),
+        })
+    }
+
+    /// Coordinator whose acquire always resolves to a bypass handle
+    /// immediately (the queue treats bypass and owner identically apart from
+    /// release, which is a no-op for bypass).
+    struct BypassCoordinator;
+
+    impl LeaseCoordinatorApi for BypassCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            _refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            async { Ok(RefreshLeaseHandle::bypass()) }.boxed()
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            Some(DEFAULT_WAIT_TIMEOUT_MS)
+        }
+    }
+
+    /// Coordinator whose FIRST acquire never resolves; subsequent acquires
+    /// resolve immediately. Tracks call counts.
+    struct StickyFirstAcquireCoordinator {
+        calls: AtomicU32,
+        configured: Option<i64>,
+    }
+
+    impl StickyFirstAcquireCoordinator {
+        fn new(configured: Option<i64>) -> Self {
+            Self {
+                calls: AtomicU32::new(0),
+                configured,
+            }
+        }
+    }
+
+    impl LeaseCoordinatorApi for StickyFirstAcquireCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            _refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            let call = self.calls.fetch_add(1, Ordering::SeqCst);
+            if call == 0 {
+                std::future::pending().boxed()
+            } else {
+                async { Ok(RefreshLeaseHandle::bypass()) }.boxed()
+            }
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            self.configured
+        }
+    }
+
+    /// Coordinator whose acquire always fails (the TS mockRejectedValue path).
+    struct FailingAcquireCoordinator;
+
+    impl LeaseCoordinatorApi for FailingAcquireCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            _refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            async { Err(io::Error::other("EBUSY lease dir")) }.boxed()
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            None
+        }
+    }
+
+    /// Coordinator whose FIRST acquire waits on a gate and then resolves;
+    /// subsequent acquires resolve immediately.
+    struct GatedFirstAcquireCoordinator {
+        calls: AtomicU32,
+        gate: Arc<Semaphore>,
+    }
+
+    impl LeaseCoordinatorApi for GatedFirstAcquireCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            _refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            let call = self.calls.fetch_add(1, Ordering::SeqCst);
+            let gate = Arc::clone(&self.gate);
+            async move {
+                if call == 0 {
+                    let permit = gate.acquire().await.expect("gate closed");
+                    permit.forget();
+                }
+                Ok(RefreshLeaseHandle::bypass())
+            }
+            .boxed()
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            Some(DEFAULT_WAIT_TIMEOUT_MS)
+        }
+    }
+
+    /// Executor returning a fixed sequence of behaviors (one per call).
+    enum ExecStep {
+        Ok(TokenResult),
+        Err(RefreshExecError),
+        Pending,
+        /// Wait for a semaphore permit, then return the result.
+        Gated(Arc<Semaphore>, TokenResult),
+    }
+
+    struct ExecScript {
+        steps: StdMutex<Vec<ExecStep>>,
+        calls: AtomicU32,
+        last_token: StdMutex<Option<String>>,
+    }
+
+    impl ExecScript {
+        fn new(steps: Vec<ExecStep>) -> Arc<Self> {
+            Arc::new(Self {
+                steps: StdMutex::new(steps),
+                calls: AtomicU32::new(0),
+                last_token: StdMutex::new(None),
+            })
+        }
+
+        fn executor(self: &Arc<Self>) -> RefreshExecutor {
+            let script = Arc::clone(self);
+            Arc::new(move |token: String| {
+                script.calls.fetch_add(1, Ordering::SeqCst);
+                *script.last_token.lock().unwrap() = Some(token);
+                let step = {
+                    let mut steps = script.steps.lock().unwrap();
+                    if steps.is_empty() {
+                        None
+                    } else {
+                        Some(steps.remove(0))
+                    }
+                };
+                async move {
+                    match step {
+                        Some(ExecStep::Ok(result)) => Ok(result),
+                        Some(ExecStep::Err(error)) => Err(error),
+                        Some(ExecStep::Pending) | None => std::future::pending().await,
+                        Some(ExecStep::Gated(gate, result)) => {
+                            let permit = gate.acquire().await.expect("gate closed");
+                            permit.forget();
+                            Ok(result)
+                        }
+                    }
+                }
+                .boxed()
+            })
+        }
+
+        fn calls(&self) -> u32 {
+            self.calls.load(Ordering::SeqCst)
+        }
+    }
+
+    async fn yield_a_few_times() {
+        for _ in 0..20 {
+            tokio::task::yield_now().await;
+        }
+    }
+
+    fn rewind_entry(queue: &RefreshQueue, token: &str, by_ms: i64) {
+        let mut state = queue.inner.lock();
+        let entry = state.pending.get_mut(token).expect("entry present");
+        entry.started_at -= by_ms;
+    }
+
+    // ---- basic refresh functionality ----
+
+    #[tokio::test]
+    async fn calls_refresh_executor_for_a_single_request() {
+        let mock = success("new-access-token", "new-refresh-token");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone())]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("test-refresh-token").await;
+
+        assert_eq!(result, mock);
+        assert_eq!(script.calls(), 1);
+        assert_eq!(
+            script.last_token.lock().unwrap().as_deref(),
+            Some("test-refresh-token")
+        );
+    }
+
+    #[tokio::test]
+    async fn returns_failed_result_when_refresh_fails() {
+        let script = ExecScript::new(vec![ExecStep::Ok(failed(
+            TokenFailureReason::HttpError,
+            Some(401),
+            None,
+        ))]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("bad-token").await;
+        let failure = result.as_failure().expect("failed result");
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+    }
+
+    #[tokio::test]
+    async fn catches_exceptions_and_returns_network_error_failure() {
+        let script = ExecScript::new(vec![ExecStep::Err(RefreshExecError {
+            message: Some("Network timeout".to_string()),
+            is_abort: false,
+        })]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("test-token").await;
+        let failure = result.as_failure().expect("failed result");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert_eq!(failure.message.as_deref(), Some("Network timeout"));
+    }
+
+    #[tokio::test]
+    async fn classifies_abort_errors_as_non_network_failures() {
+        let script = ExecScript::new(vec![ExecStep::Err(RefreshExecError {
+            message: Some("Request aborted".to_string()),
+            is_abort: true,
+        })]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("abort-token").await;
+        let failure = result.as_failure().expect("failed result");
+        assert_eq!(failure.reason, Some(TokenFailureReason::Unknown));
+        assert_eq!(failure.message.as_deref(), Some("Request aborted"));
+    }
+
+    #[tokio::test]
+    async fn handles_non_error_exception_during_refresh() {
+        // TS `mockRejectedValue("string error")` — message resolves to the
+        // fallback text.
+        let script = ExecScript::new(vec![ExecStep::Err(RefreshExecError {
+            message: None,
+            is_abort: false,
+        })]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("test-token").await;
+        let failure = result.as_failure().expect("failed result");
+        assert_eq!(failure.reason, Some(TokenFailureReason::NetworkError));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Unknown error during refresh")
+        );
+    }
+
+    // ---- deduplication of concurrent requests ----
+
+    #[tokio::test]
+    async fn dedupes_concurrent_refresh_requests_for_the_same_token() {
+        let gate = Arc::new(Semaphore::new(0));
+        let mock = success("deduped-access", "deduped-refresh");
+        let script = ExecScript::new(vec![ExecStep::Gated(Arc::clone(&gate), mock.clone())]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let task1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("same-token").await }
+        });
+        let task2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("same-token").await }
+        });
+        let task3 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("same-token").await }
+        });
+        yield_a_few_times().await;
+
+        assert_eq!(script.calls(), 1);
+
+        gate.add_permits(1);
+        let (result1, result2, result3) = (
+            task1.await.unwrap(),
+            task2.await.unwrap(),
+            task3.await.unwrap(),
+        );
+
+        assert_eq!(result1, result2);
+        assert_eq!(result2, result3);
+        assert_eq!(result1, mock);
+        assert_eq!(script.calls(), 1);
+    }
+
+    #[tokio::test]
+    async fn makes_separate_calls_for_different_tokens() {
+        let mock = success("access", "refresh");
+        let script = ExecScript::new(vec![
+            ExecStep::Ok(mock.clone()),
+            ExecStep::Ok(mock.clone()),
+            ExecStep::Ok(mock.clone()),
+        ]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let (r1, r2, r3) = tokio::join!(
+            queue.refresh("token-1"),
+            queue.refresh("token-2"),
+            queue.refresh("token-3"),
+        );
+        assert_eq!(r1, mock);
+        assert_eq!(r2, mock);
+        assert_eq!(r3, mock);
+        assert_eq!(script.calls(), 3);
+    }
+
+    #[tokio::test]
+    async fn allows_new_refresh_after_previous_completes() {
+        let mock = success("access", "refresh");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone()), ExecStep::Ok(mock.clone())]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        queue.refresh("token").await;
+        assert_eq!(script.calls(), 1);
+
+        queue.refresh("token").await;
+        assert_eq!(script.calls(), 2);
+    }
+
+    // ---- isRefreshing / pendingCount ----
+
+    #[tokio::test]
+    async fn is_refreshing_true_while_refresh_is_in_progress() {
+        let gate = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&gate),
+            success("access", "refresh"),
+        )]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        assert!(!queue.is_refreshing("token"));
+
+        let task = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("token").await }
+        });
+        yield_a_few_times().await;
+        assert!(queue.is_refreshing("token"));
+
+        gate.add_permits(1);
+        task.await.unwrap();
+
+        assert!(!queue.is_refreshing("token"));
+    }
+
+    #[tokio::test]
+    async fn tracks_the_number_of_pending_refreshes() {
+        let gate1 = Arc::new(Semaphore::new(0));
+        let gate2 = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![
+            ExecStep::Gated(Arc::clone(&gate1), success("access", "refresh")),
+            ExecStep::Gated(Arc::clone(&gate2), success("access", "refresh")),
+        ]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        assert_eq!(queue.pending_count(), 0);
+
+        let task1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("token-1").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        let task2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("token-2").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 2);
+
+        gate1.add_permits(1);
+        task1.await.unwrap();
+        assert_eq!(queue.pending_count(), 1);
+
+        gate2.add_permits(1);
+        task2.await.unwrap();
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    // ---- stale entry cleanup ----
+
+    #[tokio::test]
+    async fn evicts_stale_acquire_stage_entries_and_allows_a_fresh_retry() {
+        let coordinator = Arc::new(StickyFirstAcquireCoordinator::new(Some(
+            DEFAULT_WAIT_TIMEOUT_MS,
+        )));
+        let mock = success("access", "refresh");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone())]);
+        let queue = RefreshQueue::with_parts(1_000, coordinator.clone(), script.executor());
+
+        let _stuck = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("stale-acquire-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        // Acquire-stage entries are held until they exceed the lease wait
+        // budget (35s) + slack (5s); age this one past that 40s threshold.
+        rewind_entry(&queue, "stale-acquire-token", 41_000);
+
+        let second_result = queue.refresh("stale-acquire-token").await;
+        assert_eq!(second_result, mock);
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 2);
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    #[tokio::test]
+    async fn does_not_evict_acquire_entry_younger_than_the_lease_wait_budget() {
+        // Regression: a lease acquire() can legitimately block up to
+        // DEFAULT_WAIT_TIMEOUT_MS (35s), LONGER than the default maxEntryAgeMs
+        // (30s). Evicting earlier spawns a duplicate refresh -> invalid_grant.
+        let coordinator = Arc::new(StickyFirstAcquireCoordinator::new(Some(
+            DEFAULT_WAIT_TIMEOUT_MS,
+        )));
+        let script = ExecScript::new(vec![ExecStep::Ok(success("a", "r"))]);
+        let queue = RefreshQueue::with_parts(30_000, coordinator.clone(), script.executor());
+
+        let _stuck = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("wait-budget-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 1);
+
+        // Past maxEntryAgeMs (30s) but still within the lease wait budget:
+        // the entry must survive; a concurrent refresh dedupes onto it.
+        rewind_entry(&queue, "wait-budget-token", DEFAULT_WAIT_TIMEOUT_MS - 3_000);
+        let _join = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("wait-budget-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 1);
+
+        // Past the wait budget + slack: genuinely stuck, cleanup evicts, a
+        // fresh acquire is allowed.
+        rewind_entry(&queue, "wait-budget-token", 11_000);
+        let _retry = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("wait-budget-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 2);
+
+        queue.clear();
+    }
+
+    #[tokio::test]
+    async fn sizes_acquire_eviction_off_the_configured_lease_wait_budget() {
+        let configured_wait_ms = DEFAULT_WAIT_TIMEOUT_MS * 3;
+        let coordinator = Arc::new(StickyFirstAcquireCoordinator::new(Some(configured_wait_ms)));
+        let script = ExecScript::new(vec![ExecStep::Ok(success("a", "r"))]);
+        let queue = RefreshQueue::with_parts(30_000, coordinator.clone(), script.executor());
+
+        let _stuck = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("configured-wait-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 1);
+
+        // 45s: past the DEFAULT budget + slack (40s) but well inside the
+        // CONFIGURED budget — must survive and dedupe.
+        rewind_entry(
+            &queue,
+            "configured-wait-token",
+            DEFAULT_WAIT_TIMEOUT_MS + 10_000,
+        );
+        let _join = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("configured-wait-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 1);
+
+        // 111s: past the CONFIGURED budget (105s) + slack — evicted.
+        rewind_entry(
+            &queue,
+            "configured-wait-token",
+            configured_wait_ms + 6_000 - (DEFAULT_WAIT_TIMEOUT_MS + 10_000),
+        );
+        let _retry = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("configured-wait-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 2);
+
+        queue.clear();
+    }
+
+    #[tokio::test]
+    async fn joins_a_superseding_generation_after_stale_acquire_eviction() {
+        let acquire_gate = Arc::new(Semaphore::new(0));
+        let coordinator = Arc::new(GatedFirstAcquireCoordinator {
+            calls: AtomicU32::new(0),
+            gate: Arc::clone(&acquire_gate),
+        });
+        let exec_gate = Arc::new(Semaphore::new(0));
+        let superseded = success("access-after-supersede", "refresh-after-supersede");
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&exec_gate),
+            superseded.clone(),
+        )]);
+        let queue = RefreshQueue::with_parts(1_000, coordinator.clone(), script.executor());
+
+        let first = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("superseded-acquire-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        // Past the acquire-stage eviction threshold (wait budget 35s + 5s
+        // slack): the still-blocked first acquire is evicted and superseded.
+        rewind_entry(&queue, "superseded-acquire-token", 41_000);
+        let second = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("superseded-acquire-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 2);
+
+        // Release the first (stale-generation) acquire: it must JOIN the
+        // newer generation instead of running its own refresh.
+        acquire_gate.add_permits(1);
+        yield_a_few_times().await;
+        assert_eq!(script.calls(), 1);
+
+        exec_gate.add_permits(1);
+        let first_result = first.await.unwrap();
+        let second_result = second.await.unwrap();
+        assert_eq!(first_result, superseded);
+        assert_eq!(second_result, superseded);
+        assert_eq!(script.calls(), 1);
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    /// LeaseFs double that records every unlink (lock release). Reads report
+    /// NotFound so `owns_lock` treats the lock as still ours and unlinks it.
+    struct RecordingLeaseFs {
+        unlinks: StdMutex<Vec<std::path::PathBuf>>,
+    }
+
+    impl RecordingLeaseFs {
+        fn new() -> Arc<Self> {
+            Arc::new(Self {
+                unlinks: StdMutex::new(Vec::new()),
+            })
+        }
+
+        fn unlinked(&self, suffix: &str) -> bool {
+            self.unlinks
+                .lock()
+                .unwrap()
+                .iter()
+                .any(|path| path.to_string_lossy().ends_with(suffix))
+        }
+    }
+
+    impl LeaseFs for RecordingLeaseFs {
+        fn mkdir_recursive(&self, _dir: &Path, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn chmod(&self, _path: &Path, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn open_excl_write(&self, _path: &Path, _contents: &str, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn write_file(&self, _path: &Path, _contents: &str, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn rename(&self, _from: &Path, _to: &Path) -> io::Result<()> {
+            Ok(())
+        }
+        fn unlink(&self, path: &Path) -> io::Result<()> {
+            self.unlinks.lock().unwrap().push(path.to_path_buf());
+            Ok(())
+        }
+        fn read_to_string(&self, _path: &Path) -> io::Result<String> {
+            Err(io::Error::from(io::ErrorKind::NotFound))
+        }
+        fn mtime_ms(&self, _path: &Path) -> io::Result<f64> {
+            Err(io::Error::from(io::ErrorKind::NotFound))
+        }
+        fn read_dir_files(&self, _dir: &Path) -> io::Result<Vec<String>> {
+            Ok(Vec::new())
+        }
+    }
+
+    /// Like [`GatedFirstAcquireCoordinator`] but resolves to OWNER handles
+    /// over a [`RecordingLeaseFs`], so lock release timing is observable
+    /// (`lock-0` for the first acquire, `lock-1` for the second, …).
+    struct GatedOwnerCoordinator {
+        calls: AtomicU32,
+        gate: Arc<Semaphore>,
+        fs: Arc<RecordingLeaseFs>,
+    }
+
+    impl LeaseCoordinatorApi for GatedOwnerCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            _refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            let call = self.calls.fetch_add(1, Ordering::SeqCst);
+            let gate = Arc::clone(&self.gate);
+            let fs: Arc<dyn LeaseFs> = Arc::clone(&self.fs) as Arc<dyn LeaseFs>;
+            async move {
+                if call == 0 {
+                    let permit = gate.acquire().await.expect("gate closed");
+                    permit.forget();
+                }
+                Ok(RefreshLeaseHandle::owner(
+                    format!("hash-{call}"),
+                    std::path::PathBuf::from(format!("/lease/lock-{call}")),
+                    std::path::PathBuf::from(format!("/lease/result-{call}")),
+                    format!("nonce-{call}"),
+                    fs,
+                ))
+            }
+            .boxed()
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            Some(DEFAULT_WAIT_TIMEOUT_MS)
+        }
+    }
+
+    /// Finding: superseded lease owner must release the on-disk lock BEFORE
+    /// awaiting the newer generation's refresh (TS finally-before-adoption),
+    /// not after — otherwise the successor polls a live lock for its whole
+    /// wait budget and falls back to an unprotected bypass refresh.
+    #[tokio::test]
+    async fn superseded_owner_releases_the_lease_before_awaiting_the_newer_generation() {
+        let acquire_gate = Arc::new(Semaphore::new(0));
+        let fs = RecordingLeaseFs::new();
+        let coordinator = Arc::new(GatedOwnerCoordinator {
+            calls: AtomicU32::new(0),
+            gate: Arc::clone(&acquire_gate),
+            fs: Arc::clone(&fs),
+        });
+        let exec_gate = Arc::new(Semaphore::new(0));
+        let superseded = success("access-after-supersede", "refresh-after-supersede");
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&exec_gate),
+            superseded.clone(),
+        )]);
+        let queue = RefreshQueue::with_parts(1_000, coordinator.clone(), script.executor());
+
+        // First (stale) generation: acquire blocks on the gate.
+        let first = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("release-order-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        // Evict the acquire-stage entry, then start the superseding
+        // generation, whose refresh parks on the exec gate as lock-1 OWNER.
+        rewind_entry(&queue, "release-order-token", 41_000);
+        let second = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("release-order-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(coordinator.calls.load(Ordering::SeqCst), 2);
+        assert_eq!(script.calls(), 1, "superseding refresh in flight");
+
+        // Unblock the stale acquire: it resolves as lock-0 OWNER, discovers
+        // it was superseded, and must unlink lock-0 IMMEDIATELY — while the
+        // superseding refresh is still gated (not yet completed).
+        acquire_gate.add_permits(1);
+        yield_a_few_times().await;
+        assert!(
+            fs.unlinked("lock-0"),
+            "stale owner must release its lock BEFORE the superseding refresh completes; unlinks: {:?}",
+            fs.unlinks.lock().unwrap()
+        );
+        assert!(
+            !fs.unlinked("lock-1"),
+            "superseding owner still holds its lock while refreshing"
+        );
+
+        exec_gate.add_permits(1);
+        assert_eq!(first.await.unwrap(), superseded);
+        assert_eq!(second.await.unwrap(), superseded);
+        assert_eq!(script.calls(), 1);
+        assert!(fs.unlinked("lock-1"), "superseding owner releases at the end");
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    /// Finding: the refresh body must run EAGERLY to completion (TS async
+    /// IIFE) even when the creating caller is dropped mid-refresh (client
+    /// disconnect). A lazily polled Shared future would suspend the OAuth
+    /// exchange, leave the pending entry wedged at stage=Refresh forever
+    /// (cleanup never evicts refresh-stage entries), and serve every later
+    /// caller a stale cached "Refresh timeout" failure.
+    #[tokio::test]
+    async fn refresh_body_completes_and_cleans_up_when_the_creating_caller_is_dropped() {
+        let exec_gate = Arc::new(Semaphore::new(0));
+        let rotated = success("access-after-drop", "rotated-refresh-token");
+        let fresh = success("access-fresh", "fresh-refresh-token");
+        let script = ExecScript::new(vec![
+            ExecStep::Gated(Arc::clone(&exec_gate), rotated.clone()),
+            ExecStep::Ok(fresh.clone()),
+        ]);
+        let queue =
+            RefreshQueue::with_parts(1_000, Arc::new(BypassCoordinator), script.executor());
+
+        let creator = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("dropped-caller-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+        assert_eq!(script.calls(), 1, "refresh POST already sent");
+
+        // Client disconnect: the sole awaiter is dropped mid-refresh.
+        creator.abort();
+        let _ = creator.await;
+
+        // The detached body still processes the upstream response and the
+        // spawned wrapper runs the TS-`finally` cleanup.
+        exec_gate.add_permits(1);
+        for _ in 0..200 {
+            if queue.pending_count() == 0 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+        assert_eq!(
+            queue.pending_count(),
+            0,
+            "pending entry removed even though the creator died"
+        );
+
+        // A later caller performs a FRESH refresh (executor called again)
+        // instead of joining a wedged future / stale cached failure.
+        let second = queue.refresh("dropped-caller-token").await;
+        assert_eq!(second, fresh);
+        assert_eq!(script.calls(), 2);
+    }
+
+    #[tokio::test]
+    async fn times_out_stale_unresolved_entries_and_allows_retry() {
+        // Real-time test: maxEntryAgeMs 1000 ⇒ the stuck first call times out
+        // after ~1 s (tokio's test-util paused clock is not enabled in this
+        // workspace).
+        let successful = success("access", "refresh");
+        let script = ExecScript::new(vec![ExecStep::Pending, ExecStep::Ok(successful.clone())]);
+        let queue = RefreshQueue::with_parts(1_000, Arc::new(BypassCoordinator), script.executor());
+
+        let first_result = queue.refresh("stuck-token").await;
+        let failure = first_result.as_failure().expect("failed result");
+        assert_eq!(failure.reason, Some(TokenFailureReason::Unknown));
+        assert!(
+            failure
+                .message
+                .as_deref()
+                .unwrap_or_default()
+                .contains("Refresh timeout after"),
+            "{:?}",
+            failure.message
+        );
+        assert_eq!(queue.pending_count(), 0);
+
+        let second_result = queue.refresh("stuck-token").await;
+        assert_eq!(second_result, successful);
+        assert_eq!(script.calls(), 2);
+    }
+
+    #[tokio::test]
+    async fn recovers_after_a_429_response_and_retries_cleanly() {
+        let rate_limited = failed(TokenFailureReason::HttpError, Some(429), Some("Rate limited"));
+        let successful = success("access-after-429", "refresh-after-429");
+        let script = ExecScript::new(vec![
+            ExecStep::Ok(rate_limited.clone()),
+            ExecStep::Ok(successful.clone()),
+        ]);
+        let queue = RefreshQueue::with_parts(1_000, Arc::new(BypassCoordinator), script.executor());
+
+        let first_result = queue.refresh("rate-limited-token").await;
+        assert_eq!(first_result, rate_limited);
+        assert_eq!(queue.pending_count(), 0);
+
+        let second_result = queue.refresh("rate-limited-token").await;
+        assert_eq!(second_result, successful);
+        assert_eq!(script.calls(), 2);
+    }
+
+    #[tokio::test]
+    async fn keeps_dedupe_for_same_token_before_timeout_elapses() {
+        let gate = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![ExecStep::Gated(Arc::clone(&gate), success("a", "r"))]);
+        let queue = RefreshQueue::with_parts(1_000, Arc::new(BypassCoordinator), script.executor());
+
+        let task1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("same-token").await }
+        });
+        let task2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("same-token").await }
+        });
+        yield_a_few_times().await;
+
+        assert_eq!(script.calls(), 1);
+        assert_eq!(queue.pending_count(), 1);
+
+        gate.add_permits(1);
+        let (r1, r2) = (task1.await.unwrap(), task2.await.unwrap());
+        assert_eq!(r1, r2);
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    #[tokio::test]
+    async fn logs_stale_refresh_stage_warnings_only_once_per_entry() {
+        let script = ExecScript::new(vec![
+            ExecStep::Ok(success("a", "r")),
+            ExecStep::Ok(success("a", "r")),
+        ]);
+        let queue = RefreshQueue::with_parts(1_000, Arc::new(BypassCoordinator), script.executor());
+
+        // Inject a stale refresh-stage entry directly (the TS test reaches
+        // into the private map the same way).
+        {
+            let mut state = queue.inner.lock();
+            let never: SharedRefresh = std::future::pending::<TokenResult>().boxed().shared();
+            state.pending.insert(
+                "stale-refresh-token".to_string(),
+                RefreshEntry {
+                    future: never,
+                    started_at: now_ms() - 5_000,
+                    stage: Stage::Refresh,
+                    generation: 1,
+                    stale_warning_logged: false,
+                },
+            );
+        }
+
+        queue.refresh("fresh-token-1").await;
+        // After the first cleanup the warning flag is set (warned once)…
+        assert!(
+            queue
+                .inner
+                .lock()
+                .pending
+                .get("stale-refresh-token")
+                .expect("refresh-stage entries are never evicted")
+                .stale_warning_logged
+        );
+
+        queue.refresh("fresh-token-2").await;
+        // …and the entry is STILL present (refresh-stage is never evicted)
+        // with the flag still set — the second cleanup does not re-warn.
+        assert!(
+            queue
+                .inner
+                .lock()
+                .pending
+                .get("stale-refresh-token")
+                .expect("still present")
+                .stale_warning_logged
+        );
+        queue.clear();
+    }
+
+    // ---- singleton functions ----
+
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn get_refresh_queue_returns_singleton_instance() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        reset_refresh_queue();
+        let queue1 = get_refresh_queue(None);
+        let queue2 = get_refresh_queue(None);
+        assert!(Arc::ptr_eq(&queue1.inner, &queue2.inner));
+        reset_refresh_queue();
+    }
+
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn reset_refresh_queue_clears_the_singleton() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        reset_refresh_queue();
+        let queue1 = get_refresh_queue(None);
+        reset_refresh_queue();
+        let queue2 = get_refresh_queue(None);
+        assert!(!Arc::ptr_eq(&queue1.inner, &queue2.inner));
+        reset_refresh_queue();
+    }
+
+    // ---- clear ----
+
+    #[tokio::test]
+    async fn clear_removes_all_pending_entries() {
+        let script = ExecScript::new(vec![ExecStep::Pending, ExecStep::Pending]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let _t1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("token-1").await }
+        });
+        let _t2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("token-2").await }
+        });
+        yield_a_few_times().await;
+
+        assert_eq!(queue.pending_count(), 2);
+
+        queue.clear();
+
+        assert_eq!(queue.pending_count(), 0);
+    }
+
+    // ---- token rotation handling ----
+
+    #[tokio::test]
+    async fn tracks_token_rotation_when_refresh_returns_different_token() {
+        let mock = success("access", "new-rotated-token");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone())]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let result = queue.refresh("old-token").await;
+        let refreshed = result.as_success().expect("success");
+        assert_eq!(refreshed.refresh, "new-rotated-token");
+    }
+
+    #[tokio::test]
+    async fn reuses_pending_refresh_when_request_arrives_with_rotated_token() {
+        let gate = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&gate),
+            success("access", "new-rotated-token"),
+        )]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let task1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("old-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        // Simulate a rotation recorded while the refresh is still in flight
+        // (the TS test seeds the private map the same way).
+        queue
+            .inner
+            .lock()
+            .token_rotation_map
+            .push(("old-token".to_string(), "new-rotated-token".to_string()));
+
+        let task2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("new-rotated-token").await }
+        });
+        yield_a_few_times().await;
+
+        assert_eq!(script.calls(), 1);
+
+        gate.add_permits(1);
+        let (result1, result2) = (task1.await.unwrap(), task2.await.unwrap());
+        assert_eq!(result1, result2);
+    }
+
+    #[tokio::test]
+    async fn finds_original_token_via_rotation_map_and_reuses_pending_entry() {
+        let gate = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&gate),
+            success("access", "rotated-token"),
+        )]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        let task1 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("original-token").await }
+        });
+        yield_a_few_times().await;
+        assert_eq!(queue.pending_count(), 1);
+
+        {
+            let mut state = queue.inner.lock();
+            state
+                .token_rotation_map
+                .push(("unrelated-token".to_string(), "some-other-token".to_string()));
+            state
+                .token_rotation_map
+                .push(("original-token".to_string(), "rotated-token".to_string()));
+        }
+
+        let task2 = tokio::spawn({
+            let queue = queue.clone();
+            async move { queue.refresh("rotated-token").await }
+        });
+        yield_a_few_times().await;
+
+        assert_eq!(script.calls(), 1);
+        assert_eq!(
+            script.last_token.lock().unwrap().as_deref(),
+            Some("original-token")
+        );
+
+        gate.add_permits(1);
+        let (result1, result2) = (task1.await.unwrap(), task2.await.unwrap());
+        assert_eq!(result1, result2);
+    }
+
+    #[tokio::test]
+    async fn cleans_up_rotation_mapping_after_refresh_completes() {
+        let script = ExecScript::new(vec![
+            ExecStep::Ok(success("access", "new-rotated-token")),
+            ExecStep::Ok(success("access2", "another-token")),
+        ]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        queue.refresh("old-token").await;
+        assert_eq!(queue.pending_count(), 0);
+        // Mapping cleaned on completion: refreshing with the rotated token
+        // triggers a NEW refresh call, not a stale join.
+        queue.refresh("new-rotated-token").await;
+        assert_eq!(script.calls(), 2);
+    }
+
+    #[tokio::test]
+    async fn cleans_up_rotation_entries_pointing_to_the_completed_token() {
+        let script = ExecScript::new(vec![ExecStep::Ok(success("access", "token-b"))]);
+        let queue =
+            RefreshQueue::with_parts(30_000, Arc::new(BypassCoordinator), script.executor());
+
+        {
+            let mut state = queue.inner.lock();
+            state
+                .token_rotation_map
+                .push(("token-a".to_string(), "token-b".to_string()));
+            state
+                .token_rotation_map
+                .push(("token-c".to_string(), "token-b".to_string()));
+        }
+
+        queue.refresh("token-b").await;
+
+        let state = queue.inner.lock();
+        assert!(
+            !state
+                .token_rotation_map
+                .iter()
+                .any(|(old, _)| old == "token-a" || old == "token-c")
+        );
+    }
+
+    // ---- cross-process lease dedupe ----
+
+    #[tokio::test]
+    async fn reuses_refresh_result_across_queue_instances_via_lease_files() {
+        let lease_dir = tempfile::Builder::new()
+            .prefix("codex-refresh-lease-int-")
+            .tempdir()
+            .unwrap();
+        let lease_options = |dir: &Path| RefreshLeaseCoordinatorOptions {
+            enabled: Some(true),
+            lease_dir: Some(dir.to_path_buf()),
+            lease_ttl_ms: Some(5_000),
+            wait_timeout_ms: Some(2_000),
+            poll_interval_ms: Some(25),
+            result_ttl_ms: Some(5_000),
+            ..Default::default()
+        };
+        let lease_a = Arc::new(RefreshLeaseCoordinator::new(lease_options(lease_dir.path())));
+        let lease_b = Arc::new(RefreshLeaseCoordinator::new(lease_options(lease_dir.path())));
+
+        let delayed_result = success("shared-access", "shared-refresh-next");
+        let gate = Arc::new(Semaphore::new(0));
+        let script = ExecScript::new(vec![ExecStep::Gated(
+            Arc::clone(&gate),
+            delayed_result.clone(),
+        )]);
+        let executor = script.executor();
+        let queue_a = RefreshQueue::with_parts(30_000, lease_a, executor.clone());
+        let queue_b = RefreshQueue::with_parts(30_000, lease_b, executor);
+
+        let owner_task = tokio::spawn(async move { queue_a.refresh("same-cross-token").await });
+        // Wait until the owner has actually invoked the executor (holding the
+        // on-disk lease lock) before the follower starts.
+        for _ in 0..200 {
+            if script.calls() >= 1 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+        assert_eq!(script.calls(), 1);
+        let follower_task = tokio::spawn(async move { queue_b.refresh("same-cross-token").await });
+        tokio::time::sleep(Duration::from_millis(50)).await;
+        gate.add_permits(1);
+
+        let owner_result = owner_task.await.unwrap();
+        let follower_result = follower_task.await.unwrap();
+        assert_eq!(owner_result, delayed_result);
+        assert_eq!(follower_result, delayed_result);
+        assert_eq!(script.calls(), 1);
+    }
+
+    // ---- lease failure handling ----
+
+    #[tokio::test]
+    async fn falls_back_to_local_refresh_when_lease_acquisition_throws() {
+        let mock = success("fallback-access", "fallback-refresh");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone())]);
+        let queue = RefreshQueue::with_parts(
+            30_000,
+            Arc::new(FailingAcquireCoordinator),
+            script.executor(),
+        );
+
+        let result = queue.refresh("token-with-acquire-error").await;
+
+        assert_eq!(result, mock);
+        assert_eq!(script.calls(), 1);
+    }
+
+    /// LeaseFs whose result-file writes fail (publish errors) and whose
+    /// unlinks fail non-retryably (unlock errors) — release() error paths.
+    struct FailingReleaseFs;
+
+    impl LeaseFs for FailingReleaseFs {
+        fn mkdir_recursive(&self, _dir: &Path, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn chmod(&self, _path: &Path, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn open_excl_write(&self, _path: &Path, _contents: &str, _mode: u32) -> io::Result<()> {
+            Ok(())
+        }
+        fn write_file(&self, _path: &Path, _contents: &str, _mode: u32) -> io::Result<()> {
+            Err(cma_core::fs_retry::io_error_with_code("EIO", "publish failed"))
+        }
+        fn rename(&self, _from: &Path, _to: &Path) -> io::Result<()> {
+            Err(cma_core::fs_retry::io_error_with_code("EIO", "publish failed"))
+        }
+        fn unlink(&self, _path: &Path) -> io::Result<()> {
+            Err(cma_core::fs_retry::io_error_with_code("EINVAL", "unlock failed"))
+        }
+        fn read_to_string(&self, _path: &Path) -> io::Result<String> {
+            Err(cma_core::fs_retry::io_error_with_code("ENOENT", "missing"))
+        }
+        fn mtime_ms(&self, _path: &Path) -> io::Result<f64> {
+            Err(cma_core::fs_retry::io_error_with_code("ENOENT", "missing"))
+        }
+        fn read_dir_files(&self, _dir: &Path) -> io::Result<Vec<String>> {
+            Ok(Vec::new())
+        }
+    }
+
+    /// Coordinator yielding an OWNER handle whose release() publish fails.
+    struct FailingReleaseOwnerCoordinator;
+
+    impl LeaseCoordinatorApi for FailingReleaseOwnerCoordinator {
+        fn acquire<'a>(
+            &'a self,
+            refresh_token: &'a str,
+        ) -> BoxFuture<'a, io::Result<RefreshLeaseHandle>> {
+            let token = refresh_token.to_string();
+            async move {
+                let digest = Sha256::digest(token.as_bytes());
+                let hash: String = digest.iter().map(|b| format!("{b:02x}")).collect();
+                Ok(RefreshLeaseHandle::owner(
+                    hash.clone(),
+                    std::env::temp_dir().join(format!("{hash}.lock")),
+                    std::env::temp_dir().join(format!("{hash}.result.json")),
+                    "nonce".to_string(),
+                    Arc::new(FailingReleaseFs),
+                ))
+            }
+            .boxed()
+        }
+        fn configured_wait_timeout_ms(&self) -> Option<i64> {
+            Some(DEFAULT_WAIT_TIMEOUT_MS)
+        }
+    }
+
+    #[tokio::test]
+    async fn swallows_lease_release_errors_and_still_returns_token_result() {
+        let mock = success("release-safe-access", "release-safe-refresh");
+        let script = ExecScript::new(vec![ExecStep::Ok(mock.clone())]);
+        let queue = RefreshQueue::with_parts(
+            30_000,
+            Arc::new(FailingReleaseOwnerCoordinator),
+            script.executor(),
+        );
+
+        let result = queue.refresh("token-with-release-error").await;
+
+        assert_eq!(result, mock);
+        assert_eq!(script.calls(), 1);
+    }
+
+    // ---- fingerprint ----
+
+    #[test]
+    fn token_fingerprint_is_a_short_hash_prefix_never_the_token() {
+        assert_eq!(token_fingerprint(""), "none");
+        let fp = token_fingerprint("super-secret-refresh-token");
+        assert_eq!(fp.len(), 8);
+        assert!(fp.chars().all(|c| c.is_ascii_hexdigit()));
+        assert!(!"super-secret-refresh-token".contains(&fp));
+    }
+}
diff --git a/crates/bin/Cargo.toml b/crates/bin/Cargo.toml
new file mode 100644
index 000000000..d4220bde0
--- /dev/null
+++ b/crates/bin/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "cma-bin"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-manager = { path = "../manager" }
+cma-wrapper = { path = "../wrapper" }
+cma-proxy = { path = "../proxy" }
+cma-runtime = { path = "../runtime" }
+tokio.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/bin/src/bin/codex-multi-auth-app-launcher.rs b/crates/bin/src/bin/codex-multi-auth-app-launcher.rs
new file mode 100644
index 000000000..11ff41aa8
--- /dev/null
+++ b/crates/bin/src/bin/codex-multi-auth-app-launcher.rs
@@ -0,0 +1,7 @@
+//! `codex-multi-auth-app-launcher` — Codex app shortcut routing (TS
+//! `scripts/codex-app-launcher.js`): Windows `.lnk` retarget / macOS app /
+//! Linux `.desktop`, with `--remove` and `--dry-run`.
+
+fn main() {
+    cma_bin::run_main(|args| async move { cma_runtime::app_launcher::run(&args).await });
+}
diff --git a/crates/bin/src/bin/codex-multi-auth-app-router.rs b/crates/bin/src/bin/codex-multi-auth-app-router.rs
new file mode 100644
index 000000000..058d5a4d4
--- /dev/null
+++ b/crates/bin/src/bin/codex-multi-auth-app-router.rs
@@ -0,0 +1,8 @@
+//! `codex-multi-auth-app-router` — the detached app-bind router process
+//! (replaces `scripts/codex-app-router.js`, ARCHITECTURE R3): starts the
+//! rotation proxy, writes `app-bind/runtime-rotation-app-bind-status.json`,
+//! and idle-exits via `CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS`.
+
+fn main() {
+    cma_bin::run_main(|args| async move { cma_proxy::router::run(&args).await });
+}
diff --git a/crates/bin/src/bin/codex-multi-auth-codex.rs b/crates/bin/src/bin/codex-multi-auth-codex.rs
new file mode 100644
index 000000000..094b05e29
--- /dev/null
+++ b/crates/bin/src/bin/codex-multi-auth-codex.rs
@@ -0,0 +1,64 @@
+//! `codex-multi-auth-codex` — the codex wrapper bin (TS `scripts/codex.js`
+//! `main()`): auth-family args run the local manager; everything else
+//! forwards to the official `@openai/codex` via `cma_wrapper::forward`.
+//!
+//! R-deviation (deliberate, not a silent drop): TS `main()` calls
+//! `ensureWindowsShellShimGuards()` on every invocation — an OPT-IN win32
+//! self-heal that, under `CODEX_MULTI_AUTH_WINDOWS_BATCH_SHIM_GUARD` /
+//! `CODEX_MULTI_AUTH_PWSH_PROFILE_GUARD` (both default OFF), rewrites
+//! `codex.bat/.cmd/.ps1` shims in the npm global bin dir and upserts a
+//! PowerShell-profile `codex` function so `codex` keeps resolving to the
+//! wrapper after an official-codex npm install clobbers the shims. The Rust
+//! bin does NOT port it: the TS shim contents are npm/node_modules-specific
+//! (they exec `node scripts/codex.js`), and what a repaired shim should
+//! invoke under the native-binary distribution model is an open product
+//! decision. Until that decision lands, the two env vars are silent no-ops
+//! here; revisit `scripts/codex.js ensureWindowsShellShimGuards` +
+//! `test/codex-bin-wrapper.test.ts` when porting.
+
+use cma_wrapper::forward::{self, WrapperDispatch};
+
+fn main() {
+    cma_bin::run_main(|raw_args| async move {
+        match forward::classify_wrapper_args(&raw_args) {
+            // Internal detached app-helper child (`--codex-multi-auth-runtime-app-helper`).
+            WrapperDispatch::RunAppHelper => forward::run_runtime_rotation_app_helper().await,
+            // Auth-family (incl. `codex multi auth|multi-auth|multiauth` aliases,
+            // unless CODEX_MULTI_AUTH_BYPASS=1): run the local account manager.
+            // The startup update notice is a deliberate no-op on this path
+            // (TS `shouldRunStartupUpdateNotice` returns false for it).
+            WrapperDispatch::AuthManager { normalized_args } => {
+                let code = cma_manager::dispatcher::run_codex_multi_auth_cli(&normalized_args).await;
+                forward::maybe_install_codex_app_launcher_after_rotation_enable(
+                    &normalized_args,
+                    code,
+                )
+                .await;
+                code
+            }
+            // Forward to the official Codex CLI. `forward()` owns bin
+            // resolution, `--account` preflight, statusline, quota refresh,
+            // and observability; the bin owns the update notice and the
+            // auto-sync sandwich (both need cma-manager, which the wrapper
+            // crate must not depend on).
+            WrapperDispatch::Forward { raw_args } => {
+                let normalized_args = cma_wrapper::routing::normalize_auth_alias(&raw_args);
+                cma_wrapper::update_check::show_update_notice_if_available(
+                    &raw_args,
+                    &normalized_args,
+                    Some(&cma_bin::ManagerBackedLatestVersionFetch),
+                )
+                .await;
+                // TS runs the pre-sync after codex-bin/--account preflight;
+                // running it just before forward() is the closest seam the
+                // thin main has (an extra best-effort mirror write when the
+                // launch would fail is harmless).
+                cma_bin::auto_sync_manager_active_selection_if_enabled().await;
+                let code = forward::forward(&raw_args).await;
+                // TS `finally` branch: re-sync after the forwarded run.
+                cma_bin::auto_sync_manager_active_selection_if_enabled().await;
+                code
+            }
+        }
+    });
+}
diff --git a/crates/bin/src/bin/codex-multi-auth.rs b/crates/bin/src/bin/codex-multi-auth.rs
new file mode 100644
index 000000000..4afe3a280
--- /dev/null
+++ b/crates/bin/src/bin/codex-multi-auth.rs
@@ -0,0 +1,20 @@
+//! `codex-multi-auth` — the account-manager CLI (TS `scripts/codex-multi-auth.js`).
+//!
+//! Bare subcommands (`status`, `login`, …) normalize through the `auth`
+//! prefix rule INSIDE `run_codex_multi_auth_cli` (spec 08 §2), so this main
+//! only handles the standalone `--version`/`-v` short-circuit (which the TS
+//! bin script answered itself, before loading the manager).
+
+fn main() {
+    cma_bin::run_main(|args| async move {
+        let first = args.first().map(String::as_str).unwrap_or("");
+        if args.len() == 1 && (first == "--version" || first == "-v") {
+            // TS: prints the package version, exit 0 (the "version
+            // unavailable" branch is unreachable here — the crate version is
+            // compiled in).
+            println!("{}", cma_bin::cli_version());
+            return 0;
+        }
+        cma_manager::dispatcher::run_codex_multi_auth_cli(&args).await
+    });
+}
diff --git a/crates/bin/src/bin/mcodex.rs b/crates/bin/src/bin/mcodex.rs
new file mode 100644
index 000000000..093e2bf5b
--- /dev/null
+++ b/crates/bin/src/bin/mcodex.rs
@@ -0,0 +1,7 @@
+//! `mcodex` — convenience launcher over the codex wrapper (TS
+//! `scripts/mcodex.js`): default forward; `--monitor` (watch); `--tmux`/`-t`
+//! (+ `--live-accounts`). Missing-tool fallbacks per spec 14 §2.1 / R8.
+
+fn main() {
+    cma_bin::run_main(|args| async move { cma_wrapper::mcodex::run_mcodex(&args).await });
+}
diff --git a/crates/bin/src/lib.rs b/crates/bin/src/lib.rs
new file mode 100644
index 000000000..18f2a7fdc
--- /dev/null
+++ b/crates/bin/src/lib.rs
@@ -0,0 +1,130 @@
+//! cma-bin — shared plumbing for the five published binaries (ARCHITECTURE
+//! §2 / §6.16).
+//!
+//! Every `src/bin/*.rs` main stays thin: it hands an async entry closure to
+//! [`run_main`], which installs the panic hook, builds the multi-thread tokio
+//! runtime, drives the future to completion, and terminates the process with
+//! `std::process::exit(code)` — mirroring the Node bins' `process.exitCode`
+//! convention (ARCHITECTURE §5.4).
+//!
+//! This crate is also the ONLY place allowed to bridge `cma-wrapper` and
+//! `cma-manager` (they must not depend on each other, §4), so the two glue
+//! seams the wrapper deliberately leaves open live here:
+//! [`ManagerBackedLatestVersionFetch`] (npm update-notice fetch) and
+//! [`auto_sync_manager_active_selection_if_enabled`] (TS
+//! `autoSyncManagerActiveSelectionIfEnabled` in `scripts/codex.js`).
+
+use std::future::Future;
+use std::panic::AssertUnwindSafe;
+use std::pin::Pin;
+
+/// Exit code when the CLI future panics (Node parity: an uncaught exception
+/// terminates the process with a non-zero code; we normalize to 1).
+pub const PANIC_EXIT_CODE: i32 = 1;
+
+/// The CLI version string (TS `resolveCliVersion()` reads `package.json`;
+/// here the crate version is the package version). Never empty.
+pub fn cli_version() -> &'static str {
+    env!("CARGO_PKG_VERSION")
+}
+
+/// Install the CLI panic hook: with `CODEX_MULTI_AUTH_DEBUG=1` keep the full
+/// default report (backtrace pointer included); otherwise print one concise
+/// stderr line so a crash never dumps an internal trace at users.
+pub fn install_panic_hook() {
+    let default_hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |info| {
+        let debug = std::env::var("CODEX_MULTI_AUTH_DEBUG")
+            .unwrap_or_default()
+            .trim()
+            == "1";
+        if debug {
+            default_hook(info);
+            return;
+        }
+        let payload = info.payload();
+        let message = payload
+            .downcast_ref::<&str>()
+            .map(|text| (*text).to_string())
+            .or_else(|| payload.downcast_ref::<String>().cloned())
+            .unwrap_or_else(|| "unexpected internal error".to_string());
+        eprintln!("codex-multi-auth: fatal error: {message}");
+    }));
+}
+
+/// Thin-main driver: panic hook + multi-thread tokio runtime + exit-code
+/// convention. `entry` receives `argv[1..]` (the bin-name is dropped, like
+/// `process.argv.slice(2)`).
+///
+/// Background tasks spawned by the entry (detached children, unref'd loops)
+/// are NOT awaited — the runtime is shut down without draining, matching the
+/// Node bins, which exit as soon as the main promise settles.
+pub fn run_main<F, Fut>(entry: F) -> !
+where
+    F: FnOnce(Vec<String>) -> Fut,
+    Fut: Future<Output = i32>,
+{
+    install_panic_hook();
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let runtime = match tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(runtime) => runtime,
+        Err(error) => {
+            eprintln!("codex-multi-auth: failed to start async runtime: {error}");
+            std::process::exit(PANIC_EXIT_CODE);
+        }
+    };
+    let code = std::panic::catch_unwind(AssertUnwindSafe(|| runtime.block_on(entry(args))))
+        .unwrap_or(PANIC_EXIT_CODE);
+    runtime.shutdown_background();
+    std::process::exit(code);
+}
+
+/// Production [`cma_wrapper::update_check::LatestVersionFetch`]: the wrapper
+/// crate has no HTTP client by design, so the bin wires its startup update
+/// notice to the manager's reqwest-backed, 24h-cached npm lookup
+/// (`cma_manager::update_notice::check_for_updates`). `force=false` keeps the
+/// two modules' shared `update-check-cache.json` reads/writes coherent — the
+/// wrapper only invokes this fetcher when that cache is already stale.
+pub struct ManagerBackedLatestVersionFetch;
+
+impl cma_wrapper::update_check::LatestVersionFetch for ManagerBackedLatestVersionFetch {
+    fn fetch_latest_version(
+        &self,
+        timeout_ms: u64,
+    ) -> Pin<Box<dyn Future<Output = Option<String>> + Send + '_>> {
+        Box::pin(async move {
+            cma_manager::update_notice::check_for_updates(false, Some(timeout_ms))
+                .await
+                .latest_version
+        })
+    }
+}
+
+/// TS `autoSyncManagerActiveSelectionIfEnabled()` (`scripts/codex.js`):
+/// gated on `CODEX_MULTI_AUTH_AUTO_SYNC_ON_STARTUP` (default on; only a
+/// trimmed `"0"` disables), then best-effort — a sync failure never blocks
+/// the official Codex launch.
+pub async fn auto_sync_manager_active_selection_if_enabled() {
+    let enabled = std::env::var("CODEX_MULTI_AUTH_AUTO_SYNC_ON_STARTUP")
+        .unwrap_or_else(|_| "1".to_string())
+        .trim()
+        != "0";
+    if !enabled {
+        return;
+    }
+    let _ = cma_manager::dispatcher::auto_sync_active_account_to_codex().await;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cli_version_is_the_crate_version_and_non_empty() {
+        assert_eq!(cli_version(), env!("CARGO_PKG_VERSION"));
+        assert!(!cli_version().trim().is_empty());
+    }
+}
diff --git a/crates/bin/tests/docs_parity.rs b/crates/bin/tests/docs_parity.rs
new file mode 100644
index 000000000..b9ea53f33
--- /dev/null
+++ b/crates/bin/tests/docs_parity.rs
@@ -0,0 +1,287 @@
+//! Docs-parity suite — the `test/documentation.test.ts` analogue (spec 14
+//! §2 / §9.5, ARCHITECTURE §9.5).
+//!
+//! Docs under `docs/reference/*` are TESTED TRUTH: this suite fails when the
+//! CLI surface drifts from them. It asserts three contract families:
+//!
+//! 1. the command registry (`ACCOUNT_MANAGER_COMMANDS`) vs
+//!    `docs/reference/commands.md`;
+//! 2. the `--json` anchor list (Common Flags row + JSON Mode Contract +
+//!    additive surfaces) vs the frozen anchor set from spec 14 §2.4;
+//! 3. the stable error-code tables (proxy `error.code` values, canonical
+//!    usage-error strings, frozen refresh-failure message) vs
+//!    `docs/reference/error-contracts.md` AND the compiled implementation.
+
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use cma_manager::dispatcher::{CliOut, run_codex_multi_auth_cli_with};
+use cma_manager::help::print_usage;
+use cma_manager::registry::ACCOUNT_MANAGER_COMMANDS;
+use cma_testkit::sandbox::EnvSandbox;
+use serial_test::serial;
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .ancestors()
+        .nth(2)
+        .expect("crates/bin sits two levels below the repo root")
+        .to_path_buf()
+}
+
+fn read_doc(relative: &str) -> String {
+    let path = repo_root().join(relative);
+    fs::read_to_string(&path)
+        .unwrap_or_else(|error| panic!("cannot read {}: {error}", path.display()))
+}
+
+fn usage_text() -> String {
+    let mut out = CliOut::capture();
+    print_usage(&mut out);
+    out.info_text()
+}
+
+fn args(parts: &[&str]) -> Vec<String> {
+    parts.iter().map(|part| part.to_string()).collect()
+}
+
+/// The documentation-test `--json` anchor list (spec 14 §2.4; frozen order —
+/// it must match the Common Flags row in commands.md cell-for-cell).
+const JSON_ANCHOR_COMMANDS: [&str; 16] = [
+    "verify-flagged",
+    "verify",
+    "why-selected",
+    "best",
+    "forecast",
+    "report",
+    "usage",
+    "budget",
+    "models",
+    "monitor",
+    "integrations",
+    "fix",
+    "doctor",
+    "config explain",
+    "debug bundle",
+    "history",
+];
+
+/// Additive `--json` surfaces documented outside the compact Common Flags row.
+const ADDITIVE_JSON_SURFACES: [&str; 4] = [
+    "uninstall --json",
+    "rotation reset-rate-limits --json",
+    "rotation reset-runtime --json",
+    "account policy list --json",
+];
+
+/// The six stable runtime-rotation-proxy error codes and their documented
+/// HTTP statuses (spec 14 §7 table).
+const PROXY_ERROR_CODES: [(&str, &str); 6] = [
+    ("runtime_rotation_proxy_not_found", "`404`"),
+    ("runtime_rotation_proxy_unauthorized", "`401`"),
+    ("runtime_rotation_proxy_payload_too_large", "`413`"),
+    ("codex_runtime_rotation_pool_exhausted", "`429` or `503`"),
+    ("codex_pinned_account_unavailable", "`503`"),
+    ("codex_runtime_rotation_proxy_error", "`500`"),
+];
+
+// ---------------------------------------------------------------------------
+// 1. Command registry vs commands.md
+// ---------------------------------------------------------------------------
+
+#[test]
+fn registry_matches_ts_source_and_every_command_is_documented() {
+    // Spec 14 §2 header says "28 commands"; the ported TS source
+    // (`account-manager-commands.ts`, the authority) enumerates 29 —
+    // the registry is ported verbatim (see cma-manager::registry).
+    assert_eq!(ACCOUNT_MANAGER_COMMANDS.len(), 29);
+
+    let commands_md = read_doc("docs/reference/commands.md");
+    for command in ACCOUNT_MANAGER_COMMANDS {
+        assert!(
+            commands_md.contains(&format!("codex-multi-auth {command}")),
+            "docs/reference/commands.md does not document `codex-multi-auth {command}`"
+        );
+    }
+}
+
+#[test]
+fn usage_text_covers_every_registry_command() {
+    let usage = usage_text();
+    for command in ACCOUNT_MANAGER_COMMANDS {
+        // The usage text may list a command as an alternation of a sibling
+        // (ported verbatim from TS help.ts, e.g.
+        // `codex-multi-auth config template|init-config …`).
+        assert!(
+            usage.contains(&format!("codex-multi-auth {command}"))
+                || usage.contains(&format!("|{command}")),
+            "CLI usage text does not mention `codex-multi-auth {command}`"
+        );
+    }
+}
+
+/// The exact usage lines documentation.test.ts pinned against the CLI help.
+#[test]
+fn usage_text_contains_documentation_test_pins() {
+    let usage = usage_text();
+    for pin in [
+        "codex-multi-auth fix [--dry-run|-n] [--json] [--live] [--model <model>]",
+        "codex-multi-auth report [--live] [--json] [--explain] [--model <model>] [--max-accounts <n>] [--max-probes <n>] [--cached-only] [--out <path>]",
+        "codex-multi-auth config explain [--json]",
+        "codex-multi-auth debug bundle [--json]",
+        "codex-multi-auth why-selected [--now|-n | --last|-l] [--json]",
+    ] {
+        assert!(usage.contains(pin), "usage text lost the pinned line: {pin}");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 2. `--json` anchors
+// ---------------------------------------------------------------------------
+
+#[test]
+fn common_flags_json_row_matches_frozen_anchor_list() {
+    let commands_md = read_doc("docs/reference/commands.md");
+    let row = commands_md
+        .lines()
+        .find(|line| line.trim_start().starts_with("| `--json` |"))
+        .expect("commands.md Common Flags table has a `--json` row");
+    let cells: Vec<&str> = row.split('|').map(str::trim).collect();
+    // ["", "`--json`", "<families>", "<description>", ""]
+    let listed: Vec<&str> = cells[2].split(',').map(str::trim).collect();
+    assert_eq!(
+        listed,
+        JSON_ANCHOR_COMMANDS.to_vec(),
+        "Common Flags `--json` row drifted from the frozen anchor list"
+    );
+}
+
+#[test]
+fn json_mode_contract_lists_every_anchor_and_additive_surface() {
+    let error_contracts = read_doc("docs/reference/error-contracts.md");
+    let section_start = error_contracts
+        .find("## JSON Mode Contract")
+        .expect("error-contracts.md has a JSON Mode Contract section");
+    let section_end = error_contracts[section_start..]
+        .find("\n---")
+        .map(|offset| section_start + offset)
+        .unwrap_or(error_contracts.len());
+    let section = &error_contracts[section_start..section_end];
+
+    for command in JSON_ANCHOR_COMMANDS {
+        assert!(
+            section.contains(&format!("`{command}`")),
+            "JSON Mode Contract omits anchor `{command}`"
+        );
+    }
+    for surface in ADDITIVE_JSON_SURFACES {
+        assert!(
+            section.contains(&format!("`codex-multi-auth {surface}`")),
+            "JSON Mode Contract omits additive surface `codex-multi-auth {surface}`"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 3. Stable error-code tables
+// ---------------------------------------------------------------------------
+
+#[test]
+fn proxy_error_code_table_documents_all_six_stable_codes() {
+    let error_contracts = read_doc("docs/reference/error-contracts.md");
+    for (code, status) in PROXY_ERROR_CODES {
+        let row = error_contracts
+            .lines()
+            .find(|line| line.starts_with("| `") && line.contains(&format!("`{code}`")))
+            .unwrap_or_else(|| panic!("no proxy error table row for `{code}`"));
+        assert!(
+            row.contains(status),
+            "proxy error row for `{code}` no longer documents HTTP {status}: {row}"
+        );
+    }
+    // Pinned-unavailable structured skip reasons are a contract (issue #486).
+    for reason in [
+        "rate-limited",
+        "cooling-down:auth-failure",
+        "circuit-open",
+        "disabled",
+        "workspace-disabled",
+        "policy-blocked",
+        "missing",
+        "already-attempted",
+    ] {
+        assert!(
+            error_contracts.contains(&format!("`{reason}`")),
+            "documented pinned-unavailable skip reason `{reason}` is missing"
+        );
+    }
+    assert!(error_contracts.contains("`pinnedAccountIndex`"));
+    assert!(error_contracts.contains("`account_skip_reasons`"));
+}
+
+/// Docs ↔ implementation: the pool-exhausted payload the proxy actually
+/// builds carries the documented code, `reason`, `retry_after_ms`, and the
+/// `rotation status` hint (compact JSON, key order frozen by preserve_order).
+#[test]
+fn pool_exhausted_body_matches_documented_contract() {
+    let skip: HashMap<i64, String> = HashMap::from([(0, "rate-limited".to_string())]);
+    let body = cma_proxy::retry_loop::build_pool_exhausted_body("rate-limit", 12_345, &skip, 2);
+    assert!(body.contains("\"code\":\"codex_runtime_rotation_pool_exhausted\""));
+    assert!(body.contains("\"reason\":\"rate-limit\""));
+    assert!(body.contains("\"retry_after_ms\":12345"));
+    assert!(body.contains("\"account_skip_reasons\":{\"0\":\"rate-limited\"}"));
+    // Docs: "includes ... a hint to run `codex-multi-auth rotation status`".
+    assert!(body.contains("codex-multi-auth rotation status"));
+}
+
+/// The frozen refresh-failure message is identical in the compiled constants
+/// and in error-contracts.md (spec 14 §8 frozen-string table).
+#[test]
+fn frozen_refresh_failure_message_matches_docs_and_constants() {
+    const FROZEN: &str = "Failed to refresh token, authentication required";
+    assert_eq!(cma_core::constants::ERROR_MESSAGES.token_refresh_failed, FROZEN);
+    assert!(read_doc("docs/reference/error-contracts.md").contains(FROZEN));
+}
+
+/// Canonical usage-error strings: error-contracts.md documents them, and the
+/// live dispatcher emits exactly those strings with exit code 1.
+#[tokio::test(flavor = "multi_thread")]
+#[serial(env)]
+async fn canonical_usage_errors_match_error_contracts_doc() {
+    let error_contracts = read_doc("docs/reference/error-contracts.md");
+    assert!(error_contracts.contains("`Unknown command: <name>`"));
+    assert!(error_contracts.contains("`Missing index. Usage: codex-multi-auth switch <index>`"));
+    assert!(error_contracts.contains("`Invalid index: <value>`"));
+
+    let _sandbox = EnvSandbox::new();
+
+    let mut out = CliOut::capture();
+    let code =
+        run_codex_multi_auth_cli_with(&args(&["auth", "definitely-not-a-command"]), &mut out)
+            .await;
+    assert_eq!(code, 1);
+    assert!(
+        out.error_text()
+            .contains("Unknown command: definitely-not-a-command"),
+        "unknown-command error drifted: {}",
+        out.error_text()
+    );
+
+    let mut out = CliOut::capture();
+    let code = run_codex_multi_auth_cli_with(&args(&["auth", "switch"]), &mut out).await;
+    assert_eq!(code, 1);
+    assert_eq!(
+        out.error_text(),
+        "Missing index. Usage: codex-multi-auth switch <index>"
+    );
+
+    let mut out = CliOut::capture();
+    let code = run_codex_multi_auth_cli_with(&args(&["auth", "switch", "abc"]), &mut out).await;
+    assert_eq!(code, 1);
+    assert_eq!(out.error_text(), "Invalid index: abc");
+}
diff --git a/crates/climirror/Cargo.toml b/crates/climirror/Cargo.toml
new file mode 100644
index 000000000..23d95bb2f
--- /dev/null
+++ b/crates/climirror/Cargo.toml
@@ -0,0 +1,24 @@
+[package]
+name = "cma-cli-mirror"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+sha2.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/climirror/src/lib.rs b/crates/climirror/src/lib.rs
new file mode 100644
index 000000000..ca57eb2bf
--- /dev/null
+++ b/crates/climirror/src/lib.rs
@@ -0,0 +1,5 @@
+//! cma-cli-mirror - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod observability;
+pub mod state;
+pub mod sync;
+pub mod writer;
diff --git a/crates/climirror/src/observability.rs b/crates/climirror/src/observability.rs
new file mode 100644
index 000000000..c3c0c34c3
--- /dev/null
+++ b/crates/climirror/src/observability.rs
@@ -0,0 +1,217 @@
+//! Port of `lib/codex-cli/observability.ts` — in-process metrics counters for
+//! the Codex CLI mirror plus account fingerprint hashing for log lines.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §1.1.
+//!
+//! Contracts:
+//! - All 12 counters default to 0 and live in a module-level mutable singleton.
+//! - Metrics are **per-process, in-memory only** — never persisted to disk
+//!   (spec 11 gotcha 39).
+//! - `make_account_fingerprint` prefers the trimmed accountId, falls back to
+//!   the trimmed **lowercased** email, and returns the first 12 hex chars of
+//!   the sha256 — raw ids/emails must never reach logs.
+
+use std::sync::Mutex;
+
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+/// The Codex CLI mirror metric counters (TS `CodexCliMetrics`).
+///
+/// Serialized (diagnostics only — never persisted) with the exact TS field
+/// names via camelCase renames.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CodexCliMetrics {
+    pub read_attempts: u64,
+    pub read_successes: u64,
+    pub read_misses: u64,
+    pub read_failures: u64,
+    pub legacy_sync_env_uses: u64,
+    pub reconcile_attempts: u64,
+    pub reconcile_changes: u64,
+    pub reconcile_noops: u64,
+    pub reconcile_failures: u64,
+    pub write_attempts: u64,
+    pub write_successes: u64,
+    pub write_failures: u64,
+}
+
+/// Typed key for [`increment_codex_cli_metric`] (TS `keyof CodexCliMetrics`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CodexCliMetricKey {
+    ReadAttempts,
+    ReadSuccesses,
+    ReadMisses,
+    ReadFailures,
+    LegacySyncEnvUses,
+    ReconcileAttempts,
+    ReconcileChanges,
+    ReconcileNoops,
+    ReconcileFailures,
+    WriteAttempts,
+    WriteSuccesses,
+    WriteFailures,
+}
+
+static METRICS: Mutex<CodexCliMetrics> = Mutex::new(CodexCliMetrics {
+    read_attempts: 0,
+    read_successes: 0,
+    read_misses: 0,
+    read_failures: 0,
+    legacy_sync_env_uses: 0,
+    reconcile_attempts: 0,
+    reconcile_changes: 0,
+    reconcile_noops: 0,
+    reconcile_failures: 0,
+    write_attempts: 0,
+    write_successes: 0,
+    write_failures: 0,
+});
+
+fn lock_metrics() -> std::sync::MutexGuard<'static, CodexCliMetrics> {
+    METRICS.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// Add `delta` to the given counter (TS `incrementCodexCliMetric(key, delta)`).
+pub fn increment_codex_cli_metric_by(key: CodexCliMetricKey, delta: u64) {
+    let mut metrics = lock_metrics();
+    let slot = match key {
+        CodexCliMetricKey::ReadAttempts => &mut metrics.read_attempts,
+        CodexCliMetricKey::ReadSuccesses => &mut metrics.read_successes,
+        CodexCliMetricKey::ReadMisses => &mut metrics.read_misses,
+        CodexCliMetricKey::ReadFailures => &mut metrics.read_failures,
+        CodexCliMetricKey::LegacySyncEnvUses => &mut metrics.legacy_sync_env_uses,
+        CodexCliMetricKey::ReconcileAttempts => &mut metrics.reconcile_attempts,
+        CodexCliMetricKey::ReconcileChanges => &mut metrics.reconcile_changes,
+        CodexCliMetricKey::ReconcileNoops => &mut metrics.reconcile_noops,
+        CodexCliMetricKey::ReconcileFailures => &mut metrics.reconcile_failures,
+        CodexCliMetricKey::WriteAttempts => &mut metrics.write_attempts,
+        CodexCliMetricKey::WriteSuccesses => &mut metrics.write_successes,
+        CodexCliMetricKey::WriteFailures => &mut metrics.write_failures,
+    };
+    *slot = slot.saturating_add(delta);
+}
+
+/// Increment the given counter by 1 (TS default `delta = 1`).
+pub fn increment_codex_cli_metric(key: CodexCliMetricKey) {
+    increment_codex_cli_metric_by(key, 1);
+}
+
+/// Shallow copy of the current counters (TS `getCodexCliMetricsSnapshot`).
+pub fn get_codex_cli_metrics_snapshot() -> CodexCliMetrics {
+    *lock_metrics()
+}
+
+/// Reset all counters to 0 (TS `resetCodexCliMetricsForTests`).
+pub fn reset_codex_cli_metrics_for_tests() {
+    *lock_metrics() = CodexCliMetrics::default();
+}
+
+/// Stable 12-hex-char fingerprint for log lines (TS `makeAccountFingerprint`).
+///
+/// Raw value preference: trimmed non-empty `account_id`, else trimmed
+/// **lowercased** non-empty `email`, else `None`. The fingerprint is the first
+/// 12 hex chars of `sha256(raw)`; raw ids/emails are never logged.
+pub fn make_account_fingerprint(
+    account_id: Option<&str>,
+    email: Option<&str>,
+) -> Option<String> {
+    let raw = match account_id.map(str::trim).filter(|id| !id.is_empty()) {
+        Some(id) => id.to_string(),
+        None => match email.map(str::trim).filter(|email| !email.is_empty()) {
+            Some(email) => email.to_lowercase(),
+            None => return None,
+        },
+    };
+    let digest = Sha256::digest(raw.as_bytes());
+    let hex: String = digest.iter().map(|byte| format!("{byte:02x}")).collect();
+    Some(hex[..12].to_string())
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    fn fingerprint_prefers_account_id_over_email() {
+        let by_id = make_account_fingerprint(Some("acct-user-one"), Some("user@example.com"));
+        let id_only = make_account_fingerprint(Some("acct-user-one"), None);
+        assert_eq!(by_id, id_only);
+        assert!(by_id.is_some());
+    }
+
+    #[test]
+    fn fingerprint_trims_and_lowercases_email_fallback() {
+        let mixed = make_account_fingerprint(None, Some("  User.One@Example.COM  "));
+        let lower = make_account_fingerprint(None, Some("user.one@example.com"));
+        assert_eq!(mixed, lower);
+        // Blank accountId falls through to the email.
+        let blank_id = make_account_fingerprint(Some("   "), Some("user.one@example.com"));
+        assert_eq!(blank_id, lower);
+    }
+
+    #[test]
+    fn fingerprint_is_none_when_both_identifiers_are_absent_or_blank() {
+        assert_eq!(make_account_fingerprint(None, None), None);
+        assert_eq!(make_account_fingerprint(Some("  "), Some("")), None);
+    }
+
+    #[test]
+    fn fingerprint_is_12_lowercase_hex_chars_and_never_the_raw_value() {
+        let fp = make_account_fingerprint(Some("acct-user-one"), None).unwrap();
+        assert_eq!(fp.len(), 12);
+        assert!(fp.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));
+        assert_ne!(fp, "acct-user-one");
+    }
+
+    #[test]
+    #[serial(env)] // metrics are process-global shared state
+    fn metrics_increment_snapshot_and_reset() {
+        reset_codex_cli_metrics_for_tests();
+        assert_eq!(get_codex_cli_metrics_snapshot(), CodexCliMetrics::default());
+
+        increment_codex_cli_metric(CodexCliMetricKey::ReadAttempts);
+        increment_codex_cli_metric(CodexCliMetricKey::ReadAttempts);
+        increment_codex_cli_metric_by(CodexCliMetricKey::WriteFailures, 3);
+        let snapshot = get_codex_cli_metrics_snapshot();
+        assert_eq!(snapshot.read_attempts, 2);
+        assert_eq!(snapshot.write_failures, 3);
+        assert_eq!(snapshot.read_successes, 0);
+
+        // Snapshot is a copy — later increments do not mutate it.
+        increment_codex_cli_metric(CodexCliMetricKey::ReadAttempts);
+        assert_eq!(snapshot.read_attempts, 2);
+
+        reset_codex_cli_metrics_for_tests();
+        assert_eq!(get_codex_cli_metrics_snapshot(), CodexCliMetrics::default());
+    }
+
+    #[test]
+    fn metrics_serialize_with_ts_field_names() {
+        let json = serde_json::to_value(CodexCliMetrics::default()).unwrap();
+        let object = json.as_object().unwrap();
+        for key in [
+            "readAttempts",
+            "readSuccesses",
+            "readMisses",
+            "readFailures",
+            "legacySyncEnvUses",
+            "reconcileAttempts",
+            "reconcileChanges",
+            "reconcileNoops",
+            "reconcileFailures",
+            "writeAttempts",
+            "writeSuccesses",
+            "writeFailures",
+        ] {
+            assert!(object.contains_key(key), "missing {key}");
+        }
+        assert_eq!(object.len(), 12);
+    }
+}
diff --git a/crates/climirror/src/state.rs b/crates/climirror/src/state.rs
new file mode 100644
index 000000000..c9bcf021c
--- /dev/null
+++ b/crates/climirror/src/state.rs
@@ -0,0 +1,1344 @@
+//! Port of `lib/codex-cli/state.ts` — tolerant reader for the official Codex
+//! CLI's `accounts.json` / `auth.json` with a 5 s TTL cache.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §1.2 (+ gotchas 1, 9, 10,
+//! 38); TS source is authoritative.
+//!
+//! Contracts:
+//! - Tolerant DUAL snake_case/camelCase parsing at every level; token search is
+//!   top-level first, then nested `auth.tokens`, with the key priority order
+//!   flipping between the two levels.
+//! - JWT `exp` fallback (seconds → ms) when no finite non-zero `expiresAt` is
+//!   found (`Number("") === 0` is falsy and triggers the fallback — gotcha 38).
+//! - 5 s TTL cache with monotonic load generations: only the LATEST load may
+//!   commit `cache`/`cache_loaded_at`; forced refreshes never coalesce, while
+//!   non-forced callers coalesce onto any in-flight load.
+//! - Sync default is ON; only literal `"0"`/`"1"` are recognized; the legacy
+//!   env var warns once per process and bumps `legacySyncEnvUses`.
+//!
+//! Task-local caveat (ARCHITECTURE §5.4): cache state is process-global; none
+//! of it crosses `tokio::spawn` implicitly.
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{LazyLock, Mutex};
+
+use serde_json::{Map, Value, json};
+use tokio::sync::watch;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::{file_mtime_ms, read_text_file};
+use cma_core::jwt::decode_jwt_value;
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::runtime_paths::get_codex_home_dir;
+use cma_core::token_utils::{extract_account_email, extract_account_id};
+use cma_core::utils::now_ms;
+
+use crate::observability::{
+    CodexCliMetricKey, increment_codex_cli_metric, make_account_fingerprint,
+};
+
+const CACHE_TTL_MS: i64 = 5_000;
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+const FS_RETRY_ATTEMPTS: u32 = 4;
+
+fn state_log() -> ScopedLogger {
+    create_logger("codex-cli-state")
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/// Token snapshot for one CLI account (TS `CodexCliTokenCacheEntry`).
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexCliTokenCacheEntry {
+    /// May be `""` when only a refresh token was present.
+    pub access_token: String,
+    pub expires_at: Option<f64>,
+    pub refresh_token: Option<String>,
+    pub account_id: Option<String>,
+}
+
+/// One parsed CLI account entry (TS `CodexCliAccountSnapshot`).
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexCliAccountSnapshot {
+    /// Trimmed and lowercased.
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    /// May be `""` when only a refresh token was present.
+    pub access_token: String,
+    pub refresh_token: Option<String>,
+    pub expires_at: Option<f64>,
+    pub is_active: Option<bool>,
+}
+
+/// Parsed Codex CLI state (TS `CodexCliState`).
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexCliState {
+    pub path: PathBuf,
+    pub accounts: Vec<CodexCliAccountSnapshot>,
+    pub active_account_id: Option<String>,
+    pub active_email: Option<String>,
+    pub sync_version: Option<f64>,
+    pub source_updated_at_ms: Option<f64>,
+}
+
+// ---------------------------------------------------------------------------
+// Module cache state
+// ---------------------------------------------------------------------------
+
+type LoadResult = Option<CodexCliState>;
+/// `None` = load still pending; `Some(result)` = load settled.
+type LoadSlot = Option<LoadResult>;
+
+struct CacheState {
+    cache: Option<CodexCliState>,
+    cache_loaded_at: i64,
+    /// Monotonic load generation. forceRefresh lets loads overlap, so a slower
+    /// stale (earlier) read must not overwrite the shared cache committed by a
+    /// newer one (TS comment preserved verbatim in spirit).
+    latest_load_generation: u64,
+    in_flight: Option<watch::Receiver<LoadSlot>>,
+}
+
+static CACHE: LazyLock<Mutex<CacheState>> = LazyLock::new(|| {
+    Mutex::new(CacheState {
+        cache: None,
+        cache_loaded_at: 0,
+        latest_load_generation: 0,
+        in_flight: None,
+    })
+});
+
+static LEGACY_SYNC_WARNED: AtomicBool = AtomicBool::new(false);
+
+fn lock_cache() -> std::sync::MutexGuard<'static, CacheState> {
+    CACHE.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+// ---------------------------------------------------------------------------
+// Env helpers / path getters
+// ---------------------------------------------------------------------------
+
+fn env_string(name: &str) -> String {
+    std::env::var(name).unwrap_or_default()
+}
+
+/// Whether Codex CLI mirroring is enabled (TS `isCodexCliSyncEnabled`).
+///
+/// `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` (trimmed): `"0"` → false, `"1"` → true.
+/// Otherwise legacy `CODEX_AUTH_SYNC_CODEX_CLI` (trimmed): a non-empty value
+/// warns once per process and increments `legacySyncEnvUses`; `"0"` → false,
+/// `"1"` → true. **Default (both unset/other values): true** — any other value
+/// (e.g. `"true"`) falls through to the default.
+pub fn is_codex_cli_sync_enabled() -> bool {
+    let override_value = env_string("CODEX_MULTI_AUTH_SYNC_CODEX_CLI");
+    let override_value = override_value.trim();
+    if override_value == "0" {
+        return false;
+    }
+    if override_value == "1" {
+        return true;
+    }
+
+    let legacy = env_string("CODEX_AUTH_SYNC_CODEX_CLI");
+    let legacy = legacy.trim();
+    if !legacy.is_empty() && !LEGACY_SYNC_WARNED.swap(true, Ordering::SeqCst) {
+        increment_codex_cli_metric(CodexCliMetricKey::LegacySyncEnvUses);
+        state_log().warn(
+            "Using legacy CODEX_AUTH_SYNC_CODEX_CLI. Prefer CODEX_MULTI_AUTH_SYNC_CODEX_CLI.",
+            None,
+        );
+    }
+    if legacy == "0" {
+        return false;
+    }
+    if legacy == "1" {
+        return true;
+    }
+    true
+}
+
+fn env_path_override(name: &str) -> Option<PathBuf> {
+    let value = env_string(name);
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(PathBuf::from(trimmed))
+    }
+}
+
+/// `$CODEX_CLI_ACCOUNTS_PATH` (trimmed, non-empty) else
+/// `<codexHome>/accounts.json` (TS `getCodexCliAccountsPath`).
+pub fn get_codex_cli_accounts_path() -> PathBuf {
+    env_path_override("CODEX_CLI_ACCOUNTS_PATH")
+        .unwrap_or_else(|| get_codex_home_dir().join("accounts.json"))
+}
+
+/// `$CODEX_CLI_AUTH_PATH` else `<codexHome>/auth.json` (TS `getCodexCliAuthPath`).
+pub fn get_codex_cli_auth_path() -> PathBuf {
+    env_path_override("CODEX_CLI_AUTH_PATH")
+        .unwrap_or_else(|| get_codex_home_dir().join("auth.json"))
+}
+
+/// `$CODEX_CLI_CONFIG_PATH` else `<codexHome>/config.toml`
+/// (TS `getCodexCliConfigPath`).
+pub fn get_codex_cli_config_path() -> PathBuf {
+    env_path_override("CODEX_CLI_CONFIG_PATH")
+        .unwrap_or_else(|| get_codex_home_dir().join("config.toml"))
+}
+
+// ---------------------------------------------------------------------------
+// Tolerant value readers (shared parse vocabulary — see also writer.rs, which
+// deliberately duplicates them the way writer.ts duplicated state.ts's)
+// ---------------------------------------------------------------------------
+
+fn read_trimmed_string(value: Option<&Value>) -> Option<String> {
+    let s = value?.as_str()?;
+    let trimmed = s.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn normalize_email_value(value: Option<&Value>) -> Option<String> {
+    read_trimmed_string(value).map(|email| email.to_lowercase())
+}
+
+fn normalize_email_str(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_lowercase())
+    }
+}
+
+fn read_boolean(value: Option<&Value>) -> Option<bool> {
+    match value? {
+        Value::Bool(b) => Some(*b),
+        Value::String(s) => {
+            let lc = s.trim().to_lowercase();
+            match lc.as_str() {
+                "true" | "1" => Some(true),
+                "false" | "0" => Some(false),
+                _ => None,
+            }
+        }
+        _ => None,
+    }
+}
+
+/// JS `Number(string)` coercion for the subset of inputs this module sees.
+/// Notably `Number("") === 0` (gotcha 38) and whitespace is trimmed first.
+/// `pub(crate)` because writer.rs mirrors writer.ts's duplicated `readNumber`.
+pub(crate) fn js_number_from_str(raw: &str) -> Option<f64> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return Some(0.0);
+    }
+    if let Some(hex) = trimmed.strip_prefix("0x").or_else(|| trimmed.strip_prefix("0X")) {
+        return u128::from_str_radix(hex, 16).ok().map(|v| v as f64);
+    }
+    if let Some(oct) = trimmed.strip_prefix("0o").or_else(|| trimmed.strip_prefix("0O")) {
+        return u128::from_str_radix(oct, 8).ok().map(|v| v as f64);
+    }
+    if let Some(bin) = trimmed.strip_prefix("0b").or_else(|| trimmed.strip_prefix("0B")) {
+        return u128::from_str_radix(bin, 2).ok().map(|v| v as f64);
+    }
+    match trimmed {
+        "Infinity" | "+Infinity" => return Some(f64::INFINITY),
+        "-Infinity" => return Some(f64::NEG_INFINITY),
+        _ => {}
+    }
+    // Reject Rust-only spellings ("inf", "nan", "1_000"): JS Number() accepts
+    // only decimal/exponent syntax beyond the special cases above.
+    if !trimmed
+        .chars()
+        .all(|c| c.is_ascii_digit() || matches!(c, '+' | '-' | '.' | 'e' | 'E'))
+    {
+        return None;
+    }
+    trimmed.parse::<f64>().ok()
+}
+
+/// TS `readNumber`: finite numbers pass through; strings go through JS
+/// `Number()` coercion and must be finite.
+fn read_number(value: Option<&Value>) -> Option<f64> {
+    match value? {
+        Value::Number(n) => n.as_f64().filter(|v| v.is_finite()),
+        Value::String(s) => js_number_from_str(s).filter(|v| v.is_finite()),
+        _ => None,
+    }
+}
+
+fn extract_token_from_record(record: &Map<String, Value>, keys: &[&str]) -> Option<String> {
+    for key in keys {
+        if let Some(token) = read_trimmed_string(record.get(*key)) {
+            return Some(token);
+        }
+    }
+    None
+}
+
+fn as_object(value: Option<&Value>) -> Option<&Map<String, Value>> {
+    value?.as_object()
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+fn extract_account_snapshot(raw: &Value) -> Option<CodexCliAccountSnapshot> {
+    let record = raw.as_object()?;
+
+    let auth = as_object(record.get("auth"));
+    let tokens = auth.and_then(|auth| as_object(auth.get("tokens")));
+
+    let access_token = extract_token_from_record(record, &["accessToken", "access_token"])
+        .or_else(|| {
+            tokens.and_then(|tokens| {
+                extract_token_from_record(tokens, &["access_token", "accessToken"])
+            })
+        });
+    let refresh_token = extract_token_from_record(record, &["refreshToken", "refresh_token"])
+        .or_else(|| {
+            tokens.and_then(|tokens| {
+                extract_token_from_record(tokens, &["refresh_token", "refreshToken"])
+            })
+        });
+
+    let account_id = read_trimmed_string(record.get("accountId"))
+        .or_else(|| read_trimmed_string(record.get("account_id")))
+        .or_else(|| read_trimmed_string(record.get("workspace_id")))
+        .or_else(|| read_trimmed_string(record.get("organization_id")))
+        .or_else(|| read_trimmed_string(record.get("id")));
+    let email = normalize_email_value(record.get("email"))
+        .or_else(|| normalize_email_value(record.get("user_email")))
+        .or_else(|| normalize_email_value(record.get("username")));
+    let expires_at_raw = read_number(record.get("expiresAt"))
+        .or_else(|| read_number(record.get("expires_at")))
+        .or_else(|| tokens.and_then(|tokens| read_number(tokens.get("expires_at"))));
+
+    let mut expires_at = expires_at_raw;
+    // JS falsy check: undefined OR 0 both trigger the JWT-exp fallback.
+    let expires_at_falsy = expires_at.is_none_or(|v| v == 0.0);
+    if expires_at_falsy
+        && let Some(token) = &access_token
+        && let Some(decoded) = decode_jwt_value(token)
+        && let Some(exp) = decoded.get("exp").and_then(Value::as_f64)
+        && exp.is_finite()
+    {
+        expires_at = Some(exp * 1000.0);
+    }
+
+    let is_active = read_boolean(record.get("active"))
+        .or_else(|| read_boolean(record.get("isActive")))
+        .or_else(|| read_boolean(record.get("is_active")));
+
+    if access_token.is_none() && refresh_token.is_none() {
+        return None;
+    }
+
+    Some(CodexCliAccountSnapshot {
+        email,
+        account_id,
+        access_token: access_token.unwrap_or_default(),
+        refresh_token,
+        expires_at,
+        is_active,
+    })
+}
+
+fn parse_codex_cli_state(
+    path: &Path,
+    parsed: &Value,
+    source_updated_at_ms: Option<f64>,
+) -> Option<CodexCliState> {
+    let record = parsed.as_object()?;
+    let raw_accounts = record.get("accounts")?.as_array()?;
+
+    let accounts: Vec<CodexCliAccountSnapshot> = raw_accounts
+        .iter()
+        .filter_map(extract_account_snapshot)
+        .collect();
+
+    let mut active_account_id = read_trimmed_string(record.get("activeAccountId"))
+        .or_else(|| read_trimmed_string(record.get("active_account_id")));
+    let mut active_email = normalize_email_value(record.get("activeEmail"))
+        .or_else(|| normalize_email_value(record.get("active_email")));
+
+    if active_account_id.is_none()
+        && active_email.is_none()
+        && let Some(active_from_list) = accounts.iter().find(|a| a.is_active == Some(true))
+    {
+        active_account_id = active_from_list.account_id.clone();
+        active_email = active_from_list.email.clone();
+    }
+
+    Some(CodexCliState {
+        path: path.to_path_buf(),
+        accounts,
+        active_account_id,
+        active_email,
+        sync_version: read_number(record.get("codexMultiAuthSyncVersion")),
+        source_updated_at_ms,
+    })
+}
+
+fn parse_codex_cli_auth_state(
+    path: &Path,
+    parsed: &Value,
+    source_updated_at_ms: Option<f64>,
+) -> Option<CodexCliState> {
+    let record = parsed.as_object()?;
+    let tokens = as_object(record.get("tokens"))?;
+
+    let access_token = extract_token_from_record(tokens, &["access_token", "accessToken"]);
+    let refresh_token = extract_token_from_record(tokens, &["refresh_token", "refreshToken"]);
+    if access_token.is_none() && refresh_token.is_none() {
+        return None;
+    }
+
+    let id_token = extract_token_from_record(tokens, &["id_token", "idToken"]);
+    let account_id = read_trimmed_string(tokens.get("account_id"))
+        .or_else(|| read_trimmed_string(tokens.get("accountId")))
+        .or_else(|| extract_account_id(access_token.as_deref()));
+    let email = extract_account_email(access_token.as_deref(), id_token.as_deref())
+        .or_else(|| normalize_email_value(record.get("email")));
+
+    let mut expires_at: Option<f64> = None;
+    if let Some(token) = &access_token
+        && let Some(decoded) = decode_jwt_value(token)
+        && let Some(exp) = decoded.get("exp").and_then(Value::as_f64)
+        && exp.is_finite()
+    {
+        expires_at = Some(exp * 1000.0);
+    }
+
+    let snapshot = CodexCliAccountSnapshot {
+        email: email.clone(),
+        account_id: account_id.clone(),
+        access_token: access_token.unwrap_or_default(),
+        refresh_token,
+        expires_at,
+        is_active: Some(true),
+    };
+
+    Some(CodexCliState {
+        path: path.to_path_buf(),
+        accounts: vec![snapshot],
+        active_account_id: account_id,
+        active_email: email,
+        sync_version: read_number(record.get("codexMultiAuthSyncVersion")),
+        source_updated_at_ms,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// FS retry (TS `retryFsOperation`: 4 attempts, 10·2^n ms, {EBUSY, EPERM})
+// ---------------------------------------------------------------------------
+
+fn fs_retry_options() -> RetryOptions<std::io::Error> {
+    RetryOptions::new(
+        FS_RETRY_ATTEMPTS,
+        // TS sleeps `10 * 2 ** attempt` after 0-based failed attempt n:
+        // 10/20/40 ms before attempts 2/3/4 (1-based failed-attempt index here).
+        Backoff::from_fn(|failed_attempt| {
+            10u64.saturating_mul(2u64.saturating_pow(failed_attempt.saturating_sub(1)))
+        }),
+    )
+    .with_codes(RETRYABLE_FS_CODES)
+}
+
+async fn read_file_with_retry(path: &Path) -> std::io::Result<String> {
+    with_retry(
+        || {
+            let path = path.to_path_buf();
+            async move { read_text_file(&path) }
+        },
+        fs_retry_options(),
+    )
+    .await
+}
+
+async fn stat_mtime_with_retry(path: &Path) -> Option<f64> {
+    with_retry(
+        || {
+            let path = path.to_path_buf();
+            async move { file_mtime_ms(&path) }
+        },
+        fs_retry_options(),
+    )
+    .await
+    .ok()
+    .flatten()
+}
+
+// ---------------------------------------------------------------------------
+// Cache commit helpers
+// ---------------------------------------------------------------------------
+
+fn commit_cache(generation: u64, value: LoadResult) {
+    let mut state = lock_cache();
+    if generation == state.latest_load_generation {
+        state.cache = value;
+    }
+}
+
+fn finalize_load(generation: u64) {
+    // Only the latest load advances the shared cache timestamp, mirroring
+    // commit_cache, so a slow stale read can't reset the TTL window.
+    let mut state = lock_cache();
+    if generation == state.latest_load_generation {
+        state.cache_loaded_at = now_ms();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+
+async fn read_task_inner(generation: u64) -> LoadResult {
+    let log = state_log();
+    let accounts_path = get_codex_cli_accounts_path();
+    let auth_path = get_codex_cli_auth_path();
+    increment_codex_cli_metric(CodexCliMetricKey::ReadAttempts);
+
+    let has_accounts_path = accounts_path.exists();
+    let has_auth_path = auth_path.exists();
+    if !has_accounts_path && !has_auth_path {
+        increment_codex_cli_metric(CodexCliMetricKey::ReadMisses);
+        commit_cache(generation, None);
+        return None;
+    }
+
+    if has_accounts_path {
+        let attempt: Result<Value, String> = match read_file_with_retry(&accounts_path).await {
+            Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|e| e.to_string()),
+            Err(error) => Err(error.to_string()),
+        };
+        match attempt {
+            Ok(parsed) => {
+                let source_updated_at_ms = stat_mtime_with_retry(&accounts_path).await;
+                if let Some(state) =
+                    parse_codex_cli_state(&accounts_path, &parsed, source_updated_at_ms)
+                {
+                    increment_codex_cli_metric(CodexCliMetricKey::ReadSuccesses);
+                    log.debug(
+                        "Loaded Codex CLI state",
+                        Some(&json!({
+                            "operation": "read-state",
+                            "outcome": "success",
+                            "path": accounts_path.display().to_string(),
+                            "accountCount": state.accounts.len(),
+                            "activeAccountRef": make_account_fingerprint(
+                                state.active_account_id.as_deref(),
+                                state.active_email.as_deref(),
+                            ),
+                        })),
+                    );
+                    commit_cache(generation, Some(state.clone()));
+                    return Some(state);
+                }
+                log.warn(
+                    "Codex CLI accounts payload is malformed",
+                    Some(&json!({
+                        "operation": "read-state",
+                        "outcome": "malformed",
+                        "path": accounts_path.display().to_string(),
+                    })),
+                );
+            }
+            Err(error) => {
+                log.warn(
+                    "Failed to read Codex CLI accounts state",
+                    Some(&json!({
+                        "operation": "read-state",
+                        "outcome": "accounts-read-error",
+                        "path": accounts_path.display().to_string(),
+                        "error": error,
+                    })),
+                );
+            }
+        }
+    }
+
+    if has_auth_path {
+        let attempt: Result<Value, String> = match read_file_with_retry(&auth_path).await {
+            Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|e| e.to_string()),
+            Err(error) => Err(error.to_string()),
+        };
+        match attempt {
+            Ok(parsed) => {
+                let source_updated_at_ms = stat_mtime_with_retry(&auth_path).await;
+                if let Some(state) =
+                    parse_codex_cli_auth_state(&auth_path, &parsed, source_updated_at_ms)
+                {
+                    increment_codex_cli_metric(CodexCliMetricKey::ReadSuccesses);
+                    log.debug(
+                        "Loaded Codex CLI auth state",
+                        Some(&json!({
+                            "operation": "read-state",
+                            "outcome": "success",
+                            "path": auth_path.display().to_string(),
+                            "accountCount": state.accounts.len(),
+                            "activeAccountRef": make_account_fingerprint(
+                                state.active_account_id.as_deref(),
+                                state.active_email.as_deref(),
+                            ),
+                        })),
+                    );
+                    commit_cache(generation, Some(state.clone()));
+                    return Some(state);
+                }
+                log.warn(
+                    "Codex CLI auth payload is malformed",
+                    Some(&json!({
+                        "operation": "read-state",
+                        "outcome": "malformed",
+                        "path": auth_path.display().to_string(),
+                    })),
+                );
+            }
+            Err(error) => {
+                log.warn(
+                    "Failed to read Codex CLI auth state",
+                    Some(&json!({
+                        "operation": "read-state",
+                        "outcome": "auth-read-error",
+                        "path": auth_path.display().to_string(),
+                        "error": error,
+                    })),
+                );
+            }
+        }
+    }
+
+    increment_codex_cli_metric(CodexCliMetricKey::ReadFailures);
+    commit_cache(generation, None);
+    None
+}
+
+async fn read_task(generation: u64) -> LoadResult {
+    let result = read_task_inner(generation).await;
+    finalize_load(generation);
+    result
+}
+
+enum LoadPlan {
+    /// TTL fast path served from the shared cache.
+    Cached(CodexCliState),
+    /// Coalesce onto an in-flight load (non-forced callers only).
+    Wait(watch::Receiver<LoadSlot>),
+    /// This caller performs its own read under the claimed generation.
+    Load {
+        generation: u64,
+        tx: watch::Sender<LoadSlot>,
+        rx: watch::Receiver<LoadSlot>,
+    },
+}
+
+/// Load the Codex CLI state (TS `loadCodexCliState`).
+///
+/// Pass `force_refresh = true` to bypass the 5 s TTL cache **and** any
+/// in-flight coalesced load — a forced caller must observe fresh disk state.
+/// Returns `None` when sync is disabled, no valid payload exists, or a
+/// read/parse error occurred.
+pub async fn load_codex_cli_state(force_refresh: bool) -> Option<CodexCliState> {
+    if !is_codex_cli_sync_enabled() {
+        return None;
+    }
+
+    let now = now_ms();
+    let plan = {
+        let mut state = lock_cache();
+        let mut plan: Option<LoadPlan> = None;
+        if !force_refresh {
+            if let Some(cache) = &state.cache
+                && now - state.cache_loaded_at < CACHE_TTL_MS
+            {
+                plan = Some(LoadPlan::Cached(cache.clone()));
+            }
+            // A forceRefresh caller must not be satisfied by an in-flight load
+            // that may have been started without forceRefresh; only non-forced
+            // callers coalesce onto the in-flight load.
+            if plan.is_none()
+                && let Some(in_flight) = &state.in_flight
+            {
+                plan = Some(LoadPlan::Wait(in_flight.clone()));
+            }
+        }
+        match plan {
+            Some(plan) => plan,
+            None => {
+                // Claim a generation; only the latest load may commit the cache.
+                state.latest_load_generation += 1;
+                let generation = state.latest_load_generation;
+                let (tx, rx) = watch::channel::<LoadSlot>(None);
+                state.in_flight = Some(rx.clone());
+                LoadPlan::Load { generation, tx, rx }
+            }
+        }
+    };
+
+    match plan {
+        LoadPlan::Cached(cache) => Some(cache),
+        LoadPlan::Wait(rx) => wait_for_settled_load(rx).await,
+        LoadPlan::Load { generation, tx, rx } => {
+            // Detach the read so it always runs to completion (TS promises
+            // cannot be cancelled): if the initiating caller's future is
+            // dropped mid-read, coalesced waiters still get a settled result
+            // and the in-flight slot is still cleared.
+            let task_rx = rx.clone();
+            tokio::spawn(async move {
+                let result = read_task(generation).await;
+                let _ = tx.send(Some(result));
+                // Clear the in-flight slot only if it is still OUR load
+                // (a newer overlapping load may have replaced it).
+                let mut state = lock_cache();
+                if state
+                    .in_flight
+                    .as_ref()
+                    .is_some_and(|in_flight| in_flight.same_channel(&task_rx))
+                {
+                    state.in_flight = None;
+                }
+            });
+            wait_for_settled_load(rx).await
+        }
+    }
+}
+
+/// Await an in-flight load's settled result. If the loader vanished without
+/// settling (panic — impossible in normal operation), drop the dead in-flight
+/// slot so future callers start a fresh read instead of failing forever.
+async fn wait_for_settled_load(mut rx: watch::Receiver<LoadSlot>) -> LoadResult {
+    let settled = match rx.wait_for(|slot| slot.is_some()).await {
+        Ok(slot) => Some(slot.clone().flatten()),
+        Err(_) => None,
+    };
+    if let Some(result) = settled {
+        return result;
+    }
+    let mut state = lock_cache();
+    if state
+        .in_flight
+        .as_ref()
+        .is_some_and(|in_flight| in_flight.same_channel(&rx))
+    {
+        state.in_flight = None;
+    }
+    None
+}
+
+/// Look up tokens for an email via the (cached) CLI state
+/// (TS `lookupCodexCliTokensByEmail`). Requires a non-empty access token.
+pub async fn lookup_codex_cli_tokens_by_email(
+    email: Option<&str>,
+) -> Option<CodexCliTokenCacheEntry> {
+    let normalized = normalize_email_str(email)?;
+
+    let state = load_codex_cli_state(false).await?;
+
+    let account = state
+        .accounts
+        .iter()
+        .find(|entry| normalize_email_str(entry.email.as_deref()) == Some(normalized.clone()))?;
+    if account.access_token.is_empty() {
+        return None;
+    }
+
+    Some(CodexCliTokenCacheEntry {
+        access_token: account.access_token.clone(),
+        expires_at: account.expires_at,
+        refresh_token: account.refresh_token.clone(),
+        account_id: account.account_id.clone(),
+    })
+}
+
+/// Drop the TTL cache and any in-flight coalescing handle
+/// (TS `clearCodexCliStateCache`).
+pub fn clear_codex_cli_state_cache() {
+    let mut state = lock_cache();
+    state.cache = None;
+    state.cache_loaded_at = 0;
+    state.in_flight = None;
+}
+
+/// Clear the once-per-process legacy-env warning latch
+/// (TS `__resetCodexCliWarningCacheForTests`).
+pub fn __reset_codex_cli_warning_cache_for_tests() {
+    LEGACY_SYNC_WARNED.store(false, Ordering::SeqCst);
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/codex-cli-state.test.ts)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::observability::{get_codex_cli_metrics_snapshot, reset_codex_cli_metrics_for_tests};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::fs;
+
+    /// The JWT used by the TS suite: header `{"alg":"none"}`, payload
+    /// `{"exp":4100000000,"https://api.openai.com/auth":{"chatgpt_account_id":"acc_auth"},"email":"auth@example.com"}`.
+    const AUTH_JWT: &str = "eyJhbGciOiJub25lIn0.eyJleHAiOjQxMDAwMDAwMDAsImh0dHBzOi8vYXBpLm9wZW5haS5jb20vYXV0aCI6eyJjaGF0Z3B0X2FjY291bnRfaWQiOiJhY2NfYXV0aCJ9LCJlbWFpbCI6ImF1dGhAZXhhbXBsZS5jb20ifQ.";
+
+    struct StateFixture {
+        sandbox: EnvSandbox,
+        accounts_path: PathBuf,
+        auth_path: PathBuf,
+    }
+
+    impl StateFixture {
+        fn new() -> Self {
+            let mut sandbox = EnvSandbox::new();
+            let accounts_path = sandbox.root().join("accounts.json");
+            let auth_path = sandbox.root().join("auth.json");
+            let config_path = sandbox.root().join("config.toml");
+            sandbox.set_var("CODEX_CLI_ACCOUNTS_PATH", &accounts_path);
+            sandbox.set_var("CODEX_CLI_AUTH_PATH", &auth_path);
+            sandbox.set_var("CODEX_CLI_CONFIG_PATH", &config_path);
+            sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "1");
+            sandbox.remove_var("CODEX_AUTH_SYNC_CODEX_CLI");
+            clear_codex_cli_state_cache();
+            __reset_codex_cli_warning_cache_for_tests();
+            reset_codex_cli_metrics_for_tests();
+            StateFixture {
+                sandbox,
+                accounts_path,
+                auth_path,
+            }
+        }
+
+        fn write_accounts(&self, value: &Value) {
+            fs::write(
+                &self.accounts_path,
+                cma_core::json_io::stringify_pretty2(value),
+            )
+            .unwrap();
+        }
+
+        fn write_auth(&self, value: &Value) {
+            fs::write(&self.auth_path, cma_core::json_io::stringify_pretty2(value)).unwrap();
+        }
+    }
+
+    impl Drop for StateFixture {
+        fn drop(&mut self) {
+            clear_codex_cli_state_cache();
+            __reset_codex_cli_warning_cache_for_tests();
+            reset_codex_cli_metrics_for_tests();
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn loads_codex_cli_accounts_and_active_selection() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "codexMultiAuthSyncVersion": 123456,
+            "activeAccountId": "acc_b",
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+                {"accountId": "acc_b", "email": "b@example.com",
+                 "auth": {"tokens": {"access_token": "x.y.z", "refresh_token": "refresh-b"}},
+                 "active": true},
+            ],
+        }));
+
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.active_account_id.as_deref(), Some("acc_b"));
+        assert_eq!(state.accounts.len(), 2);
+        assert_eq!(state.sync_version, Some(123456.0));
+        assert!(state.source_updated_at_ms.is_some());
+
+        let lookup = lookup_codex_cli_tokens_by_email(Some("B@EXAMPLE.com"))
+            .await
+            .expect("lookup");
+        assert_eq!(lookup.refresh_token.as_deref(), Some("refresh-b"));
+        assert_eq!(lookup.account_id.as_deref(), Some("acc_b"));
+        drop(fx);
+    }
+
+    fn fake_state(id: &str) -> CodexCliState {
+        CodexCliState {
+            path: PathBuf::from("in-flight"),
+            accounts: Vec::new(),
+            active_account_id: Some(id.to_string()),
+            active_email: None,
+            sync_version: None,
+            source_updated_at_ms: None,
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn non_forced_loads_coalesce_onto_the_in_flight_load() {
+        let fx = StateFixture::new();
+        // A perfectly valid accounts file exists on disk...
+        fx.write_accounts(&json!({
+            "activeAccountId": "acc_a",
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+            ],
+        }));
+        clear_codex_cli_state_cache();
+        reset_codex_cli_metrics_for_tests();
+
+        // ...but an in-flight load is registered, so a non-forced caller must
+        // coalesce onto it instead of reading the disk.
+        let (tx, rx) = watch::channel::<LoadSlot>(None);
+        lock_cache().in_flight = Some(rx);
+        let _ = tx.send(Some(Some(fake_state("acc_in_flight"))));
+
+        let result = load_codex_cli_state(false).await.expect("coalesced result");
+        assert_eq!(result.active_account_id.as_deref(), Some("acc_in_flight"));
+        // No readTask ran: the caller never touched the disk.
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 0);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn concurrent_cache_miss_loads_coalesce_into_one_file_read() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "activeAccountId": "acc_a",
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+            ],
+        }));
+        clear_codex_cli_state_cache();
+        reset_codex_cli_metrics_for_tests();
+
+        // All 8 futures are polled inside one join! poll cycle on the
+        // current-thread test runtime: the first registers the in-flight slot
+        // synchronously under the cache lock, the other 7 coalesce onto it.
+        let results = tokio::join!(
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+            load_codex_cli_state(false),
+        );
+        for state in [
+            &results.0, &results.1, &results.2, &results.3, &results.4, &results.5, &results.6,
+            &results.7,
+        ] {
+            assert_eq!(
+                state
+                    .as_ref()
+                    .and_then(|state| state.active_account_id.as_deref()),
+                Some("acc_a")
+            );
+        }
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 1);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn force_refresh_bypasses_the_in_flight_load_and_reads_fresh_disk_state() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "activeAccountId": "acc_b",
+            "accounts": [
+                {"accountId": "acc_b", "email": "b@example.com",
+                 "auth": {"tokens": {"access_token": "x.y.z", "refresh_token": "refresh-b"}}},
+            ],
+        }));
+        clear_codex_cli_state_cache();
+        reset_codex_cli_metrics_for_tests();
+
+        // A stale in-flight load is registered; the forced caller must NOT be
+        // satisfied by it (TS: forced callers never coalesce).
+        let (tx, rx) = watch::channel::<LoadSlot>(None);
+        lock_cache().in_flight = Some(rx);
+        let _ = tx.send(Some(Some(fake_state("acc_stale"))));
+
+        let forced = load_codex_cli_state(true).await.expect("forced result");
+        assert_eq!(forced.active_account_id.as_deref(), Some("acc_b"));
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 1);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn stale_generation_loads_cannot_clobber_the_committed_cache() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "activeAccountId": "acc_b",
+            "accounts": [
+                {"accountId": "acc_b", "email": "b@example.com",
+                 "auth": {"tokens": {"access_token": "x.y.z", "refresh_token": "refresh-b"}}},
+            ],
+        }));
+        clear_codex_cli_state_cache();
+
+        // A real load claims the latest generation and commits acc_b.
+        let fresh = load_codex_cli_state(true).await.expect("fresh");
+        assert_eq!(fresh.active_account_id.as_deref(), Some("acc_b"));
+        let latest = lock_cache().latest_load_generation;
+
+        // A slower stale (older-generation) load resolving late must not
+        // overwrite the shared cache committed by the newer one.
+        commit_cache(latest - 1, Some(fake_state("acc_stale")));
+        finalize_load(latest - 1);
+
+        let after_stale = load_codex_cli_state(false).await.expect("cached");
+        assert_eq!(after_stale.active_account_id.as_deref(), Some("acc_b"));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn ttl_cache_serves_repeat_loads_and_force_refresh_bypasses_it() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "activeAccountId": "acc_a",
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+            ],
+        }));
+        clear_codex_cli_state_cache();
+        reset_codex_cli_metrics_for_tests();
+
+        let first = load_codex_cli_state(false).await.expect("first");
+        assert_eq!(first.active_account_id.as_deref(), Some("acc_a"));
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 1);
+
+        // Within the TTL window the cache satisfies the call — no new read.
+        let second = load_codex_cli_state(false).await.expect("second");
+        assert_eq!(second, first);
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 1);
+
+        // forceRefresh always re-reads the disk.
+        let forced = load_codex_cli_state(true).await.expect("forced");
+        assert_eq!(forced.active_account_id.as_deref(), Some("acc_a"));
+        assert_eq!(get_codex_cli_metrics_snapshot().read_attempts, 2);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn falls_back_to_auth_json_when_accounts_json_is_missing() {
+        let fx = StateFixture::new();
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "OPENAI_API_KEY": null,
+            "tokens": {
+                "access_token": AUTH_JWT,
+                "refresh_token": "refresh-auth",
+                "account_id": "acc_auth",
+            },
+            "last_refresh": "2026-02-25T21:36:07.864Z",
+        }));
+
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.path, fx.auth_path);
+        assert_eq!(state.accounts.len(), 1);
+        assert_eq!(state.active_account_id.as_deref(), Some("acc_auth"));
+        assert_eq!(state.active_email.as_deref(), Some("auth@example.com"));
+
+        let lookup = lookup_codex_cli_tokens_by_email(Some("AUTH@EXAMPLE.COM"))
+            .await
+            .expect("lookup");
+        assert_eq!(lookup.refresh_token.as_deref(), Some("refresh-auth"));
+        assert_eq!(lookup.account_id.as_deref(), Some("acc_auth"));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn falls_back_to_auth_json_when_accounts_json_is_malformed() {
+        let fx = StateFixture::new();
+        fs::write(&fx.accounts_path, "{ malformed json").unwrap();
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "OPENAI_API_KEY": null,
+            "tokens": {
+                "access_token": AUTH_JWT,
+                "refresh_token": "refresh-auth",
+                "account_id": "acc_auth",
+            },
+        }));
+
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.path, fx.auth_path);
+        assert_eq!(state.active_account_id.as_deref(), Some("acc_auth"));
+        assert_eq!(state.accounts.len(), 1);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn derives_active_selection_from_per_account_active_flag() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com", "active": true,
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+            ],
+        }));
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.accounts[0].account_id.as_deref(), Some("acc_a"));
+        assert_eq!(state.active_email.as_deref(), Some("a@example.com"));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_none_for_malformed_codex_cli_payload() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({"accounts": {"accountId": "acc_a"}}));
+        assert_eq!(load_codex_cli_state(true).await, None);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_none_when_sync_is_disabled() {
+        let mut fx = StateFixture::new();
+        fx.sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "0");
+        clear_codex_cli_state_cache();
+        fx.write_accounts(&json!({
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+            ],
+        }));
+        assert_eq!(load_codex_cli_state(true).await, None);
+        assert_eq!(lookup_codex_cli_tokens_by_email(Some("a@example.com")).await, None);
+        drop(fx);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn prefers_modern_sync_env_over_legacy() {
+        let mut sandbox = EnvSandbox::new();
+        __reset_codex_cli_warning_cache_for_tests();
+        sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "1");
+        sandbox.set_var("CODEX_AUTH_SYNC_CODEX_CLI", "0");
+        assert!(is_codex_cli_sync_enabled());
+        __reset_codex_cli_warning_cache_for_tests();
+        drop(sandbox);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn honors_legacy_sync_env_values_and_emits_warning_metric_once() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI");
+        __reset_codex_cli_warning_cache_for_tests();
+        reset_codex_cli_metrics_for_tests();
+
+        sandbox.set_var("CODEX_AUTH_SYNC_CODEX_CLI", "0");
+        assert!(!is_codex_cli_sync_enabled());
+        sandbox.set_var("CODEX_AUTH_SYNC_CODEX_CLI", "1");
+        assert!(is_codex_cli_sync_enabled());
+        assert!(is_codex_cli_sync_enabled());
+        assert_eq!(get_codex_cli_metrics_snapshot().legacy_sync_env_uses, 1);
+
+        __reset_codex_cli_warning_cache_for_tests();
+        reset_codex_cli_metrics_for_tests();
+        drop(sandbox);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn sync_defaults_on_and_ignores_unrecognized_values() {
+        let mut sandbox = EnvSandbox::new();
+        __reset_codex_cli_warning_cache_for_tests();
+        sandbox.remove_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI");
+        sandbox.remove_var("CODEX_AUTH_SYNC_CODEX_CLI");
+        assert!(is_codex_cli_sync_enabled());
+        // Only literal "0"/"1" are recognized — "true" falls to the default.
+        sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "true");
+        assert!(is_codex_cli_sync_enabled());
+        __reset_codex_cli_warning_cache_for_tests();
+        drop(sandbox);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn records_a_read_miss_when_neither_file_exists() {
+        let fx = StateFixture::new();
+        assert_eq!(load_codex_cli_state(true).await, None);
+        assert!(get_codex_cli_metrics_snapshot().read_misses >= 1);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn parses_string_booleans_and_numbers_while_filtering_invalid_entries() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                123,
+                {"accountId": "missing"},
+                {"account_id": "acc_true", "username": "TRUE@EXAMPLE.COM",
+                 "access_token": "true.access.token", "refresh_token": "true-refresh",
+                 "is_active": "1", "expires_at": "1710000000000"},
+                {"id": "acc_false", "user_email": "FALSE@EXAMPLE.COM",
+                 "access_token": "false.access.token", "refresh_token": "false-refresh",
+                 "active": "0", "expiresAt": "1710000005000"},
+            ],
+        }));
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.accounts.len(), 2);
+        assert_eq!(state.active_account_id.as_deref(), Some("acc_true"));
+        assert_eq!(state.active_email.as_deref(), Some("true@example.com"));
+        assert_eq!(state.accounts[0].is_active, Some(true));
+        assert_eq!(state.accounts[0].expires_at, Some(1_710_000_000_000.0));
+        assert_eq!(state.accounts[1].is_active, Some(false));
+        assert_eq!(state.accounts[1].expires_at, Some(1_710_000_005_000.0));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn derives_expiration_from_jwt_and_uses_auth_account_id_email_fallbacks() {
+        let fx = StateFixture::new();
+        fx.write_auth(&json!({
+            "email": "Auth@Example.COM",
+            "codexMultiAuthSyncVersion": "777",
+            "tokens": {
+                "access_token": AUTH_JWT,
+                "refresh_token": "refresh-auth",
+                "accountId": " acc_from_auth_field ",
+            },
+        }));
+        let state = load_codex_cli_state(true).await.expect("state");
+        assert_eq!(state.active_account_id.as_deref(), Some("acc_from_auth_field"));
+        assert_eq!(state.active_email.as_deref(), Some("auth@example.com"));
+        assert_eq!(state.sync_version, Some(777.0));
+        assert_eq!(state.accounts[0].expires_at, Some(4_100_000_000_000.0));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_none_when_auth_payload_tokens_are_missing_or_tokenless() {
+        let fx = StateFixture::new();
+        fx.write_auth(&json!({"tokens": []}));
+        assert_eq!(load_codex_cli_state(true).await, None);
+
+        fx.write_auth(&json!({"tokens": {"id_token": "id-only"}}));
+        clear_codex_cli_state_cache();
+        assert_eq!(load_codex_cli_state(true).await, None);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_none_for_lookup_with_blank_email_or_missing_access_token() {
+        let fx = StateFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [{"email": "a@example.com", "refresh_token": "refresh-a"}],
+        }));
+        assert_eq!(lookup_codex_cli_tokens_by_email(Some("   ")).await, None);
+        assert_eq!(lookup_codex_cli_tokens_by_email(None).await, None);
+        // Refresh-only entries survive parsing with an empty accessToken but
+        // are never surfaced by lookup.
+        assert_eq!(
+            lookup_codex_cli_tokens_by_email(Some("a@example.com")).await,
+            None
+        );
+        drop(fx);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn uses_codex_home_defaults_when_explicit_overrides_are_absent() {
+        let mut sandbox = EnvSandbox::new();
+        let codex_home = sandbox.root().join("custom-codex-home");
+        sandbox.set_var("CODEX_HOME", &codex_home);
+        sandbox.remove_var("CODEX_CLI_ACCOUNTS_PATH");
+        sandbox.remove_var("CODEX_CLI_AUTH_PATH");
+        sandbox.remove_var("CODEX_CLI_CONFIG_PATH");
+
+        assert_eq!(get_codex_cli_accounts_path(), codex_home.join("accounts.json"));
+        assert_eq!(get_codex_cli_auth_path(), codex_home.join("auth.json"));
+        assert_eq!(get_codex_cli_config_path(), codex_home.join("config.toml"));
+        drop(sandbox);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn retry_policy_retries_ebusy_eperm_and_rejects_other_codes() {
+        use cma_core::fs_retry::CodedError;
+        use std::io;
+        use std::sync::atomic::AtomicU32;
+
+        // EPERM once → succeeds on the second attempt (TS test parity via the
+        // same retry options the readers use).
+        let attempts = AtomicU32::new(0);
+        let result: Result<&str, io::Error> = with_retry(
+            || {
+                let n = attempts.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    if n == 0 {
+                        Err(io::Error::other(CodedError::new("EPERM", "locked")))
+                    } else {
+                        Ok("ok")
+                    }
+                }
+            },
+            fs_retry_options(),
+        )
+        .await;
+        assert_eq!(result.unwrap(), "ok");
+        assert_eq!(attempts.load(Ordering::SeqCst), 2);
+
+        // EACCES is NOT retryable for the CLI-state readers.
+        let attempts = AtomicU32::new(0);
+        let result: Result<&str, io::Error> = with_retry(
+            || {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    Err(io::Error::other(CodedError::new("EACCES", "denied")))
+                }
+            },
+            fs_retry_options(),
+        )
+        .await;
+        assert!(result.is_err());
+        assert_eq!(attempts.load(Ordering::SeqCst), 1);
+    }
+
+    #[test]
+    fn js_number_coercion_mirrors_number_builtin() {
+        assert_eq!(js_number_from_str(""), Some(0.0));
+        assert_eq!(js_number_from_str("   "), Some(0.0));
+        assert_eq!(js_number_from_str("1710000000000"), Some(1_710_000_000_000.0));
+        assert_eq!(js_number_from_str(" 12 "), Some(12.0));
+        assert_eq!(js_number_from_str("1.5e3"), Some(1500.0));
+        assert_eq!(js_number_from_str("0x10"), Some(16.0));
+        assert_eq!(js_number_from_str("abc"), None);
+        assert_eq!(js_number_from_str("1_000"), None);
+        assert_eq!(js_number_from_str("nan"), None);
+        // Infinity parses but read_number rejects non-finite values.
+        assert_eq!(
+            read_number(Some(&Value::String("Infinity".into()))),
+            None
+        );
+        assert_eq!(read_number(Some(&json!(42))), Some(42.0));
+        assert_eq!(read_number(Some(&json!(true))), None);
+    }
+}
diff --git a/crates/climirror/src/sync.rs b/crates/climirror/src/sync.rs
new file mode 100644
index 000000000..7251a61d7
--- /dev/null
+++ b/crates/climirror/src/sync.rs
@@ -0,0 +1,354 @@
+//! Port of `lib/codex-cli/sync.ts` — the deliberately-inert reconcile entry
+//! point that guards the one-way mirror invariant.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §1.3 (+ gotcha 2).
+//!
+//! Contracts:
+//! - **NEVER reads Codex CLI files.** Multi-auth storage is canonical; the CLI
+//!   files are a one-way mirror and must never seed, merge into, or restore the
+//!   canonical pool. This module has no filesystem access at all — the
+//!   invariant is compile-time enforced.
+//! - Normalization clamps `activeIndex` and the per-family indexes into
+//!   `[0, count-1]` and keeps the family map SPARSE: a missing family entry is
+//!   written only when its clamped value differs from `activeIndex`.
+//! - The clone drops `pinnedAccountIndex` / `affinityGeneration` (the TS clone
+//!   copies only version/accounts/activeIndex/activeIndexByFamily) — TS parity.
+
+use serde_json::json;
+
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::model_family::{MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::AccountStorageV3;
+
+use crate::observability::{CodexCliMetricKey, increment_codex_cli_metric};
+
+fn sync_log() -> ScopedLogger {
+    create_logger("codex-cli-sync")
+}
+
+/// Result of [`sync_account_storage_from_codex_cli`].
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexCliSyncResult {
+    /// The (possibly normalized) storage; `None` when canonical storage was
+    /// missing. When `changed` is false this is the input passed through
+    /// unmodified; when true it is the normalized clone (which, like the TS
+    /// clone, omits `pinnedAccountIndex`/`affinityGeneration`).
+    pub storage: Option<AccountStorageV3>,
+    pub changed: bool,
+}
+
+/// TS `cloneStorage`: copies ONLY version/accounts/activeIndex and coerces a
+/// missing family map to `{}` — pin and affinity generation are dropped.
+fn clone_storage(storage: &AccountStorageV3) -> AccountStorageV3 {
+    let mut next = storage.clone();
+    next.active_index_by_family =
+        Some(storage.active_index_by_family.clone().unwrap_or_default());
+    next.pinned_account_index = None;
+    next.affinity_generation = None;
+    next
+}
+
+/// TS `normalizeStoredFamilyIndexes` — clamp `activeIndex` and each family
+/// index into `[0, count-1]`, keeping absent family keys sparse when the
+/// resolved value equals `activeIndex`.
+fn normalize_stored_family_indexes(storage: &mut AccountStorageV3) {
+    let count = storage.accounts.len() as i64;
+    let normalized_active_index = storage.active_index;
+    let clamped = if count == 0 {
+        0
+    } else {
+        normalized_active_index.clamp(0, count - 1)
+    };
+    if storage.active_index != clamped {
+        storage.active_index = clamped;
+    }
+    let mut families = storage.active_index_by_family.clone().unwrap_or_default();
+    for family in MODEL_FAMILIES {
+        let raw = families.get(family);
+        let has_family_index = raw.is_some();
+        let resolved = raw.unwrap_or(storage.active_index);
+        let family_index = if count == 0 {
+            0
+        } else {
+            resolved.clamp(0, count - 1)
+        };
+        if !has_family_index && family_index == storage.active_index {
+            continue;
+        }
+        families.set(family, Some(family_index));
+    }
+    storage.active_index_by_family = Some(families);
+}
+
+/// Preserves one-way mirror semantics for Codex CLI compatibility state
+/// (TS `syncAccountStorageFromCodexCli`).
+///
+/// Historical reconcile entry point kept for old call sites: it only
+/// normalizes the existing local indexes and never reads or applies Codex CLI
+/// account data.
+pub async fn sync_account_storage_from_codex_cli(
+    current: Option<&AccountStorageV3>,
+) -> CodexCliSyncResult {
+    increment_codex_cli_metric(CodexCliMetricKey::ReconcileAttempts);
+
+    let Some(current) = current else {
+        increment_codex_cli_metric(CodexCliMetricKey::ReconcileNoops);
+        sync_log().debug(
+            "Skipped Codex CLI reconcile because canonical storage is missing",
+            Some(&json!({
+                "operation": "reconcile-storage",
+                "outcome": "canonical-missing",
+            })),
+        );
+        return CodexCliSyncResult {
+            storage: None,
+            changed: false,
+        };
+    };
+
+    let mut next = clone_storage(current);
+    let previous_active = next.active_index;
+    let previous_families = next.active_index_by_family.clone().unwrap_or_default();
+    normalize_stored_family_indexes(&mut next);
+
+    let changed = previous_active != next.active_index
+        || Some(&previous_families) != next.active_index_by_family.as_ref();
+
+    increment_codex_cli_metric(if changed {
+        CodexCliMetricKey::ReconcileChanges
+    } else {
+        CodexCliMetricKey::ReconcileNoops
+    });
+    sync_log().debug(
+        "Skipped Codex CLI authority import; canonical storage remains authoritative",
+        Some(&json!({
+            "operation": "reconcile-storage",
+            "outcome": if changed { "normalized-local-indexes" } else { "canonical-authoritative" },
+            "accountCount": next.accounts.len(),
+        })),
+    );
+
+    CodexCliSyncResult {
+        storage: Some(if changed { next } else { current.clone() }),
+        changed,
+    }
+}
+
+/// Resolve the active account index for a model family
+/// (TS `getActiveSelectionForFamily`): the family entry when present, else
+/// `activeIndex`, clamped into `[0, count-1]` (0 when the pool is empty).
+pub fn get_active_selection_for_family(
+    storage: &AccountStorageV3,
+    family: ModelFamily,
+) -> i64 {
+    let count = storage.accounts.len() as i64;
+    if count == 0 {
+        return 0;
+    }
+    let raw = storage
+        .active_index_by_family
+        .as_ref()
+        .and_then(|families| families.get(family));
+    let normalized_active_index = storage.active_index;
+    let candidate = raw.unwrap_or(normalized_active_index);
+    candidate.clamp(0, count - 1)
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/codex-cli-sync.test.ts — the JS-only NaN/fractional
+// index states cannot be represented in the typed schema, whose lenient
+// deserializer already truncates them; the integer contracts are ported.)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::observability::{
+        get_codex_cli_metrics_snapshot, reset_codex_cli_metrics_for_tests,
+    };
+    use serde_json::json;
+    use serial_test::serial;
+
+    fn storage_from(value: serde_json::Value) -> AccountStorageV3 {
+        serde_json::from_value(value).expect("valid AccountStorageV3 fixture")
+    }
+
+    fn account(id: &str, email: &str, refresh: &str) -> serde_json::Value {
+        json!({
+            "accountId": id,
+            "email": email,
+            "refreshToken": refresh,
+            "addedAt": 1,
+            "lastUsed": 1,
+        })
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn does_not_seed_canonical_storage_from_codex_cli_mirror_files() {
+        reset_codex_cli_metrics_for_tests();
+        let result = sync_account_storage_from_codex_cli(None).await;
+        assert!(!result.changed);
+        assert_eq!(result.storage, None);
+        let metrics = get_codex_cli_metrics_snapshot();
+        assert_eq!(metrics.reconcile_attempts, 1);
+        assert_eq!(metrics.reconcile_noops, 1);
+        reset_codex_cli_metrics_for_tests();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn does_not_merge_or_overwrite_canonical_storage_from_codex_cli_mirrors() {
+        let current = storage_from(json!({
+            "version": 3,
+            "accounts": [account("acc_a", "a@example.com", "refresh-a")],
+            "activeIndex": 0,
+            "activeIndexByFamily": {
+                "gpt-5-codex": 0, "codex-max": 0, "codex": 0, "gpt-5.2": 0, "gpt-5.1": 0,
+            },
+        }));
+
+        let result = sync_account_storage_from_codex_cli(Some(&current)).await;
+        assert!(!result.changed);
+        let storage = result.storage.expect("storage");
+        assert_eq!(storage, current);
+        assert_eq!(storage.accounts, current.accounts);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn normalizes_local_indexes_without_reading_codex_cli_mirror_state() {
+        let current = storage_from(json!({
+            "version": 3,
+            "accounts": [
+                account("acc_a", "a@example.com", "refresh-a"),
+                account("acc_b", "b@example.com", "refresh-b"),
+            ],
+            "activeIndex": 99,
+            "activeIndexByFamily": {"codex": 99},
+        }));
+
+        let result = sync_account_storage_from_codex_cli(Some(&current)).await;
+        assert!(result.changed);
+        let storage = result.storage.expect("storage");
+        assert_ne!(storage, current);
+        assert_eq!(storage.active_index, 1);
+        let families = storage.active_index_by_family.expect("families");
+        assert_eq!(families.codex, Some(1));
+        // Absent family keys resolving to activeIndex stay sparse.
+        for family in MODEL_FAMILIES {
+            if family != ModelFamily::Codex {
+                assert_eq!(families.get(family), None, "{family:?} should be absent");
+            }
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn clamps_negative_active_index_to_0_and_reports_changed() {
+        let current = storage_from(json!({
+            "version": 3,
+            "accounts": [account("acc_a", "a@example.com", "refresh-a")],
+            "activeIndex": 0,
+            "activeIndexByFamily": {"codex": -3},
+        }));
+
+        let result = sync_account_storage_from_codex_cli(Some(&current)).await;
+        assert!(result.changed);
+        let storage = result.storage.expect("storage");
+        assert_eq!(storage.active_index, 0);
+        assert_eq!(
+            storage.active_index_by_family.expect("families").codex,
+            Some(0)
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn does_not_report_changes_when_missing_family_indexes_resolve_to_active_index() {
+        let current = storage_from(json!({
+            "version": 3,
+            "accounts": [account("acc_a", "a@example.com", "refresh-a")],
+            "activeIndex": 0,
+            "activeIndexByFamily": {},
+        }));
+
+        let result = sync_account_storage_from_codex_cli(Some(&current)).await;
+        assert!(!result.changed);
+        assert_eq!(result.storage, Some(current));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn normalized_clone_drops_pin_and_generation_like_the_ts_clone() {
+        let current = storage_from(json!({
+            "version": 3,
+            "accounts": [
+                account("acc_a", "a@example.com", "refresh-a"),
+                account("acc_b", "b@example.com", "refresh-b"),
+            ],
+            "activeIndex": 5,
+            "pinnedAccountIndex": 1,
+            "affinityGeneration": 4,
+        }));
+
+        let result = sync_account_storage_from_codex_cli(Some(&current)).await;
+        assert!(result.changed);
+        let storage = result.storage.expect("storage");
+        assert_eq!(storage.active_index, 1);
+        // TS cloneStorage copies only version/accounts/activeIndex/families.
+        assert_eq!(storage.pinned_account_index, None);
+        assert_eq!(storage.affinity_generation, None);
+    }
+
+    #[test]
+    fn clamps_and_defaults_active_selection_indexes_by_model_family() {
+        let family = MODEL_FAMILIES[0];
+
+        // Empty pool → 0.
+        let empty = storage_from(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 99,
+            "activeIndexByFamily": {},
+        }));
+        assert_eq!(get_active_selection_for_family(&empty, family), 0);
+
+        // Missing family entry falls back to activeIndex.
+        let fallback = storage_from(json!({
+            "version": 3,
+            "accounts": [
+                {"refreshToken": "a", "addedAt": 1, "lastUsed": 1},
+                {"refreshToken": "b", "addedAt": 1, "lastUsed": 1},
+            ],
+            "activeIndex": 1,
+            "activeIndexByFamily": {},
+        }));
+        assert_eq!(get_active_selection_for_family(&fallback, family), 1);
+
+        // Negative family entry clamps to 0.
+        let negative = storage_from(json!({
+            "version": 3,
+            "accounts": [
+                {"refreshToken": "a", "addedAt": 1, "lastUsed": 1},
+                {"refreshToken": "b", "addedAt": 1, "lastUsed": 1},
+            ],
+            "activeIndex": 1,
+            "activeIndexByFamily": {(family.as_str()): -3},
+        }));
+        assert_eq!(get_active_selection_for_family(&negative, family), 0);
+
+        // Overflowing family entry clamps to count-1.
+        let overflow = storage_from(json!({
+            "version": 3,
+            "accounts": [
+                {"refreshToken": "a", "addedAt": 1, "lastUsed": 1},
+                {"refreshToken": "b", "addedAt": 1, "lastUsed": 1},
+                {"refreshToken": "c", "addedAt": 1, "lastUsed": 1},
+            ],
+            "activeIndex": 0,
+            "activeIndexByFamily": {(family.as_str()): 7},
+        }));
+        assert_eq!(get_active_selection_for_family(&overflow, family), 2);
+    }
+}
diff --git a/crates/climirror/src/writer.rs b/crates/climirror/src/writer.rs
new file mode 100644
index 000000000..2a8448f70
--- /dev/null
+++ b/crates/climirror/src/writer.rs
@@ -0,0 +1,1548 @@
+//! Port of `lib/codex-cli/writer.ts` — persist the multi-auth "active account
+//! selection" into the official Codex CLI's `accounts.json` / `auth.json` /
+//! `config.toml` (mirror write).
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §1.4 + §7.1–7.3 (+ gotchas
+//! 3–8, 37); TS source is authoritative.
+//!
+//! Contracts:
+//! - Dual-key writes: snake_case AND camelCase token/id keys at the top level
+//!   and inside `auth.tokens`; triple-written active flags
+//!   (`active`/`isActive`/`is_active`) on EVERY account.
+//! - `OPENAI_API_KEY` is forced to a literal JSON `null` in auth.json.
+//! - `auth_mode` defaults to `"chatgpt"`; `id_token` falls back to the ACCESS
+//!   token when no id token is available (deliberate).
+//! - Partial token pairs hard-fail the auth write (`partial-token-payload`).
+//! - `codexMultiAuthSyncVersion = Date.now()` stamped into every mirror file;
+//!   `getLastCodexCliSelectionWriteTimestamp` is the monotonic max of stamps
+//!   written this process (mtime-echo suppression, gotcha 37).
+//! - `config.toml` gets a LINE-EDIT (string manipulation, no toml crate)
+//!   guaranteeing `cli_auth_credentials_store = "file"` before the first
+//!   `[section]`; unknown fields everywhere are preserved.
+//! - All JSON is 2-space pretty, NO trailing newline, written atomically
+//!   (temp + rename retried 5× on EPERM/EBUSY) with mode 0600.
+
+use std::path::Path;
+use std::sync::LazyLock;
+use std::sync::atomic::{AtomicI64, Ordering};
+
+use serde_json::{Map, Value, json};
+
+use cma_core::json_io::{
+    TrailingNewline, WriteJsonOptions, read_text_file, stringify_pretty2, write_json_atomic,
+};
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::utils::now_ms;
+
+use crate::observability::{
+    CodexCliMetricKey, increment_codex_cli_metric, make_account_fingerprint,
+};
+use crate::state::{
+    clear_codex_cli_state_cache, get_codex_cli_accounts_path, get_codex_cli_auth_path,
+    get_codex_cli_config_path, is_codex_cli_sync_enabled,
+};
+
+fn writer_log() -> ScopedLogger {
+    create_logger("codex-cli-writer")
+}
+
+type DynError = Box<dyn std::error::Error + Send + Sync>;
+
+static LAST_SELECTION_WRITE_AT: AtomicI64 = AtomicI64::new(0);
+/// In-process serialization of all mirror writes (TS promise-chain queue;
+/// tokio's Mutex is FIFO-fair, matching the chain's ordering).
+static WRITE_QUEUE: LazyLock<tokio::sync::Mutex<()>> =
+    LazyLock::new(|| tokio::sync::Mutex::new(()));
+
+/// The selection to mirror into the Codex CLI files (TS `ActiveSelection`).
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ActiveSelection {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub access_token: Option<String>,
+    pub refresh_token: Option<String>,
+    pub expires_at: Option<f64>,
+    pub id_token: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Tolerant value readers (writer.ts deliberately duplicates state.ts's)
+// ---------------------------------------------------------------------------
+
+fn read_trimmed_string(value: Option<&Value>) -> Option<String> {
+    let s = value?.as_str()?;
+    let trimmed = s.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn trimmed_non_empty(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn read_number(value: Option<&Value>) -> Option<f64> {
+    match value? {
+        Value::Number(n) => n.as_f64().filter(|v| v.is_finite()),
+        // JS Number() coercion (Number("") === 0) — shared with state.rs.
+        Value::String(s) => crate::state::js_number_from_str(s).filter(|v| v.is_finite()),
+        _ => None,
+    }
+}
+
+fn extract_token_from_record(record: &Map<String, Value>, keys: &[&str]) -> Option<String> {
+    for key in keys {
+        if let Some(token) = read_trimmed_string(record.get(*key)) {
+            return Some(token);
+        }
+    }
+    None
+}
+
+fn normalize_email(value: Option<&Value>) -> Option<String> {
+    let s = value?.as_str()?;
+    let trimmed = s.trim().to_lowercase();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+fn normalize_email_str(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim().to_lowercase();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+fn read_account_id(record: &Map<String, Value>) -> Option<String> {
+    for key in ["accountId", "account_id", "workspace_id", "organization_id", "id"] {
+        if let Some(Value::String(value)) = record.get(key) {
+            let trimmed = value.trim();
+            if !trimmed.is_empty() {
+                return Some(trimmed.to_string());
+            }
+        }
+    }
+    None
+}
+
+fn as_object(value: Option<&Value>) -> Option<&Map<String, Value>> {
+    value?.as_object()
+}
+
+fn extract_selection_from_account_record(record: &Map<String, Value>) -> ActiveSelection {
+    let auth = as_object(record.get("auth"));
+    let tokens = auth.and_then(|auth| as_object(auth.get("tokens")));
+
+    let access_token = extract_token_from_record(record, &["accessToken", "access_token"])
+        .or_else(|| {
+            tokens.and_then(|tokens| {
+                extract_token_from_record(tokens, &["access_token", "accessToken"])
+            })
+        });
+    let refresh_token = extract_token_from_record(record, &["refreshToken", "refresh_token"])
+        .or_else(|| {
+            tokens.and_then(|tokens| {
+                extract_token_from_record(tokens, &["refresh_token", "refreshToken"])
+            })
+        });
+    let account_id = read_account_id(record).or_else(|| {
+        tokens.and_then(|tokens| {
+            read_trimmed_string(tokens.get("account_id"))
+                .or_else(|| read_trimmed_string(tokens.get("accountId")))
+        })
+    });
+    let id_token = extract_token_from_record(record, &["idToken", "id_token"]).or_else(|| {
+        tokens.and_then(|tokens| extract_token_from_record(tokens, &["id_token", "idToken"]))
+    });
+    let email = normalize_email(record.get("email"))
+        .or_else(|| normalize_email(record.get("user_email")))
+        .or_else(|| normalize_email(record.get("username")));
+    let expires_at = read_number(record.get("expiresAt"))
+        .or_else(|| read_number(record.get("expires_at")))
+        .or_else(|| tokens.and_then(|tokens| read_number(tokens.get("expires_at"))));
+
+    ActiveSelection {
+        account_id,
+        email,
+        access_token,
+        refresh_token,
+        expires_at,
+        id_token,
+    }
+}
+
+/// TS `enrichActiveAccountRecordWithTokens`: returns the record unchanged
+/// unless BOTH an access and a refresh token resolve (no partial token
+/// writes); otherwise duplicates snake+camel token keys at the top level and
+/// rebuilds `auth.tokens` with the same dual-key duplication.
+fn enrich_active_account_record_with_tokens(
+    record: Map<String, Value>,
+    selection: &ActiveSelection,
+) -> Map<String, Value> {
+    let auth = as_object(record.get("auth")).cloned().unwrap_or_default();
+    let tokens = as_object(auth.get("tokens")).cloned().unwrap_or_default();
+
+    let current_access = extract_token_from_record(&record, &["accessToken", "access_token"])
+        .or_else(|| extract_token_from_record(&tokens, &["access_token", "accessToken"]));
+    let current_refresh = extract_token_from_record(&record, &["refreshToken", "refresh_token"])
+        .or_else(|| extract_token_from_record(&tokens, &["refresh_token", "refreshToken"]));
+    let current_id_token = extract_token_from_record(&record, &["idToken", "id_token"])
+        .or_else(|| extract_token_from_record(&tokens, &["id_token", "idToken"]));
+
+    let selected_access = trimmed_non_empty(selection.access_token.as_deref());
+    let selected_refresh = trimmed_non_empty(selection.refresh_token.as_deref());
+    let selected_id_token = trimmed_non_empty(selection.id_token.as_deref());
+    // `selection.accountId?.trim() || readAccountId(record)` — the empty
+    // string is falsy, so it falls through to the record.
+    let account_id = selection
+        .account_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|id| !id.is_empty())
+        .map(str::to_string)
+        .or_else(|| read_account_id(&record));
+    let email = normalize_email_str(selection.email.as_deref())
+        .or_else(|| normalize_email(record.get("email")));
+
+    let access_token = match selected_access.or(current_access) {
+        Some(token) => token,
+        None => return record,
+    };
+    let refresh_token = match selected_refresh.or(current_refresh) {
+        Some(token) => token,
+        None => return record,
+    };
+
+    // Falls back to the ACCESS token when no id token exists (deliberate).
+    let id_token = selected_id_token
+        .or(current_id_token)
+        .unwrap_or_else(|| access_token.clone());
+
+    let mut next = record;
+    next.insert("accessToken".into(), Value::String(access_token.clone()));
+    next.insert("access_token".into(), Value::String(access_token.clone()));
+    next.insert("refreshToken".into(), Value::String(refresh_token.clone()));
+    next.insert("refresh_token".into(), Value::String(refresh_token.clone()));
+    next.insert("idToken".into(), Value::String(id_token.clone()));
+    next.insert("id_token".into(), Value::String(id_token.clone()));
+    if let Some(account_id) = &account_id {
+        next.insert("accountId".into(), Value::String(account_id.clone()));
+        next.insert("account_id".into(), Value::String(account_id.clone()));
+    }
+    if let Some(email) = &email {
+        next.insert("email".into(), Value::String(email.clone()));
+    }
+
+    let mut next_tokens = tokens;
+    next_tokens.insert("access_token".into(), Value::String(access_token.clone()));
+    next_tokens.insert("accessToken".into(), Value::String(access_token));
+    next_tokens.insert("refresh_token".into(), Value::String(refresh_token.clone()));
+    next_tokens.insert("refreshToken".into(), Value::String(refresh_token));
+    next_tokens.insert("id_token".into(), Value::String(id_token.clone()));
+    next_tokens.insert("idToken".into(), Value::String(id_token));
+    if let Some(account_id) = &account_id {
+        next_tokens.insert("account_id".into(), Value::String(account_id.clone()));
+        next_tokens.insert("accountId".into(), Value::String(account_id.clone()));
+    }
+    let mut next_auth = auth;
+    next_auth.insert("tokens".into(), Value::Object(next_tokens));
+    next.insert("auth".into(), Value::Object(next_auth));
+
+    next
+}
+
+/// TS `resolveMatchIndex`: accountId match first (against ALL id-shaped keys
+/// on the entry), then lowercased email equality.
+fn resolve_match_index(accounts: &[Value], selection: &ActiveSelection) -> Option<usize> {
+    let desired_id = trimmed_non_empty(selection.account_id.as_deref());
+    let desired_email = normalize_email_str(selection.email.as_deref());
+
+    if let Some(desired_id) = &desired_id {
+        let by_id = accounts.iter().position(|entry| {
+            entry
+                .as_object()
+                .is_some_and(|record| read_account_id(record).as_deref() == Some(desired_id))
+        });
+        if by_id.is_some() {
+            return by_id;
+        }
+    }
+
+    if let Some(desired_email) = &desired_email {
+        let by_email = accounts.iter().position(|entry| {
+            entry.as_object().is_some_and(|record| {
+                normalize_email(record.get("email")).as_deref() == Some(desired_email)
+            })
+        });
+        if by_email.is_some() {
+            return by_email;
+        }
+    }
+
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Time formatting (Node `new Date(ms).toISOString()` parity)
+// ---------------------------------------------------------------------------
+
+/// Howard Hinnant's civil-from-days algorithm.
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097; // [0, 146096]
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    (if m <= 2 { y + 1 } else { y }, m, d)
+}
+
+fn epoch_ms_to_iso(ms: i64) -> String {
+    let days = ms.div_euclid(86_400_000);
+    let rem = ms.rem_euclid(86_400_000);
+    let (year, month, day) = civil_from_days(days);
+    let millis = rem % 1000;
+    let total_seconds = rem / 1000;
+    let hours = total_seconds / 3600;
+    let minutes = (total_seconds % 3600) / 60;
+    let seconds = total_seconds % 60;
+    format!(
+        "{year:04}-{month:02}-{day:02}T{hours:02}:{minutes:02}:{seconds:02}.{millis:03}Z"
+    )
+}
+
+/// TS `toIsoTime`: ISO string of `ms` when finite and > 0, else "now".
+fn to_iso_time(ms: Option<f64>) -> String {
+    match ms {
+        Some(value) if value.is_finite() && value > 0.0 => epoch_ms_to_iso(value.trunc() as i64),
+        _ => epoch_ms_to_iso(now_ms()),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Atomic writers (TS `atomicWriteText` / `atomicWriteJson`)
+// ---------------------------------------------------------------------------
+
+async fn atomic_write_text(path: &Path, content: &str) -> std::io::Result<()> {
+    // temp at tempPathFor(path), mode 0600, rename retried 5× on EPERM/EBUSY
+    // with 10·2^n ms backoff — the json_io defaults implement exactly this.
+    write_json_atomic(
+        path,
+        content,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::None,
+            ensure_parent_dir: true,
+            ..Default::default()
+        },
+    )
+    .await
+}
+
+async fn atomic_write_json(path: &Path, payload: &Map<String, Value>) -> std::io::Result<()> {
+    atomic_write_text(path, &stringify_pretty2(payload)).await
+}
+
+// ---------------------------------------------------------------------------
+// config.toml line edit (TS `ensureCodexCliFileAuthStore`)
+// ---------------------------------------------------------------------------
+
+fn should_enforce_codex_cli_file_auth_store() -> bool {
+    let value = std::env::var("CODEX_MULTI_AUTH_ENFORCE_CLI_FILE_AUTH_STORE")
+        .unwrap_or_else(|_| "1".to_string());
+    value.trim() != "0"
+}
+
+fn ensure_trailing_newline(value: &str) -> String {
+    if value.ends_with('\n') {
+        value.to_string()
+    } else {
+        format!("{value}\n")
+    }
+}
+
+/// `/^\s*cli_auth_credentials_store\s*=/`
+fn is_auth_store_assignment(line: &str) -> bool {
+    let rest = line.trim_start();
+    match rest.strip_prefix("cli_auth_credentials_store") {
+        Some(after) => after.trim_start().starts_with('='),
+        None => false,
+    }
+}
+
+/// Split on `/\r?\n/` — Node parity: a lone `\r` stays inside its line.
+fn split_lines(raw: &str) -> Vec<String> {
+    raw.split('\n')
+        .map(|line| line.strip_suffix('\r').unwrap_or(line).to_string())
+        .collect()
+}
+
+async fn ensure_codex_cli_file_auth_store(config_path: &Path) -> Result<bool, DynError> {
+    if !should_enforce_codex_cli_file_auth_store() {
+        return Ok(false);
+    }
+
+    const DESIRED: &str = "cli_auth_credentials_store = \"file\"";
+    let raw = if config_path.exists() {
+        read_text_file(config_path)?
+    } else {
+        String::new()
+    };
+    let mut next_lines: Vec<String> = if raw.is_empty() {
+        Vec::new()
+    } else {
+        split_lines(&raw)
+    };
+
+    let mut replaced = false;
+    for line in next_lines.iter_mut() {
+        if !replaced && is_auth_store_assignment(line) {
+            replaced = true;
+            *line = DESIRED.to_string();
+        }
+    }
+
+    if !replaced {
+        let insert_at = next_lines
+            .iter()
+            .position(|line| line.trim_start().starts_with('['))
+            .unwrap_or(next_lines.len());
+        next_lines.insert(insert_at, DESIRED.to_string());
+        if insert_at < next_lines.len() - 1 && !next_lines[insert_at + 1].trim().is_empty() {
+            next_lines.insert(insert_at + 1, String::new());
+        }
+    }
+
+    let next_raw = ensure_trailing_newline(&next_lines.join("\n"));
+    if next_raw == ensure_trailing_newline(&raw) {
+        return Ok(false);
+    }
+
+    atomic_write_text(config_path, &next_raw).await?;
+    Ok(true)
+}
+
+// ---------------------------------------------------------------------------
+// auth.json writer (TS `writeCodexAuthState`)
+// ---------------------------------------------------------------------------
+
+async fn write_codex_auth_state(
+    path: &Path,
+    selection: &ActiveSelection,
+) -> Result<bool, DynError> {
+    let log = writer_log();
+    let raw = if path.exists() {
+        read_text_file(path)?
+    } else {
+        "{}".to_string()
+    };
+    let parsed: Value = serde_json::from_str(&raw)?;
+    let Some(parsed) = parsed.as_object() else {
+        log.warn(
+            "Failed to persist Codex auth selection",
+            Some(&json!({
+                "operation": "write-active-selection",
+                "outcome": "malformed-auth-state",
+                "path": path.display().to_string(),
+            })),
+        );
+        return Ok(false);
+    };
+
+    let existing_tokens = as_object(parsed.get("tokens")).cloned().unwrap_or_default();
+    let mut next = parsed.clone();
+    let mut next_tokens = existing_tokens.clone();
+
+    let sync_version = now_ms();
+    let selected_access_token = trimmed_non_empty(selection.access_token.as_deref());
+    let selected_refresh_token = trimmed_non_empty(selection.refresh_token.as_deref());
+    // Existing tokens use a bare `typeof === "string"` check (no trim/empty
+    // filter) — the empty case is caught by the missing-token guard below.
+    let existing_access_token = existing_tokens
+        .get("access_token")
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    let existing_refresh_token = existing_tokens
+        .get("refresh_token")
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    let has_selected_access = selected_access_token.is_some();
+    let has_selected_refresh = selected_refresh_token.is_some();
+    let selected_token_pair = has_selected_access && has_selected_refresh;
+
+    let (access_token, refresh_token) = if selected_token_pair {
+        (selected_access_token.clone(), selected_refresh_token.clone())
+    } else if !has_selected_access && !has_selected_refresh {
+        (existing_access_token, existing_refresh_token)
+    } else {
+        log.warn(
+            "Failed to persist Codex auth selection",
+            Some(&json!({
+                "operation": "write-active-selection",
+                "outcome": "partial-token-payload",
+                "path": path.display().to_string(),
+                "accountRef": make_account_fingerprint(
+                    selection.account_id.as_deref(),
+                    selection.email.as_deref(),
+                ),
+            })),
+        );
+        return Ok(false);
+    };
+
+    // JS falsy: undefined OR "" both fail here.
+    let (access_token, refresh_token) = match (
+        access_token.filter(|t| !t.is_empty()),
+        refresh_token.filter(|t| !t.is_empty()),
+    ) {
+        (Some(access), Some(refresh)) => (access, refresh),
+        _ => {
+            log.warn(
+                "Failed to persist Codex auth selection",
+                Some(&json!({
+                    "operation": "write-active-selection",
+                    "outcome": "missing-token-payload",
+                    "path": path.display().to_string(),
+                    "accountRef": make_account_fingerprint(
+                        selection.account_id.as_deref(),
+                        selection.email.as_deref(),
+                    ),
+                })),
+            );
+            return Ok(false);
+        }
+    };
+
+    let auth_mode = match parsed.get("auth_mode") {
+        Some(Value::String(mode)) => mode.clone(),
+        _ => "chatgpt".to_string(),
+    };
+    next.insert("auth_mode".into(), Value::String(auth_mode));
+    next.insert("OPENAI_API_KEY".into(), Value::Null);
+    if let Some(selected_email) = normalize_email_str(selection.email.as_deref()) {
+        next.insert("email".into(), Value::String(selected_email));
+    }
+    next_tokens.insert("access_token".into(), Value::String(access_token.clone()));
+    next_tokens.insert("refresh_token".into(), Value::String(refresh_token));
+    if let Some(account_id) = trimmed_non_empty(selection.account_id.as_deref()) {
+        next_tokens.insert("account_id".into(), Value::String(account_id));
+    }
+    let selected_id_token = trimmed_non_empty(selection.id_token.as_deref());
+    let existing_id_token = read_trimmed_string(existing_tokens.get("id_token"));
+    let fallback_id_token = if selected_token_pair {
+        access_token.clone()
+    } else {
+        existing_id_token.unwrap_or_else(|| access_token.clone())
+    };
+    if let Some(selected_id_token) = selected_id_token {
+        next_tokens.insert("id_token".into(), Value::String(selected_id_token));
+    } else if !fallback_id_token.is_empty() {
+        next_tokens.insert("id_token".into(), Value::String(fallback_id_token));
+    }
+    next.insert("tokens".into(), Value::Object(next_tokens));
+    next.insert(
+        "last_refresh".into(),
+        Value::String(to_iso_time(selection.expires_at)),
+    );
+    next.insert("codexMultiAuthSyncVersion".into(), json!(sync_version));
+
+    atomic_write_json(path, &next).await?;
+    LAST_SELECTION_WRITE_AT.fetch_max(sync_version, Ordering::SeqCst);
+    Ok(true)
+}
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+/// Persist the active account selection into the Codex CLI mirror files
+/// (TS `setCodexCliActiveSelection`). Queued in-process; returns `true` only
+/// when the accounts and/or auth file was actually written.
+pub async fn set_codex_cli_active_selection(selection: &ActiveSelection) -> bool {
+    let _queue_guard = WRITE_QUEUE.lock().await;
+    let log = writer_log();
+
+    if !is_codex_cli_sync_enabled() {
+        return false;
+    }
+
+    increment_codex_cli_metric(CodexCliMetricKey::WriteAttempts);
+    let accounts_path = get_codex_cli_accounts_path();
+    let auth_path = get_codex_cli_auth_path();
+    let config_path = get_codex_cli_config_path();
+    let has_accounts_path = accounts_path.exists();
+    let has_auth_path = auth_path.exists();
+    let selection_has_tokens = trimmed_non_empty(selection.access_token.as_deref()).is_some()
+        && trimmed_non_empty(selection.refresh_token.as_deref()).is_some();
+    let require_auth_write = has_auth_path || selection_has_tokens;
+
+    if !has_accounts_path && !has_auth_path && !selection_has_tokens {
+        increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+        return false;
+    }
+
+    match set_active_selection_inner(
+        &log,
+        selection,
+        &accounts_path,
+        &auth_path,
+        &config_path,
+        has_accounts_path,
+        has_auth_path,
+        selection_has_tokens,
+        require_auth_write,
+    )
+    .await
+    {
+        Ok(result) => result,
+        Err(error) => {
+            increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+            log.warn(
+                "Failed to persist Codex CLI active selection",
+                Some(&json!({
+                    "operation": "write-active-selection",
+                    "outcome": "error",
+                    "path": if has_accounts_path {
+                        accounts_path.display().to_string()
+                    } else {
+                        auth_path.display().to_string()
+                    },
+                    "accountRef": make_account_fingerprint(
+                        selection.account_id.as_deref(),
+                        selection.email.as_deref(),
+                    ),
+                    "error": error.to_string(),
+                })),
+            );
+            false
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn set_active_selection_inner(
+    log: &ScopedLogger,
+    selection: &ActiveSelection,
+    accounts_path: &Path,
+    auth_path: &Path,
+    config_path: &Path,
+    has_accounts_path: bool,
+    has_auth_path: bool,
+    selection_has_tokens: bool,
+    require_auth_write: bool,
+) -> Result<bool, DynError> {
+    let mut resolved_selection = selection.clone();
+    let mut wrote_accounts = false;
+    let mut wrote_auth = false;
+    let mut wrote_config = false;
+
+    if has_accounts_path {
+        let raw = read_text_file(accounts_path)?;
+        let parsed: Value = serde_json::from_str(&raw)?;
+        let accounts = parsed
+            .as_object()
+            .and_then(|record| record.get("accounts"))
+            .and_then(Value::as_array)
+            .cloned();
+        match accounts {
+            None => {
+                log.warn(
+                    "Failed to persist Codex CLI active selection",
+                    Some(&json!({
+                        "operation": "write-active-selection",
+                        "outcome": "malformed",
+                        "path": accounts_path.display().to_string(),
+                    })),
+                );
+            }
+            Some(accounts) => {
+                let parsed = parsed.as_object().expect("checked above").clone();
+                match resolve_match_index(&accounts, selection) {
+                    None => {
+                        log.warn(
+                            "Failed to persist Codex CLI active selection",
+                            Some(&json!({
+                                "operation": "write-active-selection",
+                                "outcome": "no-match",
+                                "path": accounts_path.display().to_string(),
+                                "accountRef": make_account_fingerprint(
+                                    selection.account_id.as_deref(),
+                                    selection.email.as_deref(),
+                                ),
+                            })),
+                        );
+                        if !has_auth_path || !selection_has_tokens {
+                            increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+                            return Ok(false);
+                        }
+                    }
+                    Some(match_index) => {
+                        let chosen = accounts[match_index].as_object().cloned();
+                        match chosen {
+                            None => {
+                                log.warn(
+                                    "Failed to persist Codex CLI active selection",
+                                    Some(&json!({
+                                        "operation": "write-active-selection",
+                                        "outcome": "invalid-account-record",
+                                        "path": accounts_path.display().to_string(),
+                                    })),
+                                );
+                                if !has_auth_path {
+                                    increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+                                    return Ok(false);
+                                }
+                            }
+                            Some(chosen) => {
+                                let chosen_selection =
+                                    extract_selection_from_account_record(&chosen);
+                                // Caller-wins merge: the record only fills gaps.
+                                resolved_selection = ActiveSelection {
+                                    account_id: resolved_selection
+                                        .account_id
+                                        .or(chosen_selection.account_id),
+                                    email: resolved_selection.email.or(chosen_selection.email),
+                                    access_token: resolved_selection
+                                        .access_token
+                                        .or(chosen_selection.access_token),
+                                    refresh_token: resolved_selection
+                                        .refresh_token
+                                        .or(chosen_selection.refresh_token),
+                                    expires_at: resolved_selection
+                                        .expires_at
+                                        .or(chosen_selection.expires_at),
+                                    id_token: resolved_selection
+                                        .id_token
+                                        .or(chosen_selection.id_token),
+                                };
+
+                                let mut next = parsed.clone();
+                                let sync_version = now_ms();
+                                // Active-pointer fields prefer the RECORD's
+                                // values over the selection's (deliberate —
+                                // gotcha 8).
+                                let chosen_account_id = read_account_id(&chosen).or_else(|| {
+                                    selection
+                                        .account_id
+                                        .as_deref()
+                                        .map(|id| id.trim().to_string())
+                                });
+                                let chosen_email = normalize_email(chosen.get("email"))
+                                    .or_else(|| normalize_email_str(selection.email.as_deref()));
+
+                                if let Some(id) =
+                                    chosen_account_id.clone().filter(|id| !id.is_empty())
+                                {
+                                    next.insert(
+                                        "activeAccountId".into(),
+                                        Value::String(id.clone()),
+                                    );
+                                    next.insert("active_account_id".into(), Value::String(id));
+                                }
+                                if let Some(email) = chosen_email.clone() {
+                                    next.insert(
+                                        "activeEmail".into(),
+                                        Value::String(email.clone()),
+                                    );
+                                    next.insert("active_email".into(), Value::String(email));
+                                }
+
+                                let next_accounts: Vec<Value> = accounts
+                                    .iter()
+                                    .enumerate()
+                                    .map(|(index, entry)| match entry.as_object() {
+                                        None => entry.clone(),
+                                        Some(record) => {
+                                            let mut updated = record.clone();
+                                            if index == match_index {
+                                                updated = enrich_active_account_record_with_tokens(
+                                                    updated,
+                                                    &resolved_selection,
+                                                );
+                                            }
+                                            let is_match = index == match_index;
+                                            updated.insert("active".into(), Value::Bool(is_match));
+                                            updated
+                                                .insert("isActive".into(), Value::Bool(is_match));
+                                            updated
+                                                .insert("is_active".into(), Value::Bool(is_match));
+                                            Value::Object(updated)
+                                        }
+                                    })
+                                    .collect();
+                                next.insert("accounts".into(), Value::Array(next_accounts));
+                                next.insert("codexMultiAuthSyncVersion".into(), json!(sync_version));
+
+                                atomic_write_json(accounts_path, &next).await?;
+                                LAST_SELECTION_WRITE_AT.fetch_max(sync_version, Ordering::SeqCst);
+                                wrote_accounts = true;
+                                log.debug(
+                                    "Persisted Codex CLI accounts selection",
+                                    Some(&json!({
+                                        "operation": "write-active-selection",
+                                        "outcome": "success",
+                                        "path": accounts_path.display().to_string(),
+                                        "accountRef": make_account_fingerprint(
+                                            chosen_account_id.as_deref(),
+                                            chosen_email.as_deref(),
+                                        ),
+                                    })),
+                                );
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if has_auth_path || wrote_accounts || selection_has_tokens {
+        wrote_auth = write_codex_auth_state(auth_path, &resolved_selection).await?;
+        if !wrote_auth {
+            log.warn(
+                "Codex auth state update skipped after accounts selection update",
+                Some(&json!({
+                    "operation": "write-active-selection",
+                    "outcome": "accounts-updated-auth-failed",
+                    "path": auth_path.display().to_string(),
+                    "accountRef": make_account_fingerprint(
+                        resolved_selection.account_id.as_deref(),
+                        resolved_selection.email.as_deref(),
+                    ),
+                })),
+            );
+            if require_auth_write || !wrote_accounts {
+                increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+                return Ok(false);
+            }
+        } else {
+            log.debug(
+                "Persisted Codex auth active selection",
+                Some(&json!({
+                    "operation": "write-active-selection",
+                    "outcome": "success",
+                    "path": auth_path.display().to_string(),
+                    "accountRef": make_account_fingerprint(
+                        resolved_selection.account_id.as_deref(),
+                        resolved_selection.email.as_deref(),
+                    ),
+                })),
+            );
+        }
+    }
+
+    match ensure_codex_cli_file_auth_store(config_path).await {
+        Ok(updated) => wrote_config = updated,
+        Err(error) => {
+            log.warn(
+                "Failed to persist Codex config file auth store",
+                Some(&json!({
+                    "operation": "write-active-selection",
+                    "outcome": "config-auth-store-update-failed",
+                    "path": config_path.display().to_string(),
+                    "error": error.to_string(),
+                })),
+            );
+        }
+    }
+
+    if wrote_accounts || wrote_auth {
+        clear_codex_cli_state_cache();
+        increment_codex_cli_metric(CodexCliMetricKey::WriteSuccesses);
+        return Ok(true);
+    }
+
+    if wrote_config {
+        log.debug(
+            "Persisted Codex config file auth store override",
+            Some(&json!({
+                "operation": "write-active-selection",
+                "outcome": "config-updated-only",
+                "path": config_path.display().to_string(),
+            })),
+        );
+    }
+
+    increment_codex_cli_metric(CodexCliMetricKey::WriteFailures);
+    Ok(false)
+}
+
+/// Module-level max of the `codexMultiAuthSyncVersion` stamps written this
+/// process (0 initially) — used to ignore mtime echoes of our own mirror
+/// writes (TS `getLastCodexCliSelectionWriteTimestamp`).
+pub fn get_last_codex_cli_selection_write_timestamp() -> i64 {
+    LAST_SELECTION_WRITE_AT.load(Ordering::SeqCst)
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/codex-cli-writer.test.ts + goldens)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::observability::{
+        get_codex_cli_metrics_snapshot, reset_codex_cli_metrics_for_tests,
+    };
+    use cma_testkit::goldens::assert_golden_str;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::fs;
+    use std::path::PathBuf;
+
+    struct WriterFixture {
+        #[allow(dead_code)]
+        sandbox: EnvSandbox,
+        accounts_path: PathBuf,
+        auth_path: PathBuf,
+        config_path: PathBuf,
+    }
+
+    impl WriterFixture {
+        fn new() -> Self {
+            let mut sandbox = EnvSandbox::new();
+            let accounts_path = sandbox.root().join("accounts.json");
+            let auth_path = sandbox.root().join("auth.json");
+            let config_path = sandbox.root().join("config.toml");
+            sandbox.set_var("CODEX_CLI_ACCOUNTS_PATH", &accounts_path);
+            sandbox.set_var("CODEX_CLI_AUTH_PATH", &auth_path);
+            sandbox.set_var("CODEX_CLI_CONFIG_PATH", &config_path);
+            sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "1");
+            sandbox.set_var("CODEX_MULTI_AUTH_ENFORCE_CLI_FILE_AUTH_STORE", "1");
+            clear_codex_cli_state_cache();
+            reset_codex_cli_metrics_for_tests();
+            WriterFixture {
+                sandbox,
+                accounts_path,
+                auth_path,
+                config_path,
+            }
+        }
+
+        fn write_accounts(&self, value: &Value) {
+            fs::write(&self.accounts_path, stringify_pretty2(value)).unwrap();
+        }
+
+        fn write_auth(&self, value: &Value) {
+            fs::write(&self.auth_path, stringify_pretty2(value)).unwrap();
+        }
+
+        fn read_json(&self, path: &Path) -> Value {
+            serde_json::from_str(&fs::read_to_string(path).unwrap()).unwrap()
+        }
+    }
+
+    impl Drop for WriterFixture {
+        fn drop(&mut self) {
+            clear_codex_cli_state_cache();
+            reset_codex_cli_metrics_for_tests();
+        }
+    }
+
+    fn selection(fields: &[(&str, &str)]) -> ActiveSelection {
+        let mut sel = ActiveSelection::default();
+        for (key, value) in fields {
+            match *key {
+                "accountId" => sel.account_id = Some((*value).to_string()),
+                "email" => sel.email = Some((*value).to_string()),
+                "accessToken" => sel.access_token = Some((*value).to_string()),
+                "refreshToken" => sel.refresh_token = Some((*value).to_string()),
+                "idToken" => sel.id_token = Some((*value).to_string()),
+                _ => panic!("unknown selection field {key}"),
+            }
+        }
+        sel
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_when_neither_accounts_nor_auth_exists() {
+        let fx = WriterFixture::new();
+        let updated =
+            set_codex_cli_active_selection(&selection(&[("accountId", "missing")])).await;
+        assert!(!updated);
+        assert!(get_codex_cli_metrics_snapshot().write_failures >= 1);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn creates_auth_json_when_missing_and_selection_includes_tokens() {
+        let fx = WriterFixture::new();
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_new"),
+            ("email", "new@example.com"),
+            ("accessToken", "new-access"),
+            ("refreshToken", "new-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["email"], "new@example.com");
+        assert_eq!(auth["tokens"]["access_token"], "new-access");
+        // id_token falls back to the ACCESS token (deliberate).
+        assert_eq!(auth["tokens"]["id_token"], "new-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "new-refresh");
+        assert_eq!(auth["tokens"]["account_id"], "acc_new");
+        assert_eq!(auth["OPENAI_API_KEY"], Value::Null);
+        assert_eq!(auth["auth_mode"], "chatgpt");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn forces_file_backed_codex_auth_store_in_config_toml() {
+        let fx = WriterFixture::new();
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_new"),
+            ("email", "new@example.com"),
+            ("accessToken", "new-access"),
+            ("refreshToken", "new-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let written_config = fs::read_to_string(&fx.config_path).unwrap();
+        assert!(written_config.contains("cli_auth_credentials_store = \"file\""));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn config_line_edit_replaces_existing_assignment_and_inserts_before_first_section() {
+        let fx = WriterFixture::new();
+        fx.write_auth(&json!({"auth_mode": "chatgpt", "tokens": {
+            "access_token": "a", "refresh_token": "r",
+        }}));
+
+        // Existing assignment (any value) is replaced in place.
+        fs::write(
+            &fx.config_path,
+            "model = \"gpt-5.2\"\ncli_auth_credentials_store = \"keyring\"\n\n[tools]\nweb_search = true\n",
+        )
+        .unwrap();
+        assert!(set_codex_cli_active_selection(&selection(&[("accountId", "x")])).await);
+        let config = fs::read_to_string(&fx.config_path).unwrap();
+        assert_eq!(
+            config,
+            "model = \"gpt-5.2\"\ncli_auth_credentials_store = \"file\"\n\n[tools]\nweb_search = true\n"
+        );
+
+        // No assignment: inserted before the first [section] with a blank line.
+        fs::write(
+            &fx.config_path,
+            "model = \"gpt-5.2\"\n[tools]\nweb_search = true\n",
+        )
+        .unwrap();
+        assert!(set_codex_cli_active_selection(&selection(&[("accountId", "x")])).await);
+        let config = fs::read_to_string(&fx.config_path).unwrap();
+        assert_eq!(
+            config,
+            "model = \"gpt-5.2\"\ncli_auth_credentials_store = \"file\"\n\n[tools]\nweb_search = true\n"
+        );
+
+        // Idempotent: a second write leaves the file byte-identical.
+        assert!(set_codex_cli_active_selection(&selection(&[("accountId", "x")])).await);
+        assert_eq!(fs::read_to_string(&fx.config_path).unwrap(), config);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn enforcement_opt_out_skips_the_config_toml_edit() {
+        let mut fx = WriterFixture::new();
+        fx.sandbox
+            .set_var("CODEX_MULTI_AUTH_ENFORCE_CLI_FILE_AUTH_STORE", "0");
+        fx.write_auth(&json!({"auth_mode": "chatgpt", "tokens": {
+            "access_token": "a", "refresh_token": "r",
+        }}));
+        assert!(set_codex_cli_active_selection(&selection(&[("accountId", "x")])).await);
+        assert!(!fx.config_path.exists());
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn matches_by_email_preserves_non_record_entries_and_writes_string_expires_at_as_iso() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                "noise-entry",
+                {"accountId": 123, "email": "target@example.com",
+                 "expires_at": "1710000000000",
+                 "auth": {"tokens": {"access_token": "target-access",
+                                      "refresh_token": "target-refresh"}}},
+                {"accountId": "acc_other", "email": "other@example.com",
+                 "auth": {"tokens": {"access_token": "other-access",
+                                      "refresh_token": "other-refresh"}}},
+            ],
+        }));
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "tokens": {"access_token": "old-access", "id_token": "old-id",
+                        "refresh_token": "old-refresh"},
+        }));
+
+        let updated =
+            set_codex_cli_active_selection(&selection(&[("email", "TARGET@EXAMPLE.COM")])).await;
+        assert!(updated);
+
+        let accounts = fx.read_json(&fx.accounts_path);
+        assert_eq!(accounts["activeEmail"], "target@example.com");
+        assert_eq!(accounts["accounts"][0], "noise-entry");
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["email"], "target@example.com");
+        assert_eq!(auth["tokens"]["access_token"], "target-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "target-refresh");
+        // new Date(1710000000000).toISOString()
+        assert_eq!(auth["last_refresh"], "2024-03-09T16:00:00.000Z");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_for_malformed_auth_payload_objects() {
+        let fx = WriterFixture::new();
+        fs::write(&fx.auth_path, "[]").unwrap();
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_a"),
+            ("accessToken", "access-a"),
+            ("refreshToken", "refresh-a"),
+        ]))
+        .await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_when_auth_payload_has_no_usable_tokens() {
+        let fx = WriterFixture::new();
+        fx.write_auth(&json!({"tokens": {}}));
+        let updated = set_codex_cli_active_selection(&selection(&[("accountId", "acc_a")])).await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_when_accounts_payload_cannot_be_parsed() {
+        let fx = WriterFixture::new();
+        fs::write(&fx.accounts_path, "{ not-json").unwrap();
+        let updated = set_codex_cli_active_selection(&selection(&[("accountId", "acc_a")])).await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn uses_auth_token_fallback_and_default_auth_mode_when_selected_account_lacks_tokens() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({"accounts": [{"accountId": "acc_a"}]}));
+        fx.write_auth(&json!({
+            "auth_mode": 123,
+            "tokens": {"access_token": "fallback-access",
+                        "refresh_token": "fallback-refresh",
+                        "id_token": "fallback-id"},
+        }));
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_a"),
+            ("email", "fallback@example.com"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let accounts = fx.read_json(&fx.accounts_path);
+        assert_eq!(accounts["activeEmail"], "fallback@example.com");
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["auth_mode"], "chatgpt");
+        assert_eq!(auth["email"], "fallback@example.com");
+        assert_eq!(auth["tokens"]["access_token"], "fallback-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "fallback-refresh");
+        assert_eq!(auth["tokens"]["id_token"], "fallback-id");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn writes_auth_from_explicit_selection_when_persisted_tokens_payload_is_not_an_object() {
+        let fx = WriterFixture::new();
+        fx.write_auth(&json!({"auth_mode": "chatgpt", "tokens": []}));
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_direct"),
+            ("email", "direct@example.com"),
+            ("accessToken", "direct-access"),
+            ("refreshToken", "direct-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["email"], "direct@example.com");
+        assert_eq!(auth["tokens"]["account_id"], "acc_direct");
+        assert_eq!(auth["tokens"]["access_token"], "direct-access");
+        assert_eq!(auth["tokens"]["id_token"], "direct-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "direct-refresh");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn falls_back_id_token_to_selected_access_token_when_id_token_is_missing() {
+        let fx = WriterFixture::new();
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "email": "old@example.com",
+            "tokens": {"access_token": "old-access", "refresh_token": "old-refresh",
+                        "id_token": "old-id-token"},
+        }));
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_new"),
+            ("email", "new@example.com"),
+            ("accessToken", "new-access"),
+            ("refreshToken", "new-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["email"], "new@example.com");
+        assert_eq!(auth["tokens"]["account_id"], "acc_new");
+        assert_eq!(auth["tokens"]["access_token"], "new-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "new-refresh");
+        // Full new pair → id_token re-anchors to the NEW access token, not the
+        // stale persisted one.
+        assert_eq!(auth["tokens"]["id_token"], "new-access");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn enriches_active_accounts_entry_with_complete_token_payload_including_id_token() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com"},
+                {"accountId": "acc_b", "email": "b@example.com"},
+            ],
+        }));
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "tokens": {"access_token": "old-access", "refresh_token": "old-refresh",
+                        "id_token": "old-id"},
+        }));
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_b"),
+            ("email", "B@EXAMPLE.COM"),
+            ("accessToken", "fresh-access"),
+            ("refreshToken", "fresh-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let accounts = fx.read_json(&fx.accounts_path);
+        let active = accounts["accounts"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|entry| entry["active"] == Value::Bool(true))
+            .expect("active entry");
+        assert_eq!(active["accountId"], "acc_b");
+        assert_eq!(active["email"], "b@example.com");
+        assert_eq!(active["auth"]["tokens"]["access_token"], "fresh-access");
+        assert_eq!(active["auth"]["tokens"]["refresh_token"], "fresh-refresh");
+        assert_eq!(active["auth"]["tokens"]["id_token"], "fresh-access");
+        // The other entry gets the triple-written inactive flags.
+        let inactive = &accounts["accounts"][0];
+        assert_eq!(inactive["active"], Value::Bool(false));
+        assert_eq!(inactive["isActive"], Value::Bool(false));
+        assert_eq!(inactive["is_active"], Value::Bool(false));
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn surfaces_auth_path_errors_when_accounts_file_is_absent() {
+        let fx = WriterFixture::new();
+        fs::write(&fx.auth_path, "{not-json").unwrap();
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_only_auth"),
+            ("accessToken", "a"),
+            ("refreshToken", "r"),
+        ]))
+        .await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn rejects_partial_token_payloads_to_avoid_mixing_stale_auth_tokens() {
+        let fx = WriterFixture::new();
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "tokens": {"access_token": "old-access", "refresh_token": "old-refresh",
+                        "account_id": "old-account"},
+        }));
+        let before = fs::read_to_string(&fx.auth_path).unwrap();
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_partial"),
+            ("email", "partial@example.com"),
+            ("accessToken", "new-access-only"),
+        ]))
+        .await;
+        assert!(!updated);
+
+        let after = fs::read_to_string(&fx.auth_path).unwrap();
+        assert_eq!(after, before, "partial pair must not half-update auth.json");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn still_updates_auth_json_when_accounts_json_has_no_match() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [{"accountId": "acc_a", "email": "a@example.com",
+                           "auth": {"tokens": {"access_token": "access-a",
+                                                "refresh_token": "refresh-a"}}}],
+        }));
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "OPENAI_API_KEY": null,
+            "tokens": {"access_token": "old-access", "id_token": "old-id-token",
+                        "refresh_token": "old-refresh", "account_id": "old-account"},
+        }));
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "missing-account"),
+            ("email", "b@example.com"),
+            ("accessToken", "fresh-access"),
+            ("refreshToken", "fresh-refresh"),
+        ]))
+        .await;
+        assert!(updated);
+
+        let auth = fx.read_json(&fx.auth_path);
+        assert_eq!(auth["email"], "b@example.com");
+        assert_eq!(auth["tokens"]["access_token"], "fresh-access");
+        assert_eq!(auth["tokens"]["id_token"], "fresh-access");
+        assert_eq!(auth["tokens"]["refresh_token"], "fresh-refresh");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn does_not_update_auth_json_when_no_match_and_selection_lacks_tokens() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [{"accountId": "acc_a", "email": "a@example.com",
+                           "auth": {"tokens": {"access_token": "access-a",
+                                                "refresh_token": "refresh-a"}}}],
+        }));
+        fx.write_auth(&json!({
+            "auth_mode": "chatgpt",
+            "OPENAI_API_KEY": null,
+            "tokens": {"access_token": "old-access", "id_token": "old-id-token",
+                        "refresh_token": "old-refresh", "account_id": "old-account"},
+        }));
+        let before = fs::read_to_string(&fx.auth_path).unwrap();
+
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "missing-account"),
+            ("email", "b@example.com"),
+        ]))
+        .await;
+        assert!(!updated);
+        assert_eq!(fs::read_to_string(&fx.auth_path).unwrap(), before);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_when_writer_sync_is_disabled() {
+        let mut fx = WriterFixture::new();
+        fx.sandbox.set_var("CODEX_MULTI_AUTH_SYNC_CODEX_CLI", "0");
+        fx.write_accounts(&json!({
+            "accounts": [{"accountId": "acc_a", "email": "a@example.com",
+                           "auth": {"tokens": {"access_token": "a.b.c",
+                                                "refresh_token": "refresh-a"}}}],
+        }));
+        let updated = set_codex_cli_active_selection(&selection(&[("accountId", "acc_a")])).await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_for_malformed_writer_payload() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({"accounts": {"accountId": "acc_a"}}));
+        let updated = set_codex_cli_active_selection(&selection(&[("accountId", "acc_a")])).await;
+        assert!(!updated);
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_false_when_auth_state_exists_but_cannot_be_persisted() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+                {"accountId": "acc_b", "email": "b@example.com",
+                 "auth": {"tokens": {"access_token": "x.y.z", "refresh_token": "refresh-b"}}},
+            ],
+        }));
+        fs::write(&fx.auth_path, stringify_pretty2(&json!([]))).unwrap();
+
+        let updated = set_codex_cli_active_selection(&selection(&[("accountId", "acc_b")])).await;
+        assert!(!updated);
+
+        // The accounts write itself still landed before the auth failure.
+        let accounts = fx.read_json(&fx.accounts_path);
+        assert_eq!(accounts["activeAccountId"], "acc_b");
+        assert_eq!(accounts["activeEmail"], "b@example.com");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn persists_active_selection_by_email_match_when_account_id_is_omitted() {
+        let fx = WriterFixture::new();
+        fx.write_accounts(&json!({
+            "accounts": [
+                {"accountId": "acc_a", "email": "a@example.com",
+                 "auth": {"tokens": {"access_token": "a.b.c", "refresh_token": "refresh-a"}}},
+                {"accountId": "acc_b", "email": "b@example.com",
+                 "auth": {"tokens": {"access_token": "x.y.z", "refresh_token": "refresh-b"}}},
+            ],
+        }));
+
+        let updated =
+            set_codex_cli_active_selection(&selection(&[("email", "B@EXAMPLE.COM")])).await;
+        assert!(updated);
+        let accounts = fx.read_json(&fx.accounts_path);
+        assert_eq!(accounts["activeAccountId"], "acc_b");
+        assert_eq!(accounts["activeEmail"], "b@example.com");
+        drop(fx);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn write_timestamp_is_the_monotonic_max_of_stamps_written_this_process() {
+        let fx = WriterFixture::new();
+        let before = get_last_codex_cli_selection_write_timestamp();
+        let updated = set_codex_cli_active_selection(&selection(&[
+            ("accountId", "acc_new"),
+            ("accessToken", "a"),
+            ("refreshToken", "r"),
+        ]))
+        .await;
+        assert!(updated);
+        let after = get_last_codex_cli_selection_write_timestamp();
+        assert!(after >= before);
+        assert!(after > 0);
+        drop(fx);
+    }
+
+    #[test]
+    fn iso_time_formatting_matches_node_to_iso_string() {
+        assert_eq!(epoch_ms_to_iso(0), "1970-01-01T00:00:00.000Z");
+        assert_eq!(epoch_ms_to_iso(1_710_000_000_000), "2024-03-09T16:00:00.000Z");
+        assert_eq!(epoch_ms_to_iso(1_750_003_600_000), "2025-06-15T16:06:40.000Z");
+        // Non-finite / non-positive expiresAt falls back to "now" (only shape
+        // is asserted — the value is clock-dependent).
+        let now_iso = to_iso_time(None);
+        assert_eq!(now_iso.len(), 24);
+        assert!(now_iso.ends_with('Z'));
+        assert_eq!(to_iso_time(Some(1_710_000_000_000.0)), "2024-03-09T16:00:00.000Z");
+        assert_eq!(to_iso_time(Some(0.0)).len(), 24);
+    }
+
+    // -----------------------------------------------------------------------
+    // Golden byte tests — reproduce crates/testkit/goldens/generate.mjs
+    // scenario 15+16 exactly, then normalize only the clock-stamped field.
+    // -----------------------------------------------------------------------
+
+    const T0: i64 = 1_750_000_000_000;
+    const EXPIRES_AT: f64 = 1_750_003_600_000.0;
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn golden_mirror_write_matches_ts_byte_output() {
+        let fx = WriterFixture::new();
+        // Seeded INPUT from generate.mjs: a pre-existing Codex CLI
+        // accounts.json with stale tokens and account two active.
+        fx.write_accounts(&json!({
+            "accounts": [
+                {
+                    "accountId": "acct-user-one",
+                    "email": "user.one@example.com",
+                    "access_token": "at-old-cli-one",
+                    "refresh_token": "rt-old-cli-one",
+                    "id_token": "idt-old-cli-one",
+                    "active": false,
+                },
+                {
+                    "accountId": "acct-user-two",
+                    "email": "user.two@example.com",
+                    "access_token": "at-old-cli-two",
+                    "refresh_token": "rt-old-cli-two",
+                    "id_token": "idt-old-cli-two",
+                    "active": true,
+                },
+            ],
+            "activeAccountId": "acct-user-two",
+            "active_account_id": "acct-user-two",
+        }));
+
+        let wrote = set_codex_cli_active_selection(&ActiveSelection {
+            account_id: Some("acct-user-one".to_string()),
+            email: Some("user.one@example.com".to_string()),
+            access_token: Some("at-fixture-account-one-0000000001".to_string()),
+            refresh_token: Some("rt-fixture-account-one-0000000001".to_string()),
+            expires_at: Some(EXPIRES_AT),
+            id_token: Some("idt-fixture-account-one-0000000001".to_string()),
+        })
+        .await;
+        assert!(wrote, "setCodexCliActiveSelection reported failure");
+
+        // Post-process exactly like the generator: replace the Date.now()
+        // stamp with T0, re-serialize with the same serializer, byte-compare.
+        let mut accounts: Value =
+            serde_json::from_str(&fs::read_to_string(&fx.accounts_path).unwrap()).unwrap();
+        accounts["codexMultiAuthSyncVersion"] = json!(T0);
+        assert_golden_str("codex-cli-accounts.json", &stringify_pretty2(&accounts));
+
+        let mut auth: Value =
+            serde_json::from_str(&fs::read_to_string(&fx.auth_path).unwrap()).unwrap();
+        auth["codexMultiAuthSyncVersion"] = json!(T0);
+        assert_golden_str("codex-cli-auth.json", &stringify_pretty2(&auth));
+        drop(fx);
+    }
+}
diff --git a/crates/config/Cargo.toml b/crates/config/Cargo.toml
new file mode 100644
index 000000000..bde1cd4f6
--- /dev/null
+++ b/crates/config/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "cma-config"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde.workspace = true
+serde_json.workspace = true
+uuid.workspace = true
+tokio.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/config/src/config_schema.rs b/crates/config/src/config_schema.rs
new file mode 100644
index 000000000..d9df8fe9d
--- /dev/null
+++ b/crates/config/src/config_schema.rs
@@ -0,0 +1,308 @@
+//! R5 drift guard for `config/schema/config.schema.json` (spec 01 §4.7,
+//! ARCHITECTURE.md decision R5).
+//!
+//! The committed JSON schema stays a golden fixture generated by the TS tool
+//! (`npm run generate:schema`). Rust does NOT re-implement the byte-exact
+//! zod→JSON-schema generator; instead this module validates that the serde
+//! `PluginConfig` model (field names, declaration ORDER, and per-field
+//! bounds) matches the fixture, so schema drift in either direction fails a
+//! test.
+//!
+//! The bound checks are black-box probes against
+//! `cma_core::schemas::plugin_config::validate_field`: for each schema
+//! property the declared type/enum/minimum/maximum is exercised with
+//! accepting and rejecting values, proving the serde model enforces exactly
+//! the committed constraints.
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{Map, Value, json};
+
+use cma_core::json_io::{ReadJsonError, read_json_file};
+use cma_core::schemas::plugin_config::{PLUGIN_CONFIG_KEYS, validate_field};
+
+/// Repo-relative path of the committed, generated schema file (mirrors the TS
+/// `CONFIG_SCHEMA_RELATIVE_PATH`).
+pub const CONFIG_SCHEMA_RELATIVE_PATH: &str = "config/schema/config.schema.json";
+
+/// Absolute path of the committed fixture, anchored at the workspace root
+/// (`crates/config/../..`).
+pub fn committed_config_schema_path() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .join(CONFIG_SCHEMA_RELATIVE_PATH)
+}
+
+/// Load and parse the committed schema fixture.
+pub fn load_committed_config_schema() -> Result<Value, ReadJsonError> {
+    read_json_file(&committed_config_schema_path())
+}
+
+fn push_issue(issues: &mut Vec<String>, message: impl Into<String>) {
+    issues.push(message.into());
+}
+
+fn probe_accepts(key: &str, value: &Value) -> bool {
+    validate_field(key, value).is_some()
+}
+
+/// Check one schema property definition against the serde model's per-field
+/// validator.
+fn check_property(key: &str, definition: &Map<String, Value>, issues: &mut Vec<String>) {
+    // The chain field has a bespoke record shape.
+    if key == "unsupportedCodexFallbackChain" {
+        if definition.get("type").and_then(Value::as_str) != Some("object") {
+            push_issue(issues, format!("{key}: fixture type is not \"object\""));
+        }
+        let min_length = definition
+            .get("additionalProperties")
+            .and_then(|ap| ap.get("items"))
+            .and_then(|items| items.get("minLength"))
+            .and_then(Value::as_i64);
+        if min_length != Some(1) {
+            push_issue(
+                issues,
+                format!("{key}: fixture no longer requires non-empty chain targets"),
+            );
+        }
+        for (probe, should_accept) in [
+            (json!({ "a": ["b"] }), true),
+            (json!({}), true),
+            (json!({ "a": [""] }), false),
+            (json!({ "a": "b" }), false),
+            (json!(["a"]), false),
+            (json!("x"), false),
+        ] {
+            if probe_accepts(key, &probe) != should_accept {
+                push_issue(
+                    issues,
+                    format!(
+                        "{key}: serde model {} {probe} but the fixture says it should {}",
+                        if should_accept { "rejects" } else { "accepts" },
+                        if should_accept { "be accepted" } else { "be rejected" },
+                    ),
+                );
+            }
+        }
+        return;
+    }
+
+    if let Some(options) = definition.get("enum").and_then(Value::as_array) {
+        // Enum property: every fixture option accepted; foreign values and
+        // non-strings rejected.
+        if definition.get("type").and_then(Value::as_str) != Some("string") {
+            push_issue(issues, format!("{key}: fixture enum is not string-typed"));
+        }
+        for option in options {
+            if !probe_accepts(key, option) {
+                push_issue(
+                    issues,
+                    format!("{key}: serde model rejects fixture enum option {option}"),
+                );
+            }
+        }
+        if probe_accepts(key, &json!("__drift_probe__")) {
+            push_issue(
+                issues,
+                format!("{key}: serde model accepts values outside the fixture enum"),
+            );
+        }
+        if probe_accepts(key, &json!(0)) {
+            push_issue(issues, format!("{key}: serde model accepts non-strings"));
+        }
+        return;
+    }
+
+    match definition.get("type").and_then(Value::as_str) {
+        Some("boolean") => {
+            if !probe_accepts(key, &json!(true)) || !probe_accepts(key, &json!(false)) {
+                push_issue(issues, format!("{key}: serde model rejects booleans"));
+            }
+            if probe_accepts(key, &json!(1)) || probe_accepts(key, &json!("true")) {
+                push_issue(
+                    issues,
+                    format!("{key}: serde model accepts non-boolean values"),
+                );
+            }
+        }
+        Some("number") => {
+            let minimum = definition.get("minimum").and_then(Value::as_f64);
+            let maximum = definition.get("maximum").and_then(Value::as_f64);
+            let Some(minimum) = minimum else {
+                push_issue(
+                    issues,
+                    format!("{key}: fixture numeric property lost its minimum"),
+                );
+                return;
+            };
+            if !probe_accepts(key, &json!(minimum)) {
+                push_issue(
+                    issues,
+                    format!("{key}: serde model rejects the fixture minimum {minimum}"),
+                );
+            }
+            if probe_accepts(key, &json!(minimum - 1.0)) {
+                push_issue(
+                    issues,
+                    format!("{key}: serde model accepts values below the fixture minimum {minimum}"),
+                );
+            }
+            match maximum {
+                Some(maximum) => {
+                    if !probe_accepts(key, &json!(maximum)) {
+                        push_issue(
+                            issues,
+                            format!("{key}: serde model rejects the fixture maximum {maximum}"),
+                        );
+                    }
+                    if probe_accepts(key, &json!(maximum + 1.0)) {
+                        push_issue(
+                            issues,
+                            format!(
+                                "{key}: serde model accepts values above the fixture maximum {maximum}"
+                            ),
+                        );
+                    }
+                }
+                None => {
+                    if !probe_accepts(key, &json!(minimum + 1.0e15)) {
+                        push_issue(
+                            issues,
+                            format!("{key}: serde model enforces a maximum the fixture lacks"),
+                        );
+                    }
+                }
+            }
+            if probe_accepts(key, &json!("123")) {
+                push_issue(issues, format!("{key}: serde model accepts numeric strings"));
+            }
+        }
+        other => push_issue(
+            issues,
+            format!("{key}: unexpected fixture property type {other:?}"),
+        ),
+    }
+}
+
+/// Compare the committed schema against the serde `PluginConfig` model.
+/// Returns a list of human-readable drift findings; empty = no drift.
+pub fn plugin_config_schema_drift(schema: &Value) -> Vec<String> {
+    let mut issues = Vec::new();
+
+    let Some(properties) = schema
+        .get("$defs")
+        .and_then(|defs| defs.get("pluginConfig"))
+        .and_then(|def| def.get("properties"))
+        .and_then(Value::as_object)
+    else {
+        return vec!["$defs.pluginConfig.properties missing from the committed schema".to_string()];
+    };
+
+    // Field NAMES and ORDER must match the serde declaration order exactly
+    // (zod shape order == serde struct order).
+    let fixture_keys: Vec<&str> = properties.keys().map(String::as_str).collect();
+    let model_keys: Vec<&str> = PLUGIN_CONFIG_KEYS.to_vec();
+    if fixture_keys != model_keys {
+        push_issue(
+            &mut issues,
+            format!(
+                "property name/order drift: fixture {fixture_keys:?} vs serde model {model_keys:?}"
+            ),
+        );
+    }
+
+    for (key, definition) in properties {
+        let Some(definition) = definition.as_object() else {
+            push_issue(&mut issues, format!("{key}: property definition is not an object"));
+            continue;
+        };
+        check_property(key, definition, &mut issues);
+    }
+
+    // Root skeleton sanity: the runtime tolerates unknown keys, so the
+    // generated definition must NOT emit additionalProperties:false
+    // (zod io:"input" semantics — spec 01 §4.7).
+    if let Some(plugin_config_def) = schema.get("$defs").and_then(|d| d.get("pluginConfig"))
+        && plugin_config_def.get("additionalProperties") == Some(&Value::Bool(false))
+    {
+        push_issue(
+            &mut issues,
+            "pluginConfig definition emits additionalProperties:false (io:\"input\" drift)",
+        );
+    }
+
+    issues
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn committed_schema_matches_the_serde_model() {
+        let schema = load_committed_config_schema()
+            .unwrap_or_else(|error| panic!("failed to read {CONFIG_SCHEMA_RELATIVE_PATH}: {error}"));
+        let drift = plugin_config_schema_drift(&schema);
+        assert!(
+            drift.is_empty(),
+            "config schema drift detected:\n{}",
+            drift.join("\n")
+        );
+    }
+
+    #[test]
+    fn committed_schema_root_skeleton_is_intact() {
+        let schema = load_committed_config_schema().expect("fixture readable");
+        assert_eq!(
+            schema.get("$schema").and_then(Value::as_str),
+            Some("https://json-schema.org/draft/2020-12/schema")
+        );
+        assert_eq!(
+            schema.get("$id").and_then(Value::as_str),
+            Some("https://codex-multi-auth.local/schema/config.schema.json")
+        );
+        assert_eq!(
+            schema.get("title").and_then(Value::as_str),
+            Some("codex-multi-auth config template")
+        );
+        assert_eq!(
+            schema.get("required"),
+            Some(&serde_json::json!(["plugin", "provider"]))
+        );
+        assert_eq!(schema.get("additionalProperties"), Some(&Value::Bool(true)));
+        assert_eq!(
+            schema
+                .get("properties")
+                .and_then(|p| p.get("pluginConfig"))
+                .and_then(|p| p.get("$ref"))
+                .and_then(Value::as_str),
+            Some("#/$defs/pluginConfig")
+        );
+    }
+
+    #[test]
+    fn drift_detector_flags_a_tampered_schema() {
+        let schema = load_committed_config_schema().expect("fixture readable");
+
+        // Removing a property must be reported.
+        let mut missing = schema.clone();
+        missing["$defs"]["pluginConfig"]["properties"]
+            .as_object_mut()
+            .unwrap()
+            .shift_remove("codexMode");
+        assert!(!plugin_config_schema_drift(&missing).is_empty());
+
+        // Changing a bound must be reported.
+        let mut wrong_bound = schema.clone();
+        wrong_bound["$defs"]["pluginConfig"]["properties"]["toastDurationMs"]["minimum"] =
+            serde_json::json!(500);
+        assert!(!plugin_config_schema_drift(&wrong_bound).is_empty());
+
+        // Changing an enum must be reported.
+        let mut wrong_enum = schema;
+        wrong_enum["$defs"]["pluginConfig"]["properties"]["routingMutex"]["enum"] =
+            serde_json::json!(["enabled", "legacy", "extra"]);
+        assert!(!plugin_config_schema_drift(&wrong_enum).is_empty());
+    }
+}
diff --git a/crates/config/src/dashboard_settings.rs b/crates/config/src/dashboard_settings.rs
new file mode 100644
index 000000000..bcf0a10b3
--- /dev/null
+++ b/crates/config/src/dashboard_settings.rs
@@ -0,0 +1,624 @@
+//! Port of `lib/dashboard-settings.ts` — dashboard display settings:
+//! normalization (clamps/enums/defaults), load from unified settings with a
+//! one-time migration from the legacy `dashboard-settings.json`.
+//!
+//! Gotcha 9 (layout-mode derivation): `menuShowDetailsForUnselectedRows` is
+//! an OUTPUT derived from `menuLayoutMode` — the input boolean only serves as
+//! the legacy fallback hint:
+//! `derived = menuLayoutMode == "expanded-rows" ? expanded
+//!          : (menuShowDetailsForUnselectedRows == true ? expanded : compact)`
+//! and the emitted boolean is `derived == expanded`.
+//!
+//! The legacy file wraps its payload under a `settings` key, is read with a
+//! 4-attempt 20/40/80 ms retry on EBUSY/EPERM/EAGAIN, is NOT deleted after
+//! migration, and migration write failures are swallowed.
+
+use std::io;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::read_text_file;
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+
+use crate::unified_settings::{
+    get_unified_settings_path, load_unified_dashboard_settings, save_unified_dashboard_settings,
+};
+
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+
+macro_rules! dashboard_str_enum {
+    ($(#[$meta:meta])* $name:ident { $($variant:ident => $text:literal),+ $(,)? }) => {
+        $(#[$meta])*
+        #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+        pub enum $name {
+            $(#[serde(rename = $text)] $variant),+
+        }
+
+        impl $name {
+            pub fn as_str(&self) -> &'static str {
+                match self {
+                    $(Self::$variant => $text),+
+                }
+            }
+        }
+    };
+}
+
+dashboard_str_enum!(
+    /// `DashboardThemePreset = "green" | "blue"`.
+    DashboardThemePreset { Green => "green", Blue => "blue" }
+);
+
+dashboard_str_enum!(
+    /// `DashboardAccentColor = "green" | "cyan" | "blue" | "yellow"`.
+    DashboardAccentColor {
+        Green => "green",
+        Cyan => "cyan",
+        Blue => "blue",
+        Yellow => "yellow",
+    }
+);
+
+dashboard_str_enum!(
+    /// `DashboardAccountSortMode = "manual" | "ready-first"`.
+    DashboardAccountSortMode { Manual => "manual", ReadyFirst => "ready-first" }
+);
+
+dashboard_str_enum!(
+    /// `DashboardStatuslineField = "last-used" | "limits" | "status"`.
+    DashboardStatuslineField {
+        LastUsed => "last-used",
+        Limits => "limits",
+        Status => "status",
+    }
+);
+
+dashboard_str_enum!(
+    /// (private in TS) `DashboardLayoutMode = "compact-details" | "expanded-rows"`.
+    DashboardLayoutMode { CompactDetails => "compact-details", ExpandedRows => "expanded-rows" }
+);
+
+dashboard_str_enum!(
+    /// (private in TS) `DashboardFocusStyle = "row-invert"` — the only value.
+    DashboardFocusStyle { RowInvert => "row-invert" }
+);
+
+// ---------------------------------------------------------------------------
+// Settings struct (serde field order == TS interface / output-literal order)
+// ---------------------------------------------------------------------------
+
+/// `DashboardDisplaySettings` — the normalized shape is always fully
+/// populated (the TS optionals exist only pre-normalization). Serialization
+/// order matches the TS normalize output literal, which is what lands in
+/// `settings.json` (golden-verified).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DashboardDisplaySettings {
+    pub show_per_account_rows: bool,
+    pub show_quota_details: bool,
+    pub show_forecast_reasons: bool,
+    pub show_recommendations: bool,
+    pub show_live_probe_notes: bool,
+    pub action_auto_return_ms: i64,
+    pub action_pause_on_key: bool,
+    pub menu_auto_fetch_limits: bool,
+    pub menu_sort_enabled: bool,
+    pub menu_sort_mode: DashboardAccountSortMode,
+    pub menu_sort_pin_current: bool,
+    pub menu_sort_quick_switch_visible_row: bool,
+    pub ui_theme_preset: DashboardThemePreset,
+    pub ui_accent_color: DashboardAccentColor,
+    pub menu_show_status_badge: bool,
+    pub menu_show_current_badge: bool,
+    pub menu_show_last_used: bool,
+    pub menu_show_quota_summary: bool,
+    pub menu_show_quota_cooldown: bool,
+    pub menu_show_fetch_status: bool,
+    pub menu_show_details_for_unselected_rows: bool,
+    pub menu_layout_mode: DashboardLayoutMode,
+    pub menu_quota_ttl_ms: i64,
+    pub menu_focus_style: DashboardFocusStyle,
+    pub menu_highlight_current_row: bool,
+    pub menu_statusline_fields: Vec<DashboardStatuslineField>,
+}
+
+impl Default for DashboardDisplaySettings {
+    /// `DEFAULT_DASHBOARD_DISPLAY_SETTINGS` (spec 01 §2.11, exact values).
+    fn default() -> Self {
+        DashboardDisplaySettings {
+            show_per_account_rows: true,
+            show_quota_details: true,
+            show_forecast_reasons: true,
+            show_recommendations: true,
+            show_live_probe_notes: true,
+            action_auto_return_ms: 2_000,
+            action_pause_on_key: true,
+            menu_auto_fetch_limits: true,
+            menu_sort_enabled: true,
+            menu_sort_mode: DashboardAccountSortMode::ReadyFirst,
+            menu_sort_pin_current: false,
+            menu_sort_quick_switch_visible_row: true,
+            ui_theme_preset: DashboardThemePreset::Green,
+            ui_accent_color: DashboardAccentColor::Green,
+            menu_show_status_badge: true,
+            menu_show_current_badge: true,
+            menu_show_last_used: true,
+            menu_show_quota_summary: true,
+            menu_show_quota_cooldown: true,
+            menu_show_fetch_status: true,
+            menu_show_details_for_unselected_rows: false,
+            menu_layout_mode: DashboardLayoutMode::CompactDetails,
+            menu_quota_ttl_ms: 300_000,
+            menu_focus_style: DashboardFocusStyle::RowInvert,
+            menu_highlight_current_row: true,
+            menu_statusline_fields: vec![
+                DashboardStatuslineField::LastUsed,
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Status,
+            ],
+        }
+    }
+}
+
+/// `DEFAULT_DASHBOARD_DISPLAY_SETTINGS` as a function (TS exports a const).
+pub fn default_dashboard_display_settings() -> DashboardDisplaySettings {
+    DashboardDisplaySettings::default()
+}
+
+// ---------------------------------------------------------------------------
+// Normalization (pure)
+// ---------------------------------------------------------------------------
+
+fn normalize_boolean(value: Option<&Value>, fallback: bool) -> bool {
+    match value {
+        Some(Value::Bool(b)) => *b,
+        _ => fallback,
+    }
+}
+
+fn normalize_theme_preset(value: Option<&Value>) -> DashboardThemePreset {
+    match value.and_then(Value::as_str) {
+        Some("blue") => DashboardThemePreset::Blue,
+        _ => DashboardThemePreset::Green,
+    }
+}
+
+fn normalize_accent_color(value: Option<&Value>) -> DashboardAccentColor {
+    match value.and_then(Value::as_str) {
+        Some("cyan") => DashboardAccentColor::Cyan,
+        Some("blue") => DashboardAccentColor::Blue,
+        Some("yellow") => DashboardAccentColor::Yellow,
+        _ => DashboardAccentColor::Green,
+    }
+}
+
+fn normalize_layout_mode(value: Option<&Value>, fallback: DashboardLayoutMode) -> DashboardLayoutMode {
+    match value.and_then(Value::as_str) {
+        Some("expanded-rows") => DashboardLayoutMode::ExpandedRows,
+        _ => fallback,
+    }
+}
+
+fn normalize_account_sort_mode(
+    value: Option<&Value>,
+    fallback: DashboardAccountSortMode,
+) -> DashboardAccountSortMode {
+    match value.and_then(Value::as_str) {
+        Some("ready-first") => DashboardAccountSortMode::ReadyFirst,
+        Some("manual") => DashboardAccountSortMode::Manual,
+        _ => fallback,
+    }
+}
+
+/// finite number → round, clamp [60_000, 1_800_000]; else fallback.
+fn normalize_quota_ttl_ms(value: Option<&Value>, fallback: i64) -> i64 {
+    match value.and_then(Value::as_f64) {
+        Some(number) if number.is_finite() => {
+            let rounded = number.round();
+            rounded.clamp(60_000.0, 1_800_000.0) as i64
+        }
+        _ => fallback,
+    }
+}
+
+/// finite number → round, clamp [0, 10_000]; else fallback.
+fn normalize_auto_return_ms(value: Option<&Value>, fallback: i64) -> i64 {
+    match value.and_then(Value::as_f64) {
+        Some(number) if number.is_finite() => {
+            let rounded = number.round();
+            rounded.clamp(0.0, 10_000.0) as i64
+        }
+        _ => fallback,
+    }
+}
+
+/// Array → keep allowed strings, dedupe preserving order; empty result or
+/// non-array → the default triple.
+fn normalize_statusline_fields(value: Option<&Value>) -> Vec<DashboardStatuslineField> {
+    let default_fields = DashboardDisplaySettings::default().menu_statusline_fields;
+    let Some(Value::Array(entries)) = value else {
+        return default_fields;
+    };
+    let mut fields: Vec<DashboardStatuslineField> = Vec::new();
+    for entry in entries {
+        let Some(text) = entry.as_str() else { continue };
+        let typed = match text {
+            "last-used" => DashboardStatuslineField::LastUsed,
+            "limits" => DashboardStatuslineField::Limits,
+            "status" => DashboardStatuslineField::Status,
+            _ => continue,
+        };
+        if !fields.contains(&typed) {
+            fields.push(typed);
+        }
+    }
+    if fields.is_empty() { default_fields } else { fields }
+}
+
+/// `normalizeDashboardDisplaySettings(value)` — pure; non-record input yields
+/// a defaults copy. See the module docs for the layout-mode derivation.
+pub fn normalize_dashboard_display_settings(value: &Value) -> DashboardDisplaySettings {
+    let Some(record) = value.as_object() else {
+        return DashboardDisplaySettings::default();
+    };
+    let defaults = DashboardDisplaySettings::default();
+    let derived_layout_mode = normalize_layout_mode(
+        record.get("menuLayoutMode"),
+        if record.get("menuShowDetailsForUnselectedRows") == Some(&Value::Bool(true)) {
+            DashboardLayoutMode::ExpandedRows
+        } else {
+            DashboardLayoutMode::CompactDetails
+        },
+    );
+    DashboardDisplaySettings {
+        show_per_account_rows: normalize_boolean(
+            record.get("showPerAccountRows"),
+            defaults.show_per_account_rows,
+        ),
+        show_quota_details: normalize_boolean(
+            record.get("showQuotaDetails"),
+            defaults.show_quota_details,
+        ),
+        show_forecast_reasons: normalize_boolean(
+            record.get("showForecastReasons"),
+            defaults.show_forecast_reasons,
+        ),
+        show_recommendations: normalize_boolean(
+            record.get("showRecommendations"),
+            defaults.show_recommendations,
+        ),
+        show_live_probe_notes: normalize_boolean(
+            record.get("showLiveProbeNotes"),
+            defaults.show_live_probe_notes,
+        ),
+        action_auto_return_ms: normalize_auto_return_ms(
+            record.get("actionAutoReturnMs"),
+            defaults.action_auto_return_ms,
+        ),
+        action_pause_on_key: normalize_boolean(
+            record.get("actionPauseOnKey"),
+            defaults.action_pause_on_key,
+        ),
+        menu_auto_fetch_limits: normalize_boolean(
+            record.get("menuAutoFetchLimits"),
+            defaults.menu_auto_fetch_limits,
+        ),
+        // NOTE (spec 01 §2.11): the TS `?? false` / `?? true` right-hand
+        // sides after the DEFAULT lookups are dead code (the defaults are all
+        // defined); the DEFAULT object values are the effective fallbacks.
+        menu_sort_enabled: normalize_boolean(
+            record.get("menuSortEnabled"),
+            defaults.menu_sort_enabled,
+        ),
+        menu_sort_mode: normalize_account_sort_mode(
+            record.get("menuSortMode"),
+            defaults.menu_sort_mode,
+        ),
+        menu_sort_pin_current: normalize_boolean(
+            record.get("menuSortPinCurrent"),
+            defaults.menu_sort_pin_current,
+        ),
+        menu_sort_quick_switch_visible_row: normalize_boolean(
+            record.get("menuSortQuickSwitchVisibleRow"),
+            defaults.menu_sort_quick_switch_visible_row,
+        ),
+        ui_theme_preset: normalize_theme_preset(record.get("uiThemePreset")),
+        ui_accent_color: normalize_accent_color(record.get("uiAccentColor")),
+        menu_show_status_badge: normalize_boolean(
+            record.get("menuShowStatusBadge"),
+            defaults.menu_show_status_badge,
+        ),
+        menu_show_current_badge: normalize_boolean(
+            record.get("menuShowCurrentBadge"),
+            defaults.menu_show_current_badge,
+        ),
+        menu_show_last_used: normalize_boolean(
+            record.get("menuShowLastUsed"),
+            defaults.menu_show_last_used,
+        ),
+        menu_show_quota_summary: normalize_boolean(
+            record.get("menuShowQuotaSummary"),
+            defaults.menu_show_quota_summary,
+        ),
+        menu_show_quota_cooldown: normalize_boolean(
+            record.get("menuShowQuotaCooldown"),
+            defaults.menu_show_quota_cooldown,
+        ),
+        menu_show_fetch_status: normalize_boolean(
+            record.get("menuShowFetchStatus"),
+            defaults.menu_show_fetch_status,
+        ),
+        // Gotcha 9: DERIVED from the layout mode, never the raw input bool.
+        menu_show_details_for_unselected_rows: derived_layout_mode
+            == DashboardLayoutMode::ExpandedRows,
+        menu_layout_mode: derived_layout_mode,
+        menu_quota_ttl_ms: normalize_quota_ttl_ms(
+            record.get("menuQuotaTtlMs"),
+            defaults.menu_quota_ttl_ms,
+        ),
+        menu_focus_style: DashboardFocusStyle::RowInvert,
+        menu_highlight_current_row: normalize_boolean(
+            record.get("menuHighlightCurrentRow"),
+            defaults.menu_highlight_current_row,
+        ),
+        menu_statusline_fields: normalize_statusline_fields(record.get("menuStatuslineFields")),
+    }
+}
+
+/// `toJsonRecord` — serialize into an order-preserving JSON record (field
+/// order == struct declaration order == TS output-literal order).
+pub fn to_json_record(settings: &DashboardDisplaySettings) -> Map<String, Value> {
+    match serde_json::to_value(settings) {
+        Ok(Value::Object(map)) => map,
+        _ => Map::new(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// IO
+// ---------------------------------------------------------------------------
+
+/// `getDashboardSettingsPath` — returns the UNIFIED settings path
+/// (settings.json), NOT the legacy file.
+pub fn get_dashboard_settings_path() -> PathBuf {
+    get_unified_settings_path()
+}
+
+/// The legacy `<multi-auth-dir>/dashboard-settings.json` location.
+fn legacy_dashboard_settings_path() -> PathBuf {
+    get_codex_multi_auth_dir().join("dashboard-settings.json")
+}
+
+const RETRYABLE_READ_CODES: &[&str] = &["EBUSY", "EPERM", "EAGAIN"];
+const LEGACY_READ_MAX_ATTEMPTS: u32 = 4;
+const LEGACY_READ_BASE_DELAY_MS: u64 = 20;
+
+/// `readLegacySettingsFile` — 4 attempts, sleeps 20/40/80 ms between
+/// retryable failures (EBUSY/EPERM/EAGAIN); other errors propagate.
+async fn read_legacy_settings_file(path: &std::path::Path) -> io::Result<String> {
+    with_retry(
+        || {
+            let path = path.to_path_buf();
+            async move { read_text_file(&path) }
+        },
+        RetryOptions::<io::Error>::new(
+            LEGACY_READ_MAX_ATTEMPTS,
+            Backoff::from_fn(|attempt| {
+                LEGACY_READ_BASE_DELAY_MS
+                    .saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+            }),
+        )
+        .with_codes(RETRYABLE_READ_CODES),
+    )
+    .await
+}
+
+/// `loadDashboardDisplaySettings` — unified section → normalize; else legacy
+/// file (retrying reads) with best-effort migration into unified settings
+/// (the legacy file is NOT deleted); any failure → defaults (read/parse
+/// failures warn with the frozen prefix).
+pub async fn load_dashboard_display_settings() -> DashboardDisplaySettings {
+    if let Some(unified_settings) = load_unified_dashboard_settings().await {
+        return normalize_dashboard_display_settings(&Value::Object(unified_settings));
+    }
+
+    let legacy_path = legacy_dashboard_settings_path();
+    if !legacy_path.exists() {
+        return DashboardDisplaySettings::default();
+    }
+
+    let outcome: Result<DashboardDisplaySettings, String> = async {
+        let raw = read_legacy_settings_file(&legacy_path)
+            .await
+            .map_err(|error| error.to_string())?;
+        let parsed: Value = serde_json::from_str(&raw).map_err(|error| error.to_string())?;
+        if !parsed.is_object() {
+            return Ok(DashboardDisplaySettings::default());
+        }
+        let normalized = normalize_dashboard_display_settings(
+            parsed.get("settings").unwrap_or(&Value::Null),
+        );
+        // Best-effort migration; the legacy file stays in place.
+        let _ = save_unified_dashboard_settings(&to_json_record(&normalized)).await;
+        Ok(normalized)
+    }
+    .await;
+
+    match outcome {
+        Ok(settings) => settings,
+        Err(message) => {
+            log_warn(
+                &format!(
+                    "Failed to load dashboard settings from {}: {}",
+                    legacy_path.display(),
+                    message
+                ),
+                None,
+            );
+            DashboardDisplaySettings::default()
+        }
+    }
+}
+
+/// `saveDashboardDisplaySettings` — normalize, then persist through the
+/// unified `dashboardDisplaySettings` section.
+pub async fn save_dashboard_display_settings(
+    settings: &DashboardDisplaySettings,
+) -> io::Result<()> {
+    let as_value = serde_json::to_value(settings).unwrap_or(Value::Null);
+    let normalized = normalize_dashboard_display_settings(&as_value);
+    save_unified_dashboard_settings(&to_json_record(&normalized)).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn non_record_input_yields_defaults_copy() {
+        for value in [json!(null), json!("x"), json!([1]), json!(7)] {
+            assert_eq!(
+                normalize_dashboard_display_settings(&value),
+                DashboardDisplaySettings::default()
+            );
+        }
+    }
+
+    #[test]
+    fn layout_mode_derivation_matrix() {
+        // Explicit expanded-rows wins.
+        let s = normalize_dashboard_display_settings(&json!({
+            "menuLayoutMode": "expanded-rows",
+            "menuShowDetailsForUnselectedRows": false,
+        }));
+        assert_eq!(s.menu_layout_mode, DashboardLayoutMode::ExpandedRows);
+        assert!(s.menu_show_details_for_unselected_rows, "boolean is DERIVED");
+
+        // Legacy boolean hint promotes to expanded-rows.
+        let s = normalize_dashboard_display_settings(&json!({
+            "menuShowDetailsForUnselectedRows": true,
+        }));
+        assert_eq!(s.menu_layout_mode, DashboardLayoutMode::ExpandedRows);
+        assert!(s.menu_show_details_for_unselected_rows);
+
+        // Unknown layout string + false hint → compact.
+        let s = normalize_dashboard_display_settings(&json!({
+            "menuLayoutMode": "weird",
+            "menuShowDetailsForUnselectedRows": "yes",
+        }));
+        assert_eq!(s.menu_layout_mode, DashboardLayoutMode::CompactDetails);
+        assert!(!s.menu_show_details_for_unselected_rows);
+    }
+
+    #[test]
+    fn clamps_and_enum_fallbacks() {
+        let s = normalize_dashboard_display_settings(&json!({
+            "menuQuotaTtlMs": 10,             // clamps up to 60_000
+            "actionAutoReturnMs": 99_999,     // clamps down to 10_000
+            "uiThemePreset": "purple",        // → green
+            "uiAccentColor": "yellow",
+            "menuSortMode": "manual",
+            "menuFocusStyle": "anything",     // always row-invert
+            "menuStatuslineFields": ["limits", "bogus", "limits", "status", 3],
+        }));
+        assert_eq!(s.menu_quota_ttl_ms, 60_000);
+        assert_eq!(s.action_auto_return_ms, 10_000);
+        assert_eq!(s.ui_theme_preset, DashboardThemePreset::Green);
+        assert_eq!(s.ui_accent_color, DashboardAccentColor::Yellow);
+        assert_eq!(s.menu_sort_mode, DashboardAccountSortMode::Manual);
+        assert_eq!(s.menu_focus_style, DashboardFocusStyle::RowInvert);
+        assert_eq!(
+            s.menu_statusline_fields,
+            vec![
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Status
+            ],
+            "dedupe preserving order, invalid entries dropped"
+        );
+
+        let upper = normalize_dashboard_display_settings(&json!({ "menuQuotaTtlMs": 99_999_999 }));
+        assert_eq!(upper.menu_quota_ttl_ms, 1_800_000);
+        let rounded = normalize_dashboard_display_settings(&json!({ "menuQuotaTtlMs": 61_000.6 }));
+        assert_eq!(rounded.menu_quota_ttl_ms, 61_001);
+    }
+
+    #[test]
+    fn empty_or_invalid_statusline_fields_fall_back_to_the_default_triple() {
+        let default_triple = DashboardDisplaySettings::default().menu_statusline_fields;
+        let s = normalize_dashboard_display_settings(&json!({ "menuStatuslineFields": [] }));
+        assert_eq!(s.menu_statusline_fields, default_triple);
+        let s = normalize_dashboard_display_settings(&json!({ "menuStatuslineFields": "limits" }));
+        assert_eq!(s.menu_statusline_fields, default_triple);
+        let s = normalize_dashboard_display_settings(&json!({ "menuStatuslineFields": [1, true] }));
+        assert_eq!(s.menu_statusline_fields, default_triple);
+    }
+
+    #[test]
+    fn booleans_only_accept_actual_booleans() {
+        let s = normalize_dashboard_display_settings(&json!({
+            "showPerAccountRows": "false",  // not a boolean → default true
+            "menuSortPinCurrent": true,
+            "menuHighlightCurrentRow": 0,
+        }));
+        assert!(s.show_per_account_rows);
+        assert!(s.menu_sort_pin_current);
+        assert!(s.menu_highlight_current_row);
+    }
+
+    #[test]
+    fn json_record_field_order_matches_the_golden_section() {
+        let record = to_json_record(&DashboardDisplaySettings::default());
+        let keys: Vec<&str> = record.keys().map(String::as_str).collect();
+        assert_eq!(
+            keys,
+            vec![
+                "showPerAccountRows",
+                "showQuotaDetails",
+                "showForecastReasons",
+                "showRecommendations",
+                "showLiveProbeNotes",
+                "actionAutoReturnMs",
+                "actionPauseOnKey",
+                "menuAutoFetchLimits",
+                "menuSortEnabled",
+                "menuSortMode",
+                "menuSortPinCurrent",
+                "menuSortQuickSwitchVisibleRow",
+                "uiThemePreset",
+                "uiAccentColor",
+                "menuShowStatusBadge",
+                "menuShowCurrentBadge",
+                "menuShowLastUsed",
+                "menuShowQuotaSummary",
+                "menuShowQuotaCooldown",
+                "menuShowFetchStatus",
+                "menuShowDetailsForUnselectedRows",
+                "menuLayoutMode",
+                "menuQuotaTtlMs",
+                "menuFocusStyle",
+                "menuHighlightCurrentRow",
+                "menuStatuslineFields",
+            ]
+        );
+        assert_eq!(record.get("menuQuotaTtlMs"), Some(&json!(300000)));
+        assert_eq!(record.get("menuSortMode"), Some(&json!("ready-first")));
+    }
+
+    #[test]
+    fn defaults_match_the_spec_table() {
+        let d = DashboardDisplaySettings::default();
+        assert!(d.menu_sort_enabled);
+        assert!(!d.menu_sort_pin_current);
+        assert_eq!(d.action_auto_return_ms, 2_000);
+        assert_eq!(d.menu_quota_ttl_ms, 300_000);
+        assert!(!d.menu_show_details_for_unselected_rows);
+        assert_eq!(d.menu_layout_mode, DashboardLayoutMode::CompactDetails);
+    }
+}
diff --git a/crates/config/src/explain.rs b/crates/config/src/explain.rs
new file mode 100644
index 000000000..0b45995e8
--- /dev/null
+++ b/crates/config/src/explain.rs
@@ -0,0 +1,513 @@
+//! Port of `getPluginConfigExplainReport` from `lib/config.ts` (spec 01
+//! §2.9.1, gotchas 2 and 13).
+//!
+//! - The stored-record resolution mirrors `loadPluginConfig` precedence
+//!   EXACTLY: env path (set + existing — even when unreadable, in which case
+//!   storageKind is `"unreadable"` with that path, never masked behind
+//!   unified) → unified `pluginConfig` section → legacy file ladder → none.
+//! - Source detection: the getter is re-run with the entry's env names
+//!   DISABLED via a thread-local seam (behavior-equivalent to the TS
+//!   delete-and-restore of `process.env` — gotcha 13); a JSON-stringify
+//!   difference means `"env"`. Otherwise a stored record owning any of the
+//!   entry's `sourceKeys` attributes the storage kind; else `"default"`.
+//! - Entry order is the fixed TS `CONFIG_EXPLAIN_ENTRIES` declaration order
+//!   (54 entries; `responseContinuation`/`backgroundResponses`/
+//!   `routingMutex`/`schedulingStrategy` come LAST, after the preemptive
+//!   quota rows — this is NOT the schema order).
+//! - Values are normalized for JSON-safe output: non-finite numbers become
+//!   the strings `"NaN"`/`"Infinity"`/`"-Infinity"`; arrays/objects recurse.
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{Map, Value};
+
+use cma_core::json_io::stringify_compact;
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_core::utils::is_record;
+
+use crate::getters::{self, with_env_names_disabled};
+use crate::load::{
+    ConfigPaths, env_config_path, load_plugin_config, read_config_record_from_path,
+    resolve_plugin_config_path,
+};
+use crate::unified_settings::{get_unified_settings_path, load_unified_plugin_config_sync};
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/// `ConfigExplainStorageKind = "unified" | "file" | "none" | "unreadable"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ConfigExplainStorageKind {
+    Unified,
+    File,
+    None,
+    Unreadable,
+}
+
+impl ConfigExplainStorageKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ConfigExplainStorageKind::Unified => "unified",
+            ConfigExplainStorageKind::File => "file",
+            ConfigExplainStorageKind::None => "none",
+            ConfigExplainStorageKind::Unreadable => "unreadable",
+        }
+    }
+}
+
+/// `ConfigExplainSource = "env" | "unified" | "file" | "default"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ConfigExplainSource {
+    Env,
+    Unified,
+    File,
+    Default,
+}
+
+impl ConfigExplainSource {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ConfigExplainSource::Env => "env",
+            ConfigExplainSource::Unified => "unified",
+            ConfigExplainSource::File => "file",
+            ConfigExplainSource::Default => "default",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct ConfigExplainEntry {
+    pub key: &'static str,
+    pub value: Value,
+    pub default_value: Value,
+    pub source: ConfigExplainSource,
+    pub env_names: &'static [&'static str],
+}
+
+#[derive(Clone, Debug)]
+pub struct ConfigExplainReport {
+    pub config_path: Option<PathBuf>,
+    pub storage_kind: ConfigExplainStorageKind,
+    pub entries: Vec<ConfigExplainEntry>,
+}
+
+// ---------------------------------------------------------------------------
+// Value conversion
+// ---------------------------------------------------------------------------
+
+/// JS number → JSON value (integral values as integers, like
+/// `JSON.stringify`); non-finite values survive into
+/// [`normalize_config_explain_value`] as nulls there, but getters only
+/// produce finite numbers.
+fn num_value(value: f64) -> Value {
+    if value.is_finite() && value.fract() == 0.0 && value.abs() < 9.007_199_254_740_992e15 {
+        Value::from(value as i64)
+    } else {
+        serde_json::Number::from_f64(value)
+            .map(Value::Number)
+            .unwrap_or(Value::Null)
+    }
+}
+
+/// `normalizeConfigExplainValue` — in TS, non-finite numbers become the
+/// strings `"NaN"`/`"Infinity"`/`"-Infinity"`; `serde_json::Value` cannot
+/// carry non-finite numbers (and [`num_value`] guards the conversion), so
+/// only the recursive clone remains observable here.
+fn normalize_config_explain_value(value: &Value) -> Value {
+    match value {
+        Value::Array(items) => {
+            Value::Array(items.iter().map(normalize_config_explain_value).collect())
+        }
+        Value::Object(map) => {
+            let mut normalized = Map::new();
+            for (key, item) in map {
+                normalized.insert(key.clone(), normalize_config_explain_value(item));
+            }
+            Value::Object(normalized)
+        }
+        other => other.clone(),
+    }
+}
+
+fn values_equal(left: &Value, right: &Value) -> bool {
+    // `configExplainValuesEqual` = JSON.stringify equality.
+    stringify_compact(left) == stringify_compact(right)
+}
+
+// ---------------------------------------------------------------------------
+// Entry table (TS CONFIG_EXPLAIN_ENTRIES declaration order — 54 entries)
+// ---------------------------------------------------------------------------
+
+type GetValue = fn(&PluginConfig) -> Value;
+
+struct ExplainMeta {
+    key: &'static str,
+    env_names: &'static [&'static str],
+    get_value: GetValue,
+    /// `sourceKeys` — defaults to `[key]`; the two unsupported-policy rows
+    /// share `["unsupportedCodexPolicy", "fallbackOnUnsupportedCodexModel"]`.
+    source_keys: &'static [&'static str],
+}
+
+macro_rules! meta {
+    ($key:literal, [$($env:literal),*], $get:expr) => {
+        ExplainMeta {
+            key: $key,
+            env_names: &[$($env),*],
+            get_value: $get,
+            source_keys: &[$key],
+        }
+    };
+    ($key:literal, [$($env:literal),*], $get:expr, sources: [$($src:literal),+]) => {
+        ExplainMeta {
+            key: $key,
+            env_names: &[$($env),*],
+            get_value: $get,
+            source_keys: &[$($src),+],
+        }
+    };
+}
+
+// fn pointers can't close over `f`, so each entry uses a small named wrapper.
+macro_rules! bool_getter {
+    ($name:ident, $inner:path) => {
+        fn $name(config: &PluginConfig) -> Value {
+            Value::Bool($inner(config))
+        }
+    };
+}
+
+macro_rules! num_getter {
+    ($name:ident, $inner:path) => {
+        fn $name(config: &PluginConfig) -> Value {
+            num_value($inner(config))
+        }
+    };
+}
+
+macro_rules! str_getter {
+    ($name:ident, $inner:path) => {
+        fn $name(config: &PluginConfig) -> Value {
+            Value::String($inner(config).as_str().to_string())
+        }
+    };
+}
+
+bool_getter!(v_codex_mode, getters::get_codex_mode);
+bool_getter!(v_codex_runtime_rotation_proxy, getters::get_codex_runtime_rotation_proxy);
+bool_getter!(v_codex_tui_v2, getters::get_codex_tui_v2);
+str_getter!(v_codex_tui_color_profile, getters::get_codex_tui_color_profile);
+str_getter!(v_codex_tui_glyph_mode, getters::get_codex_tui_glyph_mode);
+bool_getter!(v_fast_session, getters::get_fast_session);
+str_getter!(v_fast_session_strategy, getters::get_fast_session_strategy);
+num_getter!(v_fast_session_max_input_items, getters::get_fast_session_max_input_items);
+bool_getter!(v_retry_all_rate_limited, getters::get_retry_all_accounts_rate_limited);
+num_getter!(v_retry_all_max_wait_ms, getters::get_retry_all_accounts_max_wait_ms);
+num_getter!(v_retry_all_max_retries, getters::get_retry_all_accounts_max_retries);
+str_getter!(v_unsupported_codex_policy, getters::get_unsupported_codex_policy);
+bool_getter!(v_fallback_on_unsupported, getters::get_fallback_on_unsupported_codex_model);
+bool_getter!(v_fallback_gpt53_to_gpt52, getters::get_fallback_to_gpt52_on_unsupported_gpt53);
+fn v_unsupported_codex_fallback_chain(config: &PluginConfig) -> Value {
+    getters::get_unsupported_codex_fallback_chain(config).to_value()
+}
+num_getter!(v_token_refresh_skew_ms, getters::get_token_refresh_skew_ms);
+num_getter!(v_rate_limit_toast_debounce_ms, getters::get_rate_limit_toast_debounce_ms);
+num_getter!(v_toast_duration_ms, getters::get_toast_duration_ms);
+bool_getter!(v_per_project_accounts, getters::get_per_project_accounts);
+bool_getter!(v_session_recovery, getters::get_session_recovery);
+bool_getter!(v_auto_resume, getters::get_auto_resume);
+bool_getter!(v_parallel_probing, getters::get_parallel_probing);
+num_getter!(v_parallel_probing_max_concurrency, getters::get_parallel_probing_max_concurrency);
+num_getter!(v_empty_response_max_retries, getters::get_empty_response_max_retries);
+num_getter!(v_empty_response_retry_delay_ms, getters::get_empty_response_retry_delay_ms);
+num_getter!(v_rate_limit_dedup_window_ms, getters::get_rate_limit_dedup_window_ms);
+num_getter!(v_rate_limit_state_reset_ms, getters::get_rate_limit_state_reset_ms);
+num_getter!(v_rate_limit_max_backoff_ms, getters::get_rate_limit_max_backoff_ms);
+num_getter!(v_rate_limit_short_retry_threshold_ms, getters::get_rate_limit_short_retry_threshold_ms);
+bool_getter!(v_pid_offset_enabled, getters::get_pid_offset_enabled);
+num_getter!(v_fetch_timeout_ms, getters::get_fetch_timeout_ms);
+num_getter!(v_stream_stall_timeout_ms, getters::get_stream_stall_timeout_ms);
+bool_getter!(v_live_account_sync, getters::get_live_account_sync);
+num_getter!(v_live_account_sync_debounce_ms, getters::get_live_account_sync_debounce_ms);
+num_getter!(v_live_account_sync_poll_ms, getters::get_live_account_sync_poll_ms);
+bool_getter!(v_session_affinity, getters::get_session_affinity);
+num_getter!(v_session_affinity_ttl_ms, getters::get_session_affinity_ttl_ms);
+num_getter!(v_session_affinity_max_entries, getters::get_session_affinity_max_entries);
+bool_getter!(v_proactive_refresh_guardian, getters::get_proactive_refresh_guardian);
+num_getter!(v_proactive_refresh_interval_ms, getters::get_proactive_refresh_interval_ms);
+num_getter!(v_proactive_refresh_buffer_ms, getters::get_proactive_refresh_buffer_ms);
+num_getter!(v_network_error_cooldown_ms, getters::get_network_error_cooldown_ms);
+num_getter!(v_server_error_cooldown_ms, getters::get_server_error_cooldown_ms);
+num_getter!(v_token_invalidation_cooldown_ms, getters::get_token_invalidation_cooldown_ms);
+num_getter!(v_min_rotation_interval_ms, getters::get_min_rotation_interval_ms);
+bool_getter!(v_storage_backup_enabled, getters::get_storage_backup_enabled);
+bool_getter!(v_preemptive_quota_enabled, getters::get_preemptive_quota_enabled);
+num_getter!(v_preemptive_quota_5h, getters::get_preemptive_quota_remaining_percent_5h);
+num_getter!(v_preemptive_quota_7d, getters::get_preemptive_quota_remaining_percent_7d);
+num_getter!(v_preemptive_quota_max_deferral_ms, getters::get_preemptive_quota_max_deferral_ms);
+bool_getter!(v_response_continuation, getters::get_response_continuation);
+bool_getter!(v_background_responses, getters::get_background_responses);
+str_getter!(v_routing_mutex, getters::get_routing_mutex_mode);
+str_getter!(v_scheduling_strategy, getters::get_scheduling_strategy);
+
+const CONFIG_EXPLAIN_ENTRIES: &[ExplainMeta] = &[
+    meta!("codexMode", ["CODEX_MODE"], v_codex_mode),
+    meta!("codexRuntimeRotationProxy", ["CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY"], v_codex_runtime_rotation_proxy),
+    meta!("codexTuiV2", ["CODEX_TUI_V2"], v_codex_tui_v2),
+    meta!("codexTuiColorProfile", ["CODEX_TUI_COLOR_PROFILE"], v_codex_tui_color_profile),
+    meta!("codexTuiGlyphMode", ["CODEX_TUI_GLYPHS"], v_codex_tui_glyph_mode),
+    meta!("fastSession", ["CODEX_AUTH_FAST_SESSION"], v_fast_session),
+    meta!("fastSessionStrategy", ["CODEX_AUTH_FAST_SESSION_STRATEGY"], v_fast_session_strategy),
+    meta!("fastSessionMaxInputItems", ["CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS"], v_fast_session_max_input_items),
+    meta!("retryAllAccountsRateLimited", ["CODEX_AUTH_RETRY_ALL_RATE_LIMITED"], v_retry_all_rate_limited),
+    meta!("retryAllAccountsMaxWaitMs", ["CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS"], v_retry_all_max_wait_ms),
+    meta!("retryAllAccountsMaxRetries", ["CODEX_AUTH_RETRY_ALL_MAX_RETRIES"], v_retry_all_max_retries),
+    meta!(
+        "unsupportedCodexPolicy",
+        ["CODEX_AUTH_UNSUPPORTED_MODEL_POLICY", "CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL"],
+        v_unsupported_codex_policy,
+        sources: ["unsupportedCodexPolicy", "fallbackOnUnsupportedCodexModel"]
+    ),
+    meta!(
+        "fallbackOnUnsupportedCodexModel",
+        ["CODEX_AUTH_UNSUPPORTED_MODEL_POLICY", "CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL"],
+        v_fallback_on_unsupported,
+        sources: ["unsupportedCodexPolicy", "fallbackOnUnsupportedCodexModel"]
+    ),
+    meta!("fallbackToGpt52OnUnsupportedGpt53", ["CODEX_AUTH_FALLBACK_GPT53_TO_GPT52"], v_fallback_gpt53_to_gpt52),
+    meta!("unsupportedCodexFallbackChain", [], v_unsupported_codex_fallback_chain),
+    meta!("tokenRefreshSkewMs", ["CODEX_AUTH_TOKEN_REFRESH_SKEW_MS"], v_token_refresh_skew_ms),
+    meta!("rateLimitToastDebounceMs", ["CODEX_AUTH_RATE_LIMIT_TOAST_DEBOUNCE_MS"], v_rate_limit_toast_debounce_ms),
+    meta!("toastDurationMs", ["CODEX_AUTH_TOAST_DURATION_MS"], v_toast_duration_ms),
+    meta!("perProjectAccounts", ["CODEX_AUTH_PER_PROJECT_ACCOUNTS"], v_per_project_accounts),
+    meta!("sessionRecovery", ["CODEX_AUTH_SESSION_RECOVERY"], v_session_recovery),
+    meta!("autoResume", ["CODEX_AUTH_AUTO_RESUME"], v_auto_resume),
+    meta!("parallelProbing", ["CODEX_AUTH_PARALLEL_PROBING"], v_parallel_probing),
+    meta!("parallelProbingMaxConcurrency", ["CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY"], v_parallel_probing_max_concurrency),
+    meta!("emptyResponseMaxRetries", ["CODEX_AUTH_EMPTY_RESPONSE_MAX_RETRIES"], v_empty_response_max_retries),
+    meta!("emptyResponseRetryDelayMs", ["CODEX_AUTH_EMPTY_RESPONSE_RETRY_DELAY_MS"], v_empty_response_retry_delay_ms),
+    meta!("rateLimitDedupWindowMs", ["CODEX_AUTH_RATE_LIMIT_DEDUP_WINDOW_MS"], v_rate_limit_dedup_window_ms),
+    meta!("rateLimitStateResetMs", ["CODEX_AUTH_RATE_LIMIT_STATE_RESET_MS"], v_rate_limit_state_reset_ms),
+    meta!("rateLimitMaxBackoffMs", ["CODEX_AUTH_RATE_LIMIT_MAX_BACKOFF_MS"], v_rate_limit_max_backoff_ms),
+    meta!("rateLimitShortRetryThresholdMs", ["CODEX_AUTH_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS"], v_rate_limit_short_retry_threshold_ms),
+    meta!("pidOffsetEnabled", ["CODEX_AUTH_PID_OFFSET_ENABLED"], v_pid_offset_enabled),
+    meta!("fetchTimeoutMs", ["CODEX_AUTH_FETCH_TIMEOUT_MS"], v_fetch_timeout_ms),
+    meta!("streamStallTimeoutMs", ["CODEX_AUTH_STREAM_STALL_TIMEOUT_MS"], v_stream_stall_timeout_ms),
+    meta!("liveAccountSync", ["CODEX_AUTH_LIVE_ACCOUNT_SYNC"], v_live_account_sync),
+    meta!("liveAccountSyncDebounceMs", ["CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS"], v_live_account_sync_debounce_ms),
+    meta!("liveAccountSyncPollMs", ["CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS"], v_live_account_sync_poll_ms),
+    meta!("sessionAffinity", ["CODEX_AUTH_SESSION_AFFINITY"], v_session_affinity),
+    meta!("sessionAffinityTtlMs", ["CODEX_AUTH_SESSION_AFFINITY_TTL_MS"], v_session_affinity_ttl_ms),
+    meta!("sessionAffinityMaxEntries", ["CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES"], v_session_affinity_max_entries),
+    meta!("proactiveRefreshGuardian", ["CODEX_AUTH_PROACTIVE_GUARDIAN"], v_proactive_refresh_guardian),
+    meta!("proactiveRefreshIntervalMs", ["CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS"], v_proactive_refresh_interval_ms),
+    meta!("proactiveRefreshBufferMs", ["CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS"], v_proactive_refresh_buffer_ms),
+    meta!("networkErrorCooldownMs", ["CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS"], v_network_error_cooldown_ms),
+    meta!("serverErrorCooldownMs", ["CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS"], v_server_error_cooldown_ms),
+    meta!("tokenInvalidationCooldownMs", ["CODEX_AUTH_TOKEN_INVALIDATION_COOLDOWN_MS"], v_token_invalidation_cooldown_ms),
+    meta!("minRotationIntervalMs", ["CODEX_AUTH_MIN_ROTATION_INTERVAL_MS"], v_min_rotation_interval_ms),
+    meta!("storageBackupEnabled", ["CODEX_AUTH_STORAGE_BACKUP_ENABLED"], v_storage_backup_enabled),
+    meta!("preemptiveQuotaEnabled", ["CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED"], v_preemptive_quota_enabled),
+    meta!("preemptiveQuotaRemainingPercent5h", ["CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT"], v_preemptive_quota_5h),
+    meta!("preemptiveQuotaRemainingPercent7d", ["CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT"], v_preemptive_quota_7d),
+    meta!("preemptiveQuotaMaxDeferralMs", ["CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS"], v_preemptive_quota_max_deferral_ms),
+    // config-01/config-07: these live settings were once missing from the
+    // explain report; they sit at the END of the table (declaration order).
+    meta!("responseContinuation", ["CODEX_AUTH_RESPONSE_CONTINUATION"], v_response_continuation),
+    meta!("backgroundResponses", ["CODEX_AUTH_BACKGROUND_RESPONSES"], v_background_responses),
+    meta!("routingMutex", ["CODEX_AUTH_ROUTING_MUTEX"], v_routing_mutex),
+    meta!("schedulingStrategy", ["CODEX_AUTH_SCHEDULING_STRATEGY"], v_scheduling_strategy),
+];
+
+/// The explain-entry keys, in report order (for parity tests).
+pub fn config_explain_entry_keys() -> Vec<&'static str> {
+    CONFIG_EXPLAIN_ENTRIES.iter().map(|meta| meta.key).collect()
+}
+
+// ---------------------------------------------------------------------------
+// Stored-record resolution (`resolveStoredPluginConfigRecord`)
+// ---------------------------------------------------------------------------
+
+struct StoredRecord {
+    config_path: Option<PathBuf>,
+    storage_kind: ConfigExplainStorageKind,
+    record: Option<Map<String, Value>>,
+}
+
+fn resolve_stored_plugin_config_record() -> StoredRecord {
+    // config-01: mirror loadPluginConfig()'s precedence exactly.
+    if let Some(env_config_path) = env_config_path() {
+        let env_path = Path::new(&env_config_path);
+        if env_path.exists() {
+            if let Some(record) = read_config_record_from_path(env_path) {
+                return StoredRecord {
+                    config_path: Some(PathBuf::from(&env_config_path)),
+                    storage_kind: ConfigExplainStorageKind::File,
+                    record: Some(record),
+                };
+            }
+            // Env path set + existing but unreadable/invalid: report it as
+            // the active (unreadable) source, never masked behind unified.
+            return StoredRecord {
+                config_path: Some(PathBuf::from(&env_config_path)),
+                storage_kind: ConfigExplainStorageKind::Unreadable,
+                record: None,
+            };
+        }
+    }
+
+    if let Some(unified_config) = load_unified_plugin_config_sync() {
+        // (loadUnifiedPluginConfigSync already guarantees a record shape.)
+        if is_record(&Value::Object(unified_config.clone())) {
+            return StoredRecord {
+                config_path: Some(get_unified_settings_path()),
+                storage_kind: ConfigExplainStorageKind::Unified,
+                record: Some(unified_config),
+            };
+        }
+    }
+
+    let paths = ConfigPaths::resolve();
+    let Some(config_path) = resolve_plugin_config_path(&paths) else {
+        return StoredRecord {
+            config_path: None,
+            storage_kind: ConfigExplainStorageKind::None,
+            record: None,
+        };
+    };
+
+    if let Some(record) = read_config_record_from_path(&config_path) {
+        return StoredRecord {
+            config_path: Some(config_path),
+            storage_kind: ConfigExplainStorageKind::File,
+            record: Some(record),
+        };
+    }
+
+    let storage_kind = if config_path.exists() {
+        ConfigExplainStorageKind::Unreadable
+    } else {
+        ConfigExplainStorageKind::None
+    };
+    StoredRecord {
+        config_path: Some(config_path),
+        storage_kind,
+        record: None,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Report
+// ---------------------------------------------------------------------------
+
+fn resolve_config_explain_source(
+    meta: &ExplainMeta,
+    plugin_config: &PluginConfig,
+    stored_record: Option<&Map<String, Value>>,
+    storage_kind: ConfigExplainStorageKind,
+) -> ConfigExplainSource {
+    let effective_value = (meta.get_value)(plugin_config);
+    let no_env_value = with_env_names_disabled(meta.env_names, || (meta.get_value)(plugin_config));
+    if !values_equal(&effective_value, &no_env_value) {
+        return ConfigExplainSource::Env;
+    }
+    let stored_source = match storage_kind {
+        ConfigExplainStorageKind::Unified => Some(ConfigExplainSource::Unified),
+        ConfigExplainStorageKind::File => Some(ConfigExplainSource::File),
+        _ => None,
+    };
+    if let Some(source) = stored_source
+        && let Some(record) = stored_record
+        && meta.source_keys.iter().any(|key| record.contains_key(*key))
+    {
+        return source;
+    }
+    ConfigExplainSource::Default
+}
+
+/// `getPluginConfigExplainReport()` — see module docs.
+pub fn get_plugin_config_explain_report() -> ConfigExplainReport {
+    let plugin_config = load_plugin_config();
+    let stored = resolve_stored_plugin_config_record();
+    let stored_record = stored.record.as_ref();
+
+    // DEFAULT_PLUGIN_CONFIG[key] — raw defaults (not routed through getters).
+    let default_values: Map<String, Value> =
+        match serde_json::to_value(PluginConfig::default_resolved()) {
+            Ok(Value::Object(map)) => map,
+            _ => Map::new(),
+        };
+
+    let entries = CONFIG_EXPLAIN_ENTRIES
+        .iter()
+        .map(|meta| {
+            let value = (meta.get_value)(&plugin_config);
+            let default_value = default_values.get(meta.key).cloned().unwrap_or(Value::Null);
+            ConfigExplainEntry {
+                key: meta.key,
+                value: normalize_config_explain_value(&value),
+                default_value: normalize_config_explain_value(&default_value),
+                source: resolve_config_explain_source(
+                    meta,
+                    &plugin_config,
+                    stored_record,
+                    stored.storage_kind,
+                ),
+                env_names: meta.env_names,
+            }
+        })
+        .collect();
+
+    ConfigExplainReport {
+        config_path: stored.config_path,
+        storage_kind: stored.storage_kind,
+        entries,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::plugin_config::PLUGIN_CONFIG_KEYS;
+
+    #[test]
+    fn explains_every_default_plugin_config_key_with_no_extras() {
+        // Parity with test/config-explain.test.ts drift guards: same key SET
+        // as DEFAULT_PLUGIN_CONFIG (order differs deliberately at the tail).
+        let mut explain_keys = config_explain_entry_keys();
+        let mut schema_keys: Vec<&str> = PLUGIN_CONFIG_KEYS.to_vec();
+        assert_eq!(explain_keys.len(), 54);
+        explain_keys.sort_unstable();
+        schema_keys.sort_unstable();
+        assert_eq!(explain_keys, schema_keys);
+    }
+
+    #[test]
+    fn entry_order_puts_the_late_added_rows_last() {
+        let keys = config_explain_entry_keys();
+        assert_eq!(
+            &keys[50..],
+            &[
+                "responseContinuation",
+                "backgroundResponses",
+                "routingMutex",
+                "schedulingStrategy"
+            ]
+        );
+        assert_eq!(keys[0], "codexMode");
+        assert_eq!(keys[49], "preemptiveQuotaMaxDeferralMs");
+    }
+
+    #[test]
+    fn normalize_recurses_and_passes_finite_values_through() {
+        let value = serde_json::json!({ "a": [1, "x", { "b": true }] });
+        assert_eq!(normalize_config_explain_value(&value), value);
+    }
+
+    #[test]
+    fn num_value_prints_integral_numbers_without_decimals() {
+        assert_eq!(stringify_compact(&num_value(5000.0)), "5000");
+        assert_eq!(stringify_compact(&num_value(2.5)), "2.5");
+    }
+}
diff --git a/crates/config/src/getters.rs b/crates/config/src/getters.rs
new file mode 100644
index 000000000..84a6f4f12
--- /dev/null
+++ b/crates/config/src/getters.rs
@@ -0,0 +1,1035 @@
+//! Port of the ~54 typed getters of `lib/config.ts` (spec 01 §5.4 table).
+//!
+//! Resolution: env override (when valid) → config value → default, then
+//! clamp — clamping applies to env AND config values. Boolean env parsing via
+//! `parse_boolean_env`; numeric env parsing follows JS `Number()` semantics
+//! (hex/octal/binary literals, exponents, trimming); string envs are
+//! trim+lowercase and must be in the allowed set. A set, non-empty,
+//! unparseable boolean/number env emits a warn-once and is ignored.
+//!
+//! Gotchas reproduced deliberately:
+//! - `get_pid_offset_enabled` inline default **false** vs
+//!   `DEFAULT_PLUGIN_CONFIG.pidOffsetEnabled = true` (spec 01 gotcha 3 — do
+//!   NOT unify).
+//! - `get_fast_session_strategy` has bespoke resolution (gotcha 24).
+//! - `get_unsupported_codex_fallback_chain` normalization does NOT strip
+//!   `-max`/`-ultra` suffixes (gotcha 8).
+//!
+//! The explain report (`explain.rs`) re-runs getters with specific env names
+//! disabled through a thread-local — behavior-equivalent to the TS
+//! delete-and-restore of `process.env` (gotcha 13), without mutating the
+//! process environment.
+
+use std::cell::RefCell;
+
+use cma_core::env_parsing::parse_boolean_env;
+use cma_core::schemas::plugin_config::{
+    CodexTuiColorProfile, CodexTuiGlyphMode, FallbackChain, FastSessionStrategy, PluginConfig,
+    RoutingMutexMode, SchedulingStrategy, UnsupportedCodexPolicy,
+};
+
+use crate::load::log_config_warn_once;
+
+// ---------------------------------------------------------------------------
+// Env access (with the explain "env disabled" seam)
+// ---------------------------------------------------------------------------
+
+thread_local! {
+    /// Env names currently hidden from the getters (explain source-detection
+    /// re-run). Stack-of-slices semantics via simple Vec push/truncate.
+    static EXPLAIN_DISABLED_ENV: RefCell<Vec<String>> = const { RefCell::new(Vec::new()) };
+}
+
+/// Run `f` with the given env names invisible to the getters on THIS thread
+/// (`withExplainEnvUnset` — behavior-equivalent, no real env mutation).
+pub(crate) fn with_env_names_disabled<T>(env_names: &[&str], f: impl FnOnce() -> T) -> T {
+    if env_names.is_empty() {
+        return f();
+    }
+    let added = EXPLAIN_DISABLED_ENV.with(|cell| {
+        let mut disabled = cell.borrow_mut();
+        let before = disabled.len();
+        disabled.extend(env_names.iter().map(|s| s.to_string()));
+        before
+    });
+    struct Restore(usize);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            EXPLAIN_DISABLED_ENV.with(|cell| cell.borrow_mut().truncate(self.0));
+        }
+    }
+    let _restore = Restore(added);
+    f()
+}
+
+/// `process.env[name]` as seen by the getters (respecting the explain
+/// disable list).
+fn env_var(name: &str) -> Option<String> {
+    let hidden = EXPLAIN_DISABLED_ENV.with(|cell| cell.borrow().iter().any(|n| n == name));
+    if hidden {
+        return None;
+    }
+    std::env::var(name).ok()
+}
+
+// ---------------------------------------------------------------------------
+// Resolution helpers
+// ---------------------------------------------------------------------------
+
+/// JS `Number(trimmed)` for a non-empty trimmed string; `None` when the
+/// result is not a finite number (NaN/Infinity are ignored like the TS
+/// `parseNumberEnv`).
+fn parse_js_number(trimmed: &str) -> Option<f64> {
+    fn radix_value(digits: &str, radix: u32) -> Option<f64> {
+        if digits.is_empty() {
+            return None;
+        }
+        let mut acc = 0f64;
+        for c in digits.chars() {
+            let digit = c.to_digit(radix)?;
+            acc = acc * radix as f64 + digit as f64;
+        }
+        Some(acc)
+    }
+    let lower = trimmed;
+    let parsed = if let Some(rest) = lower.strip_prefix("0x").or_else(|| lower.strip_prefix("0X")) {
+        radix_value(rest, 16)
+    } else if let Some(rest) = lower.strip_prefix("0o").or_else(|| lower.strip_prefix("0O")) {
+        radix_value(rest, 8)
+    } else if let Some(rest) = lower.strip_prefix("0b").or_else(|| lower.strip_prefix("0B")) {
+        radix_value(rest, 2)
+    } else {
+        trimmed.parse::<f64>().ok()
+    };
+    parsed.filter(|value| value.is_finite())
+}
+
+fn parse_number_env(value: Option<&str>) -> Option<f64> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    parse_js_number(trimmed)
+}
+
+fn parse_string_env(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim().to_lowercase();
+    if trimmed.is_empty() { None } else { Some(trimmed) }
+}
+
+/// `resolveBooleanSetting` — env valid → env; else config → default. A set,
+/// non-empty, unparseable env warns once and is ignored.
+fn resolve_boolean_setting(env_name: &str, config_value: Option<bool>, default_value: bool) -> bool {
+    let raw_env_value = env_var(env_name);
+    let env_value = parse_boolean_env(raw_env_value.as_deref());
+    if let Some(raw) = &raw_env_value
+        && !raw.trim().is_empty()
+        && env_value.is_none()
+    {
+        log_config_warn_once(&format!(
+            "Ignoring invalid boolean env {env_name}. Expected 0/1, true/false, or yes/no."
+        ));
+    }
+    env_value.unwrap_or_else(|| config_value.unwrap_or(default_value))
+}
+
+/// `resolveNumberSetting` — env valid → env; else config → default; result
+/// clamped into `[min, max]` (defaults ±∞); clamping applies to env AND
+/// config values.
+fn resolve_number_setting(
+    env_name: &str,
+    config_value: Option<f64>,
+    default_value: f64,
+    min: Option<f64>,
+    max: Option<f64>,
+) -> f64 {
+    let raw_env_value = env_var(env_name);
+    let env_value = parse_number_env(raw_env_value.as_deref());
+    if let Some(raw) = &raw_env_value
+        && !raw.trim().is_empty()
+        && env_value.is_none()
+    {
+        log_config_warn_once(&format!(
+            "Ignoring invalid numeric env {env_name}. Expected a finite number."
+        ));
+    }
+    let candidate = env_value.or(config_value).unwrap_or(default_value);
+    let min = min.unwrap_or(f64::NEG_INFINITY);
+    let max = max.unwrap_or(f64::INFINITY);
+    min.max(max.min(candidate))
+}
+
+/// `resolveStringSetting` — env (trim+lowercase, must parse into the allowed
+/// set) → config → default. Invalid values fall through silently.
+fn resolve_string_setting<T: Copy>(
+    env_name: &str,
+    config_value: Option<T>,
+    default_value: T,
+    parse: fn(&str) -> Option<T>,
+) -> T {
+    if let Some(env_value) = parse_string_env(env_var(env_name).as_deref())
+        && let Some(valid) = parse(&env_value)
+    {
+        return valid;
+    }
+    config_value.unwrap_or(default_value)
+}
+
+// ---------------------------------------------------------------------------
+// Getters (spec 01 §5.4 — exact env names, defaults, clamps)
+// ---------------------------------------------------------------------------
+
+pub fn get_codex_mode(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting("CODEX_MODE", plugin_config.codex_mode, true)
+}
+
+pub fn get_codex_runtime_rotation_proxy(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY",
+        plugin_config.codex_runtime_rotation_proxy,
+        true,
+    )
+}
+
+pub fn get_codex_tui_v2(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting("CODEX_TUI_V2", plugin_config.codex_tui_v2, true)
+}
+
+pub fn get_codex_tui_color_profile(plugin_config: &PluginConfig) -> CodexTuiColorProfile {
+    resolve_string_setting(
+        "CODEX_TUI_COLOR_PROFILE",
+        plugin_config.codex_tui_color_profile,
+        CodexTuiColorProfile::Truecolor,
+        CodexTuiColorProfile::parse,
+    )
+}
+
+pub fn get_codex_tui_glyph_mode(plugin_config: &PluginConfig) -> CodexTuiGlyphMode {
+    resolve_string_setting(
+        "CODEX_TUI_GLYPHS",
+        plugin_config.codex_tui_glyph_mode,
+        CodexTuiGlyphMode::Ascii,
+        CodexTuiGlyphMode::parse,
+    )
+}
+
+pub fn get_fast_session(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_FAST_SESSION",
+        plugin_config.fast_session,
+        false,
+    )
+}
+
+/// Bespoke resolution (gotcha 24): env exact-match after trim+lowercase;
+/// config compared strictly against `"always"`; anything else → `"hybrid"`;
+/// no warnings.
+pub fn get_fast_session_strategy(plugin_config: &PluginConfig) -> FastSessionStrategy {
+    let env = env_var("CODEX_AUTH_FAST_SESSION_STRATEGY")
+        .unwrap_or_default()
+        .trim()
+        .to_lowercase();
+    if env == "always" {
+        return FastSessionStrategy::Always;
+    }
+    if env == "hybrid" {
+        return FastSessionStrategy::Hybrid;
+    }
+    if plugin_config.fast_session_strategy == Some(FastSessionStrategy::Always) {
+        FastSessionStrategy::Always
+    } else {
+        FastSessionStrategy::Hybrid
+    }
+}
+
+pub fn get_fast_session_max_input_items(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS",
+        plugin_config.fast_session_max_input_items,
+        30.0,
+        Some(8.0),
+        None,
+    )
+}
+
+pub fn get_retry_all_accounts_rate_limited(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_RETRY_ALL_RATE_LIMITED",
+        plugin_config.retry_all_accounts_rate_limited,
+        false,
+    )
+}
+
+pub fn get_retry_all_accounts_max_wait_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS",
+        plugin_config.retry_all_accounts_max_wait_ms,
+        0.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_retry_all_accounts_max_retries(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RETRY_ALL_MAX_RETRIES",
+        plugin_config.retry_all_accounts_max_retries,
+        0.0,
+        Some(0.0),
+        None,
+    )
+}
+
+/// Policy resolution ladder: env policy → config policy → legacy bool env
+/// (`CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL`, no warning on invalid) → config
+/// legacy bool → `"strict"`.
+pub fn get_unsupported_codex_policy(plugin_config: &PluginConfig) -> UnsupportedCodexPolicy {
+    if let Some(env_policy) =
+        parse_string_env(env_var("CODEX_AUTH_UNSUPPORTED_MODEL_POLICY").as_deref())
+        && let Some(valid) = UnsupportedCodexPolicy::parse(&env_policy)
+    {
+        return valid;
+    }
+
+    if let Some(config_policy) = plugin_config.unsupported_codex_policy {
+        return config_policy;
+    }
+
+    let legacy_env_fallback =
+        parse_boolean_env(env_var("CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL").as_deref());
+    if let Some(fallback) = legacy_env_fallback {
+        return if fallback {
+            UnsupportedCodexPolicy::Fallback
+        } else {
+            UnsupportedCodexPolicy::Strict
+        };
+    }
+
+    if let Some(legacy_config) = plugin_config.fallback_on_unsupported_codex_model {
+        return if legacy_config {
+            UnsupportedCodexPolicy::Fallback
+        } else {
+            UnsupportedCodexPolicy::Strict
+        };
+    }
+
+    UnsupportedCodexPolicy::Strict
+}
+
+pub fn get_fallback_on_unsupported_codex_model(plugin_config: &PluginConfig) -> bool {
+    get_unsupported_codex_policy(plugin_config) == UnsupportedCodexPolicy::Fallback
+}
+
+pub fn get_fallback_to_gpt52_on_unsupported_gpt53(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_FALLBACK_GPT53_TO_GPT52",
+        plugin_config.fallback_to_gpt52_on_unsupported_gpt53,
+        true,
+    )
+}
+
+/// Chain normalization (gotcha 8): trim+lowercase, take the substring after
+/// the last `/`, strip ONE reasoning-effort suffix
+/// `-(none|minimal|low|medium|high|xhigh)` — `-max`/`-ultra` are deliberately
+/// NOT stripped. Empty keys/targets dropped; entries with zero surviving
+/// targets dropped. Duplicate normalized keys: later entries overwrite the
+/// value while the first occurrence keeps its position (JS object semantics).
+pub fn get_unsupported_codex_fallback_chain(plugin_config: &PluginConfig) -> FallbackChain {
+    fn normalize_model(value: &str) -> String {
+        let trimmed = value.trim().to_lowercase();
+        if trimmed.is_empty() {
+            return String::new();
+        }
+        let stripped = if trimmed.contains('/') {
+            trimmed.rsplit('/').next().unwrap_or(&trimmed).to_string()
+        } else {
+            trimmed
+        };
+        for suffix in ["-none", "-minimal", "-low", "-medium", "-high", "-xhigh"] {
+            if let Some(base) = stripped.strip_suffix(suffix) {
+                return base.to_string();
+            }
+        }
+        stripped
+    }
+
+    let Some(chain) = plugin_config.unsupported_codex_fallback_chain.as_ref() else {
+        return FallbackChain::new();
+    };
+    let mut normalized: Vec<(String, Vec<String>)> = Vec::new();
+    for (key, targets) in chain.iter() {
+        let normalized_key = normalize_model(key);
+        if normalized_key.is_empty() {
+            continue;
+        }
+        let normalized_targets: Vec<String> = targets
+            .iter()
+            .map(|target| normalize_model(target))
+            .filter(|target| !target.is_empty())
+            .collect();
+        if normalized_targets.is_empty() {
+            continue;
+        }
+        if let Some(existing) = normalized
+            .iter_mut()
+            .find(|(existing_key, _)| *existing_key == normalized_key)
+        {
+            existing.1 = normalized_targets;
+        } else {
+            normalized.push((normalized_key, normalized_targets));
+        }
+    }
+    FallbackChain(normalized)
+}
+
+pub fn get_token_refresh_skew_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_TOKEN_REFRESH_SKEW_MS",
+        plugin_config.token_refresh_skew_ms,
+        60_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_rate_limit_toast_debounce_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RATE_LIMIT_TOAST_DEBOUNCE_MS",
+        plugin_config.rate_limit_toast_debounce_ms,
+        60_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_session_recovery(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_SESSION_RECOVERY",
+        plugin_config.session_recovery,
+        true,
+    )
+}
+
+pub fn get_auto_resume(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting("CODEX_AUTH_AUTO_RESUME", plugin_config.auto_resume, true)
+}
+
+pub fn get_toast_duration_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_TOAST_DURATION_MS",
+        plugin_config.toast_duration_ms,
+        5_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_per_project_accounts(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_PER_PROJECT_ACCOUNTS",
+        plugin_config.per_project_accounts,
+        true,
+    )
+}
+
+pub fn get_parallel_probing(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_PARALLEL_PROBING",
+        plugin_config.parallel_probing,
+        false,
+    )
+}
+
+pub fn get_parallel_probing_max_concurrency(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY",
+        plugin_config.parallel_probing_max_concurrency,
+        2.0,
+        Some(1.0),
+        None,
+    )
+}
+
+pub fn get_empty_response_max_retries(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_EMPTY_RESPONSE_MAX_RETRIES",
+        plugin_config.empty_response_max_retries,
+        2.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_empty_response_retry_delay_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_EMPTY_RESPONSE_RETRY_DELAY_MS",
+        plugin_config.empty_response_retry_delay_ms,
+        1_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_rate_limit_dedup_window_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RATE_LIMIT_DEDUP_WINDOW_MS",
+        plugin_config.rate_limit_dedup_window_ms,
+        2_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_rate_limit_state_reset_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RATE_LIMIT_STATE_RESET_MS",
+        plugin_config.rate_limit_state_reset_ms,
+        120_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_rate_limit_max_backoff_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RATE_LIMIT_MAX_BACKOFF_MS",
+        plugin_config.rate_limit_max_backoff_ms,
+        60_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+/// Config-crate getter (spec 01 gotcha 20): distinct from the request
+/// crate's renamed `configured_rate_limit_short_retry_threshold_ms`.
+pub fn get_rate_limit_short_retry_threshold_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS",
+        plugin_config.rate_limit_short_retry_threshold_ms,
+        5_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+/// Inline default **false** — deliberately different from
+/// `DEFAULT_PLUGIN_CONFIG.pidOffsetEnabled = true` (gotcha 3; do NOT "fix").
+pub fn get_pid_offset_enabled(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_PID_OFFSET_ENABLED",
+        plugin_config.pid_offset_enabled,
+        false,
+    )
+}
+
+pub fn get_fetch_timeout_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_FETCH_TIMEOUT_MS",
+        plugin_config.fetch_timeout_ms,
+        60_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_stream_stall_timeout_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_STREAM_STALL_TIMEOUT_MS",
+        plugin_config.stream_stall_timeout_ms,
+        45_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_live_account_sync(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_LIVE_ACCOUNT_SYNC",
+        plugin_config.live_account_sync,
+        true,
+    )
+}
+
+pub fn get_live_account_sync_debounce_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS",
+        plugin_config.live_account_sync_debounce_ms,
+        250.0,
+        Some(50.0),
+        None,
+    )
+}
+
+pub fn get_live_account_sync_poll_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS",
+        plugin_config.live_account_sync_poll_ms,
+        2_000.0,
+        Some(500.0),
+        None,
+    )
+}
+
+pub fn get_session_affinity(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_SESSION_AFFINITY",
+        plugin_config.session_affinity,
+        true,
+    )
+}
+
+pub fn get_session_affinity_ttl_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_SESSION_AFFINITY_TTL_MS",
+        plugin_config.session_affinity_ttl_ms,
+        1_200_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_session_affinity_max_entries(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES",
+        plugin_config.session_affinity_max_entries,
+        512.0,
+        Some(8.0),
+        None,
+    )
+}
+
+pub fn get_response_continuation(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_RESPONSE_CONTINUATION",
+        plugin_config.response_continuation,
+        false,
+    )
+}
+
+pub fn get_background_responses(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_BACKGROUND_RESPONSES",
+        plugin_config.background_responses,
+        false,
+    )
+}
+
+pub fn get_proactive_refresh_guardian(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_PROACTIVE_GUARDIAN",
+        plugin_config.proactive_refresh_guardian,
+        true,
+    )
+}
+
+pub fn get_proactive_refresh_interval_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS",
+        plugin_config.proactive_refresh_interval_ms,
+        60_000.0,
+        Some(5_000.0),
+        None,
+    )
+}
+
+pub fn get_proactive_refresh_buffer_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS",
+        plugin_config.proactive_refresh_buffer_ms,
+        300_000.0,
+        Some(30_000.0),
+        None,
+    )
+}
+
+pub fn get_network_error_cooldown_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS",
+        plugin_config.network_error_cooldown_ms,
+        6_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_server_error_cooldown_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS",
+        plugin_config.server_error_cooldown_ms,
+        4_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_token_invalidation_cooldown_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_TOKEN_INVALIDATION_COOLDOWN_MS",
+        plugin_config.token_invalidation_cooldown_ms,
+        300_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_min_rotation_interval_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_MIN_ROTATION_INTERVAL_MS",
+        plugin_config.min_rotation_interval_ms,
+        60_000.0,
+        Some(0.0),
+        None,
+    )
+}
+
+pub fn get_storage_backup_enabled(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_STORAGE_BACKUP_ENABLED",
+        plugin_config.storage_backup_enabled,
+        true,
+    )
+}
+
+pub fn get_preemptive_quota_enabled(plugin_config: &PluginConfig) -> bool {
+    resolve_boolean_setting(
+        "CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED",
+        plugin_config.preemptive_quota_enabled,
+        true,
+    )
+}
+
+pub fn get_preemptive_quota_remaining_percent_5h(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT",
+        plugin_config.preemptive_quota_remaining_percent_5h,
+        5.0,
+        Some(0.0),
+        Some(100.0),
+    )
+}
+
+pub fn get_preemptive_quota_remaining_percent_7d(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT",
+        plugin_config.preemptive_quota_remaining_percent_7d,
+        5.0,
+        Some(0.0),
+        Some(100.0),
+    )
+}
+
+pub fn get_preemptive_quota_max_deferral_ms(plugin_config: &PluginConfig) -> f64 {
+    resolve_number_setting(
+        "CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS",
+        plugin_config.preemptive_quota_max_deferral_ms,
+        7_200_000.0,
+        Some(1_000.0),
+        None,
+    )
+}
+
+pub fn get_routing_mutex_mode(plugin_config: &PluginConfig) -> RoutingMutexMode {
+    resolve_string_setting(
+        "CODEX_AUTH_ROUTING_MUTEX",
+        plugin_config.routing_mutex,
+        RoutingMutexMode::Legacy,
+        RoutingMutexMode::parse,
+    )
+}
+
+pub fn get_scheduling_strategy(plugin_config: &PluginConfig) -> SchedulingStrategy {
+    resolve_string_setting(
+        "CODEX_AUTH_SCHEDULING_STRATEGY",
+        plugin_config.scheduling_strategy,
+        SchedulingStrategy::Hybrid,
+        SchedulingStrategy::parse,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn defaults() -> PluginConfig {
+        PluginConfig::default_resolved()
+    }
+
+    fn empty() -> PluginConfig {
+        PluginConfig::default()
+    }
+
+    #[test]
+    #[serial(env)]
+    fn boolean_getter_priority_env_over_config_over_default() {
+        let mut sandbox = EnvSandbox::new();
+        let mut config = empty();
+        config.codex_mode = Some(true);
+
+        sandbox.remove_var("CODEX_MODE");
+        assert!(get_codex_mode(&empty()), "default true");
+        assert!(get_codex_mode(&config));
+        config.codex_mode = Some(false);
+        assert!(!get_codex_mode(&config), "config value wins over default");
+
+        sandbox.set_var("CODEX_MODE", "1");
+        assert!(get_codex_mode(&config), "env 1 beats config false");
+        sandbox.set_var("CODEX_MODE", "0");
+        config.codex_mode = Some(true);
+        assert!(!get_codex_mode(&config), "env 0 beats config true");
+
+        sandbox.set_var("CODEX_MODE", "not-a-bool");
+        assert!(get_codex_mode(&config), "invalid env falls back to config");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn pid_offset_split_default_is_reproduced_not_fixed() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("CODEX_AUTH_PID_OFFSET_ENABLED");
+        // Getter inline default: FALSE for a partial config…
+        assert!(!get_pid_offset_enabled(&empty()));
+        // …but the resolved defaults table carries TRUE, so a loaded config
+        // yields true.
+        assert!(get_pid_offset_enabled(&defaults()));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn number_getters_clamp_env_and_config_values() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("CODEX_AUTH_TOAST_DURATION_MS");
+        let mut config = empty();
+        // Stored 1500 is schema-valid; env 500 clamps up to min 1000.
+        config.toast_duration_ms = Some(1_500.0);
+        assert_eq!(get_toast_duration_ms(&config), 1_500.0);
+        sandbox.set_var("CODEX_AUTH_TOAST_DURATION_MS", "500");
+        assert_eq!(get_toast_duration_ms(&config), 1_000.0);
+
+        // fastSessionMaxInputItems: getter min 8, no getter max.
+        sandbox.set_var("CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS", "3");
+        assert_eq!(get_fast_session_max_input_items(&empty()), 8.0);
+        sandbox.set_var("CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS", "500");
+        assert_eq!(get_fast_session_max_input_items(&empty()), 500.0);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn number_env_parsing_follows_js_number_semantics() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("CODEX_AUTH_RETRY_ALL_MAX_RETRIES", "0x10");
+        assert_eq!(get_retry_all_accounts_max_retries(&empty()), 16.0);
+        sandbox.set_var("CODEX_AUTH_RETRY_ALL_MAX_RETRIES", "1e3");
+        assert_eq!(get_retry_all_accounts_max_retries(&empty()), 1_000.0);
+        sandbox.set_var("CODEX_AUTH_RETRY_ALL_MAX_RETRIES", "  42  ");
+        assert_eq!(get_retry_all_accounts_max_retries(&empty()), 42.0);
+        // "42abc" is NaN → ignored (default 0).
+        sandbox.set_var("CODEX_AUTH_RETRY_ALL_MAX_RETRIES", "42abc");
+        assert_eq!(get_retry_all_accounts_max_retries(&empty()), 0.0);
+        // Empty env is ignored without warning.
+        sandbox.set_var("CODEX_AUTH_RETRY_ALL_MAX_RETRIES", "   ");
+        assert_eq!(get_retry_all_accounts_max_retries(&empty()), 0.0);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn string_getters_validate_env_against_the_allowed_set() {
+        let mut sandbox = EnvSandbox::new();
+        let mut config = empty();
+        config.codex_tui_color_profile = Some(CodexTuiColorProfile::Ansi256);
+
+        sandbox.remove_var("CODEX_TUI_COLOR_PROFILE");
+        assert_eq!(
+            get_codex_tui_color_profile(&empty()),
+            CodexTuiColorProfile::Truecolor
+        );
+        assert_eq!(
+            get_codex_tui_color_profile(&config),
+            CodexTuiColorProfile::Ansi256
+        );
+        sandbox.set_var("CODEX_TUI_COLOR_PROFILE", "ANSI16");
+        assert_eq!(
+            get_codex_tui_color_profile(&config),
+            CodexTuiColorProfile::Ansi16,
+            "env is trim+lowercased"
+        );
+        sandbox.set_var("CODEX_TUI_COLOR_PROFILE", "bogus");
+        assert_eq!(
+            get_codex_tui_color_profile(&config),
+            CodexTuiColorProfile::Ansi256,
+            "invalid env falls through to config"
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn fast_session_strategy_bespoke_resolution() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("CODEX_AUTH_FAST_SESSION_STRATEGY");
+        assert_eq!(get_fast_session_strategy(&empty()), FastSessionStrategy::Hybrid);
+        let mut config = empty();
+        config.fast_session_strategy = Some(FastSessionStrategy::Always);
+        assert_eq!(get_fast_session_strategy(&config), FastSessionStrategy::Always);
+        sandbox.set_var("CODEX_AUTH_FAST_SESSION_STRATEGY", " HYBRID ");
+        assert_eq!(get_fast_session_strategy(&config), FastSessionStrategy::Hybrid);
+        sandbox.set_var("CODEX_AUTH_FAST_SESSION_STRATEGY", "always");
+        assert_eq!(get_fast_session_strategy(&empty()), FastSessionStrategy::Always);
+        // Unknown env falls through to config comparison.
+        sandbox.set_var("CODEX_AUTH_FAST_SESSION_STRATEGY", "sometimes");
+        assert_eq!(get_fast_session_strategy(&config), FastSessionStrategy::Always);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn unsupported_policy_ladder() {
+        let mut sandbox = EnvSandbox::new();
+        for name in [
+            "CODEX_AUTH_UNSUPPORTED_MODEL_POLICY",
+            "CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL",
+        ] {
+            sandbox.remove_var(name);
+        }
+        assert_eq!(
+            get_unsupported_codex_policy(&empty()),
+            UnsupportedCodexPolicy::Strict
+        );
+        assert!(!get_fallback_on_unsupported_codex_model(&empty()));
+
+        let mut config = empty();
+        config.unsupported_codex_policy = Some(UnsupportedCodexPolicy::Fallback);
+        assert_eq!(
+            get_unsupported_codex_policy(&config),
+            UnsupportedCodexPolicy::Fallback
+        );
+
+        // Legacy config bool maps when the policy key is absent.
+        let mut legacy = empty();
+        legacy.fallback_on_unsupported_codex_model = Some(true);
+        assert_eq!(
+            get_unsupported_codex_policy(&legacy),
+            UnsupportedCodexPolicy::Fallback
+        );
+
+        // Legacy env toggle beats the legacy config bool.
+        sandbox.set_var("CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL", "0");
+        assert_eq!(
+            get_unsupported_codex_policy(&legacy),
+            UnsupportedCodexPolicy::Strict
+        );
+
+        // Policy env overrides everything.
+        sandbox.set_var("CODEX_AUTH_UNSUPPORTED_MODEL_POLICY", "fallback");
+        assert_eq!(
+            get_unsupported_codex_policy(&legacy),
+            UnsupportedCodexPolicy::Fallback
+        );
+        assert!(get_fallback_on_unsupported_codex_model(&legacy));
+    }
+
+    #[test]
+    fn fallback_chain_normalization() {
+        let mut config = empty();
+        // Built directly (not via serde) so the getter's tolerance for
+        // empty keys/targets — which the schema would reject — is exercised,
+        // matching the TS getter operating on arbitrary caller configs.
+        let chain = FallbackChain(vec![
+            (
+                "  OpenAI/GPT-5.3-Codex-High  ".to_string(),
+                vec![
+                    "provider/GPT-5.2-medium".to_string(),
+                    String::new(),
+                    "gpt-5.1-xhigh".to_string(),
+                ],
+            ),
+            (
+                "gpt-5.3-codex-max".to_string(),
+                vec!["gpt-5.2-ultra".to_string()],
+            ),
+            (String::new(), vec!["x".to_string()]),
+            ("empty-targets".to_string(), vec![String::new()]),
+        ]);
+        config.unsupported_codex_fallback_chain = Some(chain);
+        let normalized = get_unsupported_codex_fallback_chain(&config);
+        // Effort suffixes stripped; -max/-ultra NOT stripped (gotcha 8);
+        // path prefixes removed; empties dropped.
+        assert_eq!(
+            normalized.get("gpt-5.3-codex"),
+            Some(&["gpt-5.2".to_string(), "gpt-5.1".to_string()][..])
+        );
+        assert_eq!(
+            normalized.get("gpt-5.3-codex-max"),
+            Some(&["gpt-5.2-ultra".to_string()][..])
+        );
+        assert_eq!(normalized.len(), 2);
+
+        // Missing chain → empty.
+        assert!(get_unsupported_codex_fallback_chain(&empty()).is_empty());
+    }
+
+    #[test]
+    #[serial(env)]
+    fn rate_limit_backoff_settings_defaults_and_env_overrides() {
+        let mut sandbox = EnvSandbox::new();
+        assert_eq!(get_rate_limit_dedup_window_ms(&empty()), 2_000.0);
+        assert_eq!(get_rate_limit_state_reset_ms(&empty()), 120_000.0);
+        assert_eq!(get_rate_limit_max_backoff_ms(&empty()), 60_000.0);
+        assert_eq!(get_rate_limit_short_retry_threshold_ms(&empty()), 5_000.0);
+
+        sandbox.set_var("CODEX_AUTH_RATE_LIMIT_DEDUP_WINDOW_MS", "1234");
+        sandbox.set_var("CODEX_AUTH_RATE_LIMIT_STATE_RESET_MS", "999");
+        sandbox.set_var("CODEX_AUTH_RATE_LIMIT_MAX_BACKOFF_MS", "70000");
+        sandbox.set_var("CODEX_AUTH_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS", "-5");
+        assert_eq!(get_rate_limit_dedup_window_ms(&empty()), 1_234.0);
+        assert_eq!(get_rate_limit_state_reset_ms(&empty()), 1_000.0, "min 1000");
+        assert_eq!(get_rate_limit_max_backoff_ms(&empty()), 70_000.0);
+        assert_eq!(get_rate_limit_short_retry_threshold_ms(&empty()), 0.0, "min 0");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn preemptive_quota_thresholds() {
+        let mut sandbox = EnvSandbox::new();
+        assert_eq!(get_preemptive_quota_remaining_percent_5h(&empty()), 5.0);
+        assert_eq!(get_preemptive_quota_remaining_percent_7d(&empty()), 5.0);
+        assert_eq!(get_preemptive_quota_max_deferral_ms(&empty()), 7_200_000.0);
+        sandbox.set_var("CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT", "150");
+        sandbox.set_var("CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT", "-3");
+        sandbox.set_var("CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS", "1");
+        assert_eq!(get_preemptive_quota_remaining_percent_5h(&empty()), 100.0);
+        assert_eq!(get_preemptive_quota_remaining_percent_7d(&empty()), 0.0);
+        assert_eq!(get_preemptive_quota_max_deferral_ms(&empty()), 1_000.0);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn routing_mutex_and_scheduling_strategy() {
+        let mut sandbox = EnvSandbox::new();
+        assert_eq!(get_routing_mutex_mode(&empty()), RoutingMutexMode::Legacy);
+        assert_eq!(get_scheduling_strategy(&empty()), SchedulingStrategy::Hybrid);
+        sandbox.set_var("CODEX_AUTH_ROUTING_MUTEX", "enabled");
+        sandbox.set_var("CODEX_AUTH_SCHEDULING_STRATEGY", "sequential");
+        assert_eq!(get_routing_mutex_mode(&empty()), RoutingMutexMode::Enabled);
+        assert_eq!(
+            get_scheduling_strategy(&empty()),
+            SchedulingStrategy::Sequential
+        );
+        sandbox.set_var("CODEX_AUTH_SCHEDULING_STRATEGY", "bogus");
+        assert_eq!(get_scheduling_strategy(&empty()), SchedulingStrategy::Hybrid);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn env_disabled_seam_hides_only_the_named_vars() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("CODEX_MODE", "0");
+        sandbox.set_var("CODEX_TUI_V2", "0");
+        assert!(!get_codex_mode(&defaults()));
+        let inside = with_env_names_disabled(&["CODEX_MODE"], || {
+            (get_codex_mode(&defaults()), get_codex_tui_v2(&defaults()))
+        });
+        assert_eq!(inside, (true, false), "only CODEX_MODE was hidden");
+        // Restored afterwards.
+        assert!(!get_codex_mode(&defaults()));
+    }
+}
diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs
new file mode 100644
index 000000000..7c63150a5
--- /dev/null
+++ b/crates/config/src/lib.rs
@@ -0,0 +1,9 @@
+//! cma-config - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod config_schema;
+pub mod dashboard_settings;
+pub mod explain;
+pub mod getters;
+pub mod load;
+pub mod lockfile;
+pub mod save;
+pub mod unified_settings;
diff --git a/crates/config/src/load.rs b/crates/config/src/load.rs
new file mode 100644
index 000000000..544447c18
--- /dev/null
+++ b/crates/config/src/load.rs
@@ -0,0 +1,494 @@
+//! Port of the load half of `lib/config.ts` — `loadPluginConfig`, the legacy
+//! path resolution ladder, per-field sanitization, and the shared read
+//! plumbing used by `save.rs` / `explain.rs`.
+//!
+//! Behavior source: spec 01 §2.9/§4.2/§10.1 + the TS source. Key contracts:
+//!
+//! - Precedence: `CODEX_MULTI_AUTH_CONFIG_PATH` (set AND existing) → unified
+//!   settings `pluginConfig` section → legacy file ladder → defaults. A
+//!   set-but-missing env path is IGNORED on load (gotcha 1) but is still the
+//!   save target (`save.rs`).
+//! - Load NEVER fails: per-field zod validation drops invalid values silently
+//!   with ONE warn-once carrying the first 3 schema errors (gotcha 4); any
+//!   throw degrades to defaults with a warn-once.
+//! - UTF-8 BOM stripped before every JSON.parse (gotcha 6).
+//! - Sync reads retry transient EBUSY/EPERM/EAGAIN immediately (5 attempts,
+//!   zero delay — the Atomics.wait regression, §10.1).
+//! - All warn-once texts are FROZEN strings.
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use serde_json::{Map, Value};
+
+use cma_core::fs_retry::{Backoff, HasErrorCode, RetryOptions, code_of, with_retry, with_retry_sync};
+use cma_core::json_io::{read_text_file, strip_utf8_bom};
+use cma_core::logger::warn_once;
+use cma_core::runtime_paths::{get_codex_home_dir, get_codex_multi_auth_dir, get_legacy_codex_dir};
+use cma_core::schemas::plugin_config::{
+    PLUGIN_CONFIG_KEYS, PluginConfig, plugin_config_issues, validate_field,
+};
+use cma_core::schemas::parse::validation_errors;
+use cma_core::utils::is_record;
+
+use crate::unified_settings::{get_unified_settings_path, load_unified_plugin_config_sync};
+
+/// Rename/lock-unlink retry codes (`RETRYABLE_FS_CODES` in config.ts).
+pub(crate) const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+/// Read/stat retry codes (`RETRYABLE_CONFIG_READ_CODES` in config.ts).
+pub(crate) const RETRYABLE_CONFIG_READ_CODES: &[&str] = &["EBUSY", "EPERM", "EAGAIN"];
+
+// ---------------------------------------------------------------------------
+// Paths (TS computed these once at module import; per-call resolution is
+// behavior-equivalent within one process and required for env sandboxing)
+// ---------------------------------------------------------------------------
+
+pub(crate) struct ConfigPaths {
+    /// `<multi-auth-dir>/config.json` (the current canonical legacy file).
+    pub config_path: PathBuf,
+    pub is_custom_codex_home: bool,
+    pub legacy_codex_home_config_path: PathBuf,
+    pub legacy_codex_home_auth_config_path: PathBuf,
+    pub legacy_codex_config_path: PathBuf,
+    pub legacy_codex_auth_config_path: PathBuf,
+}
+
+impl ConfigPaths {
+    pub(crate) fn resolve() -> Self {
+        let config_dir = get_codex_multi_auth_dir();
+        let codex_home_dir = get_codex_home_dir();
+        let legacy_codex_dir = get_legacy_codex_dir();
+        let is_custom_codex_home = codex_home_dir != legacy_codex_dir;
+        ConfigPaths {
+            config_path: config_dir.join("config.json"),
+            is_custom_codex_home,
+            legacy_codex_home_config_path: codex_home_dir.join("codex-multi-auth-config.json"),
+            legacy_codex_home_auth_config_path: codex_home_dir.join("openai-codex-auth-config.json"),
+            legacy_codex_config_path: legacy_codex_dir.join("codex-multi-auth-config.json"),
+            legacy_codex_auth_config_path: legacy_codex_dir.join("openai-codex-auth-config.json"),
+        }
+    }
+}
+
+/// `logConfigWarnOnce` — dedupe key is the FULL message string, process-global
+/// (gotcha 7). Delegates to the core warn-once registry.
+pub(crate) fn log_config_warn_once(message: &str) {
+    warn_once(message);
+}
+
+/// `__resetConfigWarningCacheForTests` — clears the warn-once set.
+pub fn __reset_config_warning_cache_for_tests() {
+    cma_core::logger::__reset_for_tests();
+}
+
+/// Trimmed non-empty `CODEX_MULTI_AUTH_CONFIG_PATH` (the raw process env —
+/// deliberately NOT routed through the explain env-disabled flag; explain
+/// never disables this variable).
+pub(crate) fn env_config_path() -> Option<String> {
+    let raw = std::env::var("CODEX_MULTI_AUTH_CONFIG_PATH").ok()?;
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+
+/// `readFileSyncWithConfigRetry` — 5 attempts, IMMEDIATE retry (zero delay,
+/// never a blocking sleep) on EBUSY/EPERM/EAGAIN; ENOENT and parse errors
+/// propagate unchanged (config-04).
+pub(crate) fn read_file_sync_with_config_retry(config_path: &Path) -> io::Result<String> {
+    with_retry_sync(
+        || read_text_file(config_path),
+        RetryOptions::<io::Error>::fixed(5, 0).with_codes(RETRYABLE_CONFIG_READ_CODES),
+    )
+}
+
+/// `resolvePluginConfigPath` — env override (existing file only) → current
+/// config.json → legacy ladder with one-time migration warnings (spec 01
+/// §4.2 order; gotcha 1 for the env branch).
+pub(crate) fn resolve_plugin_config_path(paths: &ConfigPaths) -> Option<PathBuf> {
+    if let Some(env_path) = env_config_path()
+        && Path::new(&env_path).exists()
+    {
+        return Some(PathBuf::from(env_path));
+    }
+
+    if paths.config_path.exists() {
+        return Some(paths.config_path.clone());
+    }
+
+    let legacy_warn = |legacy: &Path, config_path: &Path| {
+        log_config_warn_once(&format!(
+            "Using legacy config path {}. Please migrate to {}.",
+            legacy.display(),
+            config_path.display()
+        ));
+    };
+
+    if paths.is_custom_codex_home && paths.legacy_codex_home_config_path.exists() {
+        legacy_warn(&paths.legacy_codex_home_config_path, &paths.config_path);
+        return Some(paths.legacy_codex_home_config_path.clone());
+    }
+
+    if paths.legacy_codex_config_path.exists() {
+        legacy_warn(&paths.legacy_codex_config_path, &paths.config_path);
+        return Some(paths.legacy_codex_config_path.clone());
+    }
+
+    if paths.is_custom_codex_home && paths.legacy_codex_home_auth_config_path.exists() {
+        legacy_warn(&paths.legacy_codex_home_auth_config_path, &paths.config_path);
+        return Some(paths.legacy_codex_home_auth_config_path.clone());
+    }
+
+    if paths.legacy_codex_auth_config_path.exists() {
+        legacy_warn(&paths.legacy_codex_auth_config_path, &paths.config_path);
+        return Some(paths.legacy_codex_auth_config_path.clone());
+    }
+
+    None
+}
+
+/// `readConfigRecordFromPath` — sync tolerant reader used by the explain
+/// report: `None` when missing, malformed, non-object, or unreadable (with a
+/// warn-once naming the path).
+pub(crate) fn read_config_record_from_path(config_path: &Path) -> Option<Map<String, Value>> {
+    if !config_path.exists() {
+        return None;
+    }
+    let outcome: Result<Value, String> = read_file_sync_with_config_retry(config_path)
+        .map_err(|error| error.to_string())
+        .and_then(|content| {
+            serde_json::from_str::<Value>(strip_utf8_bom(&content)).map_err(|e| e.to_string())
+        });
+    match outcome {
+        Ok(Value::Object(map)) => Some(map),
+        Ok(_) => None,
+        Err(message) => {
+            log_config_warn_once(&format!(
+                "Failed to read config from {}: {}",
+                config_path.display(),
+                message
+            ));
+            None
+        }
+    }
+}
+
+/// `readConfigRecordForSave` classification (gotcha 12): only `Unreadable`
+/// aborts a save; `Invalid` rebuilds from the patch; `Missing` starts fresh.
+#[derive(Debug)]
+pub(crate) enum ConfigReadState {
+    Missing,
+    Ok(Map<String, Value>),
+    Invalid {
+        /// Carried for parity with the TS state shape; only the Unreadable
+        /// message is consumed (the unreadable-abort StorageError cause).
+        #[allow(dead_code)]
+        error_message: String,
+    },
+    Unreadable {
+        error_message: String,
+    },
+}
+
+enum ConfigReadErr {
+    Io(io::Error),
+    Parse(serde_json::Error),
+}
+
+impl HasErrorCode for ConfigReadErr {
+    fn error_code(&self) -> Option<&str> {
+        match self {
+            ConfigReadErr::Io(error) => code_of(error),
+            ConfigReadErr::Parse(_) => None,
+        }
+    }
+}
+
+/// `readConfigRecordForSave` — async classify-read with the 5-attempt
+/// 10/20/40/80 ms transient retry on EBUSY/EPERM/EAGAIN.
+pub(crate) async fn read_config_record_for_save(config_path: &Path) -> ConfigReadState {
+    if !config_path.exists() {
+        return ConfigReadState::Missing;
+    }
+
+    let result: Result<ConfigReadState, ConfigReadErr> = with_retry(
+        || async {
+            let content = read_text_file(config_path).map_err(ConfigReadErr::Io)?;
+            let parsed: Value = serde_json::from_str(strip_utf8_bom(&content))
+                .map_err(ConfigReadErr::Parse)?;
+            match parsed {
+                Value::Object(map) => Ok(ConfigReadState::Ok(map)),
+                _ => {
+                    let error_message = format!(
+                        "Config at {} must contain a JSON object at the root.",
+                        config_path.display()
+                    );
+                    log_config_warn_once(&error_message);
+                    Ok(ConfigReadState::Invalid { error_message })
+                }
+            }
+        },
+        RetryOptions::new(
+            5,
+            Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))),
+        )
+        .with_codes(RETRYABLE_CONFIG_READ_CODES),
+    )
+    .await;
+
+    match result {
+        Ok(state) => state,
+        Err(error) => {
+            let (code, message) = match &error {
+                ConfigReadErr::Io(io_error) => (code_of(io_error), io_error.to_string()),
+                ConfigReadErr::Parse(parse_error) => (None, parse_error.to_string()),
+            };
+            if code == Some("ENOENT") {
+                return ConfigReadState::Missing;
+            }
+            let error_message = format!(
+                "Failed to read config from {}: {}",
+                config_path.display(),
+                message
+            );
+            log_config_warn_once(&error_message);
+            match error {
+                ConfigReadErr::Parse(_) => ConfigReadState::Invalid { error_message },
+                ConfigReadErr::Io(_) if code.is_some() => {
+                    ConfigReadState::Unreadable { error_message }
+                }
+                ConfigReadErr::Io(_) => ConfigReadState::Invalid { error_message },
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Sanitization
+// ---------------------------------------------------------------------------
+
+/// `sanitizePluginConfigRecord` — per-field zod validation over the 54 known
+/// keys (schema declaration order); invalid values silently dropped; with
+/// `warn_on_invalid`, ONE warn-once carrying the first 3 formatted schema
+/// errors. `None` for non-record input.
+pub(crate) fn sanitize_plugin_config_record(
+    data: &Value,
+    warn_on_invalid: bool,
+) -> Option<Map<String, Value>> {
+    if !is_record(data) {
+        return None;
+    }
+    let record = data.as_object().expect("is_record checked");
+
+    if warn_on_invalid {
+        let schema_errors = validation_errors(plugin_config_issues, data);
+        if !schema_errors.is_empty() {
+            let first_three = schema_errors
+                .iter()
+                .take(3)
+                .cloned()
+                .collect::<Vec<_>>()
+                .join(", ");
+            log_config_warn_once(&format!(
+                "Plugin config validation warnings: {first_three}"
+            ));
+        }
+    }
+
+    let mut sanitized = Map::new();
+    for key in PLUGIN_CONFIG_KEYS {
+        let Some(value) = record.get(key) else {
+            continue;
+        };
+        if let Some(valid) = validate_field(key, value) {
+            sanitized.insert(key.to_string(), valid);
+        }
+    }
+    Some(sanitized)
+}
+
+/// `sanitizeStoredPluginConfigRecord` — validates known keys but PRESERVES
+/// unknown keys in their original positions (gotcha 5: forward-compat fields
+/// round-trip through saves). `None` for non-record input.
+pub(crate) fn sanitize_stored_plugin_config_record(data: &Value) -> Option<Map<String, Value>> {
+    if !is_record(data) {
+        return None;
+    }
+    let record = data.as_object().expect("is_record checked");
+    let mut sanitized = Map::new();
+    for (key, value) in record {
+        if !PLUGIN_CONFIG_KEYS.contains(&key.as_str()) {
+            sanitized.insert(key.clone(), value.clone());
+            continue;
+        }
+        if let Some(valid) = validate_field(key, value) {
+            sanitized.insert(key.clone(), valid);
+        }
+    }
+    Some(sanitized)
+}
+
+/// Build a typed partial [`PluginConfig`] from an already-sanitized map
+/// (every value passed `validate_field`, so the whole-schema parse succeeds).
+pub(crate) fn plugin_config_from_map(map: &Map<String, Value>) -> PluginConfig {
+    serde_json::from_value(Value::Object(map.clone())).unwrap_or_default()
+}
+
+// ---------------------------------------------------------------------------
+// loadPluginConfig
+// ---------------------------------------------------------------------------
+
+/// `getDefaultPluginConfig` — fresh copy of `DEFAULT_PLUGIN_CONFIG`.
+pub fn get_default_plugin_config() -> PluginConfig {
+    PluginConfig::default_resolved()
+}
+
+/// `loadPluginConfig` — synchronous; NEVER fails (degrades to defaults with a
+/// warn-once). Returns the fully-resolved config (defaults overlaid with the
+/// sanitized user record).
+pub fn load_plugin_config() -> PluginConfig {
+    let paths = ConfigPaths::resolve();
+    match load_plugin_config_inner(&paths) {
+        Ok(config) => config,
+        Err(message) => {
+            let config_path =
+                resolve_plugin_config_path(&paths).unwrap_or_else(|| paths.config_path.clone());
+            log_config_warn_once(&format!(
+                "Failed to load config from {}: {}",
+                config_path.display(),
+                message
+            ));
+            PluginConfig::default_resolved()
+        }
+    }
+}
+
+fn load_plugin_config_inner(paths: &ConfigPaths) -> Result<PluginConfig, String> {
+    // config-02: keep load precedence symmetric with save — prefer the env
+    // path (when set + existing) over unified settings.
+    let env_path = env_config_path();
+    let mut source_kind_is_file = false;
+    let mut user_config: Value = match env_path.as_deref().filter(|p| Path::new(p).exists()) {
+        Some(existing_env_path) => {
+            let content = read_file_sync_with_config_retry(Path::new(existing_env_path))
+                .map_err(|error| error.to_string())?;
+            source_kind_is_file = true;
+            serde_json::from_str(strip_utf8_bom(&content)).map_err(|error| error.to_string())?
+        }
+        None => match load_unified_plugin_config_sync() {
+            Some(section) => Value::Object(section),
+            None => Value::Null,
+        },
+    };
+
+    if !is_record(&user_config) {
+        let Some(config_path) = resolve_plugin_config_path(paths) else {
+            return Ok(PluginConfig::default_resolved());
+        };
+        let content =
+            read_file_sync_with_config_retry(&config_path).map_err(|error| error.to_string())?;
+        user_config =
+            serde_json::from_str(strip_utf8_bom(&content)).map_err(|error| error.to_string())?;
+        source_kind_is_file = true;
+    }
+
+    let normalized_user_config = sanitize_plugin_config_record(&user_config, true);
+
+    let has_fallback_env_override =
+        std::env::var_os("CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL").is_some()
+            || std::env::var_os("CODEX_AUTH_FALLBACK_GPT53_TO_GPT52").is_some();
+    if let Some(record) = user_config.as_object() {
+        let has_policy_key = record.contains_key("unsupportedCodexPolicy");
+        let has_legacy_fallback_key = record.contains_key("fallbackOnUnsupportedCodexModel")
+            || record.contains_key("fallbackToGpt52OnUnsupportedGpt53")
+            || record.contains_key("unsupportedCodexFallbackChain");
+        if !has_policy_key && (has_legacy_fallback_key || has_fallback_env_override) {
+            log_config_warn_once(
+                "Legacy unsupported-model fallback settings detected without unsupportedCodexPolicy. \
+Using backward-compat behavior; prefer unsupportedCodexPolicy: \"strict\" | \"fallback\".",
+            );
+        }
+    }
+
+    if source_kind_is_file && normalized_user_config.is_some() && env_config_path().is_none() {
+        log_config_warn_once(&format!(
+            "Legacy config file is still in use; settings will migrate to {} on next save.",
+            get_unified_settings_path().display()
+        ));
+    }
+
+    let partial = normalized_user_config
+        .as_ref()
+        .map(plugin_config_from_map)
+        .unwrap_or_default();
+    Ok(PluginConfig::overlay(
+        &PluginConfig::default_resolved(),
+        &partial,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn sanitize_drops_invalid_fields_and_keeps_valid_ones() {
+        let data = json!({
+            "codexMode": false,
+            "toastDurationMs": 500,        // below schema min 1000 → dropped
+            "codexTuiColorProfile": "bogus", // invalid enum → dropped
+            "fetchTimeoutMs": 60000,
+            "someFutureKey": { "x": 1 },   // unknown → not in known-key sanitize
+        });
+        let sanitized = sanitize_plugin_config_record(&data, false).unwrap();
+        assert_eq!(sanitized.get("codexMode"), Some(&json!(false)));
+        assert_eq!(sanitized.get("fetchTimeoutMs"), Some(&json!(60000)));
+        assert!(!sanitized.contains_key("toastDurationMs"));
+        assert!(!sanitized.contains_key("codexTuiColorProfile"));
+        assert!(!sanitized.contains_key("someFutureKey"));
+    }
+
+    #[test]
+    fn sanitize_returns_none_for_non_records() {
+        assert!(sanitize_plugin_config_record(&json!(null), false).is_none());
+        assert!(sanitize_plugin_config_record(&json!([1, 2]), false).is_none());
+        assert!(sanitize_plugin_config_record(&json!("x"), false).is_none());
+    }
+
+    #[test]
+    fn stored_sanitize_preserves_unknown_keys_in_input_order() {
+        let raw = r#"{"futureKey":true,"codexMode":true,"toastDurationMs":1,"anotherUnknown":{"a":1}}"#;
+        let data: Value = serde_json::from_str(raw).unwrap();
+        let sanitized = sanitize_stored_plugin_config_record(&data).unwrap();
+        let keys: Vec<&str> = sanitized.keys().map(String::as_str).collect();
+        // toastDurationMs=1 is invalid (min 1000) → dropped; unknowns kept in place.
+        assert_eq!(keys, vec!["futureKey", "codexMode", "anotherUnknown"]);
+    }
+
+    #[test]
+    fn plugin_config_from_map_round_trips_sanitized_values() {
+        let sanitized = sanitize_plugin_config_record(
+            &json!({ "codexMode": false, "fastSessionMaxInputItems": 42 }),
+            false,
+        )
+        .unwrap();
+        let partial = plugin_config_from_map(&sanitized);
+        assert_eq!(partial.codex_mode, Some(false));
+        assert_eq!(partial.fast_session_max_input_items, Some(42.0));
+        assert_eq!(partial.toast_duration_ms, None);
+    }
+
+    #[test]
+    fn default_plugin_config_is_the_resolved_table() {
+        let defaults = get_default_plugin_config();
+        assert_eq!(defaults, PluginConfig::default_resolved());
+        assert_eq!(defaults.pid_offset_enabled, Some(true));
+    }
+}
diff --git a/crates/config/src/lockfile.rs b/crates/config/src/lockfile.rs
new file mode 100644
index 000000000..0a237458a
--- /dev/null
+++ b/crates/config/src/lockfile.rs
@@ -0,0 +1,437 @@
+//! Port of the cross-process config-save lockfile from `lib/config.ts`
+//! (spec 01 §4.5/§10.2).
+//!
+//! `with_config_file_lock(target, task)` acquires `<target>.lock` via
+//! exclusive create (`wx`, mode 0600) writing a single-line JSON payload
+//! `{"pid":…,"owner":"<uuid>","acquiredAt":…,"expiresAt":…}` + `"\n"`.
+//!
+//! - TTL 10 s; wait timeout 10 s; poll 50 ms.
+//! - Stale detection: parsed finite `expiresAt` → stale iff `expiresAt <=
+//!   now`; ENOENT → stale; unreadable/malformed → mtime heuristic
+//!   (`now - mtime > 10_000` → stale; stat ENOENT → stale; other stat error →
+//!   NOT stale).
+//! - Stale locks are taken over (unlink with EBUSY/EPERM ×5 retry, failures
+//!   swallowed) and the loop re-attempts immediately.
+//! - Transient create errors (EBUSY/EPERM) before the deadline poll-retry;
+//!   at the deadline a fresh foreign lock yields an `"ELOCKTIMEOUT"`-coded
+//!   error with the frozen message.
+//! - Release is OWNER-SAFE: the lockfile is re-read and left alone when it
+//!   carries a different owner token (a stale takeover happened); ENOENT is
+//!   done; an unreadable lockfile is best-effort unlinked anyway.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use serde::Serialize;
+use serde_json::Value;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, code_of, io_error_with_code, with_retry};
+use cma_core::json_io::{strip_utf8_bom, stringify_compact};
+use cma_core::utils::{now_ms, sleep};
+
+/// `CONFIG_LOCK_TTL_MS = 10_000`.
+pub const CONFIG_LOCK_TTL_MS: i64 = 10_000;
+/// `CONFIG_LOCK_WAIT_TIMEOUT_MS = 10_000`.
+pub const CONFIG_LOCK_WAIT_TIMEOUT_MS: i64 = 10_000;
+/// `CONFIG_LOCK_POLL_MS = 50`.
+pub const CONFIG_LOCK_POLL_MS: u64 = 50;
+
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+
+/// The lock payload (serialized field order matches the TS object literal:
+/// pid, owner, acquiredAt, expiresAt).
+#[derive(Debug, Serialize)]
+struct ConfigLockPayload<'a> {
+    pid: u32,
+    owner: &'a str,
+    #[serde(rename = "acquiredAt")]
+    acquired_at: i64,
+    #[serde(rename = "expiresAt")]
+    expires_at: i64,
+}
+
+/// `<target>.lock`.
+pub fn config_lock_path_for(target_path: &Path) -> PathBuf {
+    let mut os = target_path.as_os_str().to_os_string();
+    os.push(".lock");
+    PathBuf::from(os)
+}
+
+fn exponential_10ms() -> Backoff {
+    Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1))))
+}
+
+/// Best-effort unlink with the EBUSY/EPERM ×5 retry; every failure swallowed
+/// (a leftover lockfile is recovered as stale by the next acquirer).
+async fn unlink_config_lock_with_retry(lock_path: &Path) {
+    let _ = with_retry(
+        || {
+            let lock_path = lock_path.to_path_buf();
+            async move { fs::remove_file(&lock_path) }
+        },
+        RetryOptions::<io::Error>::new(5, exponential_10ms()).with_codes(RETRYABLE_FS_CODES),
+    )
+    .await;
+}
+
+/// Owner-safe release: only unlink when the lockfile still carries OUR owner
+/// token (or is unreadable/ownerless).
+async fn release_config_lock_if_owner(lock_path: &Path, owner: &str) {
+    match fs::read(lock_path) {
+        Ok(bytes) => {
+            let content = String::from_utf8_lossy(&bytes);
+            if let Ok(parsed) = serde_json::from_str::<Value>(strip_utf8_bom(&content))
+                && let Some(lock_owner) = parsed.get("owner").and_then(Value::as_str)
+                && !lock_owner.is_empty()
+                && lock_owner != owner
+            {
+                // Lock was taken over by another holder; leave their lock.
+                return;
+            }
+            // Ours / ownerless / malformed → best-effort unlink.
+        }
+        Err(error) => {
+            if error.kind() == io::ErrorKind::NotFound {
+                return;
+            }
+            // Unreadable: fall through and attempt our best-effort unlink.
+        }
+    }
+    unlink_config_lock_with_retry(lock_path).await;
+}
+
+/// `isConfigLockStale` — expiry-first, mtime-heuristic fallback.
+async fn is_config_lock_stale(lock_path: &Path) -> bool {
+    match fs::read(lock_path) {
+        Ok(bytes) => {
+            let content = String::from_utf8_lossy(&bytes);
+            if let Ok(parsed) = serde_json::from_str::<Value>(strip_utf8_bom(&content))
+                && let Some(expires_at) = parsed.get("expiresAt").and_then(Value::as_f64)
+                && expires_at.is_finite()
+            {
+                return expires_at <= now_ms() as f64;
+            }
+            // Unreadable/malformed payload: fall through to the mtime heuristic.
+        }
+        Err(error) => {
+            if error.kind() == io::ErrorKind::NotFound {
+                return true;
+            }
+            // Fall through to the mtime heuristic.
+        }
+    }
+    match cma_core::json_io::file_mtime_ms(lock_path) {
+        Ok(Some(mtime_ms)) => (now_ms() as f64) - mtime_ms > CONFIG_LOCK_TTL_MS as f64,
+        Ok(None) => true,
+        Err(_) => false,
+    }
+}
+
+/// Exclusive-create the lockfile (`wx`, 0600 on unix) and write the payload
+/// line. Any error is returned for the caller's code-based dispatch.
+fn try_create_lock(lock_path: &Path, owner: &str) -> io::Result<()> {
+    let now = now_ms();
+    let payload = ConfigLockPayload {
+        pid: std::process::id(),
+        owner,
+        acquired_at: now,
+        expires_at: now + CONFIG_LOCK_TTL_MS,
+    };
+    let mut options = fs::OpenOptions::new();
+    options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    let mut file = options.open(lock_path)?;
+    use std::io::Write;
+    file.write_all(format!("{}\n", stringify_compact(&payload)).as_bytes())?;
+    Ok(())
+}
+
+/// `withConfigFileLock(targetPath, task)` — see module docs. The task runs
+/// with the lock held; release is owner-safe and always attempted.
+///
+/// Errors from acquisition surface as `io::Error`s converted through
+/// `E::From<io::Error>`; the timeout error carries code `"ELOCKTIMEOUT"`
+/// (recoverable via `cma_core::fs_retry::code_of`).
+pub async fn with_config_file_lock<T, E, F, Fut>(target_path: &Path, task: F) -> Result<T, E>
+where
+    E: From<io::Error>,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+{
+    with_config_file_lock_timeout(target_path, CONFIG_LOCK_WAIT_TIMEOUT_MS, task).await
+}
+
+/// [`with_config_file_lock`] with an injectable wait timeout. The wall-clock
+/// deadline cannot be faked (§8.5 — `now_ms()` parity with `Date.now()`), so
+/// tests exercise the full wait/timeout path through this seam instead of the
+/// production 10 s constant.
+async fn with_config_file_lock_timeout<T, E, F, Fut>(
+    target_path: &Path,
+    wait_timeout_ms: i64,
+    task: F,
+) -> Result<T, E>
+where
+    E: From<io::Error>,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+{
+    let lock_path = config_lock_path_for(target_path);
+    let owner = uuid::Uuid::new_v4().to_string();
+    if let Some(parent) = lock_path.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        fs::create_dir_all(parent).map_err(E::from)?;
+    }
+    let deadline = now_ms() + wait_timeout_ms;
+    loop {
+        match try_create_lock(&lock_path, &owner) {
+            Ok(()) => break,
+            Err(error) => {
+                let code = code_of(&error);
+                if code != Some("EEXIST") {
+                    // A transient FS lock on the lockfile itself: retry until
+                    // the deadline; anything else propagates.
+                    if code.is_some_and(|c| RETRYABLE_FS_CODES.contains(&c))
+                        && now_ms() < deadline
+                    {
+                        sleep(CONFIG_LOCK_POLL_MS).await;
+                        continue;
+                    }
+                    return Err(E::from(error));
+                }
+                // Lock is held. Take it over if the holder expired/crashed;
+                // otherwise wait.
+                if is_config_lock_stale(&lock_path).await {
+                    unlink_config_lock_with_retry(&lock_path).await;
+                    continue;
+                }
+                if now_ms() >= deadline {
+                    return Err(E::from(io_error_with_code(
+                        "ELOCKTIMEOUT",
+                        format!(
+                            "Timed out acquiring config save lock at {}.",
+                            lock_path.display()
+                        ),
+                    )));
+                }
+                sleep(CONFIG_LOCK_POLL_MS).await;
+            }
+        }
+    }
+    let result = task().await;
+    release_config_lock_if_owner(&lock_path, &owner).await;
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn tempdir() -> tempfile::TempDir {
+        tempfile::tempdir().expect("tempdir")
+    }
+
+    #[tokio::test]
+    async fn acquires_writes_payload_line_and_releases() {
+        let dir = tempdir();
+        let target = dir.path().join("config.json");
+        let lock_path = config_lock_path_for(&target);
+
+        let observed_lock = lock_path.clone();
+        let result: Result<&str, io::Error> = with_config_file_lock(&target, || async move {
+            let content = fs::read_to_string(&observed_lock).expect("lock exists during task");
+            assert!(content.ends_with('\n'), "single line + newline");
+            let parsed: Value = serde_json::from_str(content.trim_end()).unwrap();
+            let keys: Vec<&str> = parsed.as_object().unwrap().keys().map(String::as_str).collect();
+            assert_eq!(keys, vec!["pid", "owner", "acquiredAt", "expiresAt"]);
+            assert_eq!(parsed["pid"], json!(std::process::id()));
+            let acquired = parsed["acquiredAt"].as_i64().unwrap();
+            let expires = parsed["expiresAt"].as_i64().unwrap();
+            assert_eq!(expires - acquired, CONFIG_LOCK_TTL_MS);
+            Ok("done")
+        })
+        .await;
+        assert_eq!(result.unwrap(), "done");
+        assert!(!lock_path.exists(), "lock released after the task");
+    }
+
+    #[tokio::test]
+    async fn takes_over_a_stale_foreign_lock_and_removes_only_its_own() {
+        // config-18: expired foreign lock is stolen; our release removes OUR
+        // lock, not a hypothetical newer one.
+        let dir = tempdir();
+        let target = dir.path().join("config.json");
+        let lock_path = config_lock_path_for(&target);
+        let stale_payload = json!({
+            "pid": 12345,
+            "owner": "someone-else",
+            "acquiredAt": now_ms() - 60_000,
+            "expiresAt": now_ms() - 50_000,
+        });
+        fs::write(&lock_path, format!("{stale_payload}\n")).unwrap();
+
+        let result: Result<(), io::Error> =
+            with_config_file_lock(&target, || async { Ok(()) }).await;
+        assert!(result.is_ok());
+        assert!(!lock_path.exists());
+    }
+
+    #[tokio::test]
+    async fn owner_safe_release_leaves_a_foreign_lock_in_place() {
+        let dir = tempdir();
+        let lock_path = dir.path().join("config.json.lock");
+        fs::write(
+            &lock_path,
+            format!("{}\n", json!({ "owner": "other-owner", "expiresAt": now_ms() + 60_000 })),
+        )
+        .unwrap();
+        release_config_lock_if_owner(&lock_path, "my-owner").await;
+        assert!(lock_path.exists(), "foreign lock must not be deleted");
+
+        // Ownerless / malformed lock IS unlinked.
+        fs::write(&lock_path, "not json").unwrap();
+        release_config_lock_if_owner(&lock_path, "my-owner").await;
+        assert!(!lock_path.exists());
+    }
+
+    #[tokio::test]
+    async fn staleness_rules_match_the_ts_matrix() {
+        let dir = tempdir();
+        let lock_path = dir.path().join("config.json.lock");
+
+        // Missing → stale.
+        assert!(is_config_lock_stale(&lock_path).await);
+
+        // Fresh expiry → not stale.
+        fs::write(
+            &lock_path,
+            format!("{}\n", json!({ "expiresAt": now_ms() + 60_000 })),
+        )
+        .unwrap();
+        assert!(!is_config_lock_stale(&lock_path).await);
+
+        // Expired → stale.
+        fs::write(
+            &lock_path,
+            format!("{}\n", json!({ "expiresAt": now_ms() - 1_000 })),
+        )
+        .unwrap();
+        assert!(is_config_lock_stale(&lock_path).await);
+
+        // Malformed + fresh mtime → NOT stale (mtime heuristic).
+        fs::write(&lock_path, "garbage").unwrap();
+        assert!(!is_config_lock_stale(&lock_path).await);
+
+        // BOM-prefixed payload parses (lockfile parse DOES strip BOM).
+        fs::write(
+            &lock_path,
+            format!("\u{feff}{}\n", json!({ "expiresAt": now_ms() - 1 })),
+        )
+        .unwrap();
+        assert!(is_config_lock_stale(&lock_path).await);
+    }
+
+    #[tokio::test]
+    async fn serializes_two_contenders_in_process() {
+        // The second acquirer sees a fresh lock and waits (poll 50 ms) until
+        // release, then proceeds — no ELOCKTIMEOUT under normal handoff.
+        let dir = tempdir();
+        let target = dir.path().join("config.json");
+        let marker = dir.path().join("order.txt");
+
+        let target_a = target.clone();
+        let marker_a = marker.clone();
+        let first = tokio::spawn(async move {
+            with_config_file_lock::<_, io::Error, _, _>(&target_a, || async move {
+                cma_core::utils::sleep(120).await;
+                fs::write(&marker_a, "first").unwrap();
+                Ok(())
+            })
+            .await
+        });
+        // Give the first task time to grab the lock.
+        cma_core::utils::sleep(30).await;
+        let target_b = target.clone();
+        let marker_b = marker.clone();
+        let second = tokio::spawn(async move {
+            with_config_file_lock::<_, io::Error, _, _>(&target_b, || async move {
+                let previous = fs::read_to_string(&marker_b).unwrap_or_default();
+                assert_eq!(previous, "first", "second holder runs after the first");
+                Ok(())
+            })
+            .await
+        });
+        first.await.unwrap().unwrap();
+        second.await.unwrap().unwrap();
+    }
+
+    #[tokio::test]
+    async fn waits_then_times_out_with_elocktimeout_against_a_live_foreign_lock() {
+        // End-to-end timeout path: a FRESH foreign lock (far-future
+        // `expiresAt`) is never taken over, the acquirer polls until the
+        // deadline, and the frozen ELOCKTIMEOUT error surfaces. The wait
+        // timeout is shortened through the internal seam because the
+        // deadline is wall-clock (§8.5) and cannot be faked.
+        let dir = tempdir();
+        let target = dir.path().join("config.json");
+        let lock_path = config_lock_path_for(&target);
+        fs::write(
+            &lock_path,
+            format!(
+                "{}\n",
+                json!({
+                    "pid": 999_999,
+                    "owner": "foreign-owner",
+                    "acquiredAt": now_ms(),
+                    "expiresAt": now_ms() + 60_000,
+                })
+            ),
+        )
+        .unwrap();
+
+        let task_ran = std::sync::atomic::AtomicBool::new(false);
+        let started = now_ms();
+        let result: Result<(), io::Error> =
+            with_config_file_lock_timeout(&target, 250, || async {
+                task_ran.store(true, std::sync::atomic::Ordering::SeqCst);
+                Ok(())
+            })
+            .await;
+        let error = result.expect_err("a live foreign lock must time the acquirer out");
+        assert_eq!(code_of(&error), Some("ELOCKTIMEOUT"));
+        assert_eq!(
+            error.to_string(),
+            format!(
+                "Timed out acquiring config save lock at {}.",
+                lock_path.display()
+            )
+        );
+        assert!(
+            !task_ran.load(std::sync::atomic::Ordering::SeqCst),
+            "task must never run while the foreign lock is held"
+        );
+        // The loop really waited through the poll cycle to the deadline.
+        assert!(now_ms() - started >= 250);
+        // Owner-safety: the foreign lock is left untouched (no takeover, no
+        // release-unlink of someone else's lock).
+        let remaining: Value =
+            serde_json::from_str(fs::read_to_string(&lock_path).unwrap().trim()).unwrap();
+        assert_eq!(remaining.get("owner"), Some(&json!("foreign-owner")));
+    }
+
+    #[test]
+    fn frozen_timeout_message_shape() {
+        let error = io_error_with_code(
+            "ELOCKTIMEOUT",
+            "Timed out acquiring config save lock at /tmp/x.lock.".to_string(),
+        );
+        assert_eq!(code_of(&error), Some("ELOCKTIMEOUT"));
+        assert!(error.to_string().starts_with("Timed out acquiring config save lock at"));
+    }
+}
diff --git a/crates/config/src/save.rs b/crates/config/src/save.rs
new file mode 100644
index 000000000..967a64a54
--- /dev/null
+++ b/crates/config/src/save.rs
@@ -0,0 +1,465 @@
+//! Port of the save half of `lib/config.ts` — `savePluginConfig` (spec 01
+//! §4.3, verbatim algorithm).
+//!
+//! 1. Sanitize the patch per-field; dropped keys → warn-once
+//!    `Ignoring invalid plugin config field(s): <keys>.`
+//! 2. Env-path branch (`CODEX_MULTI_AUTH_CONFIG_PATH` set, even if the file
+//!    does not exist yet — gotcha 1): per-path in-process queue → cross-process
+//!    lockfile → 3-try ESTALE mtime-CAS around stat → classify-read → merge
+//!    (unknown keys PRESERVED) → atomic write.
+//! 3. Unified branch: in-process queue on the unified path → classify-read of
+//!    settings.json → `pluginConfig` section (or sync loader fallback) →
+//!    legacy-file fallback when the section is absent → merge →
+//!    `save_unified_plugin_config` (which replaces the whole section while
+//!    preserving sibling sections).
+//!
+//! `status == "unreadable"` anywhere aborts with the frozen `StorageError`
+//! (`"Aborting config save because <path> is unreadable."`, code
+//! `"UNREADABLE"`, hint `"Fix or remove the unreadable config file, then
+//! retry the save."`). `invalid`/`missing` rebuild from the patch (gotcha 12).
+
+use std::collections::HashMap;
+use std::fmt;
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, LazyLock, Mutex as StdMutex};
+
+use serde_json::{Map, Value};
+use tokio::sync::Mutex as AsyncMutex;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{
+    Backoff, HasErrorCode, RetryOptions, code_of, io_error_with_code, with_retry,
+};
+use cma_core::json_io::{file_mtime_ms, stringify_pretty2};
+use cma_core::schemas::plugin_config::{PLUGIN_CONFIG_KEYS, PluginConfig};
+use cma_core::temp_path::temp_path_for;
+
+use crate::load::{
+    ConfigReadState, RETRYABLE_CONFIG_READ_CODES, RETRYABLE_FS_CODES, env_config_path,
+    log_config_warn_once, read_config_record_for_save, resolve_plugin_config_path,
+    sanitize_plugin_config_record, sanitize_stored_plugin_config_record,
+};
+use crate::lockfile::with_config_file_lock;
+use crate::unified_settings::{get_unified_settings_path, load_unified_plugin_config_sync,
+    save_unified_plugin_config};
+
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+
+/// Failure of [`save_plugin_config`]: either the typed `StorageError`
+/// (`code() == "UNREADABLE"`) or an IO failure (whose Node-style code —
+/// `"ELOCKTIMEOUT"`, `"ESTALE"`, errno strings — is recoverable through
+/// [`HasErrorCode`]).
+#[derive(Debug)]
+pub enum ConfigSaveError {
+    Storage(CodexError),
+    Io(io::Error),
+}
+
+impl fmt::Display for ConfigSaveError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ConfigSaveError::Storage(error) => write!(f, "{}", error.message()),
+            ConfigSaveError::Io(error) => write!(f, "{error}"),
+        }
+    }
+}
+
+impl std::error::Error for ConfigSaveError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ConfigSaveError::Storage(error) => Some(error),
+            ConfigSaveError::Io(error) => Some(error),
+        }
+    }
+}
+
+impl From<io::Error> for ConfigSaveError {
+    fn from(error: io::Error) -> Self {
+        ConfigSaveError::Io(error)
+    }
+}
+
+impl HasErrorCode for ConfigSaveError {
+    fn error_code(&self) -> Option<&str> {
+        match self {
+            ConfigSaveError::Storage(error) => Some(error.code()),
+            ConfigSaveError::Io(error) => code_of(error),
+        }
+    }
+}
+
+impl ConfigSaveError {
+    /// The typed `StorageError` when this failure was an unreadable-abort.
+    pub fn as_storage(&self) -> Option<&CodexError> {
+        match self {
+            ConfigSaveError::Storage(error) => Some(error),
+            ConfigSaveError::Io(_) => None,
+        }
+    }
+}
+
+/// `unreadableConfigSaveError` — frozen message/hint (spec 01 §8).
+fn unreadable_config_save_error(config_path: &Path, error_message: &str) -> CodexError {
+    CodexError::storage(
+        format!(
+            "Aborting config save because {} is unreadable.",
+            config_path.display()
+        ),
+        "UNREADABLE",
+        config_path.display().to_string(),
+        "Fix or remove the unreadable config file, then retry the save.",
+        Some(Box::new(io::Error::other(error_message.to_string()))),
+    )
+}
+
+// ---------------------------------------------------------------------------
+// In-process per-path save queue (TS `configSaveQueues`)
+// ---------------------------------------------------------------------------
+
+static CONFIG_SAVE_QUEUES: LazyLock<StdMutex<HashMap<PathBuf, Arc<AsyncMutex<()>>>>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+
+/// `withConfigSaveLock` — FIFO per-path serialization; the map entry is
+/// removed when the last queued task finishes (predecessor failures never
+/// block successors — the tokio Mutex releases on drop regardless).
+async fn with_config_save_lock<T, F, Fut>(path: &Path, task: F) -> T
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = T>,
+{
+    let mutex = {
+        let mut queues = CONFIG_SAVE_QUEUES.lock().unwrap_or_else(|p| p.into_inner());
+        Arc::clone(
+            queues
+                .entry(path.to_path_buf())
+                .or_insert_with(|| Arc::new(AsyncMutex::new(()))),
+        )
+    };
+    let result = {
+        let _guard = mutex.lock().await;
+        task().await
+    };
+    {
+        let mut queues = CONFIG_SAVE_QUEUES.lock().unwrap_or_else(|p| p.into_inner());
+        // 2 == the map's reference + ours: nobody else is queued on this path.
+        if Arc::strong_count(&mutex) == 2 {
+            queues.remove(path);
+        }
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Patch sanitization
+// ---------------------------------------------------------------------------
+
+/// `sanitizePluginConfigForSave` — per-field validation (known keys only;
+/// unknown patch keys are silently dropped), plus the dropped-keys list for
+/// the warn-once. Non-finite numbers cannot occur in JSON input; nested
+/// records are cloned (shallow-copy parity).
+pub(crate) fn sanitize_plugin_config_for_save(
+    config_patch: &Map<String, Value>,
+) -> (Map<String, Value>, Vec<&'static str>) {
+    let normalized =
+        sanitize_plugin_config_record(&Value::Object(config_patch.clone()), false)
+            .unwrap_or_default();
+    let dropped_keys: Vec<&'static str> = PLUGIN_CONFIG_KEYS
+        .iter()
+        .copied()
+        .filter(|key| config_patch.contains_key(*key) && !normalized.contains_key(*key))
+        .collect();
+    (normalized, dropped_keys)
+}
+
+// ---------------------------------------------------------------------------
+// Env-path write plumbing
+// ---------------------------------------------------------------------------
+
+/// `getConfigFileMtimeMs` — retried stat (5 attempts, 10/20/40/80 ms,
+/// EBUSY/EPERM/EAGAIN; config-08). ENOENT → `None` immediately.
+async fn get_config_file_mtime_ms(file_path: &Path) -> io::Result<Option<f64>> {
+    with_retry(
+        || {
+            let file_path = file_path.to_path_buf();
+            async move { file_mtime_ms(&file_path) }
+        },
+        RetryOptions::<io::Error>::new(
+            5,
+            Backoff::from_fn(|attempt| {
+                10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+            }),
+        )
+        .with_codes(RETRYABLE_CONFIG_READ_CODES),
+    )
+    .await
+}
+
+/// `writeJsonFileAtomicWithRetry` — temp stage (`tempPathFor`), mkdir -p,
+/// `JSON.stringify(payload, null, 2)` + `"\n"`, mtime CAS via the RETRIED
+/// stat (mismatch → `"ESTALE"` with the frozen config message), rename with
+/// EBUSY/EPERM ×5 (10/20/40/80 ms), best-effort temp unlink on failure.
+async fn write_json_file_atomic_with_retry(
+    file_path: &Path,
+    payload: &Map<String, Value>,
+    expected_mtime_ms: Option<f64>,
+) -> io::Result<()> {
+    let temp_path = temp_path_for(file_path);
+    if let Some(parent) = file_path.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        fs::create_dir_all(parent)?;
+    }
+    let data = format!("{}\n", stringify_pretty2(&Value::Object(payload.clone())));
+    fs::write(&temp_path, &data)?;
+
+    let outcome: io::Result<()> = async {
+        // Compare-and-swap guard: if a concurrent writer changed the target
+        // since the caller read it, abort with ESTALE so the caller re-reads
+        // and merges instead of clobbering the other write.
+        let current_mtime_ms = get_config_file_mtime_ms(file_path).await?;
+        if current_mtime_ms != expected_mtime_ms {
+            return Err(io_error_with_code(
+                "ESTALE",
+                format!(
+                    "Config at {} changed on disk during save; retrying with latest state.",
+                    file_path.display()
+                ),
+            ));
+        }
+        with_retry(
+            || {
+                let temp_path = temp_path.clone();
+                let file_path = file_path.to_path_buf();
+                async move { fs::rename(&temp_path, &file_path) }
+            },
+            RetryOptions::<io::Error>::new(
+                5,
+                Backoff::from_fn(|attempt| {
+                    10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+                }),
+            )
+            .with_codes(RETRYABLE_FS_CODES),
+        )
+        .await
+    }
+    .await;
+
+    if outcome.is_err() {
+        let _ = fs::remove_file(&temp_path);
+    }
+    outcome
+}
+
+// ---------------------------------------------------------------------------
+// savePluginConfig
+// ---------------------------------------------------------------------------
+
+/// JS spread merge `{...existing, ...patch}` over order-preserving maps.
+fn merge_records(
+    existing: Option<&Map<String, Value>>,
+    patch: &Map<String, Value>,
+) -> Map<String, Value> {
+    let mut merged = existing.cloned().unwrap_or_default();
+    for (key, value) in patch {
+        merged.insert(key.clone(), value.clone());
+    }
+    merged
+}
+
+/// `savePluginConfig(configPatch)` — the full §4.3 algorithm. The patch is a
+/// raw JSON record so invalid values can be observed and dropped exactly like
+/// the TS `Partial<PluginConfig>` path; use [`save_plugin_config_typed`] for
+/// an already-typed patch.
+pub async fn save_plugin_config(config_patch: &Map<String, Value>) -> Result<(), ConfigSaveError> {
+    let (sanitized_patch, dropped_keys) = sanitize_plugin_config_for_save(config_patch);
+    if !dropped_keys.is_empty() {
+        log_config_warn_once(&format!(
+            "Ignoring invalid plugin config field(s): {}.",
+            dropped_keys.join(", ")
+        ));
+    }
+
+    if let Some(env_path) = env_config_path() {
+        let env_path = PathBuf::from(env_path);
+        return with_config_save_lock(&env_path, || async {
+            // In-process queue is the cheap fast path; the cross-process file
+            // lock closes the read→merge→rename TOCTOU window against OTHER
+            // processes; the mtime CAS stays as a second-line guard.
+            with_config_file_lock(&env_path, || async {
+                with_retry(
+                    || async {
+                        let expected_mtime_ms = get_config_file_mtime_ms(&env_path).await?;
+                        let env_config_state = read_config_record_for_save(&env_path).await;
+                        let existing_config = match env_config_state {
+                            ConfigReadState::Unreadable { error_message } => {
+                                return Err(ConfigSaveError::Storage(
+                                    unreadable_config_save_error(&env_path, &error_message),
+                                ));
+                            }
+                            ConfigReadState::Ok(record) => {
+                                sanitize_stored_plugin_config_record(&Value::Object(record))
+                            }
+                            ConfigReadState::Invalid { .. } | ConfigReadState::Missing => None,
+                        };
+                        let merged = merge_records(existing_config.as_ref(), &sanitized_patch);
+                        write_json_file_atomic_with_retry(&env_path, &merged, expected_mtime_ms)
+                            .await?;
+                        Ok(())
+                    },
+                    RetryOptions::<ConfigSaveError>::fixed(3, 0).with_codes(&["ESTALE"]),
+                )
+                .await
+            })
+            .await
+        })
+        .await;
+    }
+
+    let unified_path = get_unified_settings_path();
+    with_config_save_lock(&unified_path, || async {
+        let unified_config_state = read_config_record_for_save(&unified_path).await;
+        let unified_config_record: Value = match &unified_config_state {
+            ConfigReadState::Unreadable { error_message } => {
+                return Err(ConfigSaveError::Storage(unreadable_config_save_error(
+                    &unified_path,
+                    error_message,
+                )));
+            }
+            ConfigReadState::Ok(record) => {
+                record.get("pluginConfig").cloned().unwrap_or(Value::Null)
+            }
+            _ => match load_unified_plugin_config_sync() {
+                Some(section) => Value::Object(section),
+                None => Value::Null,
+            },
+        };
+        let unified_config = sanitize_stored_plugin_config_record(&unified_config_record);
+        let legacy_path = if unified_config.is_none() {
+            resolve_plugin_config_path(&crate::load::ConfigPaths::resolve())
+        } else {
+            None
+        };
+        let legacy_config = match &legacy_path {
+            Some(path) => match read_config_record_for_save(path).await {
+                ConfigReadState::Unreadable { error_message } => {
+                    return Err(ConfigSaveError::Storage(unreadable_config_save_error(
+                        path,
+                        &error_message,
+                    )));
+                }
+                ConfigReadState::Ok(record) => {
+                    sanitize_stored_plugin_config_record(&Value::Object(record))
+                }
+                _ => None,
+            },
+            None => None,
+        };
+        let base = unified_config.or(legacy_config);
+        let merged = merge_records(base.as_ref(), &sanitized_patch);
+        save_unified_plugin_config(&merged)
+            .await
+            .map_err(ConfigSaveError::Io)
+    })
+    .await
+}
+
+/// Convenience wrapper: serialize a typed partial [`PluginConfig`] (only its
+/// `Some` fields) and delegate to [`save_plugin_config`].
+pub async fn save_plugin_config_typed(patch: &PluginConfig) -> Result<(), ConfigSaveError> {
+    let value = serde_json::to_value(patch).unwrap_or_else(|_| Value::Object(Map::new()));
+    let map = match value {
+        Value::Object(map) => map,
+        _ => Map::new(),
+    };
+    save_plugin_config(&map).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn sanitize_for_save_drops_invalid_known_keys_and_reports_them() {
+        let patch: Map<String, Value> = serde_json::from_value(json!({
+            "codexMode": true,
+            "toastDurationMs": 10,        // below min 1000 → dropped + reported
+            "codexTuiGlyphMode": "wrong", // invalid enum → dropped + reported
+            "someUnknown": 1,             // unknown → silently dropped, NOT reported
+        }))
+        .unwrap();
+        let (sanitized, dropped) = sanitize_plugin_config_for_save(&patch);
+        assert_eq!(sanitized.get("codexMode"), Some(&json!(true)));
+        assert!(!sanitized.contains_key("toastDurationMs"));
+        assert!(!sanitized.contains_key("someUnknown"));
+        assert_eq!(dropped, vec!["codexTuiGlyphMode", "toastDurationMs"]);
+    }
+
+    #[test]
+    fn dropped_keys_follow_schema_declaration_order() {
+        let patch: Map<String, Value> = serde_json::from_value(json!({
+            "schedulingStrategy": "nope",
+            "codexMode": "not-a-bool",
+        }))
+        .unwrap();
+        let (_, dropped) = sanitize_plugin_config_for_save(&patch);
+        // PLUGIN_CONFIG_KEYS order, not input order.
+        assert_eq!(dropped, vec!["codexMode", "schedulingStrategy"]);
+    }
+
+    #[test]
+    fn merge_overlays_patch_and_preserves_existing_key_positions() {
+        let existing: Map<String, Value> =
+            serde_json::from_str(r#"{"futureKey":1,"codexMode":true,"other":2}"#).unwrap();
+        let patch: Map<String, Value> =
+            serde_json::from_str(r#"{"codexMode":false,"fastSession":true}"#).unwrap();
+        let merged = merge_records(Some(&existing), &patch);
+        let keys: Vec<&str> = merged.keys().map(String::as_str).collect();
+        assert_eq!(keys, vec!["futureKey", "codexMode", "other", "fastSession"]);
+        assert_eq!(merged.get("codexMode"), Some(&json!(false)));
+    }
+
+    #[test]
+    fn unreadable_error_carries_frozen_message_code_path_and_hint() {
+        let error = unreadable_config_save_error(Path::new("/tmp/config.json"), "boom");
+        assert_eq!(error.code(), "UNREADABLE");
+        assert!(
+            error
+                .message()
+                .starts_with("Aborting config save because "),
+            "message: {}",
+            error.message()
+        );
+        assert!(error.message().ends_with(" is unreadable."));
+        assert_eq!(
+            error.hint(),
+            Some("Fix or remove the unreadable config file, then retry the save.")
+        );
+        assert!(error.path().is_some());
+    }
+
+    #[tokio::test]
+    async fn write_json_file_atomic_cas_mismatch_yields_estale() {
+        let dir = tempfile::tempdir().unwrap();
+        let target = dir.path().join("config.json");
+        fs::write(&target, "{}").unwrap();
+        let payload: Map<String, Value> = Map::new();
+        // Expect "missing" while the file exists → ESTALE.
+        let error = write_json_file_atomic_with_retry(&target, &payload, None)
+            .await
+            .unwrap_err();
+        assert_eq!(code_of(&error), Some("ESTALE"));
+        assert!(error.to_string().contains("changed on disk during save"));
+        // Temp cleaned up.
+        let leftovers: Vec<_> = fs::read_dir(dir.path())
+            .unwrap()
+            .filter_map(|e| e.ok())
+            .filter(|e| e.file_name().to_string_lossy().ends_with(".tmp"))
+            .collect();
+        assert!(leftovers.is_empty());
+    }
+}
diff --git a/crates/config/src/unified_settings.rs b/crates/config/src/unified_settings.rs
new file mode 100644
index 000000000..a735498b0
--- /dev/null
+++ b/crates/config/src/unified_settings.rs
@@ -0,0 +1,417 @@
+//! Port of `lib/unified-settings.ts` — the single persisted settings file
+//! `<multi-auth-dir>/settings.json` (version 1).
+//!
+//! Behavior source: spec 01 §2.10/§4.1/§6/§10.3-§10.4 + the TS source. Key
+//! contracts preserved verbatim:
+//!
+//! - `.bak` fallback ONLY when the primary exists AND the read failure is not
+//!   ENOENT and not a transient lock code (`EBUSY`/`EAGAIN` are RETHROWN so
+//!   callers can retry — gotcha 11). Corrupt backups are treated as absent; a
+//!   corrupt primary with no usable backup reads as missing (`record: null`).
+//! - When a read fell back to the backup, the next write SKIPS the backup
+//!   snapshot so the corrupt primary can't clobber the only good copy
+//!   (gotcha 10 — `usedBackup` threads through the save).
+//! - `normalizeForWrite` = spread-then-assign: an existing `version` key keeps
+//!   its ORIGINAL key position while being forced to 1; a new file gets
+//!   `version` LAST (gotcha 23).
+//! - Async saves are serialized on ONE global in-process write queue across
+//!   BOTH sections (`pluginConfig` + `dashboardDisplaySettings`), with a
+//!   3-attempt mtime CAS against cross-process writers (`ESTALE` re-reads).
+//! - Serialization: `JSON.stringify(payload, null, 2)` + trailing `"\n"`
+//!   (via `cma_core::json_io::stringify_pretty2`). No BOM strip on parse
+//!   (gotcha 6 — writers are always this tool).
+//! - The sync writer stages to `<path>.<pid>.<epochMs>.tmp` (no random
+//!   component) and retries renames immediately; the async writer stages via
+//!   `temp_path_for` and sleeps 10/20/40/80 ms between rename attempts.
+
+use std::fs;
+use std::io;
+use std::path::PathBuf;
+
+use serde_json::{Map, Value};
+use tokio::sync::Mutex as AsyncMutex;
+
+use cma_core::fs_retry::{RetryOptions, code_of, with_retry_sync};
+use cma_core::json_io::{
+    BackupOptions, MtimeCas, TrailingNewline, WriteJsonOptions, file_mtime_ms, stringify_pretty2,
+    write_json_atomic,
+};
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::now_ms;
+
+pub type JsonRecord = Map<String, Value>;
+
+/// `UNIFIED_SETTINGS_VERSION = 1`.
+pub const UNIFIED_SETTINGS_VERSION: u64 = 1;
+
+/// Message of the (private in TS) `InvalidSettingsRecordError` — distinguishes
+/// corrupt-shape from IO failures for backup-fallback decisions (spec 01 §8).
+pub const INVALID_SETTINGS_RECORD_MESSAGE: &str =
+    "Unified settings must contain a JSON object at the root.";
+
+/// The stale-write CAS message minted with code `"ESTALE"` (spec 01 §8).
+pub const UNIFIED_SETTINGS_STALE_MESSAGE: &str =
+    "Unified settings changed on disk during save; retrying with latest state.";
+
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+const TRANSIENT_READ_FS_CODES: &[&str] = &["EBUSY", "EAGAIN"];
+
+/// One global in-process write queue serializing async saves for BOTH
+/// sections (TS `settingsWriteQueue`). tokio's Mutex is FIFO-fair, matching
+/// the promise-chain ordering.
+static SETTINGS_WRITE_QUEUE: AsyncMutex<()> = AsyncMutex::const_new(());
+
+/// `<multi-auth-dir>/settings.json`. Reads the live environment on every call
+/// (the TS module computed it once at import; per-call resolution is
+/// behavior-equivalent for a single process run and required for env
+/// sandboxing in tests).
+pub fn get_unified_settings_path() -> PathBuf {
+    get_codex_multi_auth_dir().join("settings.json")
+}
+
+/// `<settings.json>.bak` — the snapshot target.
+pub fn get_unified_settings_backup_path() -> PathBuf {
+    let mut os = get_unified_settings_path().into_os_string();
+    os.push(".bak");
+    PathBuf::from(os)
+}
+
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+
+/// Internal read-failure classification: `Invalid` covers both JSON syntax
+/// errors and the non-object-root `InvalidSettingsRecordError`; `Io` carries
+/// real filesystem failures (whose errno codes drive fallback decisions).
+enum SettingsReadError {
+    Io(io::Error),
+    /// SyntaxError or invalid root shape; carries the message for the rare
+    /// rethrow path.
+    Invalid(String),
+}
+
+impl SettingsReadError {
+    fn into_io(self) -> io::Error {
+        match self {
+            SettingsReadError::Io(error) => error,
+            SettingsReadError::Invalid(message) => io::Error::other(message),
+        }
+    }
+
+    fn is_invalid(&self) -> bool {
+        matches!(self, SettingsReadError::Invalid(_))
+    }
+
+    fn code(&self) -> Option<&str> {
+        match self {
+            SettingsReadError::Io(error) => code_of(error),
+            SettingsReadError::Invalid(_) => None,
+        }
+    }
+}
+
+struct SettingsReadResult {
+    record: Option<JsonRecord>,
+    used_backup: bool,
+}
+
+/// `readSettingsRecord*FromPath`: `Ok(None)` on ENOENT; `Invalid` on parse
+/// failure or non-object root; NO BOM stripping (gotcha 6).
+fn read_settings_record_from_path(
+    path: &std::path::Path,
+) -> Result<Option<JsonRecord>, SettingsReadError> {
+    let raw = match fs::read(path) {
+        Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => return Err(SettingsReadError::Io(error)),
+    };
+    let parsed: Value = serde_json::from_str(&raw)
+        .map_err(|error| SettingsReadError::Invalid(error.to_string()))?;
+    match parsed {
+        Value::Object(map) => Ok(Some(map)),
+        _ => Err(SettingsReadError::Invalid(
+            INVALID_SETTINGS_RECORD_MESSAGE.to_string(),
+        )),
+    }
+}
+
+/// Backup reader: corrupt backups collapse to `None`; unreadable/locked
+/// backups surface as errors so writers do not rebuild from `{}` over a
+/// transient failure.
+fn read_settings_backup() -> Result<Option<JsonRecord>, io::Error> {
+    match read_settings_record_from_path(&get_unified_settings_backup_path()) {
+        Ok(record) => Ok(record),
+        Err(error) if error.is_invalid() => Ok(None),
+        Err(error) => Err(error.into_io()),
+    }
+}
+
+/// `shouldFallbackToSettingsBackup`: missing primaries stay missing; corrupt
+/// or unreadable primaries may fall back; transient lock errors rethrow.
+fn should_fallback_to_settings_backup(primary_exists: bool, error: &SettingsReadError) -> bool {
+    if !primary_exists {
+        return false;
+    }
+    match error.code() {
+        Some("ENOENT") => false,
+        Some(code) if TRANSIENT_READ_FS_CODES.contains(&code) => false,
+        _ => true,
+    }
+}
+
+/// `readSettingsRecordSyncInternal` / `readSettingsRecordAsyncInternal` (the
+/// logic is identical; reads are small files, so both call sites use this
+/// synchronous core).
+fn read_settings_record_internal() -> Result<SettingsReadResult, io::Error> {
+    let primary_path = get_unified_settings_path();
+    let primary_exists = primary_path.exists();
+    match read_settings_record_from_path(&primary_path) {
+        Ok(Some(record)) => Ok(SettingsReadResult {
+            record: Some(record),
+            used_backup: false,
+        }),
+        Ok(None) => Ok(SettingsReadResult {
+            record: None,
+            used_backup: false,
+        }),
+        Err(error) => {
+            if !should_fallback_to_settings_backup(primary_exists, &error) {
+                return Err(error.into_io());
+            }
+            if let Some(backup) = read_settings_backup()? {
+                return Ok(SettingsReadResult {
+                    record: Some(backup),
+                    used_backup: true,
+                });
+            }
+            if error.is_invalid() {
+                return Ok(SettingsReadResult {
+                    record: None,
+                    used_backup: false,
+                });
+            }
+            Err(error.into_io())
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+/// `normalizeForWrite`: `{...record, version: 1}` — an existing `version` key
+/// keeps its position (Map::insert replaces in place), a new one appends last.
+fn normalize_for_write(record: &JsonRecord) -> JsonRecord {
+    let mut payload = record.clone();
+    payload.insert(
+        "version".to_string(),
+        Value::Number(UNIFIED_SETTINGS_VERSION.into()),
+    );
+    payload
+}
+
+/// Sync snapshot of settings.json → settings.json.bak: 5 attempts, retry only
+/// EBUSY/EPERM, immediate (no sleeping — spec 01 §10.1), silent give-up.
+fn try_snapshot_unified_settings_backup_sync(skip_because_backup_read: bool) {
+    if skip_because_backup_read {
+        return;
+    }
+    let primary = get_unified_settings_path();
+    if !primary.exists() {
+        return;
+    }
+    let backup = get_unified_settings_backup_path();
+    let _ = with_retry_sync(
+        || fs::copy(&primary, &backup).map(|_| ()),
+        RetryOptions::<io::Error>::fixed(5, 0).with_codes(RETRYABLE_FS_CODES),
+    );
+}
+
+/// `writeSettingsRecordSync` — stages to `<path>.<pid>.<epochMs>.tmp` (NO
+/// random component, matching the TS sync writer exactly), snapshot first,
+/// rename retried 5× immediately on EBUSY/EPERM, temp unlinked on failure.
+fn write_settings_record_sync(record: &JsonRecord, skip_backup_snapshot: bool) -> io::Result<()> {
+    fs::create_dir_all(get_codex_multi_auth_dir())?;
+    let payload = normalize_for_write(record);
+    let data = format!("{}\n", stringify_pretty2(&Value::Object(payload)));
+    let target = get_unified_settings_path();
+    let temp = {
+        let mut os = target.clone().into_os_string();
+        os.push(format!(".{}.{}.tmp", std::process::id(), now_ms()));
+        PathBuf::from(os)
+    };
+    try_snapshot_unified_settings_backup_sync(skip_backup_snapshot);
+    fs::write(&temp, &data)?;
+    let rename_result = with_retry_sync(
+        || fs::rename(&temp, &target),
+        RetryOptions::<io::Error>::fixed(5, 0).with_codes(RETRYABLE_FS_CODES),
+    );
+    if let Err(error) = rename_result {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+    Ok(())
+}
+
+/// `writeSettingsRecordAsync` — temp via `temp_path_for`, optional backup
+/// snapshot, mtime CAS (mismatch → `"ESTALE"`), rename retried 5× with
+/// 10/20/40/80 ms sleeps, temp unlinked on failure. Delegates to the shared
+/// `json_io::write_json_atomic` protocol, which implements exactly this.
+async fn write_settings_record_async(
+    record: &JsonRecord,
+    skip_backup_snapshot: bool,
+    expected_mtime_ms: Option<f64>,
+) -> io::Result<()> {
+    let payload = normalize_for_write(record);
+    let content = stringify_pretty2(&Value::Object(payload));
+    let options = WriteJsonOptions {
+        trailing_newline: TrailingNewline::Lf,
+        mtime_cas: Some(MtimeCas {
+            expected_mtime_ms,
+            stale_message: UNIFIED_SETTINGS_STALE_MESSAGE.to_string(),
+        }),
+        backup: if skip_backup_snapshot {
+            None
+        } else {
+            Some(BackupOptions {
+                backup_path: get_unified_settings_backup_path(),
+            })
+        },
+        fsync: false,
+        ensure_parent_dir: true,
+        parent_dir_mode: None,
+        rename_max_attempts: 5,
+    };
+    write_json_atomic(&get_unified_settings_path(), &content, None, &options).await
+}
+
+/// `getUnifiedSettingsMtimeMs` — `None` when missing; other stat errors
+/// propagate.
+fn get_unified_settings_mtime_ms() -> io::Result<Option<f64>> {
+    file_mtime_ms(&get_unified_settings_path())
+}
+
+/// The 3-attempt mtime-CAS save loop shared by both section savers.
+async fn save_section(section_key: &str, section: &JsonRecord) -> io::Result<()> {
+    let _queue = SETTINGS_WRITE_QUEUE.lock().await;
+    let mut expected_mtime_ms = get_unified_settings_mtime_ms()?;
+    let mut state = read_settings_record_internal()?;
+    for attempt in 0..3u32 {
+        let mut next_record = state.record.clone().unwrap_or_default();
+        next_record.insert(section_key.to_string(), Value::Object(section.clone()));
+        match write_settings_record_async(&next_record, state.used_backup, expected_mtime_ms).await
+        {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if code_of(&error) != Some("ESTALE") || attempt >= 2 {
+                    return Err(error);
+                }
+                expected_mtime_ms = get_unified_settings_mtime_ms()?;
+                state = read_settings_record_internal()?;
+            }
+        }
+    }
+    unreachable!("CAS loop returns within 3 attempts")
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/// `loadUnifiedPluginConfigSync` — shallow clone of the `pluginConfig`
+/// section; ANY error → `None`.
+pub fn load_unified_plugin_config_sync() -> Option<JsonRecord> {
+    let state = read_settings_record_internal().ok()?;
+    let record = state.record?;
+    match record.get("pluginConfig") {
+        Some(Value::Object(section)) => Some(section.clone()),
+        _ => None,
+    }
+}
+
+/// `saveUnifiedPluginConfigSync` — read (record ?? `{}`), replace the
+/// `pluginConfig` section, write sync (backup snapshot skipped when the read
+/// came from `.bak`).
+pub fn save_unified_plugin_config_sync(plugin_config: &JsonRecord) -> io::Result<()> {
+    let state = read_settings_record_internal()?;
+    let mut next_record = state.record.unwrap_or_default();
+    next_record.insert(
+        "pluginConfig".to_string(),
+        Value::Object(plugin_config.clone()),
+    );
+    write_settings_record_sync(&next_record, state.used_backup)
+}
+
+/// `saveUnifiedPluginConfig` — enqueued on the global write queue; 3-attempt
+/// mtime CAS with `ESTALE` re-read.
+pub async fn save_unified_plugin_config(plugin_config: &JsonRecord) -> io::Result<()> {
+    save_section("pluginConfig", plugin_config).await
+}
+
+/// `loadUnifiedDashboardSettings` — clone of the `dashboardDisplaySettings`
+/// section; errors → `None`.
+pub async fn load_unified_dashboard_settings() -> Option<JsonRecord> {
+    let state = read_settings_record_internal().ok()?;
+    let record = state.record?;
+    match record.get("dashboardDisplaySettings") {
+        Some(Value::Object(section)) => Some(section.clone()),
+        _ => None,
+    }
+}
+
+/// `saveUnifiedDashboardSettings` — same CAS loop, `dashboardDisplaySettings`
+/// section.
+pub async fn save_unified_dashboard_settings(
+    dashboard_display_settings: &JsonRecord,
+) -> io::Result<()> {
+    save_section("dashboardDisplaySettings", dashboard_display_settings).await
+}
+
+// ---------------------------------------------------------------------------
+// Test-only seam (used by tests/unified_settings_test.rs to observe the
+// usedBackup flag without widening the public surface).
+// ---------------------------------------------------------------------------
+
+#[doc(hidden)]
+pub fn __read_settings_record_for_tests() -> io::Result<(Option<JsonRecord>, bool)> {
+    read_settings_record_internal().map(|state| (state.record, state.used_backup))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn normalize_for_write_appends_version_last_for_new_records() {
+        let mut record = JsonRecord::new();
+        record.insert("pluginConfig".into(), json!({}));
+        let payload = normalize_for_write(&record);
+        let keys: Vec<&str> = payload.keys().map(String::as_str).collect();
+        assert_eq!(keys, vec!["pluginConfig", "version"]);
+        assert_eq!(payload.get("version"), Some(&json!(1)));
+    }
+
+    #[test]
+    fn normalize_for_write_keeps_existing_version_position_and_restamps_value() {
+        // Gotcha 23: spread-then-assign keeps the ORIGINAL key position.
+        let raw = r#"{"a":1,"version":99,"z":2}"#;
+        let record: JsonRecord = serde_json::from_str(raw).unwrap();
+        let payload = normalize_for_write(&record);
+        let keys: Vec<&str> = payload.keys().map(String::as_str).collect();
+        assert_eq!(keys, vec!["a", "version", "z"]);
+        assert_eq!(payload.get("version"), Some(&json!(1)));
+    }
+
+    #[test]
+    fn frozen_strings() {
+        assert_eq!(
+            INVALID_SETTINGS_RECORD_MESSAGE,
+            "Unified settings must contain a JSON object at the root."
+        );
+        assert_eq!(
+            UNIFIED_SETTINGS_STALE_MESSAGE,
+            "Unified settings changed on disk during save; retrying with latest state."
+        );
+    }
+}
diff --git a/crates/config/tests/dashboard_settings_test.rs b/crates/config/tests/dashboard_settings_test.rs
new file mode 100644
index 000000000..e12e2639a
--- /dev/null
+++ b/crates/config/tests/dashboard_settings_test.rs
@@ -0,0 +1,162 @@
+//! Integration tests for `cma_config::dashboard_settings` — ported from
+//! `test/dashboard-settings.test.ts` (IO + migration flows; the pure
+//! normalization matrix lives in the module's unit tests).
+
+use std::fs;
+
+use serde_json::{Map, Value, json};
+use serial_test::serial;
+
+use cma_config::dashboard_settings::{
+    DashboardAccentColor, DashboardDisplaySettings, DashboardThemePreset,
+    get_dashboard_settings_path, load_dashboard_display_settings, save_dashboard_display_settings,
+};
+use cma_config::unified_settings::get_unified_settings_path;
+use cma_testkit::sandbox::EnvSandbox;
+
+#[tokio::test]
+#[serial(env)]
+async fn loads_defaults_when_no_settings_files_exist() {
+    let _sandbox = EnvSandbox::new();
+    let settings = load_dashboard_display_settings().await;
+    assert_eq!(settings, DashboardDisplaySettings::default());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn dashboard_settings_path_is_the_unified_settings_file() {
+    let _sandbox = EnvSandbox::new();
+    assert_eq!(get_dashboard_settings_path(), get_unified_settings_path());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn saves_and_reloads_settings() {
+    let _sandbox = EnvSandbox::new();
+    let settings = DashboardDisplaySettings {
+        ui_theme_preset: DashboardThemePreset::Blue,
+        ui_accent_color: DashboardAccentColor::Cyan,
+        menu_quota_ttl_ms: 120_000,
+        ..Default::default()
+    };
+    save_dashboard_display_settings(&settings).await.unwrap();
+
+    let reloaded = load_dashboard_display_settings().await;
+    assert_eq!(reloaded.ui_theme_preset, DashboardThemePreset::Blue);
+    assert_eq!(reloaded.ui_accent_color, DashboardAccentColor::Cyan);
+    assert_eq!(reloaded.menu_quota_ttl_ms, 120_000);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn preserves_plugin_config_section_when_saving_dashboard_settings() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"codexMode":false},"version":1}"#,
+    )
+    .unwrap();
+    save_dashboard_display_settings(&DashboardDisplaySettings::default())
+        .await
+        .unwrap();
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(false));
+    assert!(record["dashboardDisplaySettings"].is_object());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn migrates_legacy_dashboard_settings_json_into_unified_settings() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let legacy_path = sandbox.codex_multi_auth_dir().join("dashboard-settings.json");
+    // The legacy file wraps its payload under a `settings` key.
+    let legacy_content = json!({
+        "settings": {
+            "uiThemePreset": "blue",
+            "menuQuotaTtlMs": 90_000,
+            "menuShowDetailsForUnselectedRows": true,
+        }
+    });
+    fs::write(&legacy_path, legacy_content.to_string()).unwrap();
+
+    let settings = load_dashboard_display_settings().await;
+    assert_eq!(settings.ui_theme_preset, DashboardThemePreset::Blue);
+    assert_eq!(settings.menu_quota_ttl_ms, 90_000);
+    // Layout derivation from the legacy boolean hint.
+    assert!(settings.menu_show_details_for_unselected_rows);
+
+    // Migrated into unified settings…
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["dashboardDisplaySettings"]["uiThemePreset"], json!("blue"));
+    // …and the legacy file is NOT deleted.
+    assert!(legacy_path.exists());
+
+    // Subsequent loads read the unified section (mutate it to prove it).
+    let mut section: Map<String, Value> = match record["dashboardDisplaySettings"].clone() {
+        Value::Object(map) => map,
+        _ => unreachable!(),
+    };
+    section.insert("uiAccentColor".into(), json!("yellow"));
+    cma_config::unified_settings::save_unified_dashboard_settings(&section)
+        .await
+        .unwrap();
+    let reloaded = load_dashboard_display_settings().await;
+    assert_eq!(reloaded.ui_accent_color, DashboardAccentColor::Yellow);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn falls_back_to_defaults_when_legacy_file_contains_malformed_json() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let legacy_path = sandbox.codex_multi_auth_dir().join("dashboard-settings.json");
+    fs::write(&legacy_path, "{{ nope").unwrap();
+    let settings = load_dashboard_display_settings().await;
+    assert_eq!(settings, DashboardDisplaySettings::default());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn falls_back_to_defaults_when_legacy_file_parses_to_non_record_json() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let legacy_path = sandbox.codex_multi_auth_dir().join("dashboard-settings.json");
+    fs::write(&legacy_path, "[1, 2, 3]").unwrap();
+    let settings = load_dashboard_display_settings().await;
+    assert_eq!(settings, DashboardDisplaySettings::default());
+    // No migration happened.
+    assert!(!get_unified_settings_path().exists());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn legacy_wrapper_without_settings_key_normalizes_to_defaults_and_migrates() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let legacy_path = sandbox.codex_multi_auth_dir().join("dashboard-settings.json");
+    // A record WITHOUT the `settings` wrapper: `parsed.settings` is absent →
+    // normalize(non-record) → defaults, which are then migrated.
+    fs::write(&legacy_path, r#"{"uiThemePreset":"blue"}"#).unwrap();
+    let settings = load_dashboard_display_settings().await;
+    assert_eq!(settings, DashboardDisplaySettings::default());
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert!(record["dashboardDisplaySettings"].is_object());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn save_normalizes_before_persisting() {
+    let _sandbox = EnvSandbox::new();
+    let settings = DashboardDisplaySettings {
+        menu_quota_ttl_ms: 10, // out of range → normalized up to 60_000
+        ..Default::default()
+    };
+    save_dashboard_display_settings(&settings).await.unwrap();
+    let reloaded = load_dashboard_display_settings().await;
+    assert_eq!(reloaded.menu_quota_ttl_ms, 60_000);
+}
diff --git a/crates/config/tests/explain_test.rs b/crates/config/tests/explain_test.rs
new file mode 100644
index 000000000..1684ce306
--- /dev/null
+++ b/crates/config/tests/explain_test.rs
@@ -0,0 +1,234 @@
+//! Integration tests for `cma_config::explain` — ported from
+//! `test/config-explain.test.ts` (source attribution + storageKind rows).
+
+use std::fs;
+
+use serde_json::{Value, json};
+use serial_test::serial;
+
+use cma_config::explain::{
+    ConfigExplainEntry, ConfigExplainSource, ConfigExplainStorageKind,
+    get_plugin_config_explain_report,
+};
+use cma_config::load::__reset_config_warning_cache_for_tests;
+use cma_config::unified_settings::get_unified_settings_path;
+use cma_testkit::sandbox::EnvSandbox;
+
+fn entry<'a>(entries: &'a [ConfigExplainEntry], key: &str) -> &'a ConfigExplainEntry {
+    entries
+        .iter()
+        .find(|entry| entry.key == key)
+        .unwrap_or_else(|| panic!("missing explain entry {key}"))
+}
+
+#[test]
+#[serial(env)]
+fn reports_missing_config_files_as_none_with_default_sources() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // The sandbox pins CODEX_AUTH_PID_OFFSET_ENABLED=0, which would register
+    // as an env source; drop it for a purely-default report.
+    sandbox.remove_var("CODEX_AUTH_PID_OFFSET_ENABLED");
+
+    let report = get_plugin_config_explain_report();
+    assert_eq!(report.storage_kind, ConfigExplainStorageKind::None);
+    assert_eq!(report.config_path, None);
+    assert_eq!(report.entries.len(), 54);
+    assert!(
+        report
+            .entries
+            .iter()
+            .all(|entry| entry.source == ConfigExplainSource::Default),
+        "everything defaults when nothing is stored and no env is set"
+    );
+    let codex_mode = entry(&report.entries, "codexMode");
+    assert_eq!(codex_mode.value, json!(true));
+    assert_eq!(codex_mode.default_value, json!(true));
+    assert_eq!(codex_mode.env_names, &["CODEX_MODE"]);
+}
+
+#[test]
+#[serial(env)]
+fn marks_entries_sourced_from_unified_settings_as_unified() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"codexMode":false,"toastDurationMs":9000},"version":1}"#,
+    )
+    .unwrap();
+
+    let report = get_plugin_config_explain_report();
+    assert_eq!(report.storage_kind, ConfigExplainStorageKind::Unified);
+    assert_eq!(report.config_path, Some(get_unified_settings_path()));
+
+    let codex_mode = entry(&report.entries, "codexMode");
+    assert_eq!(codex_mode.source, ConfigExplainSource::Unified);
+    assert_eq!(codex_mode.value, json!(false));
+    let toast = entry(&report.entries, "toastDurationMs");
+    assert_eq!(toast.source, ConfigExplainSource::Unified);
+    assert_eq!(toast.value, json!(9000));
+    // A key NOT present in the stored record stays "default".
+    assert_eq!(
+        entry(&report.entries, "fastSession").source,
+        ConfigExplainSource::Default
+    );
+}
+
+#[test]
+#[serial(env)]
+fn reports_env_sources_when_an_override_changes_the_effective_value() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    sandbox.set_var("CODEX_MODE", "0");
+    let report = get_plugin_config_explain_report();
+    let codex_mode = entry(&report.entries, "codexMode");
+    assert_eq!(codex_mode.source, ConfigExplainSource::Env);
+    assert_eq!(codex_mode.value, json!(false));
+}
+
+#[test]
+#[serial(env)]
+fn treats_invalid_string_env_values_as_non_env_sources() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // An invalid enum env value falls through in the getter, so disabling it
+    // changes nothing → not an env source.
+    sandbox.set_var("CODEX_TUI_COLOR_PROFILE", "chartreuse");
+    let report = get_plugin_config_explain_report();
+    let profile = entry(&report.entries, "codexTuiColorProfile");
+    assert_eq!(profile.source, ConfigExplainSource::Default);
+    assert_eq!(profile.value, json!("truecolor"));
+}
+
+#[test]
+#[serial(env)]
+fn reports_the_env_config_path_as_the_file_source_when_set() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("env-config.json");
+    fs::write(&env_file, r#"{"codexMode": false}"#).unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    // Unified ALSO exists but must be masked by the env path (config-01).
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"fastSession":true},"version":1}"#,
+    )
+    .unwrap();
+
+    let report = get_plugin_config_explain_report();
+    assert_eq!(report.storage_kind, ConfigExplainStorageKind::File);
+    assert_eq!(report.config_path, Some(env_file));
+    assert_eq!(
+        entry(&report.entries, "codexMode").source,
+        ConfigExplainSource::File
+    );
+    // fastSession only exists in unified, which was NOT consulted.
+    assert_eq!(
+        entry(&report.entries, "fastSession").source,
+        ConfigExplainSource::Default
+    );
+}
+
+#[test]
+#[serial(env)]
+fn reports_unreadable_env_config_files_consistently() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("corrupt.json");
+    fs::write(&env_file, "not json at all {{{").unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    // Healthy unified data exists, but the explain report must NOT mask the
+    // broken env path behind it (gotcha 2).
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"codexMode":false},"version":1}"#,
+    )
+    .unwrap();
+
+    let report = get_plugin_config_explain_report();
+    assert_eq!(report.storage_kind, ConfigExplainStorageKind::Unreadable);
+    assert_eq!(report.config_path, Some(env_file));
+    assert_eq!(
+        entry(&report.entries, "codexMode").source,
+        ConfigExplainSource::Default,
+        "no stored record was resolved"
+    );
+}
+
+#[test]
+#[serial(env)]
+fn attributes_alias_backed_fallback_policy_values_to_stored_config() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // Only the legacy alias key is stored; both policy rows share sourceKeys
+    // ["unsupportedCodexPolicy", "fallbackOnUnsupportedCodexModel"].
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"fallbackOnUnsupportedCodexModel":true},"version":1}"#,
+    )
+    .unwrap();
+
+    let report = get_plugin_config_explain_report();
+    // TS parity (test/config-explain.test.ts): only SOURCE is asserted. The
+    // loaded config merges DEFAULT_PLUGIN_CONFIG (which carries
+    // unsupportedCodexPolicy: "strict"), so the policy getter short-circuits
+    // on the default before consulting the legacy alias — the VALUE stays
+    // "strict" while the shared sourceKeys still attribute both rows to the
+    // stored record.
+    let policy = entry(&report.entries, "unsupportedCodexPolicy");
+    assert_eq!(policy.source, ConfigExplainSource::Unified);
+    assert_eq!(policy.value, json!("strict"));
+    let alias = entry(&report.entries, "fallbackOnUnsupportedCodexModel");
+    assert_eq!(alias.source, ConfigExplainSource::Unified);
+    assert_eq!(alias.value, json!(false));
+}
+
+#[test]
+#[serial(env)]
+fn attributes_stored_single_key_defaults_to_file_config() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // A stored value equal to the default still attributes to the store
+    // (hasOwn check, not value comparison).
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        sandbox.codex_multi_auth_dir().join("config.json"),
+        r#"{"codexMode": true}"#,
+    )
+    .unwrap();
+    let report = get_plugin_config_explain_report();
+    assert_eq!(report.storage_kind, ConfigExplainStorageKind::File);
+    assert_eq!(
+        entry(&report.entries, "codexMode").source,
+        ConfigExplainSource::File
+    );
+    assert_eq!(entry(&report.entries, "codexMode").value, json!(true));
+}
+
+#[test]
+#[serial(env)]
+fn fallback_chain_entry_has_no_env_names_and_json_safe_values() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"unsupportedCodexFallbackChain":{"gpt-5.3-codex-spark":["gpt-5.3-codex-high"]}},"version":1}"#,
+    )
+    .unwrap();
+    let report = get_plugin_config_explain_report();
+    let chain = entry(&report.entries, "unsupportedCodexFallbackChain");
+    assert!(chain.env_names.is_empty());
+    assert_eq!(chain.source, ConfigExplainSource::Unified);
+    // The VALUE is the getter output — normalized (effort suffix stripped).
+    assert_eq!(
+        chain.value,
+        json!({ "gpt-5.3-codex-spark": ["gpt-5.3-codex"] })
+    );
+    assert_eq!(chain.default_value, Value::Object(Default::default()));
+}
diff --git a/crates/config/tests/load_test.rs b/crates/config/tests/load_test.rs
new file mode 100644
index 000000000..31d06a91d
--- /dev/null
+++ b/crates/config/tests/load_test.rs
@@ -0,0 +1,205 @@
+//! Integration tests for `cma_config::load` — ported from the
+//! `loadPluginConfig` suite of `test/plugin-config.test.ts`.
+
+use std::fs;
+
+use serde_json::{Map, Value, json};
+use serial_test::serial;
+
+use cma_config::load::{__reset_config_warning_cache_for_tests, get_default_plugin_config,
+    load_plugin_config};
+use cma_config::unified_settings::get_unified_settings_path;
+use cma_core::schemas::plugin_config::{CodexTuiColorProfile, PluginConfig};
+use cma_testkit::sandbox::EnvSandbox;
+
+fn write_settings_plugin_config(sandbox: &EnvSandbox, plugin_config: Value) {
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let record = json!({ "pluginConfig": plugin_config, "version": 1 });
+    fs::write(get_unified_settings_path(), format!("{record}\n")).unwrap();
+}
+
+#[test]
+#[serial(env)]
+fn returns_default_config_when_no_file_exists() {
+    let _sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let config = load_plugin_config();
+    assert_eq!(config, PluginConfig::default_resolved());
+    assert_eq!(config, get_default_plugin_config());
+}
+
+#[test]
+#[serial(env)]
+fn loads_config_from_unified_settings_and_merges_with_defaults() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    write_settings_plugin_config(
+        &sandbox,
+        json!({ "codexMode": false, "responseContinuation": true, "toastDurationMs": 8000 }),
+    );
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+    assert_eq!(config.response_continuation, Some(true));
+    assert_eq!(config.toast_duration_ms, Some(8000.0));
+    // Unspecified fields come from the defaults.
+    assert_eq!(config.fast_session, Some(false));
+    assert_eq!(config.pid_offset_enabled, Some(true));
+}
+
+#[test]
+#[serial(env)]
+fn prefers_the_env_config_path_on_load_when_it_exists() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // Unified says one thing, the env file says another → env file wins
+    // (config-02 symmetry with save).
+    write_settings_plugin_config(&sandbox, json!({ "codexMode": true }));
+    let env_file = sandbox.root().join("env-config.json");
+    fs::write(&env_file, r#"{"codexMode": false}"#).unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+}
+
+#[test]
+#[serial(env)]
+fn falls_through_when_env_config_path_is_set_but_missing() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    write_settings_plugin_config(&sandbox, json!({ "codexMode": false }));
+    sandbox.set_var(
+        "CODEX_MULTI_AUTH_CONFIG_PATH",
+        sandbox.root().join("does-not-exist.json"),
+    );
+    // Gotcha 1: set-but-missing env path is IGNORED on load.
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+}
+
+#[test]
+#[serial(env)]
+fn falls_back_to_legacy_config_json_when_unified_is_absent() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        sandbox.codex_multi_auth_dir().join("config.json"),
+        r#"{"codexTuiColorProfile": "ansi16", "fastSession": true}"#,
+    )
+    .unwrap();
+    let config = load_plugin_config();
+    assert_eq!(
+        config.codex_tui_color_profile,
+        Some(CodexTuiColorProfile::Ansi16)
+    );
+    assert_eq!(config.fast_session, Some(true));
+}
+
+#[test]
+#[serial(env)]
+fn detects_custom_codex_home_legacy_config_before_global_legacy_path() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // Point CODEX_HOME somewhere custom so IS_CUSTOM_CODEX_HOME is true.
+    let custom_home = sandbox.root().join("custom-codex");
+    fs::create_dir_all(&custom_home).unwrap();
+    sandbox.set_var("CODEX_HOME", &custom_home);
+    fs::write(
+        custom_home.join("codex-multi-auth-config.json"),
+        r#"{"codexMode": false}"#,
+    )
+    .unwrap();
+    // Global legacy path also exists with different content — custom home wins.
+    let global_legacy_dir = sandbox.root().join(".codex");
+    fs::create_dir_all(&global_legacy_dir).unwrap();
+    fs::write(
+        global_legacy_dir.join("codex-multi-auth-config.json"),
+        r#"{"codexMode": true, "fastSession": true}"#,
+    )
+    .unwrap();
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+    assert_eq!(config.fast_session, Some(false), "global legacy not read");
+}
+
+#[test]
+#[serial(env)]
+fn parses_utf8_bom_prefixed_config_files() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("bom-config.json");
+    fs::write(&env_file, "\u{feff}{\"codexMode\": false}").unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+}
+
+#[test]
+#[serial(env)]
+fn handles_invalid_json_gracefully() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("broken.json");
+    fs::write(&env_file, "{ definitely not json").unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    let config = load_plugin_config();
+    assert_eq!(config, PluginConfig::default_resolved());
+}
+
+#[test]
+#[serial(env)]
+fn drops_invalid_persisted_values_while_keeping_valid_config_keys() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    write_settings_plugin_config(
+        &sandbox,
+        json!({
+            "codexMode": false,
+            "toastDurationMs": 500,          // below schema min → dropped
+            "codexTuiGlyphMode": "sparkles", // invalid enum → dropped
+        }),
+    );
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+    // Dropped fields resolve to the defaults after the merge.
+    assert_eq!(config.toast_duration_ms, Some(5_000.0));
+    assert_eq!(
+        config.codex_tui_glyph_mode,
+        Some(cma_core::schemas::plugin_config::CodexTuiGlyphMode::Ascii)
+    );
+}
+
+#[test]
+#[serial(env)]
+fn non_record_root_in_unified_section_falls_back_to_defaults() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig": "not-a-record", "version": 1}"#,
+    )
+    .unwrap();
+    let config = load_plugin_config();
+    assert_eq!(config, PluginConfig::default_resolved());
+}
+
+#[test]
+#[serial(env)]
+fn unknown_keys_are_stripped_on_load() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    write_settings_plugin_config(
+        &sandbox,
+        json!({ "futureFeature": { "x": 1 }, "codexMode": false }),
+    );
+    let config = load_plugin_config();
+    assert_eq!(config.codex_mode, Some(false));
+    // Round-tripping through serialization shows no unknown fields survive
+    // into the typed config.
+    let as_map: Map<String, Value> = match serde_json::to_value(&config).unwrap() {
+        Value::Object(map) => map,
+        _ => unreachable!(),
+    };
+    assert!(!as_map.contains_key("futureFeature"));
+}
diff --git a/crates/config/tests/save_test.rs b/crates/config/tests/save_test.rs
new file mode 100644
index 000000000..de2ddbe90
--- /dev/null
+++ b/crates/config/tests/save_test.rs
@@ -0,0 +1,214 @@
+//! Integration tests for `cma_config::save` — ported from the
+//! "plugin config save paths" suite of `test/config-save.test.ts`.
+
+use std::fs;
+
+use serde_json::{Map, Value, json};
+use serial_test::serial;
+
+use cma_config::load::__reset_config_warning_cache_for_tests;
+use cma_config::save::{ConfigSaveError, save_plugin_config, save_plugin_config_typed};
+use cma_config::unified_settings::get_unified_settings_path;
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_testkit::sandbox::EnvSandbox;
+
+fn patch(value: Value) -> Map<String, Value> {
+    match value {
+        Value::Object(map) => map,
+        _ => panic!("patch must be an object"),
+    }
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn merges_and_sanitizes_env_path_saves_preserving_unknown_keys() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("env-config.json");
+    fs::write(
+        &env_file,
+        r#"{"futureKey": {"keep": true}, "codexMode": true, "toastDurationMs": 5}"#,
+    )
+    .unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+
+    save_plugin_config(&patch(json!({
+        "fastSession": true,
+        "codexTuiColorProfile": "nope",  // invalid → dropped with warn-once
+    })))
+    .await
+    .expect("env-path save succeeds");
+
+    let raw = fs::read_to_string(&env_file).unwrap();
+    assert!(raw.ends_with("\n"), "trailing newline");
+    let record: Value = serde_json::from_str(&raw).unwrap();
+    // Unknown key preserved (gotcha 5); invalid stored value dropped; patch
+    // applied; invalid patch field dropped.
+    assert_eq!(record["futureKey"]["keep"], json!(true));
+    assert_eq!(record["codexMode"], json!(true));
+    assert!(record.get("toastDurationMs").is_none());
+    assert_eq!(record["fastSession"], json!(true));
+    assert!(record.get("codexTuiColorProfile").is_none());
+    // 2-space pretty formatting.
+    assert!(raw.contains("\n  \"codexMode\": true"));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn env_path_save_creates_the_file_when_missing() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("fresh").join("env-config.json");
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    save_plugin_config(&patch(json!({ "codexMode": false })))
+        .await
+        .expect("save creates parent dirs + file");
+    let record: Value = serde_json::from_str(&fs::read_to_string(&env_file).unwrap()).unwrap();
+    assert_eq!(record, json!({ "codexMode": false }));
+    // The lockfile was cleaned up.
+    assert!(!env_file.with_extension("json.lock").exists());
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn recovers_from_malformed_env_path_json_before_saving() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("malformed.json");
+    fs::write(&env_file, "{ broken json !!").unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    // Invalid (not unreadable) → rebuild from the patch (gotcha 12).
+    save_plugin_config(&patch(json!({ "fastSession": true })))
+        .await
+        .expect("invalid existing file rebuilds");
+    let record: Value = serde_json::from_str(&fs::read_to_string(&env_file).unwrap()).unwrap();
+    assert_eq!(record, json!({ "fastSession": true }));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn aborts_with_storage_error_when_the_env_path_is_unreadable() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // A DIRECTORY at the config path: exists, but reading it fails with an
+    // errno-coded error (EISDIR on unix, EPERM/EBUSY-family on Windows) →
+    // classified "unreadable" → typed StorageError abort.
+    let env_dir = sandbox.root().join("config-is-a-dir.json");
+    fs::create_dir_all(&env_dir).unwrap();
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_dir);
+
+    let error = save_plugin_config(&patch(json!({ "codexMode": false })))
+        .await
+        .expect_err("unreadable existing config aborts the save");
+    let storage = match &error {
+        ConfigSaveError::Storage(storage) => storage,
+        other => panic!("expected StorageError, got {other:?}"),
+    };
+    assert_eq!(storage.code(), "UNREADABLE");
+    assert!(storage.message().starts_with("Aborting config save because "));
+    assert!(storage.message().ends_with(" is unreadable."));
+    assert_eq!(
+        storage.hint(),
+        Some("Fix or remove the unreadable config file, then retry the save.")
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn writes_through_unified_settings_when_env_path_is_unset() {
+    let _sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    save_plugin_config(&patch(json!({ "codexMode": false, "toastDurationMs": 7000 })))
+        .await
+        .expect("unified save");
+    let raw = fs::read_to_string(get_unified_settings_path()).unwrap();
+    let record: Value = serde_json::from_str(&raw).unwrap();
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(false));
+    assert_eq!(record["pluginConfig"]["toastDurationMs"], json!(7000));
+    assert_eq!(record["version"], json!(1));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn unified_save_preserves_sibling_sections_and_merges_the_section() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        r#"{"pluginConfig":{"codexMode":true,"futureKey":1},"dashboardDisplaySettings":{"uiThemePreset":"blue"},"version":1}"#,
+    )
+    .unwrap();
+    save_plugin_config(&patch(json!({ "fastSession": true })))
+        .await
+        .unwrap();
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    // Section merged: existing values + unknown key + patch.
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(true));
+    assert_eq!(record["pluginConfig"]["futureKey"], json!(1));
+    assert_eq!(record["pluginConfig"]["fastSession"], json!(true));
+    // Sibling section untouched.
+    assert_eq!(record["dashboardDisplaySettings"]["uiThemePreset"], json!("blue"));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn first_unified_save_migrates_legacy_config_values() {
+    let sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    // Only a legacy config.json exists; the first save copies its (valid)
+    // values into settings.json merged with the patch. The legacy file is
+    // never modified.
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let legacy = sandbox.codex_multi_auth_dir().join("config.json");
+    let legacy_content = r#"{"codexMode": false, "futureKey": "kept"}"#;
+    fs::write(&legacy, legacy_content).unwrap();
+
+    save_plugin_config(&patch(json!({ "fastSession": true })))
+        .await
+        .unwrap();
+
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(false));
+    assert_eq!(record["pluginConfig"]["futureKey"], json!("kept"));
+    assert_eq!(record["pluginConfig"]["fastSession"], json!(true));
+    assert_eq!(fs::read_to_string(&legacy).unwrap(), legacy_content);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn typed_save_serializes_only_the_set_fields() {
+    let _sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let typed_patch = PluginConfig {
+        fast_session: Some(true),
+        ..PluginConfig::default()
+    };
+    save_plugin_config_typed(&typed_patch).await.unwrap();
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(
+        record["pluginConfig"],
+        json!({ "fastSession": true }),
+        "only the Some field lands in the section"
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn cleans_temp_files_after_env_path_saves() {
+    let mut sandbox = EnvSandbox::new();
+    __reset_config_warning_cache_for_tests();
+    let env_file = sandbox.root().join("env-config.json");
+    sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", &env_file);
+    save_plugin_config(&patch(json!({ "codexMode": true }))).await.unwrap();
+    let leftovers: Vec<String> = fs::read_dir(sandbox.root())
+        .unwrap()
+        .filter_map(|entry| entry.ok())
+        .map(|entry| entry.file_name().to_string_lossy().into_owned())
+        .filter(|name| name.ends_with(".tmp") || name.ends_with(".lock"))
+        .collect();
+    assert!(leftovers.is_empty(), "stray artifacts: {leftovers:?}");
+}
diff --git a/crates/config/tests/transient_read_fault_test.rs b/crates/config/tests/transient_read_fault_test.rs
new file mode 100644
index 000000000..91a7fe169
--- /dev/null
+++ b/crates/config/tests/transient_read_fault_test.rs
@@ -0,0 +1,92 @@
+//! Windows-only fault-injection coverage for the transient-read contracts
+//! that the TS suite exercised with `fs` mocks (`unified-settings.test.ts`
+//! "rethrows transient primary read errors", `dashboard-settings.test.ts`
+//! "retries transient EBUSY reads").
+//!
+//! Instead of mocking, these tests hold a real exclusive Windows file handle
+//! (`share_mode(0)`), which makes concurrent `fs::read` calls fail with
+//! `ERROR_SHARING_VIOLATION` — mapped to `"EBUSY"` by
+//! `cma_core::fs_retry::code_of` (ARCHITECTURE §8.2). No such no-mock seam
+//! exists on unix, so the file is windows-gated.
+#![cfg(windows)]
+
+use std::fs;
+use std::os::windows::fs::OpenOptionsExt;
+
+use serde_json::{Map, Value, json};
+use serial_test::serial;
+
+use cma_config::dashboard_settings::{DashboardThemePreset, load_dashboard_display_settings};
+use cma_config::unified_settings::{get_unified_settings_path, save_unified_plugin_config};
+use cma_core::fs_retry::code_of;
+use cma_testkit::sandbox::EnvSandbox;
+
+/// Opens `path` with no sharing: every other open (and thus `fs::read`) hits
+/// `ERROR_SHARING_VIOLATION` until the returned handle is dropped.
+fn hold_exclusive(path: &std::path::Path) -> fs::File {
+    fs::OpenOptions::new()
+        .read(true)
+        .share_mode(0)
+        .open(path)
+        .expect("exclusive open")
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn unified_save_rethrows_transient_primary_read_errors_without_backup_fallback() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let primary = get_unified_settings_path();
+    let original = "{\n  \"customSection\": {\n    \"keep\": true\n  },\n  \"version\": 1\n}\n";
+    fs::write(&primary, original).unwrap();
+    // A healthy backup MUST NOT be consulted for a transient primary error —
+    // that would let a writer rebuild over a merely-busy primary.
+    fs::write(
+        sandbox.codex_multi_auth_dir().join("settings.json.bak"),
+        "{\n  \"version\": 1\n}\n",
+    )
+    .unwrap();
+
+    let guard = hold_exclusive(&primary);
+    let plugin: Map<String, Value> = serde_json::from_value(json!({ "codexMode": false })).unwrap();
+    let error = save_unified_plugin_config(&plugin)
+        .await
+        .expect_err("EBUSY primary read must rethrow, not fall back");
+    assert_eq!(code_of(&error), Some("EBUSY"));
+    drop(guard);
+
+    // The busy primary was left untouched (no rebuild from backup or `{}`).
+    assert_eq!(fs::read_to_string(&primary).unwrap(), original);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn dashboard_legacy_load_retries_transient_ebusy_reads_until_the_lock_clears() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    // No unified settings.json → the legacy ladder runs.
+    let legacy_path = sandbox
+        .codex_multi_auth_dir()
+        .join("dashboard-settings.json");
+    fs::write(
+        &legacy_path,
+        "{\n  \"settings\": {\n    \"uiThemePreset\": \"blue\"\n  }\n}\n",
+    )
+    .unwrap();
+
+    // First read attempt(s) hit EBUSY; the holder releases mid-way through
+    // the 20/40/80 ms retry schedule, so a later attempt succeeds.
+    let guard = hold_exclusive(&legacy_path);
+    let release = std::thread::spawn(move || {
+        std::thread::sleep(std::time::Duration::from_millis(30));
+        drop(guard);
+    });
+
+    let settings = load_dashboard_display_settings().await;
+    release.join().unwrap();
+    assert_eq!(
+        settings.ui_theme_preset,
+        DashboardThemePreset::Blue,
+        "legacy settings must load once the transient EBUSY clears (not defaults)"
+    );
+}
diff --git a/crates/config/tests/unified_settings_test.rs b/crates/config/tests/unified_settings_test.rs
new file mode 100644
index 000000000..e9781df5c
--- /dev/null
+++ b/crates/config/tests/unified_settings_test.rs
@@ -0,0 +1,228 @@
+//! Integration tests for `cma_config::unified_settings` — ported from
+//! `test/unified-settings.test.ts` (highest-value assertions) plus the
+//! settings.json golden byte test (ARCHITECTURE.md §9.1).
+
+use std::fs;
+
+use serde_json::{Map, Value, json};
+use serial_test::serial;
+
+use cma_config::dashboard_settings::{DashboardDisplaySettings, to_json_record};
+use cma_config::unified_settings::{
+    get_unified_settings_backup_path, get_unified_settings_path, load_unified_dashboard_settings,
+    load_unified_plugin_config_sync, save_unified_dashboard_settings, save_unified_plugin_config,
+    save_unified_plugin_config_sync,
+};
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_testkit::sandbox::EnvSandbox;
+
+fn default_plugin_config_record() -> Map<String, Value> {
+    match serde_json::to_value(PluginConfig::default_resolved()) {
+        Ok(Value::Object(map)) => map,
+        _ => panic!("defaults serialize to an object"),
+    }
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn merges_plugin_and_dashboard_sections_into_one_file_byte_identical_to_golden() {
+    let _sandbox = EnvSandbox::new();
+    save_unified_plugin_config(&default_plugin_config_record())
+        .await
+        .expect("plugin save");
+    save_unified_dashboard_settings(&to_json_record(&DashboardDisplaySettings::default()))
+        .await
+        .expect("dashboard save");
+
+    let written = fs::read_to_string(get_unified_settings_path()).expect("settings written");
+    // Byte-compare against the TS-produced fixture: 2-space indent, key
+    // order (pluginConfig → version → dashboardDisplaySettings), trailing \n.
+    cma_testkit::goldens::assert_golden_str("settings.json", &written);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn preserves_unrelated_top_level_sections_during_partial_section_writes() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_path(),
+        "{\n  \"customSection\": {\n    \"keep\": true\n  },\n  \"version\": 1\n}\n",
+    )
+    .unwrap();
+
+    let plugin: Map<String, Value> =
+        serde_json::from_value(json!({ "codexMode": false })).unwrap();
+    save_unified_plugin_config(&plugin).await.unwrap();
+    let dashboard: Map<String, Value> =
+        serde_json::from_value(json!({ "uiThemePreset": "blue" })).unwrap();
+    save_unified_dashboard_settings(&dashboard).await.unwrap();
+
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["customSection"]["keep"], json!(true));
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(false));
+    assert_eq!(record["dashboardDisplaySettings"]["uiThemePreset"], json!("blue"));
+    assert_eq!(record["version"], json!(1));
+    // Existing `version` key kept its ORIGINAL position (before the newly
+    // appended sections).
+    let keys: Vec<&str> = record.as_object().unwrap().keys().map(String::as_str).collect();
+    assert_eq!(
+        keys,
+        vec!["customSection", "version", "pluginConfig", "dashboardDisplaySettings"]
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_null_sections_for_invalid_json_without_usable_backup() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(get_unified_settings_path(), "{ not json").unwrap();
+
+    assert_eq!(load_unified_plugin_config_sync(), None);
+    assert_eq!(load_unified_dashboard_settings().await, None);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_null_sections_when_settings_root_is_not_an_object() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(get_unified_settings_path(), "[1, 2, 3]\n").unwrap();
+    assert_eq!(load_unified_plugin_config_sync(), None);
+    assert_eq!(load_unified_dashboard_settings().await, None);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn recovers_sections_from_backup_when_primary_is_invalid() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(get_unified_settings_path(), "corrupted{{{").unwrap();
+    fs::write(
+        get_unified_settings_backup_path(),
+        r#"{"pluginConfig":{"codexMode":false},"dashboardDisplaySettings":{"uiThemePreset":"blue"},"version":1}"#,
+    )
+    .unwrap();
+
+    let plugin = load_unified_plugin_config_sync().expect("recovered from backup");
+    assert_eq!(plugin.get("codexMode"), Some(&json!(false)));
+    let dashboard = load_unified_dashboard_settings().await.expect("recovered");
+    assert_eq!(dashboard.get("uiThemePreset"), Some(&json!("blue")));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn does_not_load_backup_when_the_primary_file_is_missing() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(
+        get_unified_settings_backup_path(),
+        r#"{"pluginConfig":{"codexMode":false},"version":1}"#,
+    )
+    .unwrap();
+    // Missing primaries stay missing — stale backup state must not resurrect.
+    assert_eq!(load_unified_plugin_config_sync(), None);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn preserves_the_last_good_backup_when_writing_after_a_backup_derived_read() {
+    // Gotcha 10: a save whose state came from .bak SKIPS the snapshot so the
+    // corrupt primary cannot clobber the only good backup.
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    let good_backup = r#"{"pluginConfig":{"codexMode":false},"version":1}"#;
+    fs::write(get_unified_settings_path(), "corrupted{{{").unwrap();
+    fs::write(get_unified_settings_backup_path(), good_backup).unwrap();
+
+    let patch: Map<String, Value> =
+        serde_json::from_value(json!({ "fastSession": true })).unwrap();
+    save_unified_plugin_config(&patch).await.unwrap();
+
+    // The backup still holds the good pre-save content (snapshot skipped)…
+    assert_eq!(
+        fs::read_to_string(get_unified_settings_backup_path()).unwrap(),
+        good_backup
+    );
+    // …and the primary was rebuilt from the backup-derived record + patch.
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["pluginConfig"]["fastSession"], json!(true));
+
+    // A later save (healthy primary) resumes snapshotting.
+    let patch2: Map<String, Value> =
+        serde_json::from_value(json!({ "fastSession": false })).unwrap();
+    save_unified_plugin_config(&patch2).await.unwrap();
+    let backup_after: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_backup_path()).unwrap())
+            .unwrap();
+    assert_eq!(
+        backup_after["pluginConfig"]["fastSession"],
+        json!(true),
+        "second save snapshots the (now healthy) primary before writing"
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn supports_sync_plugin_config_save_and_load() {
+    let _sandbox = EnvSandbox::new();
+    let plugin: Map<String, Value> =
+        serde_json::from_value(json!({ "codexMode": true, "toastDurationMs": 6000 })).unwrap();
+    save_unified_plugin_config_sync(&plugin).unwrap();
+    let loaded = load_unified_plugin_config_sync().expect("section present");
+    assert_eq!(loaded.get("codexMode"), Some(&json!(true)));
+    assert_eq!(loaded.get("toastDurationMs"), Some(&json!(6000)));
+    // Sync writer also appends the trailing newline + version.
+    let raw = fs::read_to_string(get_unified_settings_path()).unwrap();
+    assert!(raw.ends_with("\n"));
+    let record: Value = serde_json::from_str(&raw).unwrap();
+    assert_eq!(record["version"], json!(1));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_null_for_missing_plugin_config_section() {
+    let sandbox = EnvSandbox::new();
+    fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+    fs::write(get_unified_settings_path(), r#"{"version":1}"#).unwrap();
+    assert_eq!(load_unified_plugin_config_sync(), None);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn serializes_concurrent_section_writes_and_keeps_both_sections() {
+    let _sandbox = EnvSandbox::new();
+    let plugin: Map<String, Value> =
+        serde_json::from_value(json!({ "codexMode": false })).unwrap();
+    let dashboard: Map<String, Value> =
+        serde_json::from_value(json!({ "uiAccentColor": "cyan" })).unwrap();
+    let (a, b) = tokio::join!(
+        save_unified_plugin_config(&plugin),
+        save_unified_dashboard_settings(&dashboard)
+    );
+    a.unwrap();
+    b.unwrap();
+    let record: Value =
+        serde_json::from_str(&fs::read_to_string(get_unified_settings_path()).unwrap()).unwrap();
+    assert_eq!(record["pluginConfig"]["codexMode"], json!(false));
+    assert_eq!(record["dashboardDisplaySettings"]["uiAccentColor"], json!("cyan"));
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn no_temp_files_left_behind_after_saves() {
+    let sandbox = EnvSandbox::new();
+    let plugin: Map<String, Value> = serde_json::from_value(json!({ "codexMode": true })).unwrap();
+    save_unified_plugin_config(&plugin).await.unwrap();
+    save_unified_plugin_config_sync(&plugin).unwrap();
+    let leftovers: Vec<String> = fs::read_dir(sandbox.codex_multi_auth_dir())
+        .unwrap()
+        .filter_map(|entry| entry.ok())
+        .map(|entry| entry.file_name().to_string_lossy().into_owned())
+        .filter(|name| name.ends_with(".tmp"))
+        .collect();
+    assert!(leftovers.is_empty(), "stray temp files: {leftovers:?}");
+}
diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml
new file mode 100644
index 000000000..61a758893
--- /dev/null
+++ b/crates/core/Cargo.toml
@@ -0,0 +1,34 @@
+[package]
+name = "cma-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+sha2.workspace = true
+rand.workspace = true
+uuid.workspace = true
+base64.workspace = true
+regex.workspace = true
+chrono.workspace = true
+home.workspace = true
+unicode-segmentation.workspace = true
+tokio.workspace = true
+futures.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/core/src/clock.rs b/crates/core/src/clock.rs
new file mode 100644
index 000000000..7de755cf9
--- /dev/null
+++ b/crates/core/src/clock.rs
@@ -0,0 +1,108 @@
+//! Injectable clock seam (new in the Rust port; ARCHITECTURE §6.1 / §8.5).
+//!
+//! `now_ms()` here and everywhere = WALL clock, exactly where the TS used
+//! `Date.now()` (cooldowns, rate-limit windows, persistence timestamps).
+//! `std::time::Instant` is allowed only for `performance.now()` analogues
+//! (logger timers) — never for anything persisted or compared to epoch ms.
+//!
+//! The [`Clock`] trait exists ONLY where specs demand an injectable `now`
+//! (forecast, preemptive scheduler, rotation trackers). Spec 10 gotcha:
+//! `apply_monotonic_auth_cooldown` compares REAL wall-clock values — injected
+//! test clocks must never leak into those comparisons; call sites there use
+//! [`SystemClock`] / [`now_ms`] directly, not an injected `&dyn Clock`.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicI64, Ordering};
+
+/// Wall-clock time source, in milliseconds since the Unix epoch.
+pub trait Clock: Send + Sync {
+    /// Current wall-clock time in epoch milliseconds.
+    fn now_ms(&self) -> i64;
+}
+
+/// The real wall clock (`Date.now()` equivalent).
+#[derive(Debug, Clone, Copy, Default)]
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_ms(&self) -> i64 {
+        crate::utils::now_ms()
+    }
+}
+
+/// Current wall-clock time in epoch milliseconds (free-function convenience;
+/// identical to [`crate::utils::now_ms`]).
+pub fn now_ms() -> i64 {
+    crate::utils::now_ms()
+}
+
+/// Shared handle to the real wall clock, for call sites that take
+/// `Arc<dyn Clock>`.
+pub fn system_clock() -> Arc<dyn Clock> {
+    Arc::new(SystemClock)
+}
+
+/// Manually-driven clock for tests (the Rust analogue of the TS fake-timer
+/// seams). Thread-safe; can be shared across tasks via `Arc`.
+#[derive(Debug, Default)]
+pub struct ManualClock {
+    now: AtomicI64,
+}
+
+impl ManualClock {
+    /// Creates a manual clock pinned at `start_ms`.
+    pub fn new(start_ms: i64) -> Self {
+        ManualClock {
+            now: AtomicI64::new(start_ms),
+        }
+    }
+
+    /// Pins the clock to an absolute epoch-ms value.
+    pub fn set(&self, now_ms: i64) {
+        self.now.store(now_ms, Ordering::SeqCst);
+    }
+
+    /// Advances the clock by `delta_ms` (may be negative).
+    pub fn advance(&self, delta_ms: i64) {
+        self.now.fetch_add(delta_ms, Ordering::SeqCst);
+    }
+}
+
+impl Clock for ManualClock {
+    fn now_ms(&self) -> i64 {
+        self.now.load(Ordering::SeqCst)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn system_clock_tracks_wall_clock() {
+        let clock = SystemClock;
+        let before = crate::utils::now_ms();
+        let sampled = clock.now_ms();
+        let after = crate::utils::now_ms();
+        assert!(before <= sampled && sampled <= after);
+        assert!(now_ms() >= before);
+    }
+
+    #[test]
+    fn system_clock_arc_is_usable_as_dyn_clock() {
+        let clock = system_clock();
+        assert!(clock.now_ms() > 1_577_836_800_000);
+    }
+
+    #[test]
+    fn manual_clock_set_and_advance() {
+        let clock = ManualClock::new(1_000);
+        assert_eq!(clock.now_ms(), 1_000);
+        clock.advance(500);
+        assert_eq!(clock.now_ms(), 1_500);
+        clock.advance(-250);
+        assert_eq!(clock.now_ms(), 1_250);
+        clock.set(42);
+        assert_eq!(clock.now_ms(), 42);
+    }
+}
diff --git a/crates/core/src/constants.rs b/crates/core/src/constants.rs
new file mode 100644
index 000000000..6248365a4
--- /dev/null
+++ b/crates/core/src/constants.rs
@@ -0,0 +1,529 @@
+//! Port of `lib/constants.ts` + `lib/runtime-constants.ts`.
+//!
+//! Pure constants used throughout the plugin. All user-visible strings are
+//! FROZEN — they must match the TypeScript source byte-for-byte (spec 01 §2.1,
+//! spec 14 §8).
+
+use serde::{Deserialize, Serialize};
+
+/// Plugin identifier for logging and error messages.
+pub const PLUGIN_NAME: &str = "codex-multi-auth";
+
+/// Base URL for ChatGPT backend API.
+pub const CODEX_BASE_URL: &str = "https://chatgpt.com/backend-api";
+
+/// Dummy API key used for the OpenAI SDK (actual auth via OAuth).
+pub const DUMMY_API_KEY: &str = "chatgpt-oauth";
+
+/// Provider ID for UI display — shows under "OpenAI" in the auth dropdown.
+pub const PROVIDER_ID: &str = "openai";
+
+/// Upper bound for any rate-limit / retry-after window we will honor. A single
+/// hostile or buggy upstream value (seconds-vs-ms confusion, anti-abuse
+/// misfire) must never be able to wedge an account unavailable for longer than
+/// this. `7 * 24 * 60 * 60 * 1000`.
+pub const MAX_RATE_LIMIT_DELAY_MS: i64 = 7 * 24 * 60 * 60 * 1000;
+
+/// HTTP status codes (TS `HTTP_STATUS`). Field names are the snake_case forms
+/// of the original SCREAMING_SNAKE keys.
+#[derive(Debug, Clone, Copy)]
+pub struct HttpStatus {
+    pub bad_request: u16,
+    pub ok: u16,
+    pub payload_too_large: u16,
+    pub forbidden: u16,
+    pub unauthorized: u16,
+    pub not_found: u16,
+    pub too_many_requests: u16,
+    pub bad_gateway: u16,
+    pub service_unavailable: u16,
+}
+
+/// HTTP Status Codes.
+pub const HTTP_STATUS: HttpStatus = HttpStatus {
+    bad_request: 400,
+    ok: 200,
+    payload_too_large: 413,
+    forbidden: 403,
+    unauthorized: 401,
+    not_found: 404,
+    too_many_requests: 429,
+    bad_gateway: 502,
+    service_unavailable: 503,
+};
+
+/// OpenAI-specific header NAMES (TS `OPENAI_HEADERS`).
+#[derive(Debug, Clone, Copy)]
+pub struct OpenAiHeaders {
+    /// `BETA`
+    pub beta: &'static str,
+    /// `ACCOUNT_ID`
+    pub account_id: &'static str,
+    /// `ORIGINATOR`
+    pub originator: &'static str,
+    /// `SESSION_ID`
+    pub session_id: &'static str,
+    /// `CONVERSATION_ID`
+    pub conversation_id: &'static str,
+}
+
+/// OpenAI-specific headers (exact header names).
+pub const OPENAI_HEADERS: OpenAiHeaders = OpenAiHeaders {
+    beta: "OpenAI-Beta",
+    account_id: "chatgpt-account-id",
+    originator: "originator",
+    session_id: "session_id",
+    conversation_id: "conversation_id",
+};
+
+/// OpenAI-specific header VALUES (TS `OPENAI_HEADER_VALUES`).
+#[derive(Debug, Clone, Copy)]
+pub struct OpenAiHeaderValues {
+    /// `BETA_RESPONSES`
+    pub beta_responses: &'static str,
+    /// `ORIGINATOR_CODEX`
+    pub originator_codex: &'static str,
+}
+
+/// OpenAI-specific header values.
+pub const OPENAI_HEADER_VALUES: OpenAiHeaderValues = OpenAiHeaderValues {
+    beta_responses: "responses=experimental",
+    originator_codex: "codex_cli_rs",
+};
+
+/// URL path segments (TS `URL_PATHS`).
+#[derive(Debug, Clone, Copy)]
+pub struct UrlPaths {
+    /// `MODELS`
+    pub models: &'static str,
+    /// `RESPONSES`
+    pub responses: &'static str,
+    /// `CODEX_RESPONSES`
+    pub codex_responses: &'static str,
+}
+
+/// URL path segments.
+pub const URL_PATHS: UrlPaths = UrlPaths {
+    models: "/models",
+    responses: "/responses",
+    codex_responses: "/codex/responses",
+};
+
+/// JWT claim path for ChatGPT account ID.
+pub const JWT_CLAIM_PATH: &str = "https://api.openai.com/auth";
+
+/// User-visible error message strings (TS `ERROR_MESSAGES`). FROZEN.
+#[derive(Debug, Clone, Copy)]
+pub struct ErrorMessages {
+    /// `NO_ACCOUNT_ID`
+    pub no_account_id: &'static str,
+    /// `TOKEN_REFRESH_FAILED`
+    pub token_refresh_failed: &'static str,
+    /// `REQUEST_PARSE_ERROR`
+    pub request_parse_error: &'static str,
+}
+
+/// Error messages.
+pub const ERROR_MESSAGES: ErrorMessages = ErrorMessages {
+    no_account_id: "Failed to extract accountId from token",
+    token_refresh_failed: "Failed to refresh token, authentication required",
+    request_parse_error: "Error parsing request",
+};
+
+/// Log stages for request logging (file-name components; TS `LOG_STAGES`).
+#[derive(Debug, Clone, Copy)]
+pub struct LogStages {
+    /// `BEFORE_TRANSFORM`
+    pub before_transform: &'static str,
+    /// `AFTER_TRANSFORM`
+    pub after_transform: &'static str,
+    /// `RESPONSE`
+    pub response: &'static str,
+    /// `ERROR_RESPONSE`
+    pub error_response: &'static str,
+}
+
+/// Log stages for request logging.
+pub const LOG_STAGES: LogStages = LogStages {
+    before_transform: "before-transform",
+    after_transform: "after-transform",
+    response: "response",
+    error_response: "error-response",
+};
+
+/// Platform-specific browser opener commands (TS `PLATFORM_OPENERS`).
+#[derive(Debug, Clone, Copy)]
+pub struct PlatformOpeners {
+    pub darwin: &'static str,
+    pub win32: &'static str,
+    pub linux: &'static str,
+}
+
+/// Platform-specific browser opener commands.
+pub const PLATFORM_OPENERS: PlatformOpeners = PlatformOpeners {
+    darwin: "open",
+    win32: "start",
+    linux: "xdg-open",
+};
+
+/// OAuth authorization labels (TS `AUTH_LABELS`). FROZEN user-visible copy.
+#[derive(Debug, Clone, Copy)]
+pub struct AuthLabels {
+    /// `OAUTH`
+    pub oauth: &'static str,
+    /// `OAUTH_MANUAL`
+    pub oauth_manual: &'static str,
+    /// `API_KEY`
+    pub api_key: &'static str,
+    /// `INSTRUCTIONS`
+    pub instructions: &'static str,
+    /// `INSTRUCTIONS_MANUAL`
+    pub instructions_manual: &'static str,
+}
+
+/// OAuth authorization labels.
+pub const AUTH_LABELS: AuthLabels = AuthLabels {
+    oauth: "ChatGPT Plus/Pro MULTI (Codex Subscription)",
+    oauth_manual: "ChatGPT Plus/Pro MULTI (Manual URL Paste)",
+    api_key: "Manually enter API Key MULTI",
+    instructions:
+        "A browser window should open. If it doesn't, copy the URL and open it manually.",
+    instructions_manual: "After logging in, copy the full redirect URL and paste it here.",
+};
+
+/// Multi-account configuration (TS `ACCOUNT_LIMITS`).
+#[derive(Debug, Clone, Copy)]
+pub struct AccountLimits {
+    /// Maximum number of OAuth accounts that can be registered (`MAX_ACCOUNTS`).
+    pub max_accounts: usize,
+    /// Cooldown period (ms) after auth failure before retrying account
+    /// (`AUTH_FAILURE_COOLDOWN_MS`).
+    pub auth_failure_cooldown_ms: i64,
+    /// Number of consecutive auth failures before auto-removing account
+    /// (`MAX_AUTH_FAILURES_BEFORE_REMOVAL`).
+    pub max_auth_failures_before_removal: u32,
+}
+
+/// Multi-account configuration.
+pub const ACCOUNT_LIMITS: AccountLimits = AccountLimits {
+    max_accounts: 20,
+    auth_failure_cooldown_ms: 30_000,
+    max_auth_failures_before_removal: 3,
+};
+
+/// Every reasoning-effort level, weakest first.
+///
+/// Single source of truth: the effort union and the model-id suffix pattern in
+/// the request transformer are both derived from this, so a new tier cannot be
+/// added to one and forgotten in the other.
+///
+/// `max` and `ultra` arrived with GPT-5.6.
+///
+/// `ultra` is selectable but never reaches the wire: Codex rewrites it to
+/// `max` before the request is sent. It denotes automatic subagent delegation
+/// on the client, not a distinct backend effort level.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ModelReasoningEffort {
+    None,
+    Minimal,
+    Low,
+    Medium,
+    High,
+    Xhigh,
+    Max,
+    Ultra,
+}
+
+/// All reasoning-effort levels, weakest first (TS `REASONING_EFFORTS`).
+/// Order matters: tier comparisons elsewhere rely on it.
+pub const REASONING_EFFORTS: [ModelReasoningEffort; 8] = [
+    ModelReasoningEffort::None,
+    ModelReasoningEffort::Minimal,
+    ModelReasoningEffort::Low,
+    ModelReasoningEffort::Medium,
+    ModelReasoningEffort::High,
+    ModelReasoningEffort::Xhigh,
+    ModelReasoningEffort::Max,
+    ModelReasoningEffort::Ultra,
+];
+
+impl ModelReasoningEffort {
+    /// The wire string for this effort level (exactly the TS literal).
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ModelReasoningEffort::None => "none",
+            ModelReasoningEffort::Minimal => "minimal",
+            ModelReasoningEffort::Low => "low",
+            ModelReasoningEffort::Medium => "medium",
+            ModelReasoningEffort::High => "high",
+            ModelReasoningEffort::Xhigh => "xhigh",
+            ModelReasoningEffort::Max => "max",
+            ModelReasoningEffort::Ultra => "ultra",
+        }
+    }
+
+    /// Exact-match parse of an effort literal (callers trim/lowercase first
+    /// where the TS did).
+    pub fn parse(value: &str) -> Option<Self> {
+        REASONING_EFFORTS
+            .iter()
+            .copied()
+            .find(|effort| effort.as_str() == value)
+    }
+
+    /// 0-based tier index, weakest first (position in [`REASONING_EFFORTS`]).
+    pub const fn tier(self) -> usize {
+        self as usize
+    }
+
+    /// The effort level actually sent to the Responses API. `ultra` never hits
+    /// the wire: it always resolves to `max` before the request is built.
+    pub const fn to_wire(self) -> WireReasoningEffort {
+        match self {
+            ModelReasoningEffort::None => WireReasoningEffort::None,
+            ModelReasoningEffort::Minimal => WireReasoningEffort::Minimal,
+            ModelReasoningEffort::Low => WireReasoningEffort::Low,
+            ModelReasoningEffort::Medium => WireReasoningEffort::Medium,
+            ModelReasoningEffort::High => WireReasoningEffort::High,
+            ModelReasoningEffort::Xhigh => WireReasoningEffort::Xhigh,
+            ModelReasoningEffort::Max | ModelReasoningEffort::Ultra => WireReasoningEffort::Max,
+        }
+    }
+}
+
+impl std::fmt::Display for ModelReasoningEffort {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Effort levels the Responses API actually accepts
+/// (TS `WireReasoningEffort = Exclude<ModelReasoningEffort, "ultra">`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum WireReasoningEffort {
+    None,
+    Minimal,
+    Low,
+    Medium,
+    High,
+    Xhigh,
+    Max,
+}
+
+impl WireReasoningEffort {
+    /// The wire string for this effort level.
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            WireReasoningEffort::None => "none",
+            WireReasoningEffort::Minimal => "minimal",
+            WireReasoningEffort::Low => "low",
+            WireReasoningEffort::Medium => "medium",
+            WireReasoningEffort::High => "high",
+            WireReasoningEffort::Xhigh => "xhigh",
+            WireReasoningEffort::Max => "max",
+        }
+    }
+
+    /// Exact-match parse of a wire-effort literal (`"ultra"` is rejected — it
+    /// is not a wire tier).
+    pub fn parse(value: &str) -> Option<Self> {
+        ModelReasoningEffort::parse(value).and_then(|effort| match effort {
+            ModelReasoningEffort::Ultra => None,
+            other => Some(other.to_wire()),
+        })
+    }
+}
+
+impl From<WireReasoningEffort> for ModelReasoningEffort {
+    fn from(value: WireReasoningEffort) -> Self {
+        match value {
+            WireReasoningEffort::None => ModelReasoningEffort::None,
+            WireReasoningEffort::Minimal => ModelReasoningEffort::Minimal,
+            WireReasoningEffort::Low => ModelReasoningEffort::Low,
+            WireReasoningEffort::Medium => ModelReasoningEffort::Medium,
+            WireReasoningEffort::High => ModelReasoningEffort::High,
+            WireReasoningEffort::Xhigh => ModelReasoningEffort::Xhigh,
+            WireReasoningEffort::Max => ModelReasoningEffort::Max,
+        }
+    }
+}
+
+impl std::fmt::Display for WireReasoningEffort {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+// --- lib/runtime-constants.ts ---
+
+/// Provider id of the runtime rotation proxy
+/// (TS `RUNTIME_ROTATION_PROXY_PROVIDER_ID`).
+pub const RUNTIME_ROTATION_PROXY_PROVIDER_ID: &str = "codex-multi-auth-runtime-proxy";
+
+/// Status filename written by the app runtime helper
+/// (TS `APP_RUNTIME_HELPER_STATUS_FILE`).
+pub const APP_RUNTIME_HELPER_STATUS_FILE: &str = "runtime-rotation-app-helper.json";
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn plugin_identity_constants_are_frozen() {
+        assert_eq!(PLUGIN_NAME, "codex-multi-auth");
+        assert_eq!(CODEX_BASE_URL, "https://chatgpt.com/backend-api");
+        assert_eq!(DUMMY_API_KEY, "chatgpt-oauth");
+        assert_eq!(PROVIDER_ID, "openai");
+        assert_eq!(JWT_CLAIM_PATH, "https://api.openai.com/auth");
+    }
+
+    #[test]
+    fn max_rate_limit_delay_is_seven_days() {
+        assert_eq!(MAX_RATE_LIMIT_DELAY_MS, 604_800_000);
+    }
+
+    #[test]
+    fn http_status_values_match_ts() {
+        assert_eq!(HTTP_STATUS.bad_request, 400);
+        assert_eq!(HTTP_STATUS.ok, 200);
+        assert_eq!(HTTP_STATUS.payload_too_large, 413);
+        assert_eq!(HTTP_STATUS.forbidden, 403);
+        assert_eq!(HTTP_STATUS.unauthorized, 401);
+        assert_eq!(HTTP_STATUS.not_found, 404);
+        assert_eq!(HTTP_STATUS.too_many_requests, 429);
+        assert_eq!(HTTP_STATUS.bad_gateway, 502);
+        assert_eq!(HTTP_STATUS.service_unavailable, 503);
+    }
+
+    #[test]
+    fn openai_headers_are_exact() {
+        assert_eq!(OPENAI_HEADERS.beta, "OpenAI-Beta");
+        assert_eq!(OPENAI_HEADERS.account_id, "chatgpt-account-id");
+        assert_eq!(OPENAI_HEADERS.originator, "originator");
+        assert_eq!(OPENAI_HEADERS.session_id, "session_id");
+        assert_eq!(OPENAI_HEADERS.conversation_id, "conversation_id");
+        assert_eq!(OPENAI_HEADER_VALUES.beta_responses, "responses=experimental");
+        assert_eq!(OPENAI_HEADER_VALUES.originator_codex, "codex_cli_rs");
+    }
+
+    #[test]
+    fn url_paths_match_ts() {
+        assert_eq!(URL_PATHS.models, "/models");
+        assert_eq!(URL_PATHS.responses, "/responses");
+        assert_eq!(URL_PATHS.codex_responses, "/codex/responses");
+    }
+
+    #[test]
+    fn error_messages_are_frozen() {
+        assert_eq!(
+            ERROR_MESSAGES.no_account_id,
+            "Failed to extract accountId from token"
+        );
+        assert_eq!(
+            ERROR_MESSAGES.token_refresh_failed,
+            "Failed to refresh token, authentication required"
+        );
+        assert_eq!(ERROR_MESSAGES.request_parse_error, "Error parsing request");
+    }
+
+    #[test]
+    fn log_stages_match_ts() {
+        assert_eq!(LOG_STAGES.before_transform, "before-transform");
+        assert_eq!(LOG_STAGES.after_transform, "after-transform");
+        assert_eq!(LOG_STAGES.response, "response");
+        assert_eq!(LOG_STAGES.error_response, "error-response");
+    }
+
+    #[test]
+    fn platform_openers_match_ts() {
+        assert_eq!(PLATFORM_OPENERS.darwin, "open");
+        assert_eq!(PLATFORM_OPENERS.win32, "start");
+        assert_eq!(PLATFORM_OPENERS.linux, "xdg-open");
+    }
+
+    #[test]
+    fn auth_labels_are_frozen() {
+        assert_eq!(
+            AUTH_LABELS.oauth,
+            "ChatGPT Plus/Pro MULTI (Codex Subscription)"
+        );
+        assert_eq!(
+            AUTH_LABELS.oauth_manual,
+            "ChatGPT Plus/Pro MULTI (Manual URL Paste)"
+        );
+        assert_eq!(AUTH_LABELS.api_key, "Manually enter API Key MULTI");
+        assert_eq!(
+            AUTH_LABELS.instructions,
+            "A browser window should open. If it doesn't, copy the URL and open it manually."
+        );
+        assert_eq!(
+            AUTH_LABELS.instructions_manual,
+            "After logging in, copy the full redirect URL and paste it here."
+        );
+    }
+
+    #[test]
+    fn account_limits_match_ts() {
+        assert_eq!(ACCOUNT_LIMITS.max_accounts, 20);
+        assert_eq!(ACCOUNT_LIMITS.auth_failure_cooldown_ms, 30_000);
+        assert_eq!(ACCOUNT_LIMITS.max_auth_failures_before_removal, 3);
+    }
+
+    #[test]
+    fn reasoning_efforts_ordered_weakest_first() {
+        let as_strings: Vec<&str> = REASONING_EFFORTS.iter().map(|e| e.as_str()).collect();
+        assert_eq!(
+            as_strings,
+            vec!["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]
+        );
+        // Tier comparisons rely on declaration order.
+        assert!(ModelReasoningEffort::None < ModelReasoningEffort::Ultra);
+        assert!(ModelReasoningEffort::Medium < ModelReasoningEffort::High);
+        assert_eq!(ModelReasoningEffort::Xhigh.tier(), 5);
+    }
+
+    #[test]
+    fn reasoning_effort_serde_uses_lowercase_literals() {
+        assert_eq!(
+            serde_json::to_string(&ModelReasoningEffort::Xhigh).unwrap(),
+            "\"xhigh\""
+        );
+        assert_eq!(
+            serde_json::from_str::<ModelReasoningEffort>("\"ultra\"").unwrap(),
+            ModelReasoningEffort::Ultra
+        );
+        assert_eq!(
+            serde_json::to_string(&WireReasoningEffort::Max).unwrap(),
+            "\"max\""
+        );
+        assert!(serde_json::from_str::<WireReasoningEffort>("\"ultra\"").is_err());
+    }
+
+    #[test]
+    fn ultra_resolves_to_max_on_the_wire() {
+        assert_eq!(
+            ModelReasoningEffort::Ultra.to_wire(),
+            WireReasoningEffort::Max
+        );
+        assert_eq!(ModelReasoningEffort::Max.to_wire(), WireReasoningEffort::Max);
+        assert_eq!(WireReasoningEffort::parse("ultra"), None);
+        assert_eq!(
+            WireReasoningEffort::parse("xhigh"),
+            Some(WireReasoningEffort::Xhigh)
+        );
+    }
+
+    #[test]
+    fn runtime_constants_match_ts() {
+        assert_eq!(
+            RUNTIME_ROTATION_PROXY_PROVIDER_ID,
+            "codex-multi-auth-runtime-proxy"
+        );
+        assert_eq!(
+            APP_RUNTIME_HELPER_STATUS_FILE,
+            "runtime-rotation-app-helper.json"
+        );
+    }
+}
diff --git a/crates/core/src/display_width.rs b/crates/core/src/display_width.rs
new file mode 100644
index 000000000..2c54b89ea
--- /dev/null
+++ b/crates/core/src/display_width.rs
@@ -0,0 +1,382 @@
+//! Port of `lib/ui/display-width.ts` (ui-02): terminal display-column math.
+//!
+//! Terminal alignment must count *display columns*, not UTF-16 units or bytes.
+//! This is a focused, dependency-free implementation covering the common cases:
+//! wide East-Asian ranges, zero-width combining marks across Latin/Cyrillic/
+//! Hebrew/Arabic/Syriac/Thai/Lao scripts, variation selectors, and grapheme
+//! clustering for ZWJ emoji sequences, emoji skin-tone modifiers, and
+//! regional-indicator flag pairs. It is not a full ICU east-asian-width table.
+//!
+//! IMPORTANT: the width TABLES and the bespoke cluster algorithm are ported
+//! VERBATIM from the TS source. Do NOT substitute the `unicode-width` crate's
+//! tables or UAX#29 segmentation — either would shift every table column and
+//! menu row rendered by the CLI (ARCHITECTURE §5.3 / spec 12 §2).
+
+/// Zero-width: combining marks, joiners, variation selectors across scripts.
+fn is_zero_width_code_point(cp: u32) -> bool {
+    cp == 0x200b // zero-width space
+        || cp == 0x200c // zero-width non-joiner
+        || cp == 0x200d // zero-width joiner
+        || cp == 0xfeff // zero-width no-break space (BOM)
+        || (0x0300..=0x036f).contains(&cp) // combining diacritical marks
+        || (0x0483..=0x0489).contains(&cp) // Cyrillic combining
+        || (0x0591..=0x05bd).contains(&cp) // Hebrew points
+        || cp == 0x05bf
+        || cp == 0x05c1
+        || cp == 0x05c2
+        || cp == 0x05c4
+        || cp == 0x05c5
+        || cp == 0x05c7
+        || (0x0610..=0x061a).contains(&cp) // Arabic
+        || (0x064b..=0x065f).contains(&cp)
+        || cp == 0x0670
+        || (0x06d6..=0x06dc).contains(&cp)
+        || (0x06df..=0x06e4).contains(&cp)
+        || (0x06e7..=0x06e8).contains(&cp)
+        || (0x06ea..=0x06ed).contains(&cp)
+        || cp == 0x0711 // Syriac
+        || (0x0730..=0x074a).contains(&cp)
+        || cp == 0x0e31 // Thai
+        || (0x0e34..=0x0e3a).contains(&cp)
+        || (0x0e47..=0x0e4e).contains(&cp)
+        || (0x0eb1..=0x0ebc).contains(&cp) // Lao (subset)
+        || (0x1ab0..=0x1aff).contains(&cp) // combining diacritical marks extended
+        || (0x1dc0..=0x1dff).contains(&cp) // combining diacritical marks supplement
+        || (0x20d0..=0x20ff).contains(&cp) // combining marks for symbols
+        || (0xfe00..=0xfe0f).contains(&cp) // variation selectors
+        || (0xfe20..=0xfe2f).contains(&cp) // combining half marks
+        || (0xe0100..=0xe01ef).contains(&cp) // variation selectors supplement
+}
+
+/// Emoji skin-tone modifiers attach to the preceding base emoji (zero added width).
+fn is_emoji_modifier(cp: u32) -> bool {
+    (0x1f3fb..=0x1f3ff).contains(&cp)
+}
+
+/// Regional indicator symbols (U+1F1E6–U+1F1FF) pair into a single 2-wide flag.
+fn is_regional_indicator(cp: u32) -> bool {
+    (0x1f1e6..=0x1f1ff).contains(&cp)
+}
+
+/// Emoji / pictographic code points that participate in ZWJ sequences. This is
+/// deliberately the emoji blocks only (NOT every 2-wide code point): a ZWJ
+/// between wide CJK text (e.g. 漢‍字) must NOT collapse — those are two
+/// separate 2-wide glyphs, so gating on emoji-ness keeps that width at 4.
+fn is_emoji_base(cp: u32) -> bool {
+    (0x1f300..=0x1faff).contains(&cp) // misc pictographs, emoji, symbols & pictographs ext
+        || (0x2600..=0x27bf).contains(&cp) // misc symbols + dingbats
+        || (0x1f000..=0x1f0ff).contains(&cp) // mahjong/domino/playing cards
+        || cp == 0x2764 // heavy black heart (common ZWJ component)
+}
+
+/// Returns the number of terminal columns a single code point occupies (0, 1, or 2).
+fn code_point_width(cp: u32) -> usize {
+    if is_zero_width_code_point(cp) {
+        return 0;
+    }
+    // Wide (2-column) ranges: the common CJK + fullwidth + emoji blocks.
+    if (0x1100..=0x115f).contains(&cp) // Hangul Jamo
+        || (0x2e80..=0x303e).contains(&cp) // CJK radicals, Kangxi
+        || (0x3041..=0x33ff).contains(&cp) // Hiragana, Katakana, CJK symbols
+        || (0x3400..=0x4dbf).contains(&cp) // CJK Ext A
+        || (0x4e00..=0x9fff).contains(&cp) // CJK Unified Ideographs
+        || (0xa000..=0xa4cf).contains(&cp) // Yi
+        || (0xac00..=0xd7a3).contains(&cp) // Hangul syllables
+        || (0xf900..=0xfaff).contains(&cp) // CJK compatibility ideographs
+        || (0xfe30..=0xfe4f).contains(&cp) // CJK compatibility forms
+        || (0xff00..=0xff60).contains(&cp) // Fullwidth forms
+        || (0xffe0..=0xffe6).contains(&cp) // Fullwidth signs
+        || (0x1f300..=0x1faff).contains(&cp) // emoji & pictographs
+        || (0x20000..=0x3fffd).contains(&cp)
+    // CJK Ext B+
+    {
+        return 2;
+    }
+    1
+}
+
+/// Advance through a grapheme cluster starting at code-point index `i` in `cps`,
+/// returning `(cluster_width, next_index)`. This collapses the three cluster
+/// shapes that a naive per-code-point sum overcounts:
+///   - ZWJ sequences (e.g. 👨‍👩‍👧): the whole join is one 2-wide glyph.
+///   - emoji + skin-tone modifier / variation selector: the modifier adds 0.
+///   - regional-indicator pairs (flags): two RIs render as one 2-wide glyph.
+fn cluster_width_at(cps: &[u32], i: usize) -> (usize, usize) {
+    let Some(&cp) = cps.get(i) else {
+        return (0, i + 1);
+    };
+
+    // Regional-indicator flag: consume a pair as a single width-2 glyph.
+    if is_regional_indicator(cp) {
+        if let Some(&next) = cps.get(i + 1)
+            && is_regional_indicator(next)
+        {
+            return (2, i + 2);
+        }
+        return (2, i + 1);
+    }
+
+    let mut width = code_point_width(cp);
+    let mut j = i + 1;
+    // Absorb trailing modifiers / combining marks / ZWJ-joined code points so
+    // the whole cluster counts as the width of its leading glyph.
+    while j < cps.len() {
+        let nxt = cps[j];
+        if nxt == 0x200d {
+            // ZWJ only forms a single rendered glyph when it joins emoji (e.g.
+            // 👨‍👩‍👧). For a ZWJ between non-emoji it is just a zero-width control
+            // and the following code point is its own cluster, so only absorb
+            // the joined code point when BOTH the leading glyph and the joined
+            // one are emoji/pictographic. Otherwise stop and let the joiner
+            // count as 0 and the next char count on its own.
+            if is_emoji_base(cp)
+                && let Some(&joined) = cps.get(j + 1)
+                && is_emoji_base(joined)
+            {
+                // Consume the ZWJ and the joined emoji (adds no extra width).
+                j += 2;
+                continue;
+            }
+            break;
+        }
+        // U+FE0F (variation selector-16) requests EMOJI presentation, which
+        // renders at full width 2 even for bases that are otherwise text-width
+        // 1 (e.g. ☀️ U+2600, ❤️ U+2764). U+20E3 (combining enclosing keycap)
+        // forms keycap emoji like 1️⃣ / #️⃣, also width 2. Promote accordingly.
+        if nxt == 0xfe0f || nxt == 0x20e3 {
+            width = 2;
+            j += 1;
+            continue;
+        }
+        if is_zero_width_code_point(nxt) || is_emoji_modifier(nxt) {
+            j += 1;
+            continue;
+        }
+        break;
+    }
+    (width, j)
+}
+
+/// Display width of a string in terminal columns (ignores ANSI; pass stripped text).
+pub fn display_width(text: &str) -> usize {
+    let cps: Vec<u32> = text.chars().map(|c| c as u32).collect();
+    let mut width = 0usize;
+    let mut i = 0usize;
+    while i < cps.len() {
+        let (w, next) = cluster_width_at(&cps, i);
+        width += w;
+        i = next;
+    }
+    width
+}
+
+/// Result of [`truncate_to_width`]: the kept prefix and its actual display width.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TruncateResult {
+    pub text: String,
+    pub width: usize,
+}
+
+/// Truncate `text` so its display width does not exceed `max_width`, returning
+/// the kept prefix and its actual display width. Never splits a wide glyph or a
+/// grapheme cluster (ZWJ sequence / flag / emoji+modifier) across the boundary.
+///
+/// The TS signature accepts any number and returns empty for `maxWidth <= 0`;
+/// here the parameter is unsigned, so callers clamp negatives to 0 first
+/// (`0` yields the same empty result).
+pub fn truncate_to_width(text: &str, max_width: usize) -> TruncateResult {
+    if max_width == 0 {
+        return TruncateResult {
+            text: String::new(),
+            width: 0,
+        };
+    }
+    let chars: Vec<char> = text.chars().collect();
+    let cps: Vec<u32> = chars.iter().map(|&c| c as u32).collect();
+    let mut width = 0usize;
+    let mut out = String::new();
+    let mut i = 0usize;
+    while i < cps.len() {
+        let (w, next) = cluster_width_at(&cps, i);
+        if width + w > max_width {
+            break;
+        }
+        out.extend(chars[i..next.min(chars.len())].iter());
+        width += w;
+        i = next;
+    }
+    TruncateResult { text: out, width }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn s(cps: &[u32]) -> String {
+        cps.iter()
+            .map(|&cp| char::from_u32(cp).expect("valid code point"))
+            .collect()
+    }
+
+    // === displayWidth (ported from test/display-width.test.ts) ===
+
+    #[test]
+    fn counts_ascii_as_1_column_each() {
+        assert_eq!(display_width("hello"), 5);
+        assert_eq!(display_width(""), 0);
+    }
+
+    #[test]
+    fn counts_cjk_ideographs_as_2_columns() {
+        assert_eq!(display_width("漢字"), 4); // 2 wide glyphs
+        assert_eq!(display_width("a漢"), 3); // 1 + 2
+    }
+
+    #[test]
+    fn counts_fullwidth_and_hangul_as_2_columns() {
+        assert_eq!(display_width("ＡＢ"), 4); // fullwidth A B
+        assert_eq!(display_width("한"), 2);
+    }
+
+    #[test]
+    fn treats_combining_marks_and_zwj_as_zero_width() {
+        let combining = s(&[0x65, 0x0301]); // e + COMBINING ACUTE ACCENT
+        assert_eq!(display_width(&combining), 1);
+        let zwj = s(&[0x61, 0x200d, 0x62]); // a + ZERO WIDTH JOINER + b
+        assert_eq!(display_width(&zwj), 2);
+    }
+
+    #[test]
+    fn counts_emoji_pictographs_as_2_columns() {
+        assert_eq!(display_width(&s(&[0x1f600])), 2);
+    }
+
+    #[test]
+    fn collapses_a_zwj_emoji_sequence_to_a_single_2_column_glyph() {
+        // 👨‍👩‍👧 = man + ZWJ + woman + ZWJ + girl. A naive per-code-point sum is
+        // 2+0+2+0+2 = 6; it renders as one 2-wide glyph.
+        let family = s(&[0x1f468, 0x200d, 0x1f469, 0x200d, 0x1f467]);
+        assert_eq!(display_width(&family), 2);
+    }
+
+    #[test]
+    fn counts_an_emoji_plus_skin_tone_modifier_as_one_2_column_glyph() {
+        // 👍 + medium-dark skin tone modifier (U+1F3FE) -> still 2 columns.
+        let thumbs_up = s(&[0x1f44d, 0x1f3fe]);
+        assert_eq!(display_width(&thumbs_up), 2);
+    }
+
+    #[test]
+    fn counts_a_regional_indicator_flag_pair_as_one_2_column_glyph() {
+        // 🇺🇸 = REGIONAL INDICATOR U + S -> one 2-wide flag, not 4.
+        let flag = s(&[0x1f1fa, 0x1f1f8]);
+        assert_eq!(display_width(&flag), 2);
+        // A lone trailing indicator still counts as one 2-wide glyph.
+        assert_eq!(display_width(&s(&[0x1f1fa])), 2);
+    }
+
+    #[test]
+    fn does_not_collapse_a_zwj_between_non_emoji_wide_chars() {
+        // 漢 + ZWJ + 字: two separate 2-wide CJK glyphs joined by a zero-width
+        // control = width 4, NOT 2. The ZWJ fast-path must gate on emoji-ness,
+        // not on "both sides are 2 columns".
+        let cjk_zwj = format!("漢{}字", s(&[0x200d]));
+        assert_eq!(display_width(&cjk_zwj), 4);
+    }
+
+    #[test]
+    fn counts_emoji_presentation_fe0f_clusters_at_rendered_width_2() {
+        // Bases that are text-width 1 render at width 2 with the
+        // emoji-presentation selector U+FE0F: ☀️ (U+2600), ❤️ (U+2764).
+        assert_eq!(display_width(&s(&[0x2600, 0xfe0f])), 2);
+        assert_eq!(display_width(&s(&[0x2764, 0xfe0f])), 2);
+        // Without FE0F the bare text symbol stays width 1.
+        assert_eq!(display_width(&s(&[0x2600])), 1);
+    }
+
+    #[test]
+    fn counts_a_keycap_sequence_as_width_2() {
+        // 1️⃣ = "1" + U+FE0F + U+20E3 (combining enclosing keycap).
+        let keycap = s(&[0x31, 0xfe0f, 0x20e3]);
+        assert_eq!(display_width(&keycap), 2);
+    }
+
+    #[test]
+    fn treats_non_latin_combining_marks_as_zero_width() {
+        // Arabic fatha (U+064E), Hebrew point (U+05B0), Thai sara-i (U+0E34).
+        assert_eq!(display_width(&s(&[0x61, 0x064e])), 1);
+        assert_eq!(display_width(&s(&[0x61, 0x05b0])), 1);
+        assert_eq!(display_width(&s(&[0x61, 0x0e34])), 1);
+    }
+
+    // === truncateToWidth ===
+
+    #[test]
+    fn truncates_by_columns_and_never_splits_a_wide_glyph() {
+        // "漢" is 2 cols; with max_width 1 it cannot fit, so it is dropped.
+        assert_eq!(
+            truncate_to_width("漢字", 1),
+            TruncateResult {
+                text: String::new(),
+                width: 0
+            }
+        );
+        assert_eq!(
+            truncate_to_width("漢字", 2),
+            TruncateResult {
+                text: "漢".to_string(),
+                width: 2
+            }
+        );
+        assert_eq!(
+            truncate_to_width("a漢b", 3),
+            TruncateResult {
+                text: "a漢".to_string(),
+                width: 3
+            }
+        );
+    }
+
+    #[test]
+    fn returns_empty_for_non_positive_width() {
+        assert_eq!(
+            truncate_to_width("anything", 0),
+            TruncateResult {
+                text: String::new(),
+                width: 0
+            }
+        );
+    }
+
+    #[test]
+    fn keeps_full_string_when_it_fits() {
+        assert_eq!(
+            truncate_to_width("hi", 10),
+            TruncateResult {
+                text: "hi".to_string(),
+                width: 2
+            }
+        );
+    }
+
+    #[test]
+    fn never_splits_a_zwj_emoji_cluster_across_the_boundary() {
+        // 👨‍👩‍👧 is one 2-wide cluster. At max_width 1 it can't fit (dropped
+        // whole); at 2 it is kept whole (never half a join).
+        let family = s(&[0x1f468, 0x200d, 0x1f469, 0x200d, 0x1f467]);
+        assert_eq!(
+            truncate_to_width(&family, 1),
+            TruncateResult {
+                text: String::new(),
+                width: 0
+            }
+        );
+        assert_eq!(
+            truncate_to_width(&family, 2),
+            TruncateResult {
+                text: family.clone(),
+                width: 2
+            }
+        );
+    }
+}
diff --git a/crates/core/src/env_parsing.rs b/crates/core/src/env_parsing.rs
new file mode 100644
index 000000000..befe04c86
--- /dev/null
+++ b/crates/core/src/env_parsing.rs
@@ -0,0 +1,81 @@
+//! Port of `lib/env-parsing.ts` — shared helper for parsing string
+//! environment variables.
+//!
+//! Pulled out of three near-identical local copies (lib/config.ts,
+//! lib/refresh-lease.ts, lib/codex-manager/commands/rotation.ts) so every call
+//! site agrees on accepted truthy/falsy literals and on what an unparseable
+//! value returns.
+
+const TRUE_VALUES: [&str; 3] = ["1", "true", "yes"];
+const FALSE_VALUES: [&str; 3] = ["0", "false", "no"];
+
+/// Parses a boolean environment-variable string (TS `parseBooleanEnv`).
+///
+/// Accepts (case-insensitive, trimmed): `"1"`/`"0"`, `"true"`/`"false"`,
+/// `"yes"`/`"no"`. Returns `None` for `None` input, an empty/whitespace-only
+/// string, or any value that doesn't match an accepted literal — letting
+/// callers fall back to default-handling logic.
+pub fn parse_boolean_env(value: Option<&str>) -> Option<bool> {
+    let value = value?;
+    let normalized = value.trim().to_lowercase();
+    if normalized.is_empty() {
+        return None;
+    }
+    if TRUE_VALUES.contains(&normalized.as_str()) {
+        return Some(true);
+    }
+    if FALSE_VALUES.contains(&normalized.as_str()) {
+        return Some(false);
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_the_six_accepted_literals() {
+        assert_eq!(parse_boolean_env(Some("1")), Some(true));
+        assert_eq!(parse_boolean_env(Some("0")), Some(false));
+        assert_eq!(parse_boolean_env(Some("true")), Some(true));
+        assert_eq!(parse_boolean_env(Some("false")), Some(false));
+        assert_eq!(parse_boolean_env(Some("yes")), Some(true));
+        assert_eq!(parse_boolean_env(Some("no")), Some(false));
+    }
+
+    #[test]
+    fn tolerates_case_and_whitespace() {
+        assert_eq!(parse_boolean_env(Some("TRUE")), Some(true));
+        assert_eq!(parse_boolean_env(Some("True")), Some(true));
+        assert_eq!(parse_boolean_env(Some("FALSE")), Some(false));
+        assert_eq!(parse_boolean_env(Some("YES")), Some(true));
+        assert_eq!(parse_boolean_env(Some("No")), Some(false));
+        assert_eq!(parse_boolean_env(Some("  true  ")), Some(true));
+        assert_eq!(parse_boolean_env(Some("\tfalse\n")), Some(false));
+        assert_eq!(parse_boolean_env(Some("  1 ")), Some(true));
+        assert_eq!(parse_boolean_env(Some("  0 ")), Some(false));
+    }
+
+    #[test]
+    fn returns_none_for_unset_empty_or_unrecognised() {
+        assert_eq!(parse_boolean_env(None), None);
+        for input in [
+            "", "   ", "\t\n", "maybe", "enabled", "disabled", "on", "off", "2", "-1", "null",
+            "undefined",
+        ] {
+            assert_eq!(parse_boolean_env(Some(input)), None, "input {input:?}");
+        }
+    }
+
+    #[test]
+    fn supports_nullish_coalescing_semantics() {
+        let fallback = true;
+        assert!(parse_boolean_env(Some("garbage")).unwrap_or(fallback));
+        assert!(parse_boolean_env(None).unwrap_or(fallback));
+        assert!(parse_boolean_env(Some("")).unwrap_or(fallback));
+        // An explicitly parsed false wins over the default.
+        assert!(!parse_boolean_env(Some("false")).unwrap_or(fallback));
+        assert!(!parse_boolean_env(Some("0")).unwrap_or(fallback));
+    }
+}
diff --git a/crates/core/src/errors.rs b/crates/core/src/errors.rs
new file mode 100644
index 000000000..c5a791468
--- /dev/null
+++ b/crates/core/src/errors.rs
@@ -0,0 +1,703 @@
+//! Port of `lib/errors.ts` — the typed error hierarchy for the Codex plugin.
+//!
+//! The TS class hierarchy (`CodexError` base + Api/Auth/Network/Validation/
+//! RateLimit/Storage/Unavailable subclasses) is modeled as one enum with
+//! accessor impls (ARCHITECTURE §6.1). All `code` strings and the TS class
+//! `name` strings are load-bearing and FROZEN — modules branch on them.
+//!
+//! Gotcha 21 (spec 01 §11): [`is_codex_unavailable_error`] must match on the
+//! `"CODEX_UNAVAILABLE"` code STRING, not only the concrete variant, so a
+//! generic error carrying the structural marker still matches (the Rust
+//! equivalent of the TS cross-realm guard).
+
+use std::collections::HashMap;
+use std::error::Error as StdError;
+
+use serde_json::{Map, Value};
+
+/// Chained underlying cause (TS `cause`).
+pub type ErrorCause = Box<dyn StdError + Send + Sync + 'static>;
+
+/// Arbitrary structured context data (TS `context?: Record<string, unknown>`).
+pub type ErrorContext = Map<String, Value>;
+
+/// Error codes for categorizing errors (TS `ErrorCode` const object).
+pub struct ErrorCode;
+
+impl ErrorCode {
+    pub const NETWORK_ERROR: &'static str = "CODEX_NETWORK_ERROR";
+    pub const API_ERROR: &'static str = "CODEX_API_ERROR";
+    pub const AUTH_ERROR: &'static str = "CODEX_AUTH_ERROR";
+    pub const VALIDATION_ERROR: &'static str = "CODEX_VALIDATION_ERROR";
+    pub const RATE_LIMIT: &'static str = "CODEX_RATE_LIMIT";
+    pub const TIMEOUT: &'static str = "CODEX_TIMEOUT";
+    pub const CODEX_UNAVAILABLE: &'static str = "CODEX_UNAVAILABLE";
+}
+
+/// The Codex error family. One variant per TS class:
+///
+/// | Variant        | TS class                | default `code`            |
+/// |----------------|-------------------------|---------------------------|
+/// | `Base`         | `CodexError`            | `CODEX_API_ERROR`         |
+/// | `Api`          | `CodexApiError`         | `CODEX_API_ERROR`         |
+/// | `Auth`         | `CodexAuthError`        | `CODEX_AUTH_ERROR`        |
+/// | `Network`      | `CodexNetworkError`     | `CODEX_NETWORK_ERROR`     |
+/// | `Validation`   | `CodexValidationError`  | `CODEX_VALIDATION_ERROR`  |
+/// | `RateLimit`    | `CodexRateLimitError`   | `CODEX_RATE_LIMIT`        |
+/// | `Storage`      | `StorageError`          | (caller-supplied)         |
+/// | `Unavailable`  | `CodexUnavailableError` | `CODEX_UNAVAILABLE`       |
+#[derive(Debug, thiserror::Error)]
+pub enum CodexError {
+    /// Base `CodexError`.
+    #[error("{message}")]
+    Base {
+        message: String,
+        code: String,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexApiError` — HTTP/API response errors.
+    #[error("{message}")]
+    Api {
+        message: String,
+        code: String,
+        status: u16,
+        headers: Option<HashMap<String, String>>,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexAuthError` — authentication failures. `retryable` defaults FALSE.
+    #[error("{message}")]
+    Auth {
+        message: String,
+        code: String,
+        account_id: Option<String>,
+        retryable: bool,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexNetworkError` — network/connection failures. `retryable` defaults TRUE.
+    #[error("{message}")]
+    Network {
+        message: String,
+        code: String,
+        retryable: bool,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexValidationError` — input validation failures.
+    #[error("{message}")]
+    Validation {
+        message: String,
+        code: String,
+        field: Option<String>,
+        expected: Option<String>,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexRateLimitError` — rate limit exceeded.
+    #[error("{message}")]
+    RateLimit {
+        message: String,
+        code: String,
+        retry_after_ms: Option<i64>,
+        account_id: Option<String>,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `StorageError` — filesystem code (e.g. `"UNREADABLE"`), target path, and
+    /// user-facing hint. Built via the positional ctor [`CodexError::storage`].
+    #[error("{message}")]
+    Storage {
+        message: String,
+        code: String,
+        path: String,
+        hint: String,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+    /// `CodexUnavailableError` — account signed in but no Codex entitlement.
+    /// A warning, not a failure.
+    #[error("{message}")]
+    Unavailable {
+        message: String,
+        code: String,
+        context: Option<ErrorContext>,
+        #[source]
+        cause: Option<ErrorCause>,
+    },
+}
+
+impl CodexError {
+    // ---- constructors (defaults mirror the TS constructors exactly) ----
+
+    /// `new CodexError(message)` — default code `CODEX_API_ERROR`.
+    pub fn new(message: impl Into<String>) -> Self {
+        CodexError::Base {
+            message: message.into(),
+            code: ErrorCode::API_ERROR.to_string(),
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new CodexApiError(message, { status })` — default code `CODEX_API_ERROR`.
+    pub fn api(message: impl Into<String>, status: u16) -> Self {
+        CodexError::Api {
+            message: message.into(),
+            code: ErrorCode::API_ERROR.to_string(),
+            status,
+            headers: None,
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new CodexAuthError(message)` — default code `CODEX_AUTH_ERROR`,
+    /// `retryable` defaults to **false**.
+    pub fn auth(message: impl Into<String>) -> Self {
+        CodexError::Auth {
+            message: message.into(),
+            code: ErrorCode::AUTH_ERROR.to_string(),
+            account_id: None,
+            retryable: false,
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new CodexNetworkError(message)` — default code `CODEX_NETWORK_ERROR`,
+    /// `retryable` defaults to **true**.
+    pub fn network(message: impl Into<String>) -> Self {
+        CodexError::Network {
+            message: message.into(),
+            code: ErrorCode::NETWORK_ERROR.to_string(),
+            retryable: true,
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new CodexValidationError(message)` — default code `CODEX_VALIDATION_ERROR`.
+    pub fn validation(message: impl Into<String>) -> Self {
+        CodexError::Validation {
+            message: message.into(),
+            code: ErrorCode::VALIDATION_ERROR.to_string(),
+            field: None,
+            expected: None,
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new CodexRateLimitError(message)` — default code `CODEX_RATE_LIMIT`.
+    pub fn rate_limit(message: impl Into<String>) -> Self {
+        CodexError::RateLimit {
+            message: message.into(),
+            code: ErrorCode::RATE_LIMIT.to_string(),
+            retry_after_ms: None,
+            account_id: None,
+            context: None,
+            cause: None,
+        }
+    }
+
+    /// `new StorageError(message, code, path, hint, cause?)` — POSITIONAL ctor
+    /// (spec 01 §2.7). config.ts uses code `"UNREADABLE"`.
+    pub fn storage(
+        message: impl Into<String>,
+        code: impl Into<String>,
+        path: impl Into<String>,
+        hint: impl Into<String>,
+        cause: Option<ErrorCause>,
+    ) -> Self {
+        CodexError::Storage {
+            message: message.into(),
+            code: code.into(),
+            path: path.into(),
+            hint: hint.into(),
+            context: None,
+            cause,
+        }
+    }
+
+    /// `new CodexUnavailableError(message)` — default code `CODEX_UNAVAILABLE`.
+    pub fn unavailable(message: impl Into<String>) -> Self {
+        CodexError::Unavailable {
+            message: message.into(),
+            code: ErrorCode::CODEX_UNAVAILABLE.to_string(),
+            context: None,
+            cause: None,
+        }
+    }
+
+    // ---- builder-style option setters (the TS options bag) ----
+
+    /// Overrides the `code` (any variant; TS `options.code`).
+    pub fn with_code(mut self, code: impl Into<String>) -> Self {
+        *self.code_slot() = code.into();
+        self
+    }
+
+    /// Attaches arbitrary context data (any variant; TS `options.context`).
+    pub fn with_context(mut self, context: ErrorContext) -> Self {
+        *self.context_slot() = Some(context);
+        self
+    }
+
+    /// Chains an underlying cause (any variant; TS `options.cause`).
+    pub fn with_cause(mut self, cause: impl Into<ErrorCause>) -> Self {
+        *self.cause_slot() = Some(cause.into());
+        self
+    }
+
+    /// Attaches response headers (`Api` variant only; no-op elsewhere).
+    pub fn with_headers(mut self, value: HashMap<String, String>) -> Self {
+        if let CodexError::Api { headers, .. } = &mut self {
+            *headers = Some(value);
+        }
+        self
+    }
+
+    /// Sets `accountId` (`Auth` / `RateLimit` variants only; no-op elsewhere).
+    pub fn with_account_id(mut self, value: impl Into<String>) -> Self {
+        match &mut self {
+            CodexError::Auth { account_id, .. } | CodexError::RateLimit { account_id, .. } => {
+                *account_id = Some(value.into());
+            }
+            _ => {}
+        }
+        self
+    }
+
+    /// Sets `retryable` (`Auth` / `Network` variants only; no-op elsewhere).
+    pub fn with_retryable(mut self, value: bool) -> Self {
+        match &mut self {
+            CodexError::Auth { retryable, .. } | CodexError::Network { retryable, .. } => {
+                *retryable = value;
+            }
+            _ => {}
+        }
+        self
+    }
+
+    /// Sets `field` (`Validation` variant only; no-op elsewhere).
+    pub fn with_field(mut self, value: impl Into<String>) -> Self {
+        if let CodexError::Validation { field, .. } = &mut self {
+            *field = Some(value.into());
+        }
+        self
+    }
+
+    /// Sets `expected` (`Validation` variant only; no-op elsewhere).
+    pub fn with_expected(mut self, value: impl Into<String>) -> Self {
+        if let CodexError::Validation { expected, .. } = &mut self {
+            *expected = Some(value.into());
+        }
+        self
+    }
+
+    /// Sets `retryAfterMs` (`RateLimit` variant only; no-op elsewhere).
+    pub fn with_retry_after_ms(mut self, value: i64) -> Self {
+        if let CodexError::RateLimit { retry_after_ms, .. } = &mut self {
+            *retry_after_ms = Some(value);
+        }
+        self
+    }
+
+    // ---- accessors ----
+
+    /// The TS class name (`error.name`). FROZEN strings used in logs/output.
+    pub fn name(&self) -> &'static str {
+        match self {
+            CodexError::Base { .. } => "CodexError",
+            CodexError::Api { .. } => "CodexApiError",
+            CodexError::Auth { .. } => "CodexAuthError",
+            CodexError::Network { .. } => "CodexNetworkError",
+            CodexError::Validation { .. } => "CodexValidationError",
+            CodexError::RateLimit { .. } => "CodexRateLimitError",
+            CodexError::Storage { .. } => "StorageError",
+            CodexError::Unavailable { .. } => "CodexUnavailableError",
+        }
+    }
+
+    /// The error `code` string other modules branch on.
+    pub fn code(&self) -> &str {
+        match self {
+            CodexError::Base { code, .. }
+            | CodexError::Api { code, .. }
+            | CodexError::Auth { code, .. }
+            | CodexError::Network { code, .. }
+            | CodexError::Validation { code, .. }
+            | CodexError::RateLimit { code, .. }
+            | CodexError::Storage { code, .. }
+            | CodexError::Unavailable { code, .. } => code,
+        }
+    }
+
+    /// The error message (`error.message`; also the `Display` output).
+    pub fn message(&self) -> &str {
+        match self {
+            CodexError::Base { message, .. }
+            | CodexError::Api { message, .. }
+            | CodexError::Auth { message, .. }
+            | CodexError::Network { message, .. }
+            | CodexError::Validation { message, .. }
+            | CodexError::RateLimit { message, .. }
+            | CodexError::Storage { message, .. }
+            | CodexError::Unavailable { message, .. } => message,
+        }
+    }
+
+    /// Structured context data, when attached.
+    pub fn context(&self) -> Option<&ErrorContext> {
+        match self {
+            CodexError::Base { context, .. }
+            | CodexError::Api { context, .. }
+            | CodexError::Auth { context, .. }
+            | CodexError::Network { context, .. }
+            | CodexError::Validation { context, .. }
+            | CodexError::RateLimit { context, .. }
+            | CodexError::Storage { context, .. }
+            | CodexError::Unavailable { context, .. } => context.as_ref(),
+        }
+    }
+
+    /// HTTP status (`Api` variant).
+    pub fn status(&self) -> Option<u16> {
+        match self {
+            CodexError::Api { status, .. } => Some(*status),
+            _ => None,
+        }
+    }
+
+    /// Response headers (`Api` variant).
+    pub fn headers(&self) -> Option<&HashMap<String, String>> {
+        match self {
+            CodexError::Api { headers, .. } => headers.as_ref(),
+            _ => None,
+        }
+    }
+
+    /// Account id (`Auth` / `RateLimit` variants).
+    pub fn account_id(&self) -> Option<&str> {
+        match self {
+            CodexError::Auth { account_id, .. } | CodexError::RateLimit { account_id, .. } => {
+                account_id.as_deref()
+            }
+            _ => None,
+        }
+    }
+
+    /// Retryability flag. `Some` only for the variants that carry one
+    /// (`Auth` — default false; `Network` — default true).
+    pub fn retryable(&self) -> Option<bool> {
+        match self {
+            CodexError::Auth { retryable, .. } | CodexError::Network { retryable, .. } => {
+                Some(*retryable)
+            }
+            _ => None,
+        }
+    }
+
+    /// Failing field name (`Validation` variant).
+    pub fn field(&self) -> Option<&str> {
+        match self {
+            CodexError::Validation { field, .. } => field.as_deref(),
+            _ => None,
+        }
+    }
+
+    /// Expected-value description (`Validation` variant).
+    pub fn expected(&self) -> Option<&str> {
+        match self {
+            CodexError::Validation { expected, .. } => expected.as_deref(),
+            _ => None,
+        }
+    }
+
+    /// Retry-after hint in ms (`RateLimit` variant).
+    pub fn retry_after_ms(&self) -> Option<i64> {
+        match self {
+            CodexError::RateLimit { retry_after_ms, .. } => *retry_after_ms,
+            _ => None,
+        }
+    }
+
+    /// Target path (`Storage` variant).
+    pub fn path(&self) -> Option<&str> {
+        match self {
+            CodexError::Storage { path, .. } => Some(path),
+            _ => None,
+        }
+    }
+
+    /// User-facing hint (`Storage` variant).
+    pub fn hint(&self) -> Option<&str> {
+        match self {
+            CodexError::Storage { hint, .. } => Some(hint),
+            _ => None,
+        }
+    }
+
+    /// Structural check on the CODE STRING (spec 01 gotcha 21) — matches any
+    /// variant whose code is `"CODEX_UNAVAILABLE"`, not just `Unavailable`.
+    pub fn is_codex_unavailable(&self) -> bool {
+        self.code() == ErrorCode::CODEX_UNAVAILABLE
+    }
+
+    // ---- private slot helpers ----
+
+    fn code_slot(&mut self) -> &mut String {
+        match self {
+            CodexError::Base { code, .. }
+            | CodexError::Api { code, .. }
+            | CodexError::Auth { code, .. }
+            | CodexError::Network { code, .. }
+            | CodexError::Validation { code, .. }
+            | CodexError::RateLimit { code, .. }
+            | CodexError::Storage { code, .. }
+            | CodexError::Unavailable { code, .. } => code,
+        }
+    }
+
+    fn context_slot(&mut self) -> &mut Option<ErrorContext> {
+        match self {
+            CodexError::Base { context, .. }
+            | CodexError::Api { context, .. }
+            | CodexError::Auth { context, .. }
+            | CodexError::Network { context, .. }
+            | CodexError::Validation { context, .. }
+            | CodexError::RateLimit { context, .. }
+            | CodexError::Storage { context, .. }
+            | CodexError::Unavailable { context, .. } => context,
+        }
+    }
+
+    fn cause_slot(&mut self) -> &mut Option<ErrorCause> {
+        match self {
+            CodexError::Base { cause, .. }
+            | CodexError::Api { cause, .. }
+            | CodexError::Auth { cause, .. }
+            | CodexError::Network { cause, .. }
+            | CodexError::Validation { cause, .. }
+            | CodexError::RateLimit { cause, .. }
+            | CodexError::Storage { cause, .. }
+            | CodexError::Unavailable { cause, .. } => cause,
+        }
+    }
+}
+
+/// Type guard for `CodexUnavailableError` (TS `isCodexUnavailableError`).
+///
+/// Matches on the structural `"CODEX_UNAVAILABLE"` code marker so it survives
+/// the Rust analogue of cross-realm/duplicate-module identity loss: ANY
+/// [`CodexError`] variant carrying that code matches, not just
+/// [`CodexError::Unavailable`].
+pub fn is_codex_unavailable_error(error: &(dyn StdError + 'static)) -> bool {
+    error
+        .downcast_ref::<CodexError>()
+        .is_some_and(CodexError::is_codex_unavailable)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn error_codes_match_ts() {
+        assert_eq!(ErrorCode::NETWORK_ERROR, "CODEX_NETWORK_ERROR");
+        assert_eq!(ErrorCode::API_ERROR, "CODEX_API_ERROR");
+        assert_eq!(ErrorCode::AUTH_ERROR, "CODEX_AUTH_ERROR");
+        assert_eq!(ErrorCode::VALIDATION_ERROR, "CODEX_VALIDATION_ERROR");
+        assert_eq!(ErrorCode::RATE_LIMIT, "CODEX_RATE_LIMIT");
+        assert_eq!(ErrorCode::TIMEOUT, "CODEX_TIMEOUT");
+        assert_eq!(ErrorCode::CODEX_UNAVAILABLE, "CODEX_UNAVAILABLE");
+    }
+
+    #[test]
+    fn base_error_defaults_to_api_error_code() {
+        let error = CodexError::new("Test error");
+        assert_eq!(error.message(), "Test error");
+        assert_eq!(error.name(), "CodexError");
+        assert_eq!(error.code(), ErrorCode::API_ERROR);
+        assert_eq!(error.to_string(), "Test error");
+    }
+
+    #[test]
+    fn base_error_accepts_custom_code() {
+        let error = CodexError::new("Test error").with_code(ErrorCode::TIMEOUT);
+        assert_eq!(error.code(), ErrorCode::TIMEOUT);
+    }
+
+    #[test]
+    fn base_error_accepts_cause_for_chaining() {
+        let cause = std::io::Error::other("Original error");
+        let error = CodexError::new("Wrapped error").with_cause(cause);
+        let source = error.source().expect("cause should chain via source()");
+        assert_eq!(source.to_string(), "Original error");
+    }
+
+    #[test]
+    fn base_error_accepts_context_data() {
+        let mut context = ErrorContext::new();
+        context.insert("accountId".into(), Value::from("123"));
+        context.insert("attempt".into(), Value::from(2));
+        let error = CodexError::new("Test error").with_context(context.clone());
+        assert_eq!(error.context(), Some(&context));
+    }
+
+    #[test]
+    fn api_error_carries_status_and_headers() {
+        let error = CodexError::api("Not found", 404);
+        assert_eq!(error.message(), "Not found");
+        assert_eq!(error.name(), "CodexApiError");
+        assert_eq!(error.status(), Some(404));
+        assert_eq!(error.code(), ErrorCode::API_ERROR);
+
+        let mut headers = HashMap::new();
+        headers.insert("retry-after".to_string(), "60".to_string());
+        headers.insert("x-request-id".to_string(), "abc123".to_string());
+        let error = CodexError::api("Rate limited", 429).with_headers(headers.clone());
+        assert_eq!(error.headers(), Some(&headers));
+    }
+
+    #[test]
+    fn api_error_accepts_custom_code_and_cause() {
+        let error = CodexError::api("Custom", 500).with_code(ErrorCode::TIMEOUT);
+        assert_eq!(error.code(), ErrorCode::TIMEOUT);
+
+        let cause = std::io::Error::other("Network failure");
+        let error = CodexError::api("API failed", 503).with_cause(cause);
+        assert!(error.source().is_some());
+    }
+
+    #[test]
+    fn auth_error_defaults() {
+        let error = CodexError::auth("Token expired");
+        assert_eq!(error.message(), "Token expired");
+        assert_eq!(error.name(), "CodexAuthError");
+        assert_eq!(error.code(), ErrorCode::AUTH_ERROR);
+        assert_eq!(error.retryable(), Some(false));
+        assert_eq!(error.account_id(), None);
+    }
+
+    #[test]
+    fn auth_error_accepts_account_id_and_retryable() {
+        let error = CodexError::auth("Invalid token").with_account_id("user@example.com");
+        assert_eq!(error.account_id(), Some("user@example.com"));
+
+        let error = CodexError::auth("Temporary failure").with_retryable(true);
+        assert_eq!(error.retryable(), Some(true));
+    }
+
+    #[test]
+    fn network_error_defaults() {
+        let error = CodexError::network("Connection refused");
+        assert_eq!(error.message(), "Connection refused");
+        assert_eq!(error.name(), "CodexNetworkError");
+        assert_eq!(error.code(), ErrorCode::NETWORK_ERROR);
+        assert_eq!(error.retryable(), Some(true));
+
+        let error = CodexError::network("Permanent DNS failure").with_retryable(false);
+        assert_eq!(error.retryable(), Some(false));
+    }
+
+    #[test]
+    fn validation_error_fields() {
+        let error = CodexError::validation("Invalid input");
+        assert_eq!(error.name(), "CodexValidationError");
+        assert_eq!(error.code(), ErrorCode::VALIDATION_ERROR);
+        assert_eq!(error.field(), None);
+        assert_eq!(error.expected(), None);
+
+        let error = CodexError::validation("Invalid type")
+            .with_field("age")
+            .with_expected("number");
+        assert_eq!(error.field(), Some("age"));
+        assert_eq!(error.expected(), Some("number"));
+    }
+
+    #[test]
+    fn rate_limit_error_fields() {
+        let error = CodexError::rate_limit("Rate limited");
+        assert_eq!(error.name(), "CodexRateLimitError");
+        assert_eq!(error.code(), ErrorCode::RATE_LIMIT);
+        assert_eq!(error.retry_after_ms(), None);
+        assert_eq!(error.account_id(), None);
+
+        let error = CodexError::rate_limit("Account limited")
+            .with_account_id("user@example.com")
+            .with_retry_after_ms(30_000);
+        assert_eq!(error.account_id(), Some("user@example.com"));
+        assert_eq!(error.retry_after_ms(), Some(30_000));
+    }
+
+    #[test]
+    fn storage_error_positional_ctor() {
+        let error = CodexError::storage(
+            "Aborting config save because /tmp/config.json is unreadable.",
+            "UNREADABLE",
+            "/tmp/config.json",
+            "Fix or remove the unreadable config file, then retry the save.",
+            Some(Box::new(std::io::Error::other("EACCES"))),
+        );
+        assert_eq!(error.name(), "StorageError");
+        assert_eq!(error.code(), "UNREADABLE");
+        assert_eq!(error.path(), Some("/tmp/config.json"));
+        assert_eq!(
+            error.hint(),
+            Some("Fix or remove the unreadable config file, then retry the save.")
+        );
+        assert!(error.source().is_some());
+    }
+
+    #[test]
+    fn unavailable_error_exposes_code_and_preserves_cause() {
+        let cause = std::io::Error::other("all models unsupported");
+        let error = CodexError::unavailable("Codex not available").with_cause(cause);
+        assert_eq!(error.name(), "CodexUnavailableError");
+        assert_eq!(error.code(), ErrorCode::CODEX_UNAVAILABLE);
+        assert_eq!(error.message(), "Codex not available");
+        assert_eq!(
+            error.source().unwrap().to_string(),
+            "all models unsupported"
+        );
+    }
+
+    #[test]
+    fn is_codex_unavailable_matches_instances_and_structural_code_marker() {
+        let instance = CodexError::unavailable("x");
+        assert!(is_codex_unavailable_error(&instance));
+
+        // Cross-realm / duplicate-module guard: a generic error carrying the code.
+        let structural = CodexError::new("x").with_code(ErrorCode::CODEX_UNAVAILABLE);
+        assert!(is_codex_unavailable_error(&structural));
+        assert!(structural.is_codex_unavailable());
+    }
+
+    #[test]
+    fn is_codex_unavailable_rejects_unrelated_errors() {
+        assert!(!is_codex_unavailable_error(&CodexError::api("x", 400)));
+        assert!(!is_codex_unavailable_error(&CodexError::new("x")));
+        let io_error = std::io::Error::other("x");
+        assert!(!is_codex_unavailable_error(&io_error));
+    }
+
+    #[test]
+    fn display_is_message_only() {
+        // Frozen user-visible behavior: Display never prepends the name/code.
+        let error = CodexError::auth("Failed to refresh token, authentication required");
+        assert_eq!(
+            format!("{error}"),
+            "Failed to refresh token, authentication required"
+        );
+    }
+}
diff --git a/crates/core/src/fs_retry.rs b/crates/core/src/fs_retry.rs
new file mode 100644
index 000000000..3d5da0c24
--- /dev/null
+++ b/crates/core/src/fs_retry.rs
@@ -0,0 +1,909 @@
+//! Port of `lib/fs-retry.ts` — generic transient-FS-error retry engine.
+//!
+//! Behavior source: specs/01-foundation.md §2.5, §6, §10.1, gotcha 19.
+//!
+//! Key contracts preserved from the TS source:
+//! - An error retries only when it carries a string errno-style code contained
+//!   in the retryable set (default [`FILE_RETRY_CODES`]); everything else is
+//!   returned immediately.
+//! - The backoff callback receives the **1-based index of the attempt that
+//!   just failed** (first failure → `backoff(1)`).
+//! - A computed delay of `0` retries immediately without sleeping.
+//! - Once `max_attempts` is exhausted the error from the final attempt is
+//!   returned unchanged; no delay is scheduled after the final attempt.
+//! - `on_retry` fires after each retryable failure, before the delay, and is
+//!   never invoked for the final failure.
+//! - [`with_file_operation_retry`] = 6 attempts, base 25 ms doubling
+//!   (25/50/100/200/400), jitter 0–19 ms, codes EBUSY/EPERM/EAGAIN/ENOTEMPTY/
+//!   EACCES.
+//!
+//! Rust-specific notes:
+//! - Node surfaces errno code STRINGS on every fs error; Rust's `io::Error`
+//!   carries raw OS error numbers instead. [`code_of`] is the shim that maps
+//!   raw Windows error codes (via the libuv translation table Node itself
+//!   uses) and Unix errnos back to the Node code strings the retry sets are
+//!   written against. Errors minted in-process with a synthetic code (e.g.
+//!   `"ESTALE"`, `"ELOCKTIMEOUT"`) travel as a [`CodedError`] payload inside
+//!   an `io::Error` (see [`io_error_with_code`]) and are recognized first.
+//! - `with_retry_sync` uses `std::thread::sleep` for positive delays instead
+//!   of the TS busy-wait loop (sanctioned by ARCHITECTURE.md §5.4; never call
+//!   it inside async code — use [`with_retry`] there).
+
+use std::fmt;
+use std::io;
+use std::time::Duration;
+
+/// Transient filesystem error codes shared by the canned file-operation
+/// policy. Exported because several call sites reuse the set verbatim.
+pub const FILE_RETRY_CODES: &[&str] = &["EBUSY", "EPERM", "EAGAIN", "ENOTEMPTY", "EACCES"];
+
+const FILE_RETRY_MAX_ATTEMPTS: u32 = 6;
+const FILE_RETRY_BASE_DELAY_MS: u64 = 25;
+const FILE_RETRY_JITTER_MS: u64 = 20;
+
+// ---------------------------------------------------------------------------
+// Error-code extraction
+// ---------------------------------------------------------------------------
+
+/// Node-style errno code extraction. The TS engine retried any thrown value
+/// carrying a string `code` property; Rust error types opt in by implementing
+/// this trait. `cma-core` provides impls for [`std::io::Error`] (via
+/// [`code_of`]) and [`CodedError`]; downstream crates implement it for their
+/// own error enums where they mint synthetic codes.
+pub trait HasErrorCode {
+    /// The Node errno-style code string (e.g. `"EBUSY"`), if any.
+    fn error_code(&self) -> Option<&str>;
+}
+
+impl HasErrorCode for io::Error {
+    fn error_code(&self) -> Option<&str> {
+        code_of(self)
+    }
+}
+
+impl HasErrorCode for CodedError {
+    fn error_code(&self) -> Option<&str> {
+        Some(self.code)
+    }
+}
+
+/// An error payload carrying an explicit Node-style code string. Used to mint
+/// in-process errors (`"ESTALE"`, `"ELOCKTIMEOUT"`, `"EEMPTY"`, …) that flow
+/// through [`with_retry`] with per-site retryable-code sets, exactly like the
+/// ad-hoc `NodeJS.ErrnoException` objects the TS code created.
+#[derive(Debug)]
+pub struct CodedError {
+    code: &'static str,
+    message: String,
+}
+
+impl CodedError {
+    pub fn new(code: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+        }
+    }
+
+    pub fn code(&self) -> &'static str {
+        self.code
+    }
+
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl fmt::Display for CodedError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for CodedError {}
+
+/// Wrap a synthetic code + message into an `io::Error` whose code is
+/// recoverable through [`code_of`]. This is how the port represents the
+/// TS pattern `Object.assign(new Error(msg), { code: "ESTALE" })`.
+pub fn io_error_with_code(code: &'static str, message: impl Into<String>) -> io::Error {
+    io::Error::other(CodedError::new(code, message))
+}
+
+/// Map an `io::Error` to the Node errno code string the TS retry sets are
+/// written against.
+///
+/// Resolution order:
+/// 1. An embedded [`CodedError`] payload (synthetic in-process codes) wins.
+/// 2. The raw OS error number, translated per platform. The Windows table
+///    follows libuv's `uv_translate_sys_error` (what Node actually reports):
+///    `ERROR_SHARING_VIOLATION`/`ERROR_LOCK_VIOLATION` → `EBUSY`,
+///    `ERROR_ACCESS_DENIED`/`ERROR_PRIVILEGE_NOT_HELD` → `EPERM`,
+///    `ERROR_NOACCESS`/`ERROR_ELEVATION_REQUIRED`/`ERROR_CANT_ACCESS_FILE` →
+///    `EACCES`, `ERROR_DIR_NOT_EMPTY` → `ENOTEMPTY`, etc.
+/// 3. A conservative `io::ErrorKind` fallback for errors without a raw OS
+///    number (custom errors minted by Rust std or other crates).
+pub fn code_of(error: &io::Error) -> Option<&'static str> {
+    if let Some(coded) = error
+        .get_ref()
+        .and_then(|inner| inner.downcast_ref::<CodedError>())
+    {
+        return Some(coded.code);
+    }
+    if let Some(code) = error.raw_os_error().and_then(code_for_raw_os_error) {
+        return Some(code);
+    }
+    code_for_error_kind(error.kind())
+}
+
+#[cfg(windows)]
+fn code_for_raw_os_error(raw: i32) -> Option<&'static str> {
+    // Windows error codes translated per libuv's uv_translate_sys_error —
+    // the exact mapping Node.js applies before exposing `error.code`.
+    Some(match raw {
+        2 | 3 | 123 => "ENOENT",      // FILE_NOT_FOUND / PATH_NOT_FOUND / INVALID_NAME
+        4 => "EMFILE",                // TOO_MANY_OPEN_FILES
+        5 | 1314 => "EPERM",          // ACCESS_DENIED / PRIVILEGE_NOT_HELD
+        32 | 33 | 231 => "EBUSY",     // SHARING_VIOLATION / LOCK_VIOLATION / PIPE_BUSY
+        145 => "ENOTEMPTY",           // DIR_NOT_EMPTY
+        80 | 183 => "EEXIST",         // FILE_EXISTS / ALREADY_EXISTS
+        998 | 740 | 1920 => "EACCES", // NOACCESS / ELEVATION_REQUIRED / CANT_ACCESS_FILE
+        206 => "ENAMETOOLONG",        // FILENAME_EXCED_RANGE
+        39 | 112 => "ENOSPC",         // HANDLE_DISK_FULL / DISK_FULL
+        19 => "EROFS",                // WRITE_PROTECT
+        267 => "ENOTDIR",             // ERROR_DIRECTORY
+        87 => "EINVAL",               // INVALID_PARAMETER
+        6 => "EBADF",                 // INVALID_HANDLE
+        995 => "ECANCELED",           // OPERATION_ABORTED
+        8 | 14 | 1816 => "ENOMEM",    // NOT_ENOUGH_MEMORY / OUTOFMEMORY / NOT_ENOUGH_QUOTA
+        10013 => "EACCES",            // WSAEACCES
+        10035 => "EAGAIN",            // WSAEWOULDBLOCK
+        10048 => "EADDRINUSE",        // WSAEADDRINUSE
+        10054 => "ECONNRESET",        // WSAECONNRESET
+        10061 => "ECONNREFUSED",      // WSAECONNREFUSED
+        _ => return None,
+    })
+}
+
+#[cfg(unix)]
+fn code_for_raw_os_error(raw: i32) -> Option<&'static str> {
+    // if/else chain instead of match: some errno constants alias each other
+    // on certain platforms (e.g. EAGAIN == EWOULDBLOCK on Linux) and duplicate
+    // match arms would not compile.
+    if raw == libc::EBUSY {
+        Some("EBUSY")
+    } else if raw == libc::EPERM {
+        Some("EPERM")
+    } else if raw == libc::EAGAIN || raw == libc::EWOULDBLOCK {
+        Some("EAGAIN")
+    } else if raw == libc::ENOTEMPTY {
+        Some("ENOTEMPTY")
+    } else if raw == libc::EACCES {
+        Some("EACCES")
+    } else if raw == libc::ENOENT {
+        Some("ENOENT")
+    } else if raw == libc::EEXIST {
+        Some("EEXIST")
+    } else if raw == libc::ESTALE {
+        Some("ESTALE")
+    } else if raw == libc::EISDIR {
+        Some("EISDIR")
+    } else if raw == libc::ENOTDIR {
+        Some("ENOTDIR")
+    } else if raw == libc::EINVAL {
+        Some("EINVAL")
+    } else if raw == libc::EMFILE {
+        Some("EMFILE")
+    } else if raw == libc::ENFILE {
+        Some("ENFILE")
+    } else if raw == libc::ENOSPC {
+        Some("ENOSPC")
+    } else if raw == libc::EROFS {
+        Some("EROFS")
+    } else if raw == libc::EXDEV {
+        Some("EXDEV")
+    } else if raw == libc::EIO {
+        Some("EIO")
+    } else if raw == libc::EPIPE {
+        Some("EPIPE")
+    } else if raw == libc::ELOOP {
+        Some("ELOOP")
+    } else if raw == libc::ENAMETOOLONG {
+        Some("ENAMETOOLONG")
+    } else if raw == libc::EINTR {
+        Some("EINTR")
+    } else if raw == libc::ETIMEDOUT {
+        Some("ETIMEDOUT")
+    } else if raw == libc::ECONNRESET {
+        Some("ECONNRESET")
+    } else if raw == libc::ECONNREFUSED {
+        Some("ECONNREFUSED")
+    } else if raw == libc::EADDRINUSE {
+        Some("EADDRINUSE")
+    } else if raw == libc::EBADF {
+        Some("EBADF")
+    } else if raw == libc::ENOMEM {
+        Some("ENOMEM")
+    } else if raw == libc::ECANCELED {
+        Some("ECANCELED")
+    } else if raw == libc::ETXTBSY {
+        Some("ETXTBSY")
+    } else if raw == libc::EMLINK {
+        Some("EMLINK")
+    } else if raw == libc::ENODEV {
+        Some("ENODEV")
+    } else {
+        None
+    }
+}
+
+fn code_for_error_kind(kind: io::ErrorKind) -> Option<&'static str> {
+    use io::ErrorKind as K;
+    Some(match kind {
+        K::NotFound => "ENOENT",
+        // Only reached for errors without a raw OS number; EACCES is the
+        // common POSIX source of PermissionDenied. Real Windows
+        // ERROR_ACCESS_DENIED errors carry a raw code and map to EPERM above.
+        K::PermissionDenied => "EACCES",
+        K::AlreadyExists => "EEXIST",
+        K::WouldBlock => "EAGAIN",
+        K::InvalidInput | K::InvalidData => "EINVAL",
+        K::TimedOut => "ETIMEDOUT",
+        K::Interrupted => "EINTR",
+        K::BrokenPipe => "EPIPE",
+        K::DirectoryNotEmpty => "ENOTEMPTY",
+        K::IsADirectory => "EISDIR",
+        K::NotADirectory => "ENOTDIR",
+        K::ReadOnlyFilesystem => "EROFS",
+        K::ResourceBusy => "EBUSY",
+        K::StaleNetworkFileHandle => "ESTALE",
+        K::StorageFull => "ENOSPC",
+        // (ErrorKind::FilesystemLoop is unstable — ELOOP is covered by the
+        // raw-OS-error mapping above, which every real fs error carries.)
+        K::ExecutableFileBusy => "ETXTBSY",
+        K::TooManyLinks => "EMLINK",
+        K::CrossesDevices => "EXDEV",
+        K::AddrInUse => "EADDRINUSE",
+        K::ConnectionRefused => "ECONNREFUSED",
+        K::ConnectionReset => "ECONNRESET",
+        _ => return None,
+    })
+}
+
+/// `shouldRetryFileOperation` — true when the error carries a code in
+/// [`FILE_RETRY_CODES`].
+pub fn should_retry_file_operation<E: HasErrorCode + ?Sized>(error: &E) -> bool {
+    match error.error_code() {
+        Some(code) => FILE_RETRY_CODES.contains(&code),
+        None => false,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Retry options
+// ---------------------------------------------------------------------------
+
+/// Delay schedule: either a fixed number of milliseconds or a function of the
+/// **1-based index of the attempt that just failed** (delay after the first
+/// failure is `f(1)`).
+pub enum Backoff {
+    Fixed(u64),
+    Custom(Box<dyn Fn(u32) -> u64 + Send + Sync>),
+}
+
+impl Backoff {
+    pub fn from_fn(f: impl Fn(u32) -> u64 + Send + Sync + 'static) -> Self {
+        Backoff::Custom(Box::new(f))
+    }
+
+    fn compute(&self, failed_attempt: u32) -> u64 {
+        match self {
+            Backoff::Fixed(ms) => *ms,
+            Backoff::Custom(f) => f(failed_attempt),
+        }
+    }
+}
+
+impl fmt::Debug for Backoff {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Backoff::Fixed(ms) => f.debug_tuple("Fixed").field(ms).finish(),
+            Backoff::Custom(_) => f.write_str("Custom(..)"),
+        }
+    }
+}
+
+/// Options for [`with_retry`] / [`with_retry_sync`]. Deliberately wide enough
+/// to express every hand-rolled file-retry loop in the codebase: per-site
+/// attempt counts, exponential/linear backoff schedules, optional jitter, and
+/// per-site retryable code sets are all preserved exactly.
+pub struct RetryOptions<E = io::Error> {
+    /// Total number of attempts (including the first one). Must be >= 1.
+    pub max_attempts: u32,
+    /// Delay before the next attempt (see [`Backoff`]). A computed delay of 0
+    /// retries immediately without sleeping.
+    pub backoff_ms: Backoff,
+    /// Optional jitter: adds `floor(random * jitter_ms)` (i.e. a uniform draw
+    /// from `0..jitter_ms`) to each computed backoff delay.
+    pub jitter_ms: Option<u64>,
+    /// Error codes considered transient. `None` = [`FILE_RETRY_CODES`]. An
+    /// error retries only when it carries a code in this set; everything else
+    /// is returned immediately.
+    pub retryable_codes: Option<Vec<&'static str>>,
+    /// Invoked after each retryable failure (with the 1-based attempt index),
+    /// before the backoff delay. Never invoked for the final failure.
+    pub on_retry: Option<OnRetry<E>>,
+}
+
+/// Callback invoked after each retryable failure (error, 1-based attempt index).
+pub type OnRetry<E> = Box<dyn FnMut(&E, u32) + Send>;
+
+impl<E> RetryOptions<E> {
+    pub fn new(max_attempts: u32, backoff_ms: Backoff) -> Self {
+        Self {
+            max_attempts,
+            backoff_ms,
+            jitter_ms: None,
+            retryable_codes: None,
+            on_retry: None,
+        }
+    }
+
+    /// Convenience for a fixed backoff schedule.
+    pub fn fixed(max_attempts: u32, backoff_ms: u64) -> Self {
+        Self::new(max_attempts, Backoff::Fixed(backoff_ms))
+    }
+
+    pub fn with_codes(mut self, codes: &[&'static str]) -> Self {
+        self.retryable_codes = Some(codes.to_vec());
+        self
+    }
+
+    pub fn with_jitter(mut self, jitter_ms: u64) -> Self {
+        self.jitter_ms = Some(jitter_ms);
+        self
+    }
+
+    pub fn with_on_retry(mut self, f: impl FnMut(&E, u32) + Send + 'static) -> Self {
+        self.on_retry = Some(Box::new(f));
+        self
+    }
+}
+
+impl<E> fmt::Debug for RetryOptions<E> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("RetryOptions")
+            .field("max_attempts", &self.max_attempts)
+            .field("backoff_ms", &self.backoff_ms)
+            .field("jitter_ms", &self.jitter_ms)
+            .field("retryable_codes", &self.retryable_codes)
+            .field("on_retry", &self.on_retry.as_ref().map(|_| "FnMut(..)"))
+            .finish()
+    }
+}
+
+fn is_retryable_error<E: HasErrorCode>(
+    error: &E,
+    retryable_codes: Option<&[&'static str]>,
+) -> bool {
+    let Some(code) = error.error_code() else {
+        return false;
+    };
+    match retryable_codes {
+        Some(codes) => codes.contains(&code),
+        None => FILE_RETRY_CODES.contains(&code),
+    }
+}
+
+fn compute_delay_ms<E>(options: &RetryOptions<E>, failed_attempt: u32) -> u64 {
+    let base = options.backoff_ms.compute(failed_attempt);
+    let jitter = match options.jitter_ms {
+        Some(jitter_ms) if jitter_ms > 0 => rand::Rng::random_range(&mut rand::rng(), 0..jitter_ms),
+        _ => 0,
+    };
+    base.saturating_add(jitter)
+}
+
+// ---------------------------------------------------------------------------
+// Retry engines
+// ---------------------------------------------------------------------------
+
+/// Run `operation`, retrying on transient error codes with a per-call backoff
+/// schedule. Non-retryable errors are returned immediately; once
+/// `max_attempts` is exhausted the error from the final attempt is returned
+/// unchanged. No delay is scheduled after the final attempt.
+pub async fn with_retry<T, E, F, Fut>(mut operation: F, mut options: RetryOptions<E>) -> Result<T, E>
+where
+    E: HasErrorCode,
+    F: FnMut() -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+{
+    let mut attempt: u32 = 1;
+    loop {
+        match operation().await {
+            Ok(value) => return Ok(value),
+            Err(error) => {
+                if !is_retryable_error(&error, options.retryable_codes.as_deref())
+                    || attempt >= options.max_attempts
+                {
+                    return Err(error);
+                }
+                if let Some(on_retry) = options.on_retry.as_mut() {
+                    on_retry(&error, attempt);
+                }
+                let delay_ms = compute_delay_ms(&options, attempt);
+                if delay_ms > 0 {
+                    tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+                }
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// Synchronous variant of [`with_retry`] for callers that cannot await.
+/// Positive delays use `std::thread::sleep` (the TS busy-wait is replaced per
+/// ARCHITECTURE.md §5.4); a computed delay of 0 retries immediately. Never
+/// call this inside async code — use [`with_retry`] there.
+pub fn with_retry_sync<T, E, F>(mut operation: F, mut options: RetryOptions<E>) -> Result<T, E>
+where
+    E: HasErrorCode,
+    F: FnMut() -> Result<T, E>,
+{
+    let mut attempt: u32 = 1;
+    loop {
+        match operation() {
+            Ok(value) => return Ok(value),
+            Err(error) => {
+                if !is_retryable_error(&error, options.retryable_codes.as_deref())
+                    || attempt >= options.max_attempts
+                {
+                    return Err(error);
+                }
+                if let Some(on_retry) = options.on_retry.as_mut() {
+                    on_retry(&error, attempt);
+                }
+                let delay_ms = compute_delay_ms(&options, attempt);
+                if delay_ms > 0 {
+                    std::thread::sleep(Duration::from_millis(delay_ms));
+                }
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// The canned shared file-operation policy: 6 attempts, 25 ms exponential
+/// backoff (25/50/100/200/400) plus 0–19 ms jitter, retrying only
+/// [`FILE_RETRY_CODES`].
+pub async fn with_file_operation_retry<T, E, F, Fut>(operation: F) -> Result<T, E>
+where
+    E: HasErrorCode,
+    F: FnMut() -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+{
+    with_retry(
+        operation,
+        RetryOptions {
+            max_attempts: FILE_RETRY_MAX_ATTEMPTS,
+            backoff_ms: Backoff::from_fn(|attempt| {
+                FILE_RETRY_BASE_DELAY_MS
+                    .saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+            }),
+            jitter_ms: Some(FILE_RETRY_JITTER_MS),
+            retryable_codes: Some(FILE_RETRY_CODES.to_vec()),
+            on_retry: None,
+        },
+    )
+    .await
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/fs-retry.test.ts)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::Cell;
+    use std::sync::atomic::{AtomicU32, Ordering};
+    use std::sync::{Arc, Mutex};
+
+    fn errno_error(code: &'static str) -> io::Error {
+        io_error_with_code(code, code)
+    }
+
+    #[tokio::test]
+    async fn returns_result_on_first_try_success_without_retrying() {
+        let calls = AtomicU32::new(0);
+        let result: Result<&str, io::Error> = with_retry(
+            || {
+                calls.fetch_add(1, Ordering::SeqCst);
+                async { Ok("ok") }
+            },
+            RetryOptions::fixed(5, 10),
+        )
+        .await;
+        assert_eq!(result.unwrap(), "ok");
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn retries_retryable_codes_and_resolves_once_operation_succeeds() {
+        let calls = AtomicU32::new(0);
+        let result: Result<&str, io::Error> = with_retry(
+            || {
+                let n = calls.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    match n {
+                        0 => Err(errno_error("EBUSY")),
+                        1 => Err(errno_error("EPERM")),
+                        _ => Ok("done"),
+                    }
+                }
+            },
+            RetryOptions::fixed(5, 0),
+        )
+        .await;
+        assert_eq!(result.unwrap(), "done");
+        assert_eq!(calls.load(Ordering::SeqCst), 3);
+    }
+
+    #[tokio::test]
+    async fn rethrows_last_error_once_max_attempts_is_exhausted() {
+        let calls = AtomicU32::new(0);
+        let result: Result<(), io::Error> = with_retry(
+            || {
+                let n = calls.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    match n {
+                        0 => Err(io_error_with_code("EBUSY", "first failure")),
+                        1 => Err(io_error_with_code("EBUSY", "middle failure")),
+                        _ => Err(io_error_with_code("EPERM", "last failure")),
+                    }
+                }
+            },
+            RetryOptions::fixed(3, 0),
+        )
+        .await;
+        let error = result.unwrap_err();
+        assert_eq!(code_of(&error), Some("EPERM"));
+        assert!(error.to_string().contains("last failure"));
+        assert_eq!(calls.load(Ordering::SeqCst), 3);
+    }
+
+    #[tokio::test]
+    async fn throws_immediately_on_a_non_retryable_code() {
+        let calls = AtomicU32::new(0);
+        let result: Result<(), io::Error> = with_retry(
+            || {
+                calls.fetch_add(1, Ordering::SeqCst);
+                async { Err(errno_error("ENOENT")) }
+            },
+            RetryOptions::fixed(5, 10),
+        )
+        .await;
+        assert_eq!(code_of(&result.unwrap_err()), Some("ENOENT"));
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn throws_immediately_on_errors_without_a_code() {
+        let calls = AtomicU32::new(0);
+        let result: Result<(), io::Error> = with_retry(
+            || {
+                calls.fetch_add(1, Ordering::SeqCst);
+                async { Err(io::Error::other("no code at all")) }
+            },
+            RetryOptions::fixed(5, 10),
+        )
+        .await;
+        let error = result.unwrap_err();
+        assert_eq!(code_of(&error), None);
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn honors_custom_retryable_codes_and_rejects_default_codes() {
+        // EBUSY is NOT retryable when the per-site set is ["ESTALE"].
+        let calls = AtomicU32::new(0);
+        let result: Result<(), io::Error> = with_retry(
+            || {
+                calls.fetch_add(1, Ordering::SeqCst);
+                async { Err(errno_error("EBUSY")) }
+            },
+            RetryOptions::fixed(5, 0).with_codes(&["ESTALE"]),
+        )
+        .await;
+        assert_eq!(code_of(&result.unwrap_err()), Some("EBUSY"));
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+
+        // ESTALE recovers.
+        let calls = AtomicU32::new(0);
+        let result: Result<&str, io::Error> = with_retry(
+            || {
+                let n = calls.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    if n == 0 {
+                        Err(errno_error("ESTALE"))
+                    } else {
+                        Ok("recovered")
+                    }
+                }
+            },
+            RetryOptions::fixed(3, 0).with_codes(&["ESTALE"]),
+        )
+        .await;
+        assert_eq!(result.unwrap(), "recovered");
+        assert_eq!(calls.load(Ordering::SeqCst), 2);
+    }
+
+    #[tokio::test]
+    async fn defaults_retryable_codes_to_file_retry_codes() {
+        for code in FILE_RETRY_CODES {
+            let calls = AtomicU32::new(0);
+            let result: Result<&str, io::Error> = with_retry(
+                || {
+                    let n = calls.fetch_add(1, Ordering::SeqCst);
+                    async move {
+                        if n == 0 {
+                            Err(io_error_with_code(code, *code))
+                        } else {
+                            Ok("ok")
+                        }
+                    }
+                },
+                RetryOptions::fixed(2, 0),
+            )
+            .await;
+            assert_eq!(result.unwrap(), "ok", "code {code}");
+            assert_eq!(calls.load(Ordering::SeqCst), 2, "code {code}");
+        }
+    }
+
+    #[tokio::test]
+    async fn invokes_on_retry_for_each_retryable_failure_but_not_the_final_one() {
+        let calls = AtomicU32::new(0);
+        let seen: Arc<Mutex<Vec<(String, u32)>>> = Arc::new(Mutex::new(Vec::new()));
+        let seen_cb = Arc::clone(&seen);
+        let result: Result<(), io::Error> = with_retry(
+            || {
+                let n = calls.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    match n {
+                        0 => Err(io_error_with_code("EBUSY", "first")),
+                        1 => Err(io_error_with_code("EPERM", "second")),
+                        _ => Err(io_error_with_code("EACCES", "last")),
+                    }
+                }
+            },
+            RetryOptions::fixed(3, 0).with_on_retry(move |error: &io::Error, attempt| {
+                seen_cb
+                    .lock()
+                    .unwrap()
+                    .push((code_of(error).unwrap_or("?").to_string(), attempt));
+            }),
+        )
+        .await;
+        assert_eq!(code_of(&result.unwrap_err()), Some("EACCES"));
+        let seen = seen.lock().unwrap();
+        assert_eq!(
+            *seen,
+            vec![("EBUSY".to_string(), 1), ("EPERM".to_string(), 2)]
+        );
+    }
+
+    #[test]
+    fn sync_returns_result_on_first_try_success() {
+        let calls = Cell::new(0u32);
+        let result: Result<i32, io::Error> = with_retry_sync(
+            || {
+                calls.set(calls.get() + 1);
+                Ok(42)
+            },
+            RetryOptions::fixed(4, 0),
+        );
+        assert_eq!(result.unwrap(), 42);
+        assert_eq!(calls.get(), 1);
+    }
+
+    #[test]
+    fn sync_retries_retryable_code_and_returns_once_operation_succeeds() {
+        let calls = Cell::new(0u32);
+        let result: Result<&str, io::Error> = with_retry_sync(
+            || {
+                calls.set(calls.get() + 1);
+                if calls.get() == 1 {
+                    Err(errno_error("EBUSY"))
+                } else {
+                    Ok("done")
+                }
+            },
+            RetryOptions::fixed(4, 1).with_codes(&["EBUSY"]),
+        );
+        assert_eq!(result.unwrap(), "done");
+        assert_eq!(calls.get(), 2);
+    }
+
+    #[test]
+    fn sync_rethrows_last_error_once_max_attempts_is_exhausted() {
+        let calls = Cell::new(0u32);
+        let result: Result<(), io::Error> = with_retry_sync(
+            || {
+                calls.set(calls.get() + 1);
+                Err(io_error_with_code("EPERM", "still locked"))
+            },
+            RetryOptions::fixed(4, 0),
+        );
+        let error = result.unwrap_err();
+        assert_eq!(code_of(&error), Some("EPERM"));
+        assert!(error.to_string().contains("still locked"));
+        assert_eq!(calls.get(), 4);
+    }
+
+    #[test]
+    fn sync_throws_immediately_on_a_non_retryable_code() {
+        let calls = Cell::new(0u32);
+        let result: Result<(), io::Error> = with_retry_sync(
+            || {
+                calls.set(calls.get() + 1);
+                Err(errno_error("ENOENT"))
+            },
+            RetryOptions::fixed(4, 0),
+        );
+        assert_eq!(code_of(&result.unwrap_err()), Some("ENOENT"));
+        assert_eq!(calls.get(), 1);
+    }
+
+    #[test]
+    fn sync_invokes_on_retry_with_failure_and_one_based_attempt_index() {
+        let calls = Cell::new(0u32);
+        let seen: Arc<Mutex<Vec<u32>>> = Arc::new(Mutex::new(Vec::new()));
+        let seen_cb = Arc::clone(&seen);
+        let result: Result<&str, io::Error> = with_retry_sync(
+            || {
+                calls.set(calls.get() + 1);
+                if calls.get() == 1 {
+                    Err(errno_error("EBUSY"))
+                } else {
+                    Ok("ok")
+                }
+            },
+            RetryOptions::fixed(2, 0).with_on_retry(move |_error: &io::Error, attempt| {
+                seen_cb.lock().unwrap().push(attempt);
+            }),
+        );
+        assert_eq!(result.unwrap(), "ok");
+        assert_eq!(*seen.lock().unwrap(), vec![1]);
+    }
+
+    #[tokio::test]
+    async fn file_operation_retry_makes_six_attempts_on_persistent_busy() {
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_op = Arc::clone(&calls);
+        let result: Result<(), io::Error> = with_file_operation_retry(move || {
+            calls_op.fetch_add(1, Ordering::SeqCst);
+            async { Err(io_error_with_code("EBUSY", "always locked")) }
+        })
+        .await;
+        let error = result.unwrap_err();
+        assert_eq!(code_of(&error), Some("EBUSY"));
+        assert!(error.to_string().contains("always locked"));
+        assert_eq!(calls.load(Ordering::SeqCst), 6);
+    }
+
+    #[tokio::test]
+    async fn file_operation_retry_throws_immediately_on_non_retryable_code() {
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_op = Arc::clone(&calls);
+        let result: Result<(), io::Error> = with_file_operation_retry(move || {
+            calls_op.fetch_add(1, Ordering::SeqCst);
+            async { Err(errno_error("ENOENT")) }
+        })
+        .await;
+        assert_eq!(code_of(&result.unwrap_err()), Some("ENOENT"));
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[test]
+    fn treats_every_transient_lock_code_as_retryable() {
+        for code in ["EBUSY", "EPERM", "EAGAIN", "ENOTEMPTY", "EACCES"] {
+            let stable = FILE_RETRY_CODES
+                .iter()
+                .copied()
+                .find(|c| *c == code)
+                .expect("code present in FILE_RETRY_CODES");
+            let error = io_error_with_code(stable, code);
+            assert!(should_retry_file_operation(&error), "{code}");
+        }
+    }
+
+    #[test]
+    fn does_not_retry_non_transient_errors() {
+        for code in ["ENOENT", "EISDIR", "EINVAL", "EROFS"] {
+            let stable: &'static str = match code {
+                "ENOENT" => "ENOENT",
+                "EISDIR" => "EISDIR",
+                "EINVAL" => "EINVAL",
+                _ => "EROFS",
+            };
+            let error = io_error_with_code(stable, code);
+            assert!(!should_retry_file_operation(&error), "{code}");
+        }
+    }
+
+    #[test]
+    fn returns_false_for_errors_without_a_code() {
+        let error = io::Error::other("no code");
+        assert!(!should_retry_file_operation(&error));
+    }
+
+    #[test]
+    fn code_of_prefers_embedded_coded_error_payload() {
+        let error = io_error_with_code("ESTALE", "settings changed on disk");
+        assert_eq!(code_of(&error), Some("ESTALE"));
+    }
+
+    #[test]
+    fn code_of_falls_back_to_error_kind_for_custom_errors() {
+        assert_eq!(
+            code_of(&io::Error::new(io::ErrorKind::NotFound, "gone")),
+            Some("ENOENT")
+        );
+        assert_eq!(
+            code_of(&io::Error::new(io::ErrorKind::AlreadyExists, "there")),
+            Some("EEXIST")
+        );
+        assert_eq!(code_of(&io::Error::other("mystery")), None);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn code_of_maps_windows_raw_os_errors_to_node_codes() {
+        // ERROR_SHARING_VIOLATION / ERROR_LOCK_VIOLATION -> EBUSY
+        assert_eq!(code_of(&io::Error::from_raw_os_error(32)), Some("EBUSY"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(33)), Some("EBUSY"));
+        // ERROR_ACCESS_DENIED -> EPERM (libuv/Node parity)
+        assert_eq!(code_of(&io::Error::from_raw_os_error(5)), Some("EPERM"));
+        // ERROR_FILE_NOT_FOUND / ERROR_PATH_NOT_FOUND -> ENOENT
+        assert_eq!(code_of(&io::Error::from_raw_os_error(2)), Some("ENOENT"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(3)), Some("ENOENT"));
+        // ERROR_DIR_NOT_EMPTY -> ENOTEMPTY
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(145)),
+            Some("ENOTEMPTY")
+        );
+        // ERROR_ALREADY_EXISTS -> EEXIST
+        assert_eq!(code_of(&io::Error::from_raw_os_error(183)), Some("EEXIST"));
+        // ERROR_CANT_ACCESS_FILE -> EACCES
+        assert_eq!(code_of(&io::Error::from_raw_os_error(1920)), Some("EACCES"));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn code_of_maps_unix_errnos_to_node_codes() {
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::EBUSY)),
+            Some("EBUSY")
+        );
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::EPERM)),
+            Some("EPERM")
+        );
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::EACCES)),
+            Some("EACCES")
+        );
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::ENOTEMPTY)),
+            Some("ENOTEMPTY")
+        );
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::ENOENT)),
+            Some("ENOENT")
+        );
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(libc::ESTALE)),
+            Some("ESTALE")
+        );
+    }
+}
diff --git a/crates/core/src/json_io.rs b/crates/core/src/json_io.rs
new file mode 100644
index 000000000..bc3543286
--- /dev/null
+++ b/crates/core/src/json_io.rs
@@ -0,0 +1,1035 @@
+//! THE byte-compat chokepoint for all persisted JSON (ARCHITECTURE.md §8.1).
+//!
+//! Every persisted-JSON write in the workspace goes through this module —
+//! never `serde_json::to_string*` directly in feature code. Guarantees:
+//!
+//! - [`stringify_pretty2`] is byte-identical to `JSON.stringify(x, null, 2)`:
+//!   2-space indent, `": "` after keys, `,\n` separators, `{}`/`[]` for empty
+//!   containers, non-ASCII left unescaped, control chars escaped exactly like
+//!   V8 (`\b \t \n \f \r` short forms, lowercase `\u00xx` otherwise), and —
+//!   crucially — ECMAScript `Number::toString` float formatting (`5.0` → `5`,
+//!   `1e21` → `"1e+21"`, `1e-7` → `"1e-7"`, `1e-6` → `"0.000001"`), which the
+//!   default ryu-based serde_json output does NOT match.
+//! - [`stringify_compact`] == `JSON.stringify(x)`.
+//! - [`stringify_pretty_tab`] == `JSON.stringify(x, null, "\t")` (Codex.json).
+//! - [`write_json_atomic`]/[`write_json_atomic_sync`] implement the shared
+//!   write protocol: optional `.bak` snapshot (retry EBUSY/EPERM ×5, async
+//!   delays 10/20/40/80 ms, silent give-up), staging via
+//!   [`crate::temp_path::temp_path_for`], optional mode 0600 applied
+//!   atomically at open(2) on unix (Node parity: no chmod window), optional
+//!   mtime CAS (mismatch → `"ESTALE"`-coded error), atomic rename with
+//!   per-site retry (EBUSY/EPERM ×5), best-effort temp unlink on failure.
+//! - Trailing-newline matrix is expressed via [`TrailingNewline`] (accounts /
+//!   settings YES; request-logs / runtime-observability / update-cache NO).
+//! - [`strip_utf8_bom`] strips a leading U+FEFF before parsing (Windows
+//!   editors), matching the TS `stripUtf8Bom` used on every config read.
+//!
+//! Key order: `serde_json` is built with `preserve_order`, so object key
+//! order round-trips insertion order and structs serialize in declaration
+//! order — matching V8 property-insertion order semantics.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+use serde::Serialize;
+use serde_json::ser::{CompactFormatter, Formatter, PrettyFormatter, Serializer};
+
+use crate::fs_retry::{Backoff, RetryOptions, io_error_with_code, with_retry, with_retry_sync};
+use crate::temp_path::temp_path_for;
+
+// ---------------------------------------------------------------------------
+// ECMAScript number formatting
+// ---------------------------------------------------------------------------
+
+/// Format an `f64` exactly like ECMAScript `Number::toString(10)` (the number
+/// formatting used by `JSON.stringify` and `String(n)`).
+///
+/// Also handles non-finite values (`"NaN"`, `"Infinity"`, `"-Infinity"`) for
+/// callers like the config explain-report normalization; note that inside
+/// JSON serialization non-finite floats become `null` (serde_json emits
+/// `write_null` for them, matching `JSON.stringify(NaN) === "null"`).
+pub fn format_js_number(value: f64) -> String {
+    if value.is_nan() {
+        return "NaN".to_string();
+    }
+    if value.is_infinite() {
+        return if value > 0.0 { "Infinity" } else { "-Infinity" }.to_string();
+    }
+    if value == 0.0 {
+        // Covers -0.0: String(-0) === "0" in JS (and JSON.stringify(-0) === "0"...
+        // actually V8 prints "0" via ToString; JSON.stringify(-0) is "0" too).
+        return "0".to_string();
+    }
+
+    let negative = value < 0.0;
+    let abs = value.abs();
+
+    // Rust's `{:e}` prints the shortest round-trip mantissa (no trailing
+    // zeros, single nonzero leading digit) with a decimal exponent — exactly
+    // the (s, k, n) decomposition ECMA-262 §6.1.6.1.20 needs.
+    let exp_repr = format!("{abs:e}");
+    let (mantissa, exp_part) = exp_repr
+        .split_once('e')
+        .expect("{:e} always contains an exponent");
+    let exponent: i32 = exp_part.parse().expect("{:e} exponent is an integer");
+    let digits: String = mantissa.chars().filter(|c| *c != '.').collect();
+    let n = digits.len() as i32;
+    // value = 0.<digits> * 10^k
+    let k = exponent + 1;
+
+    let body = if n <= k && k <= 21 {
+        // Integer with trailing zeros.
+        let mut s = digits.clone();
+        for _ in 0..(k - n) {
+            s.push('0');
+        }
+        s
+    } else if 0 < k && k <= 21 {
+        // Decimal point inside the digits.
+        let (int_part, frac_part) = digits.split_at(k as usize);
+        format!("{int_part}.{frac_part}")
+    } else if -6 < k && k <= 0 {
+        // 0.000ddd form.
+        let mut s = String::from("0.");
+        for _ in 0..(-k) {
+            s.push('0');
+        }
+        s.push_str(&digits);
+        s
+    } else {
+        // Exponential notation: d[.ddd]e±E where E = k - 1 (with explicit '+').
+        let e = k - 1;
+        let mantissa_out = if digits.len() == 1 {
+            digits.clone()
+        } else {
+            format!("{}.{}", &digits[..1], &digits[1..])
+        };
+        if e >= 0 {
+            format!("{mantissa_out}e+{e}")
+        } else {
+            format!("{mantissa_out}e-{}", -e)
+        }
+    };
+
+    if negative { format!("-{body}") } else { body }
+}
+
+// ---------------------------------------------------------------------------
+// Formatters (serde_json formatter overrides for JS float output)
+// ---------------------------------------------------------------------------
+
+struct JsPrettyFormatter<'a> {
+    inner: PrettyFormatter<'a>,
+}
+
+impl<'a> JsPrettyFormatter<'a> {
+    fn with_indent(indent: &'a [u8]) -> Self {
+        Self {
+            inner: PrettyFormatter::with_indent(indent),
+        }
+    }
+}
+
+macro_rules! delegate_structural {
+    ($inner:ident) => {
+        fn begin_array<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.begin_array(writer)
+        }
+
+        fn end_array<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.end_array(writer)
+        }
+
+        fn begin_array_value<W>(&mut self, writer: &mut W, first: bool) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.begin_array_value(writer, first)
+        }
+
+        fn end_array_value<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.end_array_value(writer)
+        }
+
+        fn begin_object<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.begin_object(writer)
+        }
+
+        fn end_object<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.end_object(writer)
+        }
+
+        fn begin_object_key<W>(&mut self, writer: &mut W, first: bool) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.begin_object_key(writer, first)
+        }
+
+        fn begin_object_value<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.begin_object_value(writer)
+        }
+
+        fn end_object_value<W>(&mut self, writer: &mut W) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            self.$inner.end_object_value(writer)
+        }
+    };
+}
+
+macro_rules! js_float_writes {
+    () => {
+        fn write_f32<W>(&mut self, writer: &mut W, value: f32) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            // JS has only doubles; format the f32's exact double value.
+            writer.write_all(format_js_number(f64::from(value)).as_bytes())
+        }
+
+        fn write_f64<W>(&mut self, writer: &mut W, value: f64) -> io::Result<()>
+        where
+            W: ?Sized + io::Write,
+        {
+            writer.write_all(format_js_number(value).as_bytes())
+        }
+    };
+}
+
+impl Formatter for JsPrettyFormatter<'_> {
+    delegate_structural!(inner);
+    js_float_writes!();
+}
+
+struct JsCompactFormatter;
+
+impl Formatter for JsCompactFormatter {
+    js_float_writes!();
+}
+
+// CompactFormatter is used only to prove the default-structural parity in
+// tests; suppress the unused warning path by referencing it.
+#[allow(dead_code)]
+fn _assert_compact_exists() -> CompactFormatter {
+    CompactFormatter
+}
+
+fn serialize_with_formatter<T, F>(value: &T, formatter: F) -> Result<String, serde_json::Error>
+where
+    T: ?Sized + Serialize,
+    F: Formatter,
+{
+    let mut out: Vec<u8> = Vec::with_capacity(128);
+    let mut ser = Serializer::with_formatter(&mut out, formatter);
+    value.serialize(&mut ser)?;
+    Ok(String::from_utf8(out).expect("serde_json output is always valid UTF-8"))
+}
+
+// ---------------------------------------------------------------------------
+// stringify_*
+// ---------------------------------------------------------------------------
+
+/// `JSON.stringify(value, null, 2)` — byte-exact. Panics on serialization
+/// failure (only possible for exotic types like maps with non-string keys;
+/// `serde_json::Value` and all persisted-format structs never fail). Use
+/// [`try_stringify_pretty2`] where the caller wants to handle the error.
+pub fn stringify_pretty2<T: ?Sized + Serialize>(value: &T) -> String {
+    try_stringify_pretty2(value).expect("JSON serialization failed")
+}
+
+/// Fallible variant of [`stringify_pretty2`].
+pub fn try_stringify_pretty2<T: ?Sized + Serialize>(value: &T) -> Result<String, serde_json::Error> {
+    serialize_with_formatter(value, JsPrettyFormatter::with_indent(b"  "))
+}
+
+/// `JSON.stringify(value, null, "\t")` — TAB indent (Codex.json,
+/// first-run-setup marker).
+pub fn stringify_pretty_tab<T: ?Sized + Serialize>(value: &T) -> String {
+    try_stringify_pretty_tab(value).expect("JSON serialization failed")
+}
+
+/// Fallible variant of [`stringify_pretty_tab`].
+pub fn try_stringify_pretty_tab<T: ?Sized + Serialize>(
+    value: &T,
+) -> Result<String, serde_json::Error> {
+    serialize_with_formatter(value, JsPrettyFormatter::with_indent(b"\t"))
+}
+
+/// `JSON.stringify(value)` — compact, no whitespace.
+pub fn stringify_compact<T: ?Sized + Serialize>(value: &T) -> String {
+    try_stringify_compact(value).expect("JSON serialization failed")
+}
+
+/// Fallible variant of [`stringify_compact`].
+pub fn try_stringify_compact<T: ?Sized + Serialize>(
+    value: &T,
+) -> Result<String, serde_json::Error> {
+    serialize_with_formatter(value, JsCompactFormatter)
+}
+
+// ---------------------------------------------------------------------------
+// Reading helpers
+// ---------------------------------------------------------------------------
+
+/// Strip a single leading UTF-8 BOM (U+FEFF), matching the TS `stripUtf8Bom`
+/// applied before every config-file `JSON.parse` (Windows editors add it).
+pub fn strip_utf8_bom(raw: &str) -> &str {
+    raw.strip_prefix('\u{feff}').unwrap_or(raw)
+}
+
+/// Error from [`read_json_file`], distinguishing IO failures from JSON syntax
+/// errors — storage's load ladder propagates SyntaxError but treats schema
+/// errors separately, so callers need the split.
+#[derive(Debug)]
+pub enum ReadJsonError {
+    Io(io::Error),
+    Parse(serde_json::Error),
+}
+
+impl ReadJsonError {
+    /// True when the underlying failure is file-not-found.
+    pub fn is_not_found(&self) -> bool {
+        matches!(self, ReadJsonError::Io(e) if e.kind() == io::ErrorKind::NotFound)
+    }
+
+    pub fn as_io(&self) -> Option<&io::Error> {
+        match self {
+            ReadJsonError::Io(e) => Some(e),
+            ReadJsonError::Parse(_) => None,
+        }
+    }
+}
+
+impl std::fmt::Display for ReadJsonError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ReadJsonError::Io(e) => write!(f, "{e}"),
+            ReadJsonError::Parse(e) => write!(f, "{e}"),
+        }
+    }
+}
+
+impl std::error::Error for ReadJsonError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ReadJsonError::Io(e) => Some(e),
+            ReadJsonError::Parse(e) => Some(e),
+        }
+    }
+}
+
+/// Read a file as (lossy) UTF-8 text — Node's `readFileSync(p, "utf-8")` is
+/// lossy on invalid sequences, so this uses `from_utf8_lossy` rather than
+/// failing.
+pub fn read_text_file(path: &Path) -> io::Result<String> {
+    let bytes = fs::read(path)?;
+    Ok(String::from_utf8_lossy(&bytes).into_owned())
+}
+
+/// Read + BOM-strip + parse a JSON file into a [`serde_json::Value`]
+/// (preserving key order).
+pub fn read_json_file(path: &Path) -> Result<serde_json::Value, ReadJsonError> {
+    read_json_file_as(path)
+}
+
+/// Read + BOM-strip + parse a JSON file into any deserializable type.
+pub fn read_json_file_as<T: serde::de::DeserializeOwned>(
+    path: &Path,
+) -> Result<T, ReadJsonError> {
+    let raw = read_text_file(path).map_err(ReadJsonError::Io)?;
+    serde_json::from_str(strip_utf8_bom(&raw)).map_err(ReadJsonError::Parse)
+}
+
+/// Millisecond mtime of `path` as a float (Node `stats.mtimeMs`); `Ok(None)`
+/// when the file does not exist. Used for the mtime-CAS write option.
+pub fn file_mtime_ms(path: &Path) -> io::Result<Option<f64>> {
+    match fs::metadata(path) {
+        Ok(meta) => {
+            let modified = meta.modified()?;
+            let ms = match modified.duration_since(UNIX_EPOCH) {
+                Ok(d) => d.as_secs_f64() * 1000.0,
+                // Pre-epoch mtimes (clock weirdness): negative ms like Node.
+                Err(e) => -(e.duration().as_secs_f64() * 1000.0),
+            };
+            Ok(Some(ms))
+        }
+        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(None),
+        Err(e) => Err(e),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Atomic writes
+// ---------------------------------------------------------------------------
+
+/// Trailing-newline matrix entry (per-file-type): accounts/settings files end
+/// with `"\n"`; request logs, runtime-observability, update-check-cache do
+/// not.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TrailingNewline {
+    /// No trailing newline appended.
+    None,
+    /// A single `"\n"` appended after the serialized content.
+    Lf,
+}
+
+/// Compare-and-swap on the destination's mtime, mirroring the TS unified
+/// settings / env-path config save protocol: stat the target just before the
+/// rename; `expected_mtime_ms = None` means "expected missing"; any mismatch
+/// aborts with an `"ESTALE"`-coded error carrying `stale_message` so the
+/// caller's CAS loop can re-read and retry.
+#[derive(Debug, Clone)]
+pub struct MtimeCas {
+    pub expected_mtime_ms: Option<f64>,
+    pub stale_message: String,
+}
+
+/// Pre-write `.bak` snapshot options. The copy is best-effort: retried on
+/// EBUSY/EPERM up to 5 attempts (async delays 10/20/40/80 ms; sync retries
+/// immediately) and given up silently — a failed backup never blocks the
+/// write. Skipped when the source file does not exist. Callers that recovered
+/// state from the backup itself must OMIT this option (spec 01 gotcha 10).
+#[derive(Debug, Clone)]
+pub struct BackupOptions {
+    pub backup_path: PathBuf,
+}
+
+/// Options for [`write_json_atomic`] / [`write_json_atomic_sync`].
+#[derive(Debug)]
+pub struct WriteJsonOptions {
+    pub trailing_newline: TrailingNewline,
+    pub mtime_cas: Option<MtimeCas>,
+    pub backup: Option<BackupOptions>,
+    /// fsync the staged temp file before rename (local-client-tokens style).
+    pub fsync: bool,
+    /// Create the parent directory (recursively) before staging.
+    pub ensure_parent_dir: bool,
+    /// Mode for created parent directories (unix only; typically 0o700).
+    pub parent_dir_mode: Option<u32>,
+    /// Rename attempts (retrying EBUSY/EPERM). Default 5, matching the shared
+    /// TS protocol; per-site overrides allowed.
+    pub rename_max_attempts: u32,
+}
+
+impl Default for WriteJsonOptions {
+    fn default() -> Self {
+        Self {
+            trailing_newline: TrailingNewline::Lf,
+            mtime_cas: None,
+            backup: None,
+            fsync: false,
+            ensure_parent_dir: false,
+            parent_dir_mode: None,
+            rename_max_attempts: 5,
+        }
+    }
+}
+
+const WRITE_RETRY_CODES: &[&str] = &["EBUSY", "EPERM"];
+
+fn backup_retry_backoff() -> Backoff {
+    // 10 * 2^(n-1) for the 1-based failed-attempt index → 10/20/40/80 ms.
+    Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1))))
+}
+
+fn apply_payload(content: &str, trailing_newline: TrailingNewline) -> String {
+    match trailing_newline {
+        TrailingNewline::None => content.to_string(),
+        TrailingNewline::Lf => format!("{content}\n"),
+    }
+}
+
+fn ensure_parent_dir(path: &Path, mode: Option<u32>) -> io::Result<()> {
+    let Some(parent) = path.parent() else {
+        return Ok(());
+    };
+    if parent.as_os_str().is_empty() {
+        return Ok(());
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        let mut builder = fs::DirBuilder::new();
+        builder.recursive(true);
+        if let Some(mode) = mode {
+            builder.mode(mode);
+        }
+        return builder.create(parent);
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = mode; // file modes are a no-op on Windows (Node parity)
+        fs::create_dir_all(parent)
+    }
+}
+
+/// Node `fs.writeFile(path, content, { mode })` parity: create/truncate and
+/// write with `mode` applied atomically at open(2) (`O_CREAT`) on unix, so a
+/// secret-bearing file NEVER exists with broader permissions — there is no
+/// write-then-chmod window and no world-readable crash residue. Like Node,
+/// the mode only takes effect when the open actually CREATES the file; a
+/// pre-existing file keeps its permissions. Mode is a no-op on Windows.
+pub fn write_text_file_with_mode_sync(
+    path: &Path,
+    content: &str,
+    mode: Option<u32>,
+) -> io::Result<()> {
+    let mut options = fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    if let Some(mode) = mode {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(mode);
+    }
+    #[cfg(not(unix))]
+    let _ = mode; // no-op on Windows (Node parity)
+    let mut file = options.open(path)?;
+    io::Write::write_all(&mut file, content.as_bytes())
+}
+
+fn stage_temp_file(path: &Path, payload: &str, mode: Option<u32>, fsync: bool) -> io::Result<PathBuf> {
+    let temp = temp_path_for(path);
+    if let Err(error) = write_text_file_with_mode_sync(&temp, payload, mode) {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+    if fsync {
+        let sync_result = fs::OpenOptions::new()
+            .write(true)
+            .open(&temp)
+            .and_then(|f| f.sync_all());
+        if let Err(error) = sync_result {
+            let _ = fs::remove_file(&temp);
+            return Err(error);
+        }
+    }
+    Ok(temp)
+}
+
+fn check_mtime_cas(path: &Path, cas: &MtimeCas) -> io::Result<()> {
+    let actual = file_mtime_ms(path)?;
+    if actual != cas.expected_mtime_ms {
+        return Err(io_error_with_code("ESTALE", cas.stale_message.clone()));
+    }
+    Ok(())
+}
+
+/// Atomically write `content` (a pre-serialized JSON string, typically from
+/// [`stringify_pretty2`]) to `path` via the shared temp+rename protocol.
+///
+/// `mode` is the file mode for the destination (e.g. `0o600`); applied on
+/// unix, a no-op on Windows (Node parity). See [`WriteJsonOptions`] for the
+/// backup / mtime-CAS / trailing-newline knobs. Retry delays use tokio time.
+pub async fn write_json_atomic(
+    path: &Path,
+    content: &str,
+    mode: Option<u32>,
+    options: &WriteJsonOptions,
+) -> io::Result<()> {
+    if options.ensure_parent_dir {
+        ensure_parent_dir(path, options.parent_dir_mode)?;
+    }
+
+    if let Some(backup) = &options.backup
+        && fs::metadata(path).is_ok()
+    {
+        let backup_path = backup.backup_path.clone();
+        let source = path.to_path_buf();
+        // Best-effort snapshot: retry EBUSY/EPERM ×5, then give up silently.
+        let _ = with_retry(
+            || {
+                let source = source.clone();
+                let backup_path = backup_path.clone();
+                async move { fs::copy(&source, &backup_path).map(|_| ()) }
+            },
+            RetryOptions::<io::Error>::new(5, backup_retry_backoff()).with_codes(WRITE_RETRY_CODES),
+        )
+        .await;
+    }
+
+    let payload = apply_payload(content, options.trailing_newline);
+    let temp = stage_temp_file(path, &payload, mode, options.fsync)?;
+
+    if let Some(cas) = &options.mtime_cas
+        && let Err(error) = check_mtime_cas(path, cas)
+    {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+
+    let rename_result = with_retry(
+        || {
+            let temp = temp.clone();
+            let path = path.to_path_buf();
+            async move { fs::rename(&temp, &path) }
+        },
+        RetryOptions::<io::Error>::new(options.rename_max_attempts.max(1), backup_retry_backoff())
+            .with_codes(WRITE_RETRY_CODES),
+    )
+    .await;
+
+    if let Err(error) = rename_result {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+    Ok(())
+}
+
+/// Synchronous variant of [`write_json_atomic`]. Retries are immediate (no
+/// sleeping), matching the TS sync writers which deliberately never block on
+/// timers (spec 01 §10.1).
+pub fn write_json_atomic_sync(
+    path: &Path,
+    content: &str,
+    mode: Option<u32>,
+    options: &WriteJsonOptions,
+) -> io::Result<()> {
+    if options.ensure_parent_dir {
+        ensure_parent_dir(path, options.parent_dir_mode)?;
+    }
+
+    if let Some(backup) = &options.backup
+        && fs::metadata(path).is_ok()
+    {
+        let _ = with_retry_sync(
+            || fs::copy(path, &backup.backup_path).map(|_| ()),
+            RetryOptions::<io::Error>::fixed(5, 0).with_codes(WRITE_RETRY_CODES),
+        );
+    }
+
+    let payload = apply_payload(content, options.trailing_newline);
+    let temp = stage_temp_file(path, &payload, mode, options.fsync)?;
+
+    if let Some(cas) = &options.mtime_cas
+        && let Err(error) = check_mtime_cas(path, cas)
+    {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+
+    let rename_result = with_retry_sync(
+        || fs::rename(&temp, path),
+        RetryOptions::<io::Error>::fixed(options.rename_max_attempts.max(1), 0)
+            .with_codes(WRITE_RETRY_CODES),
+    );
+
+    if let Err(error) = rename_result {
+        let _ = fs::remove_file(&temp);
+        return Err(error);
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::fs_retry::code_of;
+    use serde_json::json;
+
+    // ----- format_js_number: ECMAScript Number::toString parity -----
+
+    #[test]
+    fn format_js_number_matches_ecmascript_tostring() {
+        let cases: &[(f64, &str)] = &[
+            (0.0, "0"),
+            (-0.0, "0"),
+            (1.0, "1"),
+            (-1.5, "-1.5"),
+            (5.0, "5"),
+            (100.0, "100"),
+            (0.1, "0.1"),
+            (0.001, "0.001"),
+            (123.456, "123.456"),
+            (1234.5, "1234.5"),
+            (1e20, "100000000000000000000"),
+            (1e21, "1e+21"),
+            (2e21, "2e+21"),
+            (1.2e22, "1.2e+22"),
+            (1e-6, "0.000001"),
+            (1e-7, "1e-7"),
+            (1.5e-7, "1.5e-7"),
+            (-2.5e-10, "-2.5e-10"),
+            (9007199254740992.0, "9007199254740992"),
+            (f64::MAX, "1.7976931348623157e+308"),
+            (5e-324, "5e-324"),
+        ];
+        for (input, expected) in cases {
+            assert_eq!(&format_js_number(*input), expected, "input {input:?}");
+        }
+    }
+
+    #[test]
+    fn format_js_number_handles_non_finite_values() {
+        assert_eq!(format_js_number(f64::NAN), "NaN");
+        assert_eq!(format_js_number(f64::INFINITY), "Infinity");
+        assert_eq!(format_js_number(f64::NEG_INFINITY), "-Infinity");
+    }
+
+    // ----- stringify parity -----
+
+    #[test]
+    fn pretty2_formats_empty_containers_like_node() {
+        assert_eq!(stringify_pretty2(&json!({})), "{}");
+        assert_eq!(stringify_pretty2(&json!([])), "[]");
+        assert_eq!(stringify_pretty2(&json!(null)), "null");
+        assert_eq!(stringify_pretty2(&json!("x")), "\"x\"");
+        assert_eq!(stringify_pretty2(&json!(42)), "42");
+    }
+
+    #[test]
+    fn pretty2_matches_json_stringify_null_2_for_nested_values() {
+        let value = json!({
+            "name": "cma",
+            "nested": {
+                "empty": {},
+                "arr": [1, "two", { "deep": true }, []],
+                "nullv": null
+            },
+            "unicode": "héllo → 日本語 ✓"
+        });
+        // Verified against `JSON.stringify(value, null, 2)` in Node.
+        let expected = concat!(
+            "{\n",
+            "  \"name\": \"cma\",\n",
+            "  \"nested\": {\n",
+            "    \"empty\": {},\n",
+            "    \"arr\": [\n",
+            "      1,\n",
+            "      \"two\",\n",
+            "      {\n",
+            "        \"deep\": true\n",
+            "      },\n",
+            "      []\n",
+            "    ],\n",
+            "    \"nullv\": null\n",
+            "  },\n",
+            "  \"unicode\": \"héllo → 日本語 ✓\"\n",
+            "}"
+        );
+        assert_eq!(stringify_pretty2(&value), expected);
+    }
+
+    #[test]
+    fn pretty2_escapes_control_characters_exactly_like_v8() {
+        let value = json!({ "escapes": "line1\nline2\ttab \"q\" \\ \u{1}\u{1f}\u{7f}" });
+        // V8: \n and \t short escapes, 
/ lowercase 4-digit,
+        // U+007F NOT escaped, quote and backslash escaped.
+        let expected = concat!(
+            "{\n",
+            "  \"escapes\": \"line1\\nline2\\ttab \\\"q\\\" \\\\ \\u0001\\u001f\u{7f}\"\n",
+            "}"
+        );
+        assert_eq!(stringify_pretty2(&value), expected);
+    }
+
+    #[test]
+    fn pretty2_uses_js_float_formatting_inside_documents() {
+        let value = json!({ "big": 1e21, "whole": 5.0, "tiny": 1e-7, "frac": 0.1 });
+        let expected = concat!(
+            "{\n",
+            "  \"big\": 1e+21,\n",
+            "  \"whole\": 5,\n",
+            "  \"tiny\": 1e-7,\n",
+            "  \"frac\": 0.1\n",
+            "}"
+        );
+        assert_eq!(stringify_pretty2(&value), expected);
+    }
+
+    #[test]
+    fn compact_matches_json_stringify() {
+        let value = json!({ "a": 1, "b": [1, 2], "c": "x", "f": 2.5 });
+        assert_eq!(
+            stringify_compact(&value),
+            r#"{"a":1,"b":[1,2],"c":"x","f":2.5}"#
+        );
+    }
+
+    #[test]
+    fn pretty_tab_uses_tab_indentation() {
+        let value = json!({ "a": { "b": 1 } });
+        let expected = "{\n\t\"a\": {\n\t\t\"b\": 1\n\t}\n}";
+        assert_eq!(stringify_pretty_tab(&value), expected);
+    }
+
+    #[test]
+    fn key_order_round_trips_through_parse_and_stringify() {
+        let raw = r#"{"z":1,"a":{"y":2,"b":3},"m":[{"k2":1,"k1":2}]}"#;
+        let value: serde_json::Value = serde_json::from_str(raw).unwrap();
+        assert_eq!(stringify_compact(&value), raw);
+    }
+
+    #[test]
+    fn integers_print_without_decimal_point() {
+        let value = json!({ "epoch": 1750000000000i64, "neg": -12, "max": u64::MAX });
+        assert_eq!(
+            stringify_compact(&value),
+            format!(r#"{{"epoch":1750000000000,"neg":-12,"max":{}}}"#, u64::MAX)
+        );
+    }
+
+    // ----- strip_utf8_bom -----
+
+    #[test]
+    fn strips_a_single_leading_bom_only() {
+        assert_eq!(strip_utf8_bom("\u{feff}{\"a\":1}"), "{\"a\":1}");
+        assert_eq!(strip_utf8_bom("{\"a\":1}"), "{\"a\":1}");
+        assert_eq!(strip_utf8_bom("\u{feff}\u{feff}x"), "\u{feff}x");
+        assert_eq!(strip_utf8_bom(""), "");
+    }
+
+    // ----- read helpers -----
+
+    #[test]
+    fn read_json_file_strips_bom_and_preserves_key_order() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.json");
+        fs::write(&path, "\u{feff}{\"z\":1,\"a\":2}").unwrap();
+        let value = read_json_file(&path).unwrap();
+        assert_eq!(stringify_compact(&value), r#"{"z":1,"a":2}"#);
+    }
+
+    #[test]
+    fn read_json_file_distinguishes_io_from_parse_errors() {
+        let dir = tempfile::tempdir().unwrap();
+        let missing = read_json_file(&dir.path().join("missing.json")).unwrap_err();
+        assert!(missing.is_not_found());
+
+        let path = dir.path().join("broken.json");
+        fs::write(&path, "{ not json").unwrap();
+        let broken = read_json_file(&path).unwrap_err();
+        assert!(matches!(broken, ReadJsonError::Parse(_)));
+        assert!(!broken.is_not_found());
+    }
+
+    // ----- atomic writes -----
+
+    fn list_tmp_files(dir: &Path) -> Vec<String> {
+        fs::read_dir(dir)
+            .unwrap()
+            .filter_map(|e| e.ok())
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|name| name.ends_with(".tmp"))
+            .collect()
+    }
+
+    #[tokio::test]
+    async fn writes_content_with_trailing_newline_and_cleans_up_temp() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        let content = stringify_pretty2(&json!({ "version": 1 }));
+        write_json_atomic(&path, &content, Some(0o600), &WriteJsonOptions::default())
+            .await
+            .unwrap();
+        let written = fs::read_to_string(&path).unwrap();
+        assert_eq!(written, "{\n  \"version\": 1\n}\n");
+        assert!(list_tmp_files(dir.path()).is_empty());
+    }
+
+    #[tokio::test]
+    async fn honors_trailing_newline_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("runtime-observability.json");
+        let options = WriteJsonOptions {
+            trailing_newline: TrailingNewline::None,
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{}", Some(0o600), &options).await.unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{}");
+    }
+
+    #[tokio::test]
+    async fn snapshots_previous_content_to_backup_before_write() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        let bak = dir.path().join("settings.json.bak");
+        fs::write(&path, "old-content\n").unwrap();
+        let options = WriteJsonOptions {
+            backup: Some(BackupOptions {
+                backup_path: bak.clone(),
+            }),
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{\"new\":true}", None, &options)
+            .await
+            .unwrap();
+        assert_eq!(fs::read_to_string(&bak).unwrap(), "old-content\n");
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{\"new\":true}\n");
+    }
+
+    #[tokio::test]
+    async fn backup_is_skipped_when_target_missing() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        let bak = dir.path().join("settings.json.bak");
+        let options = WriteJsonOptions {
+            backup: Some(BackupOptions {
+                backup_path: bak.clone(),
+            }),
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{}", None, &options).await.unwrap();
+        assert!(!bak.exists());
+    }
+
+    #[tokio::test]
+    async fn mtime_cas_mismatch_yields_estale_and_leaves_target_untouched() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        fs::write(&path, "original").unwrap();
+        let options = WriteJsonOptions {
+            mtime_cas: Some(MtimeCas {
+                expected_mtime_ms: None, // expected missing, but the file exists
+                stale_message:
+                    "Unified settings changed on disk during save; retrying with latest state."
+                        .to_string(),
+            }),
+            ..Default::default()
+        };
+        let error = write_json_atomic(&path, "{}", None, &options)
+            .await
+            .unwrap_err();
+        assert_eq!(code_of(&error), Some("ESTALE"));
+        assert!(
+            error
+                .to_string()
+                .contains("Unified settings changed on disk during save")
+        );
+        assert_eq!(fs::read_to_string(&path).unwrap(), "original");
+        assert!(list_tmp_files(dir.path()).is_empty());
+    }
+
+    #[tokio::test]
+    async fn mtime_cas_match_allows_the_write() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        fs::write(&path, "original").unwrap();
+        let expected = file_mtime_ms(&path).unwrap();
+        assert!(expected.is_some());
+        let options = WriteJsonOptions {
+            mtime_cas: Some(MtimeCas {
+                expected_mtime_ms: expected,
+                stale_message: "stale".to_string(),
+            }),
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{\"ok\":true}", None, &options)
+            .await
+            .unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{\"ok\":true}\n");
+    }
+
+    #[tokio::test]
+    async fn mtime_cas_expecting_missing_passes_when_file_absent() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("fresh.json");
+        let options = WriteJsonOptions {
+            mtime_cas: Some(MtimeCas {
+                expected_mtime_ms: None,
+                stale_message: "stale".to_string(),
+            }),
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{}", None, &options).await.unwrap();
+        assert!(path.exists());
+    }
+
+    #[test]
+    fn sync_variant_writes_and_replaces_existing_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+        fs::write(&path, "old").unwrap();
+        write_json_atomic_sync(&path, "{\"v\":2}", Some(0o600), &WriteJsonOptions::default())
+            .unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{\"v\":2}\n");
+        assert!(list_tmp_files(dir.path()).is_empty());
+    }
+
+    #[tokio::test]
+    async fn ensure_parent_dir_creates_missing_directories() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("logs").join("codex-plugin").join("request-1-response.json");
+        let options = WriteJsonOptions {
+            trailing_newline: TrailingNewline::None,
+            ensure_parent_dir: true,
+            parent_dir_mode: Some(0o700),
+            ..Default::default()
+        };
+        write_json_atomic(&path, "{}", Some(0o600), &options).await.unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{}");
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn applies_file_mode_on_unix() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("secret.json");
+        write_json_atomic(&path, "{}", Some(0o600), &WriteJsonOptions::default())
+            .await
+            .unwrap();
+        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o600);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn mode_is_applied_at_open_not_via_a_post_write_chmod() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+
+        // Fresh file: created with the mode at open(2) — it can never exist
+        // with bits outside 0600 (the pre-fix write-then-chmod pattern left a
+        // 0644 window and 0644 crash residue).
+        let fresh = dir.path().join("fresh-secret.json");
+        write_text_file_with_mode_sync(&fresh, "{}", Some(0o600)).unwrap();
+        let mode = fs::metadata(&fresh).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode & !0o600, 0, "no bits outside 0600: {mode:o}");
+
+        // Pre-existing file: Node's fs.writeFile only uses `mode` when O_CREAT
+        // actually creates the file, so existing permissions are preserved —
+        // proving there is no chmod-after-write in the implementation.
+        let existing = dir.path().join("existing.json");
+        fs::write(&existing, "old").unwrap();
+        fs::set_permissions(&existing, fs::Permissions::from_mode(0o644)).unwrap();
+        write_text_file_with_mode_sync(&existing, "new", Some(0o600)).unwrap();
+        assert_eq!(fs::read_to_string(&existing).unwrap(), "new");
+        let mode = fs::metadata(&existing).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o644, "pre-existing perms preserved (Node parity)");
+    }
+
+    #[test]
+    fn file_mtime_ms_returns_none_for_missing_files() {
+        let dir = tempfile::tempdir().unwrap();
+        assert_eq!(file_mtime_ms(&dir.path().join("nope.json")).unwrap(), None);
+        let path = dir.path().join("yes.json");
+        fs::write(&path, "x").unwrap();
+        assert!(file_mtime_ms(&path).unwrap().is_some());
+    }
+}
diff --git a/crates/core/src/jwt.rs b/crates/core/src/jwt.rs
new file mode 100644
index 000000000..ae23f7bf4
--- /dev/null
+++ b/crates/core/src/jwt.rs
@@ -0,0 +1,141 @@
+//! Port of `decodeJWT` from `lib/auth/auth.ts`.
+//!
+//! UNVERIFIED JWT payload decode: base64url -> base64 normalization with manual
+//! `=` padding, UTF-8 decode, JSON parse. No signature verification (by
+//! design — the tokens come straight from the OAuth provider over TLS and are
+//! only mined for display/routing hints, never trusted for authorization).
+//!
+//! Behavior contract (spec 07 §1 / gotcha 21):
+//! - the token must have EXACTLY 3 dot-separated segments;
+//! - any error at any step returns `None`;
+//! - do NOT pull in a JWT crate.
+
+use base64::Engine;
+use base64::alphabet;
+use base64::engine::{DecodePaddingMode, GeneralPurpose, GeneralPurposeConfig};
+
+/// Standard-alphabet base64 engine tuned to be as forgiving as Node's
+/// `Buffer.from(str, "base64")` for the inputs this decoder produces:
+/// indifferent to padding and tolerant of non-zero trailing bits.
+const NODE_LIKE_BASE64: GeneralPurpose = GeneralPurpose::new(
+    &alphabet::STANDARD,
+    GeneralPurposeConfig::new()
+        .with_decode_allow_trailing_bits(true)
+        .with_decode_padding_mode(DecodePaddingMode::Indifferent),
+);
+
+/// Decode a JWT's payload segment to raw JSON without verifying the signature.
+///
+/// This is the workhorse used by `token_utils` (which mines arbitrary,
+/// schema-less claims). Returns `None` on any structural, base64, UTF-8 or
+/// JSON failure — mirroring the TS `try { … } catch { return null; }`.
+pub fn decode_jwt_value(token: &str) -> Option<serde_json::Value> {
+    let parts: Vec<&str> = token.split('.').collect();
+    if parts.len() != 3 {
+        return None;
+    }
+    let payload = parts[1];
+    // base64url -> base64: `-` -> `+`, `_` -> `/`, then pad to a multiple of 4.
+    let normalized = payload.replace('-', "+").replace('_', "/");
+    let pad = (4 - normalized.len() % 4) % 4;
+    let padded = format!("{normalized}{}", "=".repeat(pad));
+    let bytes = NODE_LIKE_BASE64.decode(padded.as_bytes()).ok()?;
+    // Node's `buffer.toString("utf-8")` is lossy (invalid sequences become
+    // U+FFFD instead of failing); mirror that so a byte-level oddity in an
+    // otherwise-parseable payload does not flip the result to None.
+    let decoded = String::from_utf8_lossy(&bytes);
+    serde_json::from_str(&decoded).ok()
+}
+
+/// Decode a JWT payload into the typed [`crate::types::JWTPayload`] model.
+///
+/// Equivalent to the TS `decodeJWT(token): JWTPayload | null`. The payload is
+/// decoded unverified; unknown claims are preserved by the `JWTPayload` model.
+pub fn decode_jwt(token: &str) -> Option<crate::types::JWTPayload> {
+    let value = decode_jwt_value(token)?;
+    serde_json::from_value(value).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+    use serde_json::{Value, json};
+
+    fn b64url(data: &str) -> String {
+        URL_SAFE_NO_PAD.encode(data.as_bytes())
+    }
+
+    fn make_jwt(payload: &Value) -> String {
+        let header = json!({ "alg": "none", "typ": "JWT" });
+        format!(
+            "{}.{}.{}",
+            b64url(&header.to_string()),
+            b64url(&payload.to_string()),
+            "sig"
+        )
+    }
+
+    #[test]
+    fn decodes_a_valid_jwt_payload() {
+        let payload = json!({
+            "https://api.openai.com/auth": { "chatgpt_account_id": "acc_123456" },
+            "email": "user@example.com",
+        });
+        let decoded = decode_jwt_value(&make_jwt(&payload)).expect("decodes");
+        assert_eq!(
+            decoded["https://api.openai.com/auth"]["chatgpt_account_id"],
+            json!("acc_123456")
+        );
+        assert_eq!(decoded["email"], json!("user@example.com"));
+    }
+
+    #[test]
+    fn requires_exactly_three_segments() {
+        let payload = json!({ "a": 1 });
+        let two = format!("{}.{}", b64url("{}"), b64url(&payload.to_string()));
+        assert!(decode_jwt_value(&two).is_none());
+        let four = format!("{}.extra", make_jwt(&payload));
+        assert!(decode_jwt_value(&four).is_none());
+        assert!(decode_jwt_value("").is_none());
+        assert!(decode_jwt_value("only-one-segment").is_none());
+    }
+
+    #[test]
+    fn returns_none_for_garbage_payload_segment() {
+        assert!(decode_jwt_value("aaa.!!!not-base64%%%.ccc").is_none());
+        // Valid base64 but not JSON.
+        let not_json = format!("aaa.{}.ccc", b64url("this is not json"));
+        assert!(decode_jwt_value(&not_json).is_none());
+    }
+
+    #[test]
+    fn handles_every_padding_remainder() {
+        // Payload lengths that produce base64url lengths with remainders 0/2/3
+        // (remainder 1 is impossible for canonical base64) all decode.
+        for filler_len in 0..12usize {
+            let payload = json!({ "k": "x".repeat(filler_len) });
+            let decoded = decode_jwt_value(&make_jwt(&payload)).expect("decodes");
+            assert_eq!(decoded["k"], json!("x".repeat(filler_len)));
+        }
+    }
+
+    #[test]
+    fn handles_url_safe_alphabet_characters() {
+        // Multi-byte UTF-8 content forces bytes whose standard-base64 encoding
+        // contains `+`/`/`; the url-safe form uses `-`/`_`, exercising the
+        // normalization path.
+        let payload = json!({ "name": "日本語テキスト😀🌍", "meta": "ÿþý" });
+        let token = make_jwt(&payload);
+        let decoded = decode_jwt_value(&token).expect("decodes");
+        assert_eq!(decoded["name"], json!("日本語テキスト😀🌍"));
+        assert_eq!(decoded["meta"], json!("ÿþý"));
+    }
+
+    #[test]
+    fn non_object_json_payload_still_parses_as_value() {
+        // JSON.parse accepts any JSON value; the raw-value decoder mirrors it.
+        let token = format!("aaa.{}.ccc", b64url("123"));
+        assert_eq!(decode_jwt_value(&token), Some(json!(123)));
+    }
+}
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
new file mode 100644
index 000000000..ce560a16e
--- /dev/null
+++ b/crates/core/src/lib.rs
@@ -0,0 +1,20 @@
+//! cma-core - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod clock;
+pub mod constants;
+pub mod display_width;
+pub mod env_parsing;
+pub mod errors;
+pub mod fs_retry;
+pub mod json_io;
+pub mod jwt;
+pub mod logger;
+pub mod model_family;
+pub mod runtime_paths;
+pub mod schemas;
+pub mod shutdown;
+pub mod table_formatter;
+pub mod temp_path;
+pub mod token_utils;
+pub mod types;
+pub mod utils;
+pub mod wsl;
diff --git a/crates/core/src/logger.rs b/crates/core/src/logger.rs
new file mode 100644
index 000000000..44897c65b
--- /dev/null
+++ b/crates/core/src/logger.rs
@@ -0,0 +1,1263 @@
+//! Port of `lib/logger.ts`: process-wide logging.
+//!
+//! - Env flags are read ONCE at first use (OnceLock) — mirroring the TS
+//!   module-import-time evaluation (spec 01 gotcha 17).
+//! - Masking order is EMAIL-BEFORE-TOKEN (gotcha 14): the token regexes would
+//!   otherwise eat email fragments. Structured `email` keys use `mask_email`,
+//!   never `mask_token` (which leaks local part + TLD).
+//! - CR/LF are stripped from every console message (log-injection defense).
+//! - `sanitize_value` recurses to depth 10 with the SENSITIVE_KEYS set matched
+//!   on keys normalized to lowercase with `-`/`_` removed.
+//! - Correlation ids: tokio task-local scope with a module-global fallback for
+//!   the legacy single-flight path. Inside a scope the scope ALWAYS wins —
+//!   including a cleared (`None`) id (gotcha: cleared-scope-wins).
+//! - Request logs: `request-<n>-<stage>.json`, mode 0600, in a 0700 dir under
+//!   `<multi-auth-dir>/logs/codex-plugin/`; 2-space pretty JSON, NO trailing
+//!   newline. An ENOENT write failure invalidates the cached dir-ready flag so
+//!   a deleted log dir self-heals (gotcha 15).
+//! - The warn-once registry is process-global, keyed on the FULL message
+//!   string, and never expires except via [`__reset_for_tests`].
+//!
+//! The TS app-client sink (`initLogger(client)`) has no JS host in the Rust
+//! port; [`init_logger`] is kept as a no-op for API parity and the console
+//! sink (gated on `CODEX_CONSOLE_LOG=1`) is the only live output.
+
+use std::cell::RefCell;
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{LazyLock, Mutex, Once, OnceLock};
+use std::time::Instant;
+
+use regex::Regex;
+use serde_json::Value;
+
+use crate::constants::PLUGIN_NAME;
+
+// ---------------------------------------------------------------------------
+// Log levels
+// ---------------------------------------------------------------------------
+
+/// Log level: `debug` < `info` < `warn` < `error`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum LogLevel {
+    Debug,
+    Info,
+    Warn,
+    Error,
+}
+
+impl LogLevel {
+    /// Numeric priority (debug 0 … error 3).
+    pub fn priority(self) -> u8 {
+        match self {
+            LogLevel::Debug => 0,
+            LogLevel::Info => 1,
+            LogLevel::Warn => 2,
+            LogLevel::Error => 3,
+        }
+    }
+
+    /// The lowercase level name as used by the TS logger.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            LogLevel::Debug => "debug",
+            LogLevel::Info => "info",
+            LogLevel::Warn => "warn",
+            LogLevel::Error => "error",
+        }
+    }
+}
+
+impl std::fmt::Display for LogLevel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Parse `CODEX_PLUGIN_LOG_LEVEL`: lowercase + trim; must be one of the four
+/// level names, else `info`.
+pub fn parse_log_level(value: Option<&str>) -> LogLevel {
+    let Some(value) = value.filter(|v| !v.is_empty()) else {
+        return LogLevel::Info;
+    };
+    match value.to_lowercase().trim() {
+        "debug" => LogLevel::Debug,
+        "info" => LogLevel::Info,
+        "warn" => LogLevel::Warn,
+        "error" => LogLevel::Error,
+        _ => LogLevel::Info,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Env-init flags (read once at first use)
+// ---------------------------------------------------------------------------
+
+struct LoggerEnv {
+    logging_enabled: bool,
+    request_body_logging_enabled: bool,
+    debug_enabled: bool,
+    log_level: LogLevel,
+    console_enabled: bool,
+}
+
+static LOGGER_ENV: OnceLock<LoggerEnv> = OnceLock::new();
+static BANNER_ONCE: Once = Once::new();
+
+fn env_is_1(name: &str) -> bool {
+    std::env::var(name).map(|v| v == "1").unwrap_or(false)
+}
+
+fn read_logger_env() -> LoggerEnv {
+    let logging_enabled = env_is_1("ENABLE_PLUGIN_REQUEST_LOGGING");
+    let request_body_logging_enabled = env_is_1("CODEX_PLUGIN_LOG_BODIES");
+    let debug_enabled = env_is_1("DEBUG_CODEX_PLUGIN") || logging_enabled;
+    let log_level = parse_log_level(std::env::var("CODEX_PLUGIN_LOG_LEVEL").ok().as_deref());
+    let console_enabled = env_is_1("CODEX_CONSOLE_LOG");
+    LoggerEnv {
+        logging_enabled,
+        request_body_logging_enabled,
+        debug_enabled,
+        log_level,
+        console_enabled,
+    }
+}
+
+/// Read the env flags (once) and emit the TS import-time banner on first use.
+fn logger_env() -> &'static LoggerEnv {
+    let env = LOGGER_ENV.get_or_init(read_logger_env);
+    BANNER_ONCE.call_once(|| {
+        // The TS banner goes through logToConsole, which is gated on
+        // CODEX_CONSOLE_LOG — replicate the gate here (direct print: calling
+        // log_to_console from inside this Once would re-enter it).
+        if !env.console_enabled {
+            return;
+        }
+        if env.logging_enabled {
+            let dir = log_dir();
+            if env.request_body_logging_enabled {
+                println!(
+                    "[{PLUGIN_NAME}] Request logging ENABLED (raw payload capture ON) - logs will be saved to: {}",
+                    dir.display()
+                );
+            } else {
+                println!(
+                    "[{PLUGIN_NAME}] Request logging ENABLED (metadata only; set CODEX_PLUGIN_LOG_BODIES=1 for raw payloads) - logs will be saved to: {}",
+                    dir.display()
+                );
+            }
+        } else if env.debug_enabled {
+            println!(
+                "[{PLUGIN_NAME}] Debug logging ENABLED (level: {})",
+                env.log_level
+            );
+        }
+    });
+    env
+}
+
+/// `ENABLE_PLUGIN_REQUEST_LOGGING === "1"` (file request logs; implies debug).
+pub fn logging_enabled() -> bool {
+    logger_env().logging_enabled
+}
+
+/// `CODEX_PLUGIN_LOG_BODIES === "1"` (keep body/fullContent in request logs).
+pub fn request_body_logging_enabled() -> bool {
+    logger_env().request_body_logging_enabled
+}
+
+/// `DEBUG_CODEX_PLUGIN === "1"` OR request logging enabled.
+pub fn debug_enabled() -> bool {
+    logger_env().debug_enabled
+}
+
+/// Effective `CODEX_PLUGIN_LOG_LEVEL` (default `info`).
+pub fn log_level() -> LogLevel {
+    logger_env().log_level
+}
+
+/// Install the host app log sink. The JS plugin host is not ported (R1), so
+/// this is a no-op retained for API parity; the console sink
+/// (`CODEX_CONSOLE_LOG=1`) is the only live output channel.
+pub fn init_logger() {}
+
+// ---------------------------------------------------------------------------
+// Masking
+// ---------------------------------------------------------------------------
+
+static EMAIL_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}").expect("email regex")
+});
+
+static TOKEN_PATTERNS: LazyLock<[Regex; 5]> = LazyLock::new(|| {
+    [
+        Regex::new(r"eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+").expect("jwt regex"),
+        Regex::new(r"(?i)[a-f0-9]{40,}").expect("hex regex"),
+        Regex::new(r"sk-[A-Za-z0-9]{20,}").expect("sk regex"),
+        Regex::new(r"(?i)Bearer\s+\S+").expect("bearer regex"),
+        // This app's own local bearer tokens: `cma_local_<base64url>` (see
+        // lib/local-client-tokens.ts). The structured-log key masker and the
+        // OAuth scrubber cover the normal paths, but the free-text scrubber is
+        // the last line of defense and must recognize the project's own token
+        // shape too.
+        Regex::new(r"cma_local_[A-Za-z0-9_-]{16,}").expect("cma_local regex"),
+    ]
+});
+
+static CRLF_PATTERN: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[\r\n]+").expect("crlf regex"));
+
+/// SENSITIVE_KEYS after normalization (lowercase, `-`/`_` stripped); the TS
+/// source lists both raw and normalized spellings, which collapse to this set.
+const SENSITIVE_KEYS: [&str; 14] = [
+    "access",
+    "accesstoken",
+    "refresh",
+    "refreshtoken",
+    "token",
+    "authorization",
+    "apikey",
+    "experimentalbearertoken",
+    "secret",
+    "password",
+    "credential",
+    "idtoken",
+    "email",
+    "accountid",
+];
+
+fn normalize_key(key: &str) -> String {
+    key.to_lowercase().replace(['-', '_'], "")
+}
+
+/// Mask a token: length <= 12 fully masked, else first 6 + `...` + last 4.
+pub fn mask_token(token: &str) -> String {
+    let count = token.chars().count();
+    if count <= 12 {
+        return "***MASKED***".to_string();
+    }
+    let head: String = token.chars().take(6).collect();
+    let tail: String = token.chars().skip(count - 4).collect();
+    format!("{head}...{tail}")
+}
+
+/// Mask an email: keep <= 2 chars of the local part and the TLD only.
+pub fn mask_email(email: &str) -> String {
+    let Some(at_index) = email.find('@') else {
+        return "***@***".to_string();
+    };
+    let local = &email[..at_index];
+    let domain = &email[at_index + 1..];
+    let tld = domain.rsplit('.').next().unwrap_or("");
+    let prefix: String = local.chars().take(2).collect();
+    format!("{prefix}***@***.{tld}")
+}
+
+/// Mask free text: emails FIRST (before token patterns might match parts of
+/// them), then the token patterns in declaration order.
+pub fn mask_string(value: &str) -> String {
+    let mut result = EMAIL_PATTERN
+        .replace_all(value, |caps: &regex::Captures<'_>| mask_email(&caps[0]))
+        .into_owned();
+    for pattern in TOKEN_PATTERNS.iter() {
+        result = pattern
+            .replace_all(&result, |caps: &regex::Captures<'_>| mask_token(&caps[0]))
+            .into_owned();
+    }
+    result
+}
+
+fn sanitize_value_at(value: &Value, depth: u32) -> Value {
+    if depth > 10 {
+        return Value::String("[max depth]".to_string());
+    }
+
+    match value {
+        Value::String(s) => Value::String(mask_string(s)),
+        Value::Array(items) => Value::Array(
+            items
+                .iter()
+                .map(|item| sanitize_value_at(item, depth + 1))
+                .collect(),
+        ),
+        Value::Object(map) => {
+            let mut sanitized = serde_json::Map::new();
+            for (key, val) in map {
+                let normalized_key = normalize_key(key);
+                if SENSITIVE_KEYS.contains(&normalized_key.as_str()) {
+                    let masked = match val {
+                        // An email value masked with mask_token leaks the local
+                        // part and TLD; structured `email` fields use the
+                        // dedicated email masker to match the free-text path.
+                        Value::String(s) if normalized_key == "email" => {
+                            Value::String(mask_email(s))
+                        }
+                        Value::String(s) => Value::String(mask_token(s)),
+                        _ => Value::String("***MASKED***".to_string()),
+                    };
+                    sanitized.insert(key.clone(), masked);
+                } else {
+                    sanitized.insert(key.clone(), sanitize_value_at(val, depth + 1));
+                }
+            }
+            Value::Object(sanitized)
+        }
+        other => other.clone(),
+    }
+}
+
+/// Recursively mask sensitive material in a JSON value (depth cap 10).
+pub fn sanitize_value(value: &Value) -> Value {
+    sanitize_value_at(value, 0)
+}
+
+/// Format a duration in ms: `<1000` -> `NNNms`; `<60000` -> `S.SSs`;
+/// else `Mm S.Ss`.
+pub fn format_duration(ms: f64) -> String {
+    if ms < 1000.0 {
+        return format!("{}ms", ms.round() as i64);
+    }
+    if ms < 60000.0 {
+        return format!("{:.2}s", ms / 1000.0);
+    }
+    let minutes = (ms / 60000.0).floor() as i64;
+    let seconds = (ms % 60000.0) / 1000.0;
+    format!("{minutes}m {seconds:.1}s")
+}
+
+// ---------------------------------------------------------------------------
+// Correlation ids (errors-logging-02)
+// ---------------------------------------------------------------------------
+//
+// A single process-global was wrong for the concurrent runtime proxy: many
+// requests are in flight at once, so a global last-writer-wins value tags log
+// lines with the wrong request. A tokio task-local scopes the id to each
+// request's task. The module-global fallback is retained ONLY for legacy
+// single-flight callers; new concurrent code should use
+// `run_with_correlation_id`. NOTE: task-local values do NOT cross
+// `tokio::spawn` — any spawn inside a scoped region must re-wrap explicitly.
+
+tokio::task_local! {
+    static CORRELATION_SCOPE: RefCell<Option<String>>;
+}
+
+static FALLBACK_CORRELATION_ID: Mutex<Option<String>> = Mutex::new(None);
+
+fn new_correlation_id() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
+fn lock_fallback() -> std::sync::MutexGuard<'static, Option<String>> {
+    FALLBACK_CORRELATION_ID
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// Run `fut` with a correlation id bound to its task-local scope.
+/// Concurrent-safe: each invocation gets an isolated id that does not leak
+/// across requests. Omitted id -> a fresh random UUID.
+pub async fn run_with_correlation_id<F>(id: Option<String>, fut: F) -> F::Output
+where
+    F: std::future::Future,
+{
+    let resolved = id.unwrap_or_else(new_correlation_id);
+    CORRELATION_SCOPE.scope(RefCell::new(Some(resolved)), fut).await
+}
+
+/// Synchronous variant of [`run_with_correlation_id`] for non-async callers.
+pub fn run_with_correlation_id_sync<T>(id: Option<String>, f: impl FnOnce() -> T) -> T {
+    let resolved = id.unwrap_or_else(new_correlation_id);
+    CORRELATION_SCOPE.sync_scope(RefCell::new(Some(resolved)), f)
+}
+
+/// Set the correlation id: inside a scope, mutates the scoped id in place;
+/// outside, sets the module-global fallback. Returns the resolved id (a fresh
+/// UUID when omitted).
+pub fn set_correlation_id(id: Option<String>) -> String {
+    let resolved = id.unwrap_or_else(new_correlation_id);
+    let in_scope = CORRELATION_SCOPE
+        .try_with(|cell| {
+            *cell.borrow_mut() = Some(resolved.clone());
+        })
+        .is_ok();
+    if !in_scope {
+        *lock_fallback() = Some(resolved.clone());
+    }
+    resolved
+}
+
+/// Get the correlation id. Inside a scope the scoped id is authoritative —
+/// including a cleared `None` (scope wins over fallback; never leak the
+/// fallback into a cleared scope). Only outside any scope does the
+/// module-global fallback apply.
+pub fn get_correlation_id() -> Option<String> {
+    match CORRELATION_SCOPE.try_with(|cell| cell.borrow().clone()) {
+        Ok(scoped) => scoped,
+        Err(_) => lock_fallback().clone(),
+    }
+}
+
+/// Clear the correlation id in the active scope, or the global fallback when
+/// no scope is active.
+pub fn clear_correlation_id() {
+    let in_scope = CORRELATION_SCOPE
+        .try_with(|cell| {
+            *cell.borrow_mut() = None;
+        })
+        .is_ok();
+    if !in_scope {
+        *lock_fallback() = None;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Console sink
+// ---------------------------------------------------------------------------
+
+fn strip_crlf(message: &str) -> String {
+    CRLF_PATTERN.replace_all(message, " ").into_owned()
+}
+
+/// The single sanctioned console sink for the whole package: every message is
+/// mask-sanitized (and CR/LF-stripped) before it reaches the terminal.
+/// `console.warn`/`console.error` map to stderr, everything else to stdout.
+fn log_to_console(level: LogLevel, message: &str, data: Option<&Value>) {
+    let env = logger_env();
+    if !env.console_enabled {
+        return;
+    }
+    let sanitized_message = strip_crlf(&mask_string(message));
+    let sanitized_data = data.map(sanitize_value);
+
+    let line = match &sanitized_data {
+        Some(value) => {
+            let rendered = serde_json::to_string(value).unwrap_or_default();
+            format!("{sanitized_message} {rendered}")
+        }
+        None => sanitized_message,
+    };
+    match level {
+        LogLevel::Warn | LogLevel::Error => eprintln!("{line}"),
+        _ => println!("{line}"),
+    }
+}
+
+fn should_log(level: LogLevel) -> bool {
+    if level == LogLevel::Error {
+        return true;
+    }
+    let env = logger_env();
+    if !env.debug_enabled && !env.logging_enabled {
+        return false;
+    }
+    level.priority() >= env.log_level.priority()
+}
+
+/// Debug-level log (gated by env flags and `CODEX_PLUGIN_LOG_LEVEL`).
+pub fn log_debug(message: &str, data: Option<&Value>) {
+    if !should_log(LogLevel::Debug) {
+        return;
+    }
+    log_to_console(LogLevel::Debug, &format!("[{PLUGIN_NAME}] {message}"), data);
+}
+
+/// Info-level log.
+pub fn log_info(message: &str, data: Option<&Value>) {
+    if !should_log(LogLevel::Info) {
+        return;
+    }
+    log_to_console(LogLevel::Info, &format!("[{PLUGIN_NAME}] {message}"), data);
+}
+
+/// Warn-level log.
+pub fn log_warn(message: &str, data: Option<&Value>) {
+    if !should_log(LogLevel::Warn) {
+        return;
+    }
+    log_to_console(LogLevel::Warn, &format!("[{PLUGIN_NAME}] {message}"), data);
+}
+
+/// Error-level log — ALWAYS emitted (no gate).
+pub fn log_error(message: &str, data: Option<&Value>) {
+    log_to_console(LogLevel::Error, &format!("[{PLUGIN_NAME}] {message}"), data);
+}
+
+// ---------------------------------------------------------------------------
+// Warn-once registry (process-global, keyed on the full message string)
+// ---------------------------------------------------------------------------
+
+static WARN_ONCE_REGISTRY: LazyLock<Mutex<HashSet<String>>> =
+    LazyLock::new(|| Mutex::new(HashSet::new()));
+
+fn lock_warn_once() -> std::sync::MutexGuard<'static, HashSet<String>> {
+    WARN_ONCE_REGISTRY
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// Emit `log_warn(message)` at most once per unique FULL message string for
+/// the lifetime of the process (spec 01 gotcha 7 — a repeat warning would
+/// change observable CLI output). Returns whether the warning was emitted.
+pub fn warn_once(message: &str) -> bool {
+    let inserted = lock_warn_once().insert(message.to_string());
+    if inserted {
+        log_warn(message, None);
+    }
+    inserted
+}
+
+/// Clear the warn-once registry (test seam; the TS analogue is
+/// `__resetConfigWarningCacheForTests`).
+pub fn __reset_for_tests() {
+    lock_warn_once().clear();
+}
+
+// ---------------------------------------------------------------------------
+// Request file logging
+// ---------------------------------------------------------------------------
+
+const LOG_DIR_MAX_ATTEMPTS: u32 = 3;
+
+static REQUEST_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+// Once the log dir is confirmed to exist we never need to stat/mkdir again for
+// this process, so the hot logging path does no filesystem work after the
+// first success.
+static LOG_DIR_READY: AtomicBool = AtomicBool::new(false);
+
+fn log_dir() -> &'static PathBuf {
+    static LOG_DIR: OnceLock<PathBuf> = OnceLock::new();
+    LOG_DIR.get_or_init(|| crate::runtime_paths::get_codex_log_dir().join("codex-plugin"))
+}
+
+fn create_log_dir(path: &Path) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        std::fs::DirBuilder::new()
+            .recursive(true)
+            .mode(0o700)
+            .create(path)
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::create_dir_all(path)
+    }
+}
+
+/// Ensure the log directory exists (best-effort, synchronous, non-blocking).
+///
+/// Logging is fire-and-forget on a concurrent request path, so this must never
+/// block: retry the mkdir up to 3 times IMMEDIATELY (no sleep) on transient
+/// EBUSY/EPERM; a persistent failure skips this one log line rather than
+/// stalling the proxy. Success is cached.
+fn ensure_log_dir(path: &Path) -> bool {
+    if LOG_DIR_READY.load(Ordering::Acquire) {
+        return true;
+    }
+    let mut last_error: Option<std::io::Error> = None;
+    for attempt in 0..LOG_DIR_MAX_ATTEMPTS {
+        let result = if path.exists() {
+            Ok(())
+        } else {
+            create_log_dir(path)
+        };
+        match result {
+            Ok(()) => {
+                LOG_DIR_READY.store(true, Ordering::Release);
+                return true;
+            }
+            Err(error) => {
+                let code = crate::fs_retry::code_of(&error).unwrap_or("");
+                let retryable = code == "EBUSY" || code == "EPERM";
+                last_error = Some(error);
+                if retryable && attempt + 1 < LOG_DIR_MAX_ATTEMPTS {
+                    // Immediate retry (no thread-blocking sleep). A transient
+                    // lock is usually gone by the next attempt.
+                    continue;
+                }
+                break;
+            }
+        }
+    }
+    log_to_console(
+        LogLevel::Warn,
+        &format!("[{PLUGIN_NAME}] Failed to ensure log directory"),
+        Some(&serde_json::json!({
+            "path": path.display().to_string(),
+            "error": last_error
+                .map(|e| e.to_string())
+                .unwrap_or_else(|| "unknown".to_string()),
+        })),
+    );
+    false
+}
+
+/// Body-suppression pass (gotcha 16): unless raw-body capture is enabled, keys
+/// whose lowercase-de-`[-_]`d form equals `body` or `fullcontent` are removed
+/// and `payloadsOmitted: true` is appended.
+fn sanitize_request_log_data_with(
+    data: &serde_json::Map<String, Value>,
+    body_logging_enabled: bool,
+) -> serde_json::Map<String, Value> {
+    if body_logging_enabled {
+        return data.clone();
+    }
+
+    let mut omitted_payloads = false;
+    let mut sanitized = serde_json::Map::new();
+    for (key, value) in data {
+        let normalized_key = normalize_key(key);
+        if normalized_key == "body" || normalized_key == "fullcontent" {
+            omitted_payloads = true;
+            continue;
+        }
+        sanitized.insert(key.clone(), value.clone());
+    }
+    if omitted_payloads {
+        sanitized.insert("payloadsOmitted".to_string(), Value::Bool(true));
+    }
+    sanitized
+}
+
+/// Assemble the request-log JSON object in the exact TS key order:
+/// `timestamp`, `requestId`, optional `correlationId`, `stage`, then the
+/// sanitized data spread (existing keys keep their first position).
+fn build_request_log_json(
+    timestamp: &str,
+    request_id: u64,
+    correlation_id: Option<&str>,
+    stage: &str,
+    sanitized_data: serde_json::Map<String, Value>,
+) -> Value {
+    let mut map = serde_json::Map::new();
+    map.insert("timestamp".to_string(), Value::String(timestamp.to_string()));
+    map.insert("requestId".to_string(), Value::from(request_id));
+    if let Some(cid) = correlation_id.filter(|c| !c.is_empty()) {
+        map.insert("correlationId".to_string(), Value::String(cid.to_string()));
+    }
+    map.insert("stage".to_string(), Value::String(stage.to_string()));
+    for (key, value) in sanitized_data {
+        map.insert(key, value);
+    }
+    Value::Object(map)
+}
+
+fn write_request_log_file(path: &Path, contents: &str) -> std::io::Result<()> {
+    use std::io::Write;
+    let mut options = std::fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    let mut file = options.open(path)?;
+    file.write_all(contents.as_bytes())
+}
+
+/// Write a per-request JSON log file `request-<n>-<stage>.json` (no-op unless
+/// `ENABLE_PLUGIN_REQUEST_LOGGING=1`). Files are 0600 in a 0700 dir; pretty
+/// 2-space JSON with NO trailing newline (spec 01 §4.6 / ARCH §8.1 matrix).
+pub fn log_request(stage: &str, data: &serde_json::Map<String, Value>) {
+    let env = logger_env();
+    if !env.logging_enabled {
+        return;
+    }
+
+    let dir = log_dir();
+    if !ensure_log_dir(dir) {
+        return;
+    }
+
+    let timestamp = chrono::Utc::now()
+        .format("%Y-%m-%dT%H:%M:%S%.3fZ")
+        .to_string();
+    let request_id = REQUEST_COUNTER.fetch_add(1, Ordering::SeqCst) + 1;
+    let correlation_id = get_correlation_id();
+    let filename = dir.join(format!("request-{request_id}-{stage}.json"));
+    let request_data = sanitize_request_log_data_with(data, env.request_body_logging_enabled);
+    let sanitized_data = match sanitize_value(&Value::Object(request_data)) {
+        Value::Object(map) => map,
+        _ => serde_json::Map::new(),
+    };
+
+    let payload = build_request_log_json(
+        &timestamp,
+        request_id,
+        correlation_id.as_deref(),
+        stage,
+        sanitized_data,
+    );
+    let serialized = crate::json_io::stringify_pretty2(&payload);
+
+    match write_request_log_file(&filename, &serialized) {
+        Ok(()) => {
+            log_to_console(
+                LogLevel::Info,
+                &format!("[{PLUGIN_NAME}] Logged {stage} to {}", filename.display()),
+                None,
+            );
+        }
+        Err(error) => {
+            // If the log dir vanished after we cached it as ready, a write
+            // fails with ENOENT and would stay broken until restart because
+            // ensure_log_dir is a no-op once ready. Invalidate the cache on a
+            // directory-missing failure so the next log_request re-creates it.
+            if error.kind() == std::io::ErrorKind::NotFound {
+                LOG_DIR_READY.store(false, Ordering::Release);
+            }
+            log_to_console(
+                LogLevel::Error,
+                &format!("[{PLUGIN_NAME}] Failed to write log: {error}"),
+                None,
+            );
+        }
+    }
+}
+
+/// Current request counter value (the id of the most recent request log).
+pub fn get_request_id() -> u64 {
+    REQUEST_COUNTER.load(Ordering::SeqCst)
+}
+
+// ---------------------------------------------------------------------------
+// Scoped loggers + timers
+// ---------------------------------------------------------------------------
+
+const MAX_TIMERS: usize = 100;
+
+/// Global timer registry: insertion-ordered, capped at [`MAX_TIMERS`] entries
+/// (oldest insertion evicted when full), mirroring the TS `Map` semantics.
+static TIMERS: Mutex<Vec<(String, Instant)>> = Mutex::new(Vec::new());
+
+fn lock_timers() -> std::sync::MutexGuard<'static, Vec<(String, Instant)>> {
+    TIMERS.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn timers_set(key: String, start: Instant) {
+    let mut timers = lock_timers();
+    // TS evicts BEFORE the set, even when the set would only overwrite.
+    if timers.len() >= MAX_TIMERS {
+        timers.remove(0);
+    }
+    if let Some(entry) = timers.iter_mut().find(|(k, _)| *k == key) {
+        entry.1 = start;
+    } else {
+        timers.push((key, start));
+    }
+}
+
+fn timers_delete(key: &str) {
+    let mut timers = lock_timers();
+    if let Some(index) = timers.iter().position(|(k, _)| k == key) {
+        timers.remove(index);
+    }
+}
+
+/// A running timer returned by [`ScopedLogger::time`]; call [`Self::end`] to
+/// stop it, log at debug level, and get the elapsed milliseconds (the TS
+/// analogue is the returned closure).
+#[derive(Debug)]
+pub struct ScopedTimer {
+    key: String,
+    prefix: String,
+    label: String,
+    start: Instant,
+}
+
+impl ScopedTimer {
+    /// Stop the timer: removes it from the registry, logs
+    /// `"<label>: <formatted duration>"` at debug level, and returns the
+    /// duration in milliseconds.
+    pub fn end(self) -> f64 {
+        let duration = self.start.elapsed().as_secs_f64() * 1000.0;
+        timers_delete(&self.key);
+        if should_log(LogLevel::Debug) {
+            let text = format!("{} {}: {}", self.prefix, self.label, format_duration(duration));
+            log_to_console(LogLevel::Debug, &text, None);
+        }
+        duration
+    }
+}
+
+/// Logger bound to a scope: prefix `[codex-multi-auth:<scope>]`.
+#[derive(Debug, Clone)]
+pub struct ScopedLogger {
+    scope: String,
+    prefix: String,
+}
+
+/// Create a scoped logger (TS `createLogger(scope)`).
+pub fn create_logger(scope: &str) -> ScopedLogger {
+    ScopedLogger {
+        scope: scope.to_string(),
+        prefix: format!("[{PLUGIN_NAME}:{scope}]"),
+    }
+}
+
+impl ScopedLogger {
+    pub fn debug(&self, message: &str, data: Option<&Value>) {
+        if !should_log(LogLevel::Debug) {
+            return;
+        }
+        log_to_console(LogLevel::Debug, &format!("{} {message}", self.prefix), data);
+    }
+
+    pub fn info(&self, message: &str, data: Option<&Value>) {
+        if !should_log(LogLevel::Info) {
+            return;
+        }
+        log_to_console(LogLevel::Info, &format!("{} {message}", self.prefix), data);
+    }
+
+    pub fn warn(&self, message: &str, data: Option<&Value>) {
+        if !should_log(LogLevel::Warn) {
+            return;
+        }
+        log_to_console(LogLevel::Warn, &format!("{} {message}", self.prefix), data);
+    }
+
+    /// Error-level — always emitted.
+    pub fn error(&self, message: &str, data: Option<&Value>) {
+        log_to_console(LogLevel::Error, &format!("{} {message}", self.prefix), data);
+    }
+
+    /// Start a timer keyed `<scope>:<label>` in the global registry (capped at
+    /// 100 entries, oldest insertion evicted).
+    pub fn time(&self, label: &str) -> ScopedTimer {
+        let key = format!("{}:{label}", self.scope);
+        let start = Instant::now();
+        timers_set(key.clone(), start);
+        ScopedTimer {
+            key,
+            prefix: self.prefix.clone(),
+            label: label.to_string(),
+            start,
+        }
+    }
+
+    /// Log a duration measured externally (no registry interaction).
+    pub fn time_end(&self, label: &str, start_time: Instant) {
+        let duration = start_time.elapsed().as_secs_f64() * 1000.0;
+        if should_log(LogLevel::Debug) {
+            let text = format!("{} {label}: {}", self.prefix, format_duration(duration));
+            log_to_console(LogLevel::Debug, &text, None);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use serial_test::serial;
+
+    // === mask_token ===
+
+    #[test]
+    fn mask_token_fully_masks_short_tokens() {
+        assert_eq!(mask_token("short"), "***MASKED***");
+        assert_eq!(mask_token("12chars_here"), "***MASKED***");
+        assert_eq!(mask_token("exactly12chr"), "***MASKED***");
+        assert_eq!(mask_token(""), "***MASKED***");
+    }
+
+    #[test]
+    fn mask_token_partially_masks_long_tokens() {
+        assert_eq!(mask_token("this-is-a-longer-token-value"), "this-i...alue");
+    }
+
+    // === mask_email (ported from test/logger.test.ts) ===
+
+    #[test]
+    fn mask_email_masks_a_standard_email_address() {
+        assert_eq!(mask_email("john.doe@example.com"), "jo***@***.com");
+    }
+
+    #[test]
+    fn mask_email_masks_a_short_local_part() {
+        assert_eq!(mask_email("a@example.org"), "a***@***.org");
+    }
+
+    #[test]
+    fn mask_email_handles_subdomain_emails() {
+        assert_eq!(mask_email("user@mail.company.co.uk"), "us***@***.uk");
+    }
+
+    #[test]
+    fn mask_email_handles_invalid_emails_gracefully() {
+        assert_eq!(mask_email("not-an-email"), "***@***");
+    }
+
+    #[test]
+    fn mask_email_preserves_tld() {
+        assert_eq!(mask_email("test@domain.io"), "te***@***.io");
+    }
+
+    // === mask_string ===
+
+    #[test]
+    fn mask_string_masks_emails_before_token_patterns() {
+        // The hex/token regexes must not eat email fragments: the email is
+        // masked first and its remnants no longer match token shapes.
+        let masked = mask_string("contact deadbeefcafe1234@example.com now");
+        assert!(masked.contains("de***@***.com"), "got: {masked}");
+        assert!(!masked.contains("example.com"));
+    }
+
+    #[test]
+    fn mask_string_masks_jwts_hex_sk_and_bearer_tokens() {
+        let jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N";
+        let masked = mask_string(&format!("token {jwt} end"));
+        assert!(!masked.contains(jwt));
+
+        let hex = "a".repeat(40);
+        assert!(!mask_string(&format!("hash {hex} end")).contains(&hex));
+
+        let sk = format!("sk-{}", "A1b2C3d4E5f6G7h8I9j0K");
+        assert!(!mask_string(&format!("key {sk} end")).contains(&sk));
+
+        let masked = mask_string("Authorization: Bearer super-secret-token-value");
+        assert!(!masked.contains("super-secret-token-value"));
+    }
+
+    #[test]
+    fn mask_string_masks_cma_local_bearer_tokens_in_free_text() {
+        let token = format!("cma_local_{}", "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6");
+        let masked = mask_string(&format!("authorization failed for {token} end"));
+        assert!(!masked.contains(&token));
+    }
+
+    // === sanitize_value ===
+
+    #[test]
+    fn sanitize_value_masks_sensitive_keys_with_non_string_values() {
+        let sanitized = sanitize_value(&json!({
+            "access_token": 12345,
+            "password": { "nested": true },
+            "apiKey": ["array", "value"],
+        }));
+        assert_eq!(sanitized["access_token"], json!("***MASKED***"));
+        assert_eq!(sanitized["password"], json!("***MASKED***"));
+        assert_eq!(sanitized["apiKey"], json!("***MASKED***"));
+    }
+
+    #[test]
+    fn sanitize_value_masks_short_string_tokens_fully() {
+        let sanitized = sanitize_value(&json!({
+            "access_token": "short",
+            "password": "12chars_here",
+            "apiKey": "exactly12chr",
+        }));
+        assert_eq!(sanitized["access_token"], json!("***MASKED***"));
+        assert_eq!(sanitized["password"], json!("***MASKED***"));
+        assert_eq!(sanitized["apiKey"], json!("***MASKED***"));
+    }
+
+    #[test]
+    fn sanitize_value_partially_masks_long_string_tokens() {
+        let sanitized = sanitize_value(&json!({
+            "access_token": "this-is-a-longer-token-value",
+        }));
+        assert_eq!(sanitized["access_token"], json!("this-i...alue"));
+    }
+
+    #[test]
+    fn sanitize_value_masks_experimental_bearer_token_key_variants() {
+        let sanitized = sanitize_value(&json!({
+            "experimental_bearer_token": "runtime-router-secret-value",
+            "experimentalBearerToken": "runtime-router-secret-value",
+            "experimental-bearer-token": "runtime-router-secret-value",
+        }));
+        assert_eq!(sanitized["experimental_bearer_token"], json!("runtim...alue"));
+        assert_eq!(sanitized["experimentalBearerToken"], json!("runtim...alue"));
+        assert_eq!(sanitized["experimental-bearer-token"], json!("runtim...alue"));
+    }
+
+    #[test]
+    fn sanitize_value_masks_email_key_with_mask_email_not_mask_token() {
+        // Regression: sanitizeValue used maskToken for every sensitive key, so
+        // an `email` field leaked the local part + TLD. It must use maskEmail.
+        let sanitized = sanitize_value(&json!({ "email": "alice@example.com" }));
+        assert_eq!(sanitized["email"], json!("al***@***.com"));
+        let rendered = sanitized["email"].as_str().unwrap();
+        assert!(!rendered.contains("alice"));
+        assert!(!rendered.contains("example"));
+    }
+
+    #[test]
+    fn sanitize_value_masks_non_string_email_key_without_leaking() {
+        let sanitized = sanitize_value(&json!({ "email": { "nested": "alice@example.com" } }));
+        assert_eq!(sanitized["email"], json!("***MASKED***"));
+    }
+
+    #[test]
+    fn sanitize_value_returns_max_depth_beyond_depth_10() {
+        let mut obj = json!({ "value": "test" });
+        for _ in 0..15 {
+            obj = json!({ "nested": obj });
+        }
+        let sanitized = sanitize_value(&obj);
+        let rendered = serde_json::to_string(&sanitized).unwrap();
+        assert!(rendered.contains("[max depth]"));
+    }
+
+    #[test]
+    fn sanitize_value_handles_arrays_nulls_and_primitives() {
+        let sanitized = sanitize_value(&json!({
+            "items": ["normal", "user@example.com", "other"],
+            "nullValue": null,
+            "count": 42,
+        }));
+        assert_eq!(sanitized["items"][0], json!("normal"));
+        assert!(sanitized["items"][1].as_str().unwrap().contains("***@***"));
+        assert_eq!(sanitized["items"][2], json!("other"));
+        assert_eq!(sanitized["nullValue"], Value::Null);
+        assert_eq!(sanitized["count"], json!(42));
+        // Non-object roots pass through the string/primitive branches.
+        assert_eq!(sanitize_value(&json!(42)), json!(42));
+        assert_eq!(sanitize_value(&Value::Null), Value::Null);
+    }
+
+    #[test]
+    fn sanitize_value_masks_nested_sensitive_keys() {
+        let sanitized = sanitize_value(&json!({
+            "auth": {
+                "access": "secret-token-that-is-long",
+                "nested": { "refresh": "another-secret-value-long" },
+            },
+        }));
+        assert_eq!(sanitized["auth"]["access"], json!("secret...long"));
+        assert_eq!(sanitized["auth"]["nested"]["refresh"], json!("anothe...long"));
+    }
+
+    // === format_duration ===
+
+    #[test]
+    fn format_duration_cases() {
+        assert_eq!(format_duration(500.0), "500ms");
+        assert_eq!(format_duration(2500.0), "2.50s");
+        assert_eq!(format_duration(90000.0), "1m 30.0s");
+        assert_eq!(format_duration(123.456), "123ms");
+        assert_eq!(format_duration(0.0), "0ms");
+    }
+
+    // === parse_log_level ===
+
+    #[test]
+    fn parse_log_level_accepts_the_four_levels_and_defaults_to_info() {
+        assert_eq!(parse_log_level(Some("debug")), LogLevel::Debug);
+        assert_eq!(parse_log_level(Some("INFO")), LogLevel::Info);
+        assert_eq!(parse_log_level(Some(" warn ")), LogLevel::Warn);
+        assert_eq!(parse_log_level(Some("error")), LogLevel::Error);
+        assert_eq!(parse_log_level(Some("bogus")), LogLevel::Info);
+        assert_eq!(parse_log_level(Some("")), LogLevel::Info);
+        assert_eq!(parse_log_level(None), LogLevel::Info);
+    }
+
+    // === request-log data shaping ===
+
+    #[test]
+    fn request_log_body_suppression_normalizes_keys() {
+        let mut data = serde_json::Map::new();
+        data.insert("Body".to_string(), json!("payload"));
+        data.insert("full_content".to_string(), json!("payload"));
+        data.insert("full-content".to_string(), json!("payload"));
+        data.insert("note".to_string(), json!("keep"));
+
+        let suppressed = sanitize_request_log_data_with(&data, false);
+        assert!(!suppressed.contains_key("Body"));
+        assert!(!suppressed.contains_key("full_content"));
+        assert!(!suppressed.contains_key("full-content"));
+        assert_eq!(suppressed["note"], json!("keep"));
+        assert_eq!(suppressed["payloadsOmitted"], json!(true));
+
+        let kept = sanitize_request_log_data_with(&data, true);
+        assert_eq!(kept["Body"], json!("payload"));
+        assert!(!kept.contains_key("payloadsOmitted"));
+    }
+
+    #[test]
+    fn request_log_body_suppression_skips_marker_when_nothing_omitted() {
+        let mut data = serde_json::Map::new();
+        data.insert("note".to_string(), json!("keep"));
+        let suppressed = sanitize_request_log_data_with(&data, false);
+        assert!(!suppressed.contains_key("payloadsOmitted"));
+    }
+
+    #[test]
+    fn request_log_json_uses_exact_key_order() {
+        let mut sanitized = serde_json::Map::new();
+        sanitized.insert("note".to_string(), json!("keep"));
+        let payload = build_request_log_json(
+            "2026-07-26T00:00:00.000Z",
+            7,
+            Some("cid-1"),
+            "response",
+            sanitized,
+        );
+        let keys: Vec<&String> = payload.as_object().unwrap().keys().collect();
+        assert_eq!(keys, ["timestamp", "requestId", "correlationId", "stage", "note"]);
+        assert_eq!(payload["requestId"], json!(7));
+    }
+
+    #[test]
+    fn request_log_json_omits_empty_or_absent_correlation_id() {
+        let payload =
+            build_request_log_json("t", 1, None, "response", serde_json::Map::new());
+        assert!(!payload.as_object().unwrap().contains_key("correlationId"));
+        let payload =
+            build_request_log_json("t", 1, Some(""), "response", serde_json::Map::new());
+        assert!(!payload.as_object().unwrap().contains_key("correlationId"));
+    }
+
+    // === log fns / logRequest smoke (disabled env => no-ops, must not panic) ===
+
+    #[test]
+    fn log_functions_do_not_panic() {
+        log_debug("debug message", None);
+        log_info("info message", Some(&json!({ "k": "v" })));
+        log_warn("warn message", None);
+        log_error("error message", Some(&json!({ "token": "secret" })));
+        let mut data = serde_json::Map::new();
+        data.insert("k".to_string(), json!("v"));
+        log_request("test-stage", &data);
+        let _ = get_request_id();
+        init_logger();
+    }
+
+    // === correlation ids ===
+
+    #[test]
+    #[serial]
+    fn fallback_correlation_id_set_get_clear() {
+        clear_correlation_id();
+        assert_eq!(get_correlation_id(), None);
+
+        let generated = set_correlation_id(None);
+        assert_eq!(generated.len(), 36); // UUID v4 hyphenated
+        assert_eq!(get_correlation_id(), Some(generated.clone()));
+
+        let explicit = set_correlation_id(Some("custom-id-123".to_string()));
+        assert_eq!(explicit, "custom-id-123");
+        assert_eq!(get_correlation_id(), Some("custom-id-123".to_string()));
+
+        clear_correlation_id();
+        assert_eq!(get_correlation_id(), None);
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn isolates_correlation_ids_across_concurrent_scopes() {
+        clear_correlation_id();
+        let (a, b) = tokio::join!(
+            run_with_correlation_id(Some("id-a".to_string()), async {
+                tokio::task::yield_now().await;
+                get_correlation_id()
+            }),
+            run_with_correlation_id(Some("id-b".to_string()), async { get_correlation_id() }),
+        );
+        assert_eq!(a, Some("id-a".to_string()));
+        assert_eq!(b, Some("id-b".to_string()));
+        // Scopes never touched the fallback.
+        assert_eq!(get_correlation_id(), None);
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn set_correlation_id_inside_a_scope_updates_only_that_scope() {
+        clear_correlation_id();
+        let inside = run_with_correlation_id(Some("original".to_string()), async {
+            set_correlation_id(Some("updated".to_string()));
+            get_correlation_id()
+        })
+        .await;
+        assert_eq!(inside, Some("updated".to_string()));
+        assert_eq!(get_correlation_id(), None);
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn cleared_scope_wins_over_fallback() {
+        clear_correlation_id();
+        set_correlation_id(Some("fallback-id".to_string()));
+        let inside = run_with_correlation_id(Some("scoped".to_string()), async {
+            clear_correlation_id();
+            // The cleared scope must win: never leak the fallback here.
+            get_correlation_id()
+        })
+        .await;
+        assert_eq!(inside, None);
+        assert_eq!(get_correlation_id(), Some("fallback-id".to_string()));
+        clear_correlation_id();
+    }
+
+    #[test]
+    #[serial]
+    fn run_with_correlation_id_sync_scopes_the_id() {
+        clear_correlation_id();
+        let inside = run_with_correlation_id_sync(None, get_correlation_id);
+        assert!(inside.is_some());
+        assert_eq!(inside.unwrap().len(), 36);
+        assert_eq!(get_correlation_id(), None);
+    }
+
+    // === warn-once ===
+
+    #[test]
+    #[serial]
+    fn warn_once_dedupes_on_the_full_message_string() {
+        __reset_for_tests();
+        assert!(warn_once("warn-once test message"));
+        assert!(!warn_once("warn-once test message"));
+        assert!(warn_once("warn-once test message 2"));
+        __reset_for_tests();
+        assert!(warn_once("warn-once test message"));
+        __reset_for_tests();
+    }
+
+    // === scoped logger + timers ===
+
+    #[test]
+    fn scoped_logger_logs_and_times_without_panicking() {
+        let logger = create_logger("test-scope");
+        logger.debug("debug", None);
+        logger.info("info", Some(&json!({ "k": "v" })));
+        logger.warn("warn", None);
+        logger.error("error", None);
+
+        let timer = logger.time("op");
+        let duration = timer.end();
+        assert!(duration >= 0.0);
+
+        logger.time_end("external", Instant::now());
+    }
+
+    #[test]
+    fn timer_registry_caps_at_100_entries_without_panicking() {
+        let logger = create_logger("cap-test");
+        let mut timers = Vec::new();
+        for i in 0..150 {
+            timers.push(logger.time(&format!("label-{i}")));
+        }
+        assert!(lock_timers().len() <= MAX_TIMERS);
+        for timer in timers {
+            let _ = timer.end();
+        }
+    }
+
+    #[test]
+    fn timer_overwrite_keeps_single_entry_per_key() {
+        let logger = create_logger("overwrite-test");
+        let t1 = logger.time("same");
+        let t2 = logger.time("same");
+        let count = lock_timers()
+            .iter()
+            .filter(|(k, _)| k == "overwrite-test:same")
+            .count();
+        assert_eq!(count, 1);
+        let _ = t2.end();
+        let _ = t1.end();
+    }
+}
diff --git a/crates/core/src/model_family.rs b/crates/core/src/model_family.rs
new file mode 100644
index 000000000..b2e065eed
--- /dev/null
+++ b/crates/core/src/model_family.rs
@@ -0,0 +1,168 @@
+//! Port of the `MODEL_FAMILIES` / `DEFAULT_MODEL` slice of
+//! `lib/request/helpers/model-map.ts` (spec 06 §"model-map").
+//!
+//! Only the family enum and the two default-model constants live in core (they
+//! are needed by the storage schemas — de-cycling move #1 in ARCHITECTURE §4).
+//! The full alias/profile tables stay in `cma-request::model_map`.
+
+use serde::{Deserialize, Serialize};
+
+/// Model family type for prompt selection (TS `PromptModelFamily`).
+/// TS declares `type ModelFamily = PromptModelFamily`.
+pub type PromptModelFamily = ModelFamily;
+
+/// All supported model families. Used for per-family account rotation and
+/// rate-limit tracking.
+///
+/// Serde renames are EXACT wire/persisted literals:
+/// `"gpt-5-codex"`, `"codex-max"`, `"codex"`, `"gpt-5.2"`, `"gpt-5.1"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub enum ModelFamily {
+    #[serde(rename = "gpt-5-codex")]
+    Gpt5Codex,
+    #[serde(rename = "codex-max")]
+    CodexMax,
+    #[serde(rename = "codex")]
+    Codex,
+    #[serde(rename = "gpt-5.2")]
+    Gpt5_2,
+    #[serde(rename = "gpt-5.1")]
+    Gpt5_1,
+}
+
+/// All supported model families, in the TS declaration order
+/// (TS `MODEL_FAMILIES`).
+pub const MODEL_FAMILIES: [ModelFamily; 5] = [
+    ModelFamily::Gpt5Codex,
+    ModelFamily::CodexMax,
+    ModelFamily::Codex,
+    ModelFamily::Gpt5_2,
+    ModelFamily::Gpt5_1,
+];
+
+/// Default model when no/unknown model is requested (TS `DEFAULT_MODEL`).
+pub const DEFAULT_MODEL: &str = "gpt-5.5";
+
+/// Model used for diagnostic live/quota probes (`check`, `report`, `best`).
+/// Deliberately distinct from [`DEFAULT_MODEL`]: GPT-5.6 is the latest general
+/// family (issue #627), so the probe leads with it, while `DEFAULT_MODEL`
+/// stays on 5.5 so actual request routing and the legacy `gpt-5` alias remain
+/// opt-in per 2.5.0. Bare `gpt-5.6` aliases to Sol; the canonical id is pinned
+/// so probe display and report `modelSelection` read `gpt-5.6-sol` without a
+/// remap arrow. (TS `DEFAULT_PROBE_MODEL`.)
+pub const DEFAULT_PROBE_MODEL: &str = "gpt-5.6-sol";
+
+impl ModelFamily {
+    /// The exact family literal (`"gpt-5-codex"`, `"codex-max"`, `"codex"`,
+    /// `"gpt-5.2"`, `"gpt-5.1"`).
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ModelFamily::Gpt5Codex => "gpt-5-codex",
+            ModelFamily::CodexMax => "codex-max",
+            ModelFamily::Codex => "codex",
+            ModelFamily::Gpt5_2 => "gpt-5.2",
+            ModelFamily::Gpt5_1 => "gpt-5.1",
+        }
+    }
+
+    /// Exact-match parse of a family literal. Model-id → family RESOLUTION
+    /// (`getModelFamily`) lives in `cma-request::model_map`, not here.
+    pub fn parse(value: &str) -> Option<Self> {
+        MODEL_FAMILIES
+            .iter()
+            .copied()
+            .find(|family| family.as_str() == value)
+    }
+}
+
+impl std::fmt::Display for ModelFamily {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Error returned by [`ModelFamily`]'s `FromStr` for unknown literals.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UnknownModelFamilyError(pub String);
+
+impl std::fmt::Display for UnknownModelFamilyError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "unknown model family: {}", self.0)
+    }
+}
+
+impl std::error::Error for UnknownModelFamilyError {}
+
+impl std::str::FromStr for ModelFamily {
+    type Err = UnknownModelFamilyError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        ModelFamily::parse(s).ok_or_else(|| UnknownModelFamilyError(s.to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn model_families_are_ordered_exactly_as_ts() {
+        let literals: Vec<&str> = MODEL_FAMILIES.iter().map(|f| f.as_str()).collect();
+        assert_eq!(
+            literals,
+            vec!["gpt-5-codex", "codex-max", "codex", "gpt-5.2", "gpt-5.1"]
+        );
+    }
+
+    #[test]
+    fn default_models_match_ts() {
+        assert_eq!(DEFAULT_MODEL, "gpt-5.5");
+        assert_eq!(DEFAULT_PROBE_MODEL, "gpt-5.6-sol");
+    }
+
+    #[test]
+    fn serde_renames_are_exact() {
+        assert_eq!(
+            serde_json::to_string(&ModelFamily::Gpt5Codex).unwrap(),
+            "\"gpt-5-codex\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ModelFamily::CodexMax).unwrap(),
+            "\"codex-max\""
+        );
+        assert_eq!(serde_json::to_string(&ModelFamily::Codex).unwrap(), "\"codex\"");
+        assert_eq!(
+            serde_json::to_string(&ModelFamily::Gpt5_2).unwrap(),
+            "\"gpt-5.2\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ModelFamily::Gpt5_1).unwrap(),
+            "\"gpt-5.1\""
+        );
+
+        for family in MODEL_FAMILIES {
+            let round: ModelFamily =
+                serde_json::from_str(&serde_json::to_string(&family).unwrap()).unwrap();
+            assert_eq!(round, family);
+        }
+    }
+
+    #[test]
+    fn parse_is_exact_match_only() {
+        assert_eq!(ModelFamily::parse("gpt-5.2"), Some(ModelFamily::Gpt5_2));
+        assert_eq!(ModelFamily::parse("codex"), Some(ModelFamily::Codex));
+        // No alias resolution in core — "gpt-5.3-codex" is a MODEL, not a family.
+        assert_eq!(ModelFamily::parse("gpt-5.3-codex"), None);
+        assert_eq!(ModelFamily::parse("GPT-5.2"), None);
+        assert_eq!(ModelFamily::parse(""), None);
+    }
+
+    #[test]
+    fn from_str_round_trips_display() {
+        for family in MODEL_FAMILIES {
+            let parsed: ModelFamily = family.to_string().parse().unwrap();
+            assert_eq!(parsed, family);
+        }
+        assert!("gpt-6".parse::<ModelFamily>().is_err());
+    }
+}
diff --git a/crates/core/src/runtime_paths.rs b/crates/core/src/runtime_paths.rs
new file mode 100644
index 000000000..8576510c7
--- /dev/null
+++ b/crates/core/src/runtime_paths.rs
@@ -0,0 +1,774 @@
+//! Port of `lib/runtime-paths.ts` — codex home / multi-auth directory
+//! resolution, including the CRITICAL storage-root probing ladder.
+//!
+//! Behavior source: specs/02-storage.md §2.1–§2.4 (port exactly) and
+//! specs/01-foundation.md §4.0.
+//!
+//! Contracts:
+//! - Home resolution (win32): first non-empty (trimmed) of `USERPROFILE`,
+//!   `HOME`, `HOMEDRIVE`+`HOMEPATH` (win32-resolved, only when BOTH
+//!   non-empty), then the OS home dir. POSIX: `HOME`, then the OS home dir.
+//! - `get_codex_home_dir` = trimmed `CODEX_HOME` if non-empty else
+//!   `<home>/.codex`.
+//! - `get_codex_multi_auth_dir` — THE storage-root selector:
+//!   1. `CODEX_MULTI_AUTH_DIR` (trimmed, non-empty) wins verbatim, no probing.
+//!   2. An explicitly non-default `CODEX_HOME` (path-normalized comparison
+//!      against `<home>/.codex`) short-circuits to `<codexHome>/multi-auth`.
+//!   3. Otherwise probe ordered candidates for real account storage
+//!      (`has_accounts_storage`), then for storage signals
+//!      (`has_storage_signals`) — primary first, then fallbacks — finally
+//!      defaulting to the primary.
+//! - Windows path dedupe/comparison is case-insensitive; returned paths
+//!   preserve their original casing.
+//! - Env vars are read on EVERY call (no caching) — matching the TS module.
+//!
+//! Testability note: the TS tests mock `process.env`/`os.homedir`; mutating
+//! process env in Rust 2024 is `unsafe` (denied workspace-wide), so the
+//! resolution logic is factored over an explicit [`RuntimePathEnv`] snapshot
+//! and tests construct fake snapshots instead. The public functions read the
+//! real process environment.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+const ACCOUNT_STORAGE_FILES: &[&str] = &["openai-codex-accounts.json", "codex-accounts.json"];
+
+const STORAGE_SIGNAL_FILES: &[&str] = &[
+    "openai-codex-accounts.json",
+    "codex-accounts.json",
+    "settings.json",
+    "config.json",
+    "dashboard-settings.json",
+];
+
+// ---------------------------------------------------------------------------
+// Environment snapshot
+// ---------------------------------------------------------------------------
+
+/// Snapshot of the environment inputs used by path resolution. Public
+/// functions build one from the live process environment per call; tests
+/// build synthetic ones.
+#[derive(Debug, Clone, Default)]
+struct RuntimePathEnv {
+    codex_home: Option<String>,
+    codex_multi_auth_dir: Option<String>,
+    userprofile: Option<String>,
+    home: Option<String>,
+    homedrive: Option<String>,
+    homepath: Option<String>,
+    /// `os.homedir()` analogue (`home::home_dir()`), pre-resolved.
+    os_homedir: Option<String>,
+}
+
+impl RuntimePathEnv {
+    fn from_process() -> Self {
+        fn env(name: &str) -> Option<String> {
+            std::env::var(name).ok()
+        }
+        Self {
+            codex_home: env("CODEX_HOME"),
+            codex_multi_auth_dir: env("CODEX_MULTI_AUTH_DIR"),
+            userprofile: env("USERPROFILE"),
+            home: env("HOME"),
+            homedrive: env("HOMEDRIVE"),
+            homepath: env("HOMEPATH"),
+            os_homedir: home::home_dir().map(|p| p.to_string_lossy().into_owned()),
+        }
+    }
+}
+
+fn first_non_empty(values: &[Option<&str>]) -> Option<String> {
+    for value in values {
+        let trimmed = value.unwrap_or("").trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+    }
+    None
+}
+
+fn join_str(base: &str, segment: &str) -> String {
+    Path::new(base).join(segment).to_string_lossy().into_owned()
+}
+
+fn resolved_user_home_dir(env: &RuntimePathEnv) -> String {
+    let os_home = env.os_homedir.clone().unwrap_or_default();
+    if cfg!(windows) {
+        let home_drive = env.homedrive.as_deref().unwrap_or("").trim();
+        let home_path = env.homepath.as_deref().unwrap_or("").trim();
+        let drive_path_home = if !home_drive.is_empty() && !home_path.is_empty() {
+            Some(resolve_drive_path(home_drive, home_path))
+        } else {
+            None
+        };
+        first_non_empty(&[
+            env.userprofile.as_deref(),
+            env.home.as_deref(),
+            drive_path_home.as_deref(),
+            Some(os_home.as_str()),
+        ])
+        .unwrap_or(os_home)
+    } else {
+        first_non_empty(&[env.home.as_deref(), Some(os_home.as_str())]).unwrap_or(os_home)
+    }
+}
+
+/// `win32.resolve("<drive>\\", homePath)` analogue: a rooted-but-driveless
+/// `homePath` (`\Users\x`) and a relative one (`Users\x`) both resolve under
+/// the drive; an already drive-rooted `homePath` (`F:\x`) wins outright, as
+/// `win32.resolve` stops at the first absolute segment from the right;
+/// separators normalize to backslashes.
+fn resolve_drive_path(drive: &str, home_path: &str) -> String {
+    let chars: Vec<char> = home_path.chars().take(3).collect();
+    if chars.len() >= 3 && chars[0].is_ascii_alphabetic() && chars[1] == ':' && (chars[2] == '\\' || chars[2] == '/') {
+        return normalize_win32(home_path);
+    }
+    let stripped = home_path.trim_start_matches(['\\', '/']);
+    normalize_win32(&format!("{drive}\\{stripped}"))
+}
+
+// ---------------------------------------------------------------------------
+// Path normalization (Node path.normalize analogues, used only for
+// comparison/dedupe — returned paths keep their original form)
+// ---------------------------------------------------------------------------
+
+fn split_win32_root(s: &str) -> (String, String) {
+    let bytes: Vec<char> = s.chars().collect();
+    // UNC: \\server\share\
+    if let Some(rest) = s.strip_prefix("\\\\") {
+        if let Some(server_end) = rest.find('\\') {
+            let after_server = &rest[server_end + 1..];
+            if let Some(share_end) = after_server.find('\\') {
+                let root_len = 2 + server_end + 1 + share_end + 1;
+                return (s[..root_len].to_string(), s[root_len..].to_string());
+            }
+            return (s.to_string(), String::new());
+        }
+        return (s.to_string(), String::new());
+    }
+    // Drive: C: or C:\
+    if bytes.len() >= 2 && bytes[0].is_ascii_alphabetic() && bytes[1] == ':' {
+        if bytes.len() >= 3 && (bytes[2] == '\\' || bytes[2] == '/') {
+            return (format!("{}{}\\", bytes[0], bytes[1]), s[3..].to_string());
+        }
+        return (format!("{}{}", bytes[0], bytes[1]), s[2..].to_string());
+    }
+    // Rooted without drive: \foo
+    if s.starts_with('\\') || s.starts_with('/') {
+        return ("\\".to_string(), s[1..].to_string());
+    }
+    (String::new(), s.to_string())
+}
+
+/// `path.win32.normalize` analogue (sufficient for root comparison): converts
+/// `/` to `\`, collapses separators, resolves `.` and `..` segments.
+fn normalize_win32(input: &str) -> String {
+    let converted: String = input
+        .chars()
+        .map(|c| if c == '/' { '\\' } else { c })
+        .collect();
+    let (root, rest) = split_win32_root(&converted);
+    let mut components: Vec<&str> = Vec::new();
+    for part in rest.split('\\') {
+        if part.is_empty() || part == "." {
+            continue;
+        }
+        if part == ".." {
+            match components.last() {
+                Some(last) if *last != ".." => {
+                    components.pop();
+                }
+                _ if root.is_empty() => components.push(".."),
+                _ => {} // ".." at an absolute root is dropped
+            }
+        } else {
+            components.push(part);
+        }
+    }
+    let joined = components.join("\\");
+    if root.is_empty() {
+        if joined.is_empty() {
+            ".".to_string()
+        } else {
+            joined
+        }
+    } else {
+        format!("{root}{joined}")
+    }
+}
+
+/// `path.posix.normalize` analogue (same scope as [`normalize_win32`]).
+fn normalize_posix(input: &str) -> String {
+    let absolute = input.starts_with('/');
+    let mut components: Vec<&str> = Vec::new();
+    for part in input.split('/') {
+        if part.is_empty() || part == "." {
+            continue;
+        }
+        if part == ".." {
+            match components.last() {
+                Some(last) if *last != ".." => {
+                    components.pop();
+                }
+                _ if !absolute => components.push(".."),
+                _ => {}
+            }
+        } else {
+            components.push(part);
+        }
+    }
+    let joined = components.join("/");
+    if absolute {
+        format!("/{joined}")
+    } else if joined.is_empty() {
+        ".".to_string()
+    } else {
+        joined
+    }
+}
+
+fn normalize_path_for_compare(value: &str) -> String {
+    let trimmed = value.trim();
+    if cfg!(windows) {
+        let normalized = normalize_win32(trimmed);
+        let (root, _) = split_win32_root(&normalized);
+        let without_trailing = if normalized == root {
+            normalized
+        } else {
+            normalized.trim_end_matches(['\\', '/']).to_string()
+        };
+        without_trailing.to_lowercase()
+    } else {
+        let normalized = normalize_posix(trimmed);
+        if normalized == "/" {
+            normalized
+        } else {
+            normalized.trim_end_matches('/').to_string()
+        }
+    }
+}
+
+fn paths_equal_normalized(a: &str, b: &str) -> bool {
+    normalize_path_for_compare(a) == normalize_path_for_compare(b)
+}
+
+/// Deduplicate path strings preserving first-seen order; entries are trimmed,
+/// empties dropped, and comparison is case-insensitive on Windows.
+fn deduplicate_paths(paths: Vec<String>) -> Vec<String> {
+    let mut seen = std::collections::HashSet::new();
+    let mut result = Vec::new();
+    for candidate in paths {
+        let trimmed = candidate.trim().to_string();
+        if trimmed.is_empty() {
+            continue;
+        }
+        let key = if cfg!(windows) {
+            trimmed.to_lowercase()
+        } else {
+            trimmed.clone()
+        };
+        if seen.insert(key) {
+            result.push(trimmed);
+        }
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Storage probes
+// ---------------------------------------------------------------------------
+
+fn has_storage_signals(dir: &Path) -> bool {
+    for signal in STORAGE_SIGNAL_FILES {
+        if dir.join(signal).exists() {
+            return true;
+        }
+    }
+    dir.join("projects").exists()
+}
+
+fn has_accounts_storage(dir: &Path) -> bool {
+    for file_name in ACCOUNT_STORAGE_FILES {
+        if dir.join(file_name).exists() {
+            return true;
+        }
+        if dir.join(format!("{file_name}.wal")).exists() {
+            return true;
+        }
+    }
+
+    if let Ok(entries) = fs::read_dir(dir) {
+        for entry in entries.flatten() {
+            // Node `withFileTypes` dirent.isFile() does not follow symlinks;
+            // DirEntry::file_type matches that.
+            let is_file = entry.file_type().map(|t| t.is_file()).unwrap_or(false);
+            if !is_file {
+                continue;
+            }
+            let name = entry.file_name().to_string_lossy().into_owned();
+            for file_name in ACCOUNT_STORAGE_FILES {
+                if !name.starts_with(&format!("{file_name}.")) {
+                    continue;
+                }
+                if name.ends_with(".tmp") {
+                    continue;
+                }
+                if name.contains(".rotate.") {
+                    continue;
+                }
+                return true;
+            }
+        }
+    }
+    // Unreadable directories are ignored and fall back to the known probes.
+    false
+}
+
+// ---------------------------------------------------------------------------
+// Resolution (env-snapshot core)
+// ---------------------------------------------------------------------------
+
+fn codex_home_dir_with(env: &RuntimePathEnv) -> String {
+    let from_env = env.codex_home.as_deref().unwrap_or("").trim();
+    if !from_env.is_empty() {
+        from_env.to_string()
+    } else {
+        join_str(&resolved_user_home_dir(env), ".codex")
+    }
+}
+
+fn legacy_codex_dir_with(env: &RuntimePathEnv) -> String {
+    join_str(&resolved_user_home_dir(env), ".codex")
+}
+
+fn fallback_codex_home_dirs(env: &RuntimePathEnv) -> Vec<String> {
+    let user_home = resolved_user_home_dir(env);
+    let devtools = Path::new(&user_home)
+        .join("DevTools")
+        .join("config")
+        .join("codex")
+        .to_string_lossy()
+        .into_owned();
+    deduplicate_paths(vec![
+        codex_home_dir_with(env),
+        devtools,
+        join_str(&user_home, ".codex"),
+    ])
+}
+
+fn codex_multi_auth_dir_with(env: &RuntimePathEnv) -> String {
+    let from_env = env.codex_multi_auth_dir.as_deref().unwrap_or("").trim();
+    if !from_env.is_empty() {
+        return from_env.to_string();
+    }
+
+    let codex_home_from_env = env.codex_home.as_deref().unwrap_or("").trim();
+    let default_codex_home = join_str(&resolved_user_home_dir(env), ".codex");
+    let is_explicit_non_default_home = !codex_home_from_env.is_empty()
+        && !paths_equal_normalized(codex_home_from_env, &default_codex_home);
+
+    let primary = join_str(&codex_home_dir_with(env), "multi-auth");
+    let mut fallback_inputs: Vec<String> = fallback_codex_home_dirs(env)
+        .into_iter()
+        .map(|dir| join_str(&dir, "multi-auth"))
+        .collect();
+    fallback_inputs.push(legacy_codex_dir_with(env));
+    let fallback_candidates = deduplicate_paths(fallback_inputs);
+
+    let mut ordered_inputs = vec![primary.clone()];
+    ordered_inputs.extend(fallback_candidates.iter().cloned());
+    let ordered_candidates = deduplicate_paths(ordered_inputs);
+
+    if is_explicit_non_default_home {
+        return primary;
+    }
+
+    // Prefer candidates that actually contain account storage. This prevents
+    // accidentally switching to a fresh empty directory that only has
+    // settings files.
+    for candidate in &ordered_candidates {
+        if has_accounts_storage(Path::new(candidate)) {
+            return candidate.clone();
+        }
+    }
+
+    if has_storage_signals(Path::new(&primary)) {
+        return primary;
+    }
+
+    for candidate in &fallback_candidates {
+        if *candidate == primary {
+            continue;
+        }
+        if has_storage_signals(Path::new(candidate)) {
+            return candidate.clone();
+        }
+    }
+
+    primary
+}
+
+// ---------------------------------------------------------------------------
+// Public API (reads the live process environment on every call)
+// ---------------------------------------------------------------------------
+
+/// Codex home dir: trimmed `CODEX_HOME` if non-empty, else `<home>/.codex`.
+pub fn get_codex_home_dir() -> PathBuf {
+    PathBuf::from(codex_home_dir_with(&RuntimePathEnv::from_process()))
+}
+
+/// The multi-auth storage root — full probing ladder (see module docs).
+pub fn get_codex_multi_auth_dir() -> PathBuf {
+    PathBuf::from(codex_multi_auth_dir_with(&RuntimePathEnv::from_process()))
+}
+
+/// `<multi-auth-dir>/cache`.
+pub fn get_codex_cache_dir() -> PathBuf {
+    get_codex_multi_auth_dir().join("cache")
+}
+
+/// `<multi-auth-dir>/logs`.
+pub fn get_codex_log_dir() -> PathBuf {
+    get_codex_multi_auth_dir().join("logs")
+}
+
+/// The legacy per-user dir: `<home>/.codex` (independent of `CODEX_HOME`).
+pub fn get_legacy_codex_dir() -> PathBuf {
+    PathBuf::from(legacy_codex_dir_with(&RuntimePathEnv::from_process()))
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/runtime-paths.test.ts, adapted to the env-snapshot
+// seam — see module docs for why process env is not mutated)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn env_with_home(home: &str) -> RuntimePathEnv {
+        // Pin the home through the platform-appropriate variable plus the OS
+        // fallback so resolution is deterministic on both platforms.
+        RuntimePathEnv {
+            userprofile: cfg!(windows).then(|| home.to_string()),
+            home: Some(home.to_string()),
+            os_homedir: Some(home.to_string()),
+            ..Default::default()
+        }
+    }
+
+    fn touch(path: &Path) {
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        fs::write(path, "{}").unwrap();
+    }
+
+    #[test]
+    fn multi_auth_dir_env_override_wins_verbatim_without_probing() {
+        let mut env = env_with_home("/home/neil");
+        env.codex_multi_auth_dir = Some("  /custom/multi-auth  ".to_string());
+        assert_eq!(codex_multi_auth_dir_with(&env), "/custom/multi-auth");
+    }
+
+    #[test]
+    fn defaults_to_primary_when_no_storage_exists_anywhere() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let env = env_with_home(&home);
+        let expected = Path::new(&home)
+            .join(".codex")
+            .join("multi-auth")
+            .to_string_lossy()
+            .into_owned();
+        assert_eq!(codex_multi_auth_dir_with(&env), expected);
+    }
+
+    #[test]
+    fn prefers_fallback_directory_with_account_storage_over_primary_signal_only_directory() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let primary = dir.path().join(".codex").join("multi-auth");
+        let fallback = dir
+            .path()
+            .join("DevTools")
+            .join("config")
+            .join("codex")
+            .join("multi-auth");
+        touch(&primary.join("settings.json"));
+        touch(&fallback.join("openai-codex-accounts.json"));
+
+        let mut env = env_with_home(&home);
+        // Default CODEX_HOME set explicitly — still counts as default root.
+        env.codex_home = Some(
+            dir.path()
+                .join(".codex")
+                .to_string_lossy()
+                .into_owned(),
+        );
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            fallback.to_string_lossy().into_owned()
+        );
+    }
+
+    #[test]
+    fn prefers_fallback_with_recoverable_backup_artifacts_over_primary_signal_only_directory() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let primary = dir.path().join(".codex").join("multi-auth");
+        let fallback = dir
+            .path()
+            .join("DevTools")
+            .join("config")
+            .join("codex")
+            .join("multi-auth");
+        touch(&primary.join("settings.json"));
+        touch(&fallback.join(
+            "openai-codex-accounts.json.manual-before-dedupe-2026-03-03T00-25-19-753Z",
+        ));
+
+        let env = env_with_home(&home);
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            fallback.to_string_lossy().into_owned()
+        );
+    }
+
+    #[test]
+    fn readdir_probe_skips_tmp_and_rotate_artifacts() {
+        let dir = tempfile::tempdir().unwrap();
+        let probe = dir.path().join("probe");
+        touch(&probe.join("openai-codex-accounts.json.123.tmp"));
+        touch(&probe.join("openai-codex-accounts.json.rotate.abc.bak"));
+        assert!(!has_accounts_storage(&probe));
+
+        touch(&probe.join("openai-codex-accounts.json.bak"));
+        assert!(has_accounts_storage(&probe));
+    }
+
+    #[test]
+    fn wal_file_counts_as_account_storage() {
+        let dir = tempfile::tempdir().unwrap();
+        let probe = dir.path().join("probe");
+        touch(&probe.join("codex-accounts.json.wal"));
+        assert!(has_accounts_storage(&probe));
+    }
+
+    #[test]
+    fn keeps_canonical_multi_auth_root_when_codex_home_is_explicit_non_default() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let canonical_home = dir.path().join(".codex-canonical");
+        let primary = canonical_home.join("multi-auth");
+        let fallback = dir
+            .path()
+            .join("DevTools")
+            .join("config")
+            .join("codex")
+            .join("multi-auth");
+        touch(&primary.join("settings.json"));
+        touch(&fallback.join("openai-codex-accounts.json"));
+
+        let mut env = env_with_home(&home);
+        env.codex_home = Some(canonical_home.to_string_lossy().into_owned());
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            primary.to_string_lossy().into_owned()
+        );
+    }
+
+    #[test]
+    fn uses_legacy_root_when_it_is_the_only_directory_containing_account_storage() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let legacy_root = dir.path().join(".codex");
+        touch(&legacy_root.join("openai-codex-accounts.json"));
+
+        let env = env_with_home(&home);
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            legacy_root.to_string_lossy().into_owned()
+        );
+    }
+
+    #[test]
+    fn treats_default_codex_home_with_trailing_separator_as_the_default_root() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let fallback = dir
+            .path()
+            .join("DevTools")
+            .join("config")
+            .join("codex")
+            .join("multi-auth");
+        touch(&fallback.join("openai-codex-accounts.json"));
+
+        let mut env = env_with_home(&home);
+        env.codex_home = Some(format!(
+            "{}{}",
+            dir.path().join(".codex").to_string_lossy(),
+            std::path::MAIN_SEPARATOR
+        ));
+        // Default root (despite trailing separator) → probing runs → the
+        // fallback holding real account storage wins.
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            fallback.to_string_lossy().into_owned()
+        );
+    }
+
+    #[cfg(not(windows))]
+    #[test]
+    fn treats_normalized_posix_codex_home_variants_of_the_default_root_as_default() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        let fallback = dir
+            .path()
+            .join("DevTools")
+            .join("config")
+            .join("codex")
+            .join("multi-auth");
+        touch(&fallback.join("openai-codex-accounts.json"));
+
+        let mut env = env_with_home(&home);
+        env.codex_home = Some(format!("{home}/./.codex//"));
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            fallback.to_string_lossy().into_owned()
+        );
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn deduplicates_windows_style_fallback_paths_case_insensitively() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_string_lossy().into_owned();
+        // CODEX_HOME differs from the real home only by case → still default.
+        let upper_home = home.to_uppercase();
+        let primary_upper = Path::new(&upper_home).join(".codex").join("multi-auth");
+        touch(&primary_upper.join("settings.json"));
+
+        let mut env = env_with_home(&home);
+        env.codex_home = Some(
+            Path::new(&upper_home)
+                .join(".codex")
+                .to_string_lossy()
+                .into_owned(),
+        );
+        // Uppercase CODEX_HOME normalizes equal to the default root, so
+        // probing runs; primary (in its original uppercase form) has signals.
+        assert_eq!(
+            codex_multi_auth_dir_with(&env),
+            primary_upper.to_string_lossy().into_owned()
+        );
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn prefers_userprofile_over_os_homedir_on_windows_when_codex_home_unset() {
+        let env = RuntimePathEnv {
+            userprofile: Some("C:\\Users\\Alice".to_string()),
+            os_homedir: Some("C:\\Windows\\System32\\config\\systemprofile".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(codex_home_dir_with(&env), "C:\\Users\\Alice\\.codex");
+        assert_eq!(legacy_codex_dir_with(&env), "C:\\Users\\Alice\\.codex");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn falls_back_to_home_when_userprofile_is_missing_on_windows() {
+        let env = RuntimePathEnv {
+            home: Some("D:\\Users\\Bob".to_string()),
+            os_homedir: Some("C:\\Windows\\System32\\config\\systemprofile".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(codex_home_dir_with(&env), "D:\\Users\\Bob\\.codex");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn falls_back_to_homedrive_and_homepath_when_userprofile_and_home_are_missing() {
+        let env = RuntimePathEnv {
+            homedrive: Some("E:".to_string()),
+            homepath: Some("\\Users\\Carol".to_string()),
+            os_homedir: Some("C:\\Windows\\System32\\config\\systemprofile".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(codex_home_dir_with(&env), "E:\\Users\\Carol\\.codex");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn normalizes_homepath_without_a_leading_slash_on_windows() {
+        let env = RuntimePathEnv {
+            homedrive: Some("E:".to_string()),
+            homepath: Some("Users\\Carol".to_string()),
+            os_homedir: Some("C:\\Windows\\System32\\config\\systemprofile".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(codex_home_dir_with(&env), "E:\\Users\\Carol\\.codex");
+    }
+
+    #[cfg(not(windows))]
+    #[test]
+    fn prefers_home_env_over_os_homedir_on_posix() {
+        let env = RuntimePathEnv {
+            home: Some("/home/alice".to_string()),
+            os_homedir: Some("/root".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(codex_home_dir_with(&env), "/home/alice/.codex");
+        assert_eq!(legacy_codex_dir_with(&env), "/home/alice/.codex");
+    }
+
+    #[test]
+    fn derived_dirs_hang_off_the_multi_auth_root() {
+        let cache = get_codex_cache_dir();
+        let logs = get_codex_log_dir();
+        let root = get_codex_multi_auth_dir();
+        assert_eq!(cache, root.join("cache"));
+        assert_eq!(logs, root.join("logs"));
+    }
+
+    // ----- normalize helpers (compiled on all platforms) -----
+
+    #[test]
+    fn normalize_win32_resolves_dots_and_separators() {
+        assert_eq!(normalize_win32("C:\\Users\\..\\Users\\x\\"), "C:\\Users\\x");
+        assert_eq!(normalize_win32("C:/Users/./Neil//.codex/"), "C:\\Users\\Neil\\.codex");
+        assert_eq!(normalize_win32("C:\\"), "C:\\");
+        assert_eq!(normalize_win32("relative\\.\\path"), "relative\\path");
+    }
+
+    #[test]
+    fn normalize_posix_resolves_dots_and_separators() {
+        assert_eq!(normalize_posix("/home/neil/./.codex//"), "/home/neil/.codex");
+        assert_eq!(normalize_posix("/a/b/../c"), "/a/c");
+        assert_eq!(normalize_posix("/"), "/");
+        assert_eq!(normalize_posix("a/./b"), "a/b");
+    }
+
+    #[test]
+    fn dedupe_preserves_first_seen_order_and_trims() {
+        let input = vec![
+            "  /a/b ".to_string(),
+            "/a/b".to_string(),
+            "".to_string(),
+            "/c".to_string(),
+        ];
+        assert_eq!(
+            deduplicate_paths(input),
+            vec!["/a/b".to_string(), "/c".to_string()]
+        );
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn dedupe_is_case_insensitive_on_windows() {
+        let input = vec![
+            "C:\\Users\\Neil".to_string(),
+            "c:\\users\\neil".to_string(),
+        ];
+        assert_eq!(deduplicate_paths(input), vec!["C:\\Users\\Neil".to_string()]);
+    }
+}
diff --git a/crates/core/src/schemas/account_storage.rs b/crates/core/src/schemas/account_storage.rs
new file mode 100644
index 000000000..85145c81d
--- /dev/null
+++ b/crates/core/src/schemas/account_storage.rs
@@ -0,0 +1,1240 @@
+//! Account storage schemas — port of the account-storage half of
+//! `lib/schemas.ts` (spec 01 §3.2, spec 02 §3–4).
+//!
+//! Byte-compat rules honored here (spec 02 §3, ARCHITECTURE §8.1):
+//! - Serde field order == zod schema declaration order (accounts:
+//!   `accountId, accountIdSource, accountLabel, email, refreshToken,
+//!   accessToken, expiresAt, enabled, addedAt, lastUsed, lastSwitchReason,
+//!   rateLimitResetTimes, coolingDownUntil, cooldownReason, workspaces,
+//!   currentWorkspaceIndex`; top level: `version, accounts, activeIndex,
+//!   activeIndexByFamily[, pinnedAccountIndex][, affinityGeneration]`).
+//! - `None` optionals are omitted (`skip_serializing_if`), mirroring
+//!   `JSON.stringify` dropping `undefined` values.
+//! - `workspaces`/`currentWorkspaceIndex` MUST be part of the schema or a
+//!   strict-strip parse silently erases workspace tracking on every load
+//!   round-trip (#491).
+//! - `version: 3` / `version: 1` are literal-checked at deserialization time.
+//! - [`RateLimitStateV3`] preserves key insertion order with JS object
+//!   semantics (re-assigning an existing key keeps its position).
+//!
+//! Zod-bound enforcement (whole-parse failure on violation, like
+//! `safeParse`): `refreshToken` non-empty, `activeIndex >= 0`,
+//! `pinnedAccountIndex`/`affinityGeneration` non-negative integers.
+//! Unknown keys are ignored on parse (zod strips them) — including V3-only
+//! keys appearing in V1 payloads.
+
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+use super::parse::{
+    Version1, Version3, de_number_lenient, de_number_min0_lenient, de_opt_int_min0_strict,
+    de_opt_number_lenient, de_opt_strict, de_string_min1, number_to_i64_lossy,
+};
+use crate::model_family::ModelFamily;
+
+// ============================================================================
+// Enums (spec 01 §3.2; also ARCHITECTURE §4 item 4 — these live in core)
+// ============================================================================
+
+/// Source of the accountId used for ChatGPT requests.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum AccountIdSource {
+    #[serde(rename = "token")]
+    Token,
+    #[serde(rename = "id_token")]
+    IdToken,
+    #[serde(rename = "org")]
+    Org,
+    #[serde(rename = "manual")]
+    Manual,
+}
+
+impl AccountIdSource {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Token => "token",
+            Self::IdToken => "id_token",
+            Self::Org => "org",
+            Self::Manual => "manual",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "token" => Some(Self::Token),
+            "id_token" => Some(Self::IdToken),
+            "org" => Some(Self::Org),
+            "manual" => Some(Self::Manual),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for AccountIdSource {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Cooldown reason for temporary account suspension.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum CooldownReason {
+    #[serde(rename = "auth-failure")]
+    AuthFailure,
+    #[serde(rename = "network-error")]
+    NetworkError,
+    #[serde(rename = "server-error")]
+    ServerError,
+    #[serde(rename = "rate-limit")]
+    RateLimit,
+}
+
+impl CooldownReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::AuthFailure => "auth-failure",
+            Self::NetworkError => "network-error",
+            Self::ServerError => "server-error",
+            Self::RateLimit => "rate-limit",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "auth-failure" => Some(Self::AuthFailure),
+            "network-error" => Some(Self::NetworkError),
+            "server-error" => Some(Self::ServerError),
+            "rate-limit" => Some(Self::RateLimit),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for CooldownReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Last switch reason for account rotation tracking.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum SwitchReason {
+    #[serde(rename = "rate-limit")]
+    RateLimit,
+    #[serde(rename = "initial")]
+    Initial,
+    #[serde(rename = "rotation")]
+    Rotation,
+    #[serde(rename = "best")]
+    Best,
+    #[serde(rename = "restore")]
+    Restore,
+    #[serde(rename = "manual")]
+    Manual,
+}
+
+impl SwitchReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::RateLimit => "rate-limit",
+            Self::Initial => "initial",
+            Self::Rotation => "rotation",
+            Self::Best => "best",
+            Self::Restore => "restore",
+            Self::Manual => "manual",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "rate-limit" => Some(Self::RateLimit),
+            "initial" => Some(Self::Initial),
+            "rotation" => Some(Self::Rotation),
+            "best" => Some(Self::Best),
+            "restore" => Some(Self::Restore),
+            "manual" => Some(Self::Manual),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for SwitchReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Switch reasons that callers may pass to `persistAndSyncSelectedAccount`.
+/// Excludes the runtime-internal reasons (`rate-limit`, `initial`) which are
+/// recorded by `markSwitched` but never originate from the CLI persist path.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum PersistedSwitchReason {
+    #[serde(rename = "rotation")]
+    Rotation,
+    #[serde(rename = "best")]
+    Best,
+    #[serde(rename = "restore")]
+    Restore,
+    #[serde(rename = "manual")]
+    Manual,
+}
+
+impl PersistedSwitchReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Rotation => "rotation",
+            Self::Best => "best",
+            Self::Restore => "restore",
+            Self::Manual => "manual",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "rotation" => Some(Self::Rotation),
+            "best" => Some(Self::Best),
+            "restore" => Some(Self::Restore),
+            "manual" => Some(Self::Manual),
+            _ => None,
+        }
+    }
+}
+
+impl From<PersistedSwitchReason> for SwitchReason {
+    fn from(value: PersistedSwitchReason) -> Self {
+        match value {
+            PersistedSwitchReason::Rotation => Self::Rotation,
+            PersistedSwitchReason::Best => Self::Best,
+            PersistedSwitchReason::Restore => Self::Restore,
+            PersistedSwitchReason::Manual => Self::Manual,
+        }
+    }
+}
+
+impl std::fmt::Display for PersistedSwitchReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Classified 429 cause — `lib/accounts/rate-limits.ts`
+/// `RateLimitReason = "quota" | "tokens" | "concurrent" | "unknown"`.
+/// (The classifier `parse_rate_limit_reason` lives in the accounts crate;
+/// only the enum is core vocabulary — ARCHITECTURE §4 item 4.)
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum RateLimitReason {
+    #[serde(rename = "quota")]
+    Quota,
+    #[serde(rename = "tokens")]
+    Tokens,
+    #[serde(rename = "concurrent")]
+    Concurrent,
+    #[serde(rename = "unknown")]
+    Unknown,
+}
+
+impl RateLimitReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Quota => "quota",
+            Self::Tokens => "tokens",
+            Self::Concurrent => "concurrent",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "quota" => Some(Self::Quota),
+            "tokens" => Some(Self::Tokens),
+            "concurrent" => Some(Self::Concurrent),
+            "unknown" => Some(Self::Unknown),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for RateLimitReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+// ============================================================================
+// RateLimitStateV3 — ordered map: quota key -> epoch-ms reset time
+// ============================================================================
+
+/// `RateLimitStateV3 = Record<string, number|undefined>` with preserved key
+/// insertion order and JS object assignment semantics: setting an existing
+/// key keeps its original position; new keys append. Values are epoch-ms
+/// timestamps modeled as `i64` (architecture R9: epochs never gain a decimal
+/// point). Deserialization requires every value to be a JSON number,
+/// mirroring `z.record(z.string(), z.number().optional())` — a non-number
+/// value fails the whole parse.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct RateLimitStateV3 {
+    entries: Vec<(String, i64)>,
+}
+
+impl RateLimitStateV3 {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn get(&self, key: &str) -> Option<i64> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, v)| *v)
+    }
+
+    pub fn contains_key(&self, key: &str) -> bool {
+        self.entries.iter().any(|(k, _)| k == key)
+    }
+
+    /// JS `obj[key] = value`: replaces in place (keeping position) when the
+    /// key exists, otherwise appends. Returns the previous value if any.
+    pub fn insert(&mut self, key: impl Into<String>, value: i64) -> Option<i64> {
+        let key = key.into();
+        if let Some(entry) = self.entries.iter_mut().find(|(k, _)| *k == key) {
+            let previous = entry.1;
+            entry.1 = value;
+            Some(previous)
+        } else {
+            self.entries.push((key, value));
+            None
+        }
+    }
+
+    /// JS `delete obj[key]`. Returns the removed value if the key existed.
+    pub fn remove(&mut self, key: &str) -> Option<i64> {
+        let index = self.entries.iter().position(|(k, _)| k == key)?;
+        Some(self.entries.remove(index).1)
+    }
+
+    /// Keep only the entries for which the predicate returns `true`.
+    pub fn retain(&mut self, mut predicate: impl FnMut(&str, i64) -> bool) {
+        self.entries.retain(|(k, v)| predicate(k, *v));
+    }
+
+    pub fn keys(&self) -> impl Iterator<Item = &str> {
+        self.entries.iter().map(|(k, _)| k.as_str())
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, i64)> {
+        self.entries.iter().map(|(k, v)| (k.as_str(), *v))
+    }
+
+    pub fn entries(&self) -> &[(String, i64)] {
+        &self.entries
+    }
+
+    pub fn clear(&mut self) {
+        self.entries.clear();
+    }
+}
+
+impl FromIterator<(String, i64)> for RateLimitStateV3 {
+    fn from_iter<T: IntoIterator<Item = (String, i64)>>(iter: T) -> Self {
+        let mut state = Self::new();
+        for (key, value) in iter {
+            state.insert(key, value);
+        }
+        state
+    }
+}
+
+impl<'a> IntoIterator for &'a RateLimitStateV3 {
+    type Item = &'a (String, i64);
+    type IntoIter = std::slice::Iter<'a, (String, i64)>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.entries.iter()
+    }
+}
+
+impl Serialize for RateLimitStateV3 {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeMap;
+        let mut map = serializer.serialize_map(Some(self.entries.len()))?;
+        for (key, value) in &self.entries {
+            map.serialize_entry(key, value)?;
+        }
+        map.end()
+    }
+}
+
+impl<'de> Deserialize<'de> for RateLimitStateV3 {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        struct MapVisitor;
+
+        impl<'de> serde::de::Visitor<'de> for MapVisitor {
+            type Value = RateLimitStateV3;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                formatter.write_str("a map of string keys to numbers")
+            }
+
+            fn visit_map<A: serde::de::MapAccess<'de>>(
+                self,
+                mut access: A,
+            ) -> Result<Self::Value, A::Error> {
+                let mut state = RateLimitStateV3::new();
+                while let Some((key, value)) = access.next_entry::<String, serde_json::Number>()? {
+                    state.insert(key, number_to_i64_lossy(&value));
+                }
+                Ok(state)
+            }
+        }
+
+        deserializer.deserialize_map(MapVisitor)
+    }
+}
+
+// ============================================================================
+// Workspace (#491)
+// ============================================================================
+
+/// Workspace entry within an account. Supports a single OpenAI account that
+/// belongs to multiple ChatGPT workspaces, each a distinct quota pool keyed
+/// by its org_id (`id`). See #491.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Workspace {
+    pub id: String,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub name: Option<String>,
+    pub enabled: bool,
+    #[serde(
+        rename = "disabledAt",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub disabled_at: Option<i64>,
+    #[serde(
+        rename = "isDefault",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub is_default: Option<bool>,
+}
+
+// ============================================================================
+// AccountMetadataV3 / AccountStorageV3
+// ============================================================================
+
+/// Account metadata V3 — current storage format. Field order and optionality
+/// mirror `AccountMetadataV3Schema` exactly (spec 01 §3.2).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AccountMetadataV3 {
+    #[serde(
+        rename = "accountId",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id: Option<String>,
+    #[serde(
+        rename = "accountIdSource",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id_source: Option<AccountIdSource>,
+    #[serde(
+        rename = "accountLabel",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_label: Option<String>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub email: Option<String>,
+    /// Required, non-empty (`z.string().min(1)`).
+    #[serde(rename = "refreshToken", deserialize_with = "de_string_min1")]
+    pub refresh_token: String,
+    #[serde(
+        rename = "accessToken",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub access_token: Option<String>,
+    #[serde(
+        rename = "expiresAt",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub expires_at: Option<i64>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub enabled: Option<bool>,
+    /// Required, ms epoch.
+    #[serde(rename = "addedAt", deserialize_with = "de_number_lenient")]
+    pub added_at: i64,
+    /// Required, ms epoch.
+    #[serde(rename = "lastUsed", deserialize_with = "de_number_lenient")]
+    pub last_used: i64,
+    #[serde(
+        rename = "lastSwitchReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_switch_reason: Option<SwitchReason>,
+    #[serde(
+        rename = "rateLimitResetTimes",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub rate_limit_reset_times: Option<RateLimitStateV3>,
+    #[serde(
+        rename = "coolingDownUntil",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooling_down_until: Option<i64>,
+    #[serde(
+        rename = "cooldownReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooldown_reason: Option<CooldownReason>,
+    /// Multi-workspace support (#491): without these two fields in the
+    /// schema, a strict-strip parse erases workspace tracking on every
+    /// load/save round-trip.
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub workspaces: Option<Vec<Workspace>>,
+    #[serde(
+        rename = "currentWorkspaceIndex",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub current_workspace_index: Option<i64>,
+}
+
+impl AccountMetadataV3 {
+    /// Minimal valid account (the three required fields), everything else
+    /// unset.
+    pub fn new(refresh_token: impl Into<String>, added_at: i64, last_used: i64) -> Self {
+        Self {
+            account_id: None,
+            account_id_source: None,
+            account_label: None,
+            email: None,
+            refresh_token: refresh_token.into(),
+            access_token: None,
+            expires_at: None,
+            enabled: None,
+            added_at,
+            last_used,
+            last_switch_reason: None,
+            rate_limit_reset_times: None,
+            cooling_down_until: None,
+            cooldown_reason: None,
+            workspaces: None,
+            current_workspace_index: None,
+        }
+    }
+
+    /// TS convention: `account.enabled !== false` (missing means enabled).
+    pub fn is_enabled(&self) -> bool {
+        self.enabled != Some(false)
+    }
+}
+
+/// Per-family active index map — object schema with one optional-number key
+/// per `MODEL_FAMILIES` entry (`.partial()`); unknown keys are stripped on
+/// parse. Serialized key order is the family declaration order.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ActiveIndexByFamily {
+    #[serde(
+        rename = "gpt-5-codex",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub gpt5_codex: Option<i64>,
+    #[serde(
+        rename = "codex-max",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub codex_max: Option<i64>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub codex: Option<i64>,
+    #[serde(
+        rename = "gpt-5.2",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub gpt5_2: Option<i64>,
+    #[serde(
+        rename = "gpt-5.1",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub gpt5_1: Option<i64>,
+}
+
+impl ActiveIndexByFamily {
+    pub fn get(&self, family: ModelFamily) -> Option<i64> {
+        match family {
+            ModelFamily::Gpt5Codex => self.gpt5_codex,
+            ModelFamily::CodexMax => self.codex_max,
+            ModelFamily::Codex => self.codex,
+            ModelFamily::Gpt5_2 => self.gpt5_2,
+            ModelFamily::Gpt5_1 => self.gpt5_1,
+        }
+    }
+
+    pub fn set(&mut self, family: ModelFamily, index: Option<i64>) {
+        match family {
+            ModelFamily::Gpt5Codex => self.gpt5_codex = index,
+            ModelFamily::CodexMax => self.codex_max = index,
+            ModelFamily::Codex => self.codex = index,
+            ModelFamily::Gpt5_2 => self.gpt5_2 = index,
+            ModelFamily::Gpt5_1 => self.gpt5_1 = index,
+        }
+    }
+
+    /// Iterate all five family slots in declaration (= serialization) order.
+    pub fn iter(&self) -> impl Iterator<Item = (ModelFamily, Option<i64>)> + '_ {
+        [
+            (ModelFamily::Gpt5Codex, self.gpt5_codex),
+            (ModelFamily::CodexMax, self.codex_max),
+            (ModelFamily::Codex, self.codex),
+            (ModelFamily::Gpt5_2, self.gpt5_2),
+            (ModelFamily::Gpt5_1, self.gpt5_1),
+        ]
+        .into_iter()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.iter().all(|(_, index)| index.is_none())
+    }
+}
+
+/// Account storage V3 — current storage format with per-family active
+/// indices, manual pin (#474) and affinity generation counter (#474).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AccountStorageV3 {
+    /// Literal `3`.
+    pub version: Version3,
+    pub accounts: Vec<AccountMetadataV3>,
+    /// Required, `>= 0` (`z.number().min(0)`).
+    #[serde(rename = "activeIndex", deserialize_with = "de_number_min0_lenient")]
+    pub active_index: i64,
+    #[serde(
+        rename = "activeIndexByFamily",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub active_index_by_family: Option<ActiveIndexByFamily>,
+    /// Optional int `>= 0` — manual pin (#474).
+    #[serde(
+        rename = "pinnedAccountIndex",
+        default,
+        deserialize_with = "de_opt_int_min0_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub pinned_account_index: Option<i64>,
+    /// Optional int `>= 0` — monotonic counter (#474).
+    #[serde(
+        rename = "affinityGeneration",
+        default,
+        deserialize_with = "de_opt_int_min0_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub affinity_generation: Option<i64>,
+}
+
+impl AccountStorageV3 {
+    /// Empty storage (`{version:3, accounts:[], activeIndex:0}`).
+    pub fn empty() -> Self {
+        Self {
+            version: Version3::default(),
+            accounts: Vec::new(),
+            active_index: 0,
+            active_index_by_family: None,
+            pinned_account_index: None,
+            affinity_generation: None,
+        }
+    }
+}
+
+// ============================================================================
+// Legacy V1 shapes (read-only; auto-migrated by the storage crate)
+// ============================================================================
+
+/// Legacy V1 account metadata for migration support (scalar
+/// `rateLimitResetTime` instead of the per-family map; no workspaces).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AccountMetadataV1 {
+    #[serde(
+        rename = "accountId",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id: Option<String>,
+    #[serde(
+        rename = "accountIdSource",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id_source: Option<AccountIdSource>,
+    #[serde(
+        rename = "accountLabel",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_label: Option<String>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub email: Option<String>,
+    #[serde(rename = "refreshToken", deserialize_with = "de_string_min1")]
+    pub refresh_token: String,
+    #[serde(
+        rename = "accessToken",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub access_token: Option<String>,
+    #[serde(
+        rename = "expiresAt",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub expires_at: Option<i64>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub enabled: Option<bool>,
+    #[serde(rename = "addedAt", deserialize_with = "de_number_lenient")]
+    pub added_at: i64,
+    #[serde(rename = "lastUsed", deserialize_with = "de_number_lenient")]
+    pub last_used: i64,
+    #[serde(
+        rename = "lastSwitchReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_switch_reason: Option<SwitchReason>,
+    /// V1 used a single scalar reset time.
+    #[serde(
+        rename = "rateLimitResetTime",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub rate_limit_reset_time: Option<i64>,
+    #[serde(
+        rename = "coolingDownUntil",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooling_down_until: Option<i64>,
+    #[serde(
+        rename = "cooldownReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooldown_reason: Option<CooldownReason>,
+}
+
+/// Legacy V1 storage format for migration support.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AccountStorageV1 {
+    /// Literal `1`.
+    pub version: Version1,
+    pub accounts: Vec<AccountMetadataV1>,
+    #[serde(rename = "activeIndex", deserialize_with = "de_number_min0_lenient")]
+    pub active_index: i64,
+}
+
+// ============================================================================
+// AnyAccountStorage — discriminated union on `version` (1 | 3)
+// ============================================================================
+
+/// Union of V1 and V3 storage formats for migration detection. Manual
+/// deserializer discriminating on the `version` key: `1` → V1, `3` → V3,
+/// anything else fails (zod discriminated-union semantics).
+#[derive(Clone, Debug, PartialEq)]
+pub enum AnyAccountStorage {
+    V1(AccountStorageV1),
+    V3(AccountStorageV3),
+}
+
+impl AnyAccountStorage {
+    pub fn version(&self) -> u8 {
+        match self {
+            Self::V1(_) => 1,
+            Self::V3(_) => 3,
+        }
+    }
+}
+
+impl Serialize for AnyAccountStorage {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        match self {
+            Self::V1(storage) => storage.serialize(serializer),
+            Self::V3(storage) => storage.serialize(serializer),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for AnyAccountStorage {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = serde_json::Value::deserialize(deserializer)?;
+        let version = value.get("version").and_then(serde_json::Value::as_f64);
+        if version == Some(1.0) {
+            AccountStorageV1::deserialize(value)
+                .map(Self::V1)
+                .map_err(serde::de::Error::custom)
+        } else if version == Some(3.0) {
+            AccountStorageV3::deserialize(value)
+                .map(Self::V3)
+                .map_err(serde::de::Error::custom)
+        } else {
+            Err(serde::de::Error::custom(
+                "Invalid input: expected version 1 or 3",
+            ))
+        }
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts account-storage suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn valid_account() -> serde_json::Value {
+        json!({
+            "refreshToken": "rt_valid_token",
+            "addedAt": 1700000000000i64,
+            "lastUsed": 1700000000001i64,
+        })
+    }
+
+    fn parse_account(value: serde_json::Value) -> Result<AccountMetadataV3, serde_json::Error> {
+        serde_json::from_value(value)
+    }
+
+    #[test]
+    fn accepts_minimal_valid_account() {
+        let account = parse_account(valid_account()).expect("minimal account parses");
+        assert_eq!(account.refresh_token, "rt_valid_token");
+        assert_eq!(account.added_at, 1_700_000_000_000);
+        assert!(account.is_enabled());
+    }
+
+    #[test]
+    fn accepts_full_account_with_all_optional_fields() {
+        let mut value = valid_account();
+        let obj = value.as_object_mut().unwrap();
+        obj.insert("accountId".into(), json!("acc_123"));
+        obj.insert("accountIdSource".into(), json!("token"));
+        obj.insert("accountLabel".into(), json!("Work Account"));
+        obj.insert("email".into(), json!("test@example.com"));
+        obj.insert("lastSwitchReason".into(), json!("rate-limit"));
+        obj.insert(
+            "rateLimitResetTimes".into(),
+            json!({ "gpt-5.2-codex": 1700000060000i64 }),
+        );
+        obj.insert("coolingDownUntil".into(), json!(1700000030000i64));
+        obj.insert("cooldownReason".into(), json!("auth-failure"));
+        let account = parse_account(value).expect("full account parses");
+        assert_eq!(account.account_id_source, Some(AccountIdSource::Token));
+        assert_eq!(account.last_switch_reason, Some(SwitchReason::RateLimit));
+        assert_eq!(account.cooldown_reason, Some(CooldownReason::AuthFailure));
+        assert_eq!(
+            account
+                .rate_limit_reset_times
+                .as_ref()
+                .and_then(|m| m.get("gpt-5.2-codex")),
+            Some(1_700_000_060_000)
+        );
+    }
+
+    #[test]
+    fn rejects_empty_refresh_token() {
+        let mut value = valid_account();
+        value["refreshToken"] = json!("");
+        assert!(parse_account(value).is_err());
+    }
+
+    #[test]
+    fn rejects_missing_refresh_token() {
+        assert!(parse_account(json!({ "addedAt": 1, "lastUsed": 1 })).is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_account_id_source() {
+        let mut value = valid_account();
+        value["accountIdSource"] = json!("invalid");
+        assert!(parse_account(value).is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_cooldown_reason() {
+        let mut value = valid_account();
+        value["cooldownReason"] = json!("unknown");
+        assert!(parse_account(value).is_err());
+    }
+
+    #[test]
+    fn preserves_workspaces_and_current_workspace_index_issue_491() {
+        let mut value = valid_account();
+        value["workspaces"] = json!([
+            { "id": "org-AAAA", "name": "Personal Plus", "enabled": true, "isDefault": true },
+            { "id": "org-BBBB", "name": "GkTech Business", "enabled": false, "disabledAt": 123 },
+        ]);
+        value["currentWorkspaceIndex"] = json!(1);
+        let account = parse_account(value).expect("parses");
+        let workspaces = account.workspaces.expect("workspaces kept");
+        assert_eq!(workspaces.len(), 2);
+        assert_eq!(workspaces[0].name.as_deref(), Some("Personal Plus"));
+        assert!(!workspaces[1].enabled);
+        assert_eq!(workspaces[1].disabled_at, Some(123));
+        assert_eq!(account.current_workspace_index, Some(1));
+    }
+
+    #[test]
+    fn rejects_workspace_missing_its_id_issue_491() {
+        let mut value = valid_account();
+        value["workspaces"] = json!([{ "name": "Personal Plus", "enabled": true }]);
+        assert!(parse_account(value).is_err());
+    }
+
+    #[test]
+    fn accepts_valid_v3_storage() {
+        let storage: AccountStorageV3 = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt_1", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": 0,
+        }))
+        .expect("valid V3 parses");
+        assert_eq!(storage.accounts.len(), 1);
+        assert_eq!(storage.active_index, 0);
+    }
+
+    #[test]
+    fn accepts_v3_storage_with_active_index_by_family_stripping_unknown_keys() {
+        // "gpt-5.2-codex" is not a model family; zod's partial object strips it.
+        let storage: AccountStorageV3 = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt_1", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": 0,
+            "activeIndexByFamily": { "gpt-5.2-codex": 0, "codex-max": 0 },
+        }))
+        .expect("parses");
+        let by_family = storage.active_index_by_family.expect("map kept");
+        assert_eq!(by_family.get(ModelFamily::CodexMax), Some(0));
+        assert_eq!(by_family.get(ModelFamily::Gpt5_2), None);
+    }
+
+    #[test]
+    fn accepts_empty_accounts_array() {
+        let storage: AccountStorageV3 = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+        }))
+        .expect("parses");
+        assert!(storage.accounts.is_empty());
+    }
+
+    #[test]
+    fn rejects_wrong_version() {
+        let result: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 2,
+            "accounts": [],
+            "activeIndex": 0,
+        }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_negative_active_index() {
+        let result: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": -1,
+        }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_fractional_or_negative_pinned_account_index() {
+        let fractional: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+            "pinnedAccountIndex": 1.5,
+        }));
+        assert!(fractional.is_err());
+        let negative: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+            "pinnedAccountIndex": -1,
+        }));
+        assert!(negative.is_err());
+    }
+
+    #[test]
+    fn accepts_valid_v1_storage() {
+        let storage: AccountStorageV1 = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt_1",
+                "addedAt": 1,
+                "lastUsed": 2,
+                "rateLimitResetTime": 1700000060000i64,
+            }],
+            "activeIndex": 0,
+        }))
+        .expect("parses");
+        assert_eq!(
+            storage.accounts[0].rate_limit_reset_time,
+            Some(1_700_000_060_000)
+        );
+    }
+
+    #[test]
+    fn v1_accepts_and_strips_v3_only_fields() {
+        // zod strips unknown keys, so a V1 account carrying the V3
+        // `rateLimitResetTimes` map still parses (test/schemas.test.ts
+        // "rejects V1 with rateLimitResetTimes (V3 field)" expects success).
+        let storage: AccountStorageV1 = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt_1",
+                "addedAt": 1,
+                "lastUsed": 2,
+                "rateLimitResetTimes": {},
+            }],
+            "activeIndex": 0,
+        }))
+        .expect("parses despite V3-only field");
+        assert_eq!(storage.accounts[0].rate_limit_reset_time, None);
+    }
+
+    #[test]
+    fn any_account_storage_accepts_v1() {
+        let storage: AnyAccountStorage = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }],
+            "activeIndex": 0,
+        }))
+        .expect("parses");
+        assert_eq!(storage.version(), 1);
+    }
+
+    #[test]
+    fn any_account_storage_accepts_v3() {
+        let storage: AnyAccountStorage = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }],
+            "activeIndex": 0,
+        }))
+        .expect("parses");
+        assert_eq!(storage.version(), 3);
+    }
+
+    #[test]
+    fn any_account_storage_rejects_unknown_version() {
+        let result: Result<AnyAccountStorage, _> = serde_json::from_value(json!({
+            "version": 5,
+            "accounts": [],
+            "activeIndex": 0,
+        }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn serializes_in_schema_key_order_with_none_omitted() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("rt", 1, 2));
+        let compact = serde_json::to_string(&storage).unwrap();
+        assert_eq!(
+            compact,
+            r#"{"version":3,"accounts":[{"refreshToken":"rt","addedAt":1,"lastUsed":2}],"activeIndex":0}"#
+        );
+    }
+
+    #[test]
+    fn serializes_optionals_in_schema_order_when_present() {
+        let mut account = AccountMetadataV3::new("rt", 1, 2);
+        account.account_id = Some("acc_1".into());
+        account.email = Some("a@b.com".into());
+        account.enabled = Some(false);
+        let mut resets = RateLimitStateV3::new();
+        resets.insert("gpt-5.2", 99);
+        account.rate_limit_reset_times = Some(resets);
+        account.cooldown_reason = Some(CooldownReason::RateLimit);
+        let compact = serde_json::to_string(&account).unwrap();
+        assert_eq!(
+            compact,
+            r#"{"accountId":"acc_1","email":"a@b.com","refreshToken":"rt","enabled":false,"addedAt":1,"lastUsed":2,"rateLimitResetTimes":{"gpt-5.2":99},"cooldownReason":"rate-limit"}"#
+        );
+    }
+
+    #[test]
+    fn top_level_key_order_includes_pin_and_generation_last() {
+        let mut storage = AccountStorageV3::empty();
+        storage.active_index_by_family = Some(ActiveIndexByFamily {
+            gpt5_codex: Some(0),
+            codex_max: Some(0),
+            codex: Some(0),
+            gpt5_2: Some(0),
+            gpt5_1: Some(0),
+        });
+        storage.pinned_account_index = Some(0);
+        storage.affinity_generation = Some(2);
+        let compact = serde_json::to_string(&storage).unwrap();
+        assert_eq!(
+            compact,
+            r#"{"version":3,"accounts":[],"activeIndex":0,"activeIndexByFamily":{"gpt-5-codex":0,"codex-max":0,"codex":0,"gpt-5.2":0,"gpt-5.1":0},"pinnedAccountIndex":0,"affinityGeneration":2}"#
+        );
+    }
+
+    #[test]
+    fn rate_limit_state_preserves_insertion_order_with_js_assignment_semantics() {
+        let mut state = RateLimitStateV3::new();
+        state.insert("gpt-5.2", 10);
+        state.insert("codex", 20);
+        state.insert("gpt-5-codex", 30);
+        // Re-assigning an existing key keeps its position (JS object rule).
+        state.insert("gpt-5.2", 11);
+        assert_eq!(
+            serde_json::to_string(&state).unwrap(),
+            r#"{"gpt-5.2":11,"codex":20,"gpt-5-codex":30}"#
+        );
+        state.remove("codex");
+        assert_eq!(
+            serde_json::to_string(&state).unwrap(),
+            r#"{"gpt-5.2":11,"gpt-5-codex":30}"#
+        );
+        // Round-trip keeps on-disk key order.
+        let parsed: RateLimitStateV3 = serde_json::from_str(r#"{"b":2,"a":1}"#).expect("parses");
+        assert_eq!(serde_json::to_string(&parsed).unwrap(), r#"{"b":2,"a":1}"#);
+    }
+
+    #[test]
+    fn rate_limit_state_rejects_non_number_values() {
+        let result: Result<RateLimitStateV3, _> = serde_json::from_str(r#"{"a":"soon"}"#);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn zod_optional_is_not_nullable_explicit_null_fails() {
+        // zod `.optional()` accepts absence (undefined) but REJECTS an
+        // explicit JSON null; plain serde Option would silently accept it.
+        for (key, null_value) in [
+            ("email", json!(null)),
+            ("accountId", json!(null)),
+            ("accountIdSource", json!(null)),
+            ("enabled", json!(null)),
+            ("expiresAt", json!(null)),
+            ("lastSwitchReason", json!(null)),
+            ("rateLimitResetTimes", json!(null)),
+            ("coolingDownUntil", json!(null)),
+            ("cooldownReason", json!(null)),
+            ("workspaces", json!(null)),
+            ("currentWorkspaceIndex", json!(null)),
+        ] {
+            let mut value = valid_account();
+            value[key] = null_value;
+            assert!(
+                parse_account(value).is_err(),
+                "{key}: null should fail the parse"
+            );
+        }
+        let storage_null_map: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+            "activeIndexByFamily": null,
+        }));
+        assert!(storage_null_map.is_err());
+        let pin_null: Result<AccountStorageV3, _> = serde_json::from_value(json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+            "pinnedAccountIndex": null,
+        }));
+        assert!(pin_null.is_err());
+    }
+
+    #[test]
+    fn enum_string_conversions() {
+        assert_eq!(SwitchReason::parse("rotation"), Some(SwitchReason::Rotation));
+        assert_eq!(SwitchReason::parse("bogus"), None);
+        assert_eq!(
+            SwitchReason::from(PersistedSwitchReason::Best),
+            SwitchReason::Best
+        );
+        assert_eq!(PersistedSwitchReason::parse("rate-limit"), None);
+        assert_eq!(RateLimitReason::parse("quota"), Some(RateLimitReason::Quota));
+        assert_eq!(
+            AccountIdSource::parse("id_token"),
+            Some(AccountIdSource::IdToken)
+        );
+        assert_eq!(CooldownReason::RateLimit.as_str(), "rate-limit");
+        assert_eq!(SwitchReason::RateLimit.to_string(), "rate-limit");
+    }
+}
diff --git a/crates/core/src/schemas/flagged.rs b/crates/core/src/schemas/flagged.rs
new file mode 100644
index 000000000..9da46ac92
--- /dev/null
+++ b/crates/core/src/schemas/flagged.rs
@@ -0,0 +1,386 @@
+//! Flagged (quarantined) account storage schemas — port of
+//! `FlaggedAccountMetadataV1Schema` / `FlaggedAccountStorageV1Schema` from
+//! `lib/schemas.ts` (spec 01 §3.2, spec 02 §3.5/§4).
+//!
+//! `FlaggedAccountMetadataV1Schema` = `AccountMetadataV3Schema.extend({
+//! flaggedAt, flaggedReason?, lastError? }).passthrough()` — unknown keys
+//! SURVIVE schema validation. In Rust the V3 fields are inlined (declaration
+//! order = zod schema order: the V3 fields first, then the flagged
+//! extensions) and passthrough is `#[serde(flatten)] extra` so unknown keys
+//! round-trip. Note that the on-disk field ORDER of the flagged file is
+//! ultimately decided by the storage crate's `normalize_flagged_storage`
+//! whitelist rebuild (spec 02 §3.5) — this schema only has to keep the data.
+
+use serde::{Deserialize, Serialize};
+
+use super::account_storage::{
+    AccountIdSource, AccountMetadataV3, CooldownReason, RateLimitStateV3, SwitchReason, Workspace,
+};
+use super::parse::{
+    Version1, de_number_lenient, de_opt_number_lenient, de_opt_strict, de_string_min1,
+};
+
+/// Flagged account metadata V1 — a V3 account plus flagging info, with
+/// passthrough of unknown keys.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct FlaggedAccountMetadataV1 {
+    // ---- AccountMetadataV3 fields (schema declaration order) ----
+    #[serde(
+        rename = "accountId",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id: Option<String>,
+    #[serde(
+        rename = "accountIdSource",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_id_source: Option<AccountIdSource>,
+    #[serde(
+        rename = "accountLabel",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub account_label: Option<String>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub email: Option<String>,
+    /// Required, non-empty.
+    #[serde(rename = "refreshToken", deserialize_with = "de_string_min1")]
+    pub refresh_token: String,
+    #[serde(
+        rename = "accessToken",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub access_token: Option<String>,
+    #[serde(
+        rename = "expiresAt",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub expires_at: Option<i64>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub enabled: Option<bool>,
+    /// Required, ms epoch.
+    #[serde(rename = "addedAt", deserialize_with = "de_number_lenient")]
+    pub added_at: i64,
+    /// Required, ms epoch.
+    #[serde(rename = "lastUsed", deserialize_with = "de_number_lenient")]
+    pub last_used: i64,
+    #[serde(
+        rename = "lastSwitchReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_switch_reason: Option<SwitchReason>,
+    #[serde(
+        rename = "rateLimitResetTimes",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub rate_limit_reset_times: Option<RateLimitStateV3>,
+    #[serde(
+        rename = "coolingDownUntil",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooling_down_until: Option<i64>,
+    #[serde(
+        rename = "cooldownReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub cooldown_reason: Option<CooldownReason>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub workspaces: Option<Vec<Workspace>>,
+    #[serde(
+        rename = "currentWorkspaceIndex",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub current_workspace_index: Option<i64>,
+    // ---- Flagging extensions ----
+    /// Required, ms epoch — when the account was quarantined.
+    #[serde(rename = "flaggedAt", deserialize_with = "de_number_lenient")]
+    pub flagged_at: i64,
+    #[serde(
+        rename = "flaggedReason",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub flagged_reason: Option<String>,
+    #[serde(
+        rename = "lastError",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub last_error: Option<String>,
+    /// zod `.passthrough()`: unknown keys survive validation and round-trip.
+    /// (They are later dropped by the storage crate's
+    /// `normalize_flagged_storage` whitelist before persisting — spec 02
+    /// §3.5.) Do not put keys here that collide with the named fields.
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, serde_json::Value>,
+}
+
+impl FlaggedAccountMetadataV1 {
+    /// Build a flagged entry from a V3 account plus flagging info.
+    pub fn from_account(
+        account: AccountMetadataV3,
+        flagged_at: i64,
+        flagged_reason: Option<String>,
+        last_error: Option<String>,
+    ) -> Self {
+        Self {
+            account_id: account.account_id,
+            account_id_source: account.account_id_source,
+            account_label: account.account_label,
+            email: account.email,
+            refresh_token: account.refresh_token,
+            access_token: account.access_token,
+            expires_at: account.expires_at,
+            enabled: account.enabled,
+            added_at: account.added_at,
+            last_used: account.last_used,
+            last_switch_reason: account.last_switch_reason,
+            rate_limit_reset_times: account.rate_limit_reset_times,
+            cooling_down_until: account.cooling_down_until,
+            cooldown_reason: account.cooldown_reason,
+            workspaces: account.workspaces,
+            current_workspace_index: account.current_workspace_index,
+            flagged_at,
+            flagged_reason,
+            last_error,
+            extra: serde_json::Map::new(),
+        }
+    }
+
+    /// The embedded V3 account view (flagging info and passthrough keys
+    /// dropped) — used when restoring a quarantined account into the pool.
+    pub fn to_account_metadata(&self) -> AccountMetadataV3 {
+        AccountMetadataV3 {
+            account_id: self.account_id.clone(),
+            account_id_source: self.account_id_source,
+            account_label: self.account_label.clone(),
+            email: self.email.clone(),
+            refresh_token: self.refresh_token.clone(),
+            access_token: self.access_token.clone(),
+            expires_at: self.expires_at,
+            enabled: self.enabled,
+            added_at: self.added_at,
+            last_used: self.last_used,
+            last_switch_reason: self.last_switch_reason,
+            rate_limit_reset_times: self.rate_limit_reset_times.clone(),
+            cooling_down_until: self.cooling_down_until,
+            cooldown_reason: self.cooldown_reason,
+            workspaces: self.workspaces.clone(),
+            current_workspace_index: self.current_workspace_index,
+        }
+    }
+}
+
+/// Flagged account storage V1 format (`{version: 1, accounts: []}`).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct FlaggedAccountStorageV1 {
+    /// Literal `1`.
+    pub version: Version1,
+    pub accounts: Vec<FlaggedAccountMetadataV1>,
+}
+
+impl FlaggedAccountStorageV1 {
+    /// Empty flagged storage (`{version:1, accounts:[]}`).
+    pub fn empty() -> Self {
+        Self {
+            version: Version1::default(),
+            accounts: Vec::new(),
+        }
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts flagged suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn valid_account() -> serde_json::Value {
+        json!({ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1, "flaggedAt": 2 })
+    }
+
+    #[test]
+    fn accepts_version_1_with_empty_accounts() {
+        let storage: FlaggedAccountStorageV1 =
+            serde_json::from_value(json!({ "version": 1, "accounts": [] })).expect("parses");
+        assert!(storage.accounts.is_empty());
+    }
+
+    #[test]
+    fn accepts_populated_accounts_with_optional_fields() {
+        let storage: FlaggedAccountStorageV1 = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "addedAt": 1,
+                "lastUsed": 1,
+                "flaggedAt": 2,
+                "flaggedReason": "rate-limit",
+                "lastError": "429",
+                "email": "a@b.com",
+            }],
+        }))
+        .expect("parses");
+        let account = &storage.accounts[0];
+        assert_eq!(account.flagged_reason.as_deref(), Some("rate-limit"));
+        assert_eq!(account.last_error.as_deref(), Some("429"));
+        assert_eq!(account.email.as_deref(), Some("a@b.com"));
+    }
+
+    #[test]
+    fn rejects_non_1_version() {
+        let result: Result<FlaggedAccountStorageV1, _> =
+            serde_json::from_value(json!({ "version": 2, "accounts": [] }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_missing_accounts_field() {
+        let result: Result<FlaggedAccountStorageV1, _> =
+            serde_json::from_value(json!({ "version": 1 }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_account_missing_required_flagged_at() {
+        let result: Result<FlaggedAccountStorageV1, _> = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }],
+        }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_account_with_wrong_types() {
+        let result: Result<FlaggedAccountStorageV1, _> = serde_json::from_value(json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "addedAt": 1,
+                "lastUsed": 1,
+                "flaggedAt": "not-a-number",
+            }],
+        }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn permits_known_v3_fields_like_workspaces() {
+        let mut value = valid_account();
+        value["workspaces"] = json!([]);
+        let account: FlaggedAccountMetadataV1 =
+            serde_json::from_value(value).expect("workspaces accepted");
+        assert_eq!(account.workspaces.as_deref(), Some(&[][..]));
+    }
+
+    #[test]
+    fn passthrough_preserves_unknown_keys_through_round_trip() {
+        let mut value = valid_account();
+        value["someFutureField"] = json!({ "nested": true });
+        value["another"] = json!(7);
+        let account: FlaggedAccountMetadataV1 =
+            serde_json::from_value(value).expect("unknown keys accepted");
+        assert_eq!(
+            account.extra.get("someFutureField"),
+            Some(&json!({ "nested": true }))
+        );
+        assert_eq!(account.extra.get("another"), Some(&json!(7)));
+        let serialized = serde_json::to_value(&account).expect("serializes");
+        assert_eq!(
+            serialized.get("someFutureField"),
+            Some(&json!({ "nested": true }))
+        );
+        assert_eq!(serialized.get("another"), Some(&json!(7)));
+        assert_eq!(serialized.get("refreshToken"), Some(&json!("rt")));
+    }
+
+    #[test]
+    fn inherits_v3_required_fields() {
+        let account: FlaggedAccountMetadataV1 =
+            serde_json::from_value(valid_account()).expect("parses");
+        assert_eq!(account.refresh_token, "rt");
+        assert_eq!(account.flagged_at, 2);
+    }
+
+    #[test]
+    fn rejects_when_flagged_at_is_missing() {
+        let result: Result<FlaggedAccountMetadataV1, _> =
+            serde_json::from_value(json!({ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_empty_refresh_token() {
+        let mut value = valid_account();
+        value["refreshToken"] = json!("");
+        let result: Result<FlaggedAccountMetadataV1, _> = serde_json::from_value(value);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn zod_optional_is_not_nullable_but_passthrough_nulls_survive() {
+        // Known optional fields reject explicit null (zod optional ≠
+        // nullable) ...
+        for key in ["flaggedReason", "lastError", "email", "enabled"] {
+            let mut value = valid_account();
+            value[key] = json!(null);
+            let result: Result<FlaggedAccountMetadataV1, _> = serde_json::from_value(value);
+            assert!(result.is_err(), "{key}: null should fail the parse");
+        }
+        // ... while UNKNOWN keys pass through untouched, null included
+        // (`.passthrough()` performs no validation on them).
+        let mut value = valid_account();
+        value["someUnknown"] = json!(null);
+        let account: FlaggedAccountMetadataV1 =
+            serde_json::from_value(value).expect("unknown null passes through");
+        assert_eq!(account.extra.get("someUnknown"), Some(&json!(null)));
+    }
+
+    #[test]
+    fn account_metadata_round_trip_helpers() {
+        let account: FlaggedAccountMetadataV1 =
+            serde_json::from_value(valid_account()).expect("parses");
+        let v3 = account.to_account_metadata();
+        assert_eq!(v3.refresh_token, "rt");
+        let back = FlaggedAccountMetadataV1::from_account(v3, 9, Some("why".into()), None);
+        assert_eq!(back.flagged_at, 9);
+        assert_eq!(back.flagged_reason.as_deref(), Some("why"));
+        assert!(back.extra.is_empty());
+    }
+}
diff --git a/crates/core/src/schemas/journal.rs b/crates/core/src/schemas/journal.rs
new file mode 100644
index 000000000..388634422
--- /dev/null
+++ b/crates/core/src/schemas/journal.rs
@@ -0,0 +1,154 @@
+//! Accounts journal (WAL) entry schema — port of
+//! `AccountsJournalEntrySchema` from `lib/schemas.ts` (spec 01 §3.2, spec 02
+//! §3.2).
+//!
+//! On-disk format (compact `JSON.stringify(entry)`, spec 02 §3.2):
+//! `{"version":1,"createdAt":<ms>,"path":"<accountsPath>","checksum":"<sha256 hex>","content":"<pretty accounts JSON>"}`
+//!
+//! Serialization field order matches the TS writer's object construction
+//! order (`storage.ts` `writeJournal`): `version, createdAt, path, checksum,
+//! content`. On read, the schema requires `version === 1` plus string
+//! `content`/`checksum`; `createdAt`/`path` are optional. The checksum
+//! integrity check (lowercase sha256 hex of `content`) and the compact
+//! serialization itself are the storage crate's business.
+
+use serde::{Deserialize, Serialize};
+
+use super::parse::{Version1, de_opt_number_lenient, de_opt_strict};
+
+/// WAL journal entry used to persist in-flight account storage state.
+/// `content` is a JSON string that parses into an `AnyAccountStorage`
+/// payload.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AccountsJournalEntry {
+    /// Literal `1`.
+    pub version: Version1,
+    /// ms epoch (always written; optional on read).
+    #[serde(
+        rename = "createdAt",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub created_at: Option<i64>,
+    /// The PRIMARY accounts path (not the wal path). Always written;
+    /// optional on read.
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub path: Option<String>,
+    /// Lowercase sha256 hex of `content`. Mismatch ⇒ WAL invalid (checked by
+    /// the storage crate on replay).
+    pub checksum: String,
+    /// The exact string that will be written to the accounts file (pretty,
+    /// 2-space).
+    pub content: String,
+}
+
+impl AccountsJournalEntry {
+    /// Build a fully-populated entry the way the TS writer does
+    /// (`{version:1, createdAt, path, checksum, content}`).
+    pub fn new(
+        created_at: i64,
+        path: impl Into<String>,
+        checksum: impl Into<String>,
+        content: impl Into<String>,
+    ) -> Self {
+        Self {
+            version: Version1::default(),
+            created_at: Some(created_at),
+            path: Some(path.into()),
+            checksum: checksum.into(),
+            content: content.into(),
+        }
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts AccountsJournalEntrySchema suite)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn accepts_a_valid_entry_with_required_fields() {
+        let entry: AccountsJournalEntry =
+            serde_json::from_value(json!({ "version": 1, "content": "{}", "checksum": "abc" }))
+                .expect("parses");
+        assert_eq!(entry.content, "{}");
+        assert_eq!(entry.checksum, "abc");
+        assert_eq!(entry.created_at, None);
+        assert_eq!(entry.path, None);
+    }
+
+    #[test]
+    fn accepts_optional_created_at_and_path() {
+        let entry: AccountsJournalEntry = serde_json::from_value(json!({
+            "version": 1,
+            "content": "{}",
+            "checksum": "abc",
+            "createdAt": 123,
+            "path": "/tmp/a",
+        }))
+        .expect("parses");
+        assert_eq!(entry.created_at, Some(123));
+        assert_eq!(entry.path.as_deref(), Some("/tmp/a"));
+    }
+
+    #[test]
+    fn rejects_non_1_version() {
+        let result: Result<AccountsJournalEntry, _> =
+            serde_json::from_value(json!({ "version": 2, "content": "{}", "checksum": "abc" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_missing_content() {
+        let result: Result<AccountsJournalEntry, _> =
+            serde_json::from_value(json!({ "version": 1, "checksum": "abc" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_wrong_types_content_number() {
+        let result: Result<AccountsJournalEntry, _> =
+            serde_json::from_value(json!({ "version": 1, "content": 12, "checksum": "abc" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn zod_optional_is_not_nullable_explicit_null_fails() {
+        for key in ["createdAt", "path"] {
+            let result: Result<AccountsJournalEntry, _> = serde_json::from_value(json!({
+                "version": 1,
+                "content": "{}",
+                "checksum": "abc",
+                key: null,
+            }));
+            assert!(result.is_err(), "{key}: null should fail the parse");
+        }
+    }
+
+    #[test]
+    fn compact_serialization_matches_ts_writer_key_order() {
+        let entry = AccountsJournalEntry::new(1_753_500_000_000, "/tmp/accounts.json", "c0ffee", "{}");
+        assert_eq!(
+            serde_json::to_string(&entry).unwrap(),
+            r#"{"version":1,"createdAt":1753500000000,"path":"/tmp/accounts.json","checksum":"c0ffee","content":"{}"}"#
+        );
+    }
+
+    #[test]
+    fn round_trips_content_string_verbatim() {
+        let pretty = "{\n  \"version\": 3,\n  \"accounts\": [],\n  \"activeIndex\": 0\n}";
+        let entry = AccountsJournalEntry::new(1, "p", "c", pretty);
+        let raw = serde_json::to_string(&entry).unwrap();
+        let parsed: AccountsJournalEntry = serde_json::from_str(&raw).expect("parses");
+        assert_eq!(parsed.content, pretty);
+    }
+}
diff --git a/crates/core/src/schemas/mod.rs b/crates/core/src/schemas/mod.rs
new file mode 100644
index 000000000..04381734f
--- /dev/null
+++ b/crates/core/src/schemas/mod.rs
@@ -0,0 +1,7 @@
+//! cma-core - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_storage;
+pub mod flagged;
+pub mod journal;
+pub mod parse;
+pub mod plugin_config;
+pub mod token;
diff --git a/crates/core/src/schemas/parse.rs b/crates/core/src/schemas/parse.rs
new file mode 100644
index 000000000..0ea35d11d
--- /dev/null
+++ b/crates/core/src/schemas/parse.rs
@@ -0,0 +1,579 @@
+//! Port of the parse/validation helper half of `lib/schemas.ts`:
+//! `safeParseJson`, `getValidationErrors`, the per-schema `safeParseX` helpers,
+//! plus the shared zod-semantics serde building blocks used by the sibling
+//! schema modules (`account_storage.rs`, `flagged.rs`, `journal.rs`,
+//! `token.rs`, `plugin_config.rs`).
+//!
+//! Behavior source of truth: spec 01 §2.8/§3 and spec 02 §4; TS source
+//! `lib/schemas.ts`. `safe_parse_json` is FAIL-CLOSED: a JSON syntax error OR
+//! a schema/shape mismatch both yield `None` (each debug-logged with its
+//! context tag). Callers that must distinguish syntax errors from schema
+//! errors (e.g. the storage loader, where a JSON SyntaxError propagates)
+//! re-run a raw `serde_json::from_str::<Value>` themselves after a `None`.
+
+use serde::de::DeserializeOwned;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde_json::Value;
+
+use super::account_storage::{AccountStorageV3, AnyAccountStorage};
+use super::flagged::FlaggedAccountStorageV1;
+use super::journal::AccountsJournalEntry;
+use super::plugin_config::PluginConfig;
+use super::token::{OAuthTokenResponse, TokenResult};
+
+// ============================================================================
+// Schema issues ("path.to.field: message" formatting)
+// ============================================================================
+
+/// One validation issue, mirroring a zod issue: a key path (indices are
+/// stringified, matching `issue.path.join(".")`) plus a message.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SchemaIssue {
+    pub path: Vec<String>,
+    pub message: String,
+}
+
+impl SchemaIssue {
+    pub fn new(path: Vec<String>, message: impl Into<String>) -> Self {
+        Self {
+            path,
+            message: message.into(),
+        }
+    }
+
+    /// Issue with an empty path (root-level failure — no path prefix when
+    /// formatted).
+    pub fn root(message: impl Into<String>) -> Self {
+        Self {
+            path: Vec::new(),
+            message: message.into(),
+        }
+    }
+
+    /// `"<path joined by '.'>: <message>"`; the path prefix is omitted when
+    /// the path is empty (spec 01 §2.8).
+    pub fn format(&self) -> String {
+        if self.path.is_empty() {
+            self.message.clone()
+        } else {
+            format!("{}: {}", self.path.join("."), self.message)
+        }
+    }
+}
+
+impl std::fmt::Display for SchemaIssue {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.format())
+    }
+}
+
+/// Format a list of issues into `"path.to.field: message"` strings.
+pub fn format_issues(issues: &[SchemaIssue]) -> Vec<String> {
+    issues.iter().map(SchemaIssue::format).collect()
+}
+
+/// Port of `getValidationErrors(schema, data)`: `[]` on success, otherwise
+/// each issue formatted as `"<dot.path>: <message>"`. The zod schema argument
+/// becomes a check closure producing [`SchemaIssue`]s (e.g.
+/// [`super::plugin_config::plugin_config_issues`]).
+pub fn validation_errors<F>(schema_check: F, data: &Value) -> Vec<String>
+where
+    F: FnOnce(&Value) -> Vec<SchemaIssue>,
+{
+    format_issues(&schema_check(data))
+}
+
+// ============================================================================
+// safeParseJson (fail-closed JSON.parse + shape boundary)
+// ============================================================================
+
+/// Debug-log sink for schema-boundary failures. Isolated here so the sibling
+/// `logger` module's exact signature is referenced from exactly one place.
+/// (TS lazily creates a scoped logger `"schemas"` and logs at debug level.)
+fn schema_debug(message: &str, data: Value) {
+    crate::logger::log_debug(message, Some(&data));
+}
+
+/// `safeParseJson(raw, schema, context)` with the default context
+/// `"safeParseJson"`. Fail-closed: syntax error OR shape mismatch → `None`.
+pub fn safe_parse_json<T: DeserializeOwned>(raw: &str) -> Option<T> {
+    safe_parse_json_with_context(raw, "safeParseJson")
+}
+
+/// `safeParseJson(raw, schema, context)`. Returns `None` on JSON syntax
+/// errors (debug log `"safeParseJson JSON.parse failed"` tagged with
+/// `context`) and on shape mismatches (debug log
+/// `"safeParseJson schema validation failed"` with the issue list — serde
+/// reports the first failing field, so the list has one entry).
+pub fn safe_parse_json_with_context<T: DeserializeOwned>(raw: &str, context: &str) -> Option<T> {
+    let parsed: Value = match serde_json::from_str(raw) {
+        Ok(value) => value,
+        Err(error) => {
+            schema_debug(
+                "safeParseJson JSON.parse failed",
+                serde_json::json!({ "context": context, "error": error.to_string() }),
+            );
+            return None;
+        }
+    };
+    match T::deserialize(parsed) {
+        Ok(value) => Some(value),
+        Err(error) => {
+            schema_debug(
+                "safeParseJson schema validation failed",
+                serde_json::json!({ "context": context, "issues": [error.to_string()] }),
+            );
+            None
+        }
+    }
+}
+
+/// Shape-only half of the boundary: validate an already-parsed JSON value
+/// against a schema type. This is the Rust analogue of calling
+/// `Schema.safeParse(data)` and taking `.data` or `null`.
+pub fn safe_parse_value<T: DeserializeOwned>(value: &Value) -> Option<T> {
+    T::deserialize(value.clone()).ok()
+}
+
+// ============================================================================
+// Typed safeParseX helpers (TS export parity)
+// ============================================================================
+
+/// `safeParsePluginConfig(data)` — parsed config or `None`, never errors.
+pub fn safe_parse_plugin_config(data: &Value) -> Option<PluginConfig> {
+    safe_parse_value(data)
+}
+
+/// `safeParseAccountStorage(data)` — V1|V3 union or `None`.
+pub fn safe_parse_account_storage(data: &Value) -> Option<AnyAccountStorage> {
+    safe_parse_value(data)
+}
+
+/// `safeParseAccountStorageV3(data)` — V3 specifically or `None`.
+pub fn safe_parse_account_storage_v3(data: &Value) -> Option<AccountStorageV3> {
+    safe_parse_value(data)
+}
+
+/// `safeParseTokenResult(data)` — success/failed union or `None`.
+pub fn safe_parse_token_result(data: &Value) -> Option<TokenResult> {
+    safe_parse_value(data)
+}
+
+/// `safeParseOAuthTokenResponse(data)` — token endpoint response or `None`.
+pub fn safe_parse_oauth_token_response(data: &Value) -> Option<OAuthTokenResponse> {
+    safe_parse_value(data)
+}
+
+/// `safeParseFlaggedAccountStorageV1(data)` — flagged storage or `None`.
+pub fn safe_parse_flagged_account_storage_v1(data: &Value) -> Option<FlaggedAccountStorageV1> {
+    safe_parse_value(data)
+}
+
+/// `safeParseAccountsJournalEntry(data)` — WAL entry or `None`.
+pub fn safe_parse_accounts_journal_entry(data: &Value) -> Option<AccountsJournalEntry> {
+    safe_parse_value(data)
+}
+
+// ============================================================================
+// Shared zod-semantics serde building blocks
+// ============================================================================
+
+/// zod-style runtime type name of a JSON value (used in
+/// `"Invalid input: expected X, received Y"` messages).
+pub fn json_type_name(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "boolean",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
+
+/// Format an f64 the way JavaScript prints it in the common cases: integral
+/// values print without a decimal point (`5` not `5.0`).
+pub fn fmt_js_number(value: f64) -> String {
+    if value.is_finite() && value.fract() == 0.0 && value.abs() < 9.007_199_254_740_992e15 {
+        format!("{}", value as i64)
+    } else {
+        format!("{value}")
+    }
+}
+
+/// Convert a JSON number to `i64` the lenient way: integral representations
+/// pass through; `u64` overflow saturates; float values truncate toward zero
+/// (Rust saturating cast). zod `z.number()` accepts any finite number — epoch
+/// timestamps are modeled as `i64` per architecture R9, so pathological
+/// fractional inputs truncate instead of failing.
+pub fn number_to_i64_lossy(n: &serde_json::Number) -> i64 {
+    if let Some(i) = n.as_i64() {
+        i
+    } else if let Some(u) = n.as_u64() {
+        i64::try_from(u).unwrap_or(i64::MAX)
+    } else {
+        // `as` casts from f64 to i64 saturate and map NaN to 0.
+        n.as_f64().unwrap_or(0.0) as i64
+    }
+}
+
+/// Strict-integer view of a JSON number (zod `.int()`): integral
+/// representations and floats with zero fractional part qualify (JS
+/// `Number.isInteger(12.0)` is `true`); anything else is `None`.
+pub fn number_as_strict_int(n: &serde_json::Number) -> Option<i64> {
+    if let Some(i) = n.as_i64() {
+        Some(i)
+    } else if let Some(u) = n.as_u64() {
+        Some(i64::try_from(u).unwrap_or(i64::MAX))
+    } else {
+        let f = n.as_f64()?;
+        if f.is_finite() && f.fract() == 0.0 {
+            Some(f as i64)
+        } else {
+            None
+        }
+    }
+}
+
+/// `z.number()` → lenient `i64` (required field).
+pub fn de_number_lenient<'de, D: Deserializer<'de>>(deserializer: D) -> Result<i64, D::Error> {
+    let n = serde_json::Number::deserialize(deserializer)?;
+    Ok(number_to_i64_lossy(&n))
+}
+
+/// zod `.optional()` semantics for a PRESENT key: absence is handled by
+/// `#[serde(default)]`, but an explicit JSON `null` must FAIL the parse —
+/// zod optional ≠ nullable (`JSON.parse` never yields `undefined`, so
+/// `z.string().optional()` rejects `null` with "expected string, received
+/// null"). Plain serde `Option<T>` would silently map `null` → `None`;
+/// this helper restores the zod behavior for strings, booleans, enums,
+/// arrays and nested schemas.
+pub fn de_opt_strict<'de, D, T>(deserializer: D) -> Result<Option<T>, D::Error>
+where
+    D: Deserializer<'de>,
+    T: Deserialize<'de>,
+{
+    T::deserialize(deserializer).map(Some)
+}
+
+/// `z.number().optional()` → lenient `Option<i64>` for a PRESENT key: the
+/// value must be a JSON number (explicit `null` fails, matching zod optional
+/// ≠ nullable); absence is handled by `#[serde(default)]`.
+pub fn de_opt_number_lenient<'de, D: Deserializer<'de>>(
+    deserializer: D,
+) -> Result<Option<i64>, D::Error> {
+    let n = serde_json::Number::deserialize(deserializer)?;
+    Ok(Some(number_to_i64_lossy(&n)))
+}
+
+/// `z.number().min(0)` → lenient non-negative `i64` (negative input fails the
+/// parse, exactly like zod).
+pub fn de_number_min0_lenient<'de, D: Deserializer<'de>>(
+    deserializer: D,
+) -> Result<i64, D::Error> {
+    let n = serde_json::Number::deserialize(deserializer)?;
+    if n.as_f64().is_some_and(|f| f < 0.0) {
+        return Err(serde::de::Error::custom(
+            "Too small: expected number to be >=0",
+        ));
+    }
+    Ok(number_to_i64_lossy(&n))
+}
+
+/// `z.number().int().min(0).optional()` → strict optional non-negative
+/// integer (`pinnedAccountIndex`, `affinityGeneration`): fractional,
+/// negative or explicit-`null` values fail the parse (absence is handled by
+/// `#[serde(default)]`).
+pub fn de_opt_int_min0_strict<'de, D: Deserializer<'de>>(
+    deserializer: D,
+) -> Result<Option<i64>, D::Error> {
+    let n = serde_json::Number::deserialize(deserializer)?;
+    let value = number_as_strict_int(&n)
+        .ok_or_else(|| serde::de::Error::custom("Invalid input: expected int, received number"))?;
+    if value < 0 {
+        return Err(serde::de::Error::custom(
+            "Too small: expected number to be >=0",
+        ));
+    }
+    Ok(Some(value))
+}
+
+/// `z.number().int().positive()` → strict integer > 0 (`expires`,
+/// `expires_in`): zero, negative or fractional values fail the parse.
+pub fn de_int_positive_strict<'de, D: Deserializer<'de>>(
+    deserializer: D,
+) -> Result<i64, D::Error> {
+    let n = serde_json::Number::deserialize(deserializer)?;
+    let value = number_as_strict_int(&n)
+        .ok_or_else(|| serde::de::Error::custom("Invalid input: expected int, received number"))?;
+    if value <= 0 {
+        return Err(serde::de::Error::custom(
+            "Too small: expected number to be >0",
+        ));
+    }
+    Ok(value)
+}
+
+/// `z.string().min(1)` → non-empty `String` (empty string fails the parse).
+pub fn de_string_min1<'de, D: Deserializer<'de>>(deserializer: D) -> Result<String, D::Error> {
+    let s = String::deserialize(deserializer)?;
+    if s.is_empty() {
+        return Err(serde::de::Error::custom(
+            "Too small: expected string to have >=1 characters",
+        ));
+    }
+    Ok(s)
+}
+
+// ============================================================================
+// Version literal marker (z.literal(N) on the `version` key)
+// ============================================================================
+
+/// Zero-sized marker enforcing `version: N` at (de)serialization time.
+/// Serializes as the integer `N`; deserialization accepts any JSON number
+/// equal to `N` (JSON `3.0` equals `3`, matching `JSON.parse` + `z.literal`).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct VersionLiteral<const N: u8>;
+
+impl<const N: u8> VersionLiteral<N> {
+    pub const VALUE: u8 = N;
+
+    pub fn value(&self) -> u8 {
+        N
+    }
+}
+
+impl<const N: u8> Serialize for VersionLiteral<N> {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_u64(u64::from(N))
+    }
+}
+
+impl<'de, const N: u8> Deserialize<'de> for VersionLiteral<N> {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let n = serde_json::Number::deserialize(deserializer)?;
+        if n.as_f64() == Some(f64::from(N)) {
+            Ok(VersionLiteral)
+        } else {
+            Err(serde::de::Error::custom(format!(
+                "Invalid input: expected {N}"
+            )))
+        }
+    }
+}
+
+/// `z.literal(1)` version marker (flagged storage, WAL journal, V1 storage).
+pub type Version1 = VersionLiteral<1>;
+/// `z.literal(3)` version marker (account storage V3).
+pub type Version3 = VersionLiteral<3>;
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts — safeParseJson / getValidationErrors
+// / safeParseX suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[derive(Debug, PartialEq, serde::Deserialize)]
+    struct Demo {
+        a: f64,
+    }
+
+    #[test]
+    fn safe_parse_json_parses_valid_json_matching_schema() {
+        let result: Option<Demo> = safe_parse_json_with_context(r#"{"a":1}"#, "test.happy");
+        assert_eq!(result, Some(Demo { a: 1.0 }));
+    }
+
+    #[test]
+    fn safe_parse_json_returns_none_on_syntax_error() {
+        let result: Option<Demo> = safe_parse_json_with_context("{not-valid-json", "test.syntax");
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn safe_parse_json_returns_none_when_schema_rejects() {
+        let result: Option<Demo> = safe_parse_json_with_context(r#"{"a":"x"}"#, "test.schema");
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn safe_parse_json_default_context_smoke() {
+        let result: Option<Demo> = safe_parse_json("not-json");
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn safe_parse_json_validates_any_account_storage_end_to_end() {
+        let raw = serde_json::to_string(&json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }],
+            "activeIndex": 0,
+        }))
+        .unwrap();
+        let result: Option<AnyAccountStorage> =
+            safe_parse_json_with_context(&raw, "test.end-to-end");
+        let storage = result.expect("should parse");
+        assert_eq!(storage.version(), 3);
+    }
+
+    #[test]
+    fn safe_parse_json_keeps_workspaces_through_load_round_trip_issue_491() {
+        let raw = serde_json::to_string(&json!({
+            "version": 3,
+            "accounts": [{
+                "refreshToken": "rt",
+                "addedAt": 1,
+                "lastUsed": 1,
+                "accountId": "org-AAAA",
+                "email": "user@gmail.com",
+                "workspaces": [{ "id": "org-AAAA", "name": "Personal Plus", "enabled": true }],
+                "currentWorkspaceIndex": 0,
+            }],
+            "activeIndex": 0,
+        }))
+        .unwrap();
+        let result: Option<AnyAccountStorage> =
+            safe_parse_json_with_context(&raw, "test.workspaces");
+        let AnyAccountStorage::V3(storage) = result.expect("should parse") else {
+            panic!("expected V3 storage");
+        };
+        let account = &storage.accounts[0];
+        let workspaces = account.workspaces.as_ref().expect("workspaces kept");
+        assert_eq!(workspaces.len(), 1);
+        assert_eq!(workspaces[0].name.as_deref(), Some("Personal Plus"));
+        assert_eq!(account.current_workspace_index, Some(0));
+    }
+
+    #[test]
+    fn validation_errors_returns_empty_for_valid_data() {
+        let errors = validation_errors(
+            super::super::plugin_config::plugin_config_issues,
+            &json!({ "codexMode": true }),
+        );
+        assert!(errors.is_empty());
+    }
+
+    #[test]
+    fn validation_errors_returns_messages_for_invalid_data() {
+        let errors = validation_errors(
+            super::super::plugin_config::plugin_config_issues,
+            &json!({ "codexMode": "yes" }),
+        );
+        assert!(!errors.is_empty());
+        assert!(errors[0].contains("codexMode"));
+    }
+
+    #[test]
+    fn validation_errors_omits_path_prefix_when_path_is_empty() {
+        let errors = validation_errors(
+            super::super::plugin_config::plugin_config_issues,
+            &json!("not-an-object"),
+        );
+        assert!(!errors.is_empty());
+        assert!(errors[0].starts_with("Invalid input"));
+    }
+
+    #[test]
+    fn schema_issue_format_joins_path_with_dots() {
+        let issue = SchemaIssue::new(
+            vec!["accounts".into(), "0".into(), "refreshToken".into()],
+            "Too small: expected string to have >=1 characters",
+        );
+        assert_eq!(
+            issue.format(),
+            "accounts.0.refreshToken: Too small: expected string to have >=1 characters"
+        );
+    }
+
+    #[test]
+    fn version_literal_round_trip_and_rejection() {
+        assert!(serde_json::from_value::<Version3>(json!(3)).is_ok());
+        assert!(serde_json::from_value::<Version3>(json!(3.0)).is_ok());
+        assert!(serde_json::from_value::<Version3>(json!(2)).is_err());
+        assert!(serde_json::from_value::<Version3>(json!("3")).is_err());
+        assert_eq!(serde_json::to_string(&Version3::default()).unwrap(), "3");
+        assert!(serde_json::from_value::<Version1>(json!(1)).is_ok());
+        assert!(serde_json::from_value::<Version1>(json!(2)).is_err());
+    }
+
+    #[test]
+    fn number_helpers_match_zod_semantics() {
+        let int = serde_json::Number::from(5);
+        let frac = serde_json::Number::from_f64(12.5).unwrap();
+        let whole_float = serde_json::Number::from_f64(12.0).unwrap();
+        assert_eq!(number_to_i64_lossy(&int), 5);
+        assert_eq!(number_to_i64_lossy(&frac), 12);
+        assert_eq!(number_as_strict_int(&int), Some(5));
+        assert_eq!(number_as_strict_int(&frac), None);
+        // JS Number.isInteger(12.0) === true.
+        assert_eq!(number_as_strict_int(&whole_float), Some(12));
+    }
+
+    #[test]
+    fn fmt_js_number_prints_integers_without_decimal_point() {
+        assert_eq!(fmt_js_number(1000.0), "1000");
+        assert_eq!(fmt_js_number(0.0), "0");
+        assert_eq!(fmt_js_number(12.5), "12.5");
+    }
+
+    #[test]
+    fn safe_parse_helpers_return_none_on_invalid_shapes() {
+        assert!(
+            safe_parse_account_storage(
+                &json!({ "version": 99, "accounts": [], "activeIndex": 0 })
+            )
+            .is_none()
+        );
+        assert!(
+            safe_parse_account_storage_v3(
+                &json!({ "version": 1, "accounts": [], "activeIndex": 0 })
+            )
+            .is_none()
+        );
+        assert!(safe_parse_plugin_config(&json!("invalid")).is_none());
+        assert!(safe_parse_token_result(&json!({ "type": "unknown" })).is_none());
+        assert!(safe_parse_oauth_token_response(&json!({ "invalid": true })).is_none());
+        assert!(
+            safe_parse_flagged_account_storage_v1(&json!({ "version": 99, "accounts": [] }))
+                .is_none()
+        );
+        assert!(safe_parse_accounts_journal_entry(&json!({ "version": 2 })).is_none());
+    }
+
+    #[test]
+    fn safe_parse_helpers_return_values_on_valid_shapes() {
+        assert!(safe_parse_account_storage(&json!({
+            "version": 1,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 1 }],
+            "activeIndex": 0,
+        }))
+        .is_some());
+        assert!(safe_parse_account_storage_v3(&json!({
+            "version": 3,
+            "accounts": [],
+            "activeIndex": 0,
+        }))
+        .is_some());
+        assert!(safe_parse_plugin_config(&json!({ "codexMode": true })).is_some());
+        assert!(safe_parse_token_result(&json!({ "type": "failed" })).is_some());
+        assert!(safe_parse_oauth_token_response(&json!({
+            "access_token": "at",
+            "expires_in": 3600,
+        }))
+        .is_some());
+        assert!(
+            safe_parse_flagged_account_storage_v1(&json!({ "version": 1, "accounts": [] }))
+                .is_some()
+        );
+        assert!(safe_parse_accounts_journal_entry(&json!({
+            "version": 1,
+            "content": "{}",
+            "checksum": "c",
+        }))
+        .is_some());
+    }
+}
diff --git a/crates/core/src/schemas/plugin_config.rs b/crates/core/src/schemas/plugin_config.rs
new file mode 100644
index 000000000..065364400
--- /dev/null
+++ b/crates/core/src/schemas/plugin_config.rs
@@ -0,0 +1,1155 @@
+//! Plugin configuration schema — port of `PluginConfigSchema` from
+//! `lib/schemas.ts` plus `DEFAULT_PLUGIN_CONFIG` from `lib/config.ts`
+//! (spec 01 §2.9/§3.1).
+//!
+//! Zod semantics implemented here (ARCHITECTURE §8.3):
+//! - [`PluginConfig`] deserialization mirrors `PluginConfigSchema.safeParse`:
+//!   every field optional, unknown keys silently stripped, ANY invalid known
+//!   field fails the whole parse (use via `safe_parse_plugin_config`).
+//! - The per-field sanitize path (`loadPluginConfig` /
+//!   `sanitizePluginConfigRecord`) is served by [`validate_field`] /
+//!   [`field_issues`]: config-crate code validates field-by-field over
+//!   `serde_json::Value`s, silently dropping invalid values (warn-once is the
+//!   config crate's business). Working in `Value` space preserves the exact
+//!   number representation of user input for byte-stable saves.
+//! - [`plugin_config_issues`] is the `getValidationErrors(PluginConfigSchema,
+//!   data)` check for use with `parse::validation_errors`.
+//!
+//! Defaults: [`PluginConfig::default_resolved`] is `DEFAULT_PLUGIN_CONFIG`
+//! with every field populated — including `pidOffsetEnabled: true`. The
+//! getter-level inline default of **false** for `getPidOffsetEnabled` is the
+//! config crate's business (spec 01 gotcha §11.3): do NOT "fix" the split.
+//!
+//! Numeric fields are `f64` (JS number semantics; zod bounds validate, they
+//! do not clamp). Serialization prints integral values without a decimal
+//! point, matching `JSON.stringify`.
+
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde_json::Value;
+
+use super::parse::{SchemaIssue, fmt_js_number, json_type_name};
+
+// ============================================================================
+// Enum value types
+// ============================================================================
+
+macro_rules! config_str_enum {
+    ($(#[$meta:meta])* $name:ident { $($variant:ident => $text:literal),+ $(,)? }) => {
+        $(#[$meta])*
+        #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+        pub enum $name {
+            $(#[serde(rename = $text)] $variant),+
+        }
+
+        impl $name {
+            pub fn as_str(&self) -> &'static str {
+                match self {
+                    $(Self::$variant => $text),+
+                }
+            }
+
+            pub fn parse(value: &str) -> Option<Self> {
+                match value {
+                    $($text => Some(Self::$variant),)+
+                    _ => None,
+                }
+            }
+        }
+
+        impl std::fmt::Display for $name {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str(self.as_str())
+            }
+        }
+    };
+}
+
+config_str_enum!(
+    /// `codexTuiColorProfile ∈ {truecolor, ansi16, ansi256}`.
+    CodexTuiColorProfile {
+        Truecolor => "truecolor",
+        Ansi16 => "ansi16",
+        Ansi256 => "ansi256",
+    }
+);
+
+config_str_enum!(
+    /// `codexTuiGlyphMode ∈ {ascii, unicode, auto}`.
+    CodexTuiGlyphMode {
+        Ascii => "ascii",
+        Unicode => "unicode",
+        Auto => "auto",
+    }
+);
+
+config_str_enum!(
+    /// `fastSessionStrategy ∈ {hybrid, always}`.
+    FastSessionStrategy {
+        Hybrid => "hybrid",
+        Always => "always",
+    }
+);
+
+config_str_enum!(
+    /// `unsupportedCodexPolicy ∈ {strict, fallback}` (`UnsupportedCodexPolicy`
+    /// in `lib/config.ts`).
+    UnsupportedCodexPolicy {
+        Strict => "strict",
+        Fallback => "fallback",
+    }
+);
+
+config_str_enum!(
+    /// `routingMutex ∈ {enabled, legacy}`.
+    RoutingMutexMode {
+        Enabled => "enabled",
+        Legacy => "legacy",
+    }
+);
+
+config_str_enum!(
+    /// `schedulingStrategy ∈ {hybrid, sequential}`.
+    SchedulingStrategy {
+        Hybrid => "hybrid",
+        Sequential => "sequential",
+    }
+);
+
+// ============================================================================
+// unsupportedCodexFallbackChain — ordered record<string, string[] (min1)>
+// ============================================================================
+
+/// `unsupportedCodexFallbackChain: Record<string, string[]>` where each array
+/// element is a non-empty string. Preserves key insertion order. Stored RAW
+/// (as validated); the normalization (lowercasing, suffix stripping — which
+/// deliberately does NOT strip `-max`/`-ultra`) happens in the config crate's
+/// `get_unsupported_codex_fallback_chain` getter (spec 01 gotcha §11.8).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct FallbackChain(pub Vec<(String, Vec<String>)>);
+
+impl FallbackChain {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    pub fn get(&self, key: &str) -> Option<&[String]> {
+        self.0
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, targets)| targets.as_slice())
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, &[String])> {
+        self.0.iter().map(|(k, v)| (k.as_str(), v.as_slice()))
+    }
+
+    /// Build from an already-validated JSON value (`validate_field` accepted
+    /// it). Returns `None` when the shape does not match the schema.
+    pub fn from_value(value: &Value) -> Option<Self> {
+        let object = value.as_object()?;
+        let mut entries = Vec::with_capacity(object.len());
+        for (key, targets) in object {
+            let array = targets.as_array()?;
+            let mut list = Vec::with_capacity(array.len());
+            for target in array {
+                let s = target.as_str()?;
+                if s.is_empty() {
+                    return None;
+                }
+                list.push(s.to_string());
+            }
+            entries.push((key.clone(), list));
+        }
+        Some(Self(entries))
+    }
+
+    pub fn to_value(&self) -> Value {
+        let mut map = serde_json::Map::new();
+        for (key, targets) in &self.0 {
+            map.insert(
+                key.clone(),
+                Value::Array(targets.iter().cloned().map(Value::String).collect()),
+            );
+        }
+        Value::Object(map)
+    }
+}
+
+impl Serialize for FallbackChain {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeMap;
+        let mut map = serializer.serialize_map(Some(self.0.len()))?;
+        for (key, targets) in &self.0 {
+            map.serialize_entry(key, targets)?;
+        }
+        map.end()
+    }
+}
+
+impl<'de> Deserialize<'de> for FallbackChain {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        Self::from_value(&value).ok_or_else(|| {
+            serde::de::Error::custom(
+                "Invalid input: expected record of non-empty string arrays",
+            )
+        })
+    }
+}
+
+// ============================================================================
+// Field table (declaration order == zod schema order == explain order)
+// ============================================================================
+
+#[derive(Clone, Copy, Debug)]
+enum FieldKind {
+    Bool,
+    Num { min: f64, max: f64 },
+    Enum(&'static [&'static str]),
+    Chain,
+}
+
+const COLOR_PROFILES: &[&str] = &["truecolor", "ansi16", "ansi256"];
+const GLYPH_MODES: &[&str] = &["ascii", "unicode", "auto"];
+const FAST_SESSION_STRATEGIES: &[&str] = &["hybrid", "always"];
+const UNSUPPORTED_POLICIES: &[&str] = &["strict", "fallback"];
+const ROUTING_MUTEX_MODES: &[&str] = &["enabled", "legacy"];
+const SCHEDULING_STRATEGIES: &[&str] = &["hybrid", "sequential"];
+
+const NUM_FIELD_COUNT: usize = 54;
+
+/// (key, validation) for every `PluginConfigSchema` field, in declaration
+/// order.
+const FIELDS: [(&str, FieldKind); NUM_FIELD_COUNT] = [
+    ("codexMode", FieldKind::Bool),
+    ("codexRuntimeRotationProxy", FieldKind::Bool),
+    ("codexTuiV2", FieldKind::Bool),
+    ("codexTuiColorProfile", FieldKind::Enum(COLOR_PROFILES)),
+    ("codexTuiGlyphMode", FieldKind::Enum(GLYPH_MODES)),
+    ("fastSession", FieldKind::Bool),
+    ("fastSessionStrategy", FieldKind::Enum(FAST_SESSION_STRATEGIES)),
+    ("fastSessionMaxInputItems", FieldKind::Num { min: 8.0, max: 200.0 }),
+    ("retryAllAccountsRateLimited", FieldKind::Bool),
+    ("retryAllAccountsMaxWaitMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("retryAllAccountsMaxRetries", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("unsupportedCodexPolicy", FieldKind::Enum(UNSUPPORTED_POLICIES)),
+    ("fallbackOnUnsupportedCodexModel", FieldKind::Bool),
+    ("fallbackToGpt52OnUnsupportedGpt53", FieldKind::Bool),
+    ("unsupportedCodexFallbackChain", FieldKind::Chain),
+    ("tokenRefreshSkewMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("rateLimitToastDebounceMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("toastDurationMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("perProjectAccounts", FieldKind::Bool),
+    ("sessionRecovery", FieldKind::Bool),
+    ("autoResume", FieldKind::Bool),
+    ("parallelProbing", FieldKind::Bool),
+    ("parallelProbingMaxConcurrency", FieldKind::Num { min: 1.0, max: 5.0 }),
+    ("emptyResponseMaxRetries", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("emptyResponseRetryDelayMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("rateLimitDedupWindowMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("rateLimitStateResetMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("rateLimitMaxBackoffMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("rateLimitShortRetryThresholdMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("pidOffsetEnabled", FieldKind::Bool),
+    ("fetchTimeoutMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("streamStallTimeoutMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("liveAccountSync", FieldKind::Bool),
+    ("liveAccountSyncDebounceMs", FieldKind::Num { min: 50.0, max: f64::INFINITY }),
+    ("liveAccountSyncPollMs", FieldKind::Num { min: 500.0, max: f64::INFINITY }),
+    ("sessionAffinity", FieldKind::Bool),
+    ("sessionAffinityTtlMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("sessionAffinityMaxEntries", FieldKind::Num { min: 8.0, max: f64::INFINITY }),
+    ("responseContinuation", FieldKind::Bool),
+    ("backgroundResponses", FieldKind::Bool),
+    ("proactiveRefreshGuardian", FieldKind::Bool),
+    ("proactiveRefreshIntervalMs", FieldKind::Num { min: 5000.0, max: f64::INFINITY }),
+    ("proactiveRefreshBufferMs", FieldKind::Num { min: 30000.0, max: f64::INFINITY }),
+    ("networkErrorCooldownMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("serverErrorCooldownMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("tokenInvalidationCooldownMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("minRotationIntervalMs", FieldKind::Num { min: 0.0, max: f64::INFINITY }),
+    ("storageBackupEnabled", FieldKind::Bool),
+    ("preemptiveQuotaEnabled", FieldKind::Bool),
+    ("preemptiveQuotaRemainingPercent5h", FieldKind::Num { min: 0.0, max: 100.0 }),
+    ("preemptiveQuotaRemainingPercent7d", FieldKind::Num { min: 0.0, max: 100.0 }),
+    ("preemptiveQuotaMaxDeferralMs", FieldKind::Num { min: 1000.0, max: f64::INFINITY }),
+    ("routingMutex", FieldKind::Enum(ROUTING_MUTEX_MODES)),
+    ("schedulingStrategy", FieldKind::Enum(SCHEDULING_STRATEGIES)),
+];
+
+/// Every known plugin-config key, in zod schema declaration order. (Spec 01
+/// speaks of "53 known keys" but the TS schema declares 54 — the two
+/// unsupported-policy getters share one explain entry; TS wins here.)
+pub const PLUGIN_CONFIG_KEYS: [&str; NUM_FIELD_COUNT] = {
+    let mut keys = [""; NUM_FIELD_COUNT];
+    let mut i = 0;
+    while i < NUM_FIELD_COUNT {
+        keys[i] = FIELDS[i].0;
+        i += 1;
+    }
+    keys
+};
+
+/// Whether `key` is a known `PluginConfigSchema` field. Config-crate save
+/// paths use this to tell "unknown key" (preserved on save) apart from
+/// "invalid value" (dropped with warn-once).
+pub fn is_known_plugin_config_key(key: &str) -> bool {
+    FIELDS.iter().any(|(k, _)| *k == key)
+}
+
+fn field_kind(key: &str) -> Option<FieldKind> {
+    FIELDS
+        .iter()
+        .find(|(k, _)| *k == key)
+        .map(|(_, kind)| *kind)
+}
+
+// ============================================================================
+// Per-field validation (the sanitize path)
+// ============================================================================
+
+/// Validation issues for a single known field (zod-flavored messages, path
+/// rooted at `key`). Empty when valid — AND when `key` is unknown (zod
+/// silently strips unknown keys without an issue; check
+/// [`is_known_plugin_config_key`] first if you need to distinguish).
+pub fn field_issues(key: &str, value: &Value) -> Vec<SchemaIssue> {
+    let Some(kind) = field_kind(key) else {
+        return Vec::new();
+    };
+    let mut issues = Vec::new();
+    match kind {
+        FieldKind::Bool => {
+            if !value.is_boolean() {
+                issues.push(SchemaIssue::new(
+                    vec![key.to_string()],
+                    format!(
+                        "Invalid input: expected boolean, received {}",
+                        json_type_name(value)
+                    ),
+                ));
+            }
+        }
+        FieldKind::Num { min, max } => match value.as_f64() {
+            None => issues.push(SchemaIssue::new(
+                vec![key.to_string()],
+                format!(
+                    "Invalid input: expected number, received {}",
+                    json_type_name(value)
+                ),
+            )),
+            Some(v) if v < min => issues.push(SchemaIssue::new(
+                vec![key.to_string()],
+                format!("Too small: expected number to be >={}", fmt_js_number(min)),
+            )),
+            Some(v) if v > max => issues.push(SchemaIssue::new(
+                vec![key.to_string()],
+                format!("Too big: expected number to be <={}", fmt_js_number(max)),
+            )),
+            Some(_) => {}
+        },
+        FieldKind::Enum(options) => {
+            let valid = value.as_str().is_some_and(|s| options.contains(&s));
+            if !valid {
+                let expected = options
+                    .iter()
+                    .map(|o| format!("\"{o}\""))
+                    .collect::<Vec<_>>()
+                    .join("|");
+                issues.push(SchemaIssue::new(
+                    vec![key.to_string()],
+                    format!("Invalid option: expected one of {expected}"),
+                ));
+            }
+        }
+        FieldKind::Chain => match value.as_object() {
+            None => issues.push(SchemaIssue::new(
+                vec![key.to_string()],
+                format!(
+                    "Invalid input: expected record, received {}",
+                    json_type_name(value)
+                ),
+            )),
+            Some(object) => {
+                for (entry_key, targets) in object {
+                    match targets.as_array() {
+                        None => issues.push(SchemaIssue::new(
+                            vec![key.to_string(), entry_key.clone()],
+                            format!(
+                                "Invalid input: expected array, received {}",
+                                json_type_name(targets)
+                            ),
+                        )),
+                        Some(array) => {
+                            for (index, target) in array.iter().enumerate() {
+                                match target.as_str() {
+                                    None => issues.push(SchemaIssue::new(
+                                        vec![
+                                            key.to_string(),
+                                            entry_key.clone(),
+                                            index.to_string(),
+                                        ],
+                                        format!(
+                                            "Invalid input: expected string, received {}",
+                                            json_type_name(target)
+                                        ),
+                                    )),
+                                    Some("") => issues.push(SchemaIssue::new(
+                                        vec![
+                                            key.to_string(),
+                                            entry_key.clone(),
+                                            index.to_string(),
+                                        ],
+                                        "Too small: expected string to have >=1 characters"
+                                            .to_string(),
+                                    )),
+                                    Some(_) => {}
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+    }
+    issues
+}
+
+/// Per-field zod validation for the sanitize path: `Some(value)` (a clone —
+/// number representation preserved for byte-stable saves) when `key` is a
+/// known field and `value` passes its schema bounds; `None` for unknown keys
+/// AND for invalid values. Spec: ARCHITECTURE §6.1
+/// `validate_field(key, &Value) -> Option<Value>`.
+pub fn validate_field(key: &str, value: &Value) -> Option<Value> {
+    if !is_known_plugin_config_key(key) {
+        return None;
+    }
+    if field_issues(key, value).is_empty() {
+        Some(value.clone())
+    } else {
+        None
+    }
+}
+
+/// `getValidationErrors(PluginConfigSchema, data)` check: a non-object root
+/// yields a single path-less issue; otherwise every known key present is
+/// validated (unknown keys are stripped silently, producing no issue).
+pub fn plugin_config_issues(value: &Value) -> Vec<SchemaIssue> {
+    let Some(map) = value.as_object() else {
+        return vec![SchemaIssue::root(format!(
+            "Invalid input: expected object, received {}",
+            json_type_name(value)
+        ))];
+    };
+    let mut issues = Vec::new();
+    for (key, _) in FIELDS.iter() {
+        if let Some(field_value) = map.get(*key) {
+            issues.extend(field_issues(key, field_value));
+        }
+    }
+    issues
+}
+
+// ============================================================================
+// PluginConfig struct
+// ============================================================================
+
+/// Serialize an `Option<f64>` the way `JSON.stringify` prints JS numbers:
+/// integral values without a decimal point. Only reached when `Some` (fields
+/// carry `skip_serializing_if = "Option::is_none"`).
+fn ser_opt_js_number<S: Serializer>(value: &Option<f64>, serializer: S) -> Result<S::Ok, S::Error> {
+    match value {
+        Some(v)
+            if v.is_finite() && v.fract() == 0.0 && v.abs() < 9.007_199_254_740_992e15 =>
+        {
+            serializer.serialize_i64(*v as i64)
+        }
+        Some(v) => serializer.serialize_f64(*v),
+        None => serializer.serialize_none(),
+    }
+}
+
+macro_rules! plugin_config_struct {
+    ($(($field:ident, $key:literal, $ty:ty $(, $ser:literal)?)),+ $(,)?) => {
+        /// The 54-field plugin configuration (`PluginConfig` =
+        /// `z.infer<typeof PluginConfigSchema>`). Every field optional;
+        /// serde names are the exact camelCase schema keys; `None` fields are
+        /// omitted on serialization; declaration order == schema order.
+        #[derive(Clone, Debug, Default, PartialEq, Serialize)]
+        pub struct PluginConfig {
+            $(
+                #[serde(rename = $key, skip_serializing_if = "Option::is_none" $(, serialize_with = $ser)?)]
+                pub $field: Option<$ty>,
+            )+
+        }
+    };
+}
+
+plugin_config_struct![
+    (codex_mode, "codexMode", bool),
+    (codex_runtime_rotation_proxy, "codexRuntimeRotationProxy", bool),
+    (codex_tui_v2, "codexTuiV2", bool),
+    (codex_tui_color_profile, "codexTuiColorProfile", CodexTuiColorProfile),
+    (codex_tui_glyph_mode, "codexTuiGlyphMode", CodexTuiGlyphMode),
+    (fast_session, "fastSession", bool),
+    (fast_session_strategy, "fastSessionStrategy", FastSessionStrategy),
+    (fast_session_max_input_items, "fastSessionMaxInputItems", f64, "ser_opt_js_number"),
+    (retry_all_accounts_rate_limited, "retryAllAccountsRateLimited", bool),
+    (retry_all_accounts_max_wait_ms, "retryAllAccountsMaxWaitMs", f64, "ser_opt_js_number"),
+    (retry_all_accounts_max_retries, "retryAllAccountsMaxRetries", f64, "ser_opt_js_number"),
+    (unsupported_codex_policy, "unsupportedCodexPolicy", UnsupportedCodexPolicy),
+    (fallback_on_unsupported_codex_model, "fallbackOnUnsupportedCodexModel", bool),
+    (fallback_to_gpt52_on_unsupported_gpt53, "fallbackToGpt52OnUnsupportedGpt53", bool),
+    (unsupported_codex_fallback_chain, "unsupportedCodexFallbackChain", FallbackChain),
+    (token_refresh_skew_ms, "tokenRefreshSkewMs", f64, "ser_opt_js_number"),
+    (rate_limit_toast_debounce_ms, "rateLimitToastDebounceMs", f64, "ser_opt_js_number"),
+    (toast_duration_ms, "toastDurationMs", f64, "ser_opt_js_number"),
+    (per_project_accounts, "perProjectAccounts", bool),
+    (session_recovery, "sessionRecovery", bool),
+    (auto_resume, "autoResume", bool),
+    (parallel_probing, "parallelProbing", bool),
+    (parallel_probing_max_concurrency, "parallelProbingMaxConcurrency", f64, "ser_opt_js_number"),
+    (empty_response_max_retries, "emptyResponseMaxRetries", f64, "ser_opt_js_number"),
+    (empty_response_retry_delay_ms, "emptyResponseRetryDelayMs", f64, "ser_opt_js_number"),
+    (rate_limit_dedup_window_ms, "rateLimitDedupWindowMs", f64, "ser_opt_js_number"),
+    (rate_limit_state_reset_ms, "rateLimitStateResetMs", f64, "ser_opt_js_number"),
+    (rate_limit_max_backoff_ms, "rateLimitMaxBackoffMs", f64, "ser_opt_js_number"),
+    (rate_limit_short_retry_threshold_ms, "rateLimitShortRetryThresholdMs", f64, "ser_opt_js_number"),
+    (pid_offset_enabled, "pidOffsetEnabled", bool),
+    (fetch_timeout_ms, "fetchTimeoutMs", f64, "ser_opt_js_number"),
+    (stream_stall_timeout_ms, "streamStallTimeoutMs", f64, "ser_opt_js_number"),
+    (live_account_sync, "liveAccountSync", bool),
+    (live_account_sync_debounce_ms, "liveAccountSyncDebounceMs", f64, "ser_opt_js_number"),
+    (live_account_sync_poll_ms, "liveAccountSyncPollMs", f64, "ser_opt_js_number"),
+    (session_affinity, "sessionAffinity", bool),
+    (session_affinity_ttl_ms, "sessionAffinityTtlMs", f64, "ser_opt_js_number"),
+    (session_affinity_max_entries, "sessionAffinityMaxEntries", f64, "ser_opt_js_number"),
+    (response_continuation, "responseContinuation", bool),
+    (background_responses, "backgroundResponses", bool),
+    (proactive_refresh_guardian, "proactiveRefreshGuardian", bool),
+    (proactive_refresh_interval_ms, "proactiveRefreshIntervalMs", f64, "ser_opt_js_number"),
+    (proactive_refresh_buffer_ms, "proactiveRefreshBufferMs", f64, "ser_opt_js_number"),
+    (network_error_cooldown_ms, "networkErrorCooldownMs", f64, "ser_opt_js_number"),
+    (server_error_cooldown_ms, "serverErrorCooldownMs", f64, "ser_opt_js_number"),
+    (token_invalidation_cooldown_ms, "tokenInvalidationCooldownMs", f64, "ser_opt_js_number"),
+    (min_rotation_interval_ms, "minRotationIntervalMs", f64, "ser_opt_js_number"),
+    (storage_backup_enabled, "storageBackupEnabled", bool),
+    (preemptive_quota_enabled, "preemptiveQuotaEnabled", bool),
+    (preemptive_quota_remaining_percent_5h, "preemptiveQuotaRemainingPercent5h", f64, "ser_opt_js_number"),
+    (preemptive_quota_remaining_percent_7d, "preemptiveQuotaRemainingPercent7d", f64, "ser_opt_js_number"),
+    (preemptive_quota_max_deferral_ms, "preemptiveQuotaMaxDeferralMs", f64, "ser_opt_js_number"),
+    (routing_mutex, "routingMutex", RoutingMutexMode),
+    (scheduling_strategy, "schedulingStrategy", SchedulingStrategy),
+];
+
+impl PluginConfig {
+    /// `DEFAULT_PLUGIN_CONFIG` — the fully-resolved defaults table from
+    /// `lib/config.ts` with every field present. NOTE
+    /// `pidOffsetEnabled: true` here vs the getter-level inline default of
+    /// false (spec 01 gotcha §11.3) — the split is deliberate and lives in
+    /// the config crate's getter.
+    pub fn default_resolved() -> Self {
+        Self {
+            codex_mode: Some(true),
+            codex_runtime_rotation_proxy: Some(true),
+            codex_tui_v2: Some(true),
+            codex_tui_color_profile: Some(CodexTuiColorProfile::Truecolor),
+            codex_tui_glyph_mode: Some(CodexTuiGlyphMode::Ascii),
+            fast_session: Some(false),
+            fast_session_strategy: Some(FastSessionStrategy::Hybrid),
+            fast_session_max_input_items: Some(30.0),
+            retry_all_accounts_rate_limited: Some(false),
+            retry_all_accounts_max_wait_ms: Some(0.0),
+            retry_all_accounts_max_retries: Some(0.0),
+            unsupported_codex_policy: Some(UnsupportedCodexPolicy::Strict),
+            fallback_on_unsupported_codex_model: Some(false),
+            fallback_to_gpt52_on_unsupported_gpt53: Some(true),
+            unsupported_codex_fallback_chain: Some(FallbackChain::new()),
+            token_refresh_skew_ms: Some(60_000.0),
+            rate_limit_toast_debounce_ms: Some(60_000.0),
+            toast_duration_ms: Some(5_000.0),
+            per_project_accounts: Some(true),
+            session_recovery: Some(true),
+            auto_resume: Some(true),
+            parallel_probing: Some(false),
+            parallel_probing_max_concurrency: Some(2.0),
+            empty_response_max_retries: Some(2.0),
+            empty_response_retry_delay_ms: Some(1_000.0),
+            rate_limit_dedup_window_ms: Some(2_000.0),
+            rate_limit_state_reset_ms: Some(120_000.0),
+            rate_limit_max_backoff_ms: Some(60_000.0),
+            rate_limit_short_retry_threshold_ms: Some(5_000.0),
+            // Default-on so parallel wrapper processes each bias toward a
+            // different account (#628); the getter-level false is the config
+            // crate's business.
+            pid_offset_enabled: Some(true),
+            fetch_timeout_ms: Some(60_000.0),
+            stream_stall_timeout_ms: Some(45_000.0),
+            live_account_sync: Some(true),
+            live_account_sync_debounce_ms: Some(250.0),
+            live_account_sync_poll_ms: Some(2_000.0),
+            session_affinity: Some(true),
+            session_affinity_ttl_ms: Some(1_200_000.0),
+            session_affinity_max_entries: Some(512.0),
+            response_continuation: Some(false),
+            background_responses: Some(false),
+            proactive_refresh_guardian: Some(true),
+            proactive_refresh_interval_ms: Some(60_000.0),
+            proactive_refresh_buffer_ms: Some(300_000.0),
+            network_error_cooldown_ms: Some(6_000.0),
+            server_error_cooldown_ms: Some(4_000.0),
+            token_invalidation_cooldown_ms: Some(300_000.0),
+            min_rotation_interval_ms: Some(60_000.0),
+            storage_backup_enabled: Some(true),
+            preemptive_quota_enabled: Some(true),
+            preemptive_quota_remaining_percent_5h: Some(5.0),
+            preemptive_quota_remaining_percent_7d: Some(5.0),
+            preemptive_quota_max_deferral_ms: Some(7_200_000.0),
+            routing_mutex: Some(RoutingMutexMode::Legacy),
+            scheduling_strategy: Some(SchedulingStrategy::Hybrid),
+        }
+    }
+
+    /// JS spread semantics `{...base, ...patch}`: every `Some` field of
+    /// `patch` overrides `base`. Used by the config crate's
+    /// `loadPluginConfig` merge (`{...DEFAULT_PLUGIN_CONFIG, ...sanitized}`).
+    pub fn overlay(base: &Self, patch: &Self) -> Self {
+        macro_rules! pick {
+            ($field:ident) => {
+                patch.$field.clone().or_else(|| base.$field.clone())
+            };
+        }
+        Self {
+            codex_mode: pick!(codex_mode),
+            codex_runtime_rotation_proxy: pick!(codex_runtime_rotation_proxy),
+            codex_tui_v2: pick!(codex_tui_v2),
+            codex_tui_color_profile: pick!(codex_tui_color_profile),
+            codex_tui_glyph_mode: pick!(codex_tui_glyph_mode),
+            fast_session: pick!(fast_session),
+            fast_session_strategy: pick!(fast_session_strategy),
+            fast_session_max_input_items: pick!(fast_session_max_input_items),
+            retry_all_accounts_rate_limited: pick!(retry_all_accounts_rate_limited),
+            retry_all_accounts_max_wait_ms: pick!(retry_all_accounts_max_wait_ms),
+            retry_all_accounts_max_retries: pick!(retry_all_accounts_max_retries),
+            unsupported_codex_policy: pick!(unsupported_codex_policy),
+            fallback_on_unsupported_codex_model: pick!(fallback_on_unsupported_codex_model),
+            fallback_to_gpt52_on_unsupported_gpt53: pick!(fallback_to_gpt52_on_unsupported_gpt53),
+            unsupported_codex_fallback_chain: pick!(unsupported_codex_fallback_chain),
+            token_refresh_skew_ms: pick!(token_refresh_skew_ms),
+            rate_limit_toast_debounce_ms: pick!(rate_limit_toast_debounce_ms),
+            toast_duration_ms: pick!(toast_duration_ms),
+            per_project_accounts: pick!(per_project_accounts),
+            session_recovery: pick!(session_recovery),
+            auto_resume: pick!(auto_resume),
+            parallel_probing: pick!(parallel_probing),
+            parallel_probing_max_concurrency: pick!(parallel_probing_max_concurrency),
+            empty_response_max_retries: pick!(empty_response_max_retries),
+            empty_response_retry_delay_ms: pick!(empty_response_retry_delay_ms),
+            rate_limit_dedup_window_ms: pick!(rate_limit_dedup_window_ms),
+            rate_limit_state_reset_ms: pick!(rate_limit_state_reset_ms),
+            rate_limit_max_backoff_ms: pick!(rate_limit_max_backoff_ms),
+            rate_limit_short_retry_threshold_ms: pick!(rate_limit_short_retry_threshold_ms),
+            pid_offset_enabled: pick!(pid_offset_enabled),
+            fetch_timeout_ms: pick!(fetch_timeout_ms),
+            stream_stall_timeout_ms: pick!(stream_stall_timeout_ms),
+            live_account_sync: pick!(live_account_sync),
+            live_account_sync_debounce_ms: pick!(live_account_sync_debounce_ms),
+            live_account_sync_poll_ms: pick!(live_account_sync_poll_ms),
+            session_affinity: pick!(session_affinity),
+            session_affinity_ttl_ms: pick!(session_affinity_ttl_ms),
+            session_affinity_max_entries: pick!(session_affinity_max_entries),
+            response_continuation: pick!(response_continuation),
+            background_responses: pick!(background_responses),
+            proactive_refresh_guardian: pick!(proactive_refresh_guardian),
+            proactive_refresh_interval_ms: pick!(proactive_refresh_interval_ms),
+            proactive_refresh_buffer_ms: pick!(proactive_refresh_buffer_ms),
+            network_error_cooldown_ms: pick!(network_error_cooldown_ms),
+            server_error_cooldown_ms: pick!(server_error_cooldown_ms),
+            token_invalidation_cooldown_ms: pick!(token_invalidation_cooldown_ms),
+            min_rotation_interval_ms: pick!(min_rotation_interval_ms),
+            storage_backup_enabled: pick!(storage_backup_enabled),
+            preemptive_quota_enabled: pick!(preemptive_quota_enabled),
+            preemptive_quota_remaining_percent_5h: pick!(preemptive_quota_remaining_percent_5h),
+            preemptive_quota_remaining_percent_7d: pick!(preemptive_quota_remaining_percent_7d),
+            preemptive_quota_max_deferral_ms: pick!(preemptive_quota_max_deferral_ms),
+            routing_mutex: pick!(routing_mutex),
+            scheduling_strategy: pick!(scheduling_strategy),
+        }
+    }
+
+    /// Assign an already-validated field value ([`field_issues`] returned
+    /// empty for it). Unknown keys are ignored.
+    fn apply_validated(&mut self, key: &str, value: &Value) {
+        let as_bool = || value.as_bool().unwrap_or_default();
+        let as_num = || value.as_f64().unwrap_or_default();
+        match key {
+            "codexMode" => self.codex_mode = Some(as_bool()),
+            "codexRuntimeRotationProxy" => self.codex_runtime_rotation_proxy = Some(as_bool()),
+            "codexTuiV2" => self.codex_tui_v2 = Some(as_bool()),
+            "codexTuiColorProfile" => {
+                self.codex_tui_color_profile =
+                    value.as_str().and_then(CodexTuiColorProfile::parse);
+            }
+            "codexTuiGlyphMode" => {
+                self.codex_tui_glyph_mode = value.as_str().and_then(CodexTuiGlyphMode::parse);
+            }
+            "fastSession" => self.fast_session = Some(as_bool()),
+            "fastSessionStrategy" => {
+                self.fast_session_strategy = value.as_str().and_then(FastSessionStrategy::parse);
+            }
+            "fastSessionMaxInputItems" => self.fast_session_max_input_items = Some(as_num()),
+            "retryAllAccountsRateLimited" => {
+                self.retry_all_accounts_rate_limited = Some(as_bool());
+            }
+            "retryAllAccountsMaxWaitMs" => self.retry_all_accounts_max_wait_ms = Some(as_num()),
+            "retryAllAccountsMaxRetries" => self.retry_all_accounts_max_retries = Some(as_num()),
+            "unsupportedCodexPolicy" => {
+                self.unsupported_codex_policy =
+                    value.as_str().and_then(UnsupportedCodexPolicy::parse);
+            }
+            "fallbackOnUnsupportedCodexModel" => {
+                self.fallback_on_unsupported_codex_model = Some(as_bool());
+            }
+            "fallbackToGpt52OnUnsupportedGpt53" => {
+                self.fallback_to_gpt52_on_unsupported_gpt53 = Some(as_bool());
+            }
+            "unsupportedCodexFallbackChain" => {
+                self.unsupported_codex_fallback_chain = FallbackChain::from_value(value);
+            }
+            "tokenRefreshSkewMs" => self.token_refresh_skew_ms = Some(as_num()),
+            "rateLimitToastDebounceMs" => self.rate_limit_toast_debounce_ms = Some(as_num()),
+            "toastDurationMs" => self.toast_duration_ms = Some(as_num()),
+            "perProjectAccounts" => self.per_project_accounts = Some(as_bool()),
+            "sessionRecovery" => self.session_recovery = Some(as_bool()),
+            "autoResume" => self.auto_resume = Some(as_bool()),
+            "parallelProbing" => self.parallel_probing = Some(as_bool()),
+            "parallelProbingMaxConcurrency" => {
+                self.parallel_probing_max_concurrency = Some(as_num());
+            }
+            "emptyResponseMaxRetries" => self.empty_response_max_retries = Some(as_num()),
+            "emptyResponseRetryDelayMs" => self.empty_response_retry_delay_ms = Some(as_num()),
+            "rateLimitDedupWindowMs" => self.rate_limit_dedup_window_ms = Some(as_num()),
+            "rateLimitStateResetMs" => self.rate_limit_state_reset_ms = Some(as_num()),
+            "rateLimitMaxBackoffMs" => self.rate_limit_max_backoff_ms = Some(as_num()),
+            "rateLimitShortRetryThresholdMs" => {
+                self.rate_limit_short_retry_threshold_ms = Some(as_num());
+            }
+            "pidOffsetEnabled" => self.pid_offset_enabled = Some(as_bool()),
+            "fetchTimeoutMs" => self.fetch_timeout_ms = Some(as_num()),
+            "streamStallTimeoutMs" => self.stream_stall_timeout_ms = Some(as_num()),
+            "liveAccountSync" => self.live_account_sync = Some(as_bool()),
+            "liveAccountSyncDebounceMs" => self.live_account_sync_debounce_ms = Some(as_num()),
+            "liveAccountSyncPollMs" => self.live_account_sync_poll_ms = Some(as_num()),
+            "sessionAffinity" => self.session_affinity = Some(as_bool()),
+            "sessionAffinityTtlMs" => self.session_affinity_ttl_ms = Some(as_num()),
+            "sessionAffinityMaxEntries" => self.session_affinity_max_entries = Some(as_num()),
+            "responseContinuation" => self.response_continuation = Some(as_bool()),
+            "backgroundResponses" => self.background_responses = Some(as_bool()),
+            "proactiveRefreshGuardian" => self.proactive_refresh_guardian = Some(as_bool()),
+            "proactiveRefreshIntervalMs" => self.proactive_refresh_interval_ms = Some(as_num()),
+            "proactiveRefreshBufferMs" => self.proactive_refresh_buffer_ms = Some(as_num()),
+            "networkErrorCooldownMs" => self.network_error_cooldown_ms = Some(as_num()),
+            "serverErrorCooldownMs" => self.server_error_cooldown_ms = Some(as_num()),
+            "tokenInvalidationCooldownMs" => {
+                self.token_invalidation_cooldown_ms = Some(as_num());
+            }
+            "minRotationIntervalMs" => self.min_rotation_interval_ms = Some(as_num()),
+            "storageBackupEnabled" => self.storage_backup_enabled = Some(as_bool()),
+            "preemptiveQuotaEnabled" => self.preemptive_quota_enabled = Some(as_bool()),
+            "preemptiveQuotaRemainingPercent5h" => {
+                self.preemptive_quota_remaining_percent_5h = Some(as_num());
+            }
+            "preemptiveQuotaRemainingPercent7d" => {
+                self.preemptive_quota_remaining_percent_7d = Some(as_num());
+            }
+            "preemptiveQuotaMaxDeferralMs" => {
+                self.preemptive_quota_max_deferral_ms = Some(as_num());
+            }
+            "routingMutex" => {
+                self.routing_mutex = value.as_str().and_then(RoutingMutexMode::parse);
+            }
+            "schedulingStrategy" => {
+                self.scheduling_strategy = value.as_str().and_then(SchedulingStrategy::parse);
+            }
+            _ => {}
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for PluginConfig {
+    /// Whole-schema `safeParse` semantics: non-object input fails; unknown
+    /// keys are stripped; ANY invalid known field fails the whole parse with
+    /// the first issue's message.
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        let Some(map) = value.as_object() else {
+            return Err(serde::de::Error::custom(format!(
+                "Invalid input: expected object, received {}",
+                json_type_name(&value)
+            )));
+        };
+        let mut config = PluginConfig::default();
+        for (key, _) in FIELDS.iter() {
+            let Some(field_value) = map.get(*key) else {
+                continue;
+            };
+            let issues = field_issues(key, field_value);
+            if let Some(first) = issues.first() {
+                return Err(serde::de::Error::custom(first.format()));
+            }
+            config.apply_validated(key, field_value);
+        }
+        Ok(config)
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts PluginConfigSchema suite)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn parse(value: Value) -> Result<PluginConfig, serde_json::Error> {
+        serde_json::from_value(value)
+    }
+
+    #[test]
+    fn accepts_empty_object_all_optional() {
+        let config = parse(json!({})).expect("empty object parses");
+        assert_eq!(config, PluginConfig::default());
+    }
+
+    #[test]
+    fn accepts_valid_full_config() {
+        let config = parse(json!({
+            "codexMode": true,
+            "codexRuntimeRotationProxy": true,
+            "fastSession": true,
+            "retryAllAccountsRateLimited": true,
+            "retryAllAccountsMaxWaitMs": 5000,
+            "retryAllAccountsMaxRetries": 3,
+            "unsupportedCodexPolicy": "strict",
+            "fallbackOnUnsupportedCodexModel": true,
+            "fallbackToGpt52OnUnsupportedGpt53": false,
+            "unsupportedCodexFallbackChain": {
+                "gpt-5.3-codex-spark": ["gpt-5.3-codex", "gpt-5.2-codex"],
+            },
+            "tokenRefreshSkewMs": 60000,
+            "rateLimitToastDebounceMs": 30000,
+            "toastDurationMs": 5000,
+            "perProjectAccounts": true,
+            "sessionRecovery": true,
+            "autoResume": false,
+            "rateLimitDedupWindowMs": 2000,
+            "rateLimitStateResetMs": 120000,
+            "rateLimitMaxBackoffMs": 60000,
+            "rateLimitShortRetryThresholdMs": 5000,
+            "fetchTimeoutMs": 60000,
+            "streamStallTimeoutMs": 45000,
+            "liveAccountSync": true,
+            "liveAccountSyncDebounceMs": 250,
+            "liveAccountSyncPollMs": 2000,
+            "sessionAffinity": true,
+            "sessionAffinityTtlMs": 1200000,
+            "sessionAffinityMaxEntries": 512,
+            "proactiveRefreshGuardian": true,
+            "proactiveRefreshIntervalMs": 60000,
+            "proactiveRefreshBufferMs": 300000,
+            "networkErrorCooldownMs": 6000,
+            "serverErrorCooldownMs": 4000,
+            "preemptiveQuotaEnabled": true,
+            "preemptiveQuotaRemainingPercent5h": 5,
+            "preemptiveQuotaRemainingPercent7d": 5,
+            "preemptiveQuotaMaxDeferralMs": 120000,
+        }))
+        .expect("full config parses");
+        assert_eq!(config.auto_resume, Some(false));
+        assert_eq!(
+            config.unsupported_codex_policy,
+            Some(UnsupportedCodexPolicy::Strict)
+        );
+        let chain = config.unsupported_codex_fallback_chain.expect("chain kept");
+        assert_eq!(
+            chain.get("gpt-5.3-codex-spark"),
+            Some(&["gpt-5.3-codex".to_string(), "gpt-5.2-codex".to_string()][..])
+        );
+    }
+
+    #[test]
+    fn enforces_minimums() {
+        let cases: &[(&str, f64, f64)] = &[
+            ("rateLimitStateResetMs", 999.0, 1000.0),
+            ("rateLimitMaxBackoffMs", 999.0, 1000.0),
+            ("liveAccountSyncDebounceMs", 49.0, 50.0),
+            ("liveAccountSyncPollMs", 499.0, 500.0),
+            ("sessionAffinityTtlMs", 999.0, 1000.0),
+            ("sessionAffinityMaxEntries", 7.0, 8.0),
+            ("proactiveRefreshIntervalMs", 4999.0, 5000.0),
+            ("proactiveRefreshBufferMs", 29999.0, 30000.0),
+            ("preemptiveQuotaMaxDeferralMs", 999.0, 1000.0),
+        ];
+        for (key, invalid, valid) in cases {
+            assert!(
+                parse(json!({ *key: invalid })).is_err(),
+                "{key}={invalid} should fail"
+            );
+            assert!(
+                parse(json!({ *key: valid })).is_ok(),
+                "{key}={valid} should pass"
+            );
+            assert!(validate_field(key, &json!(invalid)).is_none());
+            assert!(validate_field(key, &json!(valid)).is_some());
+        }
+    }
+
+    #[test]
+    fn allows_zero_and_rejects_negatives() {
+        for key in [
+            "rateLimitDedupWindowMs",
+            "rateLimitShortRetryThresholdMs",
+            "networkErrorCooldownMs",
+            "serverErrorCooldownMs",
+            "tokenInvalidationCooldownMs",
+            "minRotationIntervalMs",
+        ] {
+            assert!(parse(json!({ key: -1 })).is_err(), "{key}=-1 should fail");
+            assert!(parse(json!({ key: 0 })).is_ok(), "{key}=0 should pass");
+        }
+    }
+
+    #[test]
+    fn enforces_0_to_100_range() {
+        for key in [
+            "preemptiveQuotaRemainingPercent5h",
+            "preemptiveQuotaRemainingPercent7d",
+        ] {
+            assert!(parse(json!({ key: -1 })).is_err());
+            assert!(parse(json!({ key: 0 })).is_ok());
+            assert!(parse(json!({ key: 100 })).is_ok());
+            assert!(parse(json!({ key: 101 })).is_err());
+        }
+    }
+
+    #[test]
+    fn rejects_string_values_for_numeric_keys() {
+        for key in [
+            "liveAccountSyncDebounceMs",
+            "liveAccountSyncPollMs",
+            "sessionAffinityTtlMs",
+            "sessionAffinityMaxEntries",
+            "proactiveRefreshIntervalMs",
+            "proactiveRefreshBufferMs",
+            "rateLimitDedupWindowMs",
+            "rateLimitStateResetMs",
+            "rateLimitMaxBackoffMs",
+            "rateLimitShortRetryThresholdMs",
+            "networkErrorCooldownMs",
+            "serverErrorCooldownMs",
+            "tokenInvalidationCooldownMs",
+            "minRotationIntervalMs",
+            "preemptiveQuotaRemainingPercent5h",
+            "preemptiveQuotaRemainingPercent7d",
+            "preemptiveQuotaMaxDeferralMs",
+        ] {
+            assert!(
+                parse(json!({ key: "123" })).is_err(),
+                "{key}=\"123\" should fail"
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_toast_duration_below_1000() {
+        assert!(parse(json!({ "toastDurationMs": 500 })).is_err());
+    }
+
+    #[test]
+    fn rejects_negative_numbers_for_numeric_fields() {
+        assert!(parse(json!({ "retryAllAccountsMaxWaitMs": -100 })).is_err());
+    }
+
+    #[test]
+    fn rejects_timeout_settings_below_1000ms() {
+        assert!(parse(json!({ "fetchTimeoutMs": 999 })).is_err());
+        assert!(parse(json!({ "streamStallTimeoutMs": 999 })).is_err());
+    }
+
+    #[test]
+    fn rejects_wrong_types() {
+        assert!(parse(json!({ "codexMode": "yes" })).is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_unsupported_codex_policy() {
+        assert!(parse(json!({ "unsupportedCodexPolicy": "invalid" })).is_err());
+    }
+
+    #[test]
+    fn strips_unknown_keys_instead_of_failing() {
+        let config = parse(json!({ "someFutureKey": {"x": 1}, "codexMode": true }))
+            .expect("unknown keys stripped");
+        assert_eq!(config.codex_mode, Some(true));
+    }
+
+    #[test]
+    fn fallback_chain_validation() {
+        assert!(parse(json!({ "unsupportedCodexFallbackChain": { "a": ["b"] } })).is_ok());
+        assert!(parse(json!({ "unsupportedCodexFallbackChain": { "a": "b" } })).is_err());
+        assert!(parse(json!({ "unsupportedCodexFallbackChain": { "a": [""] } })).is_err());
+        assert!(parse(json!({ "unsupportedCodexFallbackChain": ["a"] })).is_err());
+    }
+
+    #[test]
+    fn default_resolved_matches_default_plugin_config_table() {
+        let defaults = PluginConfig::default_resolved();
+        assert_eq!(defaults.codex_mode, Some(true));
+        assert_eq!(
+            defaults.codex_tui_color_profile,
+            Some(CodexTuiColorProfile::Truecolor)
+        );
+        assert_eq!(defaults.codex_tui_glyph_mode, Some(CodexTuiGlyphMode::Ascii));
+        assert_eq!(defaults.fast_session, Some(false));
+        assert_eq!(defaults.fast_session_max_input_items, Some(30.0));
+        assert_eq!(
+            defaults.unsupported_codex_policy,
+            Some(UnsupportedCodexPolicy::Strict)
+        );
+        assert_eq!(
+            defaults.unsupported_codex_fallback_chain,
+            Some(FallbackChain::new())
+        );
+        assert_eq!(defaults.toast_duration_ms, Some(5000.0));
+        // The DEFAULTS-vs-getter split (spec 01 gotcha §11.3): true HERE.
+        assert_eq!(defaults.pid_offset_enabled, Some(true));
+        assert_eq!(defaults.session_affinity_ttl_ms, Some(1_200_000.0));
+        assert_eq!(defaults.token_invalidation_cooldown_ms, Some(300_000.0));
+        assert_eq!(defaults.preemptive_quota_max_deferral_ms, Some(7_200_000.0));
+        assert_eq!(defaults.routing_mutex, Some(RoutingMutexMode::Legacy));
+        assert_eq!(defaults.scheduling_strategy, Some(SchedulingStrategy::Hybrid));
+        // Every field is populated in the resolved defaults.
+        let serialized = serde_json::to_value(&defaults).unwrap();
+        assert_eq!(
+            serialized.as_object().unwrap().len(),
+            PLUGIN_CONFIG_KEYS.len()
+        );
+    }
+
+    #[test]
+    fn serializes_numbers_without_decimal_point() {
+        let defaults = PluginConfig::default_resolved();
+        let raw = serde_json::to_string(&defaults).unwrap();
+        assert!(raw.contains("\"toastDurationMs\":5000"), "raw: {raw}");
+        assert!(raw.contains("\"fastSessionMaxInputItems\":30"), "raw: {raw}");
+        assert!(!raw.contains(".0"), "no float artifacts: {raw}");
+        // Empty patch serializes to an empty object.
+        assert_eq!(serde_json::to_string(&PluginConfig::default()).unwrap(), "{}");
+    }
+
+    #[test]
+    fn round_trips_through_serialization() {
+        let defaults = PluginConfig::default_resolved();
+        let raw = serde_json::to_string(&defaults).unwrap();
+        let parsed: PluginConfig = serde_json::from_str(&raw).expect("round-trip parses");
+        assert_eq!(parsed, defaults);
+    }
+
+    #[test]
+    fn validate_field_returns_clone_for_valid_and_none_for_invalid_or_unknown() {
+        assert_eq!(
+            validate_field("codexMode", &json!(true)),
+            Some(json!(true))
+        );
+        assert_eq!(validate_field("codexMode", &json!("yes")), None);
+        assert_eq!(validate_field("notAField", &json!(true)), None);
+        assert_eq!(
+            validate_field("fastSessionMaxInputItems", &json!(30)),
+            Some(json!(30))
+        );
+        assert_eq!(validate_field("fastSessionMaxInputItems", &json!(7)), None);
+        assert_eq!(validate_field("fastSessionMaxInputItems", &json!(201)), None);
+        assert_eq!(
+            validate_field("codexTuiColorProfile", &json!("ansi16")),
+            Some(json!("ansi16"))
+        );
+        assert_eq!(validate_field("codexTuiColorProfile", &json!("bogus")), None);
+        // Null is invalid for optional fields (zod optional ≠ nullable).
+        assert_eq!(validate_field("codexMode", &Value::Null), None);
+    }
+
+    #[test]
+    fn is_known_plugin_config_key_distinguishes_unknown_keys() {
+        assert!(is_known_plugin_config_key("codexMode"));
+        assert!(is_known_plugin_config_key("schedulingStrategy"));
+        assert!(!is_known_plugin_config_key("somethingElse"));
+        assert_eq!(PLUGIN_CONFIG_KEYS.len(), 54);
+        assert_eq!(PLUGIN_CONFIG_KEYS[0], "codexMode");
+        assert_eq!(PLUGIN_CONFIG_KEYS[53], "schedulingStrategy");
+    }
+
+    #[test]
+    fn plugin_config_issues_reports_paths_and_root_failures() {
+        let issues = plugin_config_issues(&json!({ "codexMode": "yes" }));
+        assert_eq!(issues.len(), 1);
+        assert_eq!(issues[0].path, vec!["codexMode".to_string()]);
+        assert!(issues[0].message.contains("expected boolean"));
+
+        let root = plugin_config_issues(&json!("not-an-object"));
+        assert_eq!(root.len(), 1);
+        assert!(root[0].path.is_empty());
+        assert_eq!(
+            root[0].message,
+            "Invalid input: expected object, received string"
+        );
+
+        assert!(plugin_config_issues(&json!({ "codexMode": true })).is_empty());
+    }
+
+    #[test]
+    fn overlay_applies_js_spread_semantics() {
+        let base = PluginConfig::default_resolved();
+        let patch = PluginConfig {
+            codex_mode: Some(false),
+            toast_duration_ms: Some(9000.0),
+            ..PluginConfig::default()
+        };
+        let merged = PluginConfig::overlay(&base, &patch);
+        assert_eq!(merged.codex_mode, Some(false));
+        assert_eq!(merged.toast_duration_ms, Some(9000.0));
+        // Untouched fields keep base values.
+        assert_eq!(merged.pid_offset_enabled, Some(true));
+        assert_eq!(merged.routing_mutex, Some(RoutingMutexMode::Legacy));
+    }
+
+    #[test]
+    fn enum_parse_helpers() {
+        assert_eq!(
+            CodexTuiColorProfile::parse("truecolor"),
+            Some(CodexTuiColorProfile::Truecolor)
+        );
+        assert_eq!(CodexTuiColorProfile::parse("TRUECOLOR"), None);
+        assert_eq!(
+            FastSessionStrategy::parse("always"),
+            Some(FastSessionStrategy::Always)
+        );
+        assert_eq!(
+            RoutingMutexMode::parse("enabled"),
+            Some(RoutingMutexMode::Enabled)
+        );
+        assert_eq!(
+            SchedulingStrategy::parse("sequential"),
+            Some(SchedulingStrategy::Sequential)
+        );
+        assert_eq!(UnsupportedCodexPolicy::Fallback.as_str(), "fallback");
+        assert_eq!(CodexTuiGlyphMode::Auto.to_string(), "auto");
+    }
+}
diff --git a/crates/core/src/schemas/token.rs b/crates/core/src/schemas/token.rs
new file mode 100644
index 000000000..64a2de726
--- /dev/null
+++ b/crates/core/src/schemas/token.rs
@@ -0,0 +1,399 @@
+//! Token / OAuth response schemas — port of the token half of
+//! `lib/schemas.ts` (spec 01 §3.3).
+//!
+//! - `TokenResult` is the discriminated union on the `type` tag
+//!   (`"success"` / `"failed"`); an unknown tag fails the parse.
+//! - `TokenSuccess.expires` and `OAuthTokenResponse.expires_in` are
+//!   `z.number().int().positive()` — zero, negative or fractional values
+//!   fail (I1: never mint an already-expired token).
+//! - `access`/`refresh`/`access_token` are `z.string().min(1)`.
+
+use serde::{Deserialize, Serialize};
+
+use super::parse::{de_int_positive_strict, de_opt_number_lenient, de_opt_strict, de_string_min1};
+
+/// Token failure reason codes.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum TokenFailureReason {
+    #[serde(rename = "http_error")]
+    HttpError,
+    #[serde(rename = "invalid_response")]
+    InvalidResponse,
+    #[serde(rename = "network_error")]
+    NetworkError,
+    #[serde(rename = "missing_refresh")]
+    MissingRefresh,
+    #[serde(rename = "timeout")]
+    Timeout,
+    #[serde(rename = "unknown")]
+    Unknown,
+}
+
+impl TokenFailureReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::HttpError => "http_error",
+            Self::InvalidResponse => "invalid_response",
+            Self::NetworkError => "network_error",
+            Self::MissingRefresh => "missing_refresh",
+            Self::Timeout => "timeout",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "http_error" => Some(Self::HttpError),
+            "invalid_response" => Some(Self::InvalidResponse),
+            "network_error" => Some(Self::NetworkError),
+            "missing_refresh" => Some(Self::MissingRefresh),
+            "timeout" => Some(Self::Timeout),
+            "unknown" => Some(Self::Unknown),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for TokenFailureReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Successful token exchange result (`type: "success"` — the tag is carried
+/// by [`TokenResult`]).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct TokenSuccess {
+    /// Required, non-empty.
+    #[serde(deserialize_with = "de_string_min1")]
+    pub access: String,
+    /// Required, non-empty.
+    #[serde(deserialize_with = "de_string_min1")]
+    pub refresh: String,
+    /// Required positive integer (epoch ms expiry).
+    #[serde(deserialize_with = "de_int_positive_strict")]
+    pub expires: i64,
+    #[serde(
+        rename = "idToken",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub id_token: Option<String>,
+    #[serde(
+        rename = "multiAccount",
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub multi_account: Option<bool>,
+}
+
+/// Failed token exchange result (`type: "failed"` — the tag is carried by
+/// [`TokenResult`]).
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct TokenFailure {
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub reason: Option<TokenFailureReason>,
+    #[serde(
+        rename = "statusCode",
+        default,
+        deserialize_with = "de_opt_number_lenient",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub status_code: Option<i64>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub message: Option<String>,
+}
+
+/// Token result — discriminated union of success/failure on the `type` tag.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum TokenResult {
+    #[serde(rename = "success")]
+    Success(TokenSuccess),
+    #[serde(rename = "failed")]
+    Failed(TokenFailure),
+}
+
+impl TokenResult {
+    /// The wire value of the `type` tag.
+    pub fn type_str(&self) -> &'static str {
+        match self {
+            Self::Success(_) => "success",
+            Self::Failed(_) => "failed",
+        }
+    }
+
+    pub fn is_success(&self) -> bool {
+        matches!(self, Self::Success(_))
+    }
+
+    pub fn as_success(&self) -> Option<&TokenSuccess> {
+        match self {
+            Self::Success(success) => Some(success),
+            Self::Failed(_) => None,
+        }
+    }
+
+    pub fn as_failure(&self) -> Option<&TokenFailure> {
+        match self {
+            Self::Success(_) => None,
+            Self::Failed(failure) => Some(failure),
+        }
+    }
+}
+
+impl From<TokenSuccess> for TokenResult {
+    fn from(value: TokenSuccess) -> Self {
+        Self::Success(value)
+    }
+}
+
+impl From<TokenFailure> for TokenResult {
+    fn from(value: TokenFailure) -> Self {
+        Self::Failed(value)
+    }
+}
+
+/// OAuth token response from OpenAI (token endpoint validation boundary).
+/// Field names are already snake_case on the wire — no renames.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct OAuthTokenResponse {
+    /// Required, non-empty.
+    #[serde(deserialize_with = "de_string_min1")]
+    pub access_token: String,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub refresh_token: Option<String>,
+    /// Required positive integer (seconds).
+    #[serde(deserialize_with = "de_int_positive_strict")]
+    pub expires_in: i64,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub id_token: Option<String>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub token_type: Option<String>,
+    #[serde(
+        default,
+        deserialize_with = "de_opt_strict",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub scope: Option<String>,
+}
+
+// ============================================================================
+// Tests (ported from test/schemas.test.ts token/OAuth suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn valid_success() -> serde_json::Value {
+        json!({
+            "type": "success",
+            "access": "access_token_123",
+            "refresh": "refresh_token_456",
+            "expires": 1700003600000i64,
+        })
+    }
+
+    #[test]
+    fn accepts_valid_success() {
+        let result: TokenResult = serde_json::from_value(valid_success()).expect("parses");
+        let success = result.as_success().expect("success variant");
+        assert_eq!(success.access, "access_token_123");
+        assert_eq!(success.expires, 1_700_003_600_000);
+    }
+
+    #[test]
+    fn accepts_success_with_optional_fields() {
+        let mut value = valid_success();
+        value["idToken"] = json!("id_token_789");
+        value["multiAccount"] = json!(true);
+        let result: TokenResult = serde_json::from_value(value).expect("parses");
+        let success = result.as_success().unwrap();
+        assert_eq!(success.id_token.as_deref(), Some("id_token_789"));
+        assert_eq!(success.multi_account, Some(true));
+    }
+
+    #[test]
+    fn rejects_empty_access_token() {
+        let mut value = valid_success();
+        value["access"] = json!("");
+        assert!(serde_json::from_value::<TokenResult>(value).is_err());
+    }
+
+    #[test]
+    fn rejects_empty_refresh_token() {
+        let mut value = valid_success();
+        value["refresh"] = json!("");
+        assert!(serde_json::from_value::<TokenResult>(value).is_err());
+    }
+
+    #[test]
+    fn accepts_minimal_failure() {
+        let result: TokenResult =
+            serde_json::from_value(json!({ "type": "failed" })).expect("parses");
+        assert!(!result.is_success());
+        assert_eq!(result.type_str(), "failed");
+    }
+
+    #[test]
+    fn accepts_failure_with_all_optional_fields() {
+        let result: TokenResult = serde_json::from_value(json!({
+            "type": "failed",
+            "reason": "http_error",
+            "statusCode": 401,
+            "message": "Unauthorized",
+        }))
+        .expect("parses");
+        let failure = result.as_failure().unwrap();
+        assert_eq!(failure.reason, Some(TokenFailureReason::HttpError));
+        assert_eq!(failure.status_code, Some(401));
+        assert_eq!(failure.message.as_deref(), Some("Unauthorized"));
+    }
+
+    #[test]
+    fn rejects_invalid_failure_reason() {
+        let result: Result<TokenResult, _> =
+            serde_json::from_value(json!({ "type": "failed", "reason": "invalid_reason" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn rejects_unknown_type_tag() {
+        let result: Result<TokenResult, _> = serde_json::from_value(json!({ "type": "pending" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn serializes_with_type_tag_first() {
+        let success = TokenResult::Success(TokenSuccess {
+            access: "a".into(),
+            refresh: "r".into(),
+            expires: 123,
+            id_token: None,
+            multi_account: None,
+        });
+        assert_eq!(
+            serde_json::to_string(&success).unwrap(),
+            r#"{"type":"success","access":"a","refresh":"r","expires":123}"#
+        );
+        let failure = TokenResult::Failed(TokenFailure::default());
+        assert_eq!(
+            serde_json::to_string(&failure).unwrap(),
+            r#"{"type":"failed"}"#
+        );
+    }
+
+    #[test]
+    fn oauth_accepts_valid_response() {
+        let response: OAuthTokenResponse =
+            serde_json::from_value(json!({ "access_token": "at_123", "expires_in": 3600 }))
+                .expect("parses");
+        assert_eq!(response.access_token, "at_123");
+        assert_eq!(response.expires_in, 3600);
+    }
+
+    #[test]
+    fn oauth_accepts_response_with_all_fields() {
+        let response: OAuthTokenResponse = serde_json::from_value(json!({
+            "access_token": "at_123",
+            "refresh_token": "rt_456",
+            "expires_in": 3600,
+            "id_token": "id_789",
+            "token_type": "Bearer",
+            "scope": "openid profile",
+        }))
+        .expect("parses");
+        assert_eq!(response.refresh_token.as_deref(), Some("rt_456"));
+        assert_eq!(response.token_type.as_deref(), Some("Bearer"));
+        assert_eq!(response.scope.as_deref(), Some("openid profile"));
+    }
+
+    #[test]
+    fn oauth_rejects_missing_access_token() {
+        let result: Result<OAuthTokenResponse, _> =
+            serde_json::from_value(json!({ "expires_in": 3600 }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn oauth_rejects_missing_expires_in() {
+        let result: Result<OAuthTokenResponse, _> =
+            serde_json::from_value(json!({ "access_token": "at" }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn oauth_i1_rejects_zero_or_negative_expires_in() {
+        for bad in [0, -1, -3600] {
+            let result: Result<OAuthTokenResponse, _> =
+                serde_json::from_value(json!({ "access_token": "at_123", "expires_in": bad }));
+            assert!(result.is_err(), "expires_in {bad} should be rejected");
+        }
+    }
+
+    #[test]
+    fn oauth_i1_rejects_non_integer_expires_in() {
+        let result: Result<OAuthTokenResponse, _> =
+            serde_json::from_value(json!({ "access_token": "at_123", "expires_in": 12.5 }));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn zod_optional_is_not_nullable_explicit_null_fails() {
+        // OAuth servers occasionally send explicit nulls; zod `.optional()`
+        // rejects them, routing the exchange to the failure path.
+        for key in ["refresh_token", "id_token", "token_type", "scope"] {
+            let result: Result<OAuthTokenResponse, _> = serde_json::from_value(json!({
+                "access_token": "at_123",
+                "expires_in": 3600,
+                key: null,
+            }));
+            assert!(result.is_err(), "{key}: null should fail the parse");
+        }
+        let mut success = valid_success();
+        success["idToken"] = json!(null);
+        assert!(serde_json::from_value::<TokenResult>(success).is_err());
+        let failure: Result<TokenResult, _> =
+            serde_json::from_value(json!({ "type": "failed", "reason": null }));
+        assert!(failure.is_err());
+        let status_null: Result<TokenResult, _> =
+            serde_json::from_value(json!({ "type": "failed", "statusCode": null }));
+        assert!(status_null.is_err());
+    }
+
+    #[test]
+    fn token_success_rejects_non_positive_or_fractional_expires() {
+        for bad in [json!(0), json!(-1), json!(12.5)] {
+            let mut value = valid_success();
+            value["expires"] = bad.clone();
+            assert!(
+                serde_json::from_value::<TokenResult>(value).is_err(),
+                "expires {bad} should be rejected"
+            );
+        }
+    }
+}
diff --git a/crates/core/src/shutdown.rs b/crates/core/src/shutdown.rs
new file mode 100644
index 000000000..df175b35d
--- /dev/null
+++ b/crates/core/src/shutdown.rs
@@ -0,0 +1,427 @@
+//! Port of `lib/shutdown.ts` — process cleanup registry hooked to shutdown
+//! signals.
+//!
+//! Behavior source: specs/01-foundation.md §2.15, §10.5.
+//!
+//! Contracts preserved from the TS source:
+//! - [`register_cleanup`] appends to the registry and lazily installs the
+//!   signal handlers ONCE (SIGINT/SIGTERM in TS → `tokio::signal::ctrl_c` on
+//!   every platform plus SIGTERM on unix here). A received signal runs the
+//!   cleanups and then exits with code 0.
+//! - [`unregister_cleanup`] removes a single registration (the TS removed by
+//!   function identity; Rust closures have no identity, so registration hands
+//!   back a [`CleanupHandle`] token instead — same observable behavior:
+//!   removing one specific entry, no-op when absent).
+//! - [`run_cleanup`] is idempotent while running (concurrent calls coalesce
+//!   onto the in-flight run), snapshots + clears the list up front, awaits
+//!   each cleanup **sequentially in registration order**, swallows individual
+//!   cleanup failures (panics here — the analogue of thrown/rejected cleanup
+//!   errors), and clears the in-flight marker afterwards so a later call
+//!   re-runs with any newly registered fns.
+//! - [`get_cleanup_count`] reports the number of currently registered fns.
+//!
+//! Rust-specific notes:
+//! - Node's `beforeExit` (run cleanups when the event loop drains, without
+//!   exiting) has no Rust analogue; binary mains call `run_cleanup().await`
+//!   before returning instead (ARCHITECTURE.md §5.4: CLI paths exit after
+//!   `run()` returns; long-running bins await ctrl-c which routes through the
+//!   installed handler).
+//! - `run_cleanup` starts eagerly like the TS promise executor when a tokio
+//!   runtime is available (the shared future is additionally spawned so it
+//!   makes progress even if the caller drops it). Outside a runtime the
+//!   caller must drive the returned future (e.g. `block_on`).
+//! - Signal handlers can only be installed from inside a tokio runtime; when
+//!   `register_cleanup` is called outside one, installation is retried on the
+//!   next registration that happens inside a runtime.
+
+use std::future::Future;
+use std::panic::AssertUnwindSafe;
+use std::sync::Mutex;
+
+use futures::FutureExt;
+use futures::future::{BoxFuture, Shared};
+
+/// Opaque token identifying one [`register_cleanup`] call, used to remove that
+/// registration again via [`unregister_cleanup`] (the Rust replacement for the
+/// TS remove-by-function-identity contract).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct CleanupHandle(u64);
+
+type CleanupFn = Box<dyn FnOnce() -> BoxFuture<'static, ()> + Send>;
+
+struct CleanupEntry {
+    id: u64,
+    f: CleanupFn,
+}
+
+type SharedCleanupFuture = Shared<BoxFuture<'static, ()>>;
+
+struct State {
+    entries: Vec<CleanupEntry>,
+    next_id: u64,
+    handlers_installed: bool,
+    in_flight: Option<SharedCleanupFuture>,
+}
+
+static STATE: Mutex<State> = Mutex::new(State {
+    entries: Vec::new(),
+    next_id: 1,
+    handlers_installed: false,
+    in_flight: None,
+});
+
+fn lock_state() -> std::sync::MutexGuard<'static, State> {
+    // Poison-tolerant: a cleanup panicking elsewhere must never brick the
+    // shutdown registry (errors are swallowed during shutdown by contract).
+    STATE.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+/// Register a cleanup to run at shutdown. Mirrors TS `registerCleanup`:
+/// appends to the registry (fns run in registration order) and lazily installs
+/// the process signal handlers once.
+///
+/// Returns a [`CleanupHandle`] for [`unregister_cleanup`].
+pub fn register_cleanup<F, Fut>(f: F) -> CleanupHandle
+where
+    F: FnOnce() -> Fut + Send + 'static,
+    Fut: Future<Output = ()> + Send + 'static,
+{
+    let boxed: CleanupFn = Box::new(move || f().boxed());
+    let id = {
+        let mut state = lock_state();
+        let id = state.next_id;
+        state.next_id += 1;
+        state.entries.push(CleanupEntry { id, f: boxed });
+        ensure_shutdown_handler(&mut state);
+        id
+    };
+    CleanupHandle(id)
+}
+
+/// Convenience for synchronous cleanups — the analogue of registering a plain
+/// `() => void` function in TS.
+pub fn register_cleanup_sync<F>(f: F) -> CleanupHandle
+where
+    F: FnOnce() + Send + 'static,
+{
+    register_cleanup(move || {
+        f();
+        std::future::ready(())
+    })
+}
+
+/// Remove one registration by its handle. No-op when the handle is not (or no
+/// longer) registered — matching the TS `unregisterCleanup` no-op for
+/// non-registered functions.
+pub fn unregister_cleanup(handle: CleanupHandle) {
+    let mut state = lock_state();
+    if let Some(index) = state.entries.iter().position(|e| e.id == handle.0) {
+        state.entries.remove(index);
+    }
+}
+
+/// Number of currently registered cleanup fns (drops to 0 once a run has
+/// snapshotted the list).
+pub fn get_cleanup_count() -> usize {
+    lock_state().entries.len()
+}
+
+/// Run all registered cleanups. Semantics ported verbatim from TS
+/// `runCleanup`:
+///
+/// - Concurrent calls while a run is in flight receive the SAME in-flight
+///   future (coalesced; the cleanups execute once).
+/// - The registry is snapshotted and cleared before execution, so cleanups
+///   registered DURING the run are kept for a later run.
+/// - Cleanups execute sequentially in registration order; individual failures
+///   (panics) are swallowed.
+/// - The in-flight marker is cleared when the run finishes, so a later call
+///   re-runs with newly registered fns.
+///
+/// The run starts eagerly when a tokio runtime is available; the returned
+/// future resolves when the run completes.
+pub fn run_cleanup() -> impl Future<Output = ()> + Send + 'static {
+    let shared = {
+        let mut state = lock_state();
+        if let Some(in_flight) = &state.in_flight {
+            return in_flight.clone();
+        }
+
+        let entries: Vec<CleanupEntry> = state.entries.drain(..).collect();
+        let shared: SharedCleanupFuture = async move {
+            for entry in entries {
+                // Swallow panics from both the synchronous closure body and
+                // the returned future — the analogue of the TS
+                // `try { await fn(); } catch { /* ignore */ }`.
+                let invoked = std::panic::catch_unwind(AssertUnwindSafe(|| (entry.f)()));
+                if let Ok(future) = invoked {
+                    let _ = AssertUnwindSafe(future).catch_unwind().await;
+                }
+            }
+            // Clear the in-flight marker so a later call re-runs with any
+            // newly registered fns (TS `.finally(() => cleanupPromise = null)`).
+            lock_state().in_flight = None;
+        }
+        .boxed()
+        .shared();
+        state.in_flight = Some(shared.clone());
+        shared
+    };
+
+    // Eager start (TS promise executors run immediately): drive the shared
+    // future from a spawned task when a runtime is available, so cleanup
+    // proceeds even if the caller drops the returned future.
+    if let Ok(handle) = tokio::runtime::Handle::try_current() {
+        handle.spawn(shared.clone());
+    }
+
+    shared
+}
+
+fn ensure_shutdown_handler(state: &mut State) {
+    if state.handlers_installed {
+        return;
+    }
+    // Signal listeners need a reactor; outside a runtime, leave the flag unset
+    // so a later in-runtime registration installs them.
+    let Ok(handle) = tokio::runtime::Handle::try_current() else {
+        return;
+    };
+    state.handlers_installed = true;
+    handle.spawn(signal_listener());
+}
+
+/// Await a shutdown signal, run the cleanups, then exit 0 — the TS
+/// `process.once("SIGINT"/"SIGTERM", ...)` handlers. `process.once` semantics
+/// (handler fires a single time) hold trivially because the process exits.
+async fn signal_listener() {
+    wait_for_shutdown_signal().await;
+    run_cleanup().await;
+    std::process::exit(0);
+}
+
+#[cfg(unix)]
+async fn wait_for_shutdown_signal() {
+    use tokio::signal::unix::{SignalKind, signal};
+    let mut sigterm = match signal(SignalKind::terminate()) {
+        Ok(stream) => stream,
+        Err(_) => {
+            // SIGTERM registration failed — still honor ctrl-c (SIGINT).
+            let _ = tokio::signal::ctrl_c().await;
+            return;
+        }
+    };
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {}
+        _ = sigterm.recv() => {}
+    }
+}
+
+#[cfg(not(unix))]
+async fn wait_for_shutdown_signal() {
+    // Windows: ctrl-c is the console close/interrupt analogue of SIGINT.
+    let _ = tokio::signal::ctrl_c().await;
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/shutdown.test.ts; the process-signal integration
+// tests are not portable — they mock `process.once`/`process.exit` — so the
+// registry/coalescing contracts carry the coverage)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicU32, Ordering};
+
+    /// beforeEach analogue: drain any leftovers from a previous test.
+    async fn drain() {
+        run_cleanup().await;
+        assert_eq!(get_cleanup_count(), 0);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn registers_and_runs_cleanup_functions() {
+        drain().await;
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_fn = Arc::clone(&calls);
+        register_cleanup_sync(move || {
+            calls_fn.fetch_add(1, Ordering::SeqCst);
+        });
+        assert_eq!(get_cleanup_count(), 1);
+        run_cleanup().await;
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+        assert_eq!(get_cleanup_count(), 0);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn unregisters_cleanup_functions() {
+        drain().await;
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_fn = Arc::clone(&calls);
+        let handle = register_cleanup_sync(move || {
+            calls_fn.fetch_add(1, Ordering::SeqCst);
+        });
+        unregister_cleanup(handle);
+        assert_eq!(get_cleanup_count(), 0);
+        run_cleanup().await;
+        assert_eq!(calls.load(Ordering::SeqCst), 0);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn runs_multiple_cleanup_functions_in_registration_order() {
+        drain().await;
+        let order: Arc<Mutex<Vec<u32>>> = Arc::new(Mutex::new(Vec::new()));
+        for n in 1..=3u32 {
+            let order_fn = Arc::clone(&order);
+            register_cleanup_sync(move || {
+                order_fn.lock().unwrap().push(n);
+            });
+        }
+        run_cleanup().await;
+        assert_eq!(*order.lock().unwrap(), vec![1, 2, 3]);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn handles_async_cleanup_functions() {
+        drain().await;
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_fn = Arc::clone(&calls);
+        register_cleanup(move || async move {
+            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+            calls_fn.fetch_add(1, Ordering::SeqCst);
+        });
+        run_cleanup().await;
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn continues_cleanup_even_if_one_function_panics() {
+        drain().await;
+        let first_ran = Arc::new(AtomicU32::new(0));
+        let second_ran = Arc::new(AtomicU32::new(0));
+        let first_fn = Arc::clone(&first_ran);
+        let second_fn = Arc::clone(&second_ran);
+        // Silence the default panic backtrace noise for the expected panic.
+        let previous_hook = std::panic::take_hook();
+        std::panic::set_hook(Box::new(|_| {}));
+        register_cleanup_sync(move || {
+            first_fn.fetch_add(1, Ordering::SeqCst);
+            panic!("fail");
+        });
+        register_cleanup_sync(move || {
+            second_fn.fetch_add(1, Ordering::SeqCst);
+        });
+        run_cleanup().await;
+        std::panic::set_hook(previous_hook);
+        assert_eq!(first_ran.load(Ordering::SeqCst), 1);
+        assert_eq!(second_ran.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn clears_cleanup_list_after_running() {
+        drain().await;
+        register_cleanup_sync(|| {});
+        register_cleanup_sync(|| {});
+        assert_eq!(get_cleanup_count(), 2);
+        run_cleanup().await;
+        assert_eq!(get_cleanup_count(), 0);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn coalesces_concurrent_run_cleanup_calls_onto_one_run() {
+        drain().await;
+        let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_fn = Arc::clone(&calls);
+        register_cleanup(move || async move {
+            let _ = release_rx.await;
+            calls_fn.fetch_add(1, Ordering::SeqCst);
+        });
+
+        let first = run_cleanup();
+        let second = run_cleanup();
+
+        release_tx.send(()).unwrap();
+        // Both futures resolve, but the cleanup body ran exactly once — the
+        // TS assertion `first === second` maps to single execution here.
+        first.await;
+        second.await;
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn later_run_reexecutes_with_newly_registered_functions() {
+        drain().await;
+        let calls = Arc::new(AtomicU32::new(0));
+        let calls_a = Arc::clone(&calls);
+        register_cleanup_sync(move || {
+            calls_a.fetch_add(1, Ordering::SeqCst);
+        });
+        run_cleanup().await;
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+
+        // The in-flight marker cleared, so a fresh registration runs again.
+        let calls_b = Arc::clone(&calls);
+        register_cleanup_sync(move || {
+            calls_b.fetch_add(1, Ordering::SeqCst);
+        });
+        run_cleanup().await;
+        assert_eq!(calls.load(Ordering::SeqCst), 2);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn unregister_is_noop_for_non_registered_handle() {
+        drain().await;
+        let handle = register_cleanup_sync(|| {});
+        run_cleanup().await; // consumes the entry; handle now dangles
+        unregister_cleanup(handle); // must not panic or affect anything
+        assert_eq!(get_cleanup_count(), 0);
+        // A handle that never existed is equally a no-op.
+        unregister_cleanup(CleanupHandle(u64::MAX));
+        assert_eq!(get_cleanup_count(), 0);
+    }
+
+    #[tokio::test]
+    #[serial(shutdown)]
+    async fn functions_registered_during_a_run_are_kept_for_the_next_run() {
+        drain().await;
+        let late_ran = Arc::new(AtomicU32::new(0));
+        let late_fn = Arc::clone(&late_ran);
+        register_cleanup(move || async move {
+            // Register a new cleanup while the run is in flight; the list was
+            // snapshotted+cleared, so this stays queued for the NEXT run.
+            let late_inner = Arc::clone(&late_fn);
+            register_cleanup_sync(move || {
+                late_inner.fetch_add(1, Ordering::SeqCst);
+            });
+        });
+        run_cleanup().await;
+        assert_eq!(late_ran.load(Ordering::SeqCst), 0);
+        assert_eq!(get_cleanup_count(), 1);
+        run_cleanup().await;
+        assert_eq!(late_ran.load(Ordering::SeqCst), 1);
+        assert_eq!(get_cleanup_count(), 0);
+    }
+
+    #[test]
+    #[serial(shutdown)]
+    fn register_outside_a_runtime_does_not_panic_and_defers_handler_install() {
+        // No tokio runtime here: registration must still work; the signal
+        // handler install is deferred until an in-runtime registration.
+        let handle = register_cleanup_sync(|| {});
+        assert!(get_cleanup_count() >= 1);
+        unregister_cleanup(handle);
+    }
+}
diff --git a/crates/core/src/table_formatter.rs b/crates/core/src/table_formatter.rs
new file mode 100644
index 000000000..d336b0311
--- /dev/null
+++ b/crates/core/src/table_formatter.rs
@@ -0,0 +1,258 @@
+//! Port of `lib/table-formatter.ts`: simple ASCII table formatter for CLI tools.
+//!
+//! Generates consistent, aligned table output. Cells are measured and padded in
+//! *display columns* (via [`crate::display_width`] — CJK/emoji-aware), not code
+//! units, so wide-glyph content stays aligned (ui-02).
+//!
+//! Contract highlights (spec 01 §2.16):
+//! - cells joined with a single space;
+//! - a column of width `<= 0` renders as the empty string (never an
+//!   overflowing ellipsis);
+//! - over-wide values truncate to `width - 1` columns plus `…` (U+2026);
+//! - right alignment puts the padding before the cell.
+
+use crate::display_width::{display_width, truncate_to_width};
+
+/// Cell alignment. TS `align?: "left" | "right"` with left as the default.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TableAlign {
+    #[default]
+    Left,
+    Right,
+}
+
+/// Column definition.
+#[derive(Debug, Clone)]
+pub struct TableColumn {
+    /// Column header text.
+    pub header: String,
+    /// Column width (content will be padded/truncated to fit).
+    pub width: i32,
+    /// Alignment: left (default) or right.
+    pub align: TableAlign,
+}
+
+impl TableColumn {
+    /// Convenience constructor for a left-aligned column.
+    pub fn new(header: impl Into<String>, width: i32) -> Self {
+        Self {
+            header: header.into(),
+            width,
+            align: TableAlign::Left,
+        }
+    }
+}
+
+/// Table options.
+#[derive(Debug, Clone)]
+pub struct TableOptions {
+    /// Column definitions.
+    pub columns: Vec<TableColumn>,
+    /// Character used for the header separator line (default: `-`).
+    pub separator_char: Option<String>,
+}
+
+/// Format a value to fit within a column width.
+///
+/// ui-02: measure and pad by display columns, not code units, so CJK/emoji
+/// content stays aligned. When truncating, reserve one column for the ellipsis
+/// and never split a wide glyph across the boundary. A zero-or-negative width
+/// column has no room for content OR an ellipsis; returning `…` there would
+/// overflow the declared width by one and desync the row from the
+/// header/separator layout, so short-circuit to empty.
+fn format_cell(value: &str, width: i32, align: TableAlign) -> String {
+    if width <= 0 {
+        return String::new();
+    }
+    let width = width as usize;
+    let value_width = display_width(value);
+    let cell = if value_width > width {
+        let truncated = truncate_to_width(value, width.saturating_sub(1));
+        format!("{}\u{2026}", truncated.text)
+    } else {
+        value.to_string()
+    };
+    let pad = width.saturating_sub(display_width(&cell));
+    match align {
+        TableAlign::Right => format!("{}{}", " ".repeat(pad), cell),
+        TableAlign::Left => format!("{}{}", cell, " ".repeat(pad)),
+    }
+}
+
+/// Build a table header row and separator line: `[header_row, separator_row]`.
+pub fn build_table_header(options: &TableOptions) -> Vec<String> {
+    let separator_char = options.separator_char.as_deref().unwrap_or("-");
+
+    let header_row = options
+        .columns
+        .iter()
+        .map(|col| format_cell(&col.header, col.width, col.align))
+        .collect::<Vec<_>>()
+        .join(" ");
+
+    // NOTE: JS `String.prototype.repeat` throws a RangeError for a negative
+    // count; negative widths are therefore de facto unsupported in the TS
+    // implementation. Rust clamps to 0 instead of panicking.
+    let separator_row = options
+        .columns
+        .iter()
+        .map(|col| separator_char.repeat(col.width.max(0) as usize))
+        .collect::<Vec<_>>()
+        .join(" ");
+
+    vec![header_row, separator_row]
+}
+
+/// Build a single table row from values. Values are matched to columns by
+/// index; missing values render as empty cells.
+pub fn build_table_row<S: AsRef<str>>(values: &[S], options: &TableOptions) -> String {
+    options
+        .columns
+        .iter()
+        .enumerate()
+        .map(|(i, col)| {
+            let value = values.get(i).map(|v| v.as_ref()).unwrap_or("");
+            format_cell(value, col.width, col.align)
+        })
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Build a complete table with header, separator, and rows.
+pub fn build_table<S: AsRef<str>>(rows: &[Vec<S>], options: &TableOptions) -> Vec<String> {
+    let mut lines = build_table_header(options);
+    for row in rows {
+        lines.push(build_table_row(row, options));
+    }
+    lines
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn simple_options() -> TableOptions {
+        TableOptions {
+            columns: vec![
+                TableColumn::new("ID", 4),
+                TableColumn::new("Name", 10),
+                TableColumn::new("Status", 8),
+            ],
+            separator_char: None,
+        }
+    }
+
+    // === buildTableHeader (ported from test/table-formatter.test.ts) ===
+
+    #[test]
+    fn builds_header_row_with_proper_padding() {
+        let lines = build_table_header(&simple_options());
+        assert_eq!(lines[0], "ID   Name       Status  ");
+        assert_eq!(lines[1], "---- ---------- --------");
+    }
+
+    #[test]
+    fn uses_custom_separator_character() {
+        let options = TableOptions {
+            columns: vec![TableColumn::new("Col", 5)],
+            separator_char: Some("=".to_string()),
+        };
+        let lines = build_table_header(&options);
+        assert_eq!(lines[1], "=====");
+    }
+
+    // === buildTableRow ===
+
+    #[test]
+    fn formats_values_with_proper_padding() {
+        let row = build_table_row(&["1", "Alice", "active"], &simple_options());
+        assert_eq!(row, "1    Alice      active  ");
+    }
+
+    #[test]
+    fn truncates_long_values_with_ellipsis() {
+        let row = build_table_row(&["1", "VeryLongNameHere", "ok"], &simple_options());
+        assert_eq!(row, "1    VeryLongN\u{2026} ok      ");
+    }
+
+    #[test]
+    fn handles_missing_values_gracefully() {
+        let row = build_table_row(&["1"], &simple_options());
+        assert_eq!(row, "1                       ");
+    }
+
+    #[test]
+    fn supports_right_alignment() {
+        let options = TableOptions {
+            columns: vec![
+                TableColumn {
+                    header: "Num".to_string(),
+                    width: 5,
+                    align: TableAlign::Right,
+                },
+                TableColumn::new("Text", 5),
+            ],
+            separator_char: None,
+        };
+        let row = build_table_row(&["42", "abc"], &options);
+        assert_eq!(row, "   42 abc  ");
+    }
+
+    // ui-02: CJK content must be padded by display columns, not code units.
+    #[test]
+    fn pads_cjk_values_by_display_width_so_columns_stay_aligned() {
+        // Name col width 10; "漢字漢字" = 4 glyphs * 2 cols = 8 cols -> 2 pad spaces.
+        let row = build_table_row(&["1", "漢字漢字", "ok"], &simple_options());
+        assert_eq!(row, "1    漢字漢字   ok      ");
+    }
+
+    #[test]
+    fn truncates_wide_glyph_values_without_splitting_a_glyph() {
+        // Name width 10: a 6-glyph value = 12 cols overflows. Reserve 1 col for
+        // the ellipsis -> keep up to 9 cols of content, but a 5th wide glyph
+        // (10 cols) won't fit in 9, so only 4 glyphs (8 cols) are kept, then
+        // "…", then pad.
+        let row = build_table_row(&["1", "漢字漢字漢字", "ok"], &simple_options());
+        assert_eq!(row, "1    漢字漢字\u{2026}  ok      ");
+    }
+
+    #[test]
+    fn emits_empty_not_an_overflowing_ellipsis_for_a_zero_width_column() {
+        // A width-0 column has no room for content OR the "…" — returning "…"
+        // would overflow the declared width by one and desync the row from the
+        // header/separator layout. The cell must be empty.
+        let options = TableOptions {
+            columns: vec![TableColumn::new("A", 0), TableColumn::new("B", 3)],
+            separator_char: None,
+        };
+        let row = build_table_row(&["dropped", "ok"], &options);
+        // First cell contributes 0 columns; the join space + 3-col "ok " follow.
+        assert_eq!(row, " ok ");
+        assert!(!row.contains('\u{2026}'));
+    }
+
+    // === buildTable ===
+
+    #[test]
+    fn builds_complete_table_with_header_and_rows() {
+        let rows = vec![
+            vec!["1", "Alice", "active"],
+            vec!["2", "Bob", "idle"],
+        ];
+        let lines = build_table(&rows, &simple_options());
+        assert_eq!(lines.len(), 4);
+        assert_eq!(lines[0], "ID   Name       Status  ");
+        assert_eq!(lines[1], "---- ---------- --------");
+        assert_eq!(lines[2], "1    Alice      active  ");
+        assert_eq!(lines[3], "2    Bob        idle    ");
+    }
+
+    #[test]
+    fn handles_empty_rows_array() {
+        let rows: Vec<Vec<&str>> = Vec::new();
+        let lines = build_table(&rows, &simple_options());
+        assert_eq!(lines.len(), 2);
+        assert!(lines[0].contains("ID"));
+        assert!(lines[1].contains("----"));
+    }
+}
diff --git a/crates/core/src/temp_path.rs b/crates/core/src/temp_path.rs
new file mode 100644
index 000000000..b02c8edfe
--- /dev/null
+++ b/crates/core/src/temp_path.rs
@@ -0,0 +1,147 @@
+//! Port of `lib/temp-path.ts` — CSPRNG-suffixed temp filename generation for
+//! atomic write-then-rename staging.
+//!
+//! Behavior source: specs/01-foundation.md §2.6, gotcha 18.
+//!
+//! Contracts:
+//! - Nonce shape is `<pid>.<epochMs>.<hex8>`.
+//! - The random component MUST come from the OS CSPRNG (`rand::rngs::OsRng`
+//!   explicitly, per ARCHITECTURE.md §5.5) — a predictable PRNG would let a
+//!   local attacker pre-create (or symlink) the staged path before the atomic
+//!   write-then-rename lands. Entropy failure is a loud panic, mirroring
+//!   Node's throwing `crypto.randomBytes`: staging a token file with weaker
+//!   randomness instead would be strictly worse.
+//! - Staged names MUST keep the trailing `.tmp` extension: stale-artifact
+//!   sweepers (storage, runtime-paths, oc-chatgpt-target-detection) filter on
+//!   `ends_with(".tmp")`.
+
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use rand::TryRngCore;
+use rand::rngs::OsRng;
+
+fn epoch_ms_now() -> u128 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis()
+}
+
+/// Unpredictable nonce for temp/staging file names: `<pid>.<epochMs>.<hex8>`.
+///
+/// # Panics
+///
+/// Panics when the process CSPRNG is unavailable (e.g. misconfigured FIPS
+/// builds) — the intended failure mode is a loud error, never a weak-random
+/// fallback.
+pub fn temp_file_nonce() -> String {
+    let mut bytes = [0u8; 4];
+    OsRng
+        .try_fill_bytes(&mut bytes)
+        .expect("CSPRNG unavailable: cannot generate temp-file nonce");
+    format!(
+        "{}.{}.{:02x}{:02x}{:02x}{:02x}",
+        std::process::id(),
+        epoch_ms_now(),
+        bytes[0],
+        bytes[1],
+        bytes[2],
+        bytes[3],
+    )
+}
+
+/// Staging path for an atomic write-then-rename of `target_path`:
+/// `<targetPath>.<pid>.<epochMs>.<hex8>.tmp`.
+///
+/// Keeps the trailing `.tmp` extension so existing stale-artifact sweepers
+/// (`name.ends_with(".tmp")`) continue to skip/collect staged files.
+pub fn temp_path_for(target_path: &Path) -> PathBuf {
+    let mut os = target_path.as_os_str().to_os_string();
+    os.push(format!(".{}.tmp", temp_file_nonce()));
+    PathBuf::from(os)
+}
+
+/// String-input convenience mirroring the TS signature exactly (the TS
+/// function concatenated onto the raw string, so separators are preserved
+/// verbatim for both POSIX and Windows style targets).
+pub fn temp_path_for_str(target_path: &str) -> String {
+    format!("{}.{}.tmp", target_path, temp_file_nonce())
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/temp-path.test.ts)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashSet;
+
+    fn is_hex8(s: &str) -> bool {
+        s.len() == 8 && s.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
+    }
+
+    #[test]
+    fn produces_pid_epoch_hex8_shaped_nonces() {
+        let nonce = temp_file_nonce();
+        let parts: Vec<&str> = nonce.split('.').collect();
+        assert_eq!(parts.len(), 3, "nonce {nonce} must be <pid>.<epochMs>.<hex8>");
+        assert_eq!(parts[0], std::process::id().to_string());
+        assert!(
+            !parts[1].is_empty() && parts[1].chars().all(|c| c.is_ascii_digit()),
+            "epoch segment {} must be all digits",
+            parts[1]
+        );
+        assert!(is_hex8(parts[2]), "random segment {} must be 8 lowercase hex", parts[2]);
+    }
+
+    #[test]
+    fn does_not_repeat_across_rapid_successive_calls() {
+        // pid + timestamp collide within the same millisecond, so uniqueness
+        // rests on the crypto suffix; 200 draws must never collide.
+        let mut seen = HashSet::new();
+        for _ in 0..200 {
+            seen.insert(temp_file_nonce());
+        }
+        assert_eq!(seen.len(), 200);
+    }
+
+    #[test]
+    fn stages_next_to_the_target_and_keeps_tmp_extension_for_sweepers() {
+        let temp = temp_path_for_str("/data/accounts.json");
+        assert!(temp.starts_with("/data/accounts.json."));
+        assert!(temp.ends_with(".tmp"));
+        let middle = &temp["/data/accounts.json.".len()..temp.len() - ".tmp".len()];
+        let parts: Vec<&str> = middle.split('.').collect();
+        assert_eq!(parts.len(), 3);
+        assert!(parts[0].chars().all(|c| c.is_ascii_digit()));
+        assert!(parts[1].chars().all(|c| c.is_ascii_digit()));
+        assert!(is_hex8(parts[2]));
+    }
+
+    #[test]
+    fn handles_windows_style_targets_with_drive_letter_and_backslashes() {
+        let temp = temp_path_for_str("C:\\Users\\dev\\.codex\\accounts.json");
+        assert!(temp.starts_with("C:\\Users\\dev\\.codex\\accounts.json."));
+        assert!(temp.ends_with(".tmp"));
+    }
+
+    #[test]
+    fn path_variant_appends_to_the_full_target_path() {
+        let target = Path::new("/data/accounts.json");
+        let temp = temp_path_for(target);
+        let rendered = temp.to_string_lossy();
+        assert!(rendered.starts_with("/data/accounts.json."));
+        assert!(rendered.ends_with(".tmp"));
+    }
+
+    #[test]
+    fn never_collides_for_the_same_target_across_rapid_calls() {
+        let mut seen = HashSet::new();
+        for _ in 0..200 {
+            seen.insert(temp_path_for_str("/data/accounts.json"));
+        }
+        assert_eq!(seen.len(), 200);
+    }
+}
diff --git a/crates/core/src/token_utils.rs b/crates/core/src/token_utils.rs
new file mode 100644
index 000000000..081e13e9a
--- /dev/null
+++ b/crates/core/src/token_utils.rs
@@ -0,0 +1,1020 @@
+//! Port of `lib/auth/token-utils.ts`: JWT payload mining — account-id/email
+//! extraction, workspace candidate collection & selection.
+//!
+//! Behavior contracts (spec 07 §5, gotchas 17/18):
+//! - candidate ordering (token -> access-orgs -> id_token -> id-orgs) and the
+//!   first-wins dedupe by accountId are behavior, not style;
+//! - `select_best_account_candidate`'s 6-step preference order is exact;
+//! - only `token`/`id_token` sources auto-follow token changes; `org`/`manual`
+//!   selections are sticky across refreshes;
+//! - `extract_account_id` returns the RAW (untrimmed) claim value, while the
+//!   id-token payload miner (`extract_account_id_from_payload`) trims — this
+//!   asymmetry is deliberate and test-pinned.
+
+use serde_json::Value;
+
+use crate::constants::JWT_CLAIM_PATH;
+use crate::jwt::decode_jwt_value;
+use crate::schemas::account_storage::AccountIdSource;
+
+/// Account ID candidate from token or organization data.
+#[derive(Debug, Clone)]
+pub struct AccountIdCandidate {
+    pub account_id: String,
+    pub label: String,
+    pub source: AccountIdSource,
+    pub is_default: Option<bool>,
+    pub is_personal: Option<bool>,
+}
+
+/// Converts a value to a trimmed string if it's a non-empty string.
+/// Local helper — returns `None` for non-strings (different from
+/// `lib/utils.toStringValue`, which stringifies everything).
+fn to_string_value(value: &Value) -> Option<String> {
+    let s = value.as_str()?;
+    let trimmed = s.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// Converts a value to boolean if possible (`true`/`false` literals, or the
+/// case-insensitive trimmed strings "true"/"false").
+fn to_boolean(value: &Value) -> Option<bool> {
+    match value {
+        Value::Null => None,
+        Value::Bool(b) => Some(*b),
+        Value::String(s) => match s.trim().to_lowercase().as_str() {
+            "true" => Some(true),
+            "false" => Some(false),
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
+/// First value among `keys` that is present AND not JSON null — the Rust
+/// equivalent of a TS `record.a ?? record.b ?? …` nullish chain over raw
+/// values (a present `false`/`0`/`""` STOPS the chain).
+fn first_non_nullish<'a>(record: &'a serde_json::Map<String, Value>, keys: &[&str]) -> Option<&'a Value> {
+    keys.iter()
+        .filter_map(|key| record.get(*key))
+        .find(|value| !value.is_null())
+}
+
+/// Chain of [`to_string_value`] lookups: unlike [`first_non_nullish`], a
+/// non-string or blank value lets the chain continue to the next key.
+fn string_chain(record: &serde_json::Map<String, Value>, keys: &[&str]) -> Option<String> {
+    keys.iter()
+        .filter_map(|key| record.get(*key))
+        .find_map(to_string_value)
+}
+
+/// Formats account ID to its last 6 characters for display.
+fn format_account_id_suffix(account_id: &str) -> String {
+    let count = account_id.chars().count();
+    if count > 6 {
+        account_id.chars().skip(count - 6).collect()
+    } else {
+        account_id.to_string()
+    }
+}
+
+/// Formats a label for token-derived account candidates.
+fn format_token_candidate_label(prefix: &str, account_id: &str) -> String {
+    format!("{prefix} [id:{}]", format_account_id_suffix(account_id))
+}
+
+/// Extracts an account ID from a JWT payload: nested claim first, then the
+/// direct `chatgpt_account_id` / `account_id` / `accountId` keys (trimmed).
+fn extract_account_id_from_payload(payload: Option<&Value>) -> Option<String> {
+    let payload = payload?;
+    if let Some(auth) = payload.get(JWT_CLAIM_PATH).and_then(|v| v.as_object())
+        && let Some(id) = auth.get("chatgpt_account_id").and_then(to_string_value)
+    {
+        return Some(id);
+    }
+
+    let record = payload.as_object()?;
+    string_chain(record, &["chatgpt_account_id", "account_id", "accountId"])
+}
+
+/// Normalizes candidate arrays from various response formats: a direct array,
+/// or a record wrapping one under `data`/`items`/`accounts`/`organizations`/
+/// `workspaces`/`teams`.
+fn normalize_candidate_array(value: &Value) -> Option<&Vec<Value>> {
+    if let Value::Array(items) = value {
+        return Some(items);
+    }
+    let record = value.as_object()?;
+    let nested = first_non_nullish(
+        record,
+        &["data", "items", "accounts", "organizations", "workspaces", "teams"],
+    )?;
+    match nested {
+        Value::Array(items) => Some(items),
+        _ => None,
+    }
+}
+
+/// Extracts a single account candidate from a record.
+fn extract_candidate_from_record(
+    record: &serde_json::Map<String, Value>,
+    source: AccountIdSource,
+) -> Option<AccountIdCandidate> {
+    let account_id = string_chain(
+        record,
+        &[
+            "account_id",
+            "accountId",
+            "chatgpt_account_id",
+            "organization_id",
+            "org_id",
+            "workspace_id",
+            "team_id",
+            "id",
+        ],
+    )?;
+
+    let name = string_chain(
+        record,
+        &[
+            "name",
+            "display_name",
+            "title",
+            "organization_name",
+            "workspace_name",
+            "team_name",
+            "slug",
+        ],
+    );
+    let candidate_type = string_chain(record, &["type", "plan_type", "kind", "account_type"]);
+    let role = string_chain(record, &["role", "membership_role", "user_role"]);
+    let is_default = first_non_nullish(
+        record,
+        &[
+            "is_default",
+            "isDefault",
+            "default",
+            "primary",
+            "is_active",
+            "isActive",
+            "current",
+        ],
+    )
+    .and_then(to_boolean);
+    let is_personal = first_non_nullish(record, &["is_personal", "isPersonal", "personal"])
+        .and_then(to_boolean);
+
+    let suffix = format_account_id_suffix(&account_id);
+    let mut label_parts: Vec<String> = Vec::new();
+    let mut label_base = name.clone().unwrap_or_else(|| "Workspace".to_string());
+
+    if name.is_none()
+        && let Some(t) = &candidate_type
+    {
+        label_base = t.clone();
+    }
+
+    if let Some(t) = &candidate_type {
+        let differs_from_name = match &name {
+            None => true,
+            Some(n) => n.to_lowercase() != t.to_lowercase(),
+        };
+        if differs_from_name {
+            label_parts.push(t.clone());
+        }
+    }
+    if let Some(r) = &role {
+        label_parts.push(format!("role:{r}"));
+    }
+    if is_personal == Some(true) {
+        label_parts.push("personal".to_string());
+    }
+
+    let meta = if label_parts.is_empty() {
+        String::new()
+    } else {
+        format!(" ({})", label_parts.join(", "))
+    };
+    let label = format!("{label_base}{meta} [id:{suffix}]");
+
+    Some(AccountIdCandidate {
+        account_id,
+        label,
+        source,
+        is_default,
+        is_personal,
+    })
+}
+
+/// Collects candidates from a list-shaped value.
+fn collect_candidates_from_list(value: &Value, source: AccountIdSource) -> Vec<AccountIdCandidate> {
+    let mut result = Vec::new();
+    let Some(list) = normalize_candidate_array(value) else {
+        return result;
+    };
+    for item in list {
+        let Some(record) = item.as_object() else {
+            continue;
+        };
+        if let Some(candidate) = extract_candidate_from_record(record, source) {
+            result.push(candidate);
+        }
+    }
+    result
+}
+
+/// Collects candidates from a JWT payload: the well-known org keys at the top
+/// level first, then the same keys inside the nested auth claim.
+fn collect_candidates_from_payload(
+    payload: Option<&Value>,
+    source: AccountIdSource,
+) -> Vec<AccountIdCandidate> {
+    let Some(record) = payload.and_then(|p| p.as_object()) else {
+        return Vec::new();
+    };
+
+    let mut candidates = Vec::new();
+    let keys = ["organizations", "orgs", "accounts", "workspaces", "teams"];
+    for key in keys {
+        if let Some(value) = record.get(key) {
+            candidates.extend(collect_candidates_from_list(value, source));
+        }
+    }
+
+    if let Some(auth) = record.get(JWT_CLAIM_PATH).and_then(|v| v.as_object()) {
+        for key in keys {
+            if let Some(value) = auth.get(key) {
+                candidates.extend(collect_candidates_from_list(value, source));
+            }
+        }
+    }
+
+    candidates
+}
+
+/// Removes duplicate candidates by accountId, keeping the first occurrence.
+fn unique_candidates(candidates: Vec<AccountIdCandidate>) -> Vec<AccountIdCandidate> {
+    let mut seen = std::collections::HashSet::new();
+    let mut result = Vec::new();
+    for candidate in candidates {
+        if seen.contains(&candidate.account_id) {
+            continue;
+        }
+        seen.insert(candidate.account_id.clone());
+        result.push(candidate);
+    }
+    result
+}
+
+/// Select the best workspace candidate for OAuth account binding.
+/// Preference order:
+/// 1) org default that is not personal
+/// 2) org default (any)
+/// 3) id_token candidate
+/// 4) non-personal org candidate
+/// 5) token candidate
+/// 6) first candidate
+pub fn select_best_account_candidate(
+    candidates: &[AccountIdCandidate],
+) -> Option<&AccountIdCandidate> {
+    if candidates.is_empty() {
+        return None;
+    }
+
+    if let Some(candidate) = candidates.iter().find(|c| {
+        matches!(c.source, AccountIdSource::Org)
+            && c.is_default == Some(true)
+            && c.is_personal != Some(true)
+    }) {
+        return Some(candidate);
+    }
+
+    if let Some(candidate) = candidates
+        .iter()
+        .find(|c| matches!(c.source, AccountIdSource::Org) && c.is_default == Some(true))
+    {
+        return Some(candidate);
+    }
+
+    if let Some(candidate) = candidates
+        .iter()
+        .find(|c| matches!(c.source, AccountIdSource::IdToken))
+    {
+        return Some(candidate);
+    }
+
+    if let Some(candidate) = candidates
+        .iter()
+        .find(|c| matches!(c.source, AccountIdSource::Org) && c.is_personal != Some(true))
+    {
+        return Some(candidate);
+    }
+
+    if let Some(candidate) = candidates
+        .iter()
+        .find(|c| matches!(c.source, AccountIdSource::Token))
+    {
+        return Some(candidate);
+    }
+
+    candidates.first()
+}
+
+/// Extracts the ChatGPT account ID from a JWT access token.
+///
+/// Returns the RAW (untrimmed) claim value when it is a string with a
+/// non-blank trim; `None` otherwise. Empty/absent tokens yield `None`.
+pub fn extract_account_id(access_token: Option<&str>) -> Option<String> {
+    let token = access_token.filter(|t| !t.is_empty())?;
+    let decoded = decode_jwt_value(token)?;
+    let account_id = decoded.get(JWT_CLAIM_PATH)?.get("chatgpt_account_id")?;
+    match account_id.as_str() {
+        Some(s) if !s.trim().is_empty() => Some(s.to_string()),
+        _ => None,
+    }
+}
+
+/// Extracts the email address from OAuth tokens.
+/// Checks id_token first (where OpenAI puts email), then falls back to the
+/// access token's nested claim `email` / `chatgpt_user_email`, then the
+/// top-level `email` / `preferred_username`. Returns the raw (untrimmed,
+/// unlowercased) value; it must be a string containing `@` with a non-blank
+/// trim.
+pub fn extract_account_email(access_token: Option<&str>, id_token: Option<&str>) -> Option<String> {
+    // Try id_token first — OpenAI puts email here.
+    if let Some(idt) = id_token.filter(|t| !t.is_empty())
+        && let Some(id_decoded) = decode_jwt_value(idt)
+        && let Some(id_email) = id_decoded.get("email").and_then(|v| v.as_str())
+        && id_email.contains('@')
+        && !id_email.trim().is_empty()
+    {
+        return Some(id_email.to_string());
+    }
+
+    // Fall back to access_token.
+    let token = access_token.filter(|t| !t.is_empty())?;
+    let decoded = decode_jwt_value(token)?;
+    let nested = decoded.get(JWT_CLAIM_PATH).and_then(|v| v.as_object());
+    // TS `a ?? b ?? c ?? d` over raw values: a present non-null non-string
+    // value stops the chain and then fails the string check.
+    let candidate = [
+        nested.and_then(|n| n.get("email")),
+        nested.and_then(|n| n.get("chatgpt_user_email")),
+        decoded.get("email"),
+        decoded.get("preferred_username"),
+    ]
+    .into_iter()
+    .flatten()
+    .find(|value| !value.is_null())?;
+
+    let email = candidate.as_str()?;
+    if email.contains('@') && !email.trim().is_empty() {
+        Some(email.to_string())
+    } else {
+        None
+    }
+}
+
+/// Extracts all accountId candidates from access/id tokens.
+/// Used to support business workspaces/organizations that are not the token
+/// default. Order: token -> access-token orgs -> id_token -> id-token orgs,
+/// deduplicated by accountId (first occurrence wins).
+pub fn get_account_id_candidates(
+    access_token: Option<&str>,
+    id_token: Option<&str>,
+) -> Vec<AccountIdCandidate> {
+    let mut candidates = Vec::new();
+    let access_id = extract_account_id(access_token);
+    if let Some(id) = &access_id {
+        candidates.push(AccountIdCandidate {
+            account_id: id.clone(),
+            label: format_token_candidate_label("Token account", id),
+            source: AccountIdSource::Token,
+            is_default: Some(true),
+            is_personal: None,
+        });
+    }
+
+    if let Some(token) = access_token.filter(|t| !t.is_empty()) {
+        let access_decoded = decode_jwt_value(token);
+        candidates.extend(collect_candidates_from_payload(
+            access_decoded.as_ref(),
+            AccountIdSource::Org,
+        ));
+    }
+
+    if let Some(idt) = id_token.filter(|t| !t.is_empty()) {
+        let decoded = decode_jwt_value(idt);
+        let id_account_id = extract_account_id_from_payload(decoded.as_ref());
+        if let Some(id) = id_account_id
+            && Some(&id) != access_id.as_ref()
+        {
+            candidates.push(AccountIdCandidate {
+                account_id: id.clone(),
+                label: format_token_candidate_label("ID token account", &id),
+                source: AccountIdSource::IdToken,
+                is_default: None,
+                is_personal: None,
+            });
+        }
+        candidates.extend(collect_candidates_from_payload(
+            decoded.as_ref(),
+            AccountIdSource::Org,
+        ));
+    }
+
+    unique_candidates(candidates)
+}
+
+/// Determines if the accountId should be updated from a token-derived value.
+/// Org/manual selections stay stable across refreshes.
+pub fn should_update_account_id_from_token(
+    source: Option<&AccountIdSource>,
+    current_account_id: Option<&str>,
+) -> bool {
+    if current_account_id.is_none_or(str::is_empty) {
+        return true;
+    }
+    match source {
+        None => true,
+        Some(AccountIdSource::Token) | Some(AccountIdSource::IdToken) => true,
+        Some(_) => false,
+    }
+}
+
+/// Resolve which accountId to use for runtime API calls.
+/// Preserves explicit org/manual selections; only token/id_token sources
+/// auto-follow token changes.
+pub fn resolve_request_account_id(
+    stored_account_id: Option<&str>,
+    source: Option<&AccountIdSource>,
+    token_account_id: Option<&str>,
+) -> Option<String> {
+    let stored = stored_account_id.filter(|s| !s.is_empty());
+    let Some(stored) = stored else {
+        return token_account_id.map(|s| s.to_string());
+    };
+    if !should_update_account_id_from_token(source, Some(stored)) {
+        return Some(stored.to_string());
+    }
+    token_account_id.or(Some(stored)).map(|s| s.to_string())
+}
+
+/// Live request identity resolved from the stored workspace binding plus the
+/// freshest token-derived hints available for this request.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct RuntimeRequestIdentity {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub token_account_id: Option<String>,
+}
+
+/// Input to [`resolve_runtime_request_identity`].
+#[derive(Debug, Clone, Default)]
+pub struct ResolveRuntimeRequestIdentityInput<'a> {
+    pub stored_account_id: Option<&'a str>,
+    pub source: Option<AccountIdSource>,
+    pub stored_email: Option<&'a str>,
+    pub access_token: Option<&'a str>,
+    pub id_token: Option<&'a str>,
+}
+
+/// Resolve the live request identity for an account using the stored workspace
+/// binding plus the freshest token-derived hints available for this request.
+/// A fresh token email wins over the stored one; both pass [`sanitize_email`].
+pub fn resolve_runtime_request_identity(
+    input: ResolveRuntimeRequestIdentityInput<'_>,
+) -> RuntimeRequestIdentity {
+    let token_account_id = extract_account_id(input.access_token);
+    let account_id = resolve_request_account_id(
+        input.stored_account_id,
+        input.source.as_ref(),
+        token_account_id.as_deref(),
+    );
+    let email = sanitize_email(
+        extract_account_email(input.access_token, input.id_token).as_deref(),
+    )
+    .or_else(|| sanitize_email(input.stored_email));
+    RuntimeRequestIdentity {
+        account_id,
+        email,
+        token_account_id,
+    }
+}
+
+/// Sanitizes an email address by trimming whitespace and lowercasing.
+/// Returns `None` for empty/blank input or a value without `@`.
+pub fn sanitize_email(email: Option<&str>) -> Option<String> {
+    let email = email.filter(|e| !e.is_empty())?;
+    let trimmed = email.trim();
+    if trimmed.is_empty() || !trimmed.contains('@') {
+        return None;
+    }
+    Some(trimmed.to_lowercase())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use base64::Engine;
+    use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+    use serde_json::{Value, json};
+
+    /// Build a real (unsigned) JWT carrying `payload`, since Rust has no
+    /// module mocking: the TS suite mocks `decodeJWT`, here we feed the real
+    /// decoder equivalent tokens.
+    fn make_jwt(payload: &Value) -> String {
+        let b64 = |s: &str| URL_SAFE_NO_PAD.encode(s.as_bytes());
+        format!("{}.{}.sig", b64("{\"alg\":\"none\"}"), b64(&payload.to_string()))
+    }
+
+    fn claim_payload(account_id: &str) -> Value {
+        json!({ JWT_CLAIM_PATH: { "chatgpt_account_id": account_id } })
+    }
+
+    // === extractAccountId ===
+
+    #[test]
+    fn extract_account_id_returns_none_for_absent_or_empty_token() {
+        assert_eq!(extract_account_id(None), None);
+        assert_eq!(extract_account_id(Some("")), None);
+    }
+
+    #[test]
+    fn extract_account_id_extracts_from_jwt_claim_path() {
+        let token = make_jwt(&claim_payload("acc_123456"));
+        assert_eq!(extract_account_id(Some(&token)), Some("acc_123456".into()));
+    }
+
+    #[test]
+    fn extract_account_id_returns_none_when_decode_fails() {
+        assert_eq!(extract_account_id(Some("invalid.token")), None);
+    }
+
+    #[test]
+    fn extract_account_id_returns_none_for_blank_or_non_string_id() {
+        let blank = make_jwt(&claim_payload("   "));
+        assert_eq!(extract_account_id(Some(&blank)), None);
+        let numeric = make_jwt(&json!({ JWT_CLAIM_PATH: { "chatgpt_account_id": 12345 } }));
+        assert_eq!(extract_account_id(Some(&numeric)), None);
+    }
+
+    #[test]
+    fn extract_account_id_returns_raw_untrimmed_value() {
+        // Pinned in the TS suite: the raw claim comes back untrimmed.
+        let token = make_jwt(&claim_payload("  acc_123  "));
+        assert_eq!(extract_account_id(Some(&token)), Some("  acc_123  ".into()));
+    }
+
+    // === extractAccountEmail ===
+
+    #[test]
+    fn extract_account_email_prefers_id_token() {
+        let id_token = make_jwt(&json!({ "email": "id@example.com" }));
+        let access = make_jwt(&json!({ "email": "access@example.com" }));
+        assert_eq!(
+            extract_account_email(Some(&access), Some(&id_token)),
+            Some("id@example.com".into())
+        );
+    }
+
+    #[test]
+    fn extract_account_email_falls_back_to_access_token() {
+        let id_token = make_jwt(&json!({ "no_email": true }));
+        let access = make_jwt(&json!({ "email": "access@example.com" }));
+        assert_eq!(
+            extract_account_email(Some(&access), Some(&id_token)),
+            Some("access@example.com".into())
+        );
+    }
+
+    #[test]
+    fn extract_account_email_reads_nested_claim_and_chatgpt_user_email() {
+        let nested = make_jwt(&json!({ JWT_CLAIM_PATH: { "email": "nested@example.com" } }));
+        assert_eq!(
+            extract_account_email(Some(&nested), None),
+            Some("nested@example.com".into())
+        );
+        let user_email =
+            make_jwt(&json!({ JWT_CLAIM_PATH: { "chatgpt_user_email": "user@example.com" } }));
+        assert_eq!(
+            extract_account_email(Some(&user_email), None),
+            Some("user@example.com".into())
+        );
+    }
+
+    #[test]
+    fn extract_account_email_reads_preferred_username() {
+        let token = make_jwt(&json!({ "preferred_username": "pref@example.com" }));
+        assert_eq!(
+            extract_account_email(Some(&token), None),
+            Some("pref@example.com".into())
+        );
+    }
+
+    #[test]
+    fn extract_account_email_rejects_invalid_values() {
+        let no_at = make_jwt(&json!({ "email": "not-an-email" }));
+        assert_eq!(extract_account_email(Some(&no_at), None), None);
+        let empty = make_jwt(&json!({ "email": "" }));
+        assert_eq!(extract_account_email(Some(&empty), None), None);
+        assert_eq!(extract_account_email(None, None), None);
+    }
+
+    // === getAccountIdCandidates ===
+
+    #[test]
+    fn candidates_empty_for_no_tokens() {
+        assert!(get_account_id_candidates(None, None).is_empty());
+    }
+
+    #[test]
+    fn candidates_extract_root_level_ids_from_id_token() {
+        for (key, id) in [
+            ("chatgpt_account_id", "root_id_123"),
+            ("account_id", "alt_id_456"),
+            ("accountId", "camel_id_789"),
+        ] {
+            let id_token = make_jwt(&json!({ key: id }));
+            let candidates = get_account_id_candidates(None, Some(&id_token));
+            assert!(candidates.iter().any(|c| c.account_id == id), "key {key}");
+            assert!(
+                candidates
+                    .iter()
+                    .any(|c| matches!(c.source, AccountIdSource::IdToken)),
+                "key {key}"
+            );
+        }
+    }
+
+    #[test]
+    fn candidates_normalize_nested_wrappers_to_arrays() {
+        for wrapper in ["data", "items", "accounts", "organizations", "workspaces", "teams"] {
+            let access = make_jwt(&json!({
+                "organizations": { wrapper: [{ "account_id": "nested_org", "name": "Org" }] },
+            }));
+            let candidates = get_account_id_candidates(Some(&access), None);
+            assert!(
+                candidates.iter().any(|c| c.account_id == "nested_org"),
+                "wrapper {wrapper}"
+            );
+        }
+    }
+
+    #[test]
+    fn candidates_extract_org_lists_from_nested_claim_path() {
+        for key in ["organizations", "orgs", "accounts", "workspaces", "teams"] {
+            let access = make_jwt(&json!({
+                JWT_CLAIM_PATH: { key: [{ "account_id": format!("{key}_id"), "name": "N" }] },
+            }));
+            let candidates = get_account_id_candidates(Some(&access), None);
+            assert!(
+                candidates
+                    .iter()
+                    .any(|c| c.account_id == format!("{key}_id")
+                        && matches!(c.source, AccountIdSource::Org)),
+                "claim key {key}"
+            );
+        }
+    }
+
+    #[test]
+    fn candidates_include_default_token_candidate_from_access_token() {
+        let access = make_jwt(&claim_payload("acc_tok_123"));
+        let candidates = get_account_id_candidates(Some(&access), None);
+        assert_eq!(candidates.len(), 1);
+        let c = &candidates[0];
+        assert_eq!(c.account_id, "acc_tok_123");
+        assert_eq!(c.label, "Token account [id:ok_123]");
+        assert!(matches!(c.source, AccountIdSource::Token));
+        assert_eq!(c.is_default, Some(true));
+        assert_eq!(c.is_personal, None);
+    }
+
+    #[test]
+    fn candidates_deduplicate_by_account_id_first_wins() {
+        let mut payload = claim_payload("acc_same");
+        payload["organizations"] = json!([{ "account_id": "acc_same", "name": "Dup Org" }]);
+        let access = make_jwt(&payload);
+        let candidates = get_account_id_candidates(Some(&access), None);
+        assert_eq!(candidates.len(), 1);
+        // First occurrence (the token candidate) wins.
+        assert!(matches!(candidates[0].source, AccountIdSource::Token));
+    }
+
+    #[test]
+    fn candidates_skip_duplicate_id_token_account() {
+        let access = make_jwt(&claim_payload("acc_same"));
+        let id_token = make_jwt(&json!({ "account_id": "acc_same" }));
+        let candidates = get_account_id_candidates(Some(&access), Some(&id_token));
+        assert_eq!(candidates.len(), 1);
+        assert!(matches!(candidates[0].source, AccountIdSource::Token));
+    }
+
+    #[test]
+    fn candidates_format_labels_with_type_role_and_personal() {
+        let access = make_jwt(&json!({
+            "organizations": [{
+                "organization_id": "org_abcdef123456",
+                "name": "Acme",
+                "type": "team",
+                "role": "admin",
+                "is_personal": true,
+            }],
+        }));
+        let candidates = get_account_id_candidates(Some(&access), None);
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].label, "Acme (team, role:admin, personal) [id:123456]");
+        assert_eq!(candidates[0].is_personal, Some(true));
+    }
+
+    #[test]
+    fn candidates_use_type_as_label_base_when_name_absent() {
+        let access = make_jwt(&json!({
+            "organizations": [{ "id": "org_1", "type": "business" }],
+        }));
+        let candidates = get_account_id_candidates(Some(&access), None);
+        // type becomes the base AND still appears in the meta parts (name is
+        // absent so the case-insensitive same-name suppression does not fire).
+        assert_eq!(candidates[0].label, "business (business) [id:org_1]");
+    }
+
+    #[test]
+    fn candidates_parse_boolean_ish_strings_for_is_default() {
+        let make = |v: Value| {
+            make_jwt(&json!({
+                "organizations": [{ "account_id": "org_1", "is_default": v }],
+            }))
+        };
+        let c = get_account_id_candidates(Some(&make(json!("true"))), None);
+        assert_eq!(c[0].is_default, Some(true));
+        let c = get_account_id_candidates(Some(&make(json!("false"))), None);
+        assert_eq!(c[0].is_default, Some(false));
+        let c = get_account_id_candidates(Some(&make(json!("maybe"))), None);
+        assert_eq!(c[0].is_default, None);
+        let c = get_account_id_candidates(Some(&make(json!(1))), None);
+        assert_eq!(c[0].is_default, None);
+    }
+
+    #[test]
+    fn candidates_skip_invalid_records() {
+        let access = make_jwt(&json!({
+            "organizations": [
+                "not-a-record",
+                { "name": "No id here" },
+                { "account_id": "org_ok" },
+            ],
+        }));
+        let candidates = get_account_id_candidates(Some(&access), None);
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].account_id, "org_ok");
+    }
+
+    #[test]
+    fn candidates_keep_short_account_ids_whole_in_labels() {
+        let access = make_jwt(&json!({ "organizations": [{ "account_id": "abc" }] }));
+        let candidates = get_account_id_candidates(Some(&access), None);
+        assert_eq!(candidates[0].label, "Workspace [id:abc]");
+    }
+
+    // === selectBestAccountCandidate ===
+
+    fn cand(
+        id: &str,
+        source: AccountIdSource,
+        is_default: Option<bool>,
+        is_personal: Option<bool>,
+    ) -> AccountIdCandidate {
+        AccountIdCandidate {
+            account_id: id.to_string(),
+            label: format!("{id} label"),
+            source,
+            is_default,
+            is_personal,
+        }
+    }
+
+    #[test]
+    fn select_best_prefers_non_personal_org_default_over_token() {
+        let candidates = vec![
+            cand("tok", AccountIdSource::Token, Some(true), None),
+            cand("personal_default", AccountIdSource::Org, Some(true), Some(true)),
+            cand("org_default", AccountIdSource::Org, Some(true), Some(false)),
+        ];
+        let best = select_best_account_candidate(&candidates).unwrap();
+        assert_eq!(best.account_id, "org_default");
+    }
+
+    #[test]
+    fn select_best_falls_back_to_any_org_default() {
+        let candidates = vec![
+            cand("tok", AccountIdSource::Token, Some(true), None),
+            cand("personal_default", AccountIdSource::Org, Some(true), Some(true)),
+        ];
+        let best = select_best_account_candidate(&candidates).unwrap();
+        assert_eq!(best.account_id, "personal_default");
+    }
+
+    #[test]
+    fn select_best_prefers_id_token_when_no_org_default() {
+        let candidates = vec![
+            cand("tok", AccountIdSource::Token, Some(true), None),
+            cand("idt", AccountIdSource::IdToken, None, None),
+            cand("org_np", AccountIdSource::Org, None, Some(false)),
+        ];
+        let best = select_best_account_candidate(&candidates).unwrap();
+        assert_eq!(best.account_id, "idt");
+    }
+
+    #[test]
+    fn select_best_prefers_non_personal_org_then_token_then_first() {
+        let candidates = vec![
+            cand("tok", AccountIdSource::Token, Some(true), None),
+            cand("org_np", AccountIdSource::Org, None, Some(false)),
+        ];
+        assert_eq!(
+            select_best_account_candidate(&candidates).unwrap().account_id,
+            "org_np"
+        );
+
+        let candidates = vec![
+            cand("manual", AccountIdSource::Manual, None, None),
+            cand("tok", AccountIdSource::Token, Some(true), None),
+        ];
+        assert_eq!(
+            select_best_account_candidate(&candidates).unwrap().account_id,
+            "tok"
+        );
+
+        let candidates = vec![cand("manual", AccountIdSource::Manual, None, None)];
+        assert_eq!(
+            select_best_account_candidate(&candidates).unwrap().account_id,
+            "manual"
+        );
+
+        assert!(select_best_account_candidate(&[]).is_none());
+    }
+
+    // === shouldUpdateAccountIdFromToken ===
+
+    #[test]
+    fn should_update_rules() {
+        assert!(should_update_account_id_from_token(None, None));
+        assert!(should_update_account_id_from_token(None, Some("")));
+        assert!(should_update_account_id_from_token(None, Some("acc_1")));
+        assert!(should_update_account_id_from_token(
+            Some(&AccountIdSource::Token),
+            Some("acc_1")
+        ));
+        assert!(should_update_account_id_from_token(
+            Some(&AccountIdSource::IdToken),
+            Some("acc_1")
+        ));
+        assert!(!should_update_account_id_from_token(
+            Some(&AccountIdSource::Org),
+            Some("acc_1")
+        ));
+        assert!(!should_update_account_id_from_token(
+            Some(&AccountIdSource::Manual),
+            Some("acc_1")
+        ));
+    }
+
+    // === resolveRequestAccountId ===
+
+    #[test]
+    fn resolve_request_account_id_preserves_org_manual_selection() {
+        assert_eq!(
+            resolve_request_account_id(
+                Some("stored_org"),
+                Some(&AccountIdSource::Org),
+                Some("token_acc")
+            ),
+            Some("stored_org".into())
+        );
+        assert_eq!(
+            resolve_request_account_id(
+                Some("stored_manual"),
+                Some(&AccountIdSource::Manual),
+                Some("token_acc")
+            ),
+            Some("stored_manual".into())
+        );
+    }
+
+    #[test]
+    fn resolve_request_account_id_follows_token_sources() {
+        assert_eq!(
+            resolve_request_account_id(
+                Some("stored"),
+                Some(&AccountIdSource::Token),
+                Some("token_acc")
+            ),
+            Some("token_acc".into())
+        );
+        assert_eq!(
+            resolve_request_account_id(
+                Some("stored"),
+                Some(&AccountIdSource::IdToken),
+                Some("token_acc")
+            ),
+            Some("token_acc".into())
+        );
+    }
+
+    #[test]
+    fn resolve_request_account_id_fallbacks() {
+        // No stored -> token wins (even when None).
+        assert_eq!(
+            resolve_request_account_id(None, None, Some("token_acc")),
+            Some("token_acc".into())
+        );
+        assert_eq!(resolve_request_account_id(None, None, None), None);
+        // Updatable source but no token id -> keep stored.
+        assert_eq!(
+            resolve_request_account_id(Some("stored"), Some(&AccountIdSource::Token), None),
+            Some("stored".into())
+        );
+        // Empty stored string counts as absent (TS falsy).
+        assert_eq!(
+            resolve_request_account_id(Some(""), Some(&AccountIdSource::Org), Some("token_acc")),
+            Some("token_acc".into())
+        );
+    }
+
+    // === resolveRuntimeRequestIdentity ===
+
+    #[test]
+    fn runtime_identity_preserves_org_routing_and_hydrates_email() {
+        let access = make_jwt(&json!({
+            JWT_CLAIM_PATH: {
+                "chatgpt_account_id": "acc_token",
+                "email": "Fresh@Example.COM ",
+            },
+        }));
+        let identity = resolve_runtime_request_identity(ResolveRuntimeRequestIdentityInput {
+            stored_account_id: Some("acc_org"),
+            source: Some(AccountIdSource::Org),
+            stored_email: Some("stored@example.com"),
+            access_token: Some(&access),
+            id_token: None,
+        });
+        assert_eq!(identity.account_id, Some("acc_org".into()));
+        assert_eq!(identity.token_account_id, Some("acc_token".into()));
+        // Fresh token email wins over stored, sanitized (trim + lowercase).
+        assert_eq!(identity.email, Some("fresh@example.com".into()));
+    }
+
+    #[test]
+    fn runtime_identity_follows_token_derived_binding() {
+        let access = make_jwt(&claim_payload("acc_token"));
+        let identity = resolve_runtime_request_identity(ResolveRuntimeRequestIdentityInput {
+            stored_account_id: Some("acc_old"),
+            source: Some(AccountIdSource::Token),
+            stored_email: None,
+            access_token: Some(&access),
+            id_token: None,
+        });
+        assert_eq!(identity.account_id, Some("acc_token".into()));
+    }
+
+    #[test]
+    fn runtime_identity_falls_back_to_stored_email() {
+        let access = make_jwt(&claim_payload("acc_token"));
+        let identity = resolve_runtime_request_identity(ResolveRuntimeRequestIdentityInput {
+            stored_account_id: None,
+            source: None,
+            stored_email: Some("  Stored@Example.com "),
+            access_token: Some(&access),
+            id_token: None,
+        });
+        assert_eq!(identity.account_id, Some("acc_token".into()));
+        assert_eq!(identity.email, Some("stored@example.com".into()));
+    }
+
+    // === sanitizeEmail ===
+
+    #[test]
+    fn sanitize_email_rules() {
+        assert_eq!(sanitize_email(None), None);
+        assert_eq!(sanitize_email(Some("")), None);
+        assert_eq!(sanitize_email(Some("   ")), None);
+        assert_eq!(sanitize_email(Some("no-at-sign")), None);
+        assert_eq!(
+            sanitize_email(Some("User@Example.COM")),
+            Some("user@example.com".into())
+        );
+        assert_eq!(
+            sanitize_email(Some("  a@b.co  ")),
+            Some("a@b.co".into())
+        );
+        assert_eq!(
+            sanitize_email(Some(" MiXeD@CaSe.Io ")),
+            Some("mixed@case.io".into())
+        );
+    }
+}
diff --git a/crates/core/src/types.rs b/crates/core/src/types.rs
new file mode 100644
index 000000000..9429090c3
--- /dev/null
+++ b/crates/core/src/types.rs
@@ -0,0 +1,897 @@
+//! Port of `lib/types.ts` — hand-written interfaces (no runtime validation in
+//! TS; here permissive serde models).
+//!
+//! Design rules (ARCHITECTURE §6.1 / §8.1):
+//! - [`RequestBody`] and every nested request-shaped struct MUST round-trip
+//!   unknown fields: known typed fields + `#[serde(flatten)] extra`.
+//!   `serde_json`'s `preserve_order` feature keeps unknown-key order stable.
+//! - Fields the TS *interface* marks required but the runtime tolerates
+//!   missing (e.g. `RequestBody.model`, `InputItem.role`) are `Option` here so
+//!   permissive request bodies keep flowing exactly as they did through the JS
+//!   runtime.
+//! - Open string unions (`PromptCacheRetention`, verbosity, summary levels on
+//!   the wire) stay `String`; strict enums exist only for values WE construct
+//!   ([`ReasoningConfig`]).
+//!
+//! Schema-inferred aliases from TS `types.ts` (`PluginConfig`, `TokenResult`,
+//! `AccountIdSource`, …) live in `crate::schemas::*` — the barrel re-export
+//! has no Rust equivalent (each consumer imports from the owning module).
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Number, Value};
+
+use crate::constants::WireReasoningEffort;
+
+// ---------------------------------------------------------------------------
+// Host/user config shapes
+// ---------------------------------------------------------------------------
+
+/// TS `UserConfig` — the host's per-model configuration tree.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct UserConfig {
+    #[serde(default)]
+    pub global: ConfigOptions,
+    #[serde(default)]
+    pub models: HashMap<String, UserModelConfig>,
+}
+
+/// One entry of `UserConfig.models` (TS inline type; open record).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct UserModelConfig {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub options: Option<ConfigOptions>,
+    /// `Record<string, (ConfigOptions & { disabled?: boolean }) | undefined>`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub variants: Option<HashMap<String, Option<ModelVariantConfig>>>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `ConfigOptions`. All unions stay open strings — invalid values must
+/// degrade downstream (set-membership checks), never fail deserialization.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ConfigOptions {
+    /// `ultra` is accepted here but always resolves to `max` before the request.
+    #[serde(default, rename = "reasoningEffort", skip_serializing_if = "Option::is_none")]
+    pub reasoning_effort: Option<String>,
+    /// `"auto" | "concise" | "detailed" | "off" | "on"`.
+    #[serde(default, rename = "reasoningSummary", skip_serializing_if = "Option::is_none")]
+    pub reasoning_summary: Option<String>,
+    /// `"low" | "medium" | "high"`.
+    #[serde(default, rename = "textVerbosity", skip_serializing_if = "Option::is_none")]
+    pub text_verbosity: Option<String>,
+    /// [`PromptCacheRetention`] — open string union.
+    #[serde(default, rename = "promptCacheRetention", skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_retention: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include: Option<Vec<String>>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// `ConfigOptions & { disabled?: boolean }` (model-variant entry).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ModelVariantConfig {
+    #[serde(default, rename = "reasoningEffort", skip_serializing_if = "Option::is_none")]
+    pub reasoning_effort: Option<String>,
+    #[serde(default, rename = "reasoningSummary", skip_serializing_if = "Option::is_none")]
+    pub reasoning_summary: Option<String>,
+    #[serde(default, rename = "textVerbosity", skip_serializing_if = "Option::is_none")]
+    pub text_verbosity: Option<String>,
+    #[serde(default, rename = "promptCacheRetention", skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_retention: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub disabled: Option<bool>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `PromptCacheRetention = "5m" | "1h" | "24h" | "7d" | (string & {})` —
+/// an OPEN string union, so it stays a plain `String` in Rust.
+pub type PromptCacheRetention = String;
+
+// ---------------------------------------------------------------------------
+// Reasoning config
+// ---------------------------------------------------------------------------
+
+/// Summary detail level accepted by the Responses API (TS inline union on
+/// `ReasoningConfig.summary`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ReasoningSummary {
+    Auto,
+    Concise,
+    Detailed,
+}
+
+impl ReasoningSummary {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ReasoningSummary::Auto => "auto",
+            ReasoningSummary::Concise => "concise",
+            ReasoningSummary::Detailed => "detailed",
+        }
+    }
+}
+
+/// TS `ReasoningConfig` — the STRICT shape the transformer constructs.
+/// `effort` as sent to the API; `ultra` is absent by construction (it is a
+/// client-side tier that always resolves to `max` before the request is built).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ReasoningConfig {
+    pub effort: WireReasoningEffort,
+    pub summary: ReasoningSummary,
+}
+
+/// The PERMISSIVE `reasoning` slot of [`RequestBody`]
+/// (TS `reasoning?: Partial<ReasoningConfig>` on an unvalidated wire object).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ReasoningSettings {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effort: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub summary: Option<String>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+impl From<ReasoningConfig> for ReasoningSettings {
+    fn from(config: ReasoningConfig) -> Self {
+        ReasoningSettings {
+            effort: Some(config.effort.as_str().to_string()),
+            summary: Some(config.summary.as_str().to_string()),
+            extra: Map::new(),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+/// TS `ToolParametersSchema` (open record; `type` is nominally `"object"` but
+/// left permissive — runtime guards do the checking).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ToolParametersSchema {
+    #[serde(default, rename = "type", skip_serializing_if = "Option::is_none")]
+    pub kind: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub properties: Option<Map<String, Value>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub required: Option<Vec<String>>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `ToolFunction` (open record).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolFunction {
+    pub name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parameters: Option<ToolParametersSchema>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"function"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum FunctionToolTag {
+    #[default]
+    #[serde(rename = "function")]
+    Function,
+}
+
+/// TS `FunctionToolDefinition`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FunctionToolDefinition {
+    #[serde(rename = "type")]
+    pub kind: FunctionToolTag,
+    pub function: ToolFunction,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub defer_loading: Option<bool>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"tool_search"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToolSearchToolTag {
+    #[default]
+    #[serde(rename = "tool_search")]
+    ToolSearch,
+}
+
+/// TS `ToolSearchToolDefinition`.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ToolSearchToolDefinition {
+    #[serde(rename = "type")]
+    pub kind: ToolSearchToolTag,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_num_results: Option<Number>,
+    /// `"low" | "medium" | "high"` (open).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub search_context_size: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub filters: Option<Map<String, Value>>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"mcp"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RemoteMcpToolTag {
+    #[default]
+    #[serde(rename = "mcp")]
+    Mcp,
+}
+
+/// TS `RemoteMcpToolDefinition`.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct RemoteMcpToolDefinition {
+    #[serde(rename = "type")]
+    pub kind: RemoteMcpToolTag,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_label: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_url: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub connector_id: Option<String>,
+    /// `Record<string, string>` in TS; kept order-preserving.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub headers: Option<Map<String, Value>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub allowed_tools: Option<Vec<String>>,
+    /// `"never" | "always" | "auto" | Record<string, unknown>`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub require_approval: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub defer_loading: Option<bool>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"computer" | "computer_use_preview"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ComputerUseToolTag {
+    #[default]
+    #[serde(rename = "computer")]
+    Computer,
+    #[serde(rename = "computer_use_preview")]
+    ComputerUsePreview,
+}
+
+/// TS `ComputerUseToolDefinition`.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ComputerUseToolDefinition {
+    #[serde(rename = "type")]
+    pub kind: ComputerUseToolTag,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display_width: Option<Number>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display_height: Option<Number>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub environment: Option<String>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"namespace"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum NamespaceToolTag {
+    #[default]
+    #[serde(rename = "namespace")]
+    Namespace,
+}
+
+/// TS `ToolNamespaceDefinition` (recursive).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ToolNamespaceDefinition {
+    #[serde(rename = "type")]
+    pub kind: NamespaceToolTag,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tools: Option<Vec<RequestToolDefinition>>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `RequestToolDefinition` union. Untagged: each typed variant carries a
+/// literal `type` tag enum, so discrimination matches the TS discriminants;
+/// anything else (including the open `{type?: string}` catch-all) lands in
+/// `Other` and round-trips verbatim.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum RequestToolDefinition {
+    Function(FunctionToolDefinition),
+    ToolSearch(ToolSearchToolDefinition),
+    RemoteMcp(RemoteMcpToolDefinition),
+    ComputerUse(ComputerUseToolDefinition),
+    Namespace(ToolNamespaceDefinition),
+    Other(Value),
+}
+
+// ---------------------------------------------------------------------------
+// Text format config
+// ---------------------------------------------------------------------------
+
+/// Literal tag `"text"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TextFormatTextTag {
+    #[default]
+    #[serde(rename = "text")]
+    Text,
+}
+
+/// `{ type: "text", ... }` arm of [`TextFormatConfig`].
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct TextFormatText {
+    #[serde(rename = "type")]
+    pub kind: TextFormatTextTag,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"json_object"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TextFormatJsonObjectTag {
+    #[default]
+    #[serde(rename = "json_object")]
+    JsonObject,
+}
+
+/// `{ type: "json_object", ... }` arm of [`TextFormatConfig`].
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct TextFormatJsonObject {
+    #[serde(rename = "type")]
+    pub kind: TextFormatJsonObjectTag,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// Literal tag `"json_schema"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TextFormatJsonSchemaTag {
+    #[default]
+    #[serde(rename = "json_schema")]
+    JsonSchema,
+}
+
+/// `{ type: "json_schema", ... }` arm of [`TextFormatConfig`].
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct TextFormatJsonSchema {
+    #[serde(rename = "type")]
+    pub kind: TextFormatJsonSchemaTag,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub schema: Option<Map<String, Value>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub strict: Option<bool>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `TextFormatConfig` union (all arms are open records; the final arm is a
+/// full catch-all so any JSON value round-trips).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum TextFormatConfig {
+    Text(TextFormatText),
+    JsonObject(TextFormatJsonObject),
+    JsonSchema(TextFormatJsonSchema),
+    Other(Value),
+}
+
+/// The permissive `text` slot of [`RequestBody`]
+/// (TS `text?: { verbosity?; format? }`).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct TextSettings {
+    /// `"low" | "medium" | "high"` (open).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub verbosity: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub format: Option<TextFormatConfig>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+// ---------------------------------------------------------------------------
+// OAuth flow shapes
+// ---------------------------------------------------------------------------
+
+/// Data half of the TS `OAuthServerInfo` (the `close`/`waitForCode` behavior
+/// lives on the server handle in `cma-auth::callback_server`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OAuthServerInfo {
+    pub port: u16,
+    pub ready: bool,
+    /// The `errno` code from a failed listen (for example `EADDRINUSE`) when
+    /// `ready` is `false`. Lets callers distinguish a contended callback port
+    /// from other bind failures. Absent when `ready` is `true`.
+    #[serde(
+        default,
+        rename = "bindErrorCode",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub bind_error_code: Option<String>,
+}
+
+/// TS `PKCEPair`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PKCEPair {
+    pub challenge: String,
+    pub verifier: String,
+}
+
+/// TS `AuthorizationFlow`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuthorizationFlow {
+    pub pkce: PKCEPair,
+    pub state: String,
+    pub url: String,
+}
+
+/// TS `ParsedAuthInput`.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ParsedAuthInput {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub code: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state: Option<String>,
+}
+
+/// TS `OAuthAuthDetails = Extract<Auth, { type: "oauth" }>` — the in-memory
+/// credential triple exchanged between the account manager and auth flows.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OAuthAuthDetails {
+    pub access: String,
+    pub refresh: String,
+    /// Epoch milliseconds.
+    pub expires: i64,
+}
+
+// ---------------------------------------------------------------------------
+// JWT payload
+// ---------------------------------------------------------------------------
+
+/// The `"https://api.openai.com/auth"` claim object (see
+/// [`crate::constants::JWT_CLAIM_PATH`]).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct JwtAuthClaim {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub chatgpt_account_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub email: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub chatgpt_user_email: Option<String>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `JWTPayload` — JWT payload with ChatGPT account info. Unverified decode
+/// target (`crate::jwt::decode_jwt`); everything optional, unknown keys kept.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct JWTPayload {
+    #[serde(
+        default,
+        rename = "https://api.openai.com/auth",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub auth: Option<JwtAuthClaim>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub organizations: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub orgs: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub accounts: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workspaces: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub teams: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub email: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub preferred_username: Option<String>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+// ---------------------------------------------------------------------------
+// Request body
+// ---------------------------------------------------------------------------
+
+/// TS `InputItem` — message input item. The TS interface marks `type`/`role`
+/// required, but the runtime tolerates items without them (e.g.
+/// `function_call_output` items carry no `role`), so both are optional here.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct InputItem {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    #[serde(default, rename = "type", skip_serializing_if = "Option::is_none")]
+    pub kind: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub content: Option<Value>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// The `providerOptions.openai` slot
+/// (TS `Partial<ConfigOptions> & { store?; include? }`).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct OpenAiProviderOptions {
+    #[serde(default, rename = "reasoningEffort", skip_serializing_if = "Option::is_none")]
+    pub reasoning_effort: Option<String>,
+    #[serde(default, rename = "reasoningSummary", skip_serializing_if = "Option::is_none")]
+    pub reasoning_summary: Option<String>,
+    #[serde(default, rename = "textVerbosity", skip_serializing_if = "Option::is_none")]
+    pub text_verbosity: Option<String>,
+    #[serde(default, rename = "promptCacheRetention", skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_retention: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub store: Option<bool>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// The `providerOptions` slot of [`RequestBody`] (open record).
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ProviderOptions {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub openai: Option<OpenAiProviderOptions>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `RequestBody` — the Responses API request body. Permissive: known typed
+/// fields + `extra` for everything else; MUST round-trip unknown fields.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct RequestBody {
+    /// Required in the TS interface; optional here because the runtime routes
+    /// missing/empty models to `DEFAULT_MODEL` downstream.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub background: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub store: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub stream: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub instructions: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input: Option<Vec<InputItem>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tools: Option<Vec<RequestToolDefinition>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning: Option<ReasoningSettings>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<TextSettings>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include: Option<Vec<String>>,
+    #[serde(
+        default,
+        rename = "providerOptions",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub provider_options: Option<ProviderOptions>,
+    /// Stable key to enable prompt-token caching on Codex backend.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_key: Option<String>,
+    /// Retention mode for server-side prompt cache entries.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_retention: Option<PromptCacheRetention>,
+    /// Resume a prior Responses API turn without resending the full transcript.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub previous_response_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_output_tokens: Option<Number>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_completion_tokens: Option<Number>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+// ---------------------------------------------------------------------------
+// SSE / caching / GitHub
+// ---------------------------------------------------------------------------
+
+/// TS `SSEEventData` — SSE event data structure. `type` is nominally required;
+/// optional here so the response handler can apply its own malformed-event
+/// handling instead of failing deserialization.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct SSEEventData {
+    #[serde(default, rename = "type", skip_serializing_if = "Option::is_none")]
+    pub kind: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response: Option<Value>,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+/// TS `CacheMetadata` — cache metadata for Codex instructions.
+/// NOTE: `etag` is `string | null` (NOT optional) — `None` serializes as an
+/// explicit `null`, matching the TS on-disk cache format.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CacheMetadata {
+    pub etag: Option<String>,
+    pub tag: String,
+    #[serde(rename = "lastChecked")]
+    pub last_checked: i64,
+    pub url: String,
+    /// SHA-256 of the cached content (prompts-03). When present, the disk
+    /// cache is verified against it before use and discarded on mismatch, so
+    /// a corrupted or tampered cache file cannot be served as trusted prompt
+    /// instructions. Optional for backward compatibility with caches written
+    /// before this field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha256: Option<String>,
+}
+
+/// TS `GitHubRelease`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct GitHubRelease {
+    pub tag_name: String,
+    #[serde(flatten)]
+    pub extra: Map<String, Value>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn request_body_round_trips_unknown_fields() {
+        let raw = json!({
+            "model": "gpt-5.3-codex",
+            "stream": true,
+            "store": false,
+            "instructions": "be brief",
+            "input": [
+                {"type": "message", "role": "user", "content": "hi", "customFlag": true},
+                {"type": "function_call_output", "call_id": "c1", "output": "{}"}
+            ],
+            "reasoning": {"effort": "high", "novelKey": 1},
+            "text": {"verbosity": "low", "format": {"type": "text"}},
+            "providerOptions": {"openai": {"reasoningEffort": "medium", "store": true}},
+            "prompt_cache_key": "abc",
+            "max_output_tokens": 4096,
+            "totally_unknown_top_level": {"a": [1, 2, 3]}
+        });
+
+        let body: RequestBody = serde_json::from_value(raw.clone()).unwrap();
+        assert_eq!(body.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(body.stream, Some(true));
+        assert_eq!(body.store, Some(false));
+        assert!(body.extra.contains_key("totally_unknown_top_level"));
+
+        let input = body.input.as_ref().unwrap();
+        assert_eq!(input[0].role.as_deref(), Some("user"));
+        assert!(input[0].extra.contains_key("customFlag"));
+        // function_call_output items have no role — must still parse.
+        assert_eq!(input[1].role, None);
+        assert!(input[1].extra.contains_key("call_id"));
+
+        let reasoning = body.reasoning.as_ref().unwrap();
+        assert_eq!(reasoning.effort.as_deref(), Some("high"));
+        assert!(reasoning.extra.contains_key("novelKey"));
+
+        let round = serde_json::to_value(&body).unwrap();
+        assert_eq!(round, raw);
+    }
+
+    #[test]
+    fn request_body_without_model_still_parses() {
+        let body: RequestBody = serde_json::from_value(json!({"input": []})).unwrap();
+        assert_eq!(body.model, None);
+        let round = serde_json::to_value(&body).unwrap();
+        assert_eq!(round, json!({"input": []}));
+    }
+
+    #[test]
+    fn tool_definitions_discriminate_on_type_literal() {
+        let raw = json!([
+            {"type": "function", "function": {"name": "read_file", "parameters": {"type": "object", "properties": {}}}},
+            {"type": "tool_search", "max_num_results": 5},
+            {"type": "mcp", "server_label": "gh", "require_approval": "never"},
+            {"type": "computer_use_preview", "display_width": 1280},
+            {"type": "namespace", "name": "ns", "tools": [{"type": "function", "function": {"name": "inner"}}]},
+            {"type": "future_tool_kind", "payload": 1},
+            {"no_type_at_all": true}
+        ]);
+        let tools: Vec<RequestToolDefinition> = serde_json::from_value(raw.clone()).unwrap();
+
+        assert!(matches!(&tools[0], RequestToolDefinition::Function(f) if f.function.name == "read_file"));
+        assert!(matches!(&tools[1], RequestToolDefinition::ToolSearch(_)));
+        assert!(matches!(&tools[2], RequestToolDefinition::RemoteMcp(m) if m.server_label.as_deref() == Some("gh")));
+        assert!(matches!(
+            &tools[3],
+            RequestToolDefinition::ComputerUse(c) if c.kind == ComputerUseToolTag::ComputerUsePreview
+        ));
+        assert!(matches!(&tools[4], RequestToolDefinition::Namespace(n) if n.tools.as_ref().unwrap().len() == 1));
+        assert!(matches!(&tools[5], RequestToolDefinition::Other(_)));
+        assert!(matches!(&tools[6], RequestToolDefinition::Other(_)));
+
+        let round = serde_json::to_value(&tools).unwrap();
+        assert_eq!(round, raw);
+    }
+
+    #[test]
+    fn malformed_function_tool_falls_to_catch_all_and_round_trips() {
+        // `type: "function"` without a `function` field — the TS runtime guard
+        // would skip it; here it lands in Other and round-trips untouched.
+        let raw = json!({"type": "function", "name": "oops"});
+        let tool: RequestToolDefinition = serde_json::from_value(raw.clone()).unwrap();
+        assert!(matches!(&tool, RequestToolDefinition::Other(_)));
+        assert_eq!(serde_json::to_value(&tool).unwrap(), raw);
+    }
+
+    #[test]
+    fn text_format_config_arms() {
+        let text: TextFormatConfig = serde_json::from_value(json!({"type": "text"})).unwrap();
+        assert!(matches!(text, TextFormatConfig::Text(_)));
+
+        let schema: TextFormatConfig = serde_json::from_value(
+            json!({"type": "json_schema", "name": "s", "strict": true, "schema": {"type": "object"}}),
+        )
+        .unwrap();
+        match &schema {
+            TextFormatConfig::JsonSchema(s) => {
+                assert_eq!(s.name.as_deref(), Some("s"));
+                assert_eq!(s.strict, Some(true));
+            }
+            other => panic!("expected JsonSchema, got {other:?}"),
+        }
+
+        let unknown: TextFormatConfig =
+            serde_json::from_value(json!({"type": "grammar", "rules": []})).unwrap();
+        assert!(matches!(unknown, TextFormatConfig::Other(_)));
+    }
+
+    #[test]
+    fn reasoning_config_converts_to_wire_settings() {
+        let config = ReasoningConfig {
+            effort: WireReasoningEffort::Max,
+            summary: ReasoningSummary::Auto,
+        };
+        let settings: ReasoningSettings = config.into();
+        assert_eq!(settings.effort.as_deref(), Some("max"));
+        assert_eq!(settings.summary.as_deref(), Some("auto"));
+        assert_eq!(
+            serde_json::to_value(&settings).unwrap(),
+            json!({"effort": "max", "summary": "auto"})
+        );
+    }
+
+    #[test]
+    fn jwt_payload_reads_the_claim_path_and_keeps_unknown_keys() {
+        let raw = json!({
+            "https://api.openai.com/auth": {
+                "chatgpt_account_id": "acc_123",
+                "chatgpt_user_email": "user@example.com",
+                "plan": "pro"
+            },
+            "email": "user@example.com",
+            "exp": 1_700_000_000,
+            "custom": {"nested": true}
+        });
+        let payload: JWTPayload = serde_json::from_value(raw.clone()).unwrap();
+        let auth = payload.auth.as_ref().unwrap();
+        assert_eq!(auth.chatgpt_account_id.as_deref(), Some("acc_123"));
+        assert_eq!(auth.chatgpt_user_email.as_deref(), Some("user@example.com"));
+        assert!(auth.extra.contains_key("plan"));
+        assert_eq!(payload.email.as_deref(), Some("user@example.com"));
+        assert!(payload.extra.contains_key("exp"));
+        assert!(payload.extra.contains_key("custom"));
+        assert_eq!(serde_json::to_value(&payload).unwrap(), raw);
+    }
+
+    #[test]
+    fn cache_metadata_serializes_null_etag_and_omits_absent_sha256() {
+        let meta = CacheMetadata {
+            etag: None,
+            tag: "codex".to_string(),
+            last_checked: 1_700_000_000_123,
+            url: "https://example.com/prompt.md".to_string(),
+            sha256: None,
+        };
+        assert_eq!(
+            serde_json::to_string(&meta).unwrap(),
+            r#"{"etag":null,"tag":"codex","lastChecked":1700000000123,"url":"https://example.com/prompt.md"}"#
+        );
+
+        // Pre-sha256 caches (no field) still deserialize.
+        let old: CacheMetadata = serde_json::from_str(
+            r#"{"etag":"\"abc\"","tag":"t","lastChecked":1,"url":"u"}"#,
+        )
+        .unwrap();
+        assert_eq!(old.etag.as_deref(), Some("\"abc\""));
+        assert_eq!(old.sha256, None);
+    }
+
+    #[test]
+    fn oauth_shapes_round_trip() {
+        let info = OAuthServerInfo {
+            port: 1455,
+            ready: false,
+            bind_error_code: Some("EADDRINUSE".to_string()),
+        };
+        assert_eq!(
+            serde_json::to_value(&info).unwrap(),
+            json!({"port": 1455, "ready": false, "bindErrorCode": "EADDRINUSE"})
+        );
+
+        let details = OAuthAuthDetails {
+            access: "a".into(),
+            refresh: "r".into(),
+            expires: 1_700_000_000_000,
+        };
+        let round: OAuthAuthDetails =
+            serde_json::from_value(serde_json::to_value(&details).unwrap()).unwrap();
+        assert_eq!(round, details);
+    }
+
+    #[test]
+    fn user_config_tolerates_missing_sections_and_open_values() {
+        let config: UserConfig = serde_json::from_value(json!({})).unwrap();
+        assert!(config.models.is_empty());
+
+        let config: UserConfig = serde_json::from_value(json!({
+            "global": {"reasoningEffort": "ultra", "unknownOpt": 1},
+            "models": {
+                "gpt-5.5": {
+                    "options": {"textVerbosity": "high"},
+                    "variants": {"fast": {"reasoningEffort": "low", "disabled": true}, "off": null},
+                    "customModelKey": "x"
+                }
+            }
+        }))
+        .unwrap();
+        assert_eq!(config.global.reasoning_effort.as_deref(), Some("ultra"));
+        assert!(config.global.extra.contains_key("unknownOpt"));
+        let model = &config.models["gpt-5.5"];
+        assert_eq!(
+            model.options.as_ref().unwrap().text_verbosity.as_deref(),
+            Some("high")
+        );
+        let variants = model.variants.as_ref().unwrap();
+        assert_eq!(
+            variants["fast"].as_ref().unwrap().disabled,
+            Some(true)
+        );
+        assert!(variants["off"].is_none());
+        assert!(model.extra.contains_key("customModelKey"));
+    }
+
+    #[test]
+    fn sse_event_data_is_permissive() {
+        let event: SSEEventData = serde_json::from_value(json!({
+            "type": "response.completed",
+            "response": {"id": "resp_1"},
+            "sequence_number": 7
+        }))
+        .unwrap();
+        assert_eq!(event.kind.as_deref(), Some("response.completed"));
+        assert!(event.response.is_some());
+        assert!(event.extra.contains_key("sequence_number"));
+
+        // No type at all still parses; the response handler decides what to do.
+        let untyped: SSEEventData = serde_json::from_value(json!({"delta": "x"})).unwrap();
+        assert_eq!(untyped.kind, None);
+    }
+}
diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs
new file mode 100644
index 000000000..2e771e8cd
--- /dev/null
+++ b/crates/core/src/utils.rs
@@ -0,0 +1,133 @@
+//! Port of `lib/utils.ts` — consolidated tiny utility functions.
+//!
+//! Note: TS `isAbortError` has no Rust equivalent here — abort/timeout
+//! detection is handled by `tokio::time::timeout` / request-layer error
+//! classification (ARCHITECTURE §6.1 deliberately omits it from this file).
+
+use serde_json::Value;
+
+/// Type guard for plain objects (TS `isRecord`): in `serde_json::Value` terms,
+/// only `Value::Object` qualifies (arrays and null are NOT records).
+pub fn is_record(value: &Value) -> bool {
+    value.is_object()
+}
+
+/// Returns the current wall-clock timestamp in milliseconds since the Unix
+/// epoch (TS `nowMs`, a `Date.now()` wrapper kept as a test seam — for
+/// injectable time use [`crate::clock::Clock`]).
+pub fn now_ms() -> i64 {
+    chrono::Utc::now().timestamp_millis()
+}
+
+/// Safely converts a JSON value to a string representation (TS
+/// `toStringValue`):
+/// - strings pass through unquoted;
+/// - `null` → `"null"`;
+/// - objects/arrays → compact `JSON.stringify` output;
+/// - numbers/booleans → their JS `String(...)` form.
+///
+/// For the JS `undefined → "undefined"` case (no JSON equivalent) see
+/// [`to_string_value_opt`].
+pub fn to_string_value(value: &Value) -> String {
+    match value {
+        Value::String(s) => s.clone(),
+        Value::Null => "null".to_string(),
+        Value::Object(_) | Value::Array(_) => serde_json::to_string(value)
+            .unwrap_or_else(|_| "[object Object]".to_string()),
+        Value::Bool(b) => b.to_string(),
+        Value::Number(n) => n.to_string(),
+    }
+}
+
+/// [`to_string_value`] over an optional value: `None` (the JS `undefined`
+/// case) → `"undefined"`.
+pub fn to_string_value_opt(value: Option<&Value>) -> String {
+    match value {
+        Some(value) => to_string_value(value),
+        None => "undefined".to_string(),
+    }
+}
+
+/// Async sleep for the given number of milliseconds (TS `sleep`, a promisified
+/// `setTimeout`).
+pub async fn sleep(ms: u64) {
+    tokio::time::sleep(std::time::Duration::from_millis(ms)).await;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn is_record_accepts_only_objects() {
+        assert!(is_record(&json!({})));
+        assert!(is_record(&json!({"key": "value"})));
+        assert!(is_record(&json!({"nested": {"obj": true}})));
+
+        assert!(!is_record(&Value::Null));
+        assert!(!is_record(&json!([])));
+        assert!(!is_record(&json!([1, 2, 3])));
+        assert!(!is_record(&json!("string")));
+        assert!(!is_record(&json!(123)));
+        assert!(!is_record(&json!(true)));
+    }
+
+    #[test]
+    fn now_ms_returns_a_plausible_epoch_timestamp() {
+        let now = now_ms();
+        // 2020-01-01 in ms — anything earlier means we returned seconds or garbage.
+        assert!(now > 1_577_836_800_000, "now_ms() = {now}");
+    }
+
+    #[test]
+    fn to_string_value_returns_strings_unchanged() {
+        assert_eq!(to_string_value(&json!("hello")), "hello");
+        assert_eq!(to_string_value(&json!("")), "");
+        assert_eq!(to_string_value(&json!("123")), "123");
+    }
+
+    #[test]
+    fn to_string_value_converts_null_and_undefined() {
+        assert_eq!(to_string_value(&Value::Null), "null");
+        assert_eq!(to_string_value_opt(None), "undefined");
+        assert_eq!(to_string_value_opt(Some(&json!("x"))), "x");
+    }
+
+    #[test]
+    // 3.14 is a decimal-formatting sample (mirrors the TS test literal), not an
+    // approximation of PI.
+    #[allow(clippy::approx_constant)]
+    fn to_string_value_converts_numbers_and_booleans() {
+        assert_eq!(to_string_value(&json!(123)), "123");
+        assert_eq!(to_string_value(&json!(0)), "0");
+        assert_eq!(to_string_value(&json!(-42)), "-42");
+        assert_eq!(to_string_value(&json!(3.14)), "3.14");
+        assert_eq!(to_string_value(&json!(true)), "true");
+        assert_eq!(to_string_value(&json!(false)), "false");
+    }
+
+    #[test]
+    fn to_string_value_json_stringifies_objects_and_arrays() {
+        assert_eq!(to_string_value(&json!({})), "{}");
+        assert_eq!(to_string_value(&json!({"key": "value"})), r#"{"key":"value"}"#);
+        assert_eq!(to_string_value(&json!([1, 2, 3])), "[1,2,3]");
+        assert_eq!(
+            to_string_value(&json!({"a": {"b": {"c": 1}}})),
+            r#"{"a":{"b":{"c":1}}}"#
+        );
+    }
+
+    #[tokio::test]
+    async fn sleep_resolves_after_the_given_duration() {
+        let start = std::time::Instant::now();
+        sleep(25).await;
+        // Timer granularity varies by platform; only assert the lower bound.
+        assert!(start.elapsed() >= std::time::Duration::from_millis(20));
+    }
+
+    #[tokio::test]
+    async fn sleep_zero_resolves_immediately() {
+        sleep(0).await;
+    }
+}
diff --git a/crates/core/src/wsl.rs b/crates/core/src/wsl.rs
new file mode 100644
index 000000000..399be4e5b
--- /dev/null
+++ b/crates/core/src/wsl.rs
@@ -0,0 +1,165 @@
+//! Port of `lib/wsl.ts` — WSL (Windows Subsystem for Linux) detection.
+//!
+//! Behavior source: specs/01-foundation.md §2.14, §5.3.
+//!
+//! WSL reports itself as Linux, so every platform switch in this package
+//! treats it as a native Linux host. That is wrong for anything crossing the
+//! Windows boundary: the default browser, the clipboard, and the loopback
+//! interface that receives the OAuth callback all belong to the Windows host
+//! rather than to the distro.
+//!
+//! Contracts:
+//! - False unless the platform is Linux.
+//! - True when `WSL_DISTRO_NAME` or `WSL_INTEROP` is non-empty (NOT trimmed —
+//!   the TS check is `.length > 0` on the raw value).
+//! - Fallback for env-stripping shells (systemd units, cron): `/proc/version`
+//!   content matching `/microsoft|wsl/i`; read failure → false.
+//! - The result is memoized (it cannot change within a process lifetime).
+//! - `get_wsl_distro_name` returns the TRIMMED `WSL_DISTRO_NAME` when inside
+//!   WSL and non-empty, else `None`.
+
+use std::sync::Mutex;
+
+static CACHED_IS_WSL: Mutex<Option<bool>> = Mutex::new(None);
+
+/// Pure detection core (env values + `/proc/version` reader injected) so the
+/// decision table is unit-testable on every platform. The platform gate lives
+/// in [`detect_wsl`].
+fn detect_wsl_from(
+    wsl_distro_name: Option<&str>,
+    wsl_interop: Option<&str>,
+    read_proc_version: impl FnOnce() -> Option<String>,
+) -> bool {
+    // Set by WSL itself; present in every interop-enabled distro shell.
+    // Raw (untrimmed) length check, matching the TS source.
+    if !wsl_distro_name.unwrap_or("").is_empty() || !wsl_interop.unwrap_or("").is_empty() {
+        return true;
+    }
+
+    // /proc/version probe for shells that strip the environment.
+    match read_proc_version() {
+        Some(content) => {
+            let lower = content.to_lowercase();
+            lower.contains("microsoft") || lower.contains("wsl")
+        }
+        None => false,
+    }
+}
+
+fn detect_wsl() -> bool {
+    if !cfg!(target_os = "linux") {
+        return false;
+    }
+    let distro = std::env::var("WSL_DISTRO_NAME").ok();
+    let interop = std::env::var("WSL_INTEROP").ok();
+    detect_wsl_from(distro.as_deref(), interop.as_deref(), || {
+        std::fs::read_to_string("/proc/version").ok()
+    })
+}
+
+/// Whether the current process is running inside WSL.
+///
+/// The result is cached because it cannot change within a process lifetime.
+pub fn is_wsl() -> bool {
+    let mut cached = CACHED_IS_WSL
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Some(value) = *cached {
+        return value;
+    }
+    let value = detect_wsl();
+    *cached = Some(value);
+    value
+}
+
+/// The WSL distro name (for example `Debian`), when WSL exposes it.
+///
+/// Returns `None` outside WSL or when unset/empty after trimming.
+pub fn get_wsl_distro_name() -> Option<String> {
+    if !is_wsl() {
+        return None;
+    }
+    let name = std::env::var("WSL_DISTRO_NAME").unwrap_or_default();
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// Clear the memoized [`is_wsl`] result.
+///
+/// Test seam — production code must not call this.
+#[doc(hidden)]
+pub fn reset_wsl_detection_cache_for_tests() {
+    let mut cached = CACHED_IS_WSL
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    *cached = None;
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/wsl.test.ts decision table; the platform-gated
+// public functions are exercised where the platform allows)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    fn env_variables_win_over_proc_version() {
+        assert!(detect_wsl_from(Some("Ubuntu"), None, || None));
+        assert!(detect_wsl_from(None, Some("/run/WSL/8_interop"), || None));
+        // Untrimmed length check: whitespace-only counts as set (TS parity).
+        assert!(detect_wsl_from(Some(" "), None, || None));
+    }
+
+    #[test]
+    fn falls_back_to_proc_version_matching() {
+        assert!(detect_wsl_from(None, None, || Some(
+            "Linux version 5.15.90.1-microsoft-standard-WSL2".to_string()
+        )));
+        assert!(detect_wsl_from(None, None, || Some(
+            "Linux version 6.6.0-WSL2-custom".to_string()
+        )));
+        assert!(!detect_wsl_from(None, None, || Some(
+            "Linux version 6.1.0-13-amd64 (debian-kernel@lists.debian.org)".to_string()
+        )));
+    }
+
+    #[test]
+    fn proc_version_read_failure_means_not_wsl() {
+        assert!(!detect_wsl_from(None, None, || None));
+    }
+
+    #[test]
+    fn empty_env_values_do_not_trigger_detection() {
+        assert!(!detect_wsl_from(Some(""), Some(""), || None));
+    }
+
+    #[cfg(not(target_os = "linux"))]
+    #[test]
+    #[serial(wsl)]
+    fn is_wsl_is_false_on_non_linux_platforms_and_memoizes() {
+        reset_wsl_detection_cache_for_tests();
+        assert!(!is_wsl());
+        // Second call served from the cache.
+        assert!(!is_wsl());
+        assert_eq!(get_wsl_distro_name(), None);
+        reset_wsl_detection_cache_for_tests();
+    }
+
+    #[test]
+    #[serial(wsl)]
+    fn reset_seam_clears_the_memoized_value() {
+        reset_wsl_detection_cache_for_tests();
+        let first = is_wsl();
+        reset_wsl_detection_cache_for_tests();
+        let second = is_wsl();
+        assert_eq!(first, second);
+        reset_wsl_detection_cache_for_tests();
+    }
+}
diff --git a/crates/manager/Cargo.toml b/crates/manager/Cargo.toml
new file mode 100644
index 000000000..c89aa83d5
--- /dev/null
+++ b/crates/manager/Cargo.toml
@@ -0,0 +1,39 @@
+[package]
+name = "cma-manager"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-storage = { path = "../storage" }
+cma-auth = { path = "../auth" }
+cma-accounts = { path = "../accounts" }
+cma-rotation = { path = "../rotation" }
+cma-request = { path = "../request" }
+cma-quota = { path = "../quota" }
+cma-usage = { path = "../usage" }
+cma-cli-mirror = { path = "../climirror" }
+cma-runtime = { path = "../runtime" }
+cma-tui = { path = "../tui" }
+serde.workspace = true
+serde_json.workspace = true
+clap.workspace = true
+tokio.workspace = true
+chrono.workspace = true
+sha2.workspace = true
+reqwest.workspace = true
+uuid.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/manager/src/commands/account.rs b/crates/manager/src/commands/account.rs
new file mode 100644
index 000000000..8d9e736d4
--- /dev/null
+++ b/crates/manager/src/commands/account.rs
@@ -0,0 +1,513 @@
+//! Port of `lib/codex-manager/commands/account.ts`.
+//!
+//! `account tag|untag|weight|pause|unpause|drain|undrain|note|policy list` —
+//! per-account policy management over the shared (non-project) pool.
+
+use cma_accounts::account_policy::{
+    AccountPolicyStore, get_account_policy_key, load_account_policy_store,
+    normalize_account_policy_tag, save_account_policy_store, upsert_account_policy,
+};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use serde_json::{Map, Value, json};
+
+use crate::dispatcher::{CliOut, js_number, js_number_string, js_parse_float, js_slice_utf16};
+
+fn print_account_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth account tag <index> <tag>",
+            "  codex-multi-auth account untag <index> <tag>",
+            "  codex-multi-auth account weight <index> <0..10>",
+            "  codex-multi-auth account pause|unpause|drain|undrain <index>",
+            "  codex-multi-auth account note <index> <text>",
+            "  codex-multi-auth account policy list [--json]",
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `parseAccountIndex` — `/^\d+$/`, parseInt, safe integer `> 0`,
+/// converted to 0-based (spec 08 gotcha 13: `"1.5"`/`"2abc"` rejected).
+pub fn parse_account_index(value: Option<&str>) -> Option<usize> {
+    let value = value?;
+    if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) {
+        return None;
+    }
+    let parsed: i64 = value.parse().ok()?;
+    if parsed > 9_007_199_254_740_991 || parsed <= 0 {
+        return None;
+    }
+    Some((parsed - 1) as usize)
+}
+
+/// TS `policySummary(store, storage)` — one JSON object per stored account
+/// (key order: index, label, accountKey, tags, weight, paused, drained,
+/// note).
+pub fn policy_summary(store: &AccountPolicyStore, storage: Option<&AccountStorageV3>) -> Vec<Value> {
+    let accounts = storage.map(|s| s.accounts.as_slice()).unwrap_or(&[]);
+    accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let account_key = get_account_policy_key(account, index);
+            let policy = store.get(&account_key);
+            let mut object = Map::new();
+            object.insert("index".to_string(), Value::from(index as i64 + 1));
+            object.insert(
+                "label".to_string(),
+                Value::String(format!("Account {}", index + 1)),
+            );
+            object.insert("accountKey".to_string(), Value::String(account_key));
+            object.insert(
+                "tags".to_string(),
+                Value::Array(
+                    policy
+                        .map(|p| p.tags.iter().map(|t| Value::String(t.clone())).collect())
+                        .unwrap_or_default(),
+                ),
+            );
+            object.insert(
+                "weight".to_string(),
+                js_number(policy.map(|p| p.weight).unwrap_or(1.0)),
+            );
+            object.insert(
+                "paused".to_string(),
+                Value::Bool(policy.map(|p| p.paused).unwrap_or(false)),
+            );
+            object.insert(
+                "drained".to_string(),
+                Value::Bool(policy.map(|p| p.drained).unwrap_or(false)),
+            );
+            object.insert(
+                "note".to_string(),
+                policy
+                    .and_then(|p| p.note.clone())
+                    .map(Value::String)
+                    .unwrap_or(Value::Null),
+            );
+            Value::Object(object)
+        })
+        .collect()
+}
+
+/// Text line for one `account policy list` entry:
+/// `"{index}. {label} | weight=N[ | paused][ | drained][ | tags=a,b][ | note]"`.
+pub fn policy_list_line(entry: &Value) -> String {
+    let mut markers: Vec<String> = Vec::new();
+    let weight = entry["weight"].as_f64().unwrap_or(1.0);
+    markers.push(format!("weight={}", js_number_string(weight)));
+    if entry["paused"].as_bool() == Some(true) {
+        markers.push("paused".to_string());
+    }
+    if entry["drained"].as_bool() == Some(true) {
+        markers.push("drained".to_string());
+    }
+    let tags: Vec<&str> = entry["tags"]
+        .as_array()
+        .map(|list| list.iter().filter_map(Value::as_str).collect())
+        .unwrap_or_default();
+    if !tags.is_empty() {
+        markers.push(format!("tags={}", tags.join(",")));
+    }
+    if entry["note"].as_str().is_some_and(|note| !note.is_empty()) {
+        markers.push("note".to_string());
+    }
+    format!(
+        "{}. {} | {}",
+        entry["index"],
+        entry["label"].as_str().unwrap_or(""),
+        markers.join(" | ")
+    )
+}
+
+/// TS `runAccountCommand(args, deps)`.
+///
+/// Deviation note: policy-store save failures (which would crash the TS
+/// process) print the error on stderr and exit 1.
+pub async fn run_account_command(args: &[String], out: &mut CliOut) -> i32 {
+    // JS falsiness: TS gates the help path on `!command`, so an EMPTY-STRING
+    // first argv token (`account ""`, e.g. a scripted empty expansion) prints
+    // usage and exits 0 exactly like a missing subcommand.
+    let command = args
+        .first()
+        .map(String::as_str)
+        .filter(|command| !command.is_empty());
+    let rest: Vec<String> = if args.len() > 1 {
+        args[1..].to_vec()
+    } else {
+        Vec::new()
+    };
+    let Some(command) = command else {
+        print_account_usage(out);
+        return 0;
+    };
+    if command == "--help" || command == "-h" {
+        print_account_usage(out);
+        return 0;
+    }
+
+    cma_storage::facade::set_storage_path(None);
+    let storage: Option<AccountStorageV3> = cma_storage::load::load_accounts()
+        .await
+        .map(|loaded| loaded.storage);
+    let mut store = load_account_policy_store().await;
+
+    if command == "policy" {
+        let subcommand = rest.first().map(String::as_str);
+        let policy_args: Vec<String> = if rest.len() > 1 {
+            rest[1..].to_vec()
+        } else {
+            Vec::new()
+        };
+        if subcommand != Some("list") {
+            out.error(format!(
+                "Unknown account policy command: {}",
+                subcommand.unwrap_or("(missing)")
+            ));
+            return 1;
+        }
+        if let Some(unknown) = policy_args
+            .iter()
+            .find(|arg| arg.as_str() != "--json" && arg.as_str() != "-j")
+        {
+            out.error(format!("Unknown account policy list option: {unknown}"));
+            return 1;
+        }
+        let accounts = policy_summary(&store, storage.as_ref());
+        if policy_args
+            .iter()
+            .any(|arg| arg == "--json" || arg == "-j")
+        {
+            out.info(stringify_pretty2(&json!({
+                "command": "account policy list",
+                "accounts": accounts,
+            })));
+            return 0;
+        }
+        if accounts.is_empty() {
+            out.info("No accounts configured.");
+            return 0;
+        }
+        for entry in &accounts {
+            out.info(policy_list_line(entry));
+        }
+        return 0;
+    }
+
+    let account_index = parse_account_index(rest.first().map(String::as_str));
+    let resolved = match (&storage, account_index) {
+        (Some(storage), Some(index)) if index < storage.accounts.len() => {
+            Some((index, &storage.accounts[index]))
+        }
+        _ => None,
+    };
+    let Some((index, account)) = resolved else {
+        out.error("Account index is required and must reference a configured account.");
+        return 1;
+    };
+    let account_key = get_account_policy_key(account, index);
+    let now = cma_core::utils::now_ms();
+
+    if command == "tag" || command == "untag" {
+        let tag = normalize_account_policy_tag(rest.get(1).map(String::as_str).unwrap_or(""));
+        let Some(tag) = tag else {
+            out.error(format!("{command} requires a tag value."));
+            return 1;
+        };
+        let is_tag = command == "tag";
+        let policy = upsert_account_policy(
+            &mut store,
+            &account_key,
+            |next| {
+                if is_tag && !next.tags.contains(&tag) {
+                    next.tags.push(tag.clone());
+                }
+                if !is_tag {
+                    next.tags.retain(|existing| existing != &tag);
+                }
+            },
+            now,
+        );
+        if let Err(error) = save_account_policy_store(&store).await {
+            out.error(error.to_string());
+            return 1;
+        }
+        let joined = policy.tags.join(",");
+        out.info(format!(
+            "{} account {}: {}",
+            if is_tag { "Tagged" } else { "Removed tag from" },
+            index + 1,
+            if joined.is_empty() { "none" } else { &joined }
+        ));
+        return 0;
+    }
+
+    if command == "weight" {
+        let weight = match rest.get(1) {
+            Some(value) => js_parse_float(value),
+            None => f64::NAN,
+        };
+        if !weight.is_finite() || !(0.0..=10.0).contains(&weight) {
+            out.error("weight requires a number from 0 to 10.");
+            return 1;
+        }
+        upsert_account_policy(
+            &mut store,
+            &account_key,
+            |next| {
+                next.weight = weight;
+            },
+            now,
+        );
+        if let Err(error) = save_account_policy_store(&store).await {
+            out.error(error.to_string());
+            return 1;
+        }
+        out.info(format!(
+            "Set account {} weight to {}.",
+            index + 1,
+            js_number_string(weight)
+        ));
+        return 0;
+    }
+
+    if matches!(command, "pause" | "unpause" | "drain" | "undrain") {
+        upsert_account_policy(
+            &mut store,
+            &account_key,
+            |next| match command {
+                "pause" => next.paused = true,
+                "unpause" => next.paused = false,
+                "drain" => next.drained = true,
+                _ => next.drained = false,
+            },
+            now,
+        );
+        if let Err(error) = save_account_policy_store(&store).await {
+            out.error(error.to_string());
+            return 1;
+        }
+        out.info(format!("Updated account {}: {command}.", index + 1));
+        return 0;
+    }
+
+    if command == "note" {
+        let note = if rest.len() > 1 {
+            rest[1..].join(" ").trim().to_string()
+        } else {
+            String::new()
+        };
+        upsert_account_policy(
+            &mut store,
+            &account_key,
+            |next| {
+                next.note = if note.is_empty() {
+                    None
+                } else {
+                    Some(js_slice_utf16(&note, 500))
+                };
+            },
+            now,
+        );
+        if let Err(error) = save_account_policy_store(&store).await {
+            out.error(error.to_string());
+            return 1;
+        }
+        out.info(format!("Updated account {} note.", index + 1));
+        return 0;
+    }
+
+    out.error(format!("Unknown account command: {command}"));
+    print_account_usage(out);
+    1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn account(email: &str) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(format!("rt-{email}"), 1, 0);
+        account.email = Some(email.to_string());
+        account
+    }
+
+    async fn seed_two_accounts() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("a@example.com"));
+        storage.accounts.push(account("b@example.com"));
+        cma_storage::facade::set_storage_path(None);
+        cma_storage::save::save_accounts(&storage).await.unwrap();
+    }
+
+    // Port of test/codex-manager-account-command.test.ts index validation.
+    #[test]
+    fn parse_account_index_is_digit_only_and_one_based() {
+        assert_eq!(parse_account_index(Some("1")), Some(0));
+        assert_eq!(parse_account_index(Some("12")), Some(11));
+        assert_eq!(parse_account_index(Some("0")), None);
+        assert_eq!(parse_account_index(Some("1.5")), None);
+        assert_eq!(parse_account_index(Some("2abc")), None);
+        assert_eq!(parse_account_index(Some("-1")), None);
+        assert_eq!(parse_account_index(Some("")), None);
+        assert_eq!(parse_account_index(None), None);
+        assert_eq!(parse_account_index(Some("9007199254740993")), None);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_command_prints_usage() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_account_command(&[], &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().starts_with("Usage:"));
+
+        // JS falsiness parity: `account ""` (empty argv expansion) is the
+        // help path too — usage on stdout, exit 0, never the index error.
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&[""]), &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().starts_with("Usage:"));
+        assert!(out.error_text().is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn policy_list_rejects_unknown_subcommand_and_option() {
+        let _sandbox = EnvSandbox::new();
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["policy", "show"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown account policy command: show");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["policy"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown account policy command: (missing)");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["policy", "list", "--bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown account policy list option: --bogus");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn policy_list_reports_no_accounts() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["policy", "list"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "No accounts configured.");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn invalid_index_error_is_exact() {
+        let _sandbox = EnvSandbox::new();
+        for bad in [&["tag", "abc", "x"][..], &["tag", "0", "x"], &["tag", "9", "x"]] {
+            let mut out = CliOut::capture();
+            let code = run_account_command(&args(bad), &mut out).await;
+            assert_eq!(code, 1);
+            assert_eq!(
+                out.error_text(),
+                "Account index is required and must reference a configured account."
+            );
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn tag_untag_weight_pause_note_flow() {
+        let _sandbox = EnvSandbox::new();
+        seed_two_accounts().await;
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["tag", "1", "fast"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Tagged account 1: fast");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["untag", "1", "fast"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Removed tag from account 1: none");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["tag", "1"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "tag requires a tag value.");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["weight", "1", "2.5"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Set account 1 weight to 2.5.");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["weight", "1", "11"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "weight requires a number from 0 to 10.");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["pause", "2"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Updated account 2: pause.");
+
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["note", "1", "hello", "world"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Updated account 1 note.");
+
+        // policy list reflects the mutations (weight 2.5 kept as float,
+        // account 2 paused).
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["policy", "list", "--json"]), &mut out).await;
+        assert_eq!(code, 0);
+        let payload: serde_json::Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["command"], "account policy list");
+        assert_eq!(payload["accounts"][0]["weight"], 2.5);
+        assert_eq!(payload["accounts"][0]["note"], "hello world");
+        assert_eq!(payload["accounts"][1]["paused"], true);
+        assert_eq!(payload["accounts"][1]["weight"], 1);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn unknown_command_prints_error_and_usage() {
+        let _sandbox = EnvSandbox::new();
+        seed_two_accounts().await;
+        let mut out = CliOut::capture();
+        let code = run_account_command(&args(&["boost", "1"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown account command: boost");
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[test]
+    fn policy_list_line_matches_ts_marker_order() {
+        let entry = serde_json::json!({
+            "index": 3,
+            "label": "Account 3",
+            "accountKey": "sha256:x",
+            "tags": ["fast", "eu"],
+            "weight": 2.0,
+            "paused": true,
+            "drained": false,
+            "note": "hi",
+        });
+        assert_eq!(
+            policy_list_line(&entry),
+            "3. Account 3 | weight=2 | paused | tags=fast,eu | note"
+        );
+    }
+}
diff --git a/crates/manager/src/commands/best.rs b/crates/manager/src/commands/best.rs
new file mode 100644
index 000000000..521aaf91a
--- /dev/null
+++ b/crates/manager/src/commands/best.rs
@@ -0,0 +1,537 @@
+//! Port of `lib/codex-manager/commands/best.ts`.
+//!
+//! `best [--live] [--json] [--model <model>]` — pick the healthiest account
+//! via forecast scoring and switch to it (clearing any manual pin).
+//!
+//! Divergences that are CONTRACT (spec 08 gotchas 2/4/5/6/7):
+//! - probe-refresh persistence uses PLAIN `save_accounts` (no retry wrapper);
+//! - `--model` without `--live` is an error (forecast/report accept it);
+//! - zero accounts exits 1 (forecast exits 0);
+//! - in the already-on-best branch `lastUsed` is stamped only when a probe
+//!   refresh already dirtied storage;
+//! - `pinCleared` reflects the pin captured BEFORE the switch persists.
+
+use cma_accounts::manager_persistence::{AccountLabelSource, format_account_label};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3, PersistedSwitchReason};
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::forecast::{
+    ForecastAccountInput, evaluate_forecast_accounts, recommend_forecast_account,
+};
+use cma_quota::probe::{
+    CodexQuotaSnapshot, ProbeCodexQuotaOptions, describe_codex_probe_failure,
+    fetch_codex_quota_snapshot,
+};
+use cma_request::model_map::resolve_normalized_model;
+use serde_json::{Map, Value};
+use std::collections::{HashMap, HashSet};
+
+use crate::dispatcher::CliOut;
+use crate::help::{BestCliOptions, best_usage_text};
+
+/// TS commands/best.ts `parseBestArgs` — NO `--help` branch (the runner
+/// pre-checks help before parsing).
+pub fn parse_best_args(args: &[String]) -> Result<BestCliOptions, String> {
+    let mut options = BestCliOptions::default();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--live" || arg == "-l" {
+            options.live = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--json" || arg == "-j" {
+            options.json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--model" || arg == "-m" {
+            let value = args.get(i + 1).map(|v| v.trim().to_string());
+            match value {
+                Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                    options.model = v;
+                    options.model_provided = true;
+                    i += 2;
+                    continue;
+                }
+                _ => return Err("Missing value for --model".to_string()),
+            }
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                return Err("Missing value for --model".to_string());
+            }
+            options.model = value.to_string();
+            options.model_provided = true;
+            i += 1;
+            continue;
+        }
+        return Err(format!("Unknown option: {arg}"));
+    }
+
+    Ok(options)
+}
+
+fn label_of(storage: &AccountStorageV3, index: usize) -> String {
+    format_account_label(
+        storage
+            .accounts
+            .get(index)
+            .map(|account| account as &dyn AccountLabelSource),
+        index,
+    )
+}
+
+fn print_probe_notes(probe_errors: &[String], out: &mut CliOut) {
+    if probe_errors.is_empty() {
+        return;
+    }
+    out.info(format!("Live check notes ({}):", probe_errors.len()));
+    for error in probe_errors {
+        out.info(format!("  - {error}"));
+    }
+}
+
+fn with_probe_errors(mut object: Map<String, Value>, probe_errors: &[String]) -> Value {
+    if !probe_errors.is_empty() {
+        object.insert(
+            "probeErrors".to_string(),
+            Value::Array(
+                probe_errors
+                    .iter()
+                    .map(|error| Value::String(error.clone()))
+                    .collect(),
+            ),
+        );
+    }
+    Value::Object(object)
+}
+
+/// TS `runBestCommand(args, deps)`.
+///
+/// Deviation note: a probe-persist `saveAccounts` failure (uncaught crash in
+/// TS) prints the storage error on stderr and exits 1.
+pub async fn run_best_command(args: &[String], out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        out.info(best_usage_text());
+        return 0;
+    }
+
+    let options = match parse_best_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            out.info(best_usage_text());
+            return 1;
+        }
+    };
+    let trimmed_model = options.model.trim();
+    let probe_model = resolve_normalized_model(Some(if trimmed_model.is_empty() {
+        crate::help::DEFAULT_LIVE_PROBE_MODEL
+    } else {
+        trimmed_model
+    }));
+    if options.model_provided && !options.live {
+        out.error("--model requires --live for codex-multi-auth best");
+        out.info(best_usage_text());
+        return 1;
+    }
+
+    cma_storage::facade::set_storage_path(None);
+    let mut storage: AccountStorageV3 = match cma_storage::load::load_accounts().await {
+        Some(loaded) if !loaded.storage.accounts.is_empty() => loaded.storage,
+        _ => {
+            if options.json {
+                out.info(stringify_pretty2(
+                    &serde_json::json!({ "error": "No accounts configured." }),
+                ));
+            } else {
+                out.info("No accounts configured.");
+            }
+            return 1;
+        }
+    };
+
+    let now = cma_core::utils::now_ms();
+    let mut refresh_failures: HashMap<usize, TokenFailure> = HashMap::new();
+    let mut live_quota_by_index: HashMap<usize, CodexQuotaSnapshot> = HashMap::new();
+    let mut probe_id_token_by_index: HashMap<usize, String> = HashMap::new();
+    let mut probe_refreshed_indices: HashSet<usize> = HashSet::new();
+    let mut probe_errors: Vec<String> = Vec::new();
+    let mut changed = false;
+
+    for i in 0..storage.accounts.len() {
+        if !options.live || storage.accounts[i].enabled == Some(false) {
+            continue;
+        }
+
+        let mut probe_access_token = storage.accounts[i].access_token.clone();
+        let mut probe_account_id = storage.accounts[i].account_id.clone().or_else(|| {
+            extract_account_id(storage.accounts[i].access_token.as_deref())
+        });
+        if !crate::login::account_credentials::has_usable_access_token(&storage.accounts[i], now) {
+            let refresh_result =
+                cma_auth::refresh_queue::queued_refresh(&storage.accounts[i].refresh_token).await;
+            let success = match refresh_result {
+                TokenResult::Success(success) => success,
+                TokenResult::Failed(failure) => {
+                    let mut normalized = failure.clone();
+                    normalized.message =
+                        Some(crate::formatters::text_style::normalize_failure_detail(
+                            failure.message.as_deref(),
+                            failure.reason.map(|reason| reason.as_str()),
+                        ));
+                    refresh_failures.insert(i, normalized);
+                    continue;
+                }
+            };
+
+            let refreshed_email = sanitize_email(
+                extract_account_email(Some(&success.access), success.id_token.as_deref())
+                    .as_deref(),
+            );
+            let refreshed_account_id = extract_account_id(Some(&success.access));
+            let account = &mut storage.accounts[i];
+            let previous_refresh_token = account.refresh_token.clone();
+            let previous_access_token = account.access_token.clone();
+            let previous_expires_at = account.expires_at;
+            let previous_email = account.email.clone();
+            let previous_account_id = account.account_id.clone();
+            let previous_account_id_source = account.account_id_source;
+            account.refresh_token = success.refresh.clone();
+            account.access_token = Some(success.access.clone());
+            account.expires_at = Some(success.expires);
+            if let Some(email) = &refreshed_email {
+                account.email = Some(email.clone());
+            }
+            if let Some(account_id) = &refreshed_account_id {
+                account.account_id = Some(account_id.clone());
+                account.account_id_source = Some(AccountIdSource::Token);
+            }
+            changed = changed
+                || previous_refresh_token != account.refresh_token
+                || previous_access_token != account.access_token
+                || previous_expires_at != account.expires_at
+                || previous_email != account.email
+                || previous_account_id != account.account_id
+                || previous_account_id_source != account.account_id_source;
+            if let Some(id_token) = &success.id_token {
+                probe_id_token_by_index.insert(i, id_token.clone());
+            }
+            probe_refreshed_indices.insert(i);
+
+            probe_access_token = account.access_token.clone();
+            probe_account_id = account.account_id.clone().or(refreshed_account_id);
+        }
+
+        let (Some(probe_access_token), Some(probe_account_id)) =
+            (probe_access_token, probe_account_id)
+        else {
+            probe_errors.push(format!(
+                "{}: missing accountId for live probe",
+                label_of(&storage, i)
+            ));
+            continue;
+        };
+
+        match fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+            account_id: probe_account_id,
+            access_token: probe_access_token,
+            model: Some(probe_model.to_string()),
+            ..Default::default()
+        })
+        .await
+        {
+            Ok(live_quota) => {
+                live_quota_by_index.insert(i, live_quota);
+            }
+            Err(error) => {
+                let message = describe_codex_probe_failure(
+                    &error,
+                    Some(&|raw: &str| {
+                        crate::formatters::text_style::normalize_failure_detail(Some(raw), None)
+                    }),
+                );
+                probe_errors.push(format!("{}: {message}", label_of(&storage, i)));
+            }
+        }
+    }
+
+    let active_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    let forecast_inputs: Vec<ForecastAccountInput<'_>> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| ForecastAccountInput {
+            index,
+            account,
+            is_current: index == active_index,
+            now,
+            refresh_failure: refresh_failures.get(&index),
+            live_quota: live_quota_by_index.get(&index),
+            quota_cache: None,
+            all_accounts: None,
+            runtime_overlay: None,
+        })
+        .collect();
+    let forecast_results = evaluate_forecast_accounts(&forecast_inputs);
+    let recommendation = recommend_forecast_account(&forecast_results);
+    drop(forecast_inputs);
+
+    let Some(best_index) = recommendation.recommended_index else {
+        // Persist probe changes (plain saveAccounts — spec 08 gotcha 2).
+        if changed
+            && let Err(error) = cma_storage::save::save_accounts(&storage).await
+        {
+            out.error(error.message().to_string());
+            return 1;
+        }
+        if options.json {
+            let mut object = Map::new();
+            object.insert(
+                "error".to_string(),
+                Value::String(recommendation.reason.clone()),
+            );
+            out.info(stringify_pretty2(&with_probe_errors(object, &probe_errors)));
+        } else {
+            out.info(format!(
+                "No best account available: {}",
+                recommendation.reason
+            ));
+            print_probe_notes(&probe_errors, out);
+        }
+        return 1;
+    };
+
+    if best_index >= storage.accounts.len() {
+        if changed
+            && let Err(error) = cma_storage::save::save_accounts(&storage).await
+        {
+            out.error(error.message().to_string());
+            return 1;
+        }
+        if options.json {
+            out.info(stringify_pretty2(
+                &serde_json::json!({ "error": "Best account not found." }),
+            ));
+        } else {
+            out.info("Best account not found.");
+        }
+        return 1;
+    }
+
+    let current_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    if current_index == best_index {
+        let should_sync_current_best = probe_refreshed_indices.contains(&best_index)
+            || probe_id_token_by_index.contains_key(&best_index);
+        let mut already_best_synced: Option<bool> = None;
+        // lastUsed is stamped only inside the save callback, i.e. only when a
+        // probe refresh already dirtied storage (spec 08 gotcha 6).
+        if changed {
+            storage.accounts[best_index].last_used = now;
+            if let Err(error) = cma_storage::save::save_accounts(&storage).await {
+                out.error(error.message().to_string());
+                return 1;
+            }
+        }
+        let best_account = &storage.accounts[best_index];
+        let best_label = label_of(&storage, best_index);
+        if should_sync_current_best {
+            let synced = cma_cli_mirror::writer::set_codex_cli_active_selection(
+                &cma_cli_mirror::writer::ActiveSelection {
+                    account_id: best_account.account_id.clone(),
+                    email: best_account.email.clone(),
+                    access_token: best_account.access_token.clone(),
+                    refresh_token: Some(best_account.refresh_token.clone()),
+                    expires_at: best_account.expires_at.map(|v| v as f64),
+                    id_token: probe_id_token_by_index.get(&best_index).cloned(),
+                },
+            )
+            .await;
+            already_best_synced = Some(synced);
+            if !synced && !options.json {
+                out.warn(
+                    "Codex auth sync did not complete. Multi-auth routing will still use this account.",
+                );
+            }
+        }
+        if options.json {
+            let mut object = Map::new();
+            object.insert(
+                "message".to_string(),
+                Value::String(format!("Already on best account: {best_label}")),
+            );
+            object.insert(
+                "accountIndex".to_string(),
+                Value::from(best_index as i64 + 1),
+            );
+            object.insert(
+                "reason".to_string(),
+                Value::String(recommendation.reason.clone()),
+            );
+            if let Some(synced) = already_best_synced {
+                object.insert("synced".to_string(), Value::Bool(synced));
+            }
+            out.info(stringify_pretty2(&with_probe_errors(object, &probe_errors)));
+        } else {
+            out.info(format!(
+                "Already on best account {}: {best_label}",
+                best_index + 1
+            ));
+            out.info(format!("Reason: {}", recommendation.reason));
+            print_probe_notes(&probe_errors, out);
+        }
+        return 0;
+    }
+
+    let parsed = best_index as i64 + 1;
+    let prior_pin = storage.pinned_account_index;
+    let outcome = crate::login::persist_selected::persist_and_sync_selected_account(
+        crate::login::persist_selected::PersistSelectedAccountParams {
+            storage: storage.clone(),
+            target_index: best_index,
+            parsed,
+            switch_reason: PersistedSwitchReason::Best,
+            initial_sync_id_token: probe_id_token_by_index.get(&best_index).cloned(),
+            preserve_active_index_by_family: false,
+            set_pin: false,
+            clear_pin: true,
+            bump_affinity_generation: true,
+        },
+    )
+    .await;
+    let pin_was_cleared = prior_pin.is_some();
+    let best_label = label_of(&storage, best_index);
+
+    if options.json {
+        let mut object = Map::new();
+        object.insert(
+            "message".to_string(),
+            Value::String(format!("Switched to best account: {best_label}")),
+        );
+        object.insert("accountIndex".to_string(), Value::from(parsed));
+        object.insert(
+            "reason".to_string(),
+            Value::String(recommendation.reason.clone()),
+        );
+        object.insert("synced".to_string(), Value::Bool(outcome.synced));
+        object.insert("wasDisabled".to_string(), Value::Bool(outcome.was_disabled));
+        if pin_was_cleared {
+            object.insert("pinCleared".to_string(), Value::Bool(true));
+        }
+        out.info(stringify_pretty2(&with_probe_errors(object, &probe_errors)));
+    } else {
+        out.info(format!(
+            "Switched to best account {parsed}: {best_label}{}{}",
+            if outcome.was_disabled {
+                " (re-enabled)"
+            } else {
+                ""
+            },
+            if pin_was_cleared {
+                " (manual pin cleared)"
+            } else {
+                ""
+            }
+        ));
+        out.info(format!("Reason: {}", recommendation.reason));
+        print_probe_notes(&probe_errors, out);
+        if !outcome.synced {
+            out.warn(
+                "Codex auth sync did not complete. Multi-auth routing will still use this account.",
+            );
+        }
+    }
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    // Port of test/codex-manager-best-command.test.ts (non-live surface).
+
+    #[test]
+    fn parse_best_args_has_no_help_branch() {
+        // The command copy of the parser treats --help as an unknown option;
+        // the runner pre-checks help before parsing.
+        assert_eq!(
+            parse_best_args(&args(&["--help"])),
+            Err("Unknown option: --help".to_string())
+        );
+        let parsed = parse_best_args(&args(&["--live", "-j"])).unwrap();
+        assert!(parsed.live);
+        assert!(parsed.json);
+        assert!(!parsed.model_provided);
+        assert_eq!(parsed.model, crate::help::DEFAULT_LIVE_PROBE_MODEL);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn help_prints_usage_and_exits_zero() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_best_command(&args(&["--help"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn model_without_live_is_an_error() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_best_command(&args(&["--model", "gpt-5.5"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "--model requires --live for codex-multi-auth best"
+        );
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn parse_error_prints_message_then_usage() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_best_command(&args(&["--bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown option: --bogus");
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_accounts_exits_one_in_both_modes() {
+        let _sandbox = EnvSandbox::new();
+
+        let mut out = CliOut::capture();
+        let code = run_best_command(&[], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.info_text(), "No accounts configured.");
+
+        let mut out = CliOut::capture();
+        let code = run_best_command(&args(&["--json"]), &mut out).await;
+        assert_eq!(code, 1);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["error"], "No accounts configured.");
+    }
+}
diff --git a/crates/manager/src/commands/bridge.rs b/crates/manager/src/commands/bridge.rs
new file mode 100644
index 000000000..ecf497288
--- /dev/null
+++ b/crates/manager/src/commands/bridge.rs
@@ -0,0 +1,363 @@
+//! Port of `lib/codex-manager/commands/bridge.ts`.
+//!
+//! `bridge token create|list|rotate|revoke` — manages local bridge client
+//! tokens. Public token records never expose the stored hash.
+
+use cma_auth::local_client_tokens::{
+    LocalClientTokenRecord, add_local_client_token, load_local_client_token_store,
+    revoke_local_client_token, rotate_local_client_token,
+};
+use cma_core::json_io::stringify_pretty2;
+use serde_json::{Value, json};
+
+use crate::dispatcher::{CliOut, js_number};
+
+fn print_bridge_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth bridge token create [--label <label>] [--json]",
+            "  codex-multi-auth bridge token list [--json]",
+            "  codex-multi-auth bridge token rotate <id> [--json]",
+            "  codex-multi-auth bridge token revoke <id> [--json]",
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `publicTokenRecord(token)` — hashes never leave the store. Key order
+/// is the TS object literal order.
+pub fn public_token_record(token: &LocalClientTokenRecord) -> Value {
+    json!({
+        "id": token.id,
+        "label": token.label,
+        "prefix": token.prefix,
+        "createdAt": token.created_at,
+        "lastUsedAt": token.last_used_at.map(|v| js_number(v as f64)),
+        "revokedAt": token.revoked_at.map(|v| js_number(v as f64)),
+        "state": if token.revoked_at.is_none() { "active" } else { "revoked" },
+    })
+}
+
+fn consume_json_flag(args: &[String]) -> (bool, Vec<String>) {
+    let json = args.iter().any(|arg| arg == "--json" || arg == "-j");
+    let rest = args
+        .iter()
+        .filter(|arg| arg.as_str() != "--json" && arg.as_str() != "-j")
+        .cloned()
+        .collect();
+    (json, rest)
+}
+
+/// TS `parseLabel(args)` for `bridge token create`.
+fn parse_label(args: &[String]) -> Result<Option<String>, String> {
+    let mut label: Option<String> = None;
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--label" {
+            match args.get(i + 1) {
+                Some(value) if !value.is_empty() => {
+                    label = Some(value.clone());
+                    i += 2;
+                    continue;
+                }
+                _ => return Err("Missing value for --label".to_string()),
+            }
+        }
+        if let Some(value) = arg.strip_prefix("--label=") {
+            label = Some(value.to_string());
+            i += 1;
+            continue;
+        }
+        return Err(format!("Unknown bridge token option: {arg}"));
+    }
+    Ok(label)
+}
+
+/// TS `runBridgeCommand(args, deps)`.
+///
+/// Deviation note: local-token store IO failures (which would crash the TS
+/// process) print the error on stderr and exit 1.
+pub async fn run_bridge_command(args: &[String], out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_bridge_usage(out);
+        return 0;
+    }
+    let area = args.first().map(String::as_str);
+    let action = args.get(1).map(String::as_str);
+    let rest: Vec<String> = if args.len() > 2 {
+        args[2..].to_vec()
+    } else {
+        Vec::new()
+    };
+    if area != Some("token") {
+        out.error("Expected `codex-multi-auth bridge token ...`");
+        return 1;
+    }
+    match action {
+        Some("create") => {
+            let (json, action_args) = consume_json_flag(&rest);
+            let label = match parse_label(&action_args) {
+                Ok(label) => label,
+                Err(message) => {
+                    out.error(message);
+                    return 1;
+                }
+            };
+            let created = match add_local_client_token(label.as_deref(), None).await {
+                Ok(created) => created,
+                Err(error) => {
+                    out.error(error.to_string());
+                    return 1;
+                }
+            };
+            if json {
+                out.info(stringify_pretty2(&json!({
+                    "command": "bridge token create",
+                    "token": public_token_record(&created.record),
+                    "plainToken": created.plain_token,
+                })));
+                return 0;
+            }
+            out.info(format!("Token id: {}", created.record.id));
+            out.info(format!("Token prefix: {}", created.record.prefix));
+            out.info(format!("Token: {}", created.plain_token));
+            0
+        }
+        Some("list") => {
+            let (json, action_args) = consume_json_flag(&rest);
+            if !action_args.is_empty() {
+                out.error(format!(
+                    "Unknown bridge token list option: {}",
+                    action_args.first().map(String::as_str).unwrap_or("")
+                ));
+                return 1;
+            }
+            let store = load_local_client_token_store().await;
+            if json {
+                out.info(stringify_pretty2(&json!({
+                    "command": "bridge token list",
+                    "tokens": store.tokens.iter().map(public_token_record).collect::<Vec<_>>(),
+                })));
+                return 0;
+            }
+            if store.tokens.is_empty() {
+                out.info("No local bridge tokens configured.");
+                return 0;
+            }
+            for token in &store.tokens {
+                let state = if token.revoked_at.is_none() {
+                    "active"
+                } else {
+                    "revoked"
+                };
+                out.info(format!(
+                    "{} {} {} {}",
+                    token.id, token.prefix, token.label, state
+                ));
+            }
+            0
+        }
+        Some("rotate") => {
+            let (json, action_args) = consume_json_flag(&rest);
+            let Some(id) = action_args.first().filter(|id| !id.is_empty()) else {
+                out.error("Missing token id");
+                return 1;
+            };
+            if action_args.len() > 1 {
+                out.error(format!(
+                    "Unknown bridge token rotate option: {}",
+                    action_args.get(1).map(String::as_str).unwrap_or("")
+                ));
+                return 1;
+            }
+            let rotated = match rotate_local_client_token(id, None, None).await {
+                Ok(rotated) => rotated,
+                Err(error) => {
+                    out.error(error.to_string());
+                    return 1;
+                }
+            };
+            let Some(rotated) = rotated else {
+                out.error("Token not found or already revoked.");
+                return 1;
+            };
+            if json {
+                out.info(stringify_pretty2(&json!({
+                    "command": "bridge token rotate",
+                    "token": public_token_record(&rotated.record),
+                    "plainToken": rotated.plain_token,
+                })));
+                return 0;
+            }
+            out.info(format!("Token id: {}", rotated.record.id));
+            out.info(format!("Token prefix: {}", rotated.record.prefix));
+            out.info(format!("Token: {}", rotated.plain_token));
+            0
+        }
+        Some("revoke") => {
+            let (json, action_args) = consume_json_flag(&rest);
+            let Some(id) = action_args.first().filter(|id| !id.is_empty()) else {
+                out.error("Missing token id");
+                return 1;
+            };
+            if action_args.len() > 1 {
+                out.error(format!(
+                    "Unknown bridge token revoke option: {}",
+                    action_args.get(1).map(String::as_str).unwrap_or("")
+                ));
+                return 1;
+            }
+            let revoked = match revoke_local_client_token(id, None).await {
+                Ok(revoked) => revoked,
+                Err(error) => {
+                    out.error(error.to_string());
+                    return 1;
+                }
+            };
+            if !revoked {
+                out.error("Token not found or already revoked.");
+                return 1;
+            }
+            if json {
+                out.info(stringify_pretty2(&json!({
+                    "command": "bridge token revoke",
+                    "id": id,
+                    "revoked": true,
+                })));
+                return 0;
+            }
+            out.info("Token revoked.");
+            0
+        }
+        other => {
+            out.error(format!(
+                "Unknown bridge token action: {}",
+                other.unwrap_or("")
+            ));
+            1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn public_token_record_never_exposes_the_hash() {
+        let record = LocalClientTokenRecord {
+            id: "id-1".to_string(),
+            label: "default".to_string(),
+            prefix: "cma_local_abc".to_string(),
+            token_hash: "sha256:deadbeef".to_string(),
+            created_at: 5,
+            last_used_at: None,
+            revoked_at: None,
+        };
+        let value = public_token_record(&record);
+        let text = serde_json::to_string(&value).unwrap();
+        assert!(!text.contains("deadbeef"));
+        assert!(!text.contains("tokenHash"));
+        assert_eq!(value["state"], "active");
+        assert_eq!(value["lastUsedAt"], serde_json::Value::Null);
+        assert_eq!(value["revokedAt"], serde_json::Value::Null);
+    }
+
+    #[tokio::test]
+    async fn requires_the_token_area() {
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["nope"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Expected `codex-multi-auth bridge token ...`");
+    }
+
+    #[tokio::test]
+    async fn rejects_unknown_create_option_and_missing_label_value() {
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "create", "--bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown bridge token option: --bogus");
+
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "create", "--label"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing value for --label");
+    }
+
+    #[tokio::test]
+    async fn rejects_missing_ids_and_unknown_action() {
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "rotate"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing token id");
+
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "revoke"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing token id");
+
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "smash"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown bridge token action: smash");
+
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown bridge token action: ");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn create_list_rotate_revoke_round_trip() {
+        let _sandbox = EnvSandbox::new();
+
+        // Empty list first.
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "list"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "No local bridge tokens configured.");
+
+        // Create with a label.
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(
+            &args(&["token", "create", "--label", "ci", "--json"]),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        let payload: serde_json::Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["command"], "bridge token create");
+        assert_eq!(payload["token"]["label"], "ci");
+        assert_eq!(payload["token"]["state"], "active");
+        let plain = payload["plainToken"].as_str().unwrap().to_string();
+        assert!(plain.starts_with("cma_local"));
+        let id = payload["token"]["id"].as_str().unwrap().to_string();
+
+        // Rotate it.
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "rotate", &id]), &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().starts_with("Token id: "));
+
+        // Rotating the (now revoked) old id again fails.
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "rotate", &id]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Token not found or already revoked.");
+
+        // Revoke unknown id fails with the same message.
+        let mut out = CliOut::capture();
+        let code = run_bridge_command(&args(&["token", "revoke", "nope"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Token not found or already revoked.");
+    }
+}
diff --git a/crates/manager/src/commands/budget.rs b/crates/manager/src/commands/budget.rs
new file mode 100644
index 000000000..aa8aaf949
--- /dev/null
+++ b/crates/manager/src/commands/budget.rs
@@ -0,0 +1,367 @@
+//! Port of `lib/codex-manager/commands/budget.ts`.
+//!
+//! `budget limit|check|list` — local budget guard limits over the usage
+//! ledger. `budget check` exit code equals the evaluation result in BOTH
+//! output modes (spec 08 gotcha 14).
+
+use cma_core::json_io::stringify_pretty2;
+use cma_quota::budget_guard::{
+    BudgetGuardStore, BudgetLimit, BudgetLimitInput, BudgetWindow, evaluate_budget_guard,
+    get_budget_window_start, load_budget_guard_store, normalize_budget_key,
+    save_budget_guard_store, upsert_budget_limit,
+};
+use cma_usage::ledger::summarize_usage_ledger;
+use cma_usage::types::{UsageSummaryGroupBy, UsageSummaryQuery};
+use serde_json::json;
+
+use crate::dispatcher::{CliOut, js_number_string, js_parse_float};
+
+fn print_budget_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth budget limit <key> --window <hour|day|week|month> [--requests N] [--tokens N] [--cost USD]",
+            "  codex-multi-auth budget check <key> [--json]",
+            "  codex-multi-auth budget list [--json]",
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `parsePositiveNumber` — `parseFloat`, finite, `> 0`.
+fn parse_positive_number(value: Option<&str>) -> Option<f64> {
+    let value = value?;
+    if value.is_empty() {
+        return None;
+    }
+    let parsed = js_parse_float(value);
+    if parsed.is_finite() && parsed > 0.0 {
+        Some(parsed)
+    } else {
+        None
+    }
+}
+
+fn format_cap(value: Option<f64>) -> String {
+    match value {
+        Some(v) => js_number_string(v),
+        None => "none".to_string(),
+    }
+}
+
+/// TS `runBudgetCommand(args, deps)`.
+///
+/// Deviation note: store-save / ledger-read IO failures (which would crash
+/// the TS process) print the error on stderr and exit 1.
+pub async fn run_budget_command(args: &[String], out: &mut CliOut) -> i32 {
+    let command = args.first().map(String::as_str);
+    let rest: Vec<String> = if args.len() > 1 {
+        args[1..].to_vec()
+    } else {
+        Vec::new()
+    };
+    let Some(command) = command else {
+        print_budget_usage(out);
+        return 0;
+    };
+    if command == "--help" || command == "-h" {
+        print_budget_usage(out);
+        return 0;
+    }
+    let mut store: BudgetGuardStore = load_budget_guard_store().await;
+    let now = cma_core::utils::now_ms();
+
+    if command == "list" {
+        let json = rest.iter().any(|arg| arg == "--json" || arg == "-j");
+        let mut limits: Vec<&BudgetLimit> = store.iter().map(|(_, limit)| limit).collect();
+        limits.sort_by(|a, b| a.key.cmp(&b.key));
+        if json {
+            out.info(stringify_pretty2(&json!({
+                "command": "budget list",
+                "limits": limits,
+            })));
+            return 0;
+        }
+        if limits.is_empty() {
+            out.info("No budget limits configured.");
+            return 0;
+        }
+        for limit in limits {
+            out.info(format!(
+                "{}: window={}, requests={}, tokens={}, cost={}",
+                limit.key,
+                limit.window.as_str(),
+                format_cap(limit.max_requests),
+                format_cap(limit.max_tokens),
+                format_cap(limit.max_cost_usd),
+            ));
+        }
+        return 0;
+    }
+
+    let key = normalize_budget_key(rest.first().map(String::as_str).unwrap_or(""));
+    let Some(key) = key else {
+        out.error("Budget key is required.");
+        return 1;
+    };
+
+    if command == "limit" {
+        let mut window: Option<BudgetWindow> = None;
+        let mut max_requests: Option<f64> = None;
+        let mut max_tokens: Option<f64> = None;
+        let mut max_cost_usd: Option<f64> = None;
+        let mut i = 1usize;
+        while i < rest.len() {
+            let arg = rest[i].as_str();
+            let value = rest.get(i + 1).map(String::as_str);
+            if arg == "--window" {
+                let parsed = value.and_then(BudgetWindow::parse);
+                let Some(parsed) = parsed else {
+                    out.error("--window must be hour, day, week, or month.");
+                    return 1;
+                };
+                window = Some(parsed);
+                i += 2;
+                continue;
+            }
+            if arg == "--requests" || arg == "--tokens" || arg == "--cost" {
+                let Some(parsed) = parse_positive_number(value) else {
+                    out.error(format!("{arg} requires a positive number."));
+                    return 1;
+                };
+                match arg {
+                    "--requests" => max_requests = Some(parsed),
+                    "--tokens" => max_tokens = Some(parsed),
+                    _ => max_cost_usd = Some(parsed),
+                }
+                i += 2;
+                continue;
+            }
+            out.error(format!("Unknown budget limit option: {arg}"));
+            return 1;
+        }
+        let Some(window) = window else {
+            out.error("--window is required.");
+            return 1;
+        };
+        if max_requests.is_none() && max_tokens.is_none() && max_cost_usd.is_none() {
+            out.error("At least one of --requests, --tokens, or --cost is required.");
+            return 1;
+        }
+        let limit = match upsert_budget_limit(
+            &mut store,
+            &BudgetLimitInput {
+                key: key.clone(),
+                window,
+                max_requests,
+                max_tokens,
+                max_cost_usd,
+            },
+            now,
+        ) {
+            Ok(limit) => limit,
+            Err(error) => {
+                out.error(error.message().to_string());
+                return 1;
+            }
+        };
+        if let Err(error) = save_budget_guard_store(&store).await {
+            out.error(error.to_string());
+            return 1;
+        }
+        out.info(format!(
+            "Saved budget limit {} ({}).",
+            limit.key,
+            limit.window.as_str()
+        ));
+        return 0;
+    }
+
+    if command == "check" {
+        // rest[0] is the budget key; a missing or flag-like first token (e.g.
+        // `budget check --json`) must not be consumed as the key name.
+        let first = rest.first().map(String::as_str).unwrap_or("");
+        if first.is_empty() || first.starts_with('-') {
+            out.error("Missing budget key. Usage: codex-multi-auth budget check <key> [--json]");
+            return 1;
+        }
+        let Some(limit) = store.get(&key).cloned() else {
+            out.error(format!("Budget limit not found: {key}"));
+            return 1;
+        };
+        let summary = match summarize_usage_ledger(&UsageSummaryQuery {
+            since: Some(get_budget_window_start(limit.window, now) as f64),
+            until: None,
+            include_archives: false,
+            by: Some(UsageSummaryGroupBy::Model),
+        })
+        .await
+        {
+            Ok(summary) => summary,
+            Err(error) => {
+                out.error(error.to_string());
+                return 1;
+            }
+        };
+        let evaluation = evaluate_budget_guard(&limit, &summary);
+        if rest.iter().any(|arg| arg == "--json" || arg == "-j") {
+            out.info(stringify_pretty2(&json!({
+                "command": "budget check",
+                "evaluation": evaluation,
+            })));
+            return if evaluation.allowed { 0 } else { 1 };
+        }
+        out.info(if evaluation.allowed {
+            format!("Budget {key} allows usage.")
+        } else {
+            format!("Budget {key} blocked: {}", evaluation.reasons.join("; "))
+        });
+        return if evaluation.allowed { 0 } else { 1 };
+    }
+
+    out.error(format!("Unknown budget command: {command}"));
+    print_budget_usage(out);
+    1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_command_prints_usage_and_exits_zero() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&[], &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn requires_a_budget_key() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["limit"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Budget key is required.");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn limit_flag_validation_matches_ts() {
+        let _sandbox = EnvSandbox::new();
+
+        let mut out = CliOut::capture();
+        let code =
+            run_budget_command(&args(&["limit", "team", "--window", "decade"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "--window must be hour, day, week, or month.");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(
+            &args(&["limit", "team", "--window", "day", "--requests", "0"]),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "--requests requires a positive number.");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(
+            &args(&["limit", "team", "--window", "day", "--bogus"]),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown budget limit option: --bogus");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["limit", "team", "--requests", "5"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "--window is required.");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["limit", "team", "--window", "day"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "At least one of --requests, --tokens, or --cost is required."
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn saves_lists_and_checks_a_limit() {
+        let _sandbox = EnvSandbox::new();
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(
+            &args(&["limit", "team", "--window", "day", "--requests", "5"]),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Saved budget limit team (day).");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["list"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(
+            out.info_text(),
+            "team: window=day, requests=5, tokens=none, cost=none"
+        );
+
+        // No usage recorded → allowed, exit 0 in both modes.
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["check", "team"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "Budget team allows usage.");
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["check", "team", "--json"]), &mut out).await;
+        assert_eq!(code, 0);
+        let payload: serde_json::Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["command"], "budget check");
+        assert_eq!(payload["evaluation"]["allowed"], true);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn check_guards_flag_like_and_missing_keys() {
+        let _sandbox = EnvSandbox::new();
+
+        // "--json" normalizes to a non-empty key, so the flag-like guard in
+        // the check branch fires (spec 08 gotcha 14), not the key-required one.
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["check", "--json"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "Missing budget key. Usage: codex-multi-auth budget check <key> [--json]"
+        );
+
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["check", "ghost"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Budget limit not found: ghost");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn unknown_command_prints_error_and_usage() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_budget_command(&args(&["explode", "team"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown budget command: explode");
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+}
diff --git a/crates/manager/src/commands/check.rs b/crates/manager/src/commands/check.rs
new file mode 100644
index 000000000..f85b3db09
--- /dev/null
+++ b/crates/manager/src/commands/check.rs
@@ -0,0 +1,45 @@
+//! Port of `lib/codex-manager/commands/check.ts` — `check` always runs a
+//! live-probe health check and always exits 0. Args are ignored entirely
+//! (spec 08 gotcha 24).
+
+use std::future::Future;
+
+use crate::dispatcher::CliOut;
+
+/// Seam mirroring TS `runCheckCommand({ runHealthCheck })` — the injected
+/// health check always receives `liveProbe: true` and the command always
+/// returns 0.
+pub async fn run_check_command_via<F, Fut>(run_health_check: F) -> i32
+where
+    F: FnOnce(bool) -> Fut,
+    Fut: Future<Output = ()>,
+{
+    run_health_check(true).await;
+    0
+}
+
+/// Production entry: delegates to the real health-check engine.
+pub async fn run_check_command(args: &[String], out: &mut CliOut) -> i32 {
+    let _ = (args, &out); // args are ignored entirely (TS parity)
+    run_check_command_via(crate::health_check::run_health_check).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    // Port of test/codex-manager-check-command.test.ts: runHealthCheck is
+    // invoked with liveProbe=true and the exit code is 0.
+    #[tokio::test]
+    async fn always_live_probes_and_returns_zero() {
+        let called_live = AtomicBool::new(false);
+        let code = run_check_command_via(|live_probe| {
+            called_live.store(live_probe, Ordering::SeqCst);
+            async {}
+        })
+        .await;
+        assert_eq!(code, 0);
+        assert!(called_live.load(Ordering::SeqCst));
+    }
+}
diff --git a/crates/manager/src/commands/config_explain.rs b/crates/manager/src/commands/config_explain.rs
new file mode 100644
index 000000000..d532575f3
--- /dev/null
+++ b/crates/manager/src/commands/config_explain.rs
@@ -0,0 +1,203 @@
+//! Port of `lib/codex-manager/commands/config-explain.ts`.
+//!
+//! `config explain [--json]` — renders the 53-entry config explain report.
+//! Only `--json` is accepted (NOT `-j`, TS parity); any other arg errors.
+
+use cma_config::explain::{ConfigExplainReport, get_plugin_config_explain_report};
+use cma_core::json_io::{stringify_compact, stringify_pretty2};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+
+/// Serialize a [`ConfigExplainReport`] with the exact TS key order:
+/// `{ configPath, storageKind, entries: [{key, value, defaultValue, source,
+/// envNames}] }`.
+pub fn config_explain_report_to_value(report: &ConfigExplainReport) -> Value {
+    let mut root = Map::new();
+    root.insert(
+        "configPath".to_string(),
+        match &report.config_path {
+            Some(path) => Value::String(path.to_string_lossy().into_owned()),
+            None => Value::Null,
+        },
+    );
+    root.insert(
+        "storageKind".to_string(),
+        Value::String(report.storage_kind.as_str().to_string()),
+    );
+    let entries: Vec<Value> = report
+        .entries
+        .iter()
+        .map(|entry| {
+            let mut object = Map::new();
+            object.insert("key".to_string(), Value::String(entry.key.to_string()));
+            object.insert("value".to_string(), entry.value.clone());
+            object.insert("defaultValue".to_string(), entry.default_value.clone());
+            object.insert(
+                "source".to_string(),
+                Value::String(entry.source.as_str().to_string()),
+            );
+            object.insert(
+                "envNames".to_string(),
+                Value::Array(
+                    entry
+                        .env_names
+                        .iter()
+                        .map(|name| Value::String((*name).to_string()))
+                        .collect(),
+                ),
+            );
+            Value::Object(object)
+        })
+        .collect();
+    root.insert("entries".to_string(), Value::Array(entries));
+    Value::Object(root)
+}
+
+/// Report-provider seam (the TS `deps.getReport` may throw; production wraps
+/// the infallible getter in `Ok`).
+pub fn run_config_explain_with(
+    args: &[String],
+    get_report: impl FnOnce() -> Result<ConfigExplainReport, String>,
+    out: &mut CliOut,
+) -> i32 {
+    let json = args.iter().any(|arg| arg == "--json");
+    if let Some(unknown) = args.iter().find(|arg| arg.as_str() != "--json") {
+        out.error(format!("Unknown option: {unknown}"));
+        return 1;
+    }
+
+    let report = match get_report() {
+        Ok(report) => report,
+        Err(message) => {
+            out.error(format!("Failed to read config: {message}"));
+            return 1;
+        }
+    };
+    if json {
+        out.info(stringify_pretty2(&config_explain_report_to_value(&report)));
+        return 0;
+    }
+
+    out.info(format!("Config storage: {}", report.storage_kind.as_str()));
+    out.info(format!(
+        "Config path: {}",
+        report
+            .config_path
+            .as_ref()
+            .map(|path| path.to_string_lossy().into_owned())
+            .unwrap_or_else(|| "(none)".to_string())
+    ));
+    out.info("");
+    for entry in &report.entries {
+        let env_suffix = if entry.env_names.is_empty() {
+            String::new()
+        } else {
+            format!(" [{}]", entry.env_names.join(", "))
+        };
+        out.info(format!(
+            "{} = {} ({}){}",
+            entry.key,
+            stringify_compact(&entry.value),
+            entry.source.as_str(),
+            env_suffix
+        ));
+    }
+    0
+}
+
+/// Production entry (TS `runConfigExplainCommand(args, { getReport })`).
+pub fn run_config_explain_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_config_explain_with(args, || Ok(get_plugin_config_explain_report()), out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_config::explain::{ConfigExplainEntry, ConfigExplainSource, ConfigExplainStorageKind};
+    use serde_json::json;
+
+    fn fake_report() -> ConfigExplainReport {
+        ConfigExplainReport {
+            config_path: Some(std::path::PathBuf::from("/tmp/config.json")),
+            storage_kind: ConfigExplainStorageKind::Unified,
+            entries: vec![
+                ConfigExplainEntry {
+                    key: "debug",
+                    value: json!(true),
+                    default_value: json!(false),
+                    source: ConfigExplainSource::Env,
+                    env_names: &["CODEX_AUTH_DEBUG"],
+                },
+                ConfigExplainEntry {
+                    key: "quotaThreshold",
+                    value: json!(0.95),
+                    default_value: json!(0.95),
+                    source: ConfigExplainSource::Default,
+                    env_names: &[],
+                },
+            ],
+        }
+    }
+
+    #[test]
+    fn rejects_unknown_options_with_exact_string() {
+        let mut out = CliOut::capture();
+        let code = run_config_explain_with(
+            &["-j".to_string()],
+            || Ok(fake_report()),
+            &mut out,
+        );
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown option: -j");
+    }
+
+    #[test]
+    fn reports_getter_failure() {
+        let mut out = CliOut::capture();
+        let code = run_config_explain_with(&[], || Err("boom".to_string()), &mut out);
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Failed to read config: boom");
+    }
+
+    #[test]
+    fn text_mode_prints_storage_path_and_entries() {
+        let mut out = CliOut::capture();
+        let code = run_config_explain_with(&[], || Ok(fake_report()), &mut out);
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        assert_eq!(
+            text,
+            [
+                "Config storage: unified",
+                "Config path: /tmp/config.json",
+                "",
+                "debug = true (env) [CODEX_AUTH_DEBUG]",
+                "quotaThreshold = 0.95 (default)",
+            ]
+            .join("\n")
+        );
+    }
+
+    #[test]
+    fn json_mode_prints_report_verbatim_with_key_order() {
+        let mut out = CliOut::capture();
+        let code =
+            run_config_explain_with(&["--json".to_string()], || Ok(fake_report()), &mut out);
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        let parsed: Value = serde_json::from_str(&text).unwrap();
+        assert_eq!(parsed["configPath"], json!("/tmp/config.json"));
+        assert_eq!(parsed["storageKind"], json!("unified"));
+        assert_eq!(parsed["entries"][0]["key"], json!("debug"));
+        assert_eq!(parsed["entries"][0]["envNames"], json!(["CODEX_AUTH_DEBUG"]));
+        // Key order is part of the byte contract.
+        assert!(text.find("\"configPath\"").unwrap() < text.find("\"storageKind\"").unwrap());
+        assert!(text.find("\"storageKind\"").unwrap() < text.find("\"entries\"").unwrap());
+        let entry_start = text.find("\"key\"").unwrap();
+        assert!(entry_start < text.find("\"value\"").unwrap());
+        assert!(text.find("\"value\"").unwrap() < text.find("\"defaultValue\"").unwrap());
+        assert!(text.find("\"defaultValue\"").unwrap() < text.find("\"source\"").unwrap());
+        assert!(text.find("\"source\"").unwrap() < text.find("\"envNames\"").unwrap());
+    }
+}
diff --git a/crates/manager/src/commands/debug_bundle.rs b/crates/manager/src/commands/debug_bundle.rs
new file mode 100644
index 000000000..2a4f18ff9
--- /dev/null
+++ b/crates/manager/src/commands/debug_bundle.rs
@@ -0,0 +1,380 @@
+//! Port of `lib/codex-manager/commands/debug-bundle.ts`.
+//!
+//! `debug bundle [--json]` — a share-safe diagnostic snapshot. All paths are
+//! home-redacted, account ids/emails masked, and config values routed through
+//! the logger's `sanitize_value` (errors-logging-04).
+
+use chrono::{SecondsFormat, Utc};
+use cma_cli_mirror::state::CodexCliState;
+use cma_config::explain::{ConfigExplainReport, get_plugin_config_explain_report};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::logger::{mask_email, mask_token, sanitize_value};
+use cma_core::schemas::account_storage::AccountStorageV3;
+use serde_json::{Map, Value, json};
+
+use crate::dispatcher::{CliOut, js_number};
+
+/// `os.homedir()` analogue for the redactor: `USERPROFILE` on Windows,
+/// `HOME` on POSIX (empty string when unset — TS then skips redaction).
+fn os_homedir() -> String {
+    if cfg!(windows) {
+        std::env::var("USERPROFILE")
+            .ok()
+            .filter(|value| !value.is_empty())
+            .or_else(|| std::env::var("HOME").ok())
+            .unwrap_or_default()
+    } else {
+        std::env::var("HOME").unwrap_or_default()
+    }
+}
+
+/// Platform-injectable core of [`redact_home`] (exported for tests — the TS
+/// module exports `redactHome` itself for the same reason).
+pub fn redact_home_with(value: &str, home: &str, is_windows: bool) -> String {
+    if home.is_empty() {
+        return value.to_string();
+    }
+
+    // On win32 the comparison must be case-insensitive AND separator-
+    // insensitive; the ORIGINAL `value` keeps its separators in the suffix.
+    let canon = |s: &str| -> String {
+        if is_windows {
+            s.to_lowercase().replace('/', "\\")
+        } else {
+            s.to_string()
+        }
+    };
+    let normalized_value = canon(value);
+    let normalized_home = canon(home);
+
+    if normalized_value == normalized_home {
+        return "~".to_string();
+    }
+
+    // Require a path boundary after the home prefix so `/users/alice2` is not
+    // treated as living under home `/users/alice`.
+    if normalized_value.starts_with(&normalized_home) {
+        let boundary = normalized_value[normalized_home.len()..].chars().next();
+        let sep = if is_windows { '\\' } else { '/' };
+        if matches!(boundary, Some(b) if b == sep || b == '/' || b == '\\') {
+            // `home.len()` in TS is a UTF-16 unit count into `value`; paths
+            // are byte-compatible here because the canonicalization never
+            // changes lengths for ASCII drive/sep transforms. Use the char
+            // boundary from the ORIGINAL value.
+            let suffix: String = value.chars().skip(home.chars().count()).collect();
+            return format!("~{suffix}");
+        }
+    }
+
+    value.to_string()
+}
+
+/// TS `redactHome(value)` — replace the home-directory prefix with `~`,
+/// path-boundary aware.
+pub fn redact_home(value: &str) -> String {
+    redact_home_with(value, &os_homedir(), cfg!(windows))
+}
+
+/// TS `sanitizeConfigReport` — redact the config path, sanitize every entry
+/// `value`/`defaultValue`. Emits the report in explain key order.
+pub fn sanitize_config_report_value(report: &ConfigExplainReport, home: &str, is_windows: bool) -> Value {
+    let mut root = Map::new();
+    root.insert(
+        "configPath".to_string(),
+        match &report.config_path {
+            Some(path) => Value::String(redact_home_with(
+                &path.to_string_lossy(),
+                home,
+                is_windows,
+            )),
+            None => Value::Null,
+        },
+    );
+    root.insert(
+        "storageKind".to_string(),
+        Value::String(report.storage_kind.as_str().to_string()),
+    );
+    let entries: Vec<Value> = report
+        .entries
+        .iter()
+        .map(|entry| {
+            let mut object = Map::new();
+            object.insert("key".to_string(), Value::String(entry.key.to_string()));
+            object.insert("value".to_string(), sanitize_value(&entry.value));
+            object.insert(
+                "defaultValue".to_string(),
+                sanitize_value(&entry.default_value),
+            );
+            object.insert(
+                "source".to_string(),
+                Value::String(entry.source.as_str().to_string()),
+            );
+            object.insert(
+                "envNames".to_string(),
+                Value::Array(
+                    entry
+                        .env_names
+                        .iter()
+                        .map(|name| Value::String((*name).to_string()))
+                        .collect(),
+                ),
+            );
+            Value::Object(object)
+        })
+        .collect();
+    root.insert("entries".to_string(), Value::Array(entries));
+    Value::Object(root)
+}
+
+/// Inputs for [`build_debug_bundle`] (the loaders' outputs).
+pub struct DebugBundleData<'a> {
+    pub generated_at: String,
+    pub storage_path: String,
+    pub last_accounts_save_timestamp: i64,
+    pub config: &'a ConfigExplainReport,
+    pub accounts: Option<&'a AccountStorageV3>,
+    pub flagged_total: usize,
+    pub codex_cli: Option<&'a CodexCliState>,
+}
+
+/// Pure bundle builder (exact TS key order).
+pub fn build_debug_bundle(data: &DebugBundleData<'_>, home: &str, is_windows: bool) -> Value {
+    let total = data.accounts.map(|s| s.accounts.len()).unwrap_or(0);
+    let enabled = data
+        .accounts
+        .map(|s| {
+            s.accounts
+                .iter()
+                .filter(|account| account.enabled != Some(false))
+                .count()
+        })
+        .unwrap_or(0);
+    // `activeIndex` is always numeric in the Rust storage model; the TS
+    // typeof-number guard is vacuously true when storage exists.
+    let active_index = data
+        .accounts
+        .map(|s| Value::from(s.active_index + 1))
+        .unwrap_or(Value::Null);
+
+    let codex_cli = match data.codex_cli {
+        Some(state) => json!({
+            "path": redact_home_with(&state.path.to_string_lossy(), home, is_windows),
+            "accountCount": state.accounts.len(),
+            "activeEmail": state.active_email.as_deref().map(mask_email),
+            "activeAccountId": state.active_account_id.as_deref().map(mask_token),
+            "syncVersion": state.sync_version.map(js_number),
+            "sourceUpdatedAtMs": state.source_updated_at_ms.map(js_number),
+        }),
+        None => Value::Null,
+    };
+
+    json!({
+        "generatedAt": data.generated_at,
+        "storagePath": redact_home_with(&data.storage_path, home, is_windows),
+        "lastAccountsSaveTimestamp": data.last_accounts_save_timestamp,
+        "config": sanitize_config_report_value(data.config, home, is_windows),
+        "accounts": {
+            "total": total,
+            "enabled": enabled,
+            "activeIndex": active_index,
+        },
+        "flaggedAccounts": {
+            "total": data.flagged_total,
+        },
+        "codexCli": codex_cli,
+    })
+}
+
+/// Emit the bundle (shared by the injectable test path and production).
+fn emit_bundle(bundle: &Value, json: bool, out: &mut CliOut) -> i32 {
+    if json {
+        out.info(stringify_pretty2(bundle));
+        return 0;
+    }
+    out.info(format!(
+        "Generated: {}",
+        bundle["generatedAt"].as_str().unwrap_or("")
+    ));
+    out.info(format!(
+        "Storage: {}",
+        bundle["storagePath"].as_str().unwrap_or("")
+    ));
+    out.info(format!(
+        "Accounts: {} total, {} enabled",
+        bundle["accounts"]["total"], bundle["accounts"]["enabled"]
+    ));
+    out.info(format!("Flagged: {}", bundle["flaggedAccounts"]["total"]));
+    if bundle["codexCli"].is_object() {
+        out.info(format!(
+            "Codex CLI: {} account(s), active {}",
+            bundle["codexCli"]["accountCount"],
+            bundle["codexCli"]["activeEmail"]
+                .as_str()
+                .unwrap_or("unknown")
+        ));
+    }
+    0
+}
+
+/// TS `runDebugBundleCommand(args, deps)`.
+pub async fn run_debug_bundle_command(args: &[String], out: &mut CliOut) -> i32 {
+    let json = args.iter().any(|arg| arg == "--json");
+    if let Some(unknown) = args.iter().find(|arg| arg.as_str() != "--json") {
+        out.error(format!("Unknown option: {unknown}"));
+        return 1;
+    }
+
+    let config = get_plugin_config_explain_report();
+    let accounts = cma_storage::load::load_accounts()
+        .await
+        .map(|loaded| loaded.storage);
+    let flagged = cma_storage::flagged::load_flagged_accounts().await;
+    let codex_cli = cma_cli_mirror::state::load_codex_cli_state(true).await;
+
+    let data = DebugBundleData {
+        generated_at: Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true),
+        storage_path: cma_storage::facade::get_storage_path(),
+        last_accounts_save_timestamp: cma_storage::facade::get_last_accounts_save_timestamp(),
+        config: &config,
+        accounts: accounts.as_ref(),
+        flagged_total: flagged.accounts.len(),
+        codex_cli: codex_cli.as_ref(),
+    };
+    let bundle = build_debug_bundle(&data, &os_homedir(), cfg!(windows));
+    emit_bundle(&bundle, json, out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_config::explain::{ConfigExplainEntry, ConfigExplainSource, ConfigExplainStorageKind};
+
+    // Port of test/debug-bundle-redact.test.ts (errors-logging-04).
+
+    #[test]
+    fn posix_path_rules() {
+        let home = "/home/alice";
+        assert_eq!(
+            redact_home_with("/home/alice/.codex/config.json", home, false),
+            "~/.codex/config.json"
+        );
+        assert_eq!(redact_home_with("/home/alice", home, false), "~");
+        assert_eq!(
+            redact_home_with("/home/alice2/.codex/config.json", home, false),
+            "/home/alice2/.codex/config.json"
+        );
+        // Case-sensitive on posix.
+        assert_eq!(
+            redact_home_with("/HOME/Alice/.codex", home, false),
+            "/HOME/Alice/.codex"
+        );
+    }
+
+    #[test]
+    fn windows_path_rules() {
+        let home = "C:\\Users\\Alice";
+        assert_eq!(
+            redact_home_with("c:\\users\\alice\\.codex\\config.json", home, true),
+            "~\\.codex\\config.json"
+        );
+        // Mixed-separator windows path keeps original separators in suffix.
+        assert_eq!(
+            redact_home_with("c:/users/alice/.codex/config.json", home, true),
+            "~/.codex/config.json"
+        );
+        assert_eq!(redact_home_with("C:\\USERS\\ALICE", home, true), "~");
+        assert_eq!(
+            redact_home_with("c:\\users\\alice2\\.codex", home, true),
+            "c:\\users\\alice2\\.codex"
+        );
+    }
+
+    #[test]
+    fn empty_home_returns_value_unchanged() {
+        assert_eq!(
+            redact_home_with("/home/alice/.codex", "", false),
+            "/home/alice/.codex"
+        );
+    }
+
+    #[test]
+    fn json_bundle_redacts_and_masks() {
+        let report = ConfigExplainReport {
+            config_path: Some(std::path::PathBuf::from("/home/alice/.codex/config.json")),
+            storage_kind: ConfigExplainStorageKind::Unified,
+            entries: vec![ConfigExplainEntry {
+                key: "codexRuntimeRotationProxy",
+                value: serde_json::json!("http://user:s3cr3t-pass@proxy.internal:8080"),
+                default_value: serde_json::Value::Null,
+                source: ConfigExplainSource::Unified,
+                env_names: &[],
+            }],
+        };
+        let mut cli_state = CodexCliState {
+            path: std::path::PathBuf::from("/home/alice/.codex"),
+            accounts: Vec::new(),
+            active_account_id: Some("org-1234567890abcdef".to_string()),
+            active_email: Some("alice@example.com".to_string()),
+            sync_version: None,
+            source_updated_at_ms: None,
+        };
+        cli_state.sync_version = Some(3.0);
+        let data = DebugBundleData {
+            generated_at: "2026-01-01T00:00:00.000Z".to_string(),
+            storage_path: "/home/alice/.codex/accounts.json".to_string(),
+            last_accounts_save_timestamp: 0,
+            config: &report,
+            accounts: None,
+            flagged_total: 0,
+            codex_cli: Some(&cli_state),
+        };
+        let bundle = build_debug_bundle(&data, "/home/alice", false);
+        let text = serde_json::to_string(&bundle).unwrap();
+        assert!(text.contains("~/.codex/config.json"));
+        assert!(!text.contains("/home/alice/.codex/config.json"));
+        assert!(!text.contains("org-1234567890abcdef"));
+        assert!(!text.contains("alice@example.com"));
+        assert!(!text.contains("s3cr3t-pass"));
+        assert_eq!(bundle["accounts"]["activeIndex"], serde_json::Value::Null);
+        assert_eq!(bundle["codexCli"]["syncVersion"], 3);
+    }
+
+    #[test]
+    fn text_mode_lines() {
+        let report = ConfigExplainReport {
+            config_path: None,
+            storage_kind: ConfigExplainStorageKind::None,
+            entries: vec![],
+        };
+        let data = DebugBundleData {
+            generated_at: "2026-01-01T00:00:00.000Z".to_string(),
+            storage_path: "/x/accounts.json".to_string(),
+            last_accounts_save_timestamp: 0,
+            config: &report,
+            accounts: None,
+            flagged_total: 2,
+            codex_cli: None,
+        };
+        let bundle = build_debug_bundle(&data, "/home/alice", false);
+        let mut out = CliOut::capture();
+        assert_eq!(emit_bundle(&bundle, false, &mut out), 0);
+        assert_eq!(
+            out.info_text(),
+            [
+                "Generated: 2026-01-01T00:00:00.000Z",
+                "Storage: /x/accounts.json",
+                "Accounts: 0 total, 0 enabled",
+                "Flagged: 2",
+            ]
+            .join("\n")
+        );
+    }
+
+    #[tokio::test]
+    async fn rejects_unknown_options() {
+        let mut out = CliOut::capture();
+        let code = run_debug_bundle_command(&["-j".to_string()], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown option: -j");
+    }
+}
diff --git a/crates/manager/src/commands/forecast.rs b/crates/manager/src/commands/forecast.rs
new file mode 100644
index 000000000..a87d9dfec
--- /dev/null
+++ b/crates/manager/src/commands/forecast.rs
@@ -0,0 +1,756 @@
+//! Port of `lib/codex-manager/commands/forecast.ts`.
+//!
+//! `forecast [--live] [--json] [--explain] [--model <model>]
+//! [--no-runtime-overlay]` — best-account preview with optional live quota
+//! probing.
+//!
+//! Contract divergences vs `best`/`report` (spec 08 gotchas 2/3/4/5/16/17):
+//! - zero accounts exits 0;
+//! - probe-refresh patches apply in memory BEFORE persisting and stay
+//!   applied on persist failure;
+//! - persistence goes through the reload-clone `persist_refreshed_account_patch`;
+//! - `--model` without `--live` is silently accepted;
+//! - quota-cache saves are best-effort (never change the exit code);
+//! - forecast scoring sees the ORIGINAL loaded quota cache while live
+//!   results mutate a working CLONE.
+
+use std::collections::HashMap;
+
+use cma_accounts::rate_limits::format_wait_time;
+use cma_config::dashboard_settings::load_dashboard_display_settings;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::{DEFAULT_PROBE_MODEL, ModelFamily};
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3};
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::forecast::{
+    ForecastAccountInput, RuntimeForecastOverlay, build_forecast_explanation,
+    evaluate_forecast_accounts, recommend_forecast_account, summarize_forecast,
+};
+use cma_quota::probe::{
+    CodexQuotaSnapshot, ProbeCodexQuotaOptions, describe_codex_probe_failure,
+    fetch_codex_quota_snapshot,
+};
+use cma_quota::readiness::build_quota_email_fallback_state;
+use cma_request::model_map::resolve_normalized_model;
+use cma_runtime::observability::RuntimeObservabilitySnapshot;
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    AccountIdentityMatch, RefreshedAccountPatch, apply_refreshed_account_patch,
+    persist_refreshed_account_patch, serialize_forecast_results,
+};
+use crate::formatters::account::{availability_tone, risk_tone};
+use crate::formatters::quota::{
+    CompactQuotaFormatOptions, format_compact_quota_snapshot, style_quota_summary,
+};
+use crate::formatters::text_style::{
+    PromptTone, ResultSegment, format_result_summary, join_styled_segments, style_prompt_text,
+};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct ForecastCliOptions {
+    live: bool,
+    json: bool,
+    explain: bool,
+    model: String,
+    runtime_overlay: bool,
+}
+
+impl Default for ForecastCliOptions {
+    fn default() -> Self {
+        ForecastCliOptions {
+            live: false,
+            json: false,
+            explain: false,
+            model: DEFAULT_PROBE_MODEL.to_string(),
+            runtime_overlay: true,
+        }
+    }
+}
+
+fn print_forecast_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:".to_string(),
+            "  codex-multi-auth forecast [--live] [--json] [--explain] [--model <model>]"
+                .to_string(),
+            String::new(),
+            "Options:".to_string(),
+            "  --live, -l         Probe live quota headers via Codex backend".to_string(),
+            "  --json, -j         Print machine-readable JSON output".to_string(),
+            "  --explain          Include structured recommendation reasoning".to_string(),
+            format!("  --model, -m        Probe model for live mode (default: {DEFAULT_PROBE_MODEL})"),
+            "  --no-runtime-overlay  Ignore persisted runtime skip diagnostics".to_string(),
+        ]
+        .join("\n"),
+    );
+}
+
+fn parse_forecast_args(args: &[String]) -> Result<ForecastCliOptions, String> {
+    let mut options = ForecastCliOptions::default();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        match arg {
+            "--live" | "-l" => {
+                options.live = true;
+                i += 1;
+                continue;
+            }
+            "--json" | "-j" => {
+                options.json = true;
+                i += 1;
+                continue;
+            }
+            "--explain" => {
+                options.explain = true;
+                i += 1;
+                continue;
+            }
+            "--no-runtime-overlay" => {
+                options.runtime_overlay = false;
+                i += 1;
+                continue;
+            }
+            "--model" | "-m" => {
+                let value = args.get(i + 1).map(|v| v.trim().to_string());
+                match value {
+                    Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                        options.model = v;
+                        i += 2;
+                        continue;
+                    }
+                    _ => return Err("Missing value for --model".to_string()),
+                }
+            }
+            _ => {}
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                return Err("Missing value for --model".to_string());
+            }
+            options.model = value.to_string();
+            i += 1;
+            continue;
+        }
+        return Err(format!("Unknown option: {arg}"));
+    }
+
+    Ok(options)
+}
+
+/// Persisted runtime-observability snapshot → forecast overlay (the TS
+/// passed the snapshot straight through; Rust converts to the quota crate's
+/// typed overlay, keeping only string skip reasons).
+fn snapshot_to_overlay(snapshot: &RuntimeObservabilitySnapshot) -> RuntimeForecastOverlay {
+    let string_map = |map: &serde_json::Map<String, Value>| -> HashMap<String, String> {
+        map.iter()
+            .filter_map(|(key, value)| {
+                value
+                    .as_str()
+                    .map(|text| (key.clone(), text.to_string()))
+            })
+            .collect()
+    };
+    RuntimeForecastOverlay {
+        account_skip_reasons: string_map(&snapshot.account_skip_reasons),
+        last_pool_exhaustion_skip_reasons: string_map(&snapshot.last_pool_exhaustion_skip_reasons),
+        policy_blocked_indexes: snapshot
+            .policy_blocked_indexes
+            .iter()
+            .filter(|index| **index >= 0)
+            .map(|index| *index as usize)
+            .collect(),
+    }
+}
+
+/// TS `runForecastCommand(args, deps)`.
+pub async fn run_forecast_command(args: &[String], out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_forecast_usage(out);
+        return 0;
+    }
+
+    let options = match parse_forecast_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_forecast_usage(out);
+            return 1;
+        }
+    };
+    let trimmed_model = options.model.trim();
+    let requested_model = if trimmed_model.is_empty() {
+        DEFAULT_PROBE_MODEL.to_string()
+    } else {
+        trimmed_model.to_string()
+    };
+    let probe_model = resolve_normalized_model(Some(&requested_model));
+    let display = load_dashboard_display_settings().await;
+    let quota_cache = cma_quota::cache::load_quota_cache().await;
+    let runtime_overlay: Option<RuntimeForecastOverlay> = if options.runtime_overlay {
+        cma_runtime::observability::load_persisted_runtime_observability_snapshot()
+            .map(|snapshot| snapshot_to_overlay(&snapshot))
+    } else {
+        None
+    };
+    // Forecast scoring sees the ORIGINAL cache; live results mutate a CLONE
+    // (spec 08 gotcha 17).
+    let mut working_quota_cache = quota_cache.clone();
+    let mut quota_cache_changed = false;
+
+    cma_storage::facade::set_storage_path(None);
+    let mut storage: AccountStorageV3 = match cma_storage::load::load_accounts().await {
+        Some(loaded) if !loaded.storage.accounts.is_empty() => loaded.storage,
+        _ => {
+            out.info("No accounts configured.");
+            return 0;
+        }
+    };
+    let quota_email_fallback_state = if options.live {
+        Some(build_quota_email_fallback_state(&storage.accounts))
+    } else {
+        None
+    };
+
+    let now = cma_core::utils::now_ms();
+    let active_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    let mut refresh_failures: HashMap<usize, TokenFailure> = HashMap::new();
+    let mut live_quota_by_index: HashMap<usize, CodexQuotaSnapshot> = HashMap::new();
+    let mut probe_errors: Vec<String> = Vec::new();
+
+    for i in 0..storage.accounts.len() {
+        if !options.live || storage.accounts[i].enabled == Some(false) {
+            continue;
+        }
+
+        let label = cma_accounts::manager_persistence::format_account_label(
+            Some(&storage.accounts[i] as &dyn cma_accounts::manager_persistence::AccountLabelSource),
+            i,
+        );
+        let mut probe_access_token = storage.accounts[i].access_token.clone();
+        let mut probe_account_id = storage.accounts[i]
+            .account_id
+            .clone()
+            .or_else(|| extract_account_id(storage.accounts[i].access_token.as_deref()));
+        if !crate::login::account_credentials::has_usable_access_token(&storage.accounts[i], now) {
+            let refresh_result =
+                cma_auth::refresh_queue::queued_refresh(&storage.accounts[i].refresh_token).await;
+            let success = match refresh_result {
+                TokenResult::Success(success) => success,
+                TokenResult::Failed(failure) => {
+                    let mut normalized = failure.clone();
+                    normalized.message =
+                        Some(crate::formatters::text_style::normalize_failure_detail(
+                            failure.message.as_deref(),
+                            failure.reason.map(|reason| reason.as_str()),
+                        ));
+                    refresh_failures.insert(i, normalized);
+                    continue;
+                }
+            };
+            let refreshed_email = sanitize_email(
+                extract_account_email(Some(&success.access), success.id_token.as_deref())
+                    .as_deref(),
+            );
+            let refreshed_account_id = extract_account_id(Some(&success.access));
+            let previous_refresh_token = storage.accounts[i].refresh_token.clone();
+            let previous_access_token = storage.accounts[i].access_token.clone();
+            let previous_expires_at = storage.accounts[i].expires_at;
+            let previous_email = storage.accounts[i].email.clone();
+            let previous_account_id = storage.accounts[i].account_id.clone();
+            let mut refresh_patch = RefreshedAccountPatch {
+                refresh_token: success.refresh.clone(),
+                access_token: success.access.clone(),
+                expires_at: success.expires,
+                email: None,
+                account_id: None,
+                account_id_source: None,
+            };
+            if let Some(email) = &refreshed_email {
+                refresh_patch.email = Some(email.clone());
+            }
+            if let Some(account_id) = &refreshed_account_id {
+                refresh_patch.account_id = Some(account_id.clone());
+                refresh_patch.account_id_source = Some(AccountIdSource::Token);
+            }
+            let account_match = AccountIdentityMatch {
+                refresh_token: Some(previous_refresh_token.clone()),
+                email: previous_email.clone(),
+                account_id: previous_account_id.clone(),
+            };
+            // Apply the in-memory patch FIRST (spec 08 gotcha 3: it stays
+            // applied even when the persist below fails).
+            apply_refreshed_account_patch(&mut storage.accounts[i], &refresh_patch);
+            probe_access_token = Some(success.access.clone());
+            probe_account_id = storage.accounts[i]
+                .account_id
+                .clone()
+                .or(refreshed_account_id);
+            if previous_refresh_token != refresh_patch.refresh_token
+                || previous_access_token.as_deref() != Some(refresh_patch.access_token.as_str())
+                || previous_expires_at != Some(refresh_patch.expires_at)
+                || previous_email != storage.accounts[i].email
+                || previous_account_id != storage.accounts[i].account_id
+            {
+                let persisted = persist_refreshed_account_patch(
+                    &storage,
+                    &account_match,
+                    &refresh_patch,
+                    || async {
+                        cma_storage::load::load_accounts()
+                            .await
+                            .map(|loaded| loaded.storage)
+                    },
+                    |next_storage: &AccountStorageV3| {
+                        let snapshot = next_storage.clone();
+                        async move { cma_storage::save::save_accounts(&snapshot).await }
+                    },
+                )
+                .await;
+                if let Err(error) = persisted {
+                    let message = crate::formatters::text_style::normalize_failure_detail(
+                        Some(error.message()),
+                        None,
+                    );
+                    probe_errors.push(format!("{label}: {message}"));
+                    continue;
+                }
+            }
+        }
+
+        let (Some(probe_access_token), Some(probe_account_id)) =
+            (probe_access_token, probe_account_id)
+        else {
+            probe_errors.push(format!("{label}: missing accountId for live probe"));
+            continue;
+        };
+
+        match fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+            account_id: probe_account_id,
+            access_token: probe_access_token,
+            model: Some(probe_model.to_string()),
+            ..Default::default()
+        })
+        .await
+        {
+            Ok(live_quota) => {
+                quota_cache_changed = crate::quota_cache_helpers::update_quota_cache_for_account(
+                    &mut working_quota_cache,
+                    &storage.accounts[i],
+                    &live_quota,
+                    &storage.accounts,
+                    quota_email_fallback_state.as_ref(),
+                ) || quota_cache_changed;
+                live_quota_by_index.insert(i, live_quota);
+            }
+            Err(error) => {
+                let message = describe_codex_probe_failure(
+                    &error,
+                    Some(&|raw: &str| {
+                        crate::formatters::text_style::normalize_failure_detail(Some(raw), None)
+                    }),
+                );
+                probe_errors.push(format!("{label}: {message}"));
+            }
+        }
+    }
+
+    let forecast_inputs: Vec<ForecastAccountInput<'_>> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| ForecastAccountInput {
+            index,
+            account,
+            is_current: index == active_index,
+            now,
+            refresh_failure: refresh_failures.get(&index),
+            live_quota: live_quota_by_index.get(&index),
+            quota_cache: Some(&quota_cache),
+            all_accounts: Some(&storage.accounts),
+            runtime_overlay: runtime_overlay.as_ref(),
+        })
+        .collect();
+    let forecast_results = evaluate_forecast_accounts(&forecast_inputs);
+    drop(forecast_inputs);
+    let summary = summarize_forecast(&forecast_results);
+    let recommendation = recommend_forecast_account(&forecast_results);
+    let explanation = build_forecast_explanation(&forecast_results, &recommendation);
+
+    if options.json {
+        if quota_cache_changed {
+            // Quota cache is a derived artifact; failures must never abort
+            // the JSON output (the Rust saver is internally best-effort).
+            cma_quota::cache::save_quota_cache(&working_quota_cache).await;
+        }
+        let mut payload = Map::new();
+        payload.insert("command".to_string(), Value::String("forecast".to_string()));
+        payload.insert("model".to_string(), Value::String(requested_model.clone()));
+        payload.insert("liveProbe".to_string(), Value::Bool(options.live));
+        payload.insert(
+            "runtimeOverlay".to_string(),
+            Value::Bool(options.runtime_overlay),
+        );
+        payload.insert(
+            "summary".to_string(),
+            serde_json::to_value(summary).unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "recommendation".to_string(),
+            serde_json::to_value(&recommendation).unwrap_or(Value::Null),
+        );
+        if options.explain {
+            payload.insert(
+                "explanation".to_string(),
+                serde_json::to_value(&explanation).unwrap_or(Value::Null),
+            );
+        }
+        payload.insert(
+            "probeErrors".to_string(),
+            Value::Array(
+                probe_errors
+                    .iter()
+                    .map(|error| Value::String(error.clone()))
+                    .collect(),
+            ),
+        );
+        payload.insert(
+            "accounts".to_string(),
+            Value::Array(serialize_forecast_results(
+                &forecast_results,
+                &live_quota_by_index,
+                &refresh_failures,
+                &|snapshot: &CodexQuotaSnapshot| {
+                    cma_quota::probe::format_quota_snapshot_line(snapshot)
+                },
+            )),
+        );
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return 0;
+    }
+
+    out.info(style_prompt_text(
+        &format!(
+            "Best-account preview ({} account(s), model {requested_model}, live check {})",
+            storage.accounts.len(),
+            if options.live { "on" } else { "off" }
+        ),
+        PromptTone::Accent,
+    ));
+    out.info(format_result_summary(&[
+        ResultSegment::new(format!("{} ready now", summary.ready), PromptTone::Success),
+        ResultSegment::new(format!("{} waiting", summary.delayed), PromptTone::Warning),
+        ResultSegment::new(
+            format!("{} unavailable", summary.unavailable),
+            if summary.unavailable > 0 {
+                PromptTone::Danger
+            } else {
+                PromptTone::Muted
+            },
+        ),
+        ResultSegment::new(
+            format!("{} high risk", summary.high_risk),
+            if summary.high_risk > 0 {
+                PromptTone::Danger
+            } else {
+                PromptTone::Muted
+            },
+        ),
+    ]));
+    out.info("");
+
+    for result in &forecast_results {
+        if !display.show_per_account_rows {
+            continue;
+        }
+        let current_tag = if result.is_current { " [current]" } else { "" };
+        let wait_label = if result.wait_ms > 0 {
+            style_prompt_text(
+                &format!("wait {}", format_wait_time(result.wait_ms)),
+                PromptTone::Muted,
+            )
+        } else {
+            String::new()
+        };
+        let index_label = style_prompt_text(&format!("{}.", result.index + 1), PromptTone::Accent);
+        let account_label =
+            style_prompt_text(&format!("{}{current_tag}", result.label), PromptTone::Accent);
+        let risk_label = style_prompt_text(
+            &format!("{} risk ({})", result.risk_level.as_str(), result.risk_score),
+            risk_tone(result.risk_level),
+        );
+        let availability_label = style_prompt_text(
+            result.availability.as_str(),
+            availability_tone(result.availability),
+        );
+        let mut row_parts = vec![availability_label, risk_label];
+        if !wait_label.is_empty() {
+            row_parts.push(wait_label);
+        }
+        out.info(format!(
+            "{index_label} {account_label} {} {}",
+            style_prompt_text("|", PromptTone::Muted),
+            join_styled_segments(&row_parts)
+        ));
+        if display.show_forecast_reasons && !result.reasons.is_empty() {
+            out.info(format!(
+                "   {}",
+                style_prompt_text(
+                    &result
+                        .reasons
+                        .iter()
+                        .take(3)
+                        .cloned()
+                        .collect::<Vec<_>>()
+                        .join("; "),
+                    PromptTone::Muted
+                )
+            ));
+        }
+        if display.show_quota_details
+            && let Some(live_quota) = live_quota_by_index.get(&result.index)
+        {
+            out.info(format!(
+                "   {} {}",
+                style_prompt_text("quota:", PromptTone::Accent),
+                style_quota_summary(&format_compact_quota_snapshot(
+                    live_quota,
+                    cma_core::utils::now_ms(),
+                    &CompactQuotaFormatOptions::default(),
+                ))
+            ));
+        }
+    }
+
+    if !display.show_per_account_rows {
+        out.info(style_prompt_text(
+            "Per-account lines are hidden in dashboard settings.",
+            PromptTone::Muted,
+        ));
+    }
+
+    if display.show_recommendations || options.explain {
+        out.info("");
+    }
+
+    if display.show_recommendations {
+        if let Some(index) = recommendation.recommended_index {
+            if let Some(account) = forecast_results.iter().find(|result| result.index == index) {
+                out.info(format!(
+                    "{} {}",
+                    style_prompt_text("Best next account:", PromptTone::Accent),
+                    style_prompt_text(
+                        &format!("{} ({})", index + 1, account.label),
+                        PromptTone::Success
+                    )
+                ));
+                out.info(format!(
+                    "{} {}",
+                    style_prompt_text("Why:", PromptTone::Accent),
+                    style_prompt_text(&recommendation.reason, PromptTone::Muted)
+                ));
+                if index != active_index {
+                    out.info(format!(
+                        "{} codex-multi-auth switch {}",
+                        style_prompt_text("Switch now with:", PromptTone::Accent),
+                        index + 1
+                    ));
+                }
+            }
+        } else {
+            out.info(format!(
+                "{} {}",
+                style_prompt_text("Note:", PromptTone::Accent),
+                style_prompt_text(&recommendation.reason, PromptTone::Muted)
+            ));
+        }
+    }
+
+    if options.explain {
+        out.info(format!(
+            "{} {}",
+            style_prompt_text("Explain:", PromptTone::Accent),
+            style_prompt_text(&explanation.recommendation_reason, PromptTone::Muted)
+        ));
+        for item in &explanation.considered {
+            let selected_label = if item.selected { " selected" } else { "" };
+            let wait_label = if item.wait_ms > 0 {
+                format!(", wait {}", format_wait_time(item.wait_ms))
+            } else {
+                String::new()
+            };
+            let tone = if item.selected {
+                PromptTone::Success
+            } else {
+                PromptTone::Muted
+            };
+            out.info(format!(
+                "  {} {}",
+                style_prompt_text(if item.selected { "*" } else { "-" }, tone),
+                style_prompt_text(
+                    &format!(
+                        "{}. {}{}: {}, {} risk ({}){wait_label}{selected_label}",
+                        item.index + 1,
+                        item.label,
+                        if item.is_current { " [current]" } else { "" },
+                        item.availability.as_str(),
+                        item.risk_level.as_str(),
+                        item.risk_score
+                    ),
+                    tone
+                )
+            ));
+            if !item.reasons.is_empty() {
+                out.info(format!(
+                    "    {}",
+                    style_prompt_text(
+                        &item
+                            .reasons
+                            .iter()
+                            .take(3)
+                            .cloned()
+                            .collect::<Vec<_>>()
+                            .join("; "),
+                        PromptTone::Muted
+                    )
+                ));
+            }
+        }
+    }
+
+    if display.show_live_probe_notes && !probe_errors.is_empty() {
+        out.info("");
+        out.info(style_prompt_text(
+            &format!("Live check notes ({}):", probe_errors.len()),
+            PromptTone::Warning,
+        ));
+        for error in &probe_errors {
+            out.info(format!(
+                "  {} {}",
+                style_prompt_text("-", PromptTone::Warning),
+                style_prompt_text(error, PromptTone::Muted)
+            ));
+        }
+    }
+    if quota_cache_changed {
+        // Best-effort save; tolerate transient Windows EBUSY/EPERM without
+        // aborting the forecast (the Rust saver never propagates).
+        cma_quota::cache::save_quota_cache(&working_quota_cache).await;
+    }
+
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    // Port of test/codex-manager-forecast-command.test.ts (non-live surface).
+
+    #[test]
+    fn parse_accepts_the_forecast_flag_set() {
+        let options = parse_forecast_args(&args(&[
+            "--live",
+            "--json",
+            "--explain",
+            "--no-runtime-overlay",
+            "--model=gpt-5.5",
+        ]))
+        .unwrap();
+        assert!(options.live);
+        assert!(options.json);
+        assert!(options.explain);
+        assert!(!options.runtime_overlay);
+        assert_eq!(options.model, "gpt-5.5");
+    }
+
+    #[test]
+    fn parse_rejects_missing_model_and_unknown_options() {
+        assert_eq!(
+            parse_forecast_args(&args(&["--model"])),
+            Err("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_forecast_args(&args(&["--model", "--json"])),
+            Err("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_forecast_args(&args(&["--bogus"])),
+            Err("Unknown option: --bogus".to_string())
+        );
+    }
+
+    #[test]
+    fn model_without_live_is_accepted_unlike_best() {
+        // spec 08 gotcha 4.
+        let options = parse_forecast_args(&args(&["--model", "gpt-5.5"])).unwrap();
+        assert_eq!(options.model, "gpt-5.5");
+        assert!(!options.live);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_accounts_exits_zero_with_message() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_forecast_command(&[], &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "No accounts configured.");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn parse_error_prints_message_then_usage_and_exits_one() {
+        let _sandbox = EnvSandbox::new();
+        let mut out = CliOut::capture();
+        let code = run_forecast_command(&args(&["--bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown option: --bogus");
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[test]
+    fn snapshot_overlay_keeps_only_string_reasons_and_valid_indexes() {
+        let mut snapshot = cma_runtime::observability::create_default_snapshot();
+        snapshot
+            .account_skip_reasons
+            .insert("0".to_string(), serde_json::json!("rate-limited"));
+        snapshot
+            .account_skip_reasons
+            .insert("1".to_string(), serde_json::json!(42));
+        snapshot
+            .last_pool_exhaustion_skip_reasons
+            .insert("2".to_string(), serde_json::json!("cooldown"));
+        snapshot.policy_blocked_indexes = vec![-1, 0, 3];
+        let overlay = snapshot_to_overlay(&snapshot);
+        assert_eq!(
+            overlay.account_skip_reasons.get("0").map(String::as_str),
+            Some("rate-limited")
+        );
+        assert!(!overlay.account_skip_reasons.contains_key("1"));
+        assert_eq!(
+            overlay
+                .last_pool_exhaustion_skip_reasons
+                .get("2")
+                .map(String::as_str),
+            Some("cooldown")
+        );
+        assert_eq!(overlay.policy_blocked_indexes, vec![0, 3]);
+    }
+}
diff --git a/crates/manager/src/commands/history.rs b/crates/manager/src/commands/history.rs
new file mode 100644
index 000000000..7c7296e95
--- /dev/null
+++ b/crates/manager/src/commands/history.rs
@@ -0,0 +1,832 @@
+//! Port of `lib/codex-manager/commands/history.ts`.
+//!
+//! `history [list|show <id>] [--json]` — provider-agnostic local session
+//! browser over `~/.codex/sessions` rollout files (issue #612: bypasses
+//! `/resume` provider filtering). Read-only; no network; tolerant of
+//! malformed JSONL lines and partially-written rollouts.
+
+use std::path::Path;
+
+use chrono::{SecondsFormat, Utc};
+use cma_core::json_io::stringify_pretty2;
+use serde::Serialize;
+use serde_json::{Value, json};
+
+use crate::dispatcher::{CliOut, js_len_utf16, js_slice_utf16};
+
+pub const DEFAULT_PREVIEW_MESSAGE_COUNT: usize = 3;
+pub const MAX_THREAD_NAME_LENGTH: usize = 80;
+
+/// TS `HistorySessionSummary` (list JSON key order).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct HistorySessionSummary {
+    pub id: String,
+    #[serde(rename = "threadName")]
+    pub thread_name: String,
+    #[serde(rename = "updatedAt")]
+    pub updated_at: String,
+    pub provider: Option<String>,
+    pub originator: Option<String>,
+    pub cwd: Option<String>,
+    pub path: String,
+}
+
+/// TS `HistorySessionDetail` (show JSON key order).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct HistorySessionDetail {
+    pub id: String,
+    #[serde(rename = "threadName")]
+    pub thread_name: String,
+    #[serde(rename = "updatedAt")]
+    pub updated_at: String,
+    pub provider: Option<String>,
+    pub originator: Option<String>,
+    pub cwd: Option<String>,
+    #[serde(rename = "cliVersion")]
+    pub cli_version: Option<String>,
+    pub messages: Vec<String>,
+    pub path: String,
+}
+
+impl HistorySessionDetail {
+    fn to_summary(&self) -> HistorySessionSummary {
+        HistorySessionSummary {
+            id: self.id.clone(),
+            thread_name: self.thread_name.clone(),
+            updated_at: self.updated_at.clone(),
+            provider: self.provider.clone(),
+            originator: self.originator.clone(),
+            cwd: self.cwd.clone(),
+            path: self.path.clone(),
+        }
+    }
+}
+
+/// `getCodexHome` seam.
+pub type GetCodexHomeFn = Box<dyn Fn() -> String>;
+/// `readDirRecursive` seam.
+pub type ReadDirRecursiveFn = Box<dyn Fn(&str) -> Vec<String>>;
+/// `readFile` / `statMtime` seams (mtime as an ISO-8601 string).
+pub type ReadFileFn = Box<dyn Fn(&str) -> Result<String, String>>;
+
+/// Injectable IO (the TS `HistoryCommandDeps`); `None` fields use the real
+/// filesystem.
+#[derive(Default)]
+pub struct HistoryCommandDeps {
+    pub get_codex_home: Option<GetCodexHomeFn>,
+    pub read_dir_recursive: Option<ReadDirRecursiveFn>,
+    pub read_file: Option<ReadFileFn>,
+    /// Returns the file mtime as an ISO-8601 string.
+    pub stat_mtime_iso: Option<ReadFileFn>,
+}
+
+/// TS `ROLLOUT_FILENAME_PATTERN` (case-insensitive), hand-rolled — returns
+/// the captured session UUID (original casing) or `None`.
+pub fn rollout_session_id(file_name: &str) -> Option<String> {
+    // rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-<uuid 8-4-4-4-12>.jsonl
+    const TOTAL_LEN: usize = 8 + 10 + 1 + 8 + 1 + 36 + 6;
+    if file_name.len() != TOTAL_LEN || !file_name.is_ascii() {
+        return None;
+    }
+    let bytes = file_name.as_bytes();
+    let lower = file_name.to_ascii_lowercase();
+    if !lower.starts_with("rollout-") {
+        return None;
+    }
+    let digit = |i: usize| bytes[i].is_ascii_digit();
+    let dash = |i: usize| bytes[i] == b'-';
+    // date: positions 8..18 = dddd-dd-dd
+    for i in 8..12 {
+        if !digit(i) {
+            return None;
+        }
+    }
+    if !dash(12) || !digit(13) || !digit(14) || !dash(15) || !digit(16) || !digit(17) {
+        return None;
+    }
+    // 'T' (case-insensitive) at 18; time dd-dd-dd at 19..27
+    if lower.as_bytes()[18] != b't' {
+        return None;
+    }
+    for (start, sep) in [(19usize, 21usize), (22, 24), (25, 27)] {
+        if !digit(start) || !digit(start + 1) {
+            return None;
+        }
+        if sep < 27 && !dash(sep) {
+            return None;
+        }
+    }
+    if !dash(27) {
+        return None;
+    }
+    // uuid at 28..64: 8-4-4-4-12 lowercase-or-uppercase hex
+    let uuid = &file_name[28..64];
+    let uuid_lower = &lower[28..64];
+    let groups = [8usize, 4, 4, 4, 12];
+    let mut cursor = 0usize;
+    for (group_index, group_len) in groups.iter().enumerate() {
+        for _ in 0..*group_len {
+            let b = uuid_lower.as_bytes()[cursor];
+            if !b.is_ascii_hexdigit() || b.is_ascii_uppercase() {
+                return None;
+            }
+            cursor += 1;
+        }
+        if group_index < groups.len() - 1 {
+            if uuid_lower.as_bytes()[cursor] != b'-' {
+                return None;
+            }
+            cursor += 1;
+        }
+    }
+    if &lower[64..] != ".jsonl" {
+        return None;
+    }
+    Some(uuid.to_string())
+}
+
+/// Separator-agnostic basename (rollout paths may carry Windows separators
+/// even on POSIX).
+fn base_name_of(file_path: &str) -> &str {
+    file_path
+        .rsplit(['\\', '/'])
+        .next()
+        .unwrap_or(file_path)
+}
+
+fn read_string_field(record: Option<&Value>, key: &str) -> Option<String> {
+    let value = record?.get(key)?.as_str()?;
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `parseRollout` — parse one rollout JSONL file into a session detail.
+/// Returns `None` for unreadable files, non-rollout names, or files without
+/// a `session_meta` record.
+pub fn parse_rollout(
+    rollout_path: &str,
+    read_file: &dyn Fn(&str) -> Result<String, String>,
+    stat_mtime_iso: &dyn Fn(&str) -> Result<String, String>,
+    preview_limit: usize,
+) -> Option<HistorySessionDetail> {
+    let id_from_name = rollout_session_id(base_name_of(rollout_path))?;
+    let content = read_file(rollout_path).ok()?;
+
+    let mut id = id_from_name;
+    let mut thread_name = String::new();
+    let mut updated_at: Option<String> = None;
+    let mut provider: Option<String> = None;
+    let mut originator: Option<String> = None;
+    let mut cwd: Option<String> = None;
+    let mut cli_version: Option<String> = None;
+    let mut has_session_meta = false;
+    let mut messages: Vec<String> = Vec::new();
+
+    for line in content.split('\n') {
+        let line = line.strip_suffix('\r').unwrap_or(line);
+        if line.trim().is_empty() {
+            continue;
+        }
+        // Tolerate malformed/partial lines; a single bad line must not drop
+        // the whole session from the listing.
+        let Ok(record) = serde_json::from_str::<Value>(line) else {
+            continue;
+        };
+
+        if let Some(timestamp) = record.get("timestamp").and_then(Value::as_str) {
+            updated_at = Some(timestamp.to_string());
+        }
+
+        let record_type = record.get("type").and_then(Value::as_str);
+        let payload = record.get("payload");
+
+        if record_type == Some("session_meta") {
+            if let Some(meta_id) = read_string_field(payload, "id") {
+                id = meta_id;
+            }
+            provider = read_string_field(payload, "model_provider").or(provider);
+            originator = read_string_field(payload, "originator").or(originator);
+            cwd = read_string_field(payload, "cwd").or(cwd);
+            cli_version = read_string_field(payload, "cli_version").or(cli_version);
+            has_session_meta = true;
+        }
+
+        if record_type == Some("event_msg") {
+            let payload_type = read_string_field(payload, "type");
+            if thread_name.is_empty()
+                && payload_type.is_some()
+                && let Some(message) = read_string_field(payload, "message")
+            {
+                thread_name = message;
+            }
+            if payload_type.as_deref() == Some("user_message")
+                && messages.len() < preview_limit
+                && let Some(message) = read_string_field(payload, "message")
+            {
+                messages.push(message);
+            }
+        }
+    }
+
+    if !has_session_meta {
+        return None;
+    }
+
+    let updated_at = updated_at.unwrap_or_else(|| {
+        stat_mtime_iso(rollout_path)
+            .unwrap_or_else(|_| Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true))
+    });
+
+    if thread_name.is_empty() {
+        thread_name = "Codex session".to_string();
+    }
+    if js_len_utf16(&thread_name) > MAX_THREAD_NAME_LENGTH {
+        thread_name = format!(
+            "{}...",
+            js_slice_utf16(&thread_name, MAX_THREAD_NAME_LENGTH - 3)
+        );
+    }
+
+    Some(HistorySessionDetail {
+        id,
+        thread_name,
+        updated_at,
+        provider,
+        originator,
+        cwd,
+        cli_version,
+        messages,
+        path: rollout_path.to_string(),
+    })
+}
+
+fn default_read_dir_recursive(dir: &str) -> Vec<String> {
+    let mut results: Vec<String> = Vec::new();
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return results;
+    };
+    for entry in entries.flatten() {
+        let entry_path = entry.path();
+        let file_type = entry.file_type();
+        if file_type.as_ref().map(|t| t.is_dir()).unwrap_or(false) {
+            results.extend(default_read_dir_recursive(&entry_path.to_string_lossy()));
+            continue;
+        }
+        if file_type.map(|t| t.is_file()).unwrap_or(false) {
+            let name = entry.file_name().to_string_lossy().into_owned();
+            if rollout_session_id(&name).is_some() {
+                results.push(entry_path.to_string_lossy().into_owned());
+            }
+        }
+    }
+    results
+}
+
+struct ResolvedDeps<'a> {
+    get_codex_home: &'a dyn Fn() -> String,
+    read_dir_recursive: &'a dyn Fn(&str) -> Vec<String>,
+    read_file: &'a dyn Fn(&str) -> Result<String, String>,
+    stat_mtime_iso: &'a dyn Fn(&str) -> Result<String, String>,
+}
+
+fn sessions_dir(resolved: &ResolvedDeps<'_>) -> String {
+    Path::new(&(resolved.get_codex_home)())
+        .join("sessions")
+        .to_string_lossy()
+        .into_owned()
+}
+
+fn collect_sessions(resolved: &ResolvedDeps<'_>, preview_limit: usize) -> Vec<HistorySessionDetail> {
+    let dir = sessions_dir(resolved);
+    // A missing or unreadable sessions directory is a normal "no history
+    // yet" state, not an error.
+    let files = (resolved.read_dir_recursive)(&dir);
+    let mut sessions: Vec<HistorySessionDetail> = files
+        .iter()
+        .filter_map(|file| {
+            parse_rollout(file, resolved.read_file, resolved.stat_mtime_iso, preview_limit)
+        })
+        .collect();
+    // Most-recent first, matching how /resume presents threads.
+    sessions.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+    sessions
+}
+
+fn print_history_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage: codex-multi-auth history <list|show> [options]",
+            "",
+            "  list [--json]            List every local session across all providers",
+            "  show <id> [--json]       Show provider metadata and first messages for a session",
+            "",
+            "Lists rollout files under <codex-home>/sessions (default",
+            "~/.codex/sessions, honoring CODEX_HOME) directly, so sessions",
+            "created under a different model provider (e.g. while runtime rotation",
+            "or app bind is active) remain visible even when `codex resume` hides",
+            "them. See docs/troubleshooting.md for background.",
+        ]
+        .join("\n"),
+    );
+}
+
+fn run_history_list(args: &[String], resolved: &ResolvedDeps<'_>, out: &mut CliOut) -> i32 {
+    let json = args.iter().any(|arg| arg == "--json" || arg == "-j");
+    let sessions = collect_sessions(resolved, DEFAULT_PREVIEW_MESSAGE_COUNT);
+
+    if json {
+        out.info(stringify_pretty2(&json!({
+            "count": sessions.len(),
+            "sessions": sessions.iter().map(HistorySessionDetail::to_summary).collect::<Vec<_>>(),
+        })));
+        return 0;
+    }
+
+    if sessions.is_empty() {
+        out.info(format!(
+            "No local Codex sessions found under {}.",
+            sessions_dir(resolved)
+        ));
+        return 0;
+    }
+
+    out.info(format!(
+        "Local Codex sessions ({}) — all providers, bypassing /resume provider filtering:",
+        sessions.len()
+    ));
+    out.info("");
+    for session in &sessions {
+        let provider = session.provider.as_deref().unwrap_or("unknown-provider");
+        out.info(format!("  {}  [{}]", session.updated_at, provider));
+        out.info(format!("    id:     {}", session.id));
+        out.info(format!("    thread: {}", session.thread_name));
+        if let Some(cwd) = &session.cwd {
+            out.info(format!("    cwd:    {cwd}"));
+        }
+    }
+    out.info("");
+    out.info("Resume any session with: codex resume <id>  (or `codex resume` for the picker).");
+    0
+}
+
+fn run_history_show(args: &[String], resolved: &ResolvedDeps<'_>, out: &mut CliOut) -> i32 {
+    let json = args.iter().any(|arg| arg == "--json" || arg == "-j");
+    let session_id = args.iter().find(|arg| !arg.starts_with('-'));
+    let Some(session_id) = session_id else {
+        out.error(
+            "Missing session id. Usage: codex-multi-auth history show <session-id> [--json]",
+        );
+        return 1;
+    };
+
+    let sessions = collect_sessions(resolved, DEFAULT_PREVIEW_MESSAGE_COUNT);
+    let Some(session) = sessions.iter().find(|session| &session.id == session_id) else {
+        out.error(format!("Session not found: {session_id}"));
+        return 1;
+    };
+
+    if json {
+        out.info(stringify_pretty2(session));
+        return 0;
+    }
+
+    out.info(format!("Session {}", session.id));
+    out.info(format!(
+        "  provider:   {}",
+        session.provider.as_deref().unwrap_or("unknown")
+    ));
+    out.info(format!(
+        "  originator: {}",
+        session.originator.as_deref().unwrap_or("unknown")
+    ));
+    out.info(format!("  updated:    {}", session.updated_at));
+    if let Some(cli_version) = &session.cli_version {
+        out.info(format!("  cli:        {cli_version}"));
+    }
+    if let Some(cwd) = &session.cwd {
+        out.info(format!("  cwd:        {cwd}"));
+    }
+    out.info(format!("  file:       {}", session.path));
+    out.info("");
+    if session.messages.is_empty() {
+        out.info("  (no user messages recorded)");
+    } else {
+        out.info("  First messages:");
+        for message in &session.messages {
+            let first_line = message
+                .split('\n')
+                .next()
+                .map(|line| line.strip_suffix('\r').unwrap_or(line))
+                .unwrap_or("");
+            let preview = if js_len_utf16(first_line) > 120 {
+                format!("{}...", js_slice_utf16(first_line, 117))
+            } else {
+                first_line.to_string()
+            };
+            out.info(format!("    - {preview}"));
+        }
+    }
+    out.info("");
+    out.info(format!("Resume with: codex resume {}", session.id));
+    0
+}
+
+/// Deps-injectable core (the TS `runHistoryCommand(args, deps)`).
+pub fn run_history_command_with(
+    args: &[String],
+    deps: &HistoryCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    let default_home = || {
+        cma_core::runtime_paths::get_codex_home_dir()
+            .to_string_lossy()
+            .into_owned()
+    };
+    let default_read_dir = |dir: &str| default_read_dir_recursive(dir);
+    let default_read_file =
+        |path: &str| std::fs::read_to_string(path).map_err(|error| error.to_string());
+    let default_stat = |path: &str| {
+        std::fs::metadata(path)
+            .and_then(|meta| meta.modified())
+            .map(|mtime| {
+                chrono::DateTime::<Utc>::from(mtime).to_rfc3339_opts(SecondsFormat::Millis, true)
+            })
+            .map_err(|error| error.to_string())
+    };
+    let resolved = ResolvedDeps {
+        get_codex_home: deps
+            .get_codex_home
+            .as_deref()
+            .unwrap_or(&default_home),
+        read_dir_recursive: deps
+            .read_dir_recursive
+            .as_deref()
+            .unwrap_or(&default_read_dir),
+        read_file: deps.read_file.as_deref().unwrap_or(&default_read_file),
+        stat_mtime_iso: deps
+            .stat_mtime_iso
+            .as_deref()
+            .unwrap_or(&default_stat),
+    };
+
+    let subcommand = args.first().map(String::as_str);
+    let rest: Vec<String> = if args.len() > 1 {
+        args[1..].to_vec()
+    } else {
+        Vec::new()
+    };
+
+    if subcommand == Some("--help") || subcommand == Some("-h") {
+        print_history_usage(out);
+        return 0;
+    }
+
+    // Default to `list` when no subcommand is given; a leading flag is
+    // forwarded as a list argument (`history --json` works).
+    match subcommand {
+        None | Some("list") => run_history_list(&rest, &resolved, out),
+        Some(sub) if sub.starts_with('-') => {
+            let mut list_args = vec![sub.to_string()];
+            list_args.extend(rest);
+            run_history_list(&list_args, &resolved, out)
+        }
+        Some("show") => run_history_show(&rest, &resolved, out),
+        Some(sub) => {
+            out.error(format!("Unknown history command: {sub}"));
+            print_history_usage(out);
+            1
+        }
+    }
+}
+
+/// Production entry (real filesystem).
+pub fn run_history_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_history_command_with(args, &HistoryCommandDeps::default(), out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    const DIR: &str = "/home/user/.codex/sessions";
+
+    fn meta_line(overrides: &[(&str, &str)], timestamp: &str) -> String {
+        let mut payload = serde_json::json!({
+            "id": "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            "timestamp": timestamp,
+            "cwd": "C:\\work\\project",
+            "originator": "Codex Desktop",
+            "cli_version": "0.140.0",
+            "model_provider": "openai",
+        });
+        for (key, value) in overrides {
+            payload[*key] = serde_json::json!(value);
+        }
+        serde_json::json!({
+            "timestamp": timestamp,
+            "type": "session_meta",
+            "payload": payload,
+        })
+        .to_string()
+    }
+
+    fn user_message_line(message: &str) -> String {
+        serde_json::json!({
+            "timestamp": "2026-06-05T14:36:25.000Z",
+            "type": "event_msg",
+            "payload": { "type": "user_message", "message": message },
+        })
+        .to_string()
+    }
+
+    fn rollout_path(id: &str) -> String {
+        format!("{DIR}/2026/06/05/rollout-2026-06-05T22-35-56-{id}.jsonl")
+    }
+
+    fn deps_for(files: &[(&str, String)]) -> HistoryCommandDeps {
+        let by_path: HashMap<String, String> = files
+            .iter()
+            .map(|(id, content)| (rollout_path(id), content.clone()))
+            .collect();
+        let paths: Vec<String> = by_path.keys().cloned().collect();
+        let read_map = by_path.clone();
+        HistoryCommandDeps {
+            get_codex_home: Some(Box::new(|| "/home/user/.codex".to_string())),
+            read_dir_recursive: Some(Box::new(move |_dir| paths.clone())),
+            read_file: Some(Box::new(move |path| {
+                read_map
+                    .get(path)
+                    .cloned()
+                    .ok_or_else(|| format!("ENOENT: {path}"))
+            })),
+            stat_mtime_iso: Some(Box::new(|_path| Ok("2026-01-01T00:00:00.000Z".to_string()))),
+        }
+    }
+
+    // Port of test/codex-manager-history-command.test.ts.
+
+    #[test]
+    fn lists_sessions_from_every_provider() {
+        let deps = deps_for(&[
+            (
+                "019e9836-5001-7821-a9c2-3ffd26a1199b",
+                [
+                    meta_line(
+                        &[("id", "019e9836-5001-7821-a9c2-3ffd26a1199b"), ("model_provider", "openai")],
+                        "2026-06-05T10:00:00.000Z",
+                    ),
+                    user_message_line("first openai task"),
+                ]
+                .join("\n"),
+            ),
+            (
+                "0190abcd-1234-7821-a9c2-3ffd26a11000",
+                [
+                    meta_line(
+                        &[
+                            ("id", "0190abcd-1234-7821-a9c2-3ffd26a11000"),
+                            ("model_provider", "codex-multi-auth-runtime-proxy"),
+                        ],
+                        "2026-06-05T12:00:00.000Z",
+                    ),
+                    user_message_line("a rotated session"),
+                ]
+                .join("\n"),
+            ),
+        ]);
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&["list".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let output = out.info_text();
+        assert!(output.contains("openai"));
+        assert!(output.contains("codex-multi-auth-runtime-proxy"));
+        assert!(output.contains("019e9836-5001-7821-a9c2-3ffd26a1199b"));
+        assert!(output.contains("0190abcd-1234-7821-a9c2-3ffd26a11000"));
+    }
+
+    #[test]
+    fn defaults_to_list_when_no_subcommand() {
+        let deps = deps_for(&[(
+            "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            meta_line(&[], "2026-06-05T14:36:20.000Z"),
+        )]);
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&[], &deps, &mut out);
+        assert_eq!(code, 0);
+        assert!(out.info_text().contains("019e9836-5001-7821-a9c2-3ffd26a1199b"));
+    }
+
+    #[test]
+    fn sorts_most_recent_first() {
+        let deps = deps_for(&[
+            (
+                "00000000-0000-7821-a9c2-00000000aaaa",
+                meta_line(
+                    &[("id", "00000000-0000-7821-a9c2-00000000aaaa")],
+                    "2026-06-01T00:00:00.000Z",
+                ),
+            ),
+            (
+                "11111111-1111-7821-a9c2-11111111bbbb",
+                meta_line(
+                    &[("id", "11111111-1111-7821-a9c2-11111111bbbb")],
+                    "2026-06-10T00:00:00.000Z",
+                ),
+            ),
+        ]);
+        let mut out = CliOut::capture();
+        let code =
+            run_history_command_with(&["list".to_string(), "--json".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["count"], 2);
+        assert_eq!(payload["sessions"][0]["id"], "11111111-1111-7821-a9c2-11111111bbbb");
+        assert_eq!(payload["sessions"][1]["id"], "00000000-0000-7821-a9c2-00000000aaaa");
+    }
+
+    #[test]
+    fn json_summaries_omit_detail_fields() {
+        let deps = deps_for(&[(
+            "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            meta_line(
+                &[("model_provider", "codex-multi-auth-runtime-proxy")],
+                "2026-06-05T14:36:20.000Z",
+            ),
+        )]);
+        let mut out = CliOut::capture();
+        let code =
+            run_history_command_with(&["list".to_string(), "--json".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["count"], 1);
+        assert_eq!(
+            payload["sessions"][0]["provider"],
+            "codex-multi-auth-runtime-proxy"
+        );
+        assert!(payload["sessions"][0].get("messages").is_none());
+        assert!(payload["sessions"][0].get("cliVersion").is_none());
+    }
+
+    #[test]
+    fn empty_listing_without_error_when_dir_missing() {
+        let deps = HistoryCommandDeps {
+            get_codex_home: Some(Box::new(|| "/home/user/.codex".to_string())),
+            read_dir_recursive: Some(Box::new(|_dir| Vec::new())),
+            read_file: Some(Box::new(|path| Err(format!("ENOENT: {path}")))),
+            stat_mtime_iso: Some(Box::new(|_path| Ok("2026-01-01T00:00:00.000Z".to_string()))),
+        };
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&["list".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        assert!(out.info_text().contains("No local Codex sessions found"));
+    }
+
+    #[test]
+    fn treats_leading_flag_as_list_arg() {
+        let deps = deps_for(&[(
+            "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            meta_line(&[], "2026-06-05T14:36:20.000Z"),
+        )]);
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&["--json".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["count"], 1);
+    }
+
+    #[test]
+    fn malformed_lines_are_skipped_and_meta_required() {
+        let deps = deps_for(&[
+            (
+                "019e9836-5001-7821-a9c2-3ffd26a1199b",
+                [
+                    "{not json".to_string(),
+                    meta_line(&[], "2026-06-05T14:36:20.000Z"),
+                    "".to_string(),
+                    user_message_line("kept"),
+                ]
+                .join("\n"),
+            ),
+            (
+                // No session_meta → skipped entirely.
+                "0190abcd-1234-7821-a9c2-3ffd26a11000",
+                user_message_line("orphan"),
+            ),
+        ]);
+        let mut out = CliOut::capture();
+        let code =
+            run_history_command_with(&["list".to_string(), "--json".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        assert_eq!(payload["count"], 1);
+    }
+
+    #[test]
+    fn show_prints_detail_and_errors() {
+        let deps = deps_for(&[(
+            "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            [
+                meta_line(&[], "2026-06-05T14:36:20.000Z"),
+                user_message_line("hello there"),
+            ]
+            .join("\n"),
+        )]);
+
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&["show".to_string()], &deps, &mut out);
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "Missing session id. Usage: codex-multi-auth history show <session-id> [--json]"
+        );
+
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(
+            &["show".to_string(), "missing-id".to_string()],
+            &deps,
+            &mut out,
+        );
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Session not found: missing-id");
+
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(
+            &[
+                "show".to_string(),
+                "019e9836-5001-7821-a9c2-3ffd26a1199b".to_string(),
+            ],
+            &deps,
+            &mut out,
+        );
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        assert!(text.starts_with("Session 019e9836-5001-7821-a9c2-3ffd26a1199b"));
+        assert!(text.contains("  provider:   openai"));
+        assert!(text.contains("  originator: Codex Desktop"));
+        assert!(text.contains("  cli:        0.140.0"));
+        assert!(text.contains("    - hello there"));
+        assert!(text.ends_with("Resume with: codex resume 019e9836-5001-7821-a9c2-3ffd26a1199b"));
+    }
+
+    #[test]
+    fn unknown_subcommand_errors_with_usage() {
+        let deps = deps_for(&[]);
+        let mut out = CliOut::capture();
+        let code = run_history_command_with(&["prune".to_string()], &deps, &mut out);
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown history command: prune");
+        assert!(out.info_text().starts_with("Usage: codex-multi-auth history"));
+    }
+
+    #[test]
+    fn rollout_filename_pattern_matches_ts_regex() {
+        assert_eq!(
+            rollout_session_id("rollout-2026-06-05T22-35-56-019e9836-5001-7821-a9c2-3ffd26a1199b.jsonl"),
+            Some("019e9836-5001-7821-a9c2-3ffd26a1199b".to_string())
+        );
+        // Case-insensitive flag on the TS regex.
+        assert_eq!(
+            rollout_session_id("ROLLOUT-2026-06-05T22-35-56-019E9836-5001-7821-A9C2-3FFD26A1199B.JSONL"),
+            Some("019E9836-5001-7821-A9C2-3FFD26A1199B".to_string())
+        );
+        assert_eq!(rollout_session_id("rollout-2026-06-05.jsonl"), None);
+        assert_eq!(
+            rollout_session_id("rollout-2026-06-05T22-35-56-not-a-uuid.jsonl"),
+            None
+        );
+        assert_eq!(
+            rollout_session_id("prefix-rollout-2026-06-05T22-35-56-019e9836-5001-7821-a9c2-3ffd26a1199b.jsonl"),
+            None
+        );
+    }
+
+    #[test]
+    fn thread_name_truncates_at_80_utf16_units() {
+        let long = "x".repeat(100);
+        let deps = deps_for(&[(
+            "019e9836-5001-7821-a9c2-3ffd26a1199b",
+            [
+                meta_line(&[], "2026-06-05T14:36:20.000Z"),
+                serde_json::json!({
+                    "type": "event_msg",
+                    "payload": { "type": "agent_message", "message": long },
+                })
+                .to_string(),
+            ]
+            .join("\n"),
+        )]);
+        let mut out = CliOut::capture();
+        let code =
+            run_history_command_with(&["list".to_string(), "--json".to_string()], &deps, &mut out);
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).unwrap();
+        let thread = payload["sessions"][0]["threadName"].as_str().unwrap();
+        assert_eq!(thread.len(), 80);
+        assert!(thread.ends_with("..."));
+    }
+}
diff --git a/crates/manager/src/commands/init_config.rs b/crates/manager/src/commands/init_config.rs
new file mode 100644
index 000000000..6ab1714a1
--- /dev/null
+++ b/crates/manager/src/commands/init_config.rs
@@ -0,0 +1,356 @@
+//! Port of `lib/codex-manager/commands/init-config.ts`.
+//!
+//! `init-config` / `config template` — emit one of the three shipped Codex
+//! config templates. Per spec 08 gotcha 23 the Rust port embeds the template
+//! bytes at compile time instead of resolving the repo root at runtime.
+
+use std::path::{Component, Path, PathBuf};
+
+use crate::dispatcher::CliOut;
+
+const TEMPLATE_MODERN: &str = include_str!("../../../../config/codex-modern.json");
+const TEMPLATE_LEGACY: &str = include_str!("../../../../config/codex-legacy.json");
+const TEMPLATE_MINIMAL: &str = include_str!("../../../../config/minimal-codex.json");
+
+/// Template selector (TS `TEMPLATE_MAP` keys).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TemplateName {
+    Modern,
+    Legacy,
+    Minimal,
+}
+
+impl TemplateName {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            TemplateName::Modern => "modern",
+            TemplateName::Legacy => "legacy",
+            TemplateName::Minimal => "minimal",
+        }
+    }
+
+    fn content(self) -> &'static str {
+        match self {
+            TemplateName::Modern => TEMPLATE_MODERN,
+            TemplateName::Legacy => TEMPLATE_LEGACY,
+            TemplateName::Minimal => TEMPLATE_MINIMAL,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum ParsedArgs {
+    Ok {
+        template: TemplateName,
+        stdout: bool,
+        write_path: Option<String>,
+    },
+    Error(String),
+}
+
+fn parse_args(args: &[String]) -> ParsedArgs {
+    let mut template = TemplateName::Modern;
+    let mut stdout = true;
+    let mut write_path: Option<String> = None;
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        match arg {
+            "modern" => {
+                template = TemplateName::Modern;
+                i += 1;
+                continue;
+            }
+            "legacy" => {
+                template = TemplateName::Legacy;
+                i += 1;
+                continue;
+            }
+            "minimal" => {
+                template = TemplateName::Minimal;
+                i += 1;
+                continue;
+            }
+            "--stdout" => {
+                stdout = true;
+                i += 1;
+                continue;
+            }
+            "--write" => {
+                let Some(next) = args.get(i + 1).filter(|value| !value.is_empty()) else {
+                    return ParsedArgs::Error("Missing value for --write".to_string());
+                };
+                write_path = Some(next.clone());
+                stdout = false;
+                i += 2;
+                continue;
+            }
+            _ => {}
+        }
+        if let Some(raw) = arg.strip_prefix("--write=") {
+            let value = raw.trim();
+            if value.is_empty() {
+                return ParsedArgs::Error("Missing value for --write".to_string());
+            }
+            write_path = Some(value.to_string());
+            stdout = false;
+            i += 1;
+            continue;
+        }
+        return ParsedArgs::Error(format!("Unknown option: {arg}"));
+    }
+
+    ParsedArgs::Ok {
+        template,
+        stdout,
+        write_path,
+    }
+}
+
+/// Node `path.resolve(cwd, target)` — absolute wins, otherwise join, then
+/// lexically collapse `.`/`..` components.
+fn resolve_from(cwd: &Path, target: &str) -> PathBuf {
+    let target_path = Path::new(target);
+    let joined = if target_path.is_absolute() {
+        target_path.to_path_buf()
+    } else {
+        cwd.join(target_path)
+    };
+    let mut normalized = PathBuf::new();
+    for component in joined.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !normalized.pop() {
+                    normalized.push(component.as_os_str());
+                }
+            }
+            other => normalized.push(other.as_os_str()),
+        }
+    }
+    normalized
+}
+
+/// Seam-injectable core (the TS deps: readTemplate / writeTemplate / cwd).
+pub async fn run_init_config_with(
+    args: &[String],
+    read_template: impl FnOnce(TemplateName) -> Result<String, String>,
+    write_template: impl FnOnce(&Path, &str) -> Result<(), String>,
+    cwd: &Path,
+    out: &mut CliOut,
+) -> i32 {
+    let parsed = match parse_args(args) {
+        ParsedArgs::Ok {
+            template,
+            stdout,
+            write_path,
+        } => (template, stdout, write_path),
+        ParsedArgs::Error(message) => {
+            out.error(message);
+            return 1;
+        }
+    };
+    let (template, stdout, write_path) = parsed;
+
+    let content = match read_template(template) {
+        Ok(content) => content,
+        Err(message) => {
+            out.error(message);
+            return 1;
+        }
+    };
+
+    if stdout || write_path.is_none() {
+        out.info(content.trim_end().to_string());
+        return 0;
+    }
+
+    let output_path = resolve_from(cwd, write_path.as_deref().unwrap_or(""));
+    let final_content = if content.ends_with('\n') {
+        content
+    } else {
+        format!("{content}\n")
+    };
+    if let Err(message) = write_template(&output_path, &final_content) {
+        out.error(message);
+        return 1;
+    }
+    out.info(format!(
+        "Wrote {} template to {}",
+        template.as_str(),
+        output_path.display()
+    ));
+    0
+}
+
+/// Production entry (TS `runInitConfigCommand(args)`): embedded templates +
+/// plain (non-atomic, TS parity) mkdir+write.
+pub async fn run_init_config_command(args: &[String], out: &mut CliOut) -> i32 {
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    run_init_config_with(
+        args,
+        |template| Ok(template.content().to_string()),
+        |path, content| {
+            if let Some(parent) = path.parent() {
+                std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
+            }
+            std::fs::write(path, content).map_err(|error| error.to_string())
+        },
+        &cwd,
+        out,
+    )
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn no_write(_path: &Path, _content: &str) -> Result<(), String> {
+        panic!("write_template must not be called");
+    }
+
+    // Port of test/init-config-command.test.ts highlights.
+
+    #[tokio::test]
+    async fn defaults_to_the_modern_template_on_stdout() {
+        let mut out = CliOut::capture();
+        let code = run_init_config_with(
+            &[],
+            |template| {
+                assert_eq!(template, TemplateName::Modern);
+                Ok("{ \"a\": 1 }\n\n".to_string())
+            },
+            no_write,
+            Path::new("/work"),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "{ \"a\": 1 }");
+    }
+
+    #[tokio::test]
+    async fn selects_named_templates() {
+        for (name, expected) in [
+            ("legacy", TemplateName::Legacy),
+            ("minimal", TemplateName::Minimal),
+            ("modern", TemplateName::Modern),
+        ] {
+            let mut out = CliOut::capture();
+            let code = run_init_config_with(
+                &args(&[name]),
+                |template| {
+                    assert_eq!(template, expected);
+                    Ok("x".to_string())
+                },
+                no_write,
+                Path::new("/work"),
+                &mut out,
+            )
+            .await;
+            assert_eq!(code, 0);
+        }
+    }
+
+    #[tokio::test]
+    async fn rejects_unknown_options_and_missing_write_values() {
+        let mut out = CliOut::capture();
+        let code = run_init_config_with(
+            &args(&["--bogus"]),
+            |_| Ok(String::new()),
+            no_write,
+            Path::new("/work"),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown option: --bogus");
+
+        for bad in [&["--write"][..], &["--write="]] {
+            let mut out = CliOut::capture();
+            let code = run_init_config_with(
+                &args(bad),
+                |_| Ok(String::new()),
+                no_write,
+                Path::new("/work"),
+                &mut out,
+            )
+            .await;
+            assert_eq!(code, 1);
+            assert_eq!(out.error_text(), "Missing value for --write");
+        }
+    }
+
+    #[tokio::test]
+    async fn write_mode_appends_trailing_newline_and_reports_path() {
+        let mut out = CliOut::capture();
+        let written = std::sync::Mutex::new(Option::<(PathBuf, String)>::None);
+        let code = run_init_config_with(
+            &args(&["minimal", "--write", "out/config.json"]),
+            |_| Ok("{}".to_string()),
+            |path, content| {
+                *written.lock().unwrap() = Some((path.to_path_buf(), content.to_string()));
+                Ok(())
+            },
+            Path::new("/work"),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        let (path, content) = written.lock().unwrap().clone().unwrap();
+        assert_eq!(content, "{}\n");
+        assert!(path.ends_with(Path::new("out/config.json")));
+        let text = out.info_text();
+        assert!(text.starts_with("Wrote minimal template to "));
+        assert!(text.contains("config.json"));
+    }
+
+    #[tokio::test]
+    async fn read_failure_prints_the_message() {
+        let mut out = CliOut::capture();
+        let code = run_init_config_with(
+            &[],
+            |_| Err("ENOENT: template".to_string()),
+            no_write,
+            Path::new("/work"),
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "ENOENT: template");
+    }
+
+    #[test]
+    fn embedded_templates_are_valid_json() {
+        for template in [
+            TemplateName::Modern,
+            TemplateName::Legacy,
+            TemplateName::Minimal,
+        ] {
+            serde_json::from_str::<serde_json::Value>(template.content())
+                .unwrap_or_else(|error| panic!("{} template invalid: {error}", template.as_str()));
+        }
+    }
+
+    #[test]
+    fn resolve_from_collapses_relative_segments() {
+        assert_eq!(
+            resolve_from(Path::new("/work/sub"), "../x.json"),
+            PathBuf::from("/work/x.json")
+        );
+        assert_eq!(
+            resolve_from(Path::new("/work"), "./a/./b.json"),
+            PathBuf::from("/work/a/b.json")
+        );
+    }
+}
diff --git a/crates/manager/src/commands/integrations.rs b/crates/manager/src/commands/integrations.rs
new file mode 100644
index 000000000..43a9f275e
--- /dev/null
+++ b/crates/manager/src/commands/integrations.rs
@@ -0,0 +1,157 @@
+//! Port of `lib/codex-manager/commands/integrations.ts`.
+//!
+//! `integrations [--kind <name>] [--base-url <url>] [--model <model>]
+//! [--json]` — prints copy/paste integration snippets for the local bridge.
+
+use cma_core::json_io::stringify_pretty2;
+use serde_json::json;
+
+use crate::dispatcher::CliOut;
+use crate::integration_generators::{
+    IntegrationSnippetInput, IntegrationSnippetKind, generate_integration_snippets,
+};
+
+fn print_integrations_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth integrations [--kind <name>] [--base-url <url>] [--model <model>] [--json]",
+            "",
+            "Kinds: opencode, openclaw, python, curl, env",
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `runIntegrationsCommand(args, deps)` (sync).
+pub fn run_integrations_command(args: &[String], out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_integrations_usage(out);
+        return 0;
+    }
+    let mut kinds: Vec<IntegrationSnippetKind> = Vec::new();
+    let mut base_url: Option<String> = None;
+    let mut model: Option<String> = None;
+    let mut json = false;
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--json" || arg == "-j" {
+            json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--kind" {
+            let value = args.get(i + 1).and_then(|v| IntegrationSnippetKind::parse(v));
+            let Some(kind) = value else {
+                out.error("Missing or invalid value for --kind");
+                return 1;
+            };
+            kinds.push(kind);
+            i += 2;
+            continue;
+        }
+        if arg == "--base-url" {
+            let Some(value) = args.get(i + 1).filter(|v| !v.is_empty()) else {
+                out.error("Missing value for --base-url");
+                return 1;
+            };
+            base_url = Some(value.clone());
+            i += 2;
+            continue;
+        }
+        if arg == "--model" {
+            let value = args.get(i + 1).map(|v| v.trim().to_string());
+            match value {
+                Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                    model = Some(v);
+                    i += 2;
+                    continue;
+                }
+                _ => {
+                    out.error("Missing value for --model");
+                    return 1;
+                }
+            }
+        }
+        out.error(format!("Unknown integrations option: {arg}"));
+        return 1;
+    }
+    let snippets = generate_integration_snippets(
+        if kinds.is_empty() {
+            None
+        } else {
+            Some(kinds.as_slice())
+        },
+        &IntegrationSnippetInput {
+            base_url,
+            model,
+            env_var: None,
+        },
+    );
+    if json {
+        out.info(stringify_pretty2(&json!({
+            "command": "integrations",
+            "snippets": snippets,
+        })));
+        return 0;
+    }
+    for snippet in &snippets {
+        out.info(format!("# {}", snippet.title));
+        out.info(snippet.body.clone());
+    }
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    // Port of test/codex-manager-integrations-command.test.ts option errors.
+    #[test]
+    fn rejects_unknown_option() {
+        let mut out = CliOut::capture();
+        let code = run_integrations_command(&args(&["--bogus"]), &mut out);
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown integrations option: --bogus");
+    }
+
+    #[test]
+    fn rejects_missing_or_invalid_kind() {
+        let mut out = CliOut::capture();
+        assert_eq!(run_integrations_command(&args(&["--kind"]), &mut out), 1);
+        assert_eq!(out.error_text(), "Missing or invalid value for --kind");
+
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_integrations_command(&args(&["--kind", "bogus"]), &mut out),
+            1
+        );
+        assert_eq!(out.error_text(), "Missing or invalid value for --kind");
+    }
+
+    #[test]
+    fn rejects_missing_base_url_and_model_values() {
+        let mut out = CliOut::capture();
+        assert_eq!(run_integrations_command(&args(&["--base-url"]), &mut out), 1);
+        assert_eq!(out.error_text(), "Missing value for --base-url");
+
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_integrations_command(&args(&["--model", "--json"]), &mut out),
+            1
+        );
+        assert_eq!(out.error_text(), "Missing value for --model");
+    }
+
+    #[test]
+    fn help_prints_usage_and_exits_zero() {
+        let mut out = CliOut::capture();
+        assert_eq!(run_integrations_command(&args(&["--help"]), &mut out), 0);
+        assert!(out.info_text().contains("Kinds: opencode, openclaw, python, curl, env"));
+    }
+}
diff --git a/crates/manager/src/commands/mod.rs b/crates/manager/src/commands/mod.rs
new file mode 100644
index 000000000..f9edc8922
--- /dev/null
+++ b/crates/manager/src/commands/mod.rs
@@ -0,0 +1,24 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account;
+pub mod best;
+pub mod bridge;
+pub mod budget;
+pub mod check;
+pub mod config_explain;
+pub mod debug_bundle;
+pub mod forecast;
+pub mod history;
+pub mod init_config;
+pub mod integrations;
+pub mod models;
+pub mod monitor;
+pub mod report;
+pub mod rotation;
+pub mod status;
+pub mod switch;
+pub mod uninstall;
+pub mod unpin;
+pub mod usage;
+pub mod verify;
+pub mod why_selected;
+pub mod workspace;
diff --git a/crates/manager/src/commands/models.rs b/crates/manager/src/commands/models.rs
new file mode 100644
index 000000000..dca563d6d
--- /dev/null
+++ b/crates/manager/src/commands/models.rs
@@ -0,0 +1,211 @@
+//! Port of `lib/codex-manager/commands/models.ts`.
+//!
+//! `models [--json] [--model <model>]` — local model/account capability
+//! availability from model profiles, quota cache, and capability policy
+//! state. Read-only.
+
+use cma_accounts::capability_matrix::{
+    ModelCapabilityMatrix, ModelCapabilityMatrixInput, build_model_capability_matrix,
+};
+use cma_accounts::capability_policy::CapabilityPolicyStore;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_quota::cache::QuotaCacheData;
+use cma_quota::readiness::find_quota_cache_entry_for_account;
+use cma_request::model_map::RequestModelCatalog;
+use serde_json::{Value, json};
+
+use crate::dispatcher::CliOut;
+
+fn print_models_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth models [--json] [--model <model>]",
+            "",
+            "Shows local model/account capability availability from model profiles, quota cache, and capability policy state.",
+        ]
+        .join("\n"),
+    );
+}
+
+/// Pure matrix builder over pre-loaded state (test seam).
+pub fn build_models_matrix(
+    storage: Option<&AccountStorageV3>,
+    models: &[String],
+    quota_cache: Option<&QuotaCacheData>,
+    capability_policy: &CapabilityPolicyStore,
+    now: i64,
+) -> ModelCapabilityMatrix {
+    // Pre-resolve the (model-independent) quota-cache entry per account
+    // position — the TS called findQuotaCacheEntryForAccount inline.
+    let quota_by_account: Option<Vec<Option<Value>>> = storage.map(|storage| {
+        storage
+            .accounts
+            .iter()
+            .map(|account| {
+                find_quota_cache_entry_for_account(quota_cache, account, &storage.accounts)
+                    .and_then(|entry| serde_json::to_value(entry).ok())
+            })
+            .collect()
+    });
+    build_model_capability_matrix(
+        &RequestModelCatalog,
+        &ModelCapabilityMatrixInput {
+            storage,
+            models: if models.is_empty() { None } else { Some(models) },
+            entitlements: None,
+            capability_policy: Some(capability_policy),
+            quota_by_account: quota_by_account.as_deref(),
+            now: Some(now),
+        },
+    )
+}
+
+/// TS `runModelsCommand(args, deps)`.
+pub async fn run_models_command(args: &[String], out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_models_usage(out);
+        return 0;
+    }
+    let mut models: Vec<String> = Vec::new();
+    let mut json = false;
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--json" || arg == "-j" {
+            json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--model" {
+            let value = args.get(i + 1).map(|v| v.trim().to_string());
+            match value {
+                Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                    models.push(v);
+                    i += 2;
+                    continue;
+                }
+                _ => {
+                    out.error("Missing value for --model");
+                    return 1;
+                }
+            }
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                out.error("Missing value for --model");
+                return 1;
+            }
+            models.push(value.to_string());
+            i += 1;
+            continue;
+        }
+        out.error(format!("Unknown models option: {arg}"));
+        return 1;
+    }
+
+    cma_storage::facade::set_storage_path(None);
+    let (storage, quota_cache) = tokio::join!(
+        cma_storage::load::load_accounts(),
+        cma_quota::cache::load_quota_cache(),
+    );
+    let storage = storage.map(|loaded| loaded.storage);
+    let capability_policy =
+        CapabilityPolicyStore::with_catalog(cma_request::model_map::shared_model_catalog());
+    let matrix = build_models_matrix(
+        storage.as_ref(),
+        &models,
+        Some(&quota_cache),
+        &capability_policy,
+        cma_core::utils::now_ms(),
+    );
+    if json {
+        out.info(stringify_pretty2(&json!({
+            "command": "models",
+            "matrix": matrix,
+        })));
+        return 0;
+    }
+    if matrix.entries.is_empty() {
+        out.info("No accounts configured.");
+        return 0;
+    }
+    for entry in &matrix.entries {
+        out.info(format!(
+            "{} {}: {}",
+            entry.account_label,
+            entry.normalized_model,
+            if entry.available {
+                "available".to_string()
+            } else {
+                format!("unavailable ({})", entry.reasons.join("; "))
+            }
+        ));
+    }
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    // Port of test/codex-manager-models-command.test.ts option handling.
+    #[tokio::test]
+    async fn rejects_unknown_option_and_missing_model_value() {
+        let mut out = CliOut::capture();
+        let code = run_models_command(&args(&["--bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown models option: --bogus");
+
+        let mut out = CliOut::capture();
+        let code = run_models_command(&args(&["--model"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing value for --model");
+
+        let mut out = CliOut::capture();
+        let code = run_models_command(&args(&["--model", "--json"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing value for --model");
+
+        let mut out = CliOut::capture();
+        let code = run_models_command(&args(&["--model=  "]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Missing value for --model");
+    }
+
+    #[tokio::test]
+    async fn help_prints_usage() {
+        let mut out = CliOut::capture();
+        let code = run_models_command(&args(&["-h"]), &mut out).await;
+        assert_eq!(code, 0);
+        assert!(out.info_text().contains("codex-multi-auth models [--json] [--model <model>]"));
+    }
+
+    #[test]
+    fn empty_storage_produces_no_entries() {
+        let policy = CapabilityPolicyStore::new();
+        let matrix = build_models_matrix(None, &[], None, &policy, 1);
+        assert!(matrix.entries.is_empty());
+    }
+
+    #[test]
+    fn matrix_entries_cover_each_model_per_account() {
+        let mut storage = AccountStorageV3::empty();
+        storage
+            .accounts
+            .push(AccountMetadataV3::new("rt-1".to_string(), 1, 0));
+        let policy = CapabilityPolicyStore::new();
+        let models = vec!["gpt-5.5".to_string()];
+        let matrix = build_models_matrix(Some(&storage), &models, None, &policy, 1);
+        assert_eq!(matrix.entries.len(), 1);
+        assert_eq!(matrix.entries[0].account_label, "Account 1");
+        assert_eq!(matrix.entries[0].normalized_model, "gpt-5.5");
+    }
+}
diff --git a/crates/manager/src/commands/monitor.rs b/crates/manager/src/commands/monitor.rs
new file mode 100644
index 000000000..4bf7405f9
--- /dev/null
+++ b/crates/manager/src/commands/monitor.rs
@@ -0,0 +1,383 @@
+//! Port of `lib/codex-manager/commands/monitor.ts`.
+//!
+//! Behavior source: spec 08 §4.13 — local governance monitor aggregating
+//! runtime, usage, policy, profile, model, quota, and project context.
+
+use cma_accounts::account_policy::{load_account_policy_store, AccountPolicyStore};
+use cma_accounts::capability_matrix::{
+    build_model_capability_matrix, ModelCapabilityMatrixInput,
+};
+use cma_accounts::routing_profiles::{
+    resolve_project_routing_profile, ProjectRoutingProfileContext,
+};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::utils::now_ms;
+use cma_quota::budget_guard::{load_budget_guard_store, BudgetGuardStore};
+use cma_quota::cache::{load_quota_cache, QuotaCacheData};
+use cma_quota::readiness::find_quota_cache_entry_for_account;
+use cma_request::model_map::RequestModelCatalog;
+use cma_runtime::observability::{
+    load_persisted_runtime_observability_snapshot, RuntimeObservabilitySnapshot,
+};
+use cma_usage::ledger::summarize_usage_ledger;
+use cma_usage::types::{UsageSummary, UsageSummaryGroupBy, UsageSummaryQuery};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_load_accounts, default_set_storage_path, BoxFuture, LoadAccountsFn, SetStoragePathFn,
+};
+
+/// TS `MonitorCommandDeps` (log sinks live on [`CliOut`]).
+pub struct MonitorCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub load_runtime_observability_snapshot:
+        Box<dyn Fn() -> BoxFuture<Option<RuntimeObservabilitySnapshot>> + Send + Sync>,
+    pub load_quota_cache: Box<dyn Fn() -> BoxFuture<QuotaCacheData> + Send + Sync>,
+    pub load_account_policy_store: Box<dyn Fn() -> BoxFuture<AccountPolicyStore> + Send + Sync>,
+    pub load_budget_guard_store: Box<dyn Fn() -> BoxFuture<BudgetGuardStore> + Send + Sync>,
+    pub resolve_project_routing_profile:
+        Box<dyn Fn() -> BoxFuture<ProjectRoutingProfileContext> + Send + Sync>,
+    pub summarize_usage_ledger:
+        Box<dyn Fn(UsageSummaryQuery) -> BoxFuture<std::io::Result<UsageSummary>> + Send + Sync>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+}
+
+impl Default for MonitorCommandDeps {
+    fn default() -> Self {
+        MonitorCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            load_accounts: default_load_accounts(),
+            load_runtime_observability_snapshot: Box::new(|| {
+                Box::pin(async { load_persisted_runtime_observability_snapshot() })
+            }),
+            load_quota_cache: Box::new(|| Box::pin(load_quota_cache())),
+            load_account_policy_store: Box::new(|| Box::pin(load_account_policy_store())),
+            load_budget_guard_store: Box::new(|| Box::pin(load_budget_guard_store())),
+            resolve_project_routing_profile: Box::new(|| {
+                Box::pin(async {
+                    let start_dir = std::env::current_dir().unwrap_or_default();
+                    resolve_project_routing_profile(&start_dir).await
+                })
+            }),
+            summarize_usage_ledger: Box::new(|query| {
+                Box::pin(async move { summarize_usage_ledger(&query).await })
+            }),
+            get_now: None,
+        }
+    }
+}
+
+fn print_monitor_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth monitor [--json]",
+            "",
+            "Aggregates local runtime, usage, policy, profile, model, quota, and project context.",
+        ]
+        .join("\n"),
+    );
+}
+
+fn path_to_value(path: Option<&std::path::Path>) -> Value {
+    match path {
+        Some(path) => Value::from(path.to_string_lossy().into_owned()),
+        None => Value::Null,
+    }
+}
+
+/// Production entry.
+pub async fn run_monitor_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_monitor_command_with(args, &MonitorCommandDeps::default(), out).await
+}
+
+/// TS `runMonitorCommand(args, deps)`.
+pub async fn run_monitor_command_with(
+    args: &[String],
+    deps: &MonitorCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_monitor_usage(out);
+        return 0;
+    }
+    let mut json = false;
+    for arg in args {
+        if arg == "--json" || arg == "-j" {
+            json = true;
+            continue;
+        }
+        out.error(format!("Unknown monitor option: {arg}"));
+        return 1;
+    }
+
+    (deps.set_storage_path)(None);
+    let (storage, runtime, quota_cache, account_policies, budget_guards, project, usage) = tokio::join!(
+        (deps.load_accounts)(),
+        (deps.load_runtime_observability_snapshot)(),
+        (deps.load_quota_cache)(),
+        (deps.load_account_policy_store)(),
+        (deps.load_budget_guard_store)(),
+        (deps.resolve_project_routing_profile)(),
+        (deps.summarize_usage_ledger)(UsageSummaryQuery {
+            since: None,
+            until: None,
+            include_archives: false,
+            by: Some(UsageSummaryGroupBy::Outcome),
+        }),
+    );
+    let usage = match usage {
+        Ok(usage) => usage,
+        Err(error) => {
+            // TS lets a ledger read rejection propagate; surface as an error
+            // exit instead of a crash.
+            out.error(format!("Failed to read usage ledger: {error}"));
+            return 1;
+        }
+    };
+
+    let now = deps.get_now.as_ref().map(|f| f()).unwrap_or_else(now_ms);
+    let quota_by_account: Option<Vec<Option<Value>>> = storage.as_ref().map(|storage| {
+        storage
+            .accounts
+            .iter()
+            .map(|account| {
+                find_quota_cache_entry_for_account(
+                    Some(&quota_cache),
+                    account,
+                    &storage.accounts,
+                )
+                .map(|entry| serde_json::to_value(entry).unwrap_or(Value::Null))
+            })
+            .collect()
+    });
+    let matrix = build_model_capability_matrix(
+        &RequestModelCatalog,
+        &ModelCapabilityMatrixInput {
+            storage: storage.as_ref(),
+            models: None,
+            entitlements: None,
+            capability_policy: None,
+            quota_by_account: quota_by_account.as_deref(),
+            now: Some(now),
+        },
+    );
+
+    let account_count = storage
+        .as_ref()
+        .map(|storage| storage.accounts.len())
+        .unwrap_or(0);
+    let policy_count = account_policies.len();
+    let available = matrix.entries.iter().filter(|entry| entry.available).count();
+    let unavailable = matrix.entries.iter().filter(|entry| !entry.available).count();
+
+    let mut payload = Map::new();
+    payload.insert("command".into(), Value::from("monitor"));
+    let mut project_obj = Map::new();
+    project_obj.insert(
+        "projectKey".into(),
+        project
+            .project_key
+            .clone()
+            .map(Value::from)
+            .unwrap_or(Value::Null),
+    );
+    project_obj.insert("projectRoot".into(), path_to_value(project.project_root.as_deref()));
+    project_obj.insert("hasProfile".into(), Value::from(project.profile.is_some()));
+    project_obj.insert(
+        "budgetKey".into(),
+        project
+            .profile
+            .as_ref()
+            .and_then(|profile| profile.budget_key.clone())
+            .map(Value::from)
+            .unwrap_or(Value::Null),
+    );
+    payload.insert("project".into(), Value::Object(project_obj));
+    let mut accounts_obj = Map::new();
+    accounts_obj.insert("count".into(), Value::from(account_count as i64));
+    accounts_obj.insert("policyCount".into(), Value::from(policy_count as i64));
+    payload.insert("accounts".into(), Value::Object(accounts_obj));
+    payload.insert(
+        "runtime".into(),
+        runtime
+            .as_ref()
+            .map(|snapshot| serde_json::to_value(snapshot).unwrap_or(Value::Null))
+            .unwrap_or(Value::Null),
+    );
+    payload.insert(
+        "usage".into(),
+        serde_json::to_value(&usage).unwrap_or(Value::Null),
+    );
+    payload.insert("budgetGuardCount".into(), Value::from(budget_guards.len() as i64));
+    payload.insert(
+        "routingProfile".into(),
+        project
+            .profile
+            .as_ref()
+            .map(|profile| serde_json::to_value(profile).unwrap_or(Value::Null))
+            .unwrap_or(Value::Null),
+    );
+    let mut matrix_obj = Map::new();
+    matrix_obj.insert(
+        "models".into(),
+        Value::Array(matrix.models.iter().cloned().map(Value::from).collect()),
+    );
+    matrix_obj.insert("entries".into(), Value::from(matrix.entries.len() as i64));
+    matrix_obj.insert("available".into(), Value::from(available as i64));
+    matrix_obj.insert("unavailable".into(), Value::from(unavailable as i64));
+    payload.insert("modelMatrix".into(), Value::Object(matrix_obj));
+    let mut quota_obj = Map::new();
+    quota_obj.insert(
+        "byAccountId".into(),
+        Value::from(quota_cache.by_account_id.len() as i64),
+    );
+    quota_obj.insert("byEmail".into(), Value::from(quota_cache.by_email.len() as i64));
+    payload.insert("quotaCache".into(), Value::Object(quota_obj));
+
+    if json {
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return 0;
+    }
+
+    out.info("Local governance monitor");
+    out.info(format!(
+        "Project: {}",
+        project.project_key.as_deref().unwrap_or("none")
+    ));
+    out.info(format!("Accounts: {account_count} ({policy_count} policies)"));
+    out.info(format!(
+        "Usage: {} requests, {} tokens, ${:.6}",
+        usage.totals.requests, usage.totals.total_tokens, usage.totals.cost_usd
+    ));
+    out.info(format!("Budgets: {}", budget_guards.len()));
+    out.info(format!(
+        "Models: {available}/{} available",
+        matrix.entries.len()
+    ));
+    out.info(format!(
+        "Quota cache: {} account ids, {} emails",
+        quota_cache.by_account_id.len(),
+        quota_cache.by_email.len()
+    ));
+    if let Some(runtime) = runtime {
+        out.info(format!(
+            "Runtime: responses={}, refresh={}, failures={}",
+            runtime.responses_requests,
+            runtime.auth_refresh_requests,
+            runtime.runtime_metrics.failed_requests
+        ));
+    } else {
+        out.info("Runtime: no persisted snapshot");
+    }
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+
+    fn storage() -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        let mut account = AccountMetadataV3::new("refresh", 1, 1);
+        account.email = Some("owner@example.com".to_string());
+        account.account_id = Some("acct_1".to_string());
+        storage.accounts.push(account);
+        storage
+    }
+
+    fn deps() -> MonitorCommandDeps {
+        let storage = storage();
+        MonitorCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { Some(storage) })
+            }),
+            load_runtime_observability_snapshot: Box::new(|| Box::pin(async { None })),
+            load_quota_cache: Box::new(|| Box::pin(async { QuotaCacheData::default() })),
+            load_account_policy_store: Box::new(|| Box::pin(async { AccountPolicyStore::empty() })),
+            load_budget_guard_store: Box::new(|| Box::pin(async { BudgetGuardStore::empty() })),
+            resolve_project_routing_profile: Box::new(|| {
+                Box::pin(async {
+                    ProjectRoutingProfileContext {
+                        start_dir: "/repo".into(),
+                        project_root: Some("/repo".into()),
+                        identity_root: Some("/repo".into()),
+                        project_key: Some("project-a".to_string()),
+                        profile: None,
+                    }
+                })
+            }),
+            summarize_usage_ledger: Box::new(|query| {
+                Box::pin(async move {
+                    Ok(UsageSummary {
+                        since: None,
+                        until: None,
+                        by: query.by.unwrap_or_default(),
+                        totals: cma_usage::types::UsageSummaryBucket {
+                            key: "total".into(),
+                            requests: 2,
+                            successes: 1,
+                            failures: 1,
+                            blocked: 0,
+                            cancelled: 0,
+                            input_tokens: 10,
+                            output_tokens: 20,
+                            cached_input_tokens: 0,
+                            reasoning_tokens: 0,
+                            total_tokens: 30,
+                            cost_usd: 0.001,
+                        },
+                        buckets: vec![],
+                    })
+                })
+            }),
+            get_now: Some(Box::new(|| 123)),
+        }
+    }
+
+    #[tokio::test]
+    async fn prints_json_aggregate_output_without_raw_account_labels() {
+        let d = deps();
+        let mut out = CliOut::capture();
+        let exit_code = run_monitor_command_with(&["--json".to_string()], &d, &mut out).await;
+        assert_eq!(exit_code, 0);
+        let output = out.info_text();
+        let payload: Value = serde_json::from_str(&output).expect("json");
+        assert_eq!(payload["project"]["projectKey"], Value::from("project-a"));
+        assert_eq!(payload["accounts"]["count"], Value::from(1));
+        assert!(payload["modelMatrix"]["entries"].as_i64().unwrap() > 0);
+        assert!(!output.contains("owner@example.com"));
+    }
+
+    #[tokio::test]
+    async fn rejects_unknown_options() {
+        let d = deps();
+        let mut out = CliOut::capture();
+        let exit_code = run_monitor_command_with(&["--bad".to_string()], &d, &mut out).await;
+        assert_eq!(exit_code, 1);
+        assert!(out.error_text().contains("Unknown monitor option"));
+    }
+
+    #[tokio::test]
+    async fn text_mode_prints_governance_lines() {
+        let d = deps();
+        let mut out = CliOut::capture();
+        let exit_code = run_monitor_command_with(&[], &d, &mut out).await;
+        assert_eq!(exit_code, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Local governance monitor");
+        assert_eq!(lines[1], "Project: project-a");
+        assert_eq!(lines[2], "Accounts: 1 (0 policies)");
+        assert_eq!(lines[3], "Usage: 2 requests, 30 tokens, $0.001000");
+        assert_eq!(lines[4], "Budgets: 0");
+        assert!(lines[5].ends_with("available"));
+        assert_eq!(lines[6], "Quota cache: 0 account ids, 0 emails");
+        assert_eq!(lines[7], "Runtime: no persisted snapshot");
+    }
+}
diff --git a/crates/manager/src/commands/report.rs b/crates/manager/src/commands/report.rs
new file mode 100644
index 000000000..5247264e3
--- /dev/null
+++ b/crates/manager/src/commands/report.rs
@@ -0,0 +1,1279 @@
+//! Port of `lib/codex-manager/commands/report.ts`.
+//!
+//! `report [--live] [--json] [--explain] [--model M] [--max-accounts N]
+//! [--max-probes N] [--cached-only] [--out PATH]` — full machine-readable
+//! account/forecast/runtime report.
+//!
+//! Contract divergences vs `best`/`forecast` (spec 08 gotchas 2/3/4):
+//! - probe-refresh patches persist FIRST (reload-clone-match-save) and the
+//!   in-memory apply happens only AFTER the persist succeeds (forecast is
+//!   the other way around);
+//! - `--model` without `--live` is silently accepted;
+//! - live probing is budgeted: `--max-accounts` caps considered accounts
+//!   (checked at the TOP of each iteration, before the enabled filter),
+//!   `--max-probes` caps executed probes (checked just before probing);
+//! - `--out` writes the pretty JSON + trailing newline atomically in BOTH
+//!   output modes.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+
+use chrono::{SecondsFormat, TimeZone, Utc};
+use cma_core::errors::CodexError;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::{DEFAULT_PROBE_MODEL, ModelFamily};
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3};
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::cache::QuotaCacheData;
+use cma_quota::forecast::{
+    ForecastAccountInput, evaluate_forecast_accounts, recommend_forecast_account,
+    summarize_forecast,
+};
+use cma_quota::probe::{
+    CodexQuotaSnapshot, ProbeCodexQuotaOptions, describe_codex_probe_failure,
+    fetch_codex_quota_snapshot, format_quota_snapshot_line,
+};
+use cma_runtime::observability::RuntimeObservabilitySnapshot;
+use cma_storage::health::StorageHealthSummary;
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    AccountIdentityMatch, BoxFuture, GetStoragePathFn, LoadAccountsFn, RefreshedAccountPatch,
+    SaveAccountsFn, SetStoragePathFn, apply_refreshed_account_patch, default_get_storage_path,
+    default_load_accounts, default_save_accounts, default_set_storage_path, default_write_file,
+    persist_refreshed_account_patch, serialize_forecast_results,
+};
+use crate::formatters::model::{ModelInspection, format_model_inspection, inspect_requested_model};
+use crate::formatters::text_style::normalize_failure_detail;
+use crate::repair::fix::QuotaProbeRequest;
+
+// ============================================================================
+// Options / parsing
+// ============================================================================
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct ReportCliOptions {
+    live: bool,
+    json: bool,
+    explain: bool,
+    model: String,
+    max_accounts: Option<usize>,
+    max_probes: Option<usize>,
+    cached_only: bool,
+    out_path: Option<String>,
+}
+
+impl Default for ReportCliOptions {
+    fn default() -> Self {
+        ReportCliOptions {
+            live: false,
+            json: false,
+            explain: false,
+            model: DEFAULT_PROBE_MODEL.to_string(),
+            max_accounts: None,
+            max_probes: None,
+            cached_only: false,
+            out_path: None,
+        }
+    }
+}
+
+fn print_report_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage: codex-multi-auth report [--live] [--json] [--explain] [--model MODEL] [--out PATH]".to_string(),
+            String::new(),
+            "Options:".to_string(),
+            "  --live, -l         Probe live quota headers via Codex backend".to_string(),
+            "  --json, -j         Print machine-readable JSON output".to_string(),
+            "  --explain          Print per-account reasoning in text mode".to_string(),
+            format!("  --model, -m        Probe model for live mode (default: {DEFAULT_PROBE_MODEL})"),
+            "  --max-accounts N   Limit how many enabled accounts live mode can consider".to_string(),
+            "  --max-probes N     Limit how many live quota probes can run".to_string(),
+            "  --cached-only      Skip refreshes and only use already-usable access tokens".to_string(),
+            "  --out              Write JSON report to a file path".to_string(),
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `parsePositiveIntegerOption(rawValue)` — trimmed, digit-only, safe
+/// integer `>= 1`.
+fn parse_positive_integer_option(raw_value: &str) -> Option<usize> {
+    let normalized = raw_value.trim();
+    if normalized.is_empty() || !normalized.bytes().all(|byte| byte.is_ascii_digit()) {
+        return None;
+    }
+    let parsed: u64 = normalized.parse().ok()?;
+    if !(1..=9_007_199_254_740_991).contains(&parsed) {
+        return None;
+    }
+    Some(parsed as usize)
+}
+
+fn parse_report_args(args: &[String]) -> Result<ReportCliOptions, String> {
+    let mut options = ReportCliOptions::default();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        match arg {
+            "--live" | "-l" => {
+                options.live = true;
+                i += 1;
+                continue;
+            }
+            "--json" | "-j" => {
+                options.json = true;
+                i += 1;
+                continue;
+            }
+            "--explain" => {
+                options.explain = true;
+                i += 1;
+                continue;
+            }
+            "--cached-only" => {
+                options.cached_only = true;
+                i += 1;
+                continue;
+            }
+            "--model" | "-m" => {
+                let value = args.get(i + 1).map(|value| value.trim().to_string());
+                match value {
+                    Some(value) if !value.is_empty() && !value.starts_with('-') => {
+                        options.model = value;
+                        i += 2;
+                        continue;
+                    }
+                    _ => return Err("Missing value for --model".to_string()),
+                }
+            }
+            "--max-accounts" => {
+                let Some(value) = args.get(i + 1) else {
+                    return Err("Missing value for --max-accounts".to_string());
+                };
+                if value.is_empty() {
+                    return Err("Missing value for --max-accounts".to_string());
+                }
+                let Some(parsed) = parse_positive_integer_option(value) else {
+                    return Err("--max-accounts must be a positive integer".to_string());
+                };
+                options.max_accounts = Some(parsed);
+                i += 2;
+                continue;
+            }
+            "--max-probes" => {
+                let Some(value) = args.get(i + 1) else {
+                    return Err("Missing value for --max-probes".to_string());
+                };
+                if value.is_empty() {
+                    return Err("Missing value for --max-probes".to_string());
+                }
+                let Some(parsed) = parse_positive_integer_option(value) else {
+                    return Err("--max-probes must be a positive integer".to_string());
+                };
+                options.max_probes = Some(parsed);
+                i += 2;
+                continue;
+            }
+            "--out" => {
+                let Some(value) = args.get(i + 1) else {
+                    return Err("Missing value for --out".to_string());
+                };
+                if value.is_empty() {
+                    return Err("Missing value for --out".to_string());
+                }
+                options.out_path = Some(value.clone());
+                i += 2;
+                continue;
+            }
+            _ => {}
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                return Err("Missing value for --model".to_string());
+            }
+            options.model = value.to_string();
+            i += 1;
+            continue;
+        }
+        if let Some(raw) = arg.strip_prefix("--max-accounts=") {
+            let Some(parsed) = parse_positive_integer_option(raw) else {
+                return Err("--max-accounts must be a positive integer".to_string());
+            };
+            options.max_accounts = Some(parsed);
+            i += 1;
+            continue;
+        }
+        if let Some(raw) = arg.strip_prefix("--max-probes=") {
+            let Some(parsed) = parse_positive_integer_option(raw) else {
+                return Err("--max-probes must be a positive integer".to_string());
+            };
+            options.max_probes = Some(parsed);
+            i += 1;
+            continue;
+        }
+        if let Some(raw) = arg.strip_prefix("--out=") {
+            let value = raw.trim();
+            if value.is_empty() {
+                return Err("Missing value for --out".to_string());
+            }
+            options.out_path = Some(value.to_string());
+            i += 1;
+            continue;
+        }
+        return Err(format!("Unknown option: {arg}"));
+    }
+
+    Ok(options)
+}
+
+// ============================================================================
+// Deps
+// ============================================================================
+
+/// TS `ReportCommandDeps` (log sinks live on [`CliOut`]).
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct ReportCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub get_storage_path: GetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub save_accounts: SaveAccountsFn,
+    pub queued_refresh: Box<dyn Fn(String) -> BoxFuture<TokenResult> + Send + Sync>,
+    pub fetch_codex_quota_snapshot: Box<
+        dyn Fn(QuotaProbeRequest) -> BoxFuture<Result<CodexQuotaSnapshot, CodexError>>
+            + Send
+            + Sync,
+    >,
+    pub inspect_storage_health:
+        Option<Box<dyn Fn() -> BoxFuture<StorageHealthSummary> + Send + Sync>>,
+    pub load_runtime_observability_snapshot: Option<
+        Box<
+            dyn Fn() -> BoxFuture<Result<Option<RuntimeObservabilitySnapshot>, CodexError>>
+                + Send
+                + Sync,
+        >,
+    >,
+    pub load_quota_cache: Option<Box<dyn Fn() -> BoxFuture<QuotaCacheData> + Send + Sync>>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+    pub get_cwd: Option<Box<dyn Fn() -> PathBuf + Send + Sync>>,
+    pub write_file: Option<
+        Box<dyn Fn(PathBuf, String) -> BoxFuture<std::io::Result<()>> + Send + Sync>,
+    >,
+}
+
+impl Default for ReportCommandDeps {
+    fn default() -> Self {
+        ReportCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            get_storage_path: default_get_storage_path(),
+            load_accounts: default_load_accounts(),
+            save_accounts: default_save_accounts(),
+            queued_refresh: Box::new(|refresh_token| {
+                Box::pin(
+                    async move { cma_auth::refresh_queue::queued_refresh(&refresh_token).await },
+                )
+            }),
+            fetch_codex_quota_snapshot: Box::new(|request| {
+                Box::pin(async move {
+                    fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+                        account_id: request.account_id,
+                        access_token: request.access_token,
+                        model: Some(request.model),
+                        ..Default::default()
+                    })
+                    .await
+                })
+            }),
+            inspect_storage_health: Some(Box::new(|| {
+                Box::pin(cma_storage::health::inspect_storage_health())
+            })),
+            load_runtime_observability_snapshot: Some(Box::new(|| {
+                Box::pin(async {
+                    Ok(
+                        cma_runtime::observability::load_persisted_runtime_observability_snapshot(
+                        ),
+                    )
+                })
+            })),
+            load_quota_cache: Some(Box::new(|| Box::pin(cma_quota::cache::load_quota_cache()))),
+            get_now: None,
+            get_cwd: None,
+            write_file: None,
+        }
+    }
+}
+
+/// `new Date(now).toISOString()`.
+fn to_iso_string(now: i64) -> String {
+    Utc.timestamp_millis_opt(now)
+        .single()
+        .map(|value| value.to_rfc3339_opts(SecondsFormat::Millis, true))
+        .unwrap_or_default()
+}
+
+// ============================================================================
+// runReportCommand
+// ============================================================================
+
+/// Production entry (dispatcher wiring).
+pub async fn run_report_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_report_command_with(args, &ReportCommandDeps::default(), out).await
+}
+
+/// TS `runReportCommand(args, deps)`.
+pub async fn run_report_command_with(
+    args: &[String],
+    deps: &ReportCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_report_usage(out);
+        return 0;
+    }
+
+    let options = match parse_report_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_report_usage(out);
+            return 1;
+        }
+    };
+    let trimmed_model = options.model.trim();
+    let requested_model = if trimmed_model.is_empty() {
+        DEFAULT_PROBE_MODEL.to_string()
+    } else {
+        trimmed_model.to_string()
+    };
+    let model_inspection: ModelInspection = inspect_requested_model(&requested_model);
+
+    (deps.set_storage_path)(None);
+    let storage_path = (deps.get_storage_path)();
+    let mut storage: Option<AccountStorageV3> = (deps.load_accounts)().await;
+    let storage_health = match &deps.inspect_storage_health {
+        Some(inspect) => Some(inspect().await),
+        None => None,
+    };
+    let now = deps
+        .get_now
+        .as_ref()
+        .map(|get_now| get_now())
+        .unwrap_or_else(cma_core::utils::now_ms);
+    let account_count = storage
+        .as_ref()
+        .map(|storage| storage.accounts.len())
+        .unwrap_or(0);
+    let active_index = storage
+        .as_ref()
+        .map(|storage| {
+            cma_runtime::account_status::resolve_active_index(storage, ModelFamily::Codex)
+        })
+        .unwrap_or(0);
+    let mut refresh_failures: HashMap<usize, TokenFailure> = HashMap::new();
+    let mut live_quota_by_index: HashMap<usize, CodexQuotaSnapshot> = HashMap::new();
+    let mut probe_errors: Vec<String> = Vec::new();
+    let quota_cache: Option<QuotaCacheData> = match &deps.load_quota_cache {
+        Some(load_quota_cache) => Some(load_quota_cache().await),
+        None => None,
+    };
+    let mut runtime_snapshot: Option<RuntimeObservabilitySnapshot> = None;
+    let mut runtime_key_present = false;
+    let mut runtime_snapshot_load_error: Option<String> = None;
+    if let Some(load_snapshot) = &deps.load_runtime_observability_snapshot {
+        runtime_key_present = true;
+        match load_snapshot().await {
+            Ok(snapshot) => runtime_snapshot = snapshot,
+            Err(error) => {
+                runtime_snapshot = None;
+                let message = error.message().to_string();
+                out.error(format!(
+                    "Runtime observability snapshot unavailable: {message}"
+                ));
+                runtime_snapshot_load_error = Some(message);
+            }
+        }
+    }
+    let mut considered_live_accounts = 0usize;
+    let mut executed_live_probes = 0usize;
+
+    if let Some(storage) = &mut storage
+        && options.live
+    {
+        for i in 0..storage.accounts.len() {
+            // Account budget — checked at the TOP of each iteration, BEFORE
+            // the enabled filter.
+            if let Some(max_accounts) = options.max_accounts
+                && considered_live_accounts >= max_accounts
+            {
+                probe_errors.push(format!(
+                    "live probe account budget reached ({max_accounts})"
+                ));
+                break;
+            }
+            if storage.accounts[i].enabled == Some(false) {
+                continue;
+            }
+            considered_live_accounts += 1;
+
+            let label = crate::repair::fix::account_label(&storage.accounts[i], i);
+            let mut probe_access_token = storage.accounts[i].access_token.clone();
+            let mut probe_account_id = storage.accounts[i]
+                .account_id
+                .clone()
+                .or_else(|| extract_account_id(storage.accounts[i].access_token.as_deref()));
+            if !crate::login::account_credentials::has_usable_access_token(
+                &storage.accounts[i],
+                now,
+            ) {
+                if options.cached_only {
+                    probe_errors.push(format!(
+                        "{label}: skipped refresh because --cached-only is enabled"
+                    ));
+                    continue;
+                }
+                let refresh_result =
+                    (deps.queued_refresh)(storage.accounts[i].refresh_token.clone()).await;
+                let success = match refresh_result {
+                    TokenResult::Success(success) => success,
+                    TokenResult::Failed(failure) => {
+                        let mut normalized = failure.clone();
+                        normalized.message = Some(normalize_failure_detail(
+                            failure.message.as_deref(),
+                            failure.reason.map(|reason| reason.as_str()),
+                        ));
+                        refresh_failures.insert(i, normalized);
+                        continue;
+                    }
+                };
+
+                let refreshed_email = sanitize_email(
+                    extract_account_email(Some(&success.access), success.id_token.as_deref())
+                        .as_deref(),
+                );
+                let token_derived_account_id = extract_account_id(Some(&success.access));
+                let refreshed_account_id = storage.accounts[i]
+                    .account_id
+                    .clone()
+                    .or_else(|| token_derived_account_id.clone());
+                let previous_refresh_token = storage.accounts[i].refresh_token.clone();
+                let previous_access_token = storage.accounts[i].access_token.clone();
+                let previous_expires_at = storage.accounts[i].expires_at;
+                let previous_email = storage.accounts[i].email.clone();
+                let previous_account_id = storage.accounts[i].account_id.clone();
+                let mut refresh_patch = RefreshedAccountPatch {
+                    refresh_token: success.refresh.clone(),
+                    access_token: success.access.clone(),
+                    expires_at: success.expires,
+                    email: None,
+                    account_id: None,
+                    account_id_source: None,
+                };
+                if let Some(email) = &refreshed_email {
+                    refresh_patch.email = Some(email.clone());
+                }
+                if let Some(account_id) = &token_derived_account_id {
+                    refresh_patch.account_id = Some(account_id.clone());
+                    refresh_patch.account_id_source = Some(AccountIdSource::Token);
+                }
+                let account_match = AccountIdentityMatch {
+                    refresh_token: Some(previous_refresh_token.clone()),
+                    email: previous_email.clone(),
+                    account_id: previous_account_id.clone(),
+                };
+                if previous_refresh_token != refresh_patch.refresh_token
+                    || previous_access_token.as_deref()
+                        != Some(refresh_patch.access_token.as_str())
+                    || previous_expires_at != Some(refresh_patch.expires_at)
+                {
+                    // Persist FIRST; the in-memory apply happens only after
+                    // the persist succeeds (spec 08 gotcha 3 — the reverse
+                    // of forecast).
+                    let persisted = persist_refreshed_account_patch(
+                        storage,
+                        &account_match,
+                        &refresh_patch,
+                        || (deps.load_accounts)(),
+                        |next_storage: &AccountStorageV3| {
+                            (deps.save_accounts)(next_storage.clone())
+                        },
+                    )
+                    .await;
+                    if let Err(error) = persisted {
+                        let message =
+                            normalize_failure_detail(Some(error.message()), None);
+                        probe_errors.push(format!("{label}: {message}"));
+                        continue;
+                    }
+                    apply_refreshed_account_patch(&mut storage.accounts[i], &refresh_patch);
+                }
+                probe_access_token = Some(success.access.clone());
+                probe_account_id = refresh_patch
+                    .account_id
+                    .clone()
+                    .or_else(|| storage.accounts[i].account_id.clone())
+                    .or(refreshed_account_id);
+            }
+
+            let (Some(probe_access_token), Some(probe_account_id)) =
+                (probe_access_token, probe_account_id)
+            else {
+                probe_errors.push(format!("{label}: missing accountId for live probe"));
+                continue;
+            };
+            // Probe budget — checked just before probing.
+            if let Some(max_probes) = options.max_probes
+                && executed_live_probes >= max_probes
+            {
+                probe_errors.push(format!("live probe request budget reached ({max_probes})"));
+                break;
+            }
+
+            executed_live_probes += 1;
+            match (deps.fetch_codex_quota_snapshot)(QuotaProbeRequest {
+                account_id: probe_account_id,
+                access_token: probe_access_token,
+                model: model_inspection.normalized.clone(),
+            })
+            .await
+            {
+                Ok(live_quota) => {
+                    live_quota_by_index.insert(i, live_quota);
+                }
+                Err(error) => {
+                    let message = describe_codex_probe_failure(
+                        &error,
+                        Some(&|raw: &str| normalize_failure_detail(Some(raw), None)),
+                    );
+                    probe_errors.push(format!("{label}: {message}"));
+                }
+            }
+        }
+    }
+
+    let runtime_overlay = runtime_snapshot
+        .as_ref()
+        .map(crate::repair::doctor::snapshot_to_overlay);
+    let forecast_results = match &storage {
+        Some(storage) => {
+            let inputs: Vec<ForecastAccountInput<'_>> = storage
+                .accounts
+                .iter()
+                .enumerate()
+                .map(|(index, account)| ForecastAccountInput {
+                    index,
+                    account,
+                    is_current: index == active_index,
+                    now,
+                    refresh_failure: refresh_failures.get(&index),
+                    live_quota: live_quota_by_index.get(&index),
+                    quota_cache: quota_cache.as_ref(),
+                    all_accounts: Some(&storage.accounts),
+                    runtime_overlay: runtime_overlay.as_ref(),
+                })
+                .collect();
+            evaluate_forecast_accounts(&inputs)
+        }
+        None => Vec::new(),
+    };
+    let forecast_summary = summarize_forecast(&forecast_results);
+    let recommendation = recommend_forecast_account(&forecast_results);
+    let enabled_count = storage
+        .as_ref()
+        .map(|storage| {
+            storage
+                .accounts
+                .iter()
+                .filter(|account| account.enabled != Some(false))
+                .count()
+        })
+        .unwrap_or(0);
+    let disabled_count = account_count.saturating_sub(enabled_count);
+    let cooling_count = storage
+        .as_ref()
+        .map(|storage| {
+            storage
+                .accounts
+                .iter()
+                .filter(|account| {
+                    matches!(account.cooling_down_until, Some(until) if until > now)
+                })
+                .count()
+        })
+        .unwrap_or(0);
+    let rate_limited_count = storage
+        .as_ref()
+        .map(|storage| {
+            storage
+                .accounts
+                .iter()
+                .filter(|account| {
+                    cma_runtime::account_status::format_rate_limit_entry(
+                        account.rate_limit_reset_times.as_ref(),
+                        now,
+                        &cma_accounts::rate_limits::format_wait_time,
+                        ModelFamily::Codex,
+                    )
+                    .is_some()
+                })
+                .count()
+        })
+        .unwrap_or(0);
+
+    // Report object — exact key order (spec 08 §4.14 step 6).
+    let generated_at = to_iso_string(now);
+    let mut report = Map::new();
+    report.insert("command".into(), Value::from("report"));
+    report.insert("generatedAt".into(), Value::from(generated_at.clone()));
+    report.insert("storagePath".into(), Value::from(storage_path.clone()));
+    if let Some(storage_health) = &storage_health {
+        report.insert(
+            "storageHealth".into(),
+            serde_json::to_value(storage_health).unwrap_or(Value::Null),
+        );
+    }
+    report.insert("model".into(), Value::from(requested_model.clone()));
+    let mut model_selection = Map::new();
+    model_selection.insert(
+        "requested".into(),
+        Value::from(model_inspection.requested.clone()),
+    );
+    model_selection.insert(
+        "normalized".into(),
+        Value::from(model_inspection.normalized.clone()),
+    );
+    model_selection.insert("remapped".into(), Value::from(model_inspection.remapped));
+    model_selection.insert(
+        "promptFamily".into(),
+        serde_json::to_value(model_inspection.prompt_family).unwrap_or(Value::Null),
+    );
+    model_selection.insert(
+        "capabilities".into(),
+        serde_json::to_value(model_inspection.capabilities).unwrap_or(Value::Null),
+    );
+    report.insert("modelSelection".into(), Value::Object(model_selection));
+    report.insert("liveProbe".into(), Value::from(options.live));
+    let mut live_probe_budget = Map::new();
+    live_probe_budget.insert("cachedOnly".into(), Value::from(options.cached_only));
+    live_probe_budget.insert(
+        "maxAccounts".into(),
+        options
+            .max_accounts
+            .map(|value| Value::from(value as i64))
+            .unwrap_or(Value::Null),
+    );
+    live_probe_budget.insert(
+        "maxProbes".into(),
+        options
+            .max_probes
+            .map(|value| Value::from(value as i64))
+            .unwrap_or(Value::Null),
+    );
+    live_probe_budget.insert(
+        "consideredAccounts".into(),
+        Value::from(considered_live_accounts as i64),
+    );
+    live_probe_budget.insert(
+        "executedProbes".into(),
+        Value::from(executed_live_probes as i64),
+    );
+    report.insert("liveProbeBudget".into(), Value::Object(live_probe_budget));
+    let mut accounts_obj = Map::new();
+    accounts_obj.insert("total".into(), Value::from(account_count as i64));
+    accounts_obj.insert("enabled".into(), Value::from(enabled_count as i64));
+    accounts_obj.insert("disabled".into(), Value::from(disabled_count as i64));
+    accounts_obj.insert("coolingDown".into(), Value::from(cooling_count as i64));
+    accounts_obj.insert("rateLimited".into(), Value::from(rate_limited_count as i64));
+    report.insert("accounts".into(), Value::Object(accounts_obj));
+    report.insert(
+        "activeIndex".into(),
+        if account_count > 0 {
+            Value::from((active_index + 1) as i64)
+        } else {
+            Value::Null
+        },
+    );
+    let mut forecast_obj = Map::new();
+    forecast_obj.insert(
+        "summary".into(),
+        serde_json::to_value(forecast_summary).unwrap_or(Value::Null),
+    );
+    let mut recommendation_obj = serde_json::to_value(&recommendation)
+        .ok()
+        .and_then(|value| value.as_object().cloned())
+        .unwrap_or_default();
+    recommendation_obj.insert(
+        "selectedReason".into(),
+        match recommendation.recommended_index {
+            Some(recommended_index) => forecast_results
+                .get(recommended_index)
+                .and_then(|result| result.reasons.first().cloned())
+                .map(Value::from)
+                .unwrap_or_else(|| Value::from(recommendation.reason.clone())),
+            None => Value::from(recommendation.reason.clone()),
+        },
+    );
+    forecast_obj.insert("recommendation".into(), Value::Object(recommendation_obj));
+    forecast_obj.insert(
+        "probeErrors".into(),
+        Value::Array(probe_errors.iter().cloned().map(Value::from).collect()),
+    );
+    let mut forecast_account_rows = serialize_forecast_results(
+        &forecast_results,
+        &live_quota_by_index,
+        &refresh_failures,
+        &|snapshot: &CodexQuotaSnapshot| format_quota_snapshot_line(snapshot),
+    );
+    // Flip `selected` on the recommended row (array position == account
+    // index because inputs are built in index order).
+    if let Some(recommended_index) = recommendation.recommended_index
+        && let Some(Value::Object(selected_row)) = forecast_account_rows.get_mut(recommended_index)
+    {
+        selected_row.insert("selected".into(), Value::from(true));
+    }
+    forecast_obj.insert("accounts".into(), Value::Array(forecast_account_rows));
+    report.insert("forecast".into(), Value::Object(forecast_obj));
+    report.insert(
+        "runtimeOverlay".into(),
+        Value::from(runtime_snapshot.is_some()),
+    );
+    if runtime_key_present {
+        report.insert(
+            "runtime".into(),
+            runtime_snapshot
+                .as_ref()
+                .map(|snapshot| serde_json::to_value(snapshot).unwrap_or(Value::Null))
+                .unwrap_or(Value::Null),
+        );
+    }
+    report.insert(
+        "runtimeSnapshotLoadError".into(),
+        runtime_snapshot_load_error
+            .clone()
+            .map(Value::from)
+            .unwrap_or(Value::Null),
+    );
+    let report_value = Value::Object(report);
+
+    let cwd = deps
+        .get_cwd
+        .as_ref()
+        .map(|get_cwd| get_cwd())
+        .unwrap_or_else(|| std::env::current_dir().unwrap_or_default());
+    let resolved_out_path = options
+        .out_path
+        .as_ref()
+        .map(|out_path| resolve_against(&cwd, out_path));
+    if let Some(output_path) = &resolved_out_path {
+        let contents = format!("{}\n", stringify_pretty2(&report_value));
+        let written = match &deps.write_file {
+            Some(write_file) => write_file(output_path.clone(), contents).await,
+            None => default_write_file(output_path, &contents).await,
+        };
+        if let Err(error) = written {
+            // TS lets the write rejection propagate; the Rust surface
+            // reports it and exits 1.
+            out.error(error.to_string());
+            return 1;
+        }
+    }
+
+    if options.json {
+        out.info(stringify_pretty2(&report_value));
+        return 0;
+    }
+
+    out.info(format!("Report generated at {generated_at}"));
+    out.info(format!("Storage: {storage_path}"));
+    if let Some(storage_health) = &storage_health {
+        out.info(format!("Storage health: {}", storage_health.state.as_str()));
+    }
+    out.info(format!(
+        "Model: {}",
+        format_model_inspection(&model_inspection)
+    ));
+    if options.live {
+        let mut budget_parts = vec![
+            format!("considered {considered_live_accounts} account(s)"),
+            format!("executed {executed_live_probes} probe(s)"),
+        ];
+        if let Some(max_accounts) = options.max_accounts {
+            budget_parts.push(format!("max-accounts {max_accounts}"));
+        }
+        if let Some(max_probes) = options.max_probes {
+            budget_parts.push(format!("max-probes {max_probes}"));
+        }
+        if options.cached_only {
+            budget_parts.push("cached-only".to_string());
+        }
+        out.info(format!("Live probe budget: {}", budget_parts.join(", ")));
+    }
+    out.info(format!(
+        "Accounts: {account_count} total ({enabled_count} enabled, {disabled_count} disabled, {cooling_count} cooling, {rate_limited_count} rate-limited)"
+    ));
+    if account_count > 0 {
+        out.info(format!("Active account: {}", active_index + 1));
+    }
+    out.info(format!(
+        "Forecast: {} ready, {} delayed, {} unavailable",
+        forecast_summary.ready, forecast_summary.delayed, forecast_summary.unavailable
+    ));
+    match recommendation.recommended_index {
+        Some(recommended_index) => {
+            out.info(format!(
+                "Recommendation: account {} ({})",
+                recommended_index + 1,
+                recommendation.reason
+            ));
+        }
+        None => {
+            out.info(format!("Recommendation: {}", recommendation.reason));
+        }
+    }
+    if let Some(output_path) = &resolved_out_path {
+        out.info(format!("Report written: {}", output_path.display()));
+    }
+    if !probe_errors.is_empty() {
+        out.info(format!("Probe notes: {}", probe_errors.len()));
+    }
+    if let Some(snapshot) = &runtime_snapshot {
+        out.info(format!(
+            "Runtime traffic: responses={}, refresh={}, probes={}",
+            snapshot.responses_requests,
+            snapshot.auth_refresh_requests,
+            snapshot.diagnostic_probe_requests
+        ));
+    }
+    if options.explain {
+        out.info("");
+        for result in &forecast_results {
+            out.info(format!(
+                "Account {}: {}, {} risk ({})",
+                result.index + 1,
+                result.availability.as_str(),
+                result.risk_level.as_str(),
+                result.risk_score
+            ));
+            if !result.reasons.is_empty() {
+                out.info(format!("  Reasons: {}", result.reasons.join("; ")));
+            }
+            if let Some(refresh_failure) = refresh_failures.get(&result.index)
+                && let Some(message) = &refresh_failure.message
+            {
+                out.info(format!("  Refresh failure: {message}"));
+            }
+            if let Some(live_quota) = live_quota_by_index.get(&result.index) {
+                out.info(format!(
+                    "  Live quota: {}",
+                    format_quota_snapshot_line(live_quota)
+                ));
+            }
+        }
+    }
+    0
+}
+
+/// Node `path.resolve(cwd, value)` (absolute value wins), including Node's
+/// lexical normalization: `.`/`..` segments collapse and separators become
+/// the platform's, so the `Report written:` echo matches TS byte-for-byte
+/// (`--out C:/x/./report.json` echoes `C:\x\report.json` on Windows). No
+/// filesystem access. Mirrors `cma_storage`'s `node_resolve` component walk.
+fn resolve_against(cwd: &Path, value: &str) -> PathBuf {
+    use std::path::Component;
+    let candidate = Path::new(value);
+    let joined: PathBuf = if candidate.is_absolute() {
+        candidate.to_path_buf()
+    } else if cfg!(windows) && candidate.has_root() {
+        // win32 `\foo` resolves onto the cwd's drive.
+        let mut prefixed = PathBuf::new();
+        if let Some(Component::Prefix(prefix)) = cwd.components().next() {
+            prefixed.push(prefix.as_os_str());
+        }
+        prefixed.push(candidate);
+        prefixed
+    } else {
+        cwd.join(candidate)
+    };
+    let mut normalized = PathBuf::new();
+    for component in joined.components() {
+        match component {
+            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
+            Component::RootDir => normalized.push(std::path::MAIN_SEPARATOR_STR),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !matches!(
+                    normalized.components().next_back(),
+                    None | Some(Component::Prefix(_)) | Some(Component::RootDir)
+                ) {
+                    normalized.pop();
+                }
+            }
+            Component::Normal(part) => normalized.push(part),
+        }
+    }
+    normalized
+}
+
+// ============================================================================
+// Tests — ported from test/codex-manager-report-command.test.ts (core
+// assertions)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_core::schemas::token::TokenSuccess;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    /// Node `path.resolve` parity for the `Report written:` echo: separators
+    /// normalize to the platform's and `.`/`..` segments collapse.
+    #[cfg(windows)]
+    #[test]
+    fn resolve_against_normalizes_like_node_path_resolve_on_windows() {
+        let cwd = Path::new(r"C:\work");
+        assert_eq!(
+            resolve_against(cwd, "C:/x/./report.json"),
+            PathBuf::from(r"C:\x\report.json")
+        );
+        assert_eq!(
+            resolve_against(cwd, "C:/x/sub/../report.json"),
+            PathBuf::from(r"C:\x\report.json")
+        );
+        assert_eq!(
+            resolve_against(cwd, "out/report.json"),
+            PathBuf::from(r"C:\work\out\report.json")
+        );
+        // Drive-relative `\foo` resolves onto the cwd's drive.
+        assert_eq!(
+            resolve_against(cwd, r"\x\report.json"),
+            PathBuf::from(r"C:\x\report.json")
+        );
+    }
+
+    #[cfg(not(windows))]
+    #[test]
+    fn resolve_against_collapses_dot_segments_like_node_path_resolve() {
+        let cwd = Path::new("/work");
+        assert_eq!(
+            resolve_against(cwd, "/x/./report.json"),
+            PathBuf::from("/x/report.json")
+        );
+        assert_eq!(
+            resolve_against(cwd, "out/../report.json"),
+            PathBuf::from("/work/report.json")
+        );
+    }
+
+    fn account(refresh: &str, email: Option<&str>, usable: bool) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        account.account_id = Some(format!("acct-{refresh}"));
+        if usable {
+            account.access_token = Some(format!("access-{refresh}"));
+            account.expires_at = Some(1_000_000 + 10 * 60 * 1000);
+        }
+        account
+    }
+
+    fn snapshot() -> CodexQuotaSnapshot {
+        CodexQuotaSnapshot {
+            status: 200,
+            plan_type: Some("plus".to_string()),
+            active_limit: None,
+            primary: Default::default(),
+            secondary: Default::default(),
+            model: "gpt-5.5".to_string(),
+        }
+    }
+
+    fn deps_with_storage(storage: AccountStorageV3) -> ReportCommandDeps {
+        ReportCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            get_storage_path: Box::new(|| "/tmp/accounts.json".to_string()),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { Some(storage) })
+            }),
+            save_accounts: Box::new(|_| Box::pin(async { Ok(()) })),
+            queued_refresh: Box::new(|_| {
+                Box::pin(async {
+                    TokenResult::Success(TokenSuccess {
+                        access: "refreshed-access".to_string(),
+                        refresh: "refreshed-refresh".to_string(),
+                        expires: 99_999_999,
+                        id_token: None,
+                        multi_account: None,
+                    })
+                })
+            }),
+            fetch_codex_quota_snapshot: Box::new(|_| Box::pin(async { Ok(snapshot()) })),
+            inspect_storage_health: None,
+            load_runtime_observability_snapshot: Some(Box::new(|| Box::pin(async { Ok(None) }))),
+            load_quota_cache: Some(Box::new(|| Box::pin(async { QuotaCacheData::default() }))),
+            get_now: Some(Box::new(|| 1_000_000)),
+            get_cwd: Some(Box::new(|| PathBuf::from("/tmp"))),
+            write_file: Some(Box::new(|_, _| Box::pin(async { Ok(()) }))),
+        }
+    }
+
+    #[test]
+    fn parse_rejects_invalid_budget_values_and_missing_model() {
+        assert_eq!(
+            parse_report_args(&args(&["--max-accounts", "1.5"])),
+            Err("--max-accounts must be a positive integer".to_string())
+        );
+        assert_eq!(
+            parse_report_args(&args(&["--max-accounts", "0"])),
+            Err("--max-accounts must be a positive integer".to_string())
+        );
+        assert_eq!(
+            parse_report_args(&args(&["--max-probes=2abc"])),
+            Err("--max-probes must be a positive integer".to_string())
+        );
+        assert_eq!(
+            parse_report_args(&args(&["--model"])),
+            Err("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_report_args(&args(&["--out"])),
+            Err("Missing value for --out".to_string())
+        );
+        assert_eq!(
+            parse_report_args(&args(&["--bogus"])),
+            Err("Unknown option: --bogus".to_string())
+        );
+        let options = parse_report_args(&args(&[
+            "--live",
+            "--json",
+            "--explain",
+            "--cached-only",
+            "--max-accounts=2",
+            "--max-probes",
+            "3",
+            "--model=gpt-5.5",
+            "--out=report.json",
+        ]))
+        .unwrap();
+        assert!(options.live && options.json && options.explain && options.cached_only);
+        assert_eq!(options.max_accounts, Some(2));
+        assert_eq!(options.max_probes, Some(3));
+        assert_eq!(options.model, "gpt-5.5");
+        assert_eq!(options.out_path.as_deref(), Some("report.json"));
+    }
+
+    #[tokio::test]
+    async fn report_json_shape_and_selected_flag() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com"), true));
+        let deps = deps_with_storage(storage);
+        let mut out = CliOut::capture();
+        let code = run_report_command_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let keys: Vec<&str> = payload
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(String::as_str)
+            .collect();
+        assert_eq!(
+            keys,
+            vec![
+                "command",
+                "generatedAt",
+                "storagePath",
+                "model",
+                "modelSelection",
+                "liveProbe",
+                "liveProbeBudget",
+                "accounts",
+                "activeIndex",
+                "forecast",
+                "runtimeOverlay",
+                "runtime",
+                "runtimeSnapshotLoadError"
+            ]
+        );
+        assert_eq!(payload["generatedAt"], Value::from("1970-01-01T00:16:40.000Z"));
+        assert_eq!(payload["model"], Value::from(DEFAULT_PROBE_MODEL));
+        assert_eq!(payload["activeIndex"], Value::from(1));
+        assert_eq!(payload["runtimeOverlay"], Value::from(false));
+        assert_eq!(payload["runtime"], Value::Null);
+        assert_eq!(payload["runtimeSnapshotLoadError"], Value::Null);
+        // The recommended row is flipped to selected: true.
+        let accounts = payload["forecast"]["accounts"].as_array().unwrap();
+        let recommended = payload["forecast"]["recommendation"]["recommendedIndex"]
+            .as_u64()
+            .expect("recommended index") as usize;
+        assert_eq!(accounts[recommended]["selected"], Value::from(true));
+        assert!(
+            payload["forecast"]["recommendation"]
+                .get("selectedReason")
+                .is_some()
+        );
+    }
+
+    // Account budget: checked at the TOP of each iteration; the budget note
+    // lands in probeErrors and stops the loop.
+    #[tokio::test]
+    async fn live_account_budget_stops_probing() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com"), true));
+        storage.accounts.push(account("rt-b", Some("b@x.com"), true));
+        let probes = Arc::new(AtomicUsize::new(0));
+        let probes_clone = Arc::clone(&probes);
+        let mut deps = deps_with_storage(storage);
+        deps.fetch_codex_quota_snapshot = Box::new(move |_| {
+            probes_clone.fetch_add(1, Ordering::SeqCst);
+            Box::pin(async { Ok(snapshot()) })
+        });
+        let mut out = CliOut::capture();
+        let code = run_report_command_with(
+            &args(&["--json", "--live", "--max-accounts", "1"]),
+            &deps,
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        assert_eq!(probes.load(Ordering::SeqCst), 1);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(
+            payload["liveProbeBudget"]["consideredAccounts"],
+            Value::from(1)
+        );
+        assert_eq!(payload["liveProbeBudget"]["executedProbes"], Value::from(1));
+        let probe_errors = payload["forecast"]["probeErrors"].as_array().unwrap();
+        assert!(probe_errors.contains(&Value::from("live probe account budget reached (1)")));
+    }
+
+    // --cached-only skips refreshes for unusable tokens with the frozen note.
+    #[tokio::test]
+    async fn cached_only_skips_refresh() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com"), false));
+        let refreshes = Arc::new(AtomicUsize::new(0));
+        let refreshes_clone = Arc::clone(&refreshes);
+        let mut deps = deps_with_storage(storage);
+        deps.queued_refresh = Box::new(move |_| {
+            refreshes_clone.fetch_add(1, Ordering::SeqCst);
+            Box::pin(async {
+                TokenResult::Failed(TokenFailure::default())
+            })
+        });
+        let mut out = CliOut::capture();
+        let code = run_report_command_with(
+            &args(&["--json", "--live", "--cached-only"]),
+            &deps,
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        assert_eq!(refreshes.load(Ordering::SeqCst), 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let probe_errors = payload["forecast"]["probeErrors"].as_array().unwrap();
+        assert_eq!(payload["liveProbeBudget"]["cachedOnly"], Value::from(true));
+        assert!(
+            probe_errors
+                .iter()
+                .any(|error| error.as_str().unwrap().ends_with(
+                    ": skipped refresh because --cached-only is enabled"
+                ))
+        );
+    }
+
+    // Report persists FIRST: when the persist fails the in-memory account is
+    // NOT patched and the probe is skipped with a probe error.
+    #[tokio::test]
+    async fn persist_failure_skips_in_memory_apply_and_probe() {
+        let mut storage = AccountStorageV3::empty();
+        let mut unusable = account("rt-a", Some("a@x.com"), false);
+        unusable.account_id = None;
+        storage.accounts.push(unusable);
+        let probes = Arc::new(AtomicUsize::new(0));
+        let probes_clone = Arc::clone(&probes);
+        let mut deps = deps_with_storage(storage);
+        deps.save_accounts = Box::new(|_| {
+            Box::pin(async { Err(CodexError::new("save exploded")) })
+        });
+        deps.fetch_codex_quota_snapshot = Box::new(move |_| {
+            probes_clone.fetch_add(1, Ordering::SeqCst);
+            Box::pin(async { Ok(snapshot()) })
+        });
+        let mut out = CliOut::capture();
+        let code =
+            run_report_command_with(&args(&["--json", "--live"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        // Persist failed → probe never ran for that account.
+        assert_eq!(probes.load(Ordering::SeqCst), 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let probe_errors = payload["forecast"]["probeErrors"].as_array().unwrap();
+        assert_eq!(probe_errors.len(), 1);
+        assert!(probe_errors[0].as_str().unwrap().contains("save exploded"));
+        // No liveQuota / refreshFailure on the serialized row.
+        let row = &payload["forecast"]["accounts"][0];
+        assert!(row.get("liveQuota").is_none());
+        assert!(row.get("refreshFailure").is_none());
+    }
+
+    // --out writes the pretty report + trailing newline atomically (real
+    // writer) in text mode, and prints the confirmation line.
+    #[tokio::test]
+    async fn out_flag_writes_report_file() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com"), true));
+        let mut deps = deps_with_storage(storage);
+        let cwd = dir.path().to_path_buf();
+        deps.get_cwd = Some(Box::new(move || cwd.clone()));
+        deps.write_file = None; // real atomic writer
+        let mut out = CliOut::capture();
+        let code = run_report_command_with(
+            &args(&["--out", "nested/report.json"]),
+            &deps,
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 0);
+        let written =
+            std::fs::read_to_string(dir.path().join("nested").join("report.json")).expect("read");
+        assert!(written.ends_with("\n"));
+        let payload: Value = serde_json::from_str(&written).expect("json");
+        assert_eq!(payload["command"], Value::from("report"));
+        assert!(out.info_text().contains("Report written: "));
+    }
+
+    // Text mode prints the frozen lines in order.
+    #[tokio::test]
+    async fn text_mode_prints_report_lines() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com"), true));
+        let deps = deps_with_storage(storage);
+        let mut out = CliOut::capture();
+        let code = run_report_command_with(&args(&["--explain"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Report generated at 1970-01-01T00:16:40.000Z");
+        assert_eq!(lines[1], "Storage: /tmp/accounts.json");
+        assert!(lines[2].starts_with("Model: "));
+        assert!(lines[3].starts_with("Accounts: 1 total (1 enabled, 0 disabled"));
+        assert_eq!(lines[4], "Active account: 1");
+        assert!(lines[5].starts_with("Forecast: "));
+        assert!(lines[6].starts_with("Recommendation: "));
+        assert!(text.contains("Account 1: "));
+    }
+}
diff --git a/crates/manager/src/commands/rotation.rs b/crates/manager/src/commands/rotation.rs
new file mode 100644
index 000000000..cabece6e3
--- /dev/null
+++ b/crates/manager/src/commands/rotation.rs
@@ -0,0 +1,1537 @@
+//! Port of `lib/codex-manager/commands/rotation.ts`.
+//!
+//! Behavior source: spec 08 §4.15. Gotchas honored here:
+//! - `rotation status` and `reset-rate-limits` save/restore the process
+//!   storage-path scope (all other commands just set null and leave it);
+//!   `reset-rate-limits` HOLDS the null scope across load AND save.
+//! - reset-rate-limits deletes only rate-limit keys whose reset time is in
+//!   the FUTURE; the JSON `changes` array must equal the actual mutation;
+//!   `restartHint` only on real (non-dry-run) changes.
+//! - Helper-status file: 1 MiB cap, `kind` must equal
+//!   `"codex-app-runtime-rotation-helper"`, `state ∈ {stopped, idle-timeout}`
+//!   counts as not running, EPERM-alive PID check, label suppressed when it
+//!   contains `"@"` (email leak guard), `lastAccountEmail` never read.
+//! - `reset-runtime` / `reset-rate-limits` JSON output is COMPACT.
+
+use cma_accounts::manager::AccountManager;
+use cma_accounts::manager_persistence::{format_account_label, format_cooldown};
+use cma_accounts::rate_limits::format_wait_time;
+use cma_core::constants::APP_RUNTIME_HELPER_STATUS_FILE;
+use cma_core::env_parsing::parse_boolean_env;
+use cma_core::json_io::stringify_compact;
+use cma_core::model_family::ModelFamily;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_core::utils::now_ms;
+use cma_quota::cache::{load_quota_cache, QuotaCacheData};
+use cma_quota::readiness::{find_quota_cache_entry_for_account, is_quota_cache_entry_exhausted};
+use cma_runtime::app_bind::{
+    bind_codex_app_runtime_rotation, format_app_bind_status, get_app_bind_status,
+    is_process_alive, unbind_codex_app_runtime_rotation, AppBindOptions, AppBindResult,
+    AppBindStatus,
+};
+use cma_runtime::current_account::{
+    app_runtime_helper_status_to_signal, resolve_account_current_markers,
+    resolve_runtime_current_account, AppRuntimeHelperAccountStatus, RuntimeCurrentAccountOptions,
+    RuntimeCurrentAccountSources,
+};
+use cma_runtime::observability::{
+    load_persisted_runtime_observability_snapshot, record_runtime_reset,
+    RuntimeObservabilitySnapshot,
+};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_get_storage_path, default_load_accounts, default_save_accounts,
+    default_set_storage_path, save_accounts_with_retry_boxed, BoxFuture, GetStoragePathFn,
+    LoadAccountsFn, SaveAccountsFn, SetStoragePathFn,
+};
+use crate::rate_limit_markers::is_rate_limited_marker;
+
+// ============================================================================
+// App-runtime-helper status file (rotation.ts keeps its OWN tolerant reader —
+// it additionally reads idleExpiresAt/totalRequests/rotations and hardcodes
+// lastAccountEmail to null for privacy)
+// ============================================================================
+
+const MAX_STATUS_FILE_BYTES: u64 = 1024 * 1024; // 1 MB sanity cap
+
+/// TS local `AppRuntimeHelperStatus`.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct AppRuntimeHelperStatus {
+    pub kind: Option<String>,
+    pub state: Option<String>,
+    pub pid: Option<i64>,
+    pub idle_expires_at: Option<i64>,
+    pub total_requests: Option<i64>,
+    pub rotations: Option<i64>,
+    pub last_account_index: Option<i64>,
+    pub last_account_label: Option<String>,
+    /// Deliberately never read from disk — privacy.
+    pub last_account_email: Option<String>,
+    pub last_account_id: Option<String>,
+    pub last_account_updated_at: Option<i64>,
+    pub updated_at: Option<i64>,
+}
+
+fn read_optional_number(record: &Map<String, Value>, key: &str) -> Option<i64> {
+    let value = record.get(key)?;
+    let number = value.as_f64().filter(|v| v.is_finite())?;
+    Some(number as i64)
+}
+
+fn read_optional_string(record: &Map<String, Value>, key: &str) -> Option<String> {
+    let value = record.get(key)?.as_str()?;
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `readAppRuntimeHelperStatus()`.
+pub fn read_app_runtime_helper_status() -> Option<AppRuntimeHelperStatus> {
+    let status_path = get_codex_multi_auth_dir().join(APP_RUNTIME_HELPER_STATUS_FILE);
+    if !status_path.exists() {
+        return None;
+    }
+    let metadata = std::fs::metadata(&status_path).ok()?;
+    if metadata.len() > MAX_STATUS_FILE_BYTES {
+        return None;
+    }
+    let raw = std::fs::read_to_string(&status_path).ok()?;
+    let parsed: Value = serde_json::from_str(&raw).ok()?;
+    let record = parsed.as_object()?;
+    Some(AppRuntimeHelperStatus {
+        state: read_optional_string(record, "state"),
+        kind: read_optional_string(record, "kind"),
+        pid: read_optional_number(record, "pid"),
+        idle_expires_at: read_optional_number(record, "idleExpiresAt"),
+        total_requests: read_optional_number(record, "totalRequests"),
+        rotations: read_optional_number(record, "rotations"),
+        last_account_index: read_optional_number(record, "lastAccountIndex"),
+        last_account_label: read_optional_string(record, "lastAccountLabel"),
+        last_account_email: None,
+        last_account_id: read_optional_string(record, "lastAccountId"),
+        last_account_updated_at: read_optional_number(record, "lastAccountUpdatedAt"),
+        updated_at: read_optional_number(record, "updatedAt"),
+    })
+}
+
+fn format_helper_last_account(status: &AppRuntimeHelperStatus) -> Option<String> {
+    if let Some(label) = &status.last_account_label
+        && !label.contains('@')
+    {
+        return Some(label.clone());
+    }
+    if let Some(id) = &status.last_account_id {
+        return Some(match status.last_account_index {
+            Some(index) => format!("Account {} ({id})", index + 1),
+            None => id.clone(),
+        });
+    }
+    status
+        .last_account_index
+        .map(|index| format!("Account {}", index + 1))
+}
+
+/// TS `formatAppRuntimeHelperStatus(now, status)`.
+pub fn format_app_runtime_helper_status(now: i64, status: Option<&AppRuntimeHelperStatus>) -> String {
+    let Some(status) = status else {
+        return "Codex app helper: not running".to_string();
+    };
+    if status.kind.as_deref() != Some("codex-app-runtime-rotation-helper") {
+        return "Codex app helper: not running".to_string();
+    }
+    let alive = is_process_alive(status.pid);
+    if !alive
+        || status.state.as_deref() == Some("stopped")
+        || status.state.as_deref() == Some("idle-timeout")
+    {
+        return "Codex app helper: not running".to_string();
+    }
+    let mut parts = vec![match status.pid {
+        Some(pid) if pid != 0 => format!("running pid={pid}"),
+        _ => "running".to_string(),
+    }];
+    if let Some(total_requests) = status.total_requests {
+        parts.push(format!("requests={total_requests}"));
+    }
+    if let Some(rotations) = status.rotations {
+        parts.push(format!("rotations={rotations}"));
+    }
+    if let Some(last_account) = format_helper_last_account(status) {
+        parts.push(format!("lastAccount={last_account}"));
+    }
+    if let Some(idle_expires_at) = status.idle_expires_at
+        && idle_expires_at > now
+    {
+        parts.push(format!("idle-expires={}", format_wait_time(idle_expires_at - now)));
+    }
+    format!("Codex app helper: {}", parts.join(", "))
+}
+
+fn to_runtime_helper_account_status(status: &AppRuntimeHelperStatus) -> AppRuntimeHelperAccountStatus {
+    AppRuntimeHelperAccountStatus {
+        kind: status.kind.clone(),
+        state: status.state.clone(),
+        pid: status.pid,
+        last_account_index: status.last_account_index,
+        last_account_label: status.last_account_label.clone(),
+        last_account_email: status.last_account_email.clone(),
+        last_account_id: status.last_account_id.clone(),
+        last_account_updated_at: status.last_account_updated_at,
+        updated_at: status.updated_at,
+    }
+}
+
+/// TS `shouldAutoBindCodexApp(env)` — `CODEX_MULTI_AUTH_APP_BIND_INSTALL`,
+/// default `"1"`; auto-bind disabled only when ∈ {"0","false","no"}.
+fn should_auto_bind_codex_app() -> bool {
+    let override_value = std::env::var("CODEX_MULTI_AUTH_APP_BIND_INSTALL")
+        .unwrap_or_else(|_| "1".to_string())
+        .trim()
+        .to_lowercase();
+    !matches!(override_value.as_str(), "0" | "false" | "no")
+}
+
+fn format_env_override() -> String {
+    let raw = std::env::var("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY").ok();
+    let Some(raw) = raw else {
+        return "none".to_string();
+    };
+    if raw.trim().is_empty() {
+        return "none".to_string();
+    }
+    match parse_boolean_env(Some(&raw)) {
+        None => format!("invalid ({raw})"),
+        Some(true) => "enabled".to_string(),
+        Some(false) => "disabled".to_string(),
+    }
+}
+
+// ============================================================================
+// Deps
+// ============================================================================
+
+type AppBindActionFn = Box<dyn Fn() -> BoxFuture<Result<AppBindResult, String>> + Send + Sync>;
+
+/// TS `RotationCommandDeps` (log sinks live on [`CliOut`]).
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct RotationCommandDeps {
+    pub load_plugin_config: Box<dyn Fn() -> PluginConfig + Send + Sync>,
+    pub save_plugin_config:
+        Box<dyn Fn(Map<String, Value>) -> BoxFuture<Result<(), String>> + Send + Sync>,
+    pub get_codex_runtime_rotation_proxy: Box<dyn Fn(&PluginConfig) -> bool + Send + Sync>,
+    pub load_accounts: LoadAccountsFn,
+    pub save_accounts: Option<SaveAccountsFn>,
+    pub resolve_active_index: Box<dyn Fn(&AccountStorageV3) -> usize + Send + Sync>,
+    pub get_storage_path: GetStoragePathFn,
+    pub set_storage_path: SetStoragePathFn,
+    pub bind_codex_app: Option<AppBindActionFn>,
+    pub unbind_codex_app: Option<AppBindActionFn>,
+    pub get_codex_app_bind_status:
+        Option<Box<dyn Fn() -> BoxFuture<Result<AppBindStatus, String>> + Send + Sync>>,
+    pub load_runtime_observability_snapshot:
+        Option<Box<dyn Fn() -> BoxFuture<Option<RuntimeObservabilitySnapshot>> + Send + Sync>>,
+    pub load_quota_cache: Option<Box<dyn Fn() -> BoxFuture<Option<QuotaCacheData>> + Send + Sync>>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+    /// Test seams for the process-global reset effects.
+    pub reset_volatile_runtime_state: Box<dyn Fn() + Send + Sync>,
+    pub record_runtime_reset: Box<dyn Fn(&str) + Send + Sync>,
+    /// Test seam over [`read_app_runtime_helper_status`].
+    pub read_helper_status: Box<dyn Fn() -> Option<AppRuntimeHelperStatus> + Send + Sync>,
+}
+
+impl Default for RotationCommandDeps {
+    fn default() -> Self {
+        RotationCommandDeps {
+            load_plugin_config: Box::new(cma_config::load::load_plugin_config),
+            save_plugin_config: Box::new(|patch| {
+                Box::pin(async move {
+                    cma_config::save::save_plugin_config(&patch)
+                        .await
+                        .map_err(|error| error.to_string())
+                })
+            }),
+            get_codex_runtime_rotation_proxy: Box::new(|config| {
+                cma_config::getters::get_codex_runtime_rotation_proxy(config)
+            }),
+            load_accounts: default_load_accounts(),
+            save_accounts: Some(default_save_accounts()),
+            resolve_active_index: Box::new(|storage| {
+                cma_runtime::account_status::resolve_active_index(storage, ModelFamily::Codex)
+            }),
+            get_storage_path: default_get_storage_path(),
+            set_storage_path: default_set_storage_path(),
+            bind_codex_app: Some(Box::new(|| {
+                Box::pin(async { bind_codex_app_runtime_rotation(&AppBindOptions::default()).await })
+            })),
+            unbind_codex_app: Some(Box::new(|| {
+                Box::pin(async {
+                    unbind_codex_app_runtime_rotation(&AppBindOptions::default()).await
+                })
+            })),
+            get_codex_app_bind_status: Some(Box::new(|| {
+                Box::pin(async { get_app_bind_status(&AppBindOptions::default()).await })
+            })),
+            load_runtime_observability_snapshot: Some(Box::new(|| {
+                Box::pin(async { load_persisted_runtime_observability_snapshot() })
+            })),
+            load_quota_cache: Some(Box::new(|| {
+                Box::pin(async { Some(load_quota_cache().await) })
+            })),
+            get_now: None,
+            reset_volatile_runtime_state: Box::new(AccountManager::reset_volatile_runtime_state),
+            record_runtime_reset: Box::new(record_runtime_reset),
+            read_helper_status: Box::new(read_app_runtime_helper_status),
+        }
+    }
+}
+
+fn print_rotation_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth rotation enable",
+            "  codex-multi-auth rotation disable",
+            "  codex-multi-auth rotation status",
+            "  codex-multi-auth rotation bind-app",
+            "  codex-multi-auth rotation unbind-app",
+            "  codex-multi-auth rotation reset-rate-limits [--all | --account <idx>] [--dry-run] [--json]",
+            "  codex-multi-auth rotation reset-runtime [--json]",
+            "",
+            "Behavior:",
+            "  - Runtime rotation is enabled by default for request-bearing Codex sessions",
+            "  - Binds the packaged Codex desktop app to the same localhost router when enabled or repaired",
+            "  - Use CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0 to disable the proxy for the current process without changing persistent settings",
+            "  - reset-rate-limits clears stored rateLimitResetTimes and active coolingDownUntil entries; use when `fix --live` confirms quota is available but the proxy still returns 503 pool-exhausted",
+            "  - reset-runtime clears process-local runtime trackers and re-applies the Codex app bind when available",
+        ]
+        .join("\n"),
+    );
+}
+
+// ============================================================================
+// reset-runtime
+// ============================================================================
+
+async fn run_reset_runtime(args: &[String], deps: &RotationCommandDeps, out: &mut CliOut) -> i32 {
+    let mut json = false;
+    for arg in args {
+        if arg == "--json" || arg == "-j" {
+            json = true;
+            continue;
+        }
+        if arg == "--help" || arg == "-h" || arg == "help" {
+            out.info("Usage: codex-multi-auth rotation reset-runtime [--json]");
+            return 0;
+        }
+        out.error(format!("Unknown reset-runtime option: {arg}"));
+        return 1;
+    }
+
+    let mut unbind: Option<AppBindResult> = None;
+    let mut bind: Option<AppBindResult> = None;
+    let mut app_bind_restarted = false;
+    if let (Some(unbind_codex_app), Some(bind_codex_app)) =
+        (&deps.unbind_codex_app, &deps.bind_codex_app)
+    {
+        let restart = async {
+            let unbind_result = unbind_codex_app().await?;
+            let bind_result = bind_codex_app().await?;
+            Ok::<(AppBindResult, AppBindResult), String>((unbind_result, bind_result))
+        }
+        .await;
+        match restart {
+            Ok((unbind_result, bind_result)) => {
+                unbind = Some(unbind_result);
+                bind = Some(bind_result);
+                app_bind_restarted = true;
+            }
+            Err(message) => {
+                if json {
+                    let mut payload = Map::new();
+                    payload.insert("ok".into(), Value::from(false));
+                    payload.insert("command".into(), Value::from("rotation reset-runtime"));
+                    payload.insert("resetVolatileRuntimeState".into(), Value::from(false));
+                    payload.insert("appBindRestarted".into(), Value::from(app_bind_restarted));
+                    payload.insert("error".into(), Value::from(message));
+                    out.info(stringify_compact(&Value::Object(payload)));
+                } else {
+                    out.error(format!(
+                        "Runtime reset completed, but app bind restart failed: {message}"
+                    ));
+                }
+                return 1;
+            }
+        }
+    }
+    (deps.reset_volatile_runtime_state)();
+    (deps.record_runtime_reset)("rotation-reset-runtime");
+    if json {
+        let mut payload = Map::new();
+        payload.insert("ok".into(), Value::from(true));
+        payload.insert("command".into(), Value::from("rotation reset-runtime"));
+        payload.insert("resetVolatileRuntimeState".into(), Value::from(true));
+        payload.insert("appBindRestarted".into(), Value::from(app_bind_restarted));
+        payload.insert(
+            "unbindStatus".into(),
+            unbind
+                .as_ref()
+                .and_then(|result| result.status.state.as_ref())
+                .map(|state| serde_json::to_value(state).unwrap_or(Value::Null))
+                .unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "bindStatus".into(),
+            bind.as_ref()
+                .and_then(|result| result.status.state.as_ref())
+                .map(|state| serde_json::to_value(state).unwrap_or(Value::Null))
+                .unwrap_or(Value::Null),
+        );
+        out.info(stringify_compact(&Value::Object(payload)));
+    } else {
+        out.info("Runtime rotation volatile state reset.");
+        if app_bind_restarted {
+            out.info("Codex app bind restarted.");
+        } else {
+            out.info("Codex app bind helpers unavailable; new wrapper sessions will use the reset state.");
+        }
+    }
+    0
+}
+
+// ============================================================================
+// reset-rate-limits
+// ============================================================================
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ResetScope {
+    All,
+    Account,
+}
+
+impl ResetScope {
+    fn as_str(self) -> &'static str {
+        match self {
+            ResetScope::All => "all",
+            ResetScope::Account => "account",
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq)]
+struct ResetRateLimitsOptions {
+    scope: ResetScope,
+    account_index: Option<usize>,
+    dry_run: bool,
+    json: bool,
+}
+
+enum ParseResetRateLimits {
+    Ok(ResetRateLimitsOptions),
+    Help,
+    Err(String),
+}
+
+fn parse_reset_rate_limits_args(args: &[String]) -> ParseResetRateLimits {
+    let mut scope = ResetScope::All;
+    let mut scope_explicit = false;
+    let mut account_index: Option<usize> = None;
+    let mut dry_run = false;
+    let mut json = false;
+
+    let mut i = 0;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--help" || arg == "-h" || arg == "help" {
+            return ParseResetRateLimits::Help;
+        }
+        if arg == "--all" {
+            if scope_explicit && scope != ResetScope::All {
+                return ParseResetRateLimits::Err(
+                    "--all and --account are mutually exclusive".to_string(),
+                );
+            }
+            scope = ResetScope::All;
+            scope_explicit = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--account" {
+            if scope_explicit && scope == ResetScope::All {
+                return ParseResetRateLimits::Err(
+                    "--all and --account are mutually exclusive".to_string(),
+                );
+            }
+            let Some(next) = args.get(i + 1) else {
+                return ParseResetRateLimits::Err("--account requires a 1-based index".to_string());
+            };
+            if next.is_empty() || !next.chars().all(|c| c.is_ascii_digit()) {
+                return ParseResetRateLimits::Err(format!(
+                    "--account expects a positive 1-based integer, got: {next}"
+                ));
+            }
+            let Ok(parsed) = next.parse::<i64>() else {
+                return ParseResetRateLimits::Err(format!(
+                    "--account expects a positive 1-based integer, got: {next}"
+                ));
+            };
+            if parsed < 1 {
+                return ParseResetRateLimits::Err(format!(
+                    "--account expects a positive 1-based integer, got: {next}"
+                ));
+            }
+            scope = ResetScope::Account;
+            scope_explicit = true;
+            account_index = Some((parsed - 1) as usize);
+            i += 2;
+            continue;
+        }
+        if arg == "--dry-run" {
+            dry_run = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--json" || arg == "-j" {
+            json = true;
+            i += 1;
+            continue;
+        }
+        return ParseResetRateLimits::Err(format!("Unknown reset-rate-limits option: {arg}"));
+    }
+
+    ParseResetRateLimits::Ok(ResetRateLimitsOptions {
+        scope,
+        account_index,
+        dry_run,
+        json,
+    })
+}
+
+fn print_reset_rate_limits_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth rotation reset-rate-limits [--all | --account <idx>] [--dry-run] [--json]",
+            "",
+            "Options:",
+            "  --all              Clear timers for every account (default)",
+            "  --account <idx>    Clear timers for a single 1-based account index",
+            "  --dry-run          Report what would change without writing",
+            "  --json, -j         Print machine-readable JSON output",
+            "",
+            "Notes:",
+            "  - Clears stored rateLimitResetTimes entries with reset times still in the future",
+            "    and any active coolingDownUntil entries.",
+            "  - Use when `codex-multi-auth fix --live` confirms upstream quota is available but the",
+            "    runtime rotation proxy still returns 503 pool-exhausted.",
+            "  - If a runtime rotation proxy is currently running it may re-persist its in-memory",
+            "    timers and revert these changes. After clearing, run `codex-multi-auth rotation disable`",
+            "    then `codex-multi-auth rotation enable` (or restart the Codex app) to flush in-memory",
+            "    state and reload from disk.",
+        ]
+        .join("\n"),
+    );
+}
+
+const RESET_RATE_LIMITS_RESTART_HINT: &str =
+    "If a runtime rotation proxy is currently running it may re-persist its in-memory timers and revert these changes. Run `codex-multi-auth rotation disable` then `codex-multi-auth rotation enable` (or restart the Codex app) to flush in-memory state and reload from disk.";
+
+/// Build a privacy-safe label for reset-rate-limits change reports —
+/// deliberately no email (PII): `account {i+1} (id:***{last4})`.
+fn redacted_reset_rate_limits_label(account: &AccountMetadataV3, index: usize) -> String {
+    let id = account.account_id.as_deref().unwrap_or("");
+    let tail = if id.chars().count() > 4 {
+        let count = id.chars().count();
+        let (byte_idx, _) = id.char_indices().nth(count - 4).expect("count > 4");
+        format!("***{}", &id[byte_idx..])
+    } else {
+        "***".to_string()
+    };
+    format!("account {} (id:{tail})", index + 1)
+}
+
+struct ResetRateLimitsAccountChange {
+    index: usize,
+    label: String,
+    cleared_rate_limit_keys: Vec<String>,
+    cleared_cooling_down: bool,
+}
+
+async fn run_reset_rate_limits(
+    args: &[String],
+    deps: &RotationCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    let now = deps.get_now.as_ref().map(|f| f()).unwrap_or_else(now_ms);
+
+    let options = match parse_reset_rate_limits_args(args) {
+        ParseResetRateLimits::Err(error) => {
+            out.error(error);
+            return 1;
+        }
+        ParseResetRateLimits::Help => {
+            print_reset_rate_limits_usage(out);
+            return 0;
+        }
+        ParseResetRateLimits::Ok(options) => options,
+    };
+    let ResetRateLimitsOptions {
+        scope,
+        account_index,
+        dry_run,
+        json,
+    } = options;
+
+    // Keep the shared (non-project-scoped) path scope active across both load
+    // AND save so that `saveAccounts` writes to the same file we loaded from.
+    // Restoring the previous path between load and save would silently route
+    // the write to the project storage file.
+    let previous_storage_path = (deps.get_storage_path)();
+    (deps.set_storage_path)(None);
+    let result = run_reset_rate_limits_scoped(
+        deps,
+        out,
+        now,
+        scope,
+        account_index,
+        dry_run,
+        json,
+    )
+    .await;
+    (deps.set_storage_path)(Some(previous_storage_path.as_str()));
+    result
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn run_reset_rate_limits_scoped(
+    deps: &RotationCommandDeps,
+    out: &mut CliOut,
+    now: i64,
+    scope: ResetScope,
+    account_index: Option<usize>,
+    dry_run: bool,
+    json: bool,
+) -> i32 {
+    let storage = (deps.load_accounts)().await;
+    let storage_path = (deps.get_storage_path)();
+
+    let Some(mut storage) = storage.filter(|storage| !storage.accounts.is_empty()) else {
+        if json {
+            let mut payload = Map::new();
+            payload.insert("ok".into(), Value::from(false));
+            payload.insert("error".into(), Value::from("no accounts configured"));
+            payload.insert("storagePath".into(), Value::from(storage_path));
+            out.info(stringify_compact(&Value::Object(payload)));
+        } else {
+            out.error("No accounts configured.");
+        }
+        return 1;
+    };
+
+    if scope == ResetScope::Account {
+        let Some(index) = account_index else {
+            out.error("internal: account scope without index");
+            return 1;
+        };
+        if index >= storage.accounts.len() {
+            let message = format!(
+                "Account index out of range (1..{}): {}",
+                storage.accounts.len(),
+                index + 1
+            );
+            if json {
+                let mut payload = Map::new();
+                payload.insert("ok".into(), Value::from(false));
+                payload.insert("error".into(), Value::from(message));
+                payload.insert("storagePath".into(), Value::from(storage_path));
+                out.info(stringify_compact(&Value::Object(payload)));
+            } else {
+                out.error(message);
+            }
+            return 1;
+        }
+    }
+
+    let target_indexes: Vec<usize> = match scope {
+        ResetScope::All => (0..storage.accounts.len()).collect(),
+        ResetScope::Account => account_index.into_iter().collect(),
+    };
+    let mut changes: Vec<ResetRateLimitsAccountChange> = Vec::new();
+
+    for &index in &target_indexes {
+        let Some(account) = storage.accounts.get_mut(index) else {
+            continue;
+        };
+        let cleared_rate_limit_keys: Vec<String> = account
+            .rate_limit_reset_times
+            .as_ref()
+            .map(|times| {
+                times
+                    .iter()
+                    .filter(|(_, value)| *value > now)
+                    .map(|(key, _)| key.to_string())
+                    .collect()
+            })
+            .unwrap_or_default();
+        let cleared_cooling_down = account.cooling_down_until.is_some_and(|until| until > now);
+        if cleared_rate_limit_keys.is_empty() && !cleared_cooling_down {
+            continue;
+        }
+        changes.push(ResetRateLimitsAccountChange {
+            index,
+            label: redacted_reset_rate_limits_label(account, index),
+            cleared_rate_limit_keys: cleared_rate_limit_keys.clone(),
+            cleared_cooling_down,
+        });
+        if !dry_run {
+            // Only delete the keys we reported (future-active resets) so
+            // callers who inspect the JSON output can trust the report matches
+            // the action exactly. Past entries are no-ops and are pruned
+            // naturally by clearExpiredRateLimits.
+            if let Some(times) = account.rate_limit_reset_times.as_mut() {
+                for key in &cleared_rate_limit_keys {
+                    times.remove(key);
+                }
+            }
+            if cleared_cooling_down {
+                account.cooling_down_until = None;
+            }
+        }
+    }
+
+    if !dry_run && !changes.is_empty() {
+        let Some(save_accounts) = &deps.save_accounts else {
+            let message =
+                "reset-rate-limits requires writable account storage but saveAccounts dep was not provided";
+            if json {
+                let mut payload = Map::new();
+                payload.insert("ok".into(), Value::from(false));
+                payload.insert("error".into(), Value::from(message));
+                payload.insert("storagePath".into(), Value::from(storage_path));
+                out.info(stringify_compact(&Value::Object(payload)));
+            } else {
+                out.error(message);
+            }
+            return 1;
+        };
+        // Use saveAccountsWithRetry to absorb transient Windows EBUSY/EPERM
+        // contention, matching every other saveAccounts call site.
+        if let Err(error) = save_accounts_with_retry_boxed(&storage, save_accounts).await {
+            let code = error.code();
+            let message = if !code.is_empty() {
+                format!("Failed to persist reset-rate-limits ({code}); rate-limit timers were not cleared.")
+            } else {
+                format!("Failed to persist reset-rate-limits: {}", error.message())
+            };
+            if json {
+                let mut payload = Map::new();
+                payload.insert("ok".into(), Value::from(false));
+                payload.insert("error".into(), Value::from(message));
+                payload.insert("storagePath".into(), Value::from(storage_path));
+                out.info(stringify_compact(&Value::Object(payload)));
+            } else {
+                out.error(message);
+            }
+            return 1;
+        }
+    }
+
+    if json {
+        let mut payload = Map::new();
+        payload.insert("ok".into(), Value::from(true));
+        payload.insert("dryRun".into(), Value::from(dry_run));
+        payload.insert("scope".into(), Value::from(scope.as_str()));
+        payload.insert("storagePath".into(), Value::from(storage_path));
+        payload.insert(
+            "accountsScanned".into(),
+            Value::from(target_indexes.len() as i64),
+        );
+        payload.insert("accountsChanged".into(), Value::from(changes.len() as i64));
+        payload.insert(
+            "changes".into(),
+            Value::Array(
+                changes
+                    .iter()
+                    .map(|change| {
+                        let mut row = Map::new();
+                        row.insert("index".into(), Value::from(change.index as i64));
+                        row.insert("label".into(), Value::from(change.label.clone()));
+                        row.insert(
+                            "clearedRateLimitKeys".into(),
+                            Value::Array(
+                                change
+                                    .cleared_rate_limit_keys
+                                    .iter()
+                                    .cloned()
+                                    .map(Value::from)
+                                    .collect(),
+                            ),
+                        );
+                        row.insert(
+                            "clearedCoolingDown".into(),
+                            Value::from(change.cleared_cooling_down),
+                        );
+                        Value::Object(row)
+                    })
+                    .collect(),
+            ),
+        );
+        if !changes.is_empty() && !dry_run {
+            payload.insert(
+                "restartHint".into(),
+                Value::from(RESET_RATE_LIMITS_RESTART_HINT),
+            );
+        }
+        out.info(stringify_compact(&Value::Object(payload)));
+        return 0;
+    }
+
+    if changes.is_empty() {
+        out.info(match scope {
+            ResetScope::All => {
+                "No accounts had active rate-limit or cooldown timers to clear.".to_string()
+            }
+            ResetScope::Account => format!(
+                "Account {} had no active rate-limit or cooldown timers to clear.",
+                account_index.unwrap_or(0) + 1
+            ),
+        });
+        return 0;
+    }
+
+    out.info(format!(
+        "{} {}/{} account(s):",
+        if dry_run { "Would clear" } else { "Cleared" },
+        changes.len(),
+        target_indexes.len()
+    ));
+    for change in &changes {
+        let mut parts: Vec<String> = Vec::new();
+        if !change.cleared_rate_limit_keys.is_empty() {
+            parts.push(format!(
+                "rate-limit keys: {}",
+                change.cleared_rate_limit_keys.join(", ")
+            ));
+        }
+        if change.cleared_cooling_down {
+            parts.push("cooldown".to_string());
+        }
+        out.info(format!(
+            "  {}. {} | {}",
+            change.index + 1,
+            change.label,
+            parts.join(" | ")
+        ));
+    }
+    if dry_run {
+        out.info("(dry-run; no changes written)");
+    } else {
+        out.info(format!("Note: {RESET_RATE_LIMITS_RESTART_HINT}"));
+    }
+    0
+}
+
+// ============================================================================
+// status
+// ============================================================================
+
+async fn print_codex_app_bind_status(
+    deps: &RotationCommandDeps,
+    out: &mut CliOut,
+) -> Option<AppBindStatus> {
+    let Some(get_status) = &deps.get_codex_app_bind_status else {
+        out.info("Codex app bind: unavailable");
+        return None;
+    };
+    match get_status().await {
+        Ok(status) => {
+            out.info(format_app_bind_status(&status));
+            Some(status)
+        }
+        Err(message) => {
+            out.info(format!("Codex app bind: unavailable ({message})"));
+            None
+        }
+    }
+}
+
+async fn print_rotation_status(deps: &RotationCommandDeps, out: &mut CliOut) -> i32 {
+    let previous_storage_path = (deps.get_storage_path)();
+    let now = deps.get_now.as_ref().map(|f| f()).unwrap_or_else(now_ms);
+    // Rotation status reports the shared Codex account pool, not a
+    // project-scoped override.
+    (deps.set_storage_path)(None);
+    let config = (deps.load_plugin_config)();
+    let env_override =
+        parse_boolean_env(std::env::var("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY").ok().as_deref());
+    let enabled = env_override.unwrap_or_else(|| (deps.get_codex_runtime_rotation_proxy)(&config));
+    let storage = (deps.load_accounts)().await;
+    let storage_path = (deps.get_storage_path)();
+    (deps.set_storage_path)(Some(previous_storage_path.as_str()));
+
+    out.info(format!(
+        "Runtime rotation proxy: {}",
+        if enabled { "enabled" } else { "disabled" }
+    ));
+    out.info(format!(
+        "Stored setting: {}",
+        if config.codex_runtime_rotation_proxy == Some(true) {
+            "enabled"
+        } else {
+            "disabled"
+        }
+    ));
+    out.info(format!("Env override: {}", format_env_override()));
+    let helper_status = (deps.read_helper_status)();
+    out.info(format_app_runtime_helper_status(now, helper_status.as_ref()));
+    let app_bind_status = print_codex_app_bind_status(deps, out).await;
+    out.info(format!("Storage: {storage_path}"));
+
+    let Some(storage) = storage.filter(|storage| !storage.accounts.is_empty()) else {
+        out.info("Accounts: none configured");
+        return 0;
+    };
+
+    let active_index = (deps.resolve_active_index)(&storage);
+    let (runtime_snapshot, quota_cache) = tokio::join!(
+        async {
+            match &deps.load_runtime_observability_snapshot {
+                Some(load) => load().await,
+                None => None,
+            }
+        },
+        async {
+            match &deps.load_quota_cache {
+                Some(load) => load().await,
+                None => None,
+            }
+        },
+    );
+    let runtime_current = resolve_runtime_current_account(
+        &storage,
+        &RuntimeCurrentAccountSources {
+            runtime_snapshot,
+            app_bind_status: app_bind_status
+                .as_ref()
+                .filter(|status| status.running)
+                .and_then(|status| status.router.clone()),
+            app_helper_status: app_runtime_helper_status_to_signal(
+                helper_status
+                    .as_ref()
+                    .map(to_runtime_helper_account_status)
+                    .as_ref(),
+            ),
+        },
+        RuntimeCurrentAccountOptions {
+            now: Some(now),
+            max_age_ms: None,
+        },
+    );
+    out.info(format!("Accounts: {}", storage.accounts.len()));
+    for (index, account) in storage.accounts.iter().enumerate() {
+        let mut markers: Vec<String> =
+            resolve_account_current_markers(index, active_index, runtime_current.as_ref())
+                .into_iter()
+                .map(|marker| marker.as_str().to_string())
+                .collect();
+        if account.enabled == Some(false) {
+            markers.push("disabled".to_string());
+        }
+        if let Some(cooldown) = format_cooldown(
+            account.cooling_down_until,
+            account.cooldown_reason.as_ref().map(|reason| reason.as_str()),
+            now,
+        ) {
+            markers.push(format!("cooldown:{cooldown}"));
+        }
+        let future_resets: Vec<i64> = account
+            .rate_limit_reset_times
+            .as_ref()
+            .map(|times| times.iter().map(|(_, value)| value).filter(|v| *v > now).collect())
+            .unwrap_or_default();
+        if !future_resets.is_empty() {
+            let wait_ms = future_resets.iter().min().copied().unwrap_or(now) - now;
+            markers.push(format!("rate-limited:{}", format_wait_time(wait_ms)));
+        }
+        let quota_entry =
+            find_quota_cache_entry_for_account(quota_cache.as_ref(), account, &storage.accounts);
+        if quota_entry.is_some_and(|entry| entry.status == 429.0)
+            && !markers.iter().any(|marker| is_rate_limited_marker(marker))
+        {
+            markers.push("rate-limited".to_string());
+        }
+        if is_quota_cache_entry_exhausted(quota_entry, now) {
+            markers.push("quota-exhausted".to_string());
+        }
+        let marker_label = if markers.is_empty() {
+            String::new()
+        } else {
+            format!(" [{}]", markers.join(", "))
+        };
+        out.info(format!(
+            "{}. {}{marker_label}",
+            index + 1,
+            format_account_label(Some(account), index)
+        ));
+    }
+
+    0
+}
+
+// ============================================================================
+// entry
+// ============================================================================
+
+/// Production entry.
+pub async fn run_rotation_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_rotation_command_with(args, &RotationCommandDeps::default(), out).await
+}
+
+/// TS `runRotationCommand(args, deps)`.
+pub async fn run_rotation_command_with(
+    args: &[String],
+    deps: &RotationCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    let subcommand = args.first().map(String::as_str);
+    let rest = if args.len() > 1 { &args[1..] } else { &[] };
+    match subcommand {
+        None | Some("status") => {
+            if let Some(first) = rest.first() {
+                out.error(format!("Unknown rotation status option: {first}"));
+                return 1;
+            }
+            return print_rotation_status(deps, out).await;
+        }
+        Some("--help") | Some("-h") | Some("help") => {
+            print_rotation_usage(out);
+            return 0;
+        }
+        Some("reset-rate-limits") => return run_reset_rate_limits(rest, deps, out).await,
+        Some("reset-runtime") => return run_reset_runtime(rest, deps, out).await,
+        _ => {}
+    }
+    let subcommand = subcommand.expect("checked above");
+    if let Some(first) = rest.first() {
+        // enable/disable/bind-app/unbind-app take no extra args; the unknown
+        // check runs before the subcommand branch (TS order).
+        if matches!(subcommand, "enable" | "disable" | "bind-app" | "unbind-app") {
+            out.error(format!("Unknown rotation option: {first}"));
+            return 1;
+        }
+    }
+    match subcommand {
+        "enable" => {
+            let mut patch = Map::new();
+            patch.insert("codexRuntimeRotationProxy".into(), Value::from(true));
+            if let Err(error) = (deps.save_plugin_config)(patch).await {
+                out.error(error);
+                return 1;
+            }
+            out.info("Runtime rotation proxy enabled.");
+            out.info("New Codex sessions will route Responses traffic through the localhost proxy.");
+            if let Some(bind_codex_app) = &deps.bind_codex_app
+                && should_auto_bind_codex_app()
+            {
+                match bind_codex_app().await {
+                    Ok(result) => {
+                        out.info(result.message.clone());
+                        out.info(format_app_bind_status(&result.status));
+                    }
+                    Err(message) => {
+                        out.error(format!("Codex app bind failed: {message}"));
+                        out.info("Wrapper-launched CLI and app sessions still use runtime rotation.");
+                    }
+                }
+            }
+            0
+        }
+        "disable" => {
+            let mut patch = Map::new();
+            patch.insert("codexRuntimeRotationProxy".into(), Value::from(false));
+            if let Err(error) = (deps.save_plugin_config)(patch).await {
+                out.error(error);
+                return 1;
+            }
+            out.info("Runtime rotation proxy disabled.");
+            if let Some(unbind_codex_app) = &deps.unbind_codex_app {
+                match unbind_codex_app().await {
+                    Ok(result) => {
+                        out.info(result.message.clone());
+                        out.info(format_app_bind_status(&result.status));
+                    }
+                    Err(message) => {
+                        out.error(format!("Codex app unbind failed: {message}"));
+                        return 1;
+                    }
+                }
+            }
+            0
+        }
+        "bind-app" => {
+            let Some(bind_codex_app) = &deps.bind_codex_app else {
+                out.error("Codex app bind is unavailable in this build.");
+                return 1;
+            };
+            match bind_codex_app().await {
+                Ok(result) => {
+                    out.info(result.message.clone());
+                    out.info(format_app_bind_status(&result.status));
+                    0
+                }
+                Err(message) => {
+                    out.error(message);
+                    1
+                }
+            }
+        }
+        "unbind-app" => {
+            let Some(unbind_codex_app) = &deps.unbind_codex_app else {
+                out.error("Codex app bind is unavailable in this build.");
+                return 1;
+            };
+            match unbind_codex_app().await {
+                Ok(result) => {
+                    out.info(result.message.clone());
+                    out.info(format_app_bind_status(&result.status));
+                    0
+                }
+                Err(message) => {
+                    out.error(message);
+                    1
+                }
+            }
+        }
+        other => {
+            out.error(format!("Unknown rotation command: {other}"));
+            print_rotation_usage(out);
+            1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::RateLimitStateV3;
+    use std::sync::{Arc, Mutex};
+
+    fn args(values: &[&str]) -> Vec<String> {
+        values.iter().map(|s| s.to_string()).collect()
+    }
+
+    struct Harness {
+        deps: RotationCommandDeps,
+        saved: Arc<Mutex<Option<AccountStorageV3>>>,
+        saved_config: Arc<Mutex<Vec<Map<String, Value>>>>,
+        path_scopes: Arc<Mutex<Vec<Option<String>>>>,
+    }
+
+    fn harness(storage: Option<AccountStorageV3>) -> Harness {
+        let saved: Arc<Mutex<Option<AccountStorageV3>>> = Arc::new(Mutex::new(None));
+        let saved_clone = Arc::clone(&saved);
+        let saved_config: Arc<Mutex<Vec<Map<String, Value>>>> = Arc::new(Mutex::new(Vec::new()));
+        let saved_config_clone = Arc::clone(&saved_config);
+        let path_scopes: Arc<Mutex<Vec<Option<String>>>> = Arc::new(Mutex::new(Vec::new()));
+        let path_scopes_clone = Arc::clone(&path_scopes);
+        let deps = RotationCommandDeps {
+            load_plugin_config: Box::new(PluginConfig::default),
+            save_plugin_config: Box::new(move |patch| {
+                saved_config_clone.lock().unwrap().push(patch);
+                Box::pin(async { Ok(()) })
+            }),
+            get_codex_runtime_rotation_proxy: Box::new(|config| {
+                config.codex_runtime_rotation_proxy.unwrap_or(true)
+            }),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { storage })
+            }),
+            save_accounts: Some(Box::new(move |storage| {
+                let saved = Arc::clone(&saved_clone);
+                Box::pin(async move {
+                    *saved.lock().unwrap() = Some(storage);
+                    Ok(())
+                })
+            })),
+            resolve_active_index: Box::new(|_| 0),
+            get_storage_path: Box::new(|| "/shared/accounts.json".to_string()),
+            set_storage_path: Box::new(move |path| {
+                path_scopes_clone
+                    .lock()
+                    .unwrap()
+                    .push(path.map(str::to_string));
+            }),
+            bind_codex_app: None,
+            unbind_codex_app: None,
+            get_codex_app_bind_status: None,
+            load_runtime_observability_snapshot: None,
+            load_quota_cache: None,
+            get_now: Some(Box::new(|| 1_000_000)),
+            reset_volatile_runtime_state: Box::new(|| {}),
+            record_runtime_reset: Box::new(|_| {}),
+            read_helper_status: Box::new(|| None),
+        };
+        Harness {
+            deps,
+            saved,
+            saved_config,
+            path_scopes,
+        }
+    }
+
+    fn storage_with_timers() -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        // Account 1: future + past rate limits and an active cooldown.
+        let mut a = AccountMetadataV3::new("token-a", 1, 1);
+        a.account_id = Some("acct_1234567890".to_string());
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", 2_000_000); // future
+        times.insert("codex:gpt-5.5", 500); // past — preserved
+        a.rate_limit_reset_times = Some(times);
+        a.cooling_down_until = Some(1_500_000);
+        storage.accounts.push(a);
+        // Account 2: nothing active.
+        storage.accounts.push(AccountMetadataV3::new("token-b", 1, 1));
+        storage
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_clears_future_only_and_persists() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-rate-limits"]), &h.deps, &mut out).await,
+            0
+        );
+        let saved = h.saved.lock().unwrap().clone().expect("saved");
+        let times = saved.accounts[0].rate_limit_reset_times.as_ref().unwrap();
+        assert!(!times.contains_key("codex"));
+        // Past entry deliberately preserved.
+        assert_eq!(times.get("codex:gpt-5.5"), Some(500));
+        assert_eq!(saved.accounts[0].cooling_down_until, None);
+        let text = out.info_text();
+        assert!(text.starts_with("Cleared 1/2 account(s):"));
+        assert!(text.contains("  1. account 1 (id:***7890) | rate-limit keys: codex | cooldown"));
+        assert!(text.contains(&format!("Note: {RESET_RATE_LIMITS_RESTART_HINT}")));
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_dry_run_reports_without_saving() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(
+                &args(&["reset-rate-limits", "--dry-run"]),
+                &h.deps,
+                &mut out
+            )
+            .await,
+            0
+        );
+        assert!(h.saved.lock().unwrap().is_none());
+        let text = out.info_text();
+        assert!(text.starts_with("Would clear 1/2 account(s):"));
+        assert!(text.contains("(dry-run; no changes written)"));
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_json_is_compact_with_restart_hint() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-rate-limits", "--json"]), &h.deps, &mut out)
+                .await,
+            0
+        );
+        let text = out.info_text();
+        assert!(!text.contains('\n'));
+        let payload: Value = serde_json::from_str(&text).expect("json");
+        assert_eq!(payload["ok"], Value::from(true));
+        assert_eq!(payload["scope"], Value::from("all"));
+        assert_eq!(payload["accountsScanned"], Value::from(2));
+        assert_eq!(payload["accountsChanged"], Value::from(1));
+        assert_eq!(
+            payload["changes"][0]["clearedRateLimitKeys"],
+            serde_json::json!(["codex"])
+        );
+        assert_eq!(payload["changes"][0]["clearedCoolingDown"], Value::from(true));
+        assert_eq!(
+            payload["restartHint"],
+            Value::from(RESET_RATE_LIMITS_RESTART_HINT)
+        );
+        // No email leaked into labels.
+        assert!(!text.contains('@'));
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_json_omits_hint_for_dry_run_and_noop() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        run_rotation_command_with(
+            &args(&["reset-rate-limits", "--json", "--dry-run"]),
+            &h.deps,
+            &mut out,
+        )
+        .await;
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert!(payload.get("restartHint").is_none());
+
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("t", 1, 1));
+        let h = harness(Some(storage));
+        let mut out = CliOut::capture();
+        run_rotation_command_with(&args(&["reset-rate-limits", "--json"]), &h.deps, &mut out)
+            .await;
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["accountsChanged"], Value::from(0));
+        assert!(payload.get("restartHint").is_none());
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_scope_and_range_checks() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(
+                &args(&["reset-rate-limits", "--account", "9"]),
+                &h.deps,
+                &mut out
+            )
+            .await,
+            1
+        );
+        assert_eq!(out.error_text(), "Account index out of range (1..2): 9");
+
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(
+                &args(&["reset-rate-limits", "--all", "--account", "1"]),
+                &h.deps,
+                &mut out
+            )
+            .await,
+            1
+        );
+        assert_eq!(out.error_text(), "--all and --account are mutually exclusive");
+
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(
+                &args(&["reset-rate-limits", "--account", "1", "--all"]),
+                &h.deps,
+                &mut out
+            )
+            .await,
+            1
+        );
+        assert_eq!(out.error_text(), "--all and --account are mutually exclusive");
+
+        for bad in ["1.5", "abc", "-2", "0"] {
+            let mut out = CliOut::capture();
+            assert_eq!(
+                run_rotation_command_with(
+                    &args(&["reset-rate-limits", "--account", bad]),
+                    &h.deps,
+                    &mut out
+                )
+                .await,
+                1,
+                "value {bad:?}"
+            );
+            assert_eq!(
+                out.error_text(),
+                format!("--account expects a positive 1-based integer, got: {bad}")
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_noop_message_without_save_dep() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("t", 1, 1));
+        let mut h = harness(Some(storage));
+        h.deps.save_accounts = None;
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-rate-limits"]), &h.deps, &mut out).await,
+            0
+        );
+        assert_eq!(
+            out.info_text(),
+            "No accounts had active rate-limit or cooldown timers to clear."
+        );
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_fails_fast_when_save_dep_missing() {
+        let mut h = harness(Some(storage_with_timers()));
+        h.deps.save_accounts = None;
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-rate-limits"]), &h.deps, &mut out).await,
+            1
+        );
+        assert_eq!(
+            out.error_text(),
+            "reset-rate-limits requires writable account storage but saveAccounts dep was not provided"
+        );
+    }
+
+    #[tokio::test]
+    async fn reset_rate_limits_holds_null_scope_across_load_and_save() {
+        let h = harness(Some(storage_with_timers()));
+        let mut out = CliOut::capture();
+        run_rotation_command_with(&args(&["reset-rate-limits"]), &h.deps, &mut out).await;
+        let scopes = h.path_scopes.lock().unwrap().clone();
+        // set(null) up front, restore(previous) at the end — nothing between.
+        assert_eq!(
+            scopes,
+            vec![None, Some("/shared/accounts.json".to_string())]
+        );
+    }
+
+    #[tokio::test]
+    async fn reset_runtime_json_without_helpers() {
+        let reset_called = Arc::new(Mutex::new(false));
+        let reset_clone = Arc::clone(&reset_called);
+        let recorded: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+        let recorded_clone = Arc::clone(&recorded);
+        let mut h = harness(None);
+        h.deps.reset_volatile_runtime_state = Box::new(move || {
+            *reset_clone.lock().unwrap() = true;
+        });
+        h.deps.record_runtime_reset = Box::new(move |reason| {
+            recorded_clone.lock().unwrap().push(reason.to_string());
+        });
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-runtime", "--json"]), &h.deps, &mut out).await,
+            0
+        );
+        let text = out.info_text();
+        assert!(!text.contains('\n'));
+        let payload: Value = serde_json::from_str(&text).expect("json");
+        assert_eq!(payload["ok"], Value::from(true));
+        assert_eq!(payload["command"], Value::from("rotation reset-runtime"));
+        assert_eq!(payload["resetVolatileRuntimeState"], Value::from(true));
+        assert_eq!(payload["appBindRestarted"], Value::from(false));
+        assert_eq!(payload["unbindStatus"], Value::Null);
+        assert_eq!(payload["bindStatus"], Value::Null);
+        assert!(*reset_called.lock().unwrap());
+        assert_eq!(recorded.lock().unwrap().as_slice(), ["rotation-reset-runtime"]);
+    }
+
+    #[tokio::test]
+    async fn reset_runtime_text_reports_wrapper_fallback() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["reset-runtime"]), &h.deps, &mut out).await,
+            0
+        );
+        let text = out.info_text();
+        assert!(text.contains("Runtime rotation volatile state reset."));
+        assert!(text.contains(
+            "Codex app bind helpers unavailable; new wrapper sessions will use the reset state."
+        ));
+    }
+
+    #[tokio::test]
+    async fn enable_and_disable_write_config() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_rotation_command_with(&args(&["enable"]), &h.deps, &mut out).await, 0);
+        let text = out.info_text();
+        assert!(text.contains("Runtime rotation proxy enabled."));
+        assert!(text.contains(
+            "New Codex sessions will route Responses traffic through the localhost proxy."
+        ));
+        let mut out = CliOut::capture();
+        assert_eq!(run_rotation_command_with(&args(&["disable"]), &h.deps, &mut out).await, 0);
+        assert!(out.info_text().contains("Runtime rotation proxy disabled."));
+        let saved = h.saved_config.lock().unwrap();
+        assert_eq!(saved.len(), 2);
+        assert_eq!(saved[0]["codexRuntimeRotationProxy"], Value::from(true));
+        assert_eq!(saved[1]["codexRuntimeRotationProxy"], Value::from(false));
+    }
+
+    #[tokio::test]
+    async fn bind_app_unavailable_in_this_build() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_rotation_command_with(&args(&["bind-app"]), &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "Codex app bind is unavailable in this build.");
+    }
+
+    #[tokio::test]
+    async fn unknown_subcommand_prints_usage() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_rotation_command_with(&args(&["bogus"]), &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "Unknown rotation command: bogus");
+        assert!(out.info_text().starts_with("Usage:"));
+    }
+
+    #[tokio::test]
+    async fn status_rejects_extra_args() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_rotation_command_with(&args(&["status", "--json"]), &h.deps, &mut out).await,
+            1
+        );
+        assert_eq!(out.error_text(), "Unknown rotation status option: --json");
+    }
+
+    #[test]
+    fn helper_status_formatting_guards() {
+        // Not running: wrong kind.
+        let status = AppRuntimeHelperStatus {
+            kind: Some("other".to_string()),
+            ..Default::default()
+        };
+        assert_eq!(
+            format_app_runtime_helper_status(0, Some(&status)),
+            "Codex app helper: not running"
+        );
+        // Running: own pid is alive; email-shaped label suppressed.
+        let status = AppRuntimeHelperStatus {
+            kind: Some("codex-app-runtime-rotation-helper".to_string()),
+            state: Some("running".to_string()),
+            pid: Some(std::process::id() as i64),
+            total_requests: Some(7),
+            rotations: Some(2),
+            last_account_index: Some(0),
+            last_account_label: Some("user@example.com".to_string()),
+            last_account_id: Some("acct_9".to_string()),
+            idle_expires_at: Some(61_000),
+            ..Default::default()
+        };
+        let line = format_app_runtime_helper_status(1_000, Some(&status));
+        assert!(line.starts_with(&format!(
+            "Codex app helper: running pid={}",
+            std::process::id()
+        )));
+        assert!(line.contains("requests=7"));
+        assert!(line.contains("rotations=2"));
+        assert!(line.contains("lastAccount=Account 1 (acct_9)"));
+        assert!(!line.contains("user@example.com"));
+        assert!(line.contains("idle-expires=1m"));
+        // stopped state counts as not running even when alive.
+        let stopped = AppRuntimeHelperStatus {
+            state: Some("stopped".to_string()),
+            ..status
+        };
+        assert_eq!(
+            format_app_runtime_helper_status(1_000, Some(&stopped)),
+            "Codex app helper: not running"
+        );
+    }
+}
diff --git a/crates/manager/src/commands/status.rs b/crates/manager/src/commands/status.rs
new file mode 100644
index 000000000..557fa8335
--- /dev/null
+++ b/crates/manager/src/commands/status.rs
@@ -0,0 +1,747 @@
+//! Port of `lib/codex-manager/commands/status.ts` (`status`/`list` +
+//! `features`).
+//!
+//! Behavior source: spec 08 §4.16. `status --json` emits the identical key
+//! set in the empty-storage branch (nulls + `accounts: []`) — consumers rely
+//! on one stable shape (gotcha 11). The marker order is contract (gotcha 12):
+//! current → disabled → rate-limited → 429-from-quota (dedup via
+//! `isRateLimitedMarker`) → quota-exhausted → cooldown.
+
+use cma_accounts::manager_persistence::{format_account_label, format_cooldown, format_workspace_lines};
+use cma_accounts::rate_limits::format_wait_time;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::utils::now_ms;
+use cma_quota::cache::{load_quota_cache, QuotaCacheData};
+use cma_quota::forecast::{evaluate_forecast_accounts, recommend_forecast_account, ForecastAccountInput};
+use cma_quota::readiness::{find_quota_cache_entry_for_account, is_quota_cache_entry_exhausted};
+use cma_runtime::app_bind::{get_app_bind_status, AppBindOptions, AppBindRouterStatus};
+use cma_runtime::current_account::{
+    read_app_runtime_helper_account_signal, resolve_account_current_markers,
+    resolve_runtime_current_account, RuntimeAccountSignal, RuntimeCurrentAccountOptions,
+    RuntimeCurrentAccountSelection, RuntimeCurrentAccountSources,
+};
+use cma_runtime::observability::{
+    load_persisted_runtime_observability_snapshot, RuntimeObservabilitySnapshot,
+};
+use cma_storage::health::{inspect_storage_health, StorageHealthSummary};
+use cma_storage::load::LoadedAccountStorage;
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_get_storage_path, default_set_storage_path, BoxFuture, GetStoragePathFn,
+    SetStoragePathFn,
+};
+use crate::rate_limit_markers::is_rate_limited_marker;
+
+// ============================================================================
+// IMPLEMENTED_FEATURES (dispatcher table; ids and names are output verbatim)
+// ============================================================================
+
+/// TS `IMPLEMENTED_FEATURES` — used by the `features` command.
+pub const IMPLEMENTED_FEATURES: [(u32, &str); 54] = [
+    (1, "Multi-account OAuth login dashboard"),
+    (2, "Account add/update dedupe by token/id/email"),
+    (3, "Set current account command"),
+    (4, "Per-family active index handling"),
+    (5, "Quick health check command"),
+    (6, "Full refresh check command"),
+    (7, "Flagged account verification command"),
+    (8, "Flagged account restore flow"),
+    (9, "Best account forecast engine"),
+    (10, "Forecast live quota probing"),
+    (11, "Auto-fix command (safe mode)"),
+    (12, "Doctor diagnostics command"),
+    (13, "JSON outputs for machine automation"),
+    (14, "Report generation command"),
+    (15, "Storage v3 normalization and migration"),
+    (16, "Storage backup and recovery journal"),
+    (17, "Project-scoped and global storage paths"),
+    (18, "Quota cache storage"),
+    (19, "Live account sync watcher"),
+    (20, "Session affinity store"),
+    (21, "Refresh queue dedupe (in-process)"),
+    (22, "Refresh lease dedupe (cross-process)"),
+    (23, "Token rotation mapping in refresh queue"),
+    (24, "Refresh guardian (proactive refresh)"),
+    (25, "Preemptive quota scheduler"),
+    (26, "Entitlement cache for unsupported models"),
+    (27, "Capability policy scoring store"),
+    (28, "Failure policy evaluation module"),
+    (29, "Streaming failover pipeline"),
+    (30, "Rate-limit backoff and cooldown handling"),
+    (31, "Host request transformer bridge"),
+    (32, "Prompt template sync with cache"),
+    (33, "Codex CLI active-account state sync"),
+    (34, "TUI quick-switch hotkeys (1-9)"),
+    (35, "TUI search and help toggles"),
+    (36, "TUI account detail hotkeys (S/R/E/D)"),
+    (37, "TUI settings hub (list/summary/behavior/theme)"),
+    (38, "Dashboard display customization"),
+    (39, "Unified color/theme runtime (v2 UI)"),
+    (40, "OAuth browser-first flow with manual callback fallback"),
+    (41, "Auto-switch to best account command"),
+    (42, "Device-code OAuth login (--device-auth)"),
+    (43, "Workspace/org-bound login (--org)"),
+    (44, "Manual pin, unpin, and affinity-generation invalidation"),
+    (45, "Per-account workspace selection command"),
+    (46, "Default-on runtime Responses rotation proxy"),
+    (47, "Reversible packaged Codex app bind and launcher routing"),
+    (48, "Local usage ledger, budgets, and account policies"),
+    (49, "Routing profiles and model capability matrix"),
+    (50, "Local bridge tokens and integration snippets"),
+    (51, "Provider-agnostic local history listing"),
+    (52, "Why-selected and monitor diagnostics"),
+    (53, "Config explain, init-config templates, and debug bundle"),
+    (54, "mcodex convenience launcher (monitor/tmux/forward)"),
+];
+
+/// TS `runFeaturesCommand(deps)`.
+pub fn run_features_command(out: &mut CliOut) -> i32 {
+    out.info(format!("Implemented features ({})", IMPLEMENTED_FEATURES.len()));
+    out.info("");
+    for (id, name) in IMPLEMENTED_FEATURES {
+        out.info(format!("{id}. {name}"));
+    }
+    0
+}
+
+// ============================================================================
+// status / list
+// ============================================================================
+
+type FormatRateLimitEntryFn =
+    Box<dyn Fn(&AccountMetadataV3, i64) -> Option<String> + Send + Sync>;
+
+/// TS `StatusCommandDeps` (log sinks live on [`CliOut`]).
+pub struct StatusCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub get_storage_path: GetStoragePathFn,
+    pub load_accounts: Box<dyn Fn() -> BoxFuture<Option<LoadedAccountStorage>> + Send + Sync>,
+    pub resolve_active_index: Box<dyn Fn(&AccountStorageV3) -> usize + Send + Sync>,
+    pub format_rate_limit_entry: FormatRateLimitEntryFn,
+    pub load_runtime_observability_snapshot:
+        Option<Box<dyn Fn() -> BoxFuture<Option<RuntimeObservabilitySnapshot>> + Send + Sync>>,
+    pub load_app_bind_status:
+        Option<Box<dyn Fn() -> BoxFuture<Option<AppBindRouterStatus>> + Send + Sync>>,
+    pub load_app_helper_status: Option<Box<dyn Fn() -> Option<RuntimeAccountSignal> + Send + Sync>>,
+    pub load_quota_cache: Option<Box<dyn Fn() -> BoxFuture<Option<QuotaCacheData>> + Send + Sync>>,
+    pub inspect_storage_health:
+        Option<Box<dyn Fn() -> BoxFuture<StorageHealthSummary> + Send + Sync>>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+    /// When true, emit a single machine-readable JSON object (cli-manager-03).
+    pub json: bool,
+}
+
+impl StatusCommandDeps {
+    /// Production wiring (matches the TS dispatcher's `runListOrStatusCommand`).
+    pub fn production(json: bool) -> Self {
+        StatusCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            get_storage_path: default_get_storage_path(),
+            load_accounts: Box::new(|| Box::pin(cma_storage::load::load_accounts())),
+            resolve_active_index: Box::new(|storage| {
+                cma_runtime::account_status::resolve_active_index(storage, ModelFamily::Codex)
+            }),
+            format_rate_limit_entry: Box::new(|account, now| {
+                cma_runtime::account_status::format_rate_limit_entry(
+                    account.rate_limit_reset_times.as_ref(),
+                    now,
+                    &format_wait_time,
+                    ModelFamily::Codex,
+                )
+            }),
+            load_runtime_observability_snapshot: Some(Box::new(|| {
+                Box::pin(async { load_persisted_runtime_observability_snapshot() })
+            })),
+            load_app_bind_status: Some(Box::new(|| {
+                Box::pin(async {
+                    // TS: getAppBindStatus().then(s => s.running ? s.router :
+                    // null).catch(() => null)
+                    match get_app_bind_status(&AppBindOptions::default()).await {
+                        Ok(status) if status.running => status.router,
+                        _ => None,
+                    }
+                })
+            })),
+            load_app_helper_status: Some(Box::new(read_app_runtime_helper_account_signal)),
+            load_quota_cache: Some(Box::new(|| {
+                Box::pin(async { Some(load_quota_cache().await) })
+            })),
+            inspect_storage_health: Some(Box::new(|| Box::pin(inspect_storage_health()))),
+            get_now: None,
+            json,
+        }
+    }
+}
+
+const RESTORE_REASONS: [&str; 3] = ["empty-storage", "intentional-reset", "missing-storage"];
+
+/// Build the status marker list for one account (cli-manager-03). Order
+/// matters and is preserved: current → disabled → rate-limited →
+/// 429-from-quota → quota-exhausted → cooldown.
+#[allow(clippy::too_many_arguments)]
+fn build_account_markers(
+    account: &AccountMetadataV3,
+    index: usize,
+    active_index: usize,
+    runtime_current: Option<&RuntimeCurrentAccountSelection>,
+    now: i64,
+    quota_cache: Option<&QuotaCacheData>,
+    all_accounts: &[AccountMetadataV3],
+    format_rate_limit_entry: &FormatRateLimitEntryFn,
+) -> Vec<String> {
+    let mut markers: Vec<String> = resolve_account_current_markers(index, active_index, runtime_current)
+        .into_iter()
+        .map(|marker| marker.as_str().to_string())
+        .collect();
+    if account.enabled == Some(false) {
+        markers.push("disabled".to_string());
+    }
+    if format_rate_limit_entry(account, now).is_some() {
+        markers.push("rate-limited".to_string());
+    }
+    let quota_entry = find_quota_cache_entry_for_account(quota_cache, account, all_accounts);
+    if quota_entry.is_some_and(|entry| entry.status == 429.0)
+        && !markers.iter().any(|marker| is_rate_limited_marker(marker))
+    {
+        markers.push("rate-limited".to_string());
+    }
+    if is_quota_cache_entry_exhausted(quota_entry, now) {
+        markers.push("quota-exhausted".to_string());
+    }
+    if let Some(cooldown) = format_cooldown(
+        account.cooling_down_until,
+        account.cooldown_reason.as_ref().map(|reason| reason.as_str()),
+        now,
+    ) {
+        markers.push(format!("cooldown:{cooldown}"));
+    }
+    markers
+}
+
+fn format_runtime_last_account(snapshot: &RuntimeObservabilitySnapshot) -> Option<String> {
+    if let Some(label) = &snapshot.last_account_label
+        && !label.is_empty()
+        && !label.contains('@')
+    {
+        return Some(label.clone());
+    }
+    if let Some(id) = &snapshot.last_account_id
+        && !id.is_empty()
+    {
+        return Some(match snapshot.last_account_index {
+            Some(index) => format!("Account {} ({id})", index + 1),
+            None => id.clone(),
+        });
+    }
+    if let Some(index) = snapshot.last_account_index {
+        return Some(format!("Account {}", index + 1));
+    }
+    None
+}
+
+/// Production entry (dispatcher precomputes `json` from `--json`/`-j`).
+pub async fn run_status_command(json: bool, out: &mut CliOut) -> i32 {
+    run_status_command_with(&StatusCommandDeps::production(json), out).await
+}
+
+/// TS `runStatusCommand(deps)`.
+pub async fn run_status_command_with(deps: &StatusCommandDeps, out: &mut CliOut) -> i32 {
+    (deps.set_storage_path)(None);
+    let loaded = (deps.load_accounts)().await;
+    let path = (deps.get_storage_path)();
+    let storage_health = match &deps.inspect_storage_health {
+        Some(inspect) => Some(inspect().await),
+        None => None,
+    };
+
+    let is_empty = loaded
+        .as_ref()
+        .map(|loaded| loaded.storage.accounts.is_empty())
+        .unwrap_or(true);
+    if is_empty {
+        let restore_reason = loaded
+            .as_ref()
+            .and_then(|loaded| loaded.restore.as_ref())
+            .map(|restore| restore.restore_reason)
+            .filter(|reason| RESTORE_REASONS.contains(reason));
+        let effective_state: Option<String> = if restore_reason == Some("intentional-reset") {
+            Some("intentional-reset".to_string())
+        } else if let Some(health) = &storage_health {
+            Some(health.state.as_str().to_string())
+        } else if matches!(restore_reason, Some("empty-storage") | Some("missing-storage")) {
+            Some("empty".to_string())
+        } else {
+            None
+        };
+        if deps.json {
+            let mut payload = Map::new();
+            payload.insert("storagePath".into(), Value::from(path));
+            payload.insert(
+                "storageHealth".into(),
+                effective_state.clone().map(Value::from).unwrap_or(Value::Null),
+            );
+            payload.insert("accountCount".into(), Value::from(0));
+            // Emit the same keys the populated branch does (as null) so a
+            // --json consumer sees one stable shape regardless of account
+            // count.
+            payload.insert("activeIndex".into(), Value::Null);
+            payload.insert("pinnedAccountIndex".into(), Value::Null);
+            payload.insert("recommendedIndex".into(), Value::Null);
+            payload.insert("recommendationReason".into(), Value::Null);
+            payload.insert("runtimeInUseIndex".into(), Value::Null);
+            payload.insert("accounts".into(), Value::Array(Vec::new()));
+            out.info(stringify_pretty2(&Value::Object(payload)));
+            return 0;
+        }
+        out.info(match effective_state.as_deref() {
+            Some("intentional-reset") => "No accounts configured. Storage was intentionally reset.",
+            Some("recoverable") => "No accounts configured. Recovery artifacts are available.",
+            Some("corrupt") => "No accounts configured. Storage appears corrupted.",
+            _ => "No accounts configured.",
+        });
+        out.info(format!("Storage: {path}"));
+        if let Some(state) = effective_state {
+            out.info(format!("Storage health: {state}"));
+        }
+        return 0;
+    }
+
+    let storage = loaded.expect("non-empty checked above").storage;
+    let now = deps.get_now.as_ref().map(|f| f()).unwrap_or_else(now_ms);
+    let active_index = (deps.resolve_active_index)(&storage);
+    let forecast_inputs: Vec<ForecastAccountInput<'_>> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| ForecastAccountInput::new(index, account, index == active_index, now))
+        .collect();
+    let forecast_results = evaluate_forecast_accounts(&forecast_inputs);
+    let recommendation = recommend_forecast_account(&forecast_results);
+    if !deps.json {
+        out.info(format!("Accounts ({})", storage.accounts.len()));
+        out.info(format!("Storage: {path}"));
+        if let Some(recommended_index) = recommendation.recommended_index {
+            out.info(format!(
+                "Selection reason: account {} ({})",
+                recommended_index + 1,
+                recommendation.reason
+            ));
+        }
+        if let Some(health) = &storage_health {
+            out.info(format!("Storage health: {}", health.state.as_str()));
+        }
+    }
+    let app_helper_status = deps.load_app_helper_status.as_ref().and_then(|load| load());
+    let (runtime_snapshot, app_bind_status, quota_cache) = tokio::join!(
+        async {
+            match &deps.load_runtime_observability_snapshot {
+                Some(load) => load().await,
+                None => None,
+            }
+        },
+        async {
+            match &deps.load_app_bind_status {
+                Some(load) => load().await,
+                None => None,
+            }
+        },
+        async {
+            match &deps.load_quota_cache {
+                Some(load) => load().await,
+                None => None,
+            }
+        },
+    );
+    let runtime_current = resolve_runtime_current_account(
+        &storage,
+        &RuntimeCurrentAccountSources {
+            runtime_snapshot: runtime_snapshot.clone(),
+            app_bind_status,
+            app_helper_status,
+        },
+        RuntimeCurrentAccountOptions {
+            now: Some(now),
+            max_age_ms: None,
+        },
+    );
+
+    // cli-manager-03: machine-readable output for status/list.
+    if deps.json {
+        let accounts: Vec<Value> = storage
+            .accounts
+            .iter()
+            .enumerate()
+            .map(|(i, account)| {
+                let markers = build_account_markers(
+                    account,
+                    i,
+                    active_index,
+                    runtime_current.as_ref(),
+                    now,
+                    quota_cache.as_ref(),
+                    &storage.accounts,
+                    &deps.format_rate_limit_entry,
+                );
+                let mut row = Map::new();
+                row.insert("index".into(), Value::from(i as i64));
+                row.insert(
+                    "label".into(),
+                    Value::from(format_account_label(Some(account), i)),
+                );
+                row.insert("enabled".into(), Value::from(account.enabled != Some(false)));
+                row.insert("current".into(), Value::from(i == active_index));
+                row.insert(
+                    "markers".into(),
+                    Value::Array(markers.into_iter().map(Value::from).collect()),
+                );
+                row.insert(
+                    "lastUsed".into(),
+                    if account.last_used > 0 {
+                        Value::from(account.last_used)
+                    } else {
+                        Value::Null
+                    },
+                );
+                row.insert(
+                    "reason".into(),
+                    forecast_results
+                        .get(i)
+                        .and_then(|result| result.reasons.first())
+                        .map(|reason| Value::from(reason.clone()))
+                        .unwrap_or(Value::Null),
+                );
+                Value::Object(row)
+            })
+            .collect();
+        let mut payload = Map::new();
+        payload.insert("storagePath".into(), Value::from(path));
+        payload.insert(
+            "storageHealth".into(),
+            storage_health
+                .as_ref()
+                .map(|health| Value::from(health.state.as_str()))
+                .unwrap_or(Value::Null),
+        );
+        payload.insert("accountCount".into(), Value::from(storage.accounts.len() as i64));
+        payload.insert("activeIndex".into(), Value::from(active_index as i64));
+        payload.insert(
+            "pinnedAccountIndex".into(),
+            storage
+                .pinned_account_index
+                .map(Value::from)
+                .unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "recommendedIndex".into(),
+            recommendation
+                .recommended_index
+                .map(|index| Value::from(index as i64))
+                .unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "recommendationReason".into(),
+            Value::from(recommendation.reason.clone()),
+        );
+        payload.insert(
+            "runtimeInUseIndex".into(),
+            runtime_current
+                .as_ref()
+                .map(|current| Value::from(current.index as i64))
+                .unwrap_or(Value::Null),
+        );
+        payload.insert("accounts".into(), Value::Array(accounts));
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return 0;
+    }
+
+    if let Some(snapshot) = &runtime_snapshot {
+        let runtime_metrics = &snapshot.runtime_metrics;
+        let pool_cooldown = snapshot
+            .pool_exhaustion_cooldown_until
+            .filter(|until| *until > now)
+            .map(|until| format_wait_time(until - now));
+        let server_cooldown = snapshot
+            .server_burst_cooldown_until
+            .filter(|until| *until > now)
+            .map(|until| format_wait_time(until - now));
+        out.info(format!(
+            "Runtime: responses={}, refresh={}, probes={}, budgetExhaustions={}",
+            snapshot.responses_requests,
+            snapshot.auth_refresh_requests,
+            snapshot.diagnostic_probe_requests,
+            runtime_metrics.request_attempt_budget_exhaustions
+        ));
+        if let Some(last_runtime_account) = format_runtime_last_account(snapshot) {
+            out.info(format!("Last runtime account: {last_runtime_account}"));
+        }
+        if pool_cooldown.is_some() || server_cooldown.is_some() {
+            out.info(format!(
+                "Cooldowns: pool={}, server-burst={}",
+                pool_cooldown.as_deref().unwrap_or("none"),
+                server_cooldown.as_deref().unwrap_or("none")
+            ));
+        }
+        if let Some(current_request_id) = &snapshot.current_request_id
+            && !current_request_id.is_empty()
+        {
+            out.info(format!("Last request trace: {current_request_id}"));
+        }
+    }
+    if let Some(current) = &runtime_current {
+        out.info(format!(
+            "Runtime in use: account {} ({})",
+            current.index + 1,
+            current.source.as_str()
+        ));
+    }
+    if let Some(pinned_account_index) = storage.pinned_account_index {
+        if pinned_account_index < 0 || pinned_account_index >= storage.accounts.len() as i64 {
+            out.info(format!(
+                "Pinned: invalid account index {pinned_account_index}; run codex-multi-auth unpin"
+            ));
+        } else {
+            out.info(format!("Pinned: account {} (set by switch)", pinned_account_index + 1));
+            if let Some(current) = &runtime_current
+                && current.index as i64 != pinned_account_index
+            {
+                out.info(format!(
+                    "  warning: runtime currently using account {} but pin requests account {}; the proxy will pick up the pin on the next request.",
+                    current.index + 1,
+                    pinned_account_index + 1
+                ));
+            }
+        }
+    }
+    out.info("");
+
+    for (i, account) in storage.accounts.iter().enumerate() {
+        let label = format_account_label(Some(account), i);
+        let markers = build_account_markers(
+            account,
+            i,
+            active_index,
+            runtime_current.as_ref(),
+            now,
+            quota_cache.as_ref(),
+            &storage.accounts,
+            &deps.format_rate_limit_entry,
+        );
+        let marker_label = if markers.is_empty() {
+            String::new()
+        } else {
+            format!(" [{}]", markers.join(", "))
+        };
+        let last_used = if account.last_used > 0 {
+            format!("used {} ago", format_wait_time(now - account.last_used))
+        } else {
+            "never used".to_string()
+        };
+        out.info(format!("{}. {label}{marker_label} {last_used}", i + 1));
+        if let Some(primary_reason) = forecast_results
+            .get(i)
+            .and_then(|result| result.reasons.first())
+        {
+            out.info(format!("   reason: {primary_reason}"));
+        }
+        // Surface every workspace a same-email account can rotate between, so
+        // personal Plus vs business/team stay visible at once (issue #491).
+        if account.workspaces.as_ref().map(Vec::len).unwrap_or(0) > 1 {
+            out.info("   workspaces:");
+            for workspace_line in format_workspace_lines(Some(account), "     ") {
+                out.info(workspace_line);
+            }
+        }
+    }
+
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::RateLimitStateV3;
+    use cma_storage::load::RestoreMetadata;
+
+    fn deps_with(
+        loaded: Option<LoadedAccountStorage>,
+        json: bool,
+        now: i64,
+    ) -> StatusCommandDeps {
+        StatusCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            get_storage_path: Box::new(|| "/tmp/accounts.json".to_string()),
+            load_accounts: Box::new(move || {
+                let loaded = loaded.clone();
+                Box::pin(async move { loaded })
+            }),
+            resolve_active_index: Box::new(|storage| {
+                cma_runtime::account_status::resolve_active_index(storage, ModelFamily::Codex)
+            }),
+            format_rate_limit_entry: Box::new(|account, now| {
+                cma_runtime::account_status::format_rate_limit_entry(
+                    account.rate_limit_reset_times.as_ref(),
+                    now,
+                    &format_wait_time,
+                    ModelFamily::Codex,
+                )
+            }),
+            load_runtime_observability_snapshot: None,
+            load_app_bind_status: None,
+            load_app_helper_status: None,
+            load_quota_cache: None,
+            inspect_storage_health: None,
+            get_now: Some(Box::new(move || now)),
+            json,
+        }
+    }
+
+    fn storage_with_accounts(count: usize) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        for i in 0..count {
+            let mut account = AccountMetadataV3::new(format!("token-{i}"), 1, 1_000);
+            account.email = Some(format!("user{i}@example.com"));
+            storage.accounts.push(account);
+        }
+        storage
+    }
+
+    #[tokio::test]
+    async fn empty_storage_json_emits_stable_key_set() {
+        let deps = deps_with(None, true, 5_000);
+        let mut out = CliOut::capture();
+        assert_eq!(run_status_command_with(&deps, &mut out).await, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let object = payload.as_object().expect("object");
+        let keys: Vec<&str> = object.keys().map(String::as_str).collect();
+        assert_eq!(
+            keys,
+            vec![
+                "storagePath",
+                "storageHealth",
+                "accountCount",
+                "activeIndex",
+                "pinnedAccountIndex",
+                "recommendedIndex",
+                "recommendationReason",
+                "runtimeInUseIndex",
+                "accounts",
+            ]
+        );
+        assert_eq!(payload["accountCount"], Value::from(0));
+        assert_eq!(payload["activeIndex"], Value::Null);
+        assert_eq!(payload["accounts"], Value::Array(vec![]));
+    }
+
+    #[tokio::test]
+    async fn empty_storage_intentional_reset_message() {
+        let loaded = LoadedAccountStorage {
+            storage: AccountStorageV3::empty(),
+            restore: Some(RestoreMetadata {
+                restore_eligible: false,
+                restore_reason: "intentional-reset",
+            }),
+        };
+        let deps = deps_with(Some(loaded), false, 5_000);
+        let mut out = CliOut::capture();
+        assert_eq!(run_status_command_with(&deps, &mut out).await, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "No accounts configured. Storage was intentionally reset.");
+        assert_eq!(lines[1], "Storage: /tmp/accounts.json");
+        assert_eq!(lines[2], "Storage health: intentional-reset");
+    }
+
+    #[tokio::test]
+    async fn populated_json_has_markers_and_recommendation() {
+        let mut storage = storage_with_accounts(2);
+        storage.accounts[1].enabled = Some(false);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", 999_999);
+        storage.accounts[0].rate_limit_reset_times = Some(times);
+        let loaded = LoadedAccountStorage { storage, restore: None };
+        let deps = deps_with(Some(loaded), true, 5_000);
+        let mut out = CliOut::capture();
+        assert_eq!(run_status_command_with(&deps, &mut out).await, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["accountCount"], Value::from(2));
+        assert_eq!(payload["activeIndex"], Value::from(0));
+        let accounts = payload["accounts"].as_array().expect("accounts");
+        // Account 0 is current + rate-limited; account 1 disabled.
+        let markers0: Vec<&str> = accounts[0]["markers"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|value| value.as_str().unwrap())
+            .collect();
+        assert_eq!(markers0, vec!["current", "rate-limited"]);
+        let markers1: Vec<&str> = accounts[1]["markers"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|value| value.as_str().unwrap())
+            .collect();
+        assert_eq!(markers1, vec!["disabled"]);
+        assert_eq!(accounts[0]["lastUsed"], Value::from(1_000));
+    }
+
+    #[tokio::test]
+    async fn text_mode_lists_accounts_with_used_ago() {
+        let storage = storage_with_accounts(1);
+        let loaded = LoadedAccountStorage { storage, restore: None };
+        let deps = deps_with(Some(loaded), false, 3_601_000);
+        let mut out = CliOut::capture();
+        assert_eq!(run_status_command_with(&deps, &mut out).await, 0);
+        let text = out.info_text();
+        assert!(text.starts_with("Accounts (1)\nStorage: /tmp/accounts.json"));
+        // formatWaitTime is minutes-based (`Xm Ys`, frozen): 3,600,000 ms
+        // renders as "60m 0s", never "1h".
+        assert!(text.contains("1. Account 1 (user0@example.com) [current] used 60m 0s ago"));
+    }
+
+    #[tokio::test]
+    async fn invalid_pin_prints_unpin_hint() {
+        let mut storage = storage_with_accounts(1);
+        storage.pinned_account_index = Some(9);
+        let loaded = LoadedAccountStorage { storage, restore: None };
+        let deps = deps_with(Some(loaded), false, 5_000);
+        let mut out = CliOut::capture();
+        assert_eq!(run_status_command_with(&deps, &mut out).await, 0);
+        assert!(out
+            .info_text()
+            .contains("Pinned: invalid account index 9; run codex-multi-auth unpin"));
+    }
+
+    #[test]
+    fn features_command_lists_all_54() {
+        let mut out = CliOut::capture();
+        assert_eq!(run_features_command(&mut out), 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Implemented features (54)");
+        assert_eq!(lines[1], "");
+        assert_eq!(lines[2], "1. Multi-account OAuth login dashboard");
+        assert_eq!(lines[55], "54. mcodex convenience launcher (monitor/tmux/forward)");
+    }
+
+    #[test]
+    fn runtime_last_account_label_email_guard() {
+        let mut snapshot = cma_runtime::observability::create_default_snapshot();
+        snapshot.last_account_label = Some("user@example.com".to_string());
+        snapshot.last_account_id = Some("acct_123".to_string());
+        snapshot.last_account_index = Some(1);
+        // Label containing '@' is suppressed in favor of the id form.
+        assert_eq!(
+            format_runtime_last_account(&snapshot).as_deref(),
+            Some("Account 2 (acct_123)")
+        );
+        snapshot.last_account_label = Some("Team account".to_string());
+        assert_eq!(
+            format_runtime_last_account(&snapshot).as_deref(),
+            Some("Team account")
+        );
+    }
+}
diff --git a/crates/manager/src/commands/switch.rs b/crates/manager/src/commands/switch.rs
new file mode 100644
index 000000000..d6ce7a6af
--- /dev/null
+++ b/crates/manager/src/commands/switch.rs
@@ -0,0 +1,285 @@
+//! Port of `lib/codex-manager/commands/switch.ts`.
+//!
+//! Behavior source: spec 08 §4.17. Digit-only index validation (`/^\d+$/`)
+//! is a deliberate fix — `parseInt` truncation of `"1.5"`/`"2abc"` must be
+//! rejected (spec 08 gotcha 13).
+
+use cma_accounts::manager_persistence::format_account_label;
+use cma_core::schemas::account_storage::{AccountStorageV3, PersistedSwitchReason};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_load_accounts, default_set_storage_path, BoxFuture, LoadAccountsFn, SetStoragePathFn,
+};
+
+/// Parameters of the injected `persistAndSyncSelectedAccount` call (the TS
+/// inline type in switch.ts; production wiring adapts the login-cluster
+/// implementation).
+pub struct PersistAndSyncSelectedAccountParams {
+    pub storage: AccountStorageV3,
+    pub target_index: usize,
+    /// 1-based parsed index (TS `parsed`).
+    pub parsed: i64,
+    pub switch_reason: PersistedSwitchReason,
+    pub initial_sync_id_token: Option<String>,
+    pub set_pin: bool,
+    pub clear_pin: bool,
+    pub bump_affinity_generation: bool,
+}
+
+/// `{ synced, wasDisabled }`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct PersistAndSyncSelectedAccountOutcome {
+    pub synced: bool,
+    pub was_disabled: bool,
+}
+
+/// Injected `persistAndSyncSelectedAccount`.
+pub type PersistAndSyncSelectedAccountFn = Box<
+    dyn Fn(PersistAndSyncSelectedAccountParams) -> BoxFuture<PersistAndSyncSelectedAccountOutcome>
+        + Send
+        + Sync,
+>;
+
+/// TS `SwitchCommandDeps` (log sinks live on [`CliOut`]).
+pub struct SwitchCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub persist_and_sync_selected_account: PersistAndSyncSelectedAccountFn,
+}
+
+impl SwitchCommandDeps {
+    /// Real storage wiring around an injected persist implementation.
+    pub fn new(persist_and_sync_selected_account: PersistAndSyncSelectedAccountFn) -> Self {
+        SwitchCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            load_accounts: default_load_accounts(),
+            persist_and_sync_selected_account,
+        }
+    }
+}
+
+/// Production entry: wires the login-cluster
+/// `persistAndSyncSelectedAccount` (spec 09 §1.9).
+pub async fn run_switch_command(args: &[String], out: &mut CliOut) -> i32 {
+    let deps = SwitchCommandDeps::new(Box::new(|params| {
+        Box::pin(async move {
+            let outcome = crate::login::persist_selected::persist_and_sync_selected_account(
+                crate::login::persist_selected::PersistSelectedAccountParams {
+                    storage: params.storage,
+                    target_index: params.target_index,
+                    parsed: params.parsed,
+                    switch_reason: params.switch_reason,
+                    initial_sync_id_token: params.initial_sync_id_token,
+                    preserve_active_index_by_family: false,
+                    set_pin: params.set_pin,
+                    clear_pin: params.clear_pin,
+                    bump_affinity_generation: params.bump_affinity_generation,
+                },
+            )
+            .await;
+            PersistAndSyncSelectedAccountOutcome {
+                synced: outcome.synced,
+                was_disabled: outcome.was_disabled,
+            }
+        })
+    }));
+    run_switch_command_with(args, &deps, out).await
+}
+
+/// TS `runSwitchCommand(args, deps)`.
+pub async fn run_switch_command_with(
+    args: &[String],
+    deps: &SwitchCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    (deps.set_storage_path)(None);
+    let Some(index_arg) = args.first() else {
+        out.error("Missing index. Usage: codex-multi-auth switch <index>");
+        return 1;
+    };
+
+    // Require a plain positive integer. parseInt would silently truncate
+    // "1.5" -> 1 (or "2abc" -> 2), selecting a real account from malformed
+    // input; reject anything that isn't all digits.
+    let trimmed = index_arg.trim();
+    if trimmed.is_empty() || !trimmed.chars().all(|c| c.is_ascii_digit()) {
+        out.error(format!("Invalid index: {index_arg}"));
+        return 1;
+    }
+    let Ok(parsed) = trimmed.parse::<i64>() else {
+        out.error(format!("Invalid index: {index_arg}"));
+        return 1;
+    };
+    if parsed < 1 {
+        out.error(format!("Invalid index: {index_arg}"));
+        return 1;
+    }
+
+    let target_index = (parsed - 1) as usize;
+    let Some(storage) = (deps.load_accounts)().await else {
+        out.error("No accounts configured.");
+        return 1;
+    };
+    if storage.accounts.is_empty() {
+        out.error("No accounts configured.");
+        return 1;
+    }
+
+    if target_index >= storage.accounts.len() {
+        out.error(format!(
+            "Index out of range. Valid range: 1-{}",
+            storage.accounts.len()
+        ));
+        return 1;
+    }
+
+    let Some(account) = storage.accounts.get(target_index).cloned() else {
+        out.error(format!("Account {parsed} not found."));
+        return 1;
+    };
+
+    let outcome = (deps.persist_and_sync_selected_account)(PersistAndSyncSelectedAccountParams {
+        storage,
+        target_index,
+        parsed,
+        switch_reason: PersistedSwitchReason::Manual,
+        initial_sync_id_token: None,
+        set_pin: true,
+        clear_pin: false,
+        bump_affinity_generation: true,
+    })
+    .await;
+
+    if !outcome.synced {
+        out.warn(format!(
+            "Switched account {parsed} locally, but Codex auth sync did not complete. Multi-auth routing will still use this account."
+        ));
+    }
+
+    out.info(format!(
+        "Switched to account {parsed}: {}{} (pinned for runtime routing)",
+        format_account_label(Some(&account), target_index),
+        if outcome.was_disabled { " (re-enabled)" } else { "" },
+    ));
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use std::sync::{Arc, Mutex};
+
+    #[allow(clippy::type_complexity)]
+    struct Harness {
+        deps: SwitchCommandDeps,
+        persist_calls: Arc<Mutex<Vec<(usize, i64, bool, bool)>>>,
+    }
+
+    fn harness(storage: Option<AccountStorageV3>, synced: bool, was_disabled: bool) -> Harness {
+        let persist_calls = Arc::new(Mutex::new(Vec::new()));
+        let persist_clone = Arc::clone(&persist_calls);
+        let deps = SwitchCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { storage })
+            }),
+            persist_and_sync_selected_account: Box::new(move |params| {
+                persist_clone.lock().unwrap().push((
+                    params.target_index,
+                    params.parsed,
+                    params.set_pin,
+                    params.bump_affinity_generation,
+                ));
+                Box::pin(async move {
+                    PersistAndSyncSelectedAccountOutcome { synced, was_disabled }
+                })
+            }),
+        };
+        Harness { deps, persist_calls }
+    }
+
+    fn storage_with(count: usize) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        for i in 0..count {
+            let mut account = AccountMetadataV3::new(format!("token-{i}"), 1, 1);
+            account.email = Some(format!("user{i}@example.com"));
+            storage.accounts.push(account);
+        }
+        storage
+    }
+
+    #[tokio::test]
+    async fn missing_index_errors() {
+        let h = harness(Some(storage_with(1)), true, false);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&[], &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "Missing index. Usage: codex-multi-auth switch <index>");
+    }
+
+    #[tokio::test]
+    async fn rejects_non_digit_indexes() {
+        for bad in ["1.5", "2abc", "-1", "abc"] {
+            let h = harness(Some(storage_with(3)), true, false);
+            let mut out = CliOut::capture();
+            let args = vec![bad.to_string()];
+            assert_eq!(run_switch_command_with(&args, &h.deps, &mut out).await, 1, "arg {bad:?}");
+            assert_eq!(out.error_text(), format!("Invalid index: {bad}"));
+            assert!(h.persist_calls.lock().unwrap().is_empty());
+        }
+    }
+
+    #[tokio::test]
+    async fn zero_is_invalid() {
+        let h = harness(Some(storage_with(3)), true, false);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&["0".to_string()], &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "Invalid index: 0");
+    }
+
+    #[tokio::test]
+    async fn no_accounts_errors() {
+        let h = harness(None, true, false);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&["1".to_string()], &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "No accounts configured.");
+    }
+
+    #[tokio::test]
+    async fn out_of_range_reports_valid_range() {
+        let h = harness(Some(storage_with(2)), true, false);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&["5".to_string()], &h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "Index out of range. Valid range: 1-2");
+    }
+
+    #[tokio::test]
+    async fn switches_and_pins_with_manual_reason() {
+        let h = harness(Some(storage_with(2)), true, false);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&["2".to_string()], &h.deps, &mut out).await, 0);
+        assert_eq!(h.persist_calls.lock().unwrap().as_slice(), [(1usize, 2i64, true, true)]);
+        assert_eq!(
+            out.info_text(),
+            "Switched to account 2: Account 2 (user1@example.com) (pinned for runtime routing)"
+        );
+        assert!(out.warn_text().is_empty());
+    }
+
+    #[tokio::test]
+    async fn unsynced_switch_warns_and_re_enabled_suffix() {
+        let h = harness(Some(storage_with(1)), false, true);
+        let mut out = CliOut::capture();
+        assert_eq!(run_switch_command_with(&["1".to_string()], &h.deps, &mut out).await, 0);
+        assert_eq!(
+            out.warn_text(),
+            "Switched account 1 locally, but Codex auth sync did not complete. Multi-auth routing will still use this account."
+        );
+        assert_eq!(
+            out.info_text(),
+            "Switched to account 1: Account 1 (user0@example.com) (re-enabled) (pinned for runtime routing)"
+        );
+    }
+}
diff --git a/crates/manager/src/commands/uninstall.rs b/crates/manager/src/commands/uninstall.rs
new file mode 100644
index 000000000..66c790681
--- /dev/null
+++ b/crates/manager/src/commands/uninstall.rs
@@ -0,0 +1,819 @@
+//! Port of `lib/codex-manager/commands/uninstall.ts`.
+//!
+//! `uninstall [--dry-run] [--json] [--clear-accounts]` — reverses all
+//! first-run setup changes: unbinds the Codex app, removes OS launchers,
+//! strips the plugin from Codex.json, and clears the plugin cache.
+//!
+//! CRITICAL contracts (spec 08 §4.18 / gotcha 19):
+//! - Codex.json is rewritten as `JSON.stringify(config, null, "\t") + "\n"`
+//!   — TAB indent + trailing LF, byte format matters;
+//! - the shared bun.lock is deleted ONLY when the plugin list is provably
+//!   empty (ENOENT ⇒ safe; parse error / missing `plugins` / non-empty list
+//!   ⇒ keep);
+//! - the default log sink is STDERR with the `codex-multi-auth: ` prefix;
+//! - `--clear-accounts` without a wired handler is a partial failure, never
+//!   a silent no-op;
+//! - JSON output is COMPACT; exit code is `partialFailure ? 1 : 0`.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{code_of, with_file_operation_retry};
+use cma_core::json_io::{stringify_compact, stringify_pretty_tab};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::BoxFuture;
+
+const PLUGIN_NAME: &str = "codex-multi-auth";
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+/// TS `resolveUninstallPaths(platform, env, home)` return shape.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct UninstallPaths {
+    pub config_path: PathBuf,
+    pub cache_node_modules: PathBuf,
+    pub cache_bun_lock: PathBuf,
+}
+
+/// TS `resolveUninstallPaths(platform, env, home)`.
+pub fn resolve_uninstall_paths(
+    platform: &str,
+    env: &HashMap<String, String>,
+    home: &Path,
+) -> UninstallPaths {
+    let is_windows = platform == "win32";
+    let app_data = env
+        .get("APPDATA")
+        .map(|value| value.trim().to_string())
+        .unwrap_or_default();
+    let local_app_data = env
+        .get("LOCALAPPDATA")
+        .or(env.get("APPDATA"))
+        .map(|value| value.trim().to_string())
+        .unwrap_or_default();
+    let config_base = if is_windows {
+        if app_data.is_empty() {
+            home.join("AppData").join("Roaming")
+        } else {
+            PathBuf::from(app_data)
+        }
+    } else {
+        home.join(".config")
+    };
+    let cache_base = if is_windows {
+        if local_app_data.is_empty() {
+            home.join("AppData").join("Local")
+        } else {
+            PathBuf::from(local_app_data)
+        }
+    } else {
+        home.join(".cache")
+    };
+    let config_dir = config_base.join("Codex");
+    let cache_dir = cache_base.join("Codex");
+    UninstallPaths {
+        config_path: config_dir.join("Codex.json"),
+        cache_node_modules: cache_dir.join("node_modules").join(PLUGIN_NAME),
+        cache_bun_lock: cache_dir.join("bun.lock"),
+    }
+}
+
+fn current_platform() -> &'static str {
+    if cfg!(windows) {
+        "win32"
+    } else if cfg!(target_os = "macos") {
+        "darwin"
+    } else {
+        "linux"
+    }
+}
+
+/// `os.homedir()` analogue via the env ladder (spec 02 §2.1 — env vars
+/// first; the `home` crate is not a cma-manager dependency).
+fn default_home_dir() -> PathBuf {
+    let non_blank = |key: &str| {
+        std::env::var(key)
+            .ok()
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    };
+    if cfg!(windows) {
+        if let Some(profile) = non_blank("USERPROFILE") {
+            return PathBuf::from(profile);
+        }
+        if let Some(home) = non_blank("HOME") {
+            return PathBuf::from(home);
+        }
+        if let (Some(drive), Some(path)) = (non_blank("HOMEDRIVE"), non_blank("HOMEPATH")) {
+            return PathBuf::from(format!("{drive}{path}"));
+        }
+    } else if let Some(home) = non_blank("HOME") {
+        return PathBuf::from(home);
+    }
+    PathBuf::new()
+}
+
+fn default_paths() -> UninstallPaths {
+    let env: HashMap<String, String> = std::env::vars().collect();
+    resolve_uninstall_paths(current_platform(), &env, &default_home_dir())
+}
+
+// ============================================================================
+// Plugin list filtering
+// ============================================================================
+
+/// JS truthiness over a JSON value (`list.filter(Boolean)`).
+fn is_js_truthy(value: &Value) -> bool {
+    match value {
+        Value::Null => false,
+        Value::Bool(flag) => *flag,
+        Value::Number(number) => number.as_f64().is_some_and(|n| n != 0.0 && !n.is_nan()),
+        Value::String(text) => !text.is_empty(),
+        Value::Array(_) | Value::Object(_) => true,
+    }
+}
+
+/// TS `removePluginFromList(list)` — pre-filter falsy entries (matching
+/// `scripts/install-codex-auth-utils.js`), then drop string entries equal to
+/// `codex-multi-auth` or starting with `codex-multi-auth@`; non-strings are
+/// kept.
+pub fn remove_plugin_from_list(list: &[Value]) -> Vec<Value> {
+    list.iter()
+        .filter(|entry| is_js_truthy(entry))
+        .filter(|entry| match entry.as_str() {
+            Some(text) => text != PLUGIN_NAME && !text.starts_with(&format!("{PLUGIN_NAME}@")),
+            None => true,
+        })
+        .cloned()
+        .collect()
+}
+
+// ============================================================================
+// Arg parsing
+// ============================================================================
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+struct UninstallCliOptions {
+    dry_run: bool,
+    json: bool,
+    clear_accounts: bool,
+}
+
+fn print_uninstall_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth uninstall [--dry-run] [--json] [--clear-accounts]",
+            "",
+            "Options:",
+            "  --dry-run          Show what would be removed without making changes",
+            "  --json             Print machine-readable JSON output",
+            "  --clear-accounts   Also remove stored account credentials (irreversible)",
+            "",
+            "Behavior:",
+            "  Reverses all first-run setup changes: unbinds Codex app, removes OS launchers,",
+            "  strips plugin from Codex.json, and clears the plugin cache.",
+            "",
+            "Recommended order (npm@7+ no longer fires preuninstall lifecycle scripts,",
+            "so cleanup must be initiated manually):",
+            "  1. codex-multi-auth uninstall          # remove residual artifacts",
+            "  2. npm uninstall -g codex-multi-auth   # remove the package itself",
+        ]
+        .join("\n"),
+    );
+}
+
+enum ParsedUninstallArgs {
+    Ok(UninstallCliOptions),
+    Help,
+    Error(String),
+}
+
+/// TS `parseUninstallArgs(args)`.
+fn parse_uninstall_args(args: &[String]) -> ParsedUninstallArgs {
+    let mut options = UninstallCliOptions::default();
+    for arg in args {
+        match arg.as_str() {
+            "--help" | "-h" => return ParsedUninstallArgs::Help,
+            "--dry-run" => options.dry_run = true,
+            "--json" | "-j" => options.json = true,
+            "--clear-accounts" => options.clear_accounts = true,
+            other => return ParsedUninstallArgs::Error(format!("Unknown option: {other}")),
+        }
+    }
+    ParsedUninstallArgs::Ok(options)
+}
+
+// ============================================================================
+// Deps
+// ============================================================================
+
+/// TS `UninstallCommandDeps`.
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct UninstallCommandDeps {
+    /// Extra log sink (TS `deps.log`); `None` = stderr with the
+    /// `codex-multi-auth: ` prefix via the command's [`CliOut`].
+    pub log: Option<Box<dyn Fn(&str) + Send + Sync>>,
+    /// `--clear-accounts` handler (wired to real storage clearing by
+    /// default — the dispatcher passes `clearAccounts`).
+    pub clear_accounts: Option<Box<dyn Fn() -> BoxFuture<Result<(), CodexError>> + Send + Sync>>,
+    pub unbind: Option<Box<dyn Fn() -> BoxFuture<Result<(), String>> + Send + Sync>>,
+    pub remove_launcher: Option<Box<dyn Fn() -> BoxFuture<Result<(), String>> + Send + Sync>>,
+    pub paths: Option<UninstallPaths>,
+}
+
+impl Default for UninstallCommandDeps {
+    fn default() -> Self {
+        UninstallCommandDeps {
+            log: None,
+            clear_accounts: Some(Box::new(|| {
+                Box::pin(async {
+                    cma_storage::clear::clear_accounts()
+                        .await
+                        .map_err(|error| CodexError::new(error.to_string()))
+                })
+            })),
+            unbind: None,
+            remove_launcher: None,
+            paths: None,
+        }
+    }
+}
+
+/// Node `rm(path, { recursive: true, force: true })` — removes a file or a
+/// directory tree; missing targets are fine.
+async fn rm_recursive_force(path: &Path) -> std::io::Result<()> {
+    match tokio::fs::metadata(path).await {
+        Ok(metadata) => {
+            if metadata.is_dir() {
+                tokio::fs::remove_dir_all(path).await
+            } else {
+                tokio::fs::remove_file(path).await
+            }
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+/// Node `rm(path, { force: true })` (non-recursive).
+async fn rm_force(path: &Path) -> std::io::Result<()> {
+    match tokio::fs::remove_file(path).await {
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        result => result,
+    }
+}
+
+// ============================================================================
+// runUninstallCommand
+// ============================================================================
+
+/// Production entry (dispatcher wiring — `clearAccounts` is wired).
+pub async fn run_uninstall_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_uninstall_command_with(args, &UninstallCommandDeps::default(), out).await
+}
+
+/// TS `runUninstallCommand(args, deps)`.
+pub async fn run_uninstall_command_with(
+    args: &[String],
+    deps: &UninstallCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    let options = match parse_uninstall_args(args) {
+        ParsedUninstallArgs::Ok(options) => options,
+        ParsedUninstallArgs::Help => {
+            print_uninstall_usage(out);
+            return 0;
+        }
+        ParsedUninstallArgs::Error(message) => {
+            out.error(format!("codex-multi-auth uninstall: {message}"));
+            out.error("Run \"codex-multi-auth uninstall --help\" for usage.");
+            return 1;
+        }
+    };
+
+    let dry_run = options.dry_run;
+    let json = options.json;
+    let clear_accounts_flag = options.clear_accounts;
+    let paths = deps.paths.clone().unwrap_or_else(default_paths);
+    let mut removed: Vec<&'static str> = Vec::new();
+    let mut warnings: Vec<String> = Vec::new();
+    let mut partial_failure = false;
+
+    // TS default sink = stderr with the "codex-multi-auth: " prefix.
+    macro_rules! log {
+        ($msg:expr) => {{
+            let message: String = $msg;
+            match &deps.log {
+                Some(log) => log(&message),
+                None => out.error(format!("codex-multi-auth: {message}")),
+            }
+        }};
+    }
+
+    // Surface a missing --clear-accounts handler immediately: silently
+    // no-oping would leave the user believing tokens were removed.
+    if clear_accounts_flag && deps.clear_accounts.is_none() {
+        let msg =
+            "--clear-accounts has no effect: no clearAccounts handler is wired in this build";
+        log!(format!("warning: {msg}"));
+        warnings.push(msg.to_string());
+        partial_failure = true;
+    }
+
+    // Unbind Codex app runtime rotation.
+    let unbind_result: Result<(), String> = if dry_run {
+        log!("[dry-run] Would unbind Codex app runtime rotation".to_string());
+        Ok(())
+    } else {
+        let result = match &deps.unbind {
+            Some(unbind) => unbind().await,
+            None => cma_runtime::app_bind::unbind_codex_app_runtime_rotation(
+                &cma_runtime::app_bind::AppBindOptions::default(),
+            )
+            .await
+            .map(|_| ()),
+        };
+        if result.is_ok() {
+            removed.push("app-bind");
+        }
+        result
+    };
+    if let Err(error) = unbind_result {
+        let msg = format!("app unbind skipped: {error}");
+        log!(msg.clone());
+        warnings.push(msg);
+        partial_failure = true;
+    }
+
+    // Remove OS-level launcher (loaded lazily in TS so dry-run needs no
+    // dist file; the Rust launcher is a library call).
+    let launcher_result: Result<(), String> = if dry_run {
+        log!("[dry-run] Would remove OS launcher".to_string());
+        Ok(())
+    } else {
+        let result = match &deps.remove_launcher {
+            Some(remove_launcher) => remove_launcher().await,
+            None => {
+                let sink: cma_runtime::app_launcher::SharedLogSink =
+                    Arc::new(|message: &str| eprintln!("codex-multi-auth: {message}"));
+                cma_runtime::app_launcher::install_codex_app_launcher(
+                    &cma_runtime::app_launcher::AppLauncherOptions {
+                        remove: true,
+                        log: Some(sink),
+                        ..Default::default()
+                    },
+                )
+                .await
+                .map(|_| ())
+            }
+        };
+        if result.is_ok() {
+            removed.push("launcher");
+        }
+        result
+    };
+    if let Err(error) = launcher_result {
+        let msg = format!("launcher removal skipped: {error}");
+        log!(msg.clone());
+        warnings.push(msg);
+        partial_failure = true;
+    }
+
+    // Remove the plugin entry from Codex.json and decide whether the SHARED
+    // bun.lock is safe to delete. Decision table:
+    //   - File ENOENT             → safe (nothing to protect)
+    //   - Parse error / read fail → NOT safe (unknown state, be conservative)
+    //   - File ok, no plugins[]   → NOT safe (we don't know what's installed)
+    //   - File ok, plugins[]=[]   → safe
+    //   - File ok, plugins[]≠[]   → NOT safe
+    let mut bun_lock_safe = false;
+    let config_step: Result<(), String> = async {
+        let read_result = with_file_operation_retry(|| async {
+            tokio::fs::read_to_string(&paths.config_path).await
+        })
+        .await;
+        let raw = match read_result {
+            Ok(raw) => raw,
+            Err(error) => {
+                if code_of(&error) == Some("ENOENT") {
+                    bun_lock_safe = true;
+                    if dry_run {
+                        log!(format!(
+                            "[dry-run] Would remove {PLUGIN_NAME} from {}",
+                            paths.config_path.display()
+                        ));
+                    }
+                    return Ok(());
+                }
+                return Err(error.to_string());
+            }
+        };
+        let mut config: Value =
+            serde_json::from_str(&raw).map_err(|error| error.to_string())?;
+        let plugins = config
+            .as_object()
+            .and_then(|object| object.get("plugins"))
+            .and_then(Value::as_array)
+            .cloned();
+        match plugins {
+            Some(plugins) => {
+                let next = remove_plugin_from_list(&plugins);
+                bun_lock_safe = next.is_empty();
+                if dry_run {
+                    log!(format!(
+                        "[dry-run] Would remove {PLUGIN_NAME} from {}",
+                        paths.config_path.display()
+                    ));
+                } else {
+                    if let Some(object) = config.as_object_mut() {
+                        object.insert("plugins".to_string(), Value::Array(next));
+                    }
+                    let contents = format!("{}\n", stringify_pretty_tab(&config));
+                    with_file_operation_retry(|| async {
+                        tokio::fs::write(&paths.config_path, contents.as_bytes()).await
+                    })
+                    .await
+                    .map_err(|error| error.to_string())?;
+                    removed.push("config-entry");
+                }
+            }
+            None => {
+                if dry_run {
+                    log!(format!(
+                        "[dry-run] Would remove {PLUGIN_NAME} from {}",
+                        paths.config_path.display()
+                    ));
+                }
+            }
+        }
+        Ok(())
+    }
+    .await;
+    if let Err(error) = config_step {
+        let msg = format!("config cleanup skipped: {error}");
+        log!(msg.clone());
+        warnings.push(msg);
+        partial_failure = true;
+    }
+
+    // Cache clear — bun.lock only when provably safe (shared across all
+    // Codex plugins).
+    let cache_step: Result<(), String> = async {
+        if dry_run {
+            log!(format!(
+                "[dry-run] Would remove {}",
+                paths.cache_node_modules.display()
+            ));
+            if bun_lock_safe {
+                log!(format!(
+                    "[dry-run] Would remove {}",
+                    paths.cache_bun_lock.display()
+                ));
+            } else {
+                log!(format!(
+                    "[dry-run] Would skip {} (other plugins still installed)",
+                    paths.cache_bun_lock.display()
+                ));
+            }
+            return Ok(());
+        }
+        with_file_operation_retry(|| async { rm_recursive_force(&paths.cache_node_modules).await })
+            .await
+            .map_err(|error| error.to_string())?;
+        if bun_lock_safe {
+            with_file_operation_retry(|| async { rm_force(&paths.cache_bun_lock).await })
+                .await
+                .map_err(|error| error.to_string())?;
+        }
+        removed.push("cache");
+        Ok(())
+    }
+    .await;
+    if let Err(error) = cache_step {
+        let msg = format!("cache clear skipped: {error}");
+        log!(msg.clone());
+        warnings.push(msg);
+        partial_failure = true;
+    }
+
+    // Optionally clear stored accounts.
+    if clear_accounts_flag && let Some(clear_accounts) = &deps.clear_accounts {
+        let clear_step: Result<(), String> = if dry_run {
+            log!("[dry-run] Would clear stored account credentials".to_string());
+            Ok(())
+        } else {
+            let result = clear_accounts()
+                .await
+                .map_err(|error| error.message().to_string());
+            if result.is_ok() {
+                removed.push("accounts");
+            }
+            result
+        };
+        if let Err(error) = clear_step {
+            let msg = format!("account clear skipped: {error}");
+            log!(msg.clone());
+            warnings.push(msg);
+            partial_failure = true;
+        }
+    }
+
+    if json {
+        let mut payload = Map::new();
+        payload.insert("dryRun".into(), Value::from(dry_run));
+        payload.insert(
+            "removed".into(),
+            Value::Array(removed.iter().map(|step| Value::from(*step)).collect()),
+        );
+        payload.insert(
+            "warnings".into(),
+            Value::Array(warnings.iter().cloned().map(Value::from).collect()),
+        );
+        payload.insert("ok".into(), Value::from(!partial_failure));
+        out.info(stringify_compact(&Value::Object(payload)));
+    } else if !dry_run {
+        let summary = if removed.is_empty() {
+            "nothing to remove".to_string()
+        } else {
+            removed.join(", ")
+        };
+        log!(format!("uninstall complete: {summary}"));
+        if !warnings.is_empty() {
+            log!(format!(
+                "warnings: {} step(s) skipped (see above)",
+                warnings.len()
+            ));
+        }
+    }
+
+    if partial_failure { 1 } else { 0 }
+}
+
+// ============================================================================
+// Tests — ported from test/uninstall-command.test.ts +
+// test/uninstall-ebusy-retry.test.ts (core decision table)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn env(pairs: &[(&str, &str)]) -> HashMap<String, String> {
+        pairs
+            .iter()
+            .map(|(key, value)| (key.to_string(), value.to_string()))
+            .collect()
+    }
+
+    fn noop_deps(paths: UninstallPaths) -> UninstallCommandDeps {
+        UninstallCommandDeps {
+            log: None,
+            clear_accounts: Some(Box::new(|| Box::pin(async { Ok(()) }))),
+            unbind: Some(Box::new(|| Box::pin(async { Ok(()) }))),
+            remove_launcher: Some(Box::new(|| Box::pin(async { Ok(()) }))),
+            paths: Some(paths),
+        }
+    }
+
+    fn temp_paths(dir: &Path) -> UninstallPaths {
+        UninstallPaths {
+            config_path: dir.join("Codex").join("Codex.json"),
+            cache_node_modules: dir.join("cache").join("node_modules").join(PLUGIN_NAME),
+            cache_bun_lock: dir.join("cache").join("bun.lock"),
+        }
+    }
+
+    #[test]
+    fn resolve_paths_win32_honors_appdata_with_fallbacks() {
+        let home = Path::new("C:/Users/dev");
+        let paths = resolve_uninstall_paths(
+            "win32",
+            &env(&[("APPDATA", "C:/Roaming"), ("LOCALAPPDATA", "C:/Local")]),
+            home,
+        );
+        assert_eq!(paths.config_path, PathBuf::from("C:/Roaming/Codex/Codex.json"));
+        assert_eq!(
+            paths.cache_node_modules,
+            PathBuf::from("C:/Local/Codex/node_modules/codex-multi-auth")
+        );
+        assert_eq!(paths.cache_bun_lock, PathBuf::from("C:/Local/Codex/bun.lock"));
+
+        // LOCALAPPDATA falls back to APPDATA; both fall back to home.
+        let fallback = resolve_uninstall_paths("win32", &env(&[("APPDATA", "C:/Roaming")]), home);
+        assert_eq!(fallback.cache_bun_lock, PathBuf::from("C:/Roaming/Codex/bun.lock"));
+        let bare = resolve_uninstall_paths("win32", &env(&[]), home);
+        assert_eq!(
+            bare.config_path,
+            home.join("AppData").join("Roaming").join("Codex").join("Codex.json")
+        );
+        assert_eq!(
+            bare.cache_bun_lock,
+            home.join("AppData").join("Local").join("Codex").join("bun.lock")
+        );
+    }
+
+    #[test]
+    fn resolve_paths_posix_uses_config_and_cache() {
+        let home = Path::new("/home/dev");
+        let paths = resolve_uninstall_paths("linux", &env(&[]), home);
+        assert_eq!(paths.config_path, PathBuf::from("/home/dev/.config/Codex/Codex.json"));
+        assert_eq!(paths.cache_bun_lock, PathBuf::from("/home/dev/.cache/Codex/bun.lock"));
+    }
+
+    #[test]
+    fn remove_plugin_from_list_filters_falsy_and_versioned_entries() {
+        let list = vec![
+            json!("codex-multi-auth"),
+            json!("codex-multi-auth@1.2.3"),
+            json!("other-plugin"),
+            json!(null),
+            json!(""),
+            json!(false),
+            json!(0),
+            json!(42),
+            json!({ "name": "keep-object" }),
+        ];
+        let next = remove_plugin_from_list(&list);
+        assert_eq!(
+            next,
+            vec![json!("other-plugin"), json!(42), json!({ "name": "keep-object" })]
+        );
+        // A different plugin sharing the prefix without `@` is kept.
+        let kept = remove_plugin_from_list(&[json!("codex-multi-auth-extras")]);
+        assert_eq!(kept, vec![json!("codex-multi-auth-extras")]);
+    }
+
+    #[tokio::test]
+    async fn unknown_option_prints_prefixed_error() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let deps = noop_deps(temp_paths(dir.path()));
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--bogus"]), &deps, &mut out).await;
+        assert_eq!(code, 1);
+        let errors = out.error_text();
+        assert!(errors.contains("codex-multi-auth uninstall: Unknown option: --bogus"));
+        assert!(errors.contains("Run \"codex-multi-auth uninstall --help\" for usage."));
+    }
+
+    #[tokio::test]
+    async fn dry_run_logs_previews_and_writes_nothing() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let paths = temp_paths(dir.path());
+        std::fs::create_dir_all(paths.config_path.parent().unwrap()).unwrap();
+        std::fs::write(
+            &paths.config_path,
+            "{\n\t\"plugins\": [\"codex-multi-auth\", \"other\"]\n}\n",
+        )
+        .unwrap();
+        let deps = noop_deps(paths.clone());
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--dry-run", "--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        // Compact JSON on stdout.
+        assert_eq!(
+            out.info_text(),
+            "{\"dryRun\":true,\"removed\":[],\"warnings\":[],\"ok\":true}"
+        );
+        // Non-empty remainder → bun.lock skip preview on stderr.
+        let errors = out.error_text();
+        assert!(errors.contains("[dry-run] Would unbind Codex app runtime rotation"));
+        assert!(errors.contains("(other plugins still installed)"));
+        // Nothing was modified.
+        let raw = std::fs::read_to_string(&paths.config_path).unwrap();
+        assert!(raw.contains("codex-multi-auth"));
+    }
+
+    #[tokio::test]
+    async fn rewrites_codex_json_with_tab_indent_and_trailing_newline() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let paths = temp_paths(dir.path());
+        std::fs::create_dir_all(paths.config_path.parent().unwrap()).unwrap();
+        std::fs::write(
+            &paths.config_path,
+            "{\"plugins\":[\"codex-multi-auth@2.7.1\",\"other\"],\"theme\":\"dark\"}",
+        )
+        .unwrap();
+        std::fs::create_dir_all(&paths.cache_node_modules).unwrap();
+        std::fs::write(&paths.cache_bun_lock, "lock").unwrap();
+        let deps = noop_deps(paths.clone());
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["ok"], Value::from(true));
+        assert_eq!(
+            payload["removed"],
+            json!(["app-bind", "launcher", "config-entry", "cache"])
+        );
+        // TAB-indented + trailing newline, unknown keys preserved in place.
+        let written = std::fs::read_to_string(&paths.config_path).unwrap();
+        assert_eq!(
+            written,
+            "{\n\t\"plugins\": [\n\t\t\"other\"\n\t],\n\t\"theme\": \"dark\"\n}\n"
+        );
+        // Remainder non-empty → shared bun.lock kept.
+        assert!(paths.cache_bun_lock.exists());
+        assert!(!paths.cache_node_modules.exists());
+    }
+
+    #[tokio::test]
+    async fn bun_lock_removed_only_when_plugin_list_provably_empty() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let paths = temp_paths(dir.path());
+        std::fs::create_dir_all(paths.config_path.parent().unwrap()).unwrap();
+        std::fs::write(&paths.config_path, "{\"plugins\":[\"codex-multi-auth\"]}").unwrap();
+        std::fs::create_dir_all(paths.cache_bun_lock.parent().unwrap()).unwrap();
+        std::fs::write(&paths.cache_bun_lock, "lock").unwrap();
+        let deps = noop_deps(paths.clone());
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        assert!(!paths.cache_bun_lock.exists());
+    }
+
+    #[tokio::test]
+    async fn enoent_config_is_safe_but_parse_error_is_conservative() {
+        // ENOENT → safe → bun.lock removed.
+        let dir = tempfile::tempdir().expect("tempdir");
+        let paths = temp_paths(dir.path());
+        std::fs::create_dir_all(paths.cache_bun_lock.parent().unwrap()).unwrap();
+        std::fs::write(&paths.cache_bun_lock, "lock").unwrap();
+        let deps = noop_deps(paths.clone());
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        assert!(!paths.cache_bun_lock.exists());
+
+        // Parse error → uncertain → bun.lock kept, warning + exit 1.
+        let dir = tempfile::tempdir().expect("tempdir");
+        let paths = temp_paths(dir.path());
+        std::fs::create_dir_all(paths.config_path.parent().unwrap()).unwrap();
+        std::fs::write(&paths.config_path, "{not json").unwrap();
+        std::fs::create_dir_all(paths.cache_bun_lock.parent().unwrap()).unwrap();
+        std::fs::write(&paths.cache_bun_lock, "lock").unwrap();
+        let deps = noop_deps(paths.clone());
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 1);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["ok"], Value::from(false));
+        assert!(
+            payload["warnings"][0]
+                .as_str()
+                .unwrap()
+                .starts_with("config cleanup skipped: ")
+        );
+        assert!(paths.cache_bun_lock.exists());
+    }
+
+    #[tokio::test]
+    async fn clear_accounts_without_handler_is_partial_failure() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let mut deps = noop_deps(temp_paths(dir.path()));
+        deps.clear_accounts = None;
+        let mut out = CliOut::capture();
+        let code =
+            run_uninstall_command_with(&args(&["--clear-accounts", "--json"]), &deps, &mut out)
+                .await;
+        assert_eq!(code, 1);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["ok"], Value::from(false));
+        assert_eq!(
+            payload["warnings"][0],
+            Value::from(
+                "--clear-accounts has no effect: no clearAccounts handler is wired in this build"
+            )
+        );
+        assert!(
+            out.error_text().contains(
+                "codex-multi-auth: warning: --clear-accounts has no effect"
+            )
+        );
+    }
+
+    #[tokio::test]
+    async fn text_mode_logs_summary_through_stderr_sink() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let deps = noop_deps(temp_paths(dir.path()));
+        let mut out = CliOut::capture();
+        let code = run_uninstall_command_with(&[], &deps, &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.info_text(), "");
+        assert!(
+            out.error_text()
+                .contains("codex-multi-auth: uninstall complete: app-bind, launcher, cache")
+        );
+    }
+}
diff --git a/crates/manager/src/commands/unpin.rs b/crates/manager/src/commands/unpin.rs
new file mode 100644
index 000000000..c2f6b7b72
--- /dev/null
+++ b/crates/manager/src/commands/unpin.rs
@@ -0,0 +1,168 @@
+//! Port of `lib/codex-manager/commands/unpin.ts`.
+//!
+//! Behavior source: spec 08 §4.19. Affinity-generation lost-update guard:
+//! re-read the on-disk `affinityGeneration` just before saving and take
+//! `max(memory, disk) + 1` — extra bumps are harmless, missed bumps let the
+//! proxy cling to the wrong account.
+
+use cma_storage::load::read_affinity_generation_from_disk;
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_get_storage_path, default_load_accounts, default_save_accounts,
+    default_set_storage_path, save_accounts_with_retry_boxed, GetStoragePathFn, LoadAccountsFn,
+    SaveAccountsFn, SetStoragePathFn,
+};
+
+/// TS `UnpinCommandDeps` (log sinks live on [`CliOut`]).
+pub struct UnpinCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub save_accounts: SaveAccountsFn,
+    /// Optional (TS `getStoragePath?`): absent → disk generation read as 0.
+    pub get_storage_path: Option<GetStoragePathFn>,
+}
+
+impl Default for UnpinCommandDeps {
+    fn default() -> Self {
+        UnpinCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            load_accounts: default_load_accounts(),
+            save_accounts: default_save_accounts(),
+            get_storage_path: Some(default_get_storage_path()),
+        }
+    }
+}
+
+/// Production entry (dispatcher: rest args are ignored for this command).
+pub async fn run_unpin_command(out: &mut CliOut) -> i32 {
+    run_unpin_command_with(&UnpinCommandDeps::default(), out).await
+}
+
+/// TS `runUnpinCommand(deps)`.
+pub async fn run_unpin_command_with(deps: &UnpinCommandDeps, out: &mut CliOut) -> i32 {
+    (deps.set_storage_path)(None);
+
+    let Some(mut storage) = (deps.load_accounts)().await else {
+        out.error("No accounts configured.");
+        return 1;
+    };
+    if storage.accounts.is_empty() {
+        out.error("No accounts configured.");
+        return 1;
+    }
+
+    let Some(previous_pin) = storage.pinned_account_index else {
+        out.info("No pin to clear.");
+        return 0;
+    };
+
+    storage.pinned_account_index = None;
+    // Re-read the on-disk affinityGeneration just before saving so concurrent
+    // CLI processes don't lose increments via lost-update on the load+mutate
+    // pair (see module docs).
+    let disk_generation = deps
+        .get_storage_path
+        .as_ref()
+        .map(|get_storage_path| read_affinity_generation_from_disk(get_storage_path()))
+        .unwrap_or(0);
+    let in_memory_generation = storage.affinity_generation.unwrap_or(0);
+    storage.affinity_generation = Some(in_memory_generation.max(disk_generation) + 1);
+    if let Err(error) = save_accounts_with_retry_boxed(&storage, &deps.save_accounts).await {
+        // TS lets the save rejection propagate out of the command; surface it
+        // as an error exit instead of a crash.
+        out.error(error.message());
+        return 1;
+    }
+
+    out.info(format!(
+        "Cleared manual pin (was account {}). Runtime routing will resume hybrid rotation.",
+        previous_pin + 1
+    ));
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+    use std::sync::{Arc, Mutex};
+
+    fn storage_with_pin(pin: Option<i64>, generation: Option<i64>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("token", 1, 1));
+        storage.pinned_account_index = pin;
+        storage.affinity_generation = generation;
+        storage
+    }
+
+    struct Harness {
+        deps: UnpinCommandDeps,
+        saved: Arc<Mutex<Option<AccountStorageV3>>>,
+    }
+
+    fn harness(storage: Option<AccountStorageV3>) -> Harness {
+        let saved: Arc<Mutex<Option<AccountStorageV3>>> = Arc::new(Mutex::new(None));
+        let saved_clone = Arc::clone(&saved);
+        let deps = UnpinCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { storage })
+            }),
+            save_accounts: Box::new(move |storage| {
+                let saved = Arc::clone(&saved_clone);
+                Box::pin(async move {
+                    *saved.lock().unwrap() = Some(storage);
+                    Ok(())
+                })
+            }),
+            get_storage_path: None,
+        };
+        Harness { deps, saved }
+    }
+
+    #[tokio::test]
+    async fn no_accounts_errors() {
+        let h = harness(None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_unpin_command_with(&h.deps, &mut out).await, 1);
+        assert_eq!(out.error_text(), "No accounts configured.");
+    }
+
+    #[tokio::test]
+    async fn no_pin_is_a_clean_no_op() {
+        let h = harness(Some(storage_with_pin(None, None)));
+        let mut out = CliOut::capture();
+        assert_eq!(run_unpin_command_with(&h.deps, &mut out).await, 0);
+        assert_eq!(out.info_text(), "No pin to clear.");
+        assert!(h.saved.lock().unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn clears_pin_and_bumps_generation() {
+        let h = harness(Some(storage_with_pin(Some(0), Some(4))));
+        let mut out = CliOut::capture();
+        assert_eq!(run_unpin_command_with(&h.deps, &mut out).await, 0);
+        let saved = h.saved.lock().unwrap().clone().expect("saved");
+        assert_eq!(saved.pinned_account_index, None);
+        assert_eq!(saved.affinity_generation, Some(5));
+        assert_eq!(
+            out.info_text(),
+            "Cleared manual pin (was account 1). Runtime routing will resume hybrid rotation."
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_generation_starts_from_zero() {
+        let h = harness(Some(storage_with_pin(Some(2), None)));
+        let mut out = CliOut::capture();
+        assert_eq!(run_unpin_command_with(&h.deps, &mut out).await, 0);
+        let saved = h.saved.lock().unwrap().clone().expect("saved");
+        assert_eq!(saved.affinity_generation, Some(1));
+        assert_eq!(
+            out.info_text(),
+            "Cleared manual pin (was account 3). Runtime routing will resume hybrid rotation."
+        );
+    }
+}
diff --git a/crates/manager/src/commands/usage.rs b/crates/manager/src/commands/usage.rs
new file mode 100644
index 000000000..a17253cc2
--- /dev/null
+++ b/crates/manager/src/commands/usage.rs
@@ -0,0 +1,788 @@
+//! Port of `lib/codex-manager/commands/usage.ts`.
+//!
+//! Behavior source: spec 08 §4.20 (+ gotcha 15): `--json` includes raw rows
+//! (read + summarize rows); text/CSV summarize the ledger directly.
+//! `--json`+`--csv` conflict. CSV with zero buckets emits one row from
+//! totals. The `--out` confirmation line prints only in text mode.
+
+use std::path::{Path, PathBuf};
+
+use cma_core::json_io::stringify_compact;
+use cma_core::utils::now_ms;
+use cma_usage::ledger::{
+    read_usage_ledger_rows, rotate_usage_ledger, summarize_usage_ledger, summarize_usage_rows,
+    RotateUsageLedgerOptions,
+};
+use cma_usage::types::{
+    UsageLedgerQuery, UsageLedgerRow, UsageSummary, UsageSummaryBucket, UsageSummaryGroupBy,
+    UsageSummaryQuery,
+};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{default_write_file, BoxFuture};
+
+#[derive(Clone, Debug, PartialEq)]
+struct UsageCliOptions {
+    since: Option<f64>,
+    by: UsageSummaryGroupBy,
+    json: bool,
+    csv: bool,
+    out_path: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+struct UsageRotateOptions {
+    json: bool,
+    if_larger_than_bytes: Option<u64>,
+}
+
+enum Parsed<T> {
+    Ok(T),
+    Err(String),
+}
+
+/// TS `UsageCommandDeps` (log sinks live on [`CliOut`]).
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct UsageCommandDeps {
+    pub summarize_usage:
+        Box<dyn Fn(UsageSummaryQuery) -> BoxFuture<std::io::Result<UsageSummary>> + Send + Sync>,
+    pub read_rows:
+        Box<dyn Fn(UsageLedgerQuery) -> BoxFuture<std::io::Result<Vec<UsageLedgerRow>>> + Send + Sync>,
+    pub summarize_rows:
+        Box<dyn Fn(&[UsageLedgerRow], &UsageSummaryQuery) -> UsageSummary + Send + Sync>,
+    pub rotate_ledger:
+        Box<dyn Fn(RotateUsageLedgerOptions) -> BoxFuture<std::io::Result<Option<PathBuf>>> + Send + Sync>,
+    pub get_cwd: Box<dyn Fn() -> PathBuf + Send + Sync>,
+    pub write_file:
+        Box<dyn Fn(PathBuf, String) -> BoxFuture<std::io::Result<()>> + Send + Sync>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+}
+
+impl Default for UsageCommandDeps {
+    fn default() -> Self {
+        UsageCommandDeps {
+            summarize_usage: Box::new(|query| {
+                Box::pin(async move { summarize_usage_ledger(&query).await })
+            }),
+            read_rows: Box::new(|query| {
+                Box::pin(async move { read_usage_ledger_rows(&query).await })
+            }),
+            summarize_rows: Box::new(summarize_usage_rows),
+            rotate_ledger: Box::new(|options| {
+                Box::pin(async move { rotate_usage_ledger(&options).await })
+            }),
+            get_cwd: Box::new(|| std::env::current_dir().unwrap_or_default()),
+            write_file: Box::new(|path, contents| {
+                Box::pin(async move { default_write_file(&path, &contents).await })
+            }),
+            get_now: None,
+        }
+    }
+}
+
+fn parse_positive_integer(raw_value: &str) -> Option<u64> {
+    let trimmed = raw_value.trim();
+    if trimmed.is_empty() || !trimmed.chars().all(|c| c.is_ascii_digit()) {
+        return None;
+    }
+    let parsed: u64 = trimmed.parse().ok()?;
+    // JS Number.isSafeInteger + parsed > 0.
+    if parsed == 0 || parsed > 9_007_199_254_740_991 {
+        return None;
+    }
+    Some(parsed)
+}
+
+/// TS `parseSinceValue(value)` — relative durations (`24h`, `7d`, `2w`,
+/// `30m`), all-digit epoch ms, else an ISO date string. The TS ledger runs
+/// strings through `Date.parse`; the Rust ledger query is epoch-ms only, so
+/// the date-string subset (`YYYY-MM-DD` and RFC3339-style timestamps) is
+/// parsed here. Unparseable strings behave like `Date.parse` returning NaN:
+/// no `since` filter is applied.
+fn parse_since_value(value: &str, now: i64) -> Option<f64> {
+    let trimmed = value.trim();
+    if let Some(ms) = parse_relative_duration(trimmed, now) {
+        return Some(ms);
+    }
+    if !trimmed.is_empty() && trimmed.chars().all(|c| c.is_ascii_digit()) {
+        return trimmed.parse::<f64>().ok();
+    }
+    parse_date_string_ms(trimmed)
+}
+
+fn parse_relative_duration(trimmed: &str, now: i64) -> Option<f64> {
+    if trimmed.len() < 2 {
+        return None;
+    }
+    let (digits, unit) = trimmed.split_at(trimmed.len() - 1);
+    if digits.is_empty() || !digits.chars().all(|c| c.is_ascii_digit()) {
+        return None;
+    }
+    let amount: f64 = digits.parse().ok()?;
+    let multiplier = match unit.chars().next()?.to_ascii_lowercase() {
+        'm' => 60_000.0,
+        'h' => 3_600_000.0,
+        'd' => 86_400_000.0,
+        'w' => 604_800_000.0,
+        _ => return None,
+    };
+    Some(now as f64 - amount * multiplier)
+}
+
+/// Howard Hinnant's days-from-civil (same algorithm the usage ledger uses
+/// for day bucketing) — parse `YYYY-MM-DD[THH:MM[:SS[.sss]]][Z]` as UTC.
+fn parse_date_string_ms(value: &str) -> Option<f64> {
+    let bytes = value.as_bytes();
+    if bytes.len() < 10 || bytes[4] != b'-' || bytes[7] != b'-' {
+        return None;
+    }
+    let year: i64 = value.get(0..4)?.parse().ok()?;
+    let month: i64 = value.get(5..7)?.parse().ok()?;
+    let day: i64 = value.get(8..10)?.parse().ok()?;
+    if !(1..=12).contains(&month) || !(1..=31).contains(&day) {
+        return None;
+    }
+    let (mut hour, mut minute, mut second, mut millis) = (0i64, 0i64, 0i64, 0i64);
+    if bytes.len() > 10 {
+        if bytes[10] != b'T' && bytes[10] != b' ' {
+            return None;
+        }
+        let time = value.get(11..)?.trim_end_matches('Z');
+        let mut parts = time.splitn(3, ':');
+        hour = parts.next()?.parse().ok()?;
+        minute = parts.next().unwrap_or("0").parse().ok()?;
+        if let Some(rest) = parts.next() {
+            let mut sec_parts = rest.splitn(2, '.');
+            second = sec_parts.next()?.parse().ok()?;
+            if let Some(frac) = sec_parts.next() {
+                let frac3: String = frac.chars().take(3).collect();
+                millis = format!("{frac3:0<3}").parse().ok()?;
+            }
+        }
+    }
+    let y = if month <= 2 { year - 1 } else { year };
+    let era = if y >= 0 { y } else { y - 399 } / 400;
+    let yoe = y - era * 400;
+    let mp = (month + 9) % 12;
+    let doy = (153 * mp + 2) / 5 + day - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    let days = era * 146_097 + doe - 719_468;
+    Some(((days * 86_400 + hour * 3_600 + minute * 60 + second) * 1_000 + millis) as f64)
+}
+
+fn print_usage_command_help(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth usage [--since <time|duration>] [--by <model|account|project|outcome|day>] [--json|--csv] [--out <path>]",
+            "  codex-multi-auth usage rotate [--if-larger-than-bytes <bytes>] [--json]",
+            "",
+            "Options:",
+            "  --since            Filter rows by timestamp, ISO date, or relative duration like 24h, 7d, 2w",
+            "  --by               Group summary output (default: model)",
+            "  --json, -j         Print machine-readable JSON output",
+            "  --csv              Print or write CSV bucket output",
+            "  --out              Write output to a file path",
+            "",
+            "Notes:",
+            "  - Usage rows contain local metadata only, not prompts, tokens, auth headers, raw emails, or raw account ids.",
+        ]
+        .join("\n"),
+    );
+}
+
+fn parse_usage_args(args: &[String], now: i64) -> Parsed<UsageCliOptions> {
+    let mut options = UsageCliOptions {
+        since: None,
+        by: UsageSummaryGroupBy::Model,
+        json: false,
+        csv: false,
+        out_path: None,
+    };
+
+    let mut i = 0;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--json" || arg == "-j" {
+            options.json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--csv" {
+            options.csv = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--since" {
+            let Some(value) = args.get(i + 1) else {
+                return Parsed::Err("Missing value for --since".to_string());
+            };
+            options.since = parse_since_value(value, now);
+            i += 2;
+            continue;
+        }
+        if let Some(value) = arg.strip_prefix("--since=") {
+            let value = value.trim();
+            if value.is_empty() {
+                return Parsed::Err("Missing value for --since".to_string());
+            }
+            options.since = parse_since_value(value, now);
+            i += 1;
+            continue;
+        }
+        if arg == "--by" {
+            let Some(value) = args.get(i + 1) else {
+                return Parsed::Err("Missing value for --by".to_string());
+            };
+            let Some(by) = UsageSummaryGroupBy::parse(value) else {
+                return Parsed::Err(format!("Unknown --by value: {value}"));
+            };
+            options.by = by;
+            i += 2;
+            continue;
+        }
+        if let Some(value) = arg.strip_prefix("--by=") {
+            let value = value.trim();
+            let Some(by) = UsageSummaryGroupBy::parse(value) else {
+                return Parsed::Err(format!("Unknown --by value: {value}"));
+            };
+            options.by = by;
+            i += 1;
+            continue;
+        }
+        if arg == "--out" {
+            let Some(value) = args.get(i + 1) else {
+                return Parsed::Err("Missing value for --out".to_string());
+            };
+            options.out_path = Some(value.clone());
+            i += 2;
+            continue;
+        }
+        if let Some(value) = arg.strip_prefix("--out=") {
+            let value = value.trim();
+            if value.is_empty() {
+                return Parsed::Err("Missing value for --out".to_string());
+            }
+            options.out_path = Some(value.to_string());
+            i += 1;
+            continue;
+        }
+        return Parsed::Err(format!("Unknown usage option: {arg}"));
+    }
+
+    if options.json && options.csv {
+        return Parsed::Err("Cannot combine --json and --csv".to_string());
+    }
+    Parsed::Ok(options)
+}
+
+fn parse_rotate_args(args: &[String]) -> Parsed<UsageRotateOptions> {
+    let mut options = UsageRotateOptions {
+        json: false,
+        if_larger_than_bytes: None,
+    };
+    let mut i = 0;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--json" || arg == "-j" {
+            options.json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--if-larger-than-bytes" {
+            let Some(value) = args.get(i + 1) else {
+                return Parsed::Err("Missing value for --if-larger-than-bytes".to_string());
+            };
+            let Some(parsed) = parse_positive_integer(value) else {
+                return Parsed::Err(
+                    "--if-larger-than-bytes must be a positive integer".to_string(),
+                );
+            };
+            options.if_larger_than_bytes = Some(parsed);
+            i += 2;
+            continue;
+        }
+        if let Some(value) = arg.strip_prefix("--if-larger-than-bytes=") {
+            let Some(parsed) = parse_positive_integer(value) else {
+                return Parsed::Err(
+                    "--if-larger-than-bytes must be a positive integer".to_string(),
+                );
+            };
+            options.if_larger_than_bytes = Some(parsed);
+            i += 1;
+            continue;
+        }
+        return Parsed::Err(format!("Unknown usage rotate option: {arg}"));
+    }
+    Parsed::Ok(options)
+}
+
+fn format_currency(value: f64) -> String {
+    format!("${value:.6}")
+}
+
+fn format_text_summary(summary: &UsageSummary) -> String {
+    let mut lines = vec![
+        format!("Usage summary by {}", summary.by.as_str()),
+        format!(
+            "Requests: {} ({} success, {} failed, {} blocked, {} cancelled)",
+            summary.totals.requests,
+            summary.totals.successes,
+            summary.totals.failures,
+            summary.totals.blocked,
+            summary.totals.cancelled
+        ),
+        format!(
+            "Tokens: {} total ({} input, {} output, {} cached, {} reasoning)",
+            summary.totals.total_tokens,
+            summary.totals.input_tokens,
+            summary.totals.output_tokens,
+            summary.totals.cached_input_tokens,
+            summary.totals.reasoning_tokens
+        ),
+        format!("Estimated cost: {}", format_currency(summary.totals.cost_usd)),
+    ];
+    if summary.buckets.is_empty() {
+        lines.push("No usage rows found.".to_string());
+        return lines.join("\n");
+    }
+    lines.push(String::new());
+    for bucket in &summary.buckets {
+        lines.push(format!(
+            "{}: {} request(s), {} token(s), {}",
+            bucket.key,
+            bucket.requests,
+            bucket.total_tokens,
+            format_currency(bucket.cost_usd)
+        ));
+    }
+    lines.join("\n")
+}
+
+fn csv_escape(text: &str) -> String {
+    if text.contains('"') || text.contains(',') || text.contains('\r') || text.contains('\n') {
+        format!("\"{}\"", text.replace('"', "\"\""))
+    } else {
+        text.to_string()
+    }
+}
+
+fn bucket_to_csv_row(bucket: &UsageSummaryBucket) -> String {
+    [
+        bucket.key.clone(),
+        bucket.requests.to_string(),
+        bucket.successes.to_string(),
+        bucket.failures.to_string(),
+        bucket.blocked.to_string(),
+        bucket.cancelled.to_string(),
+        bucket.input_tokens.to_string(),
+        bucket.output_tokens.to_string(),
+        bucket.cached_input_tokens.to_string(),
+        bucket.reasoning_tokens.to_string(),
+        bucket.total_tokens.to_string(),
+        format!("{:.8}", bucket.cost_usd),
+    ]
+    .iter()
+    .map(|value| csv_escape(value))
+    .collect::<Vec<_>>()
+    .join(",")
+}
+
+fn format_csv_summary(summary: &UsageSummary) -> String {
+    let mut lines = vec![
+        "key,requests,successes,failures,blocked,cancelled,inputTokens,outputTokens,cachedInputTokens,reasoningTokens,totalTokens,costUsd"
+            .to_string(),
+    ];
+    lines.extend(summary.buckets.iter().map(bucket_to_csv_row));
+    if summary.buckets.is_empty() {
+        lines.push(bucket_to_csv_row(&summary.totals));
+    }
+    lines.join("\n")
+}
+
+fn rows_to_json_payload(summary: &UsageSummary, rows: &[UsageLedgerRow]) -> String {
+    let mut payload = Map::new();
+    payload.insert("command".into(), Value::from("usage"));
+    payload.insert(
+        "summary".into(),
+        serde_json::to_value(summary).unwrap_or(Value::Null),
+    );
+    payload.insert(
+        "rows".into(),
+        serde_json::to_value(rows).unwrap_or(Value::Array(Vec::new())),
+    );
+    cma_core::json_io::stringify_pretty2(&Value::Object(payload))
+}
+
+/// Production entry.
+pub async fn run_usage_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_usage_command_with(args, &UsageCommandDeps::default(), out).await
+}
+
+/// TS `runUsageCommand(args, deps)`.
+pub async fn run_usage_command_with(
+    args: &[String],
+    deps: &UsageCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_usage_command_help(out);
+        return 0;
+    }
+
+    if args.first().map(String::as_str) == Some("rotate") {
+        let parsed = match parse_rotate_args(&args[1..]) {
+            Parsed::Ok(options) => options,
+            Parsed::Err(message) => {
+                out.error(message);
+                return 1;
+            }
+        };
+        let rotated_path = match (deps.rotate_ledger)(RotateUsageLedgerOptions {
+            if_larger_than_bytes: parsed.if_larger_than_bytes,
+            ..Default::default()
+        })
+        .await
+        {
+            Ok(path) => path,
+            Err(error) => {
+                out.error(format!("Failed to rotate usage ledger: {error}"));
+                return 1;
+            }
+        };
+        if parsed.json {
+            let mut payload = Map::new();
+            payload.insert("command".into(), Value::from("usage rotate"));
+            payload.insert("rotated".into(), Value::from(rotated_path.is_some()));
+            payload.insert(
+                "path".into(),
+                rotated_path
+                    .as_ref()
+                    .map(|path| Value::from(path.to_string_lossy().into_owned()))
+                    .unwrap_or(Value::Null),
+            );
+            out.info(stringify_compact(&Value::Object(payload)));
+        } else {
+            out.info(match &rotated_path {
+                Some(path) => format!("Usage ledger rotated: {}", path.display()),
+                None => "Usage ledger rotation skipped.".to_string(),
+            });
+        }
+        return 0;
+    }
+
+    let now = deps.get_now.as_ref().map(|f| f()).unwrap_or_else(now_ms);
+    let options = match parse_usage_args(args, now) {
+        Parsed::Ok(options) => options,
+        Parsed::Err(message) => {
+            out.error(message);
+            print_usage_command_help(out);
+            return 1;
+        }
+    };
+    let summary_query = UsageSummaryQuery {
+        since: options.since,
+        until: None,
+        include_archives: false,
+        by: Some(options.by),
+    };
+    let mut rows: Vec<UsageLedgerRow> = Vec::new();
+    let summary = if options.json {
+        let read = (deps.read_rows)(summary_query.ledger_query()).await;
+        match read {
+            Ok(read_rows) => {
+                rows = read_rows;
+                (deps.summarize_rows)(&rows, &summary_query)
+            }
+            Err(error) => {
+                out.error(format!("Failed to read usage ledger: {error}"));
+                return 1;
+            }
+        }
+    } else {
+        match (deps.summarize_usage)(summary_query).await {
+            Ok(summary) => summary,
+            Err(error) => {
+                out.error(format!("Failed to read usage ledger: {error}"));
+                return 1;
+            }
+        }
+    };
+    let rendered = if options.json {
+        rows_to_json_payload(&summary, &rows)
+    } else if options.csv {
+        format_csv_summary(&summary)
+    } else {
+        format_text_summary(&summary)
+    };
+
+    if let Some(out_path) = &options.out_path {
+        let output_path = resolve_from_cwd(&(deps.get_cwd)(), out_path);
+        if let Err(error) = (deps.write_file)(output_path.clone(), format!("{rendered}\n")).await {
+            out.error(format!("Failed to write usage report: {error}"));
+            return 1;
+        }
+        if !options.json && !options.csv {
+            out.info(format!("Usage report written: {}", output_path.display()));
+        }
+        return 0;
+    }
+
+    out.info(rendered);
+    0
+}
+
+/// Node `path.resolve(cwd, value)`.
+pub(crate) fn resolve_from_cwd(cwd: &Path, value: &str) -> PathBuf {
+    let candidate = Path::new(value);
+    if candidate.is_absolute() {
+        candidate.to_path_buf()
+    } else {
+        cwd.join(candidate)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Arc, Mutex};
+
+    fn empty_bucket(key: &str) -> UsageSummaryBucket {
+        UsageSummaryBucket {
+            key: key.to_string(),
+            requests: 0,
+            successes: 0,
+            failures: 0,
+            blocked: 0,
+            cancelled: 0,
+            input_tokens: 0,
+            output_tokens: 0,
+            cached_input_tokens: 0,
+            reasoning_tokens: 0,
+            total_tokens: 0,
+            cost_usd: 0.0,
+        }
+    }
+
+    fn summary_with(buckets: Vec<UsageSummaryBucket>) -> UsageSummary {
+        let mut totals = empty_bucket("total");
+        totals.requests = 3;
+        totals.successes = 2;
+        totals.failures = 1;
+        totals.input_tokens = 100;
+        totals.output_tokens = 50;
+        totals.total_tokens = 150;
+        totals.cost_usd = 0.5;
+        UsageSummary {
+            since: None,
+            until: None,
+            by: UsageSummaryGroupBy::Model,
+            totals,
+            buckets,
+        }
+    }
+
+    struct Harness {
+        deps: UsageCommandDeps,
+        written: Arc<Mutex<Option<(PathBuf, String)>>>,
+    }
+
+    fn harness(summary: UsageSummary, rotate_result: Option<PathBuf>) -> Harness {
+        let written: Arc<Mutex<Option<(PathBuf, String)>>> = Arc::new(Mutex::new(None));
+        let written_clone = Arc::clone(&written);
+        let summary_for_rows = summary.clone();
+        let deps = UsageCommandDeps {
+            summarize_usage: Box::new(move |query| {
+                let mut summary = summary.clone();
+                summary.by = query.by.unwrap_or_default();
+                summary.since = query.since;
+                Box::pin(async move { Ok(summary) })
+            }),
+            read_rows: Box::new(|_query| Box::pin(async { Ok(Vec::new()) })),
+            summarize_rows: Box::new(move |_rows, query| {
+                let mut summary = summary_for_rows.clone();
+                summary.by = query.by.unwrap_or_default();
+                summary
+            }),
+            rotate_ledger: Box::new(move |_options| {
+                let rotate_result = rotate_result.clone();
+                Box::pin(async move { Ok(rotate_result) })
+            }),
+            get_cwd: Box::new(|| PathBuf::from("/work")),
+            write_file: Box::new(move |path, contents| {
+                let written = Arc::clone(&written_clone);
+                Box::pin(async move {
+                    *written.lock().unwrap() = Some((path, contents));
+                    Ok(())
+                })
+            }),
+            get_now: Some(Box::new(|| 1_000_000)),
+        };
+        Harness { deps, written }
+    }
+
+    fn args(values: &[&str]) -> Vec<String> {
+        values.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn since_parsing_relative_epoch_and_iso() {
+        assert_eq!(parse_since_value("24h", 100_000_000), Some(100_000_000.0 - 86_400_000.0));
+        assert_eq!(parse_since_value("30m", 10_000_000), Some(10_000_000.0 - 1_800_000.0));
+        assert_eq!(parse_since_value("2w", 2_000_000_000), Some(2_000_000_000.0 - 1_209_600_000.0));
+        assert_eq!(parse_since_value("12345", 0), Some(12345.0));
+        // 1970-01-02 UTC midnight.
+        assert_eq!(parse_since_value("1970-01-02", 0), Some(86_400_000.0));
+        // Unparseable → no filter (Date.parse NaN).
+        assert_eq!(parse_since_value("not-a-date", 0), None);
+    }
+
+    #[tokio::test]
+    async fn json_and_csv_conflict() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_usage_command_with(&args(&["--json", "--csv"]), &h.deps, &mut out).await,
+            1
+        );
+        assert!(out.error_text().starts_with("Cannot combine --json and --csv"));
+    }
+
+    #[tokio::test]
+    async fn unknown_by_value_rejected() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_usage_command_with(&args(&["--by", "bogus"]), &h.deps, &mut out).await,
+            1
+        );
+        assert!(out.error_text().starts_with("Unknown --by value: bogus"));
+    }
+
+    #[tokio::test]
+    async fn text_summary_shape() {
+        let mut bucket = empty_bucket("gpt-5.5");
+        bucket.requests = 2;
+        bucket.total_tokens = 120;
+        bucket.cost_usd = 0.25;
+        let h = harness(summary_with(vec![bucket]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_usage_command_with(&[], &h.deps, &mut out).await, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Usage summary by model");
+        assert_eq!(lines[1], "Requests: 3 (2 success, 1 failed, 0 blocked, 0 cancelled)");
+        assert_eq!(lines[2], "Tokens: 150 total (100 input, 50 output, 0 cached, 0 reasoning)");
+        assert_eq!(lines[3], "Estimated cost: $0.500000");
+        assert_eq!(lines[4], "");
+        assert_eq!(lines[5], "gpt-5.5: 2 request(s), 120 token(s), $0.250000");
+    }
+
+    #[tokio::test]
+    async fn csv_zero_buckets_emits_totals_row() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_usage_command_with(&args(&["--csv"]), &h.deps, &mut out).await, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(
+            lines[0],
+            "key,requests,successes,failures,blocked,cancelled,inputTokens,outputTokens,cachedInputTokens,reasoningTokens,totalTokens,costUsd"
+        );
+        assert_eq!(lines[1], "total,3,2,1,0,0,100,50,0,0,150,0.50000000");
+        assert_eq!(lines.len(), 2);
+    }
+
+    #[test]
+    fn csv_escapes_quotes_and_commas() {
+        assert_eq!(csv_escape("plain"), "plain");
+        assert_eq!(csv_escape("a,b"), "\"a,b\"");
+        assert_eq!(csv_escape("say \"hi\""), "\"say \"\"hi\"\"\"");
+    }
+
+    #[tokio::test]
+    async fn json_mode_includes_rows() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_usage_command_with(&args(&["--json"]), &h.deps, &mut out).await, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["command"], Value::from("usage"));
+        assert!(payload["summary"].is_object());
+        assert!(payload["rows"].is_array());
+    }
+
+    #[tokio::test]
+    async fn out_writes_file_and_confirms_in_text_mode_only() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_usage_command_with(&args(&["--out", "report.txt"]), &h.deps, &mut out).await,
+            0
+        );
+        let (path, contents) = h.written.lock().unwrap().clone().expect("written");
+        assert!(contents.ends_with('\n'));
+        assert!(path.ends_with("report.txt"));
+        assert!(out.info_text().starts_with("Usage report written: "));
+
+        // CSV mode: no confirmation line.
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_usage_command_with(&args(&["--csv", "--out", "report.csv"]), &h.deps, &mut out)
+                .await,
+            0
+        );
+        assert!(out.info_text().is_empty());
+    }
+
+    #[tokio::test]
+    async fn rotate_json_is_compact() {
+        let h = harness(summary_with(vec![]), Some(PathBuf::from("/ledger/usage-ledger.1.jsonl")));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_usage_command_with(&args(&["rotate", "--json"]), &h.deps, &mut out).await,
+            0
+        );
+        let text = out.info_text();
+        assert!(!text.contains('\n'));
+        let payload: Value = serde_json::from_str(&text).expect("json");
+        assert_eq!(payload["command"], Value::from("usage rotate"));
+        assert_eq!(payload["rotated"], Value::from(true));
+    }
+
+    #[tokio::test]
+    async fn rotate_skipped_message() {
+        let h = harness(summary_with(vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_usage_command_with(&args(&["rotate"]), &h.deps, &mut out).await, 0);
+        assert_eq!(out.info_text(), "Usage ledger rotation skipped.");
+    }
+
+    #[tokio::test]
+    async fn rotate_rejects_non_positive_threshold() {
+        let h = harness(summary_with(vec![]), None);
+        for bad in ["0", "abc", "1.5"] {
+            let mut out = CliOut::capture();
+            assert_eq!(
+                run_usage_command_with(
+                    &args(&["rotate", "--if-larger-than-bytes", bad]),
+                    &h.deps,
+                    &mut out
+                )
+                .await,
+                1,
+                "value {bad:?}"
+            );
+            assert_eq!(out.error_text(), "--if-larger-than-bytes must be a positive integer");
+        }
+    }
+}
diff --git a/crates/manager/src/commands/verify.rs b/crates/manager/src/commands/verify.rs
new file mode 100644
index 000000000..65cf379c6
--- /dev/null
+++ b/crates/manager/src/commands/verify.rs
@@ -0,0 +1,792 @@
+//! Port of `lib/codex-manager/commands/verify.ts`.
+//!
+//! Behavior source: spec 08 §4.21 (+ gotcha 20): the sandbox escape probe
+//! must reject with a message matching `/access denied/i`; a rejection with a
+//! different message is a FAILURE. Escape candidates must be verified outside
+//! home/tmp/projectRoot; when impossible, the test records ok+skipped.
+
+use std::path::{Path, PathBuf};
+
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{default_set_storage_path, BoxFuture, SetStoragePathFn};
+
+/// TS `VerifyCliOptions`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct VerifyCliOptions {
+    pub json: bool,
+    pub paths: bool,
+    pub flagged: bool,
+    pub all: bool,
+}
+
+/// One `Path chain` step.
+#[derive(Clone, Debug, PartialEq)]
+pub struct VerifyPathStep {
+    pub name: String,
+    pub input: Option<String>,
+    pub output: Option<String>,
+    pub ok: bool,
+    pub error: Option<String>,
+}
+
+/// One sandbox test result.
+#[derive(Clone, Debug, PartialEq)]
+pub struct VerifySandboxResult {
+    pub name: String,
+    pub input: String,
+    pub rejected: bool,
+    pub ok: bool,
+    pub error: Option<String>,
+}
+
+/// TS `VerifyPathsReport`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct VerifyPathsReport {
+    pub ok: bool,
+    pub steps: Vec<VerifyPathStep>,
+    pub sandbox_tests: Vec<VerifySandboxResult>,
+}
+
+/// TS `VerifyPathsDeps`.
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct VerifyPathsDeps {
+    pub get_cwd: Box<dyn Fn() -> PathBuf + Send + Sync>,
+    pub find_project_root: Box<dyn Fn(&Path) -> Option<PathBuf> + Send + Sync>,
+    pub resolve_project_storage_identity_root: Box<dyn Fn(&Path) -> PathBuf + Send + Sync>,
+    pub get_project_storage_key: Box<dyn Fn(&Path) -> String + Send + Sync>,
+    pub get_project_config_dir: Box<dyn Fn(&Path) -> PathBuf + Send + Sync>,
+    pub get_project_global_config_dir: Box<dyn Fn(&Path) -> PathBuf + Send + Sync>,
+    pub resolve_path: Box<dyn Fn(&str) -> Result<PathBuf, String> + Send + Sync>,
+    /// `os.homedir()` / `os.tmpdir()` seams for the sandbox candidates.
+    pub homedir: Box<dyn Fn() -> PathBuf + Send + Sync>,
+    pub tmpdir: Box<dyn Fn() -> PathBuf + Send + Sync>,
+}
+
+impl Default for VerifyPathsDeps {
+    fn default() -> Self {
+        VerifyPathsDeps {
+            get_cwd: Box::new(|| std::env::current_dir().unwrap_or_default()),
+            find_project_root: Box::new(cma_storage::paths::find_project_root),
+            resolve_project_storage_identity_root: Box::new(
+                cma_storage::paths::resolve_project_storage_identity_root,
+            ),
+            get_project_storage_key: Box::new(cma_storage::paths::get_project_storage_key),
+            get_project_config_dir: Box::new(cma_storage::paths::get_project_config_dir),
+            get_project_global_config_dir: Box::new(
+                cma_storage::paths::get_project_global_config_dir,
+            ),
+            resolve_path: Box::new(|input| {
+                cma_storage::paths::resolve_path(input).map_err(|error| error.0)
+            }),
+            homedir: Box::new(default_homedir),
+            tmpdir: Box::new(std::env::temp_dir),
+        }
+    }
+}
+
+fn default_homedir() -> PathBuf {
+    #[cfg(windows)]
+    {
+        if let Ok(profile) = std::env::var("USERPROFILE")
+            && !profile.trim().is_empty()
+        {
+            return PathBuf::from(profile);
+        }
+        if let Ok(home) = std::env::var("HOME")
+            && !home.trim().is_empty()
+        {
+            return PathBuf::from(home);
+        }
+        if let (Ok(drive), Ok(path)) = (std::env::var("HOMEDRIVE"), std::env::var("HOMEPATH"))
+            && !drive.trim().is_empty()
+            && !path.trim().is_empty()
+        {
+            return PathBuf::from(format!("{drive}{path}"));
+        }
+    }
+    #[cfg(not(windows))]
+    {
+        if let Ok(home) = std::env::var("HOME")
+            && !home.trim().is_empty()
+        {
+            return PathBuf::from(home);
+        }
+    }
+    // `os.homedir()` env ladder exhausted (spec 02 §2.1 resolves env vars
+    // first; the `home` crate is not a cma-manager dependency).
+    PathBuf::new()
+}
+
+/// TS `VerifyCommandDeps` (log sinks live on [`CliOut`]).
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct VerifyCommandDeps {
+    pub verify_paths_deps: VerifyPathsDeps,
+    pub run_verify_flagged: Option<Box<dyn Fn(Vec<String>) -> BoxFuture<i32> + Send + Sync>>,
+    pub set_storage_path: Option<SetStoragePathFn>,
+}
+
+impl Default for VerifyCommandDeps {
+    fn default() -> Self {
+        VerifyCommandDeps {
+            verify_paths_deps: VerifyPathsDeps::default(),
+            run_verify_flagged: Some(Box::new(|args| {
+                Box::pin(async move {
+                    let mut inner_out = CliOut::stdio();
+                    crate::repair::verify_flagged::run_verify_flagged(&args, &mut inner_out).await
+                })
+            })),
+            set_storage_path: Some(default_set_storage_path()),
+        }
+    }
+}
+
+/// TS `parseVerifyArgs(args)`.
+pub fn parse_verify_args(args: &[String]) -> Result<VerifyCliOptions, String> {
+    let mut options = VerifyCliOptions::default();
+    let mut paths_explicit = false;
+    let mut flagged_explicit = false;
+    for arg in args {
+        match arg.as_str() {
+            "--json" | "-j" => options.json = true,
+            "--paths" => {
+                options.paths = true;
+                paths_explicit = true;
+            }
+            "--flagged" => {
+                options.flagged = true;
+                flagged_explicit = true;
+            }
+            "--all" => {
+                options.paths = true;
+                options.flagged = true;
+                options.all = true;
+            }
+            // Passed through to verify-flagged when --flagged or --all is
+            // used.
+            "--dry-run" | "-n" | "--no-restore" => {}
+            other => return Err(format!("Unknown option: {other}")),
+        }
+    }
+    if paths_explicit && flagged_explicit && !options.all {
+        return Err(
+            "--paths and --flagged cannot be combined; use --all to run both, or pick one"
+                .to_string(),
+        );
+    }
+    Ok(options)
+}
+
+/// TS `printVerifyUsage()`.
+pub fn print_verify_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth verify --paths [--json]",
+            "  codex-multi-auth verify --flagged [--json] [--dry-run] [--no-restore]",
+            "",
+            "Options:",
+            "  --paths           Self-test storage path resolution chain and resolvePath sandbox",
+            "  --flagged         Verify previously-flagged accounts (delegates to verify-flagged)",
+            "  --json, -j        Print machine-readable JSON output",
+            "",
+            "Notes:",
+            "  - `codex-multi-auth verify-flagged` remains available as a back-compat alias.",
+            "  - `--paths` and `--flagged` cannot be combined; use `verify-flagged` when you only need flagged checks.",
+        ]
+        .join("\n"),
+    );
+}
+
+fn normalize_for_compare(path: &Path) -> String {
+    let absolute = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        std::env::current_dir().unwrap_or_default().join(path)
+    };
+    let text = absolute.to_string_lossy().into_owned();
+    if cfg!(windows) {
+        text.to_lowercase()
+    } else {
+        text
+    }
+}
+
+fn is_within_base(base_dir: &Path, target_path: &str) -> bool {
+    let base = normalize_for_compare(base_dir);
+    let target = normalize_for_compare(Path::new(target_path));
+    if target == base {
+        return true;
+    }
+    let with_sep = if base.ends_with(std::path::MAIN_SEPARATOR) || base.ends_with('/') {
+        base
+    } else {
+        format!("{base}{}", std::path::MAIN_SEPARATOR)
+    };
+    target.starts_with(&with_sep)
+}
+
+/// TS `pickEscapeProbePath(projectRoot)` — an absolute path guaranteed to be
+/// outside home, tmp, and the project root; `None` when no safe candidate is
+/// available (callers treat that as "skip the escape probe").
+fn pick_escape_probe_path(deps: &VerifyPathsDeps, project_root: &Path) -> Option<String> {
+    let tag = format!("codex_multi_auth_sandbox_escape_probe_{}", std::process::id());
+    let candidates: Vec<String> = if cfg!(windows) {
+        vec![
+            format!("Z:\\__{tag}__"),
+            format!("Y:\\__{tag}__"),
+            format!("\\\\?\\UNC\\server-that-does-not-exist\\share\\{tag}"),
+        ]
+    } else {
+        vec![
+            format!("/__{tag}__"),
+            format!("/var/__{tag}__"),
+            format!("/opt/__{tag}__"),
+        ]
+    };
+
+    let home = (deps.homedir)();
+    let tmp = (deps.tmpdir)();
+    candidates.into_iter().find(|candidate| {
+        !is_within_base(&home, candidate)
+            && !is_within_base(&tmp, candidate)
+            && !is_within_base(project_root, candidate)
+    })
+}
+
+fn run_sandbox_tests(deps: &VerifyPathsDeps) -> Vec<VerifySandboxResult> {
+    let mut results = Vec::new();
+
+    let inside_home = (deps.homedir)()
+        .join(".codex")
+        .join("multi-auth-verify-probe");
+    let inside_home_text = inside_home.to_string_lossy().into_owned();
+    match (deps.resolve_path)(&inside_home_text) {
+        Ok(resolved) => results.push(VerifySandboxResult {
+            name: "sandbox-accept-home".to_string(),
+            input: inside_home_text,
+            rejected: false,
+            ok: !resolved.as_os_str().is_empty(),
+            error: None,
+        }),
+        Err(error) => results.push(VerifySandboxResult {
+            name: "sandbox-accept-home".to_string(),
+            input: inside_home_text,
+            rejected: true,
+            ok: false,
+            error: Some(error),
+        }),
+    }
+
+    let inside_tmp = (deps.tmpdir)().join("codex-multi-auth-verify-probe.tmp");
+    let inside_tmp_text = inside_tmp.to_string_lossy().into_owned();
+    match (deps.resolve_path)(&inside_tmp_text) {
+        Ok(resolved) => results.push(VerifySandboxResult {
+            name: "sandbox-accept-tmp".to_string(),
+            input: inside_tmp_text,
+            rejected: false,
+            ok: !resolved.as_os_str().is_empty(),
+            error: None,
+        }),
+        Err(error) => results.push(VerifySandboxResult {
+            name: "sandbox-accept-tmp".to_string(),
+            input: inside_tmp_text,
+            rejected: true,
+            ok: false,
+            error: Some(error),
+        }),
+    }
+
+    let project_root = (deps.get_cwd)();
+    let Some(escape_attempt) = pick_escape_probe_path(deps, &project_root) else {
+        results.push(VerifySandboxResult {
+            name: "sandbox-reject-escape".to_string(),
+            input: String::new(),
+            rejected: false,
+            ok: true,
+            error: Some(
+                "skipped: no candidate outside home/tmp/project could be constructed".to_string(),
+            ),
+        });
+        return results;
+    };
+
+    match (deps.resolve_path)(&escape_attempt) {
+        Ok(_) => results.push(VerifySandboxResult {
+            name: "sandbox-reject-escape".to_string(),
+            input: escape_attempt,
+            rejected: false,
+            ok: false,
+            error: Some("resolvePath accepted a sandbox-escape candidate".to_string()),
+        }),
+        Err(message) => {
+            let looks_like_sandbox_rejection = message.to_lowercase().contains("access denied");
+            results.push(VerifySandboxResult {
+                name: "sandbox-reject-escape".to_string(),
+                input: escape_attempt,
+                rejected: true,
+                ok: looks_like_sandbox_rejection,
+                error: if looks_like_sandbox_rejection {
+                    None
+                } else {
+                    Some(message)
+                },
+            });
+        }
+    }
+
+    results
+}
+
+/// TS `runVerifyPathsCheck(deps)`.
+pub fn run_verify_paths_check(deps: &VerifyPathsDeps) -> VerifyPathsReport {
+    let mut steps: Vec<VerifyPathStep> = Vec::new();
+
+    let cwd = (deps.get_cwd)();
+    steps.push(VerifyPathStep {
+        name: "process.cwd".to_string(),
+        input: None,
+        output: Some(cwd.to_string_lossy().into_owned()),
+        ok: true,
+        error: None,
+    });
+
+    let mut project_root: Option<PathBuf> = None;
+    match (deps.find_project_root)(&cwd) {
+        Some(result) => {
+            project_root = Some(result.clone());
+            steps.push(VerifyPathStep {
+                name: "findProjectRoot".to_string(),
+                input: Some(cwd.to_string_lossy().into_owned()),
+                output: Some(result.to_string_lossy().into_owned()),
+                ok: true,
+                error: None,
+            });
+        }
+        None => {
+            steps.push(VerifyPathStep {
+                name: "findProjectRoot".to_string(),
+                input: Some(cwd.to_string_lossy().into_owned()),
+                output: None,
+                ok: false,
+                error: Some("no project root detected from cwd".to_string()),
+            });
+        }
+    }
+
+    let mut identity_root: Option<PathBuf> = None;
+    if let Some(project_root) = &project_root {
+        let output = (deps.resolve_project_storage_identity_root)(project_root);
+        identity_root = Some(output.clone());
+        steps.push(VerifyPathStep {
+            name: "resolveProjectStorageIdentityRoot".to_string(),
+            input: Some(project_root.to_string_lossy().into_owned()),
+            output: Some(output.to_string_lossy().into_owned()),
+            ok: true,
+            error: None,
+        });
+    }
+
+    let key_input = identity_root.clone().or(project_root.clone());
+    let mut storage_key: Option<String> = None;
+    if let Some(key_input) = &key_input {
+        let output = (deps.get_project_storage_key)(key_input);
+        storage_key = Some(output.clone());
+        steps.push(VerifyPathStep {
+            name: "getProjectStorageKey".to_string(),
+            input: Some(key_input.to_string_lossy().into_owned()),
+            output: Some(output),
+            ok: true,
+            error: None,
+        });
+        steps.push(VerifyPathStep {
+            name: "getProjectConfigDir".to_string(),
+            input: Some(key_input.to_string_lossy().into_owned()),
+            output: Some(
+                (deps.get_project_config_dir)(key_input)
+                    .to_string_lossy()
+                    .into_owned(),
+            ),
+            ok: true,
+            error: None,
+        });
+        steps.push(VerifyPathStep {
+            name: "getProjectGlobalConfigDir".to_string(),
+            input: Some(key_input.to_string_lossy().into_owned()),
+            output: Some(
+                (deps.get_project_global_config_dir)(key_input)
+                    .to_string_lossy()
+                    .into_owned(),
+            ),
+            ok: true,
+            error: None,
+        });
+    }
+
+    let sandbox_tests = run_sandbox_tests(deps);
+    let ok = steps.iter().all(|step| step.ok)
+        && sandbox_tests.iter().all(|test| test.ok)
+        && storage_key.as_deref().is_some_and(|key| !key.is_empty());
+
+    VerifyPathsReport {
+        ok,
+        steps,
+        sandbox_tests,
+    }
+}
+
+fn step_to_value(step: &VerifyPathStep) -> Value {
+    let mut row = Map::new();
+    row.insert("name".into(), Value::from(step.name.clone()));
+    if let Some(input) = &step.input {
+        row.insert("input".into(), Value::from(input.clone()));
+    }
+    if let Some(output) = &step.output {
+        row.insert("output".into(), Value::from(output.clone()));
+    }
+    row.insert("ok".into(), Value::from(step.ok));
+    if let Some(error) = &step.error {
+        row.insert("error".into(), Value::from(error.clone()));
+    }
+    Value::Object(row)
+}
+
+fn sandbox_to_value(test: &VerifySandboxResult) -> Value {
+    let mut row = Map::new();
+    row.insert("name".into(), Value::from(test.name.clone()));
+    row.insert("input".into(), Value::from(test.input.clone()));
+    row.insert("rejected".into(), Value::from(test.rejected));
+    row.insert("ok".into(), Value::from(test.ok));
+    if let Some(error) = &test.error {
+        row.insert("error".into(), Value::from(error.clone()));
+    }
+    Value::Object(row)
+}
+
+fn paths_report_to_value(report: &VerifyPathsReport) -> Value {
+    let mut payload = Map::new();
+    payload.insert("command".into(), Value::from("verify"));
+    payload.insert("mode".into(), Value::from("paths"));
+    payload.insert("ok".into(), Value::from(report.ok));
+    payload.insert(
+        "steps".into(),
+        Value::Array(report.steps.iter().map(step_to_value).collect()),
+    );
+    payload.insert(
+        "sandboxTests".into(),
+        Value::Array(report.sandbox_tests.iter().map(sandbox_to_value).collect()),
+    );
+    Value::Object(payload)
+}
+
+/// Production entry.
+pub async fn run_verify_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_verify_command_with(args, &VerifyCommandDeps::default(), out).await
+}
+
+/// TS `runVerifyCommand(args, deps)`.
+pub async fn run_verify_command_with(
+    args: &[String],
+    deps: &VerifyCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_verify_usage(out);
+        return 0;
+    }
+
+    let options = match parse_verify_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_verify_usage(out);
+            return 1;
+        }
+    };
+
+    if !options.paths && !options.flagged {
+        out.error(
+            "verify requires a mode: --paths (path chain self-test), --flagged (verify flagged accounts), or --all",
+        );
+        print_verify_usage(out);
+        return 1;
+    }
+
+    let mut paths_report: Option<VerifyPathsReport> = None;
+    if options.paths {
+        // Reset storage-path state so the sandbox probe and path-chain steps
+        // run against a clean baseline, matching the other command handlers.
+        if let Some(set_storage_path) = &deps.set_storage_path {
+            set_storage_path(None);
+        }
+        paths_report = Some(run_verify_paths_check(&deps.verify_paths_deps));
+    }
+
+    let mut flagged_exit_code: Option<i32> = None;
+    if options.flagged {
+        let Some(run_verify_flagged) = &deps.run_verify_flagged else {
+            out.error("verify --flagged delegation is not available");
+            return 1;
+        };
+        let passthrough: Vec<String> = args
+            .iter()
+            .filter(|arg| *arg != "--flagged" && *arg != "--paths" && *arg != "--all")
+            .cloned()
+            .collect();
+        flagged_exit_code = Some(run_verify_flagged(passthrough).await);
+    }
+
+    let paths_ok = paths_report.as_ref().map(|report| report.ok).unwrap_or(true);
+    let flagged_ok = flagged_exit_code.is_none_or(|code| code == 0);
+    let overall_ok = paths_ok && flagged_ok;
+
+    if options.json {
+        let mut payload = Map::new();
+        payload.insert("command".into(), Value::from("verify"));
+        payload.insert(
+            "mode".into(),
+            Value::from(if options.all {
+                "all"
+            } else if options.paths {
+                "paths"
+            } else {
+                "flagged"
+            }),
+        );
+        payload.insert("ok".into(), Value::from(overall_ok));
+        if let Some(report) = &paths_report {
+            payload.insert("paths".into(), paths_report_to_value(report));
+        }
+        if let Some(code) = flagged_exit_code {
+            payload.insert("flaggedExitCode".into(), Value::from(code));
+        }
+        out.info(cma_core::json_io::stringify_pretty2(&Value::Object(payload)));
+        return if overall_ok { 0 } else { 1 };
+    }
+
+    let Some(report) = &paths_report else {
+        return if overall_ok { 0 } else { 1 };
+    };
+
+    out.info(format!(
+        "verify --paths: {}",
+        if report.ok { "OK" } else { "FAIL" }
+    ));
+    out.info("");
+    out.info("Path chain:");
+    for step in &report.steps {
+        let marker = if step.ok { "✓" } else { "✗" };
+        let details = if step.ok {
+            format!(" → {}", step.output.as_deref().unwrap_or(""))
+        } else {
+            format!(" error: {}", step.error.as_deref().unwrap_or("unknown"))
+        };
+        let input = step
+            .input
+            .as_ref()
+            .map(|input| format!(" (in: {input})"))
+            .unwrap_or_default();
+        out.info(format!("  {marker} {}{input}{details}", step.name));
+    }
+    out.info("");
+    out.info("Sandbox tests:");
+    for test in &report.sandbox_tests {
+        let marker = if test.ok { "✓" } else { "✗" };
+        let rejected_label = if test.rejected { "rejected" } else { "accepted" };
+        out.info(format!(
+            "  {marker} {} ({rejected_label}): {}",
+            test.name,
+            test.error.as_deref().unwrap_or("ok")
+        ));
+    }
+
+    if overall_ok { 0 } else { 1 }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(values: &[&str]) -> Vec<String> {
+        values.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn fake_paths_deps(reject_message: &'static str) -> VerifyPathsDeps {
+        VerifyPathsDeps {
+            get_cwd: Box::new(|| PathBuf::from("/repo/project")),
+            find_project_root: Box::new(|_| Some(PathBuf::from("/repo/project"))),
+            resolve_project_storage_identity_root: Box::new(|root| root.to_path_buf()),
+            get_project_storage_key: Box::new(|_| "project-abc123456789".to_string()),
+            get_project_config_dir: Box::new(|root| root.join(".codex")),
+            get_project_global_config_dir: Box::new(|_| PathBuf::from("/home/u/.codex/multi-auth/projects/project-abc123456789")),
+            resolve_path: Box::new(move |input| {
+                // Accept anything under home/tmp probes; reject the escape
+                // candidates with the injected message.
+                if input.contains("sandbox_escape_probe") {
+                    Err(reject_message.to_string())
+                } else {
+                    Ok(PathBuf::from(input))
+                }
+            }),
+            homedir: Box::new(|| PathBuf::from("/home/u")),
+            tmpdir: Box::new(|| PathBuf::from("/tmp")),
+        }
+    }
+
+    fn deps_with(paths: VerifyPathsDeps, flagged_code: Option<i32>) -> VerifyCommandDeps {
+        VerifyCommandDeps {
+            verify_paths_deps: paths,
+            run_verify_flagged: flagged_code.map(|code| {
+                let f: Box<dyn Fn(Vec<String>) -> BoxFuture<i32> + Send + Sync> =
+                    Box::new(move |_args| Box::pin(async move { code }));
+                f
+            }),
+            set_storage_path: None,
+        }
+    }
+
+    #[tokio::test]
+    async fn requires_a_mode() {
+        let deps = deps_with(fake_paths_deps("Access denied: nope"), Some(0));
+        let mut out = CliOut::capture();
+        assert_eq!(run_verify_command_with(&[], &deps, &mut out).await, 1);
+        assert_eq!(
+            out.error_text(),
+            "verify requires a mode: --paths (path chain self-test), --flagged (verify flagged accounts), or --all"
+        );
+    }
+
+    #[tokio::test]
+    async fn paths_and_flagged_cannot_be_combined_without_all() {
+        let deps = deps_with(fake_paths_deps("Access denied: nope"), Some(0));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(&args(&["--paths", "--flagged"]), &deps, &mut out).await,
+            1
+        );
+        assert_eq!(
+            out.error_text(),
+            "--paths and --flagged cannot be combined; use --all to run both, or pick one"
+        );
+    }
+
+    #[tokio::test]
+    async fn paths_mode_reports_ok_chain_and_access_denied_rejection() {
+        let deps = deps_with(fake_paths_deps("Access denied: path must be within home directory, project directory, or temp directory"), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(&args(&["--paths", "--json"]), &deps, &mut out).await,
+            0
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["command"], Value::from("verify"));
+        assert_eq!(payload["mode"], Value::from("paths"));
+        assert_eq!(payload["ok"], Value::from(true));
+        let steps = payload["paths"]["steps"].as_array().expect("steps");
+        let names: Vec<&str> = steps
+            .iter()
+            .map(|step| step["name"].as_str().unwrap())
+            .collect();
+        assert_eq!(
+            names,
+            vec![
+                "process.cwd",
+                "findProjectRoot",
+                "resolveProjectStorageIdentityRoot",
+                "getProjectStorageKey",
+                "getProjectConfigDir",
+                "getProjectGlobalConfigDir",
+            ]
+        );
+        let sandbox = payload["paths"]["sandboxTests"].as_array().expect("tests");
+        assert_eq!(sandbox.len(), 3);
+        assert_eq!(sandbox[2]["name"], Value::from("sandbox-reject-escape"));
+        assert_eq!(sandbox[2]["rejected"], Value::from(true));
+        assert_eq!(sandbox[2]["ok"], Value::from(true));
+        assert!(sandbox[2].get("error").is_none());
+    }
+
+    #[tokio::test]
+    async fn wrong_rejection_reason_fails_the_escape_probe() {
+        let deps = deps_with(fake_paths_deps("ENOENT: no such file"), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(&args(&["--paths"]), &deps, &mut out).await,
+            1
+        );
+        let text = out.info_text();
+        assert!(text.starts_with("verify --paths: FAIL"));
+        assert!(text.contains("✗ sandbox-reject-escape (rejected): ENOENT: no such file"));
+    }
+
+    #[tokio::test]
+    async fn no_project_root_fails_and_reports_error() {
+        let mut paths = fake_paths_deps("Access denied: x");
+        paths.find_project_root = Box::new(|_| None);
+        let deps = deps_with(paths, None);
+        let mut out = CliOut::capture();
+        assert_eq!(run_verify_command_with(&args(&["--paths"]), &deps, &mut out).await, 1);
+        let text = out.info_text();
+        assert!(text.contains("✗ findProjectRoot (in: "));
+        assert!(text.contains(" error: no project root detected from cwd"));
+    }
+
+    #[tokio::test]
+    async fn flagged_mode_delegates_and_passes_through_flags() {
+        use std::sync::{Arc, Mutex};
+        let received: Arc<Mutex<Vec<Vec<String>>>> = Arc::new(Mutex::new(Vec::new()));
+        let received_clone = Arc::clone(&received);
+        let deps = VerifyCommandDeps {
+            verify_paths_deps: fake_paths_deps("Access denied: x"),
+            run_verify_flagged: Some(Box::new(move |args| {
+                received_clone.lock().unwrap().push(args);
+                Box::pin(async { 0 })
+            })),
+            set_storage_path: None,
+        };
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(
+                &args(&["--flagged", "--json", "--dry-run", "-n", "--no-restore"]),
+                &deps,
+                &mut out
+            )
+            .await,
+            0
+        );
+        assert_eq!(
+            received.lock().unwrap()[0],
+            args(&["--json", "--dry-run", "-n", "--no-restore"])
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["mode"], Value::from("flagged"));
+        assert_eq!(payload["flaggedExitCode"], Value::from(0));
+        assert!(payload.get("paths").is_none());
+    }
+
+    #[tokio::test]
+    async fn all_mode_combines_both_and_flagged_failure_fails_overall() {
+        let deps = deps_with(fake_paths_deps("Access denied: x"), Some(1));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(&args(&["--all", "--json"]), &deps, &mut out).await,
+            1
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["mode"], Value::from("all"));
+        assert_eq!(payload["ok"], Value::from(false));
+        assert_eq!(payload["flaggedExitCode"], Value::from(1));
+    }
+
+    #[tokio::test]
+    async fn flagged_delegation_unavailable_errors() {
+        let deps = deps_with(fake_paths_deps("Access denied: x"), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_verify_command_with(&args(&["--flagged"]), &deps, &mut out).await,
+            1
+        );
+        assert_eq!(out.error_text(), "verify --flagged delegation is not available");
+    }
+}
diff --git a/crates/manager/src/commands/why_selected.rs b/crates/manager/src/commands/why_selected.rs
new file mode 100644
index 000000000..71a47c486
--- /dev/null
+++ b/crates/manager/src/commands/why_selected.rs
@@ -0,0 +1,698 @@
+//! Port of `lib/codex-manager/commands/why-selected.ts`.
+//!
+//! Behavior source: spec 08 §4.22 (+ gotcha 22): `--last` performs a live
+//! recomputation (there is no persisted selection tracker); the runtime
+//! snapshot only contributes `generatedAt` via the dispatcher wrapper.
+//! Non-finite scores print `"NaN"`.
+
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::token_utils::sanitize_email;
+use cma_core::utils::now_ms;
+use cma_rotation::selector::{
+    select_hybrid_account_traced, AccountWithMetrics, HybridSelectionCandidateTrace,
+    HybridSelectionTraceResult, SelectHybridAccountParams,
+};
+use cma_rotation::trackers::{get_health_tracker, get_token_tracker, TrackerKey};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_load_accounts, default_set_storage_path, BoxFuture, LoadAccountsFn, SetStoragePathFn,
+};
+
+/// TS `WhySelectedCliOptions`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct WhySelectedCliOptions {
+    pub json: bool,
+    pub mode: WhySelectedMode,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum WhySelectedMode {
+    Now,
+    Last,
+}
+
+impl WhySelectedMode {
+    fn as_str(self) -> &'static str {
+        match self {
+            WhySelectedMode::Now => "now",
+            WhySelectedMode::Last => "last",
+        }
+    }
+}
+
+/// The dispatcher's snapshot wrapper output — ONLY `generatedAt` passes
+/// through (number|string), everything else is dropped.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct WhySelectedRuntimeSnapshot {
+    pub generated_at: Option<Value>,
+}
+
+/// TS `WhySelectedCommandDeps` (log sinks live on [`CliOut`]).
+#[allow(clippy::type_complexity)] // boxed DI seams mirror the TS deps object 1:1
+pub struct WhySelectedCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub select_account_traced:
+        Box<dyn Fn(&AccountStorageV3) -> HybridSelectionTraceResult + Send + Sync>,
+    pub load_runtime_observability_snapshot:
+        Option<Box<dyn Fn() -> BoxFuture<Option<WhySelectedRuntimeSnapshot>> + Send + Sync>>,
+    pub sanitize_email: Box<dyn Fn(Option<&str>) -> Option<String> + Send + Sync>,
+}
+
+/// TS dispatcher `buildSelectAccountTraced()` — builds `AccountWithMetrics`
+/// from persisted storage and runs the traced hybrid selector against the
+/// process-global (volatile, never persisted) trackers.
+pub fn select_account_traced_production(storage: &AccountStorageV3) -> HybridSelectionTraceResult {
+    let now = now_ms();
+    let health_tracker = get_health_tracker(None);
+    let token_tracker = get_token_tracker(None);
+    let accounts_with_metrics: Vec<AccountWithMetrics> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let enabled = account.enabled != Some(false);
+            let rate_limited = account
+                .rate_limit_reset_times
+                .as_ref()
+                .map(|times| times.iter().any(|(_, value)| value > now))
+                .unwrap_or(false);
+            let cooling_down = account.cooling_down_until.is_some_and(|until| until > now);
+            AccountWithMetrics {
+                index,
+                tracker_key: account
+                    .account_id
+                    .clone()
+                    .map(TrackerKey::from)
+                    .or(Some(TrackerKey::Number(index as i64))),
+                is_available: enabled && !rate_limited && !cooling_down,
+                last_used: account.last_used,
+            }
+        })
+        .collect();
+    let metrics_ref: &[AccountWithMetrics] = &accounts_with_metrics;
+    select_hybrid_account_traced(SelectHybridAccountParams::new(
+        metrics_ref,
+        health_tracker,
+        token_tracker,
+    ))
+}
+
+impl Default for WhySelectedCommandDeps {
+    fn default() -> Self {
+        WhySelectedCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            load_accounts: default_load_accounts(),
+            select_account_traced: Box::new(select_account_traced_production),
+            load_runtime_observability_snapshot: Some(Box::new(|| {
+                Box::pin(async {
+                    let snapshot =
+                        cma_runtime::observability::load_persisted_runtime_observability_snapshot()?;
+                    // Only {generatedAt} passes through (number|string).
+                    match snapshot.extra.get("generatedAt") {
+                        Some(value) if value.is_number() || value.is_string() => {
+                            Some(WhySelectedRuntimeSnapshot {
+                                generated_at: Some(value.clone()),
+                            })
+                        }
+                        _ => None,
+                    }
+                })
+            })),
+            sanitize_email: Box::new(sanitize_email),
+        }
+    }
+}
+
+/// TS `parseWhySelectedArgs(args)`.
+pub fn parse_why_selected_args(args: &[String]) -> Result<WhySelectedCliOptions, String> {
+    let mut options = WhySelectedCliOptions {
+        json: false,
+        mode: WhySelectedMode::Now,
+    };
+    let mut mode_explicitly_set = false;
+    for arg in args {
+        if arg == "--json" || arg == "-j" {
+            options.json = true;
+            continue;
+        }
+        if arg == "--now" || arg == "-n" {
+            if mode_explicitly_set && options.mode != WhySelectedMode::Now {
+                return Err("Cannot combine --now with --last".to_string());
+            }
+            options.mode = WhySelectedMode::Now;
+            mode_explicitly_set = true;
+            continue;
+        }
+        if arg == "--last" || arg == "-l" {
+            if mode_explicitly_set && options.mode != WhySelectedMode::Last {
+                return Err("Cannot combine --now with --last".to_string());
+            }
+            options.mode = WhySelectedMode::Last;
+            mode_explicitly_set = true;
+            continue;
+        }
+        return Err(format!("Unknown option: {arg}"));
+    }
+    Ok(options)
+}
+
+/// TS `printWhySelectedUsage()`.
+pub fn print_why_selected_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth why-selected [--now | --last] [--json]",
+            "",
+            "Options:",
+            "  --now, -n     Run selection now with live state (default)",
+            "  --last, -l    Recompute selection using current state + last persisted runtime snapshot",
+            "  --json, -j    Print machine-readable JSON output",
+            "",
+            "Exits 0 when an account is selected, 1 when no account can be selected.",
+        ]
+        .join("\n"),
+    );
+}
+
+fn format_score(value: f64) -> String {
+    if !value.is_finite() {
+        return "NaN".to_string();
+    }
+    format!("{value:.2}")
+}
+
+fn number_value(value: f64) -> Value {
+    serde_json::Number::from_f64(value)
+        .map(Value::Number)
+        .unwrap_or(Value::Null)
+}
+
+struct CandidateRecord {
+    index: usize,
+    one_based_index: usize,
+    email: Option<String>,
+    account_id: Option<String>,
+    enabled: bool,
+    available: bool,
+    health: f64,
+    tokens: f64,
+    hours_since_used: f64,
+    capability_boost: f64,
+    pid_bonus: f64,
+    score: f64,
+    last_switch_reason: Option<String>,
+    last_rate_limit_reason: Option<String>,
+    cooldown_reason: Option<String>,
+    reason: Option<String>,
+}
+
+fn build_candidate_record(
+    storage: &AccountStorageV3,
+    candidate: &HybridSelectionCandidateTrace,
+    sanitize: &(dyn Fn(Option<&str>) -> Option<String> + Send + Sync),
+) -> CandidateRecord {
+    let account = storage.accounts.get(candidate.index);
+    CandidateRecord {
+        index: candidate.index,
+        one_based_index: candidate.index + 1,
+        email: sanitize(account.and_then(|account| account.email.as_deref())),
+        account_id: account.and_then(|account| account.account_id.clone()),
+        enabled: account.map(|account| account.enabled != Some(false)).unwrap_or(true),
+        available: candidate.is_available,
+        health: candidate.health,
+        tokens: candidate.tokens,
+        hours_since_used: candidate.hours_since_used,
+        capability_boost: candidate.capability_boost,
+        pid_bonus: candidate.pid_bonus,
+        score: candidate.score,
+        last_switch_reason: account
+            .and_then(|account| account.last_switch_reason)
+            .map(|reason| reason.as_str().to_string()),
+        // Runtime-only ManagedAccount field; never present on persisted
+        // storage (the TS CLI reads it as undefined here too).
+        last_rate_limit_reason: None,
+        cooldown_reason: account
+            .and_then(|account| account.cooldown_reason)
+            .map(|reason| reason.as_str().to_string()),
+        reason: candidate.reason.map(str::to_string),
+    }
+}
+
+fn candidate_to_value(record: &CandidateRecord) -> Value {
+    let mut row = Map::new();
+    row.insert("index".into(), Value::from(record.index as i64));
+    row.insert("oneBasedIndex".into(), Value::from(record.one_based_index as i64));
+    if let Some(email) = &record.email {
+        row.insert("email".into(), Value::from(email.clone()));
+    }
+    if let Some(account_id) = &record.account_id {
+        row.insert("accountId".into(), Value::from(account_id.clone()));
+    }
+    row.insert("enabled".into(), Value::from(record.enabled));
+    row.insert("available".into(), Value::from(record.available));
+    row.insert("health".into(), number_value(record.health));
+    row.insert("tokens".into(), number_value(record.tokens));
+    row.insert("hoursSinceUsed".into(), number_value(record.hours_since_used));
+    row.insert("capabilityBoost".into(), number_value(record.capability_boost));
+    row.insert("pidBonus".into(), number_value(record.pid_bonus));
+    row.insert("score".into(), number_value(record.score));
+    if let Some(last_switch_reason) = &record.last_switch_reason {
+        row.insert("lastSwitchReason".into(), Value::from(last_switch_reason.clone()));
+    }
+    if let Some(last_rate_limit_reason) = &record.last_rate_limit_reason {
+        row.insert(
+            "lastRateLimitReason".into(),
+            Value::from(last_rate_limit_reason.clone()),
+        );
+    }
+    if let Some(cooldown_reason) = &record.cooldown_reason {
+        row.insert("cooldownReason".into(), Value::from(cooldown_reason.clone()));
+    }
+    if let Some(reason) = &record.reason {
+        row.insert("reason".into(), Value::from(reason.clone()));
+    }
+    Value::Object(row)
+}
+
+/// Production entry.
+pub async fn run_why_selected_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_why_selected_command_with(args, &WhySelectedCommandDeps::default(), out).await
+}
+
+/// TS `runWhySelectedCommand(args, deps)`.
+pub async fn run_why_selected_command_with(
+    args: &[String],
+    deps: &WhySelectedCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_why_selected_usage(out);
+        return 0;
+    }
+
+    let options = match parse_why_selected_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_why_selected_usage(out);
+            return 1;
+        }
+    };
+
+    (deps.set_storage_path)(None);
+    let storage = (deps.load_accounts)().await;
+    let Some(storage) = storage.filter(|storage| !storage.accounts.is_empty()) else {
+        if options.json {
+            let mut payload = Map::new();
+            payload.insert("command".into(), Value::from("why-selected"));
+            payload.insert("mode".into(), Value::from(options.mode.as_str()));
+            payload.insert("ok".into(), Value::from(false));
+            payload.insert("error".into(), Value::from("no accounts configured"));
+            payload.insert("selected".into(), Value::Null);
+            payload.insert("candidates".into(), Value::Array(Vec::new()));
+            out.info(cma_core::json_io::stringify_pretty2(&Value::Object(payload)));
+        } else {
+            out.error("No accounts configured. Run `codex-multi-auth login` to add an account.");
+        }
+        return 1;
+    };
+
+    let trace = (deps.select_account_traced)(&storage);
+    let candidates: Vec<CandidateRecord> = trace
+        .candidates
+        .iter()
+        .map(|candidate| build_candidate_record(&storage, candidate, deps.sanitize_email.as_ref()))
+        .collect();
+
+    let selected_record: Option<(CandidateRecord, String)> = trace.selected_index.and_then(|selected_index| {
+        trace
+            .candidates
+            .iter()
+            .find(|candidate| candidate.index == selected_index)
+            .map(|base_candidate| {
+                (
+                    build_candidate_record(&storage, base_candidate, deps.sanitize_email.as_ref()),
+                    trace.selection_reason.clone(),
+                )
+            })
+    });
+
+    let mut runtime_snapshot: Option<WhySelectedRuntimeSnapshot> = None;
+    if options.mode == WhySelectedMode::Last
+        && let Some(load) = &deps.load_runtime_observability_snapshot
+    {
+        runtime_snapshot = load().await;
+    }
+
+    if options.json {
+        let mut payload = Map::new();
+        payload.insert("command".into(), Value::from("why-selected"));
+        payload.insert("mode".into(), Value::from(options.mode.as_str()));
+        payload.insert("ok".into(), Value::from(selected_record.is_some()));
+        payload.insert(
+            "availableCount".into(),
+            Value::from(trace.available_count as i64),
+        );
+        payload.insert("totalCount".into(), Value::from(storage.accounts.len() as i64));
+        if let Some(quota_key) = &trace.quota_key {
+            payload.insert("quotaKey".into(), Value::from(quota_key.clone()));
+        }
+        let mut config = Map::new();
+        config.insert("healthWeight".into(), number_value(trace.config.health_weight));
+        config.insert("tokenWeight".into(), number_value(trace.config.token_weight));
+        config.insert(
+            "freshnessWeight".into(),
+            number_value(trace.config.freshness_weight),
+        );
+        payload.insert("config".into(), Value::Object(config));
+        payload.insert(
+            "selected".into(),
+            selected_record
+                .as_ref()
+                .map(|(record, selection_reason)| {
+                    let mut value = candidate_to_value(record);
+                    if let Some(object) = value.as_object_mut() {
+                        object.insert(
+                            "selectionReason".into(),
+                            Value::from(selection_reason.clone()),
+                        );
+                    }
+                    value
+                })
+                .unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "candidates".into(),
+            Value::Array(candidates.iter().map(candidate_to_value).collect()),
+        );
+        if options.mode == WhySelectedMode::Last {
+            payload.insert(
+                "runtimeSnapshot".into(),
+                runtime_snapshot
+                    .as_ref()
+                    .map(|snapshot| {
+                        let mut object = Map::new();
+                        if let Some(generated_at) = &snapshot.generated_at {
+                            object.insert("generatedAt".into(), generated_at.clone());
+                        }
+                        Value::Object(object)
+                    })
+                    .unwrap_or(Value::Null),
+            );
+        }
+        out.info(cma_core::json_io::stringify_pretty2(&Value::Object(payload)));
+        return if selected_record.is_some() { 0 } else { 1 };
+    }
+
+    let mode_label = match options.mode {
+        WhySelectedMode::Last => "Last selection (live recomputation; no persistent tracker)",
+        WhySelectedMode::Now => "Selection right now (live)",
+    };
+    out.info(format!("why-selected: {mode_label}"));
+    if let Some(quota_key) = &trace.quota_key {
+        out.info(format!("Quota key: {quota_key}"));
+    }
+    out.info(format!(
+        "Available: {} of {} account(s)",
+        trace.available_count,
+        storage.accounts.len()
+    ));
+    out.info("");
+
+    if let Some((record, selection_reason)) = &selected_record {
+        let label = match &record.email {
+            Some(email) => format!("Selected: account {} <{email}>", record.one_based_index),
+            None => format!("Selected: account {}", record.one_based_index),
+        };
+        out.info(label);
+        out.info(format!("  score: {}", format_score(record.score)));
+        out.info(format!("  health: {:.1}", record.health));
+        out.info(format!("  tokens: {:.1}", record.tokens));
+        out.info(format!("  hoursSinceUsed: {:.2}", record.hours_since_used));
+        out.info(format!("  reason: {selection_reason}"));
+        if let Some(last_switch_reason) = &record.last_switch_reason {
+            out.info(format!("  lastSwitchReason: {last_switch_reason}"));
+        }
+        if let Some(last_rate_limit_reason) = &record.last_rate_limit_reason {
+            out.info(format!("  lastRateLimitReason: {last_rate_limit_reason}"));
+        }
+        if let Some(cooldown_reason) = &record.cooldown_reason {
+            out.info(format!("  cooldownReason: {cooldown_reason}"));
+        }
+    } else {
+        out.error(format!(
+            "No account could be selected: {}. Run `codex-multi-auth check` or `codex-multi-auth doctor` for diagnostics.",
+            trace.selection_reason
+        ));
+    }
+
+    out.info("");
+    out.info("Candidates (sorted by score desc):");
+    for candidate in &candidates {
+        let marker = if selected_record
+            .as_ref()
+            .is_some_and(|(record, _)| candidate.index == record.index)
+        {
+            "*"
+        } else if candidate.available {
+            " "
+        } else {
+            "x"
+        };
+        let email_segment = candidate
+            .email
+            .as_ref()
+            .map(|email| format!(" <{email}>"))
+            .unwrap_or_default();
+        let reason_segment = candidate
+            .reason
+            .as_ref()
+            .map(|reason| format!(" ({reason})"))
+            .unwrap_or_default();
+        out.info(format!(
+            "  {marker} {}{email_segment}: score={} health={:.0} tokens={:.0} hrs={:.1}{reason_segment}",
+            candidate.one_based_index,
+            format_score(candidate.score),
+            candidate.health,
+            candidate.tokens,
+            candidate.hours_since_used,
+        ));
+    }
+
+    if options.mode == WhySelectedMode::Last && runtime_snapshot.is_none() {
+        out.info("");
+        out.info(
+            "Note: no persistent selection tracker exists. Output above is a live recomputation from current state.",
+        );
+    }
+
+    if selected_record.is_some() { 0 } else { 1 }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_rotation::selector::HybridSelectionConfig;
+
+    fn args(values: &[&str]) -> Vec<String> {
+        values.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn storage_with(count: usize) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        for i in 0..count {
+            let mut account = AccountMetadataV3::new(format!("token-{i}"), 1, 1);
+            account.email = Some(format!("user{i}@example.com"));
+            account.account_id = Some(format!("acct-{i}"));
+            storage.accounts.push(account);
+        }
+        storage
+    }
+
+    fn trace_with(selected: Option<usize>, candidates: Vec<HybridSelectionCandidateTrace>) -> HybridSelectionTraceResult {
+        HybridSelectionTraceResult {
+            selected: None,
+            selected_index: selected,
+            selection_reason: if selected.is_some() {
+                "highest hybrid score".to_string()
+            } else {
+                "no accounts available".to_string()
+            },
+            candidates,
+            config: HybridSelectionConfig::default(),
+            quota_key: None,
+            available_count: selected.map(|_| 1).unwrap_or(0),
+        }
+    }
+
+    fn candidate(index: usize, score: f64, available: bool) -> HybridSelectionCandidateTrace {
+        HybridSelectionCandidateTrace {
+            index,
+            tracker_key: TrackerKey::Number(index as i64),
+            is_available: available,
+            last_used: 0,
+            health: 100.0,
+            tokens: 50.0,
+            hours_since_used: 1.25,
+            capability_boost: 0.0,
+            pid_bonus: 0.0,
+            score,
+            reason: if available {
+                None
+            } else {
+                Some("unavailable (rate-limited, cooling down, or circuit open)")
+            },
+        }
+    }
+
+    fn deps_with(
+        storage: Option<AccountStorageV3>,
+        trace: HybridSelectionTraceResult,
+        snapshot: Option<WhySelectedRuntimeSnapshot>,
+    ) -> WhySelectedCommandDeps {
+        WhySelectedCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { storage })
+            }),
+            select_account_traced: Box::new(move |_storage| trace.clone()),
+            load_runtime_observability_snapshot: Some(Box::new(move || {
+                let snapshot = snapshot.clone();
+                Box::pin(async move { snapshot })
+            })),
+            sanitize_email: Box::new(sanitize_email),
+        }
+    }
+
+    #[tokio::test]
+    async fn empty_storage_json_payload_and_exit_1() {
+        let deps = deps_with(None, trace_with(None, vec![]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_why_selected_command_with(&args(&["--json"]), &deps, &mut out).await,
+            1
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["command"], Value::from("why-selected"));
+        assert_eq!(payload["mode"], Value::from("now"));
+        assert_eq!(payload["ok"], Value::from(false));
+        assert_eq!(payload["error"], Value::from("no accounts configured"));
+        assert_eq!(payload["selected"], Value::Null);
+    }
+
+    #[tokio::test]
+    async fn conflicting_modes_rejected() {
+        let deps = deps_with(Some(storage_with(1)), trace_with(Some(0), vec![candidate(0, 5.0, true)]), None);
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_why_selected_command_with(&args(&["--now", "--last"]), &deps, &mut out).await,
+            1
+        );
+        assert_eq!(out.error_text(), "Cannot combine --now with --last");
+    }
+
+    #[tokio::test]
+    async fn selected_json_includes_selection_reason_and_exit_0() {
+        let deps = deps_with(
+            Some(storage_with(2)),
+            trace_with(Some(0), vec![candidate(0, 5.0, true), candidate(1, 2.0, false)]),
+            None,
+        );
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_why_selected_command_with(&args(&["--json"]), &deps, &mut out).await,
+            0
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["ok"], Value::from(true));
+        assert_eq!(payload["selected"]["selectionReason"], Value::from("highest hybrid score"));
+        assert_eq!(payload["selected"]["oneBasedIndex"], Value::from(1));
+        assert_eq!(payload["candidates"].as_array().unwrap().len(), 2);
+        // runtimeSnapshot key absent in `now` mode.
+        assert!(payload.get("runtimeSnapshot").is_none());
+        // JS number semantics: JSON.stringify(2) is "2" (integer form),
+        // never "2.0".
+        assert_eq!(payload["config"]["healthWeight"], Value::from(2));
+    }
+
+    #[tokio::test]
+    async fn text_mode_prints_candidates_with_markers() {
+        let deps = deps_with(
+            Some(storage_with(2)),
+            trace_with(Some(0), vec![candidate(0, 5.0, true), candidate(1, 2.0, false)]),
+            None,
+        );
+        let mut out = CliOut::capture();
+        assert_eq!(run_why_selected_command_with(&[], &deps, &mut out).await, 0);
+        let text = out.info_text();
+        assert!(text.starts_with("why-selected: Selection right now (live)"));
+        assert!(text.contains("Available: 1 of 2 account(s)"));
+        assert!(text.contains("Selected: account 1 <user0@example.com>"));
+        assert!(text.contains("  score: 5.00"));
+        assert!(text.contains("  health: 100.0"));
+        assert!(text.contains("  hoursSinceUsed: 1.25"));
+        assert!(text.contains("Candidates (sorted by score desc):"));
+        assert!(text.contains("  * 1 <user0@example.com>: score=5.00 health=100 tokens=50 hrs=1.2"));
+        assert!(text.contains(
+            "  x 2 <user1@example.com>: score=2.00 health=100 tokens=50 hrs=1.2 (unavailable (rate-limited, cooling down, or circuit open))"
+        ));
+    }
+
+    #[tokio::test]
+    async fn last_mode_without_snapshot_appends_note_and_null_snapshot() {
+        let deps = deps_with(
+            Some(storage_with(1)),
+            trace_with(Some(0), vec![candidate(0, 5.0, true)]),
+            None,
+        );
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_why_selected_command_with(&args(&["--last", "--json"]), &deps, &mut out).await,
+            0
+        );
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["mode"], Value::from("last"));
+        assert_eq!(payload["runtimeSnapshot"], Value::Null);
+
+        let deps = deps_with(
+            Some(storage_with(1)),
+            trace_with(Some(0), vec![candidate(0, 5.0, true)]),
+            None,
+        );
+        let mut out = CliOut::capture();
+        run_why_selected_command_with(&args(&["--last"]), &deps, &mut out).await;
+        assert!(out.info_text().contains(
+            "Note: no persistent selection tracker exists. Output above is a live recomputation from current state."
+        ));
+    }
+
+    #[tokio::test]
+    async fn no_selection_exits_1_with_diagnostics_hint() {
+        let deps = deps_with(
+            Some(storage_with(1)),
+            trace_with(None, vec![candidate(0, f64::NEG_INFINITY, false)]),
+            None,
+        );
+        let mut out = CliOut::capture();
+        assert_eq!(run_why_selected_command_with(&[], &deps, &mut out).await, 1);
+        assert_eq!(
+            out.error_text(),
+            "No account could be selected: no accounts available. Run `codex-multi-auth check` or `codex-multi-auth doctor` for diagnostics."
+        );
+        // Non-finite scores print NaN.
+        assert!(out.info_text().contains("score=NaN"));
+    }
+
+    #[test]
+    fn unknown_option_message() {
+        assert_eq!(
+            parse_why_selected_args(&args(&["--bogus"])).unwrap_err(),
+            "Unknown option: --bogus"
+        );
+    }
+}
diff --git a/crates/manager/src/commands/workspace.rs b/crates/manager/src/commands/workspace.rs
new file mode 100644
index 000000000..68733450d
--- /dev/null
+++ b/crates/manager/src/commands/workspace.rs
@@ -0,0 +1,380 @@
+//! Port of `lib/codex-manager/commands/workspace.ts` (issue #491).
+//!
+//! Behavior source: spec 08 §4.23. Digit-only index validation matches
+//! `switch` (spec 08 gotcha 13).
+
+use cma_accounts::manager_persistence::{format_account_label, format_workspace_lines};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    default_load_accounts, default_save_accounts, default_set_storage_path,
+    save_accounts_with_retry_boxed, LoadAccountsFn, SaveAccountsFn, SetStoragePathFn,
+};
+
+/// TS `WorkspaceCommandDeps` (log sinks live on [`CliOut`]).
+pub struct WorkspaceCommandDeps {
+    pub set_storage_path: SetStoragePathFn,
+    pub load_accounts: LoadAccountsFn,
+    pub save_accounts: SaveAccountsFn,
+}
+
+impl Default for WorkspaceCommandDeps {
+    fn default() -> Self {
+        WorkspaceCommandDeps {
+            set_storage_path: default_set_storage_path(),
+            load_accounts: default_load_accounts(),
+            save_accounts: default_save_accounts(),
+        }
+    }
+}
+
+/// Production entry.
+pub async fn run_workspace_command(args: &[String], out: &mut CliOut) -> i32 {
+    run_workspace_command_with(args, &WorkspaceCommandDeps::default(), out).await
+}
+
+fn parse_positive_digit_index(value: &str) -> Option<i64> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() || !trimmed.chars().all(|c| c.is_ascii_digit()) {
+        return None;
+    }
+    let parsed: i64 = value.trim_start().parse().ok()?;
+    if parsed < 1 {
+        return None;
+    }
+    Some(parsed)
+}
+
+/// TS `runWorkspaceCommand(args, deps)` — `workspace <account> [workspace]`:
+/// list (1 arg) or set (2 args) the active workspace of an account.
+pub async fn run_workspace_command_with(
+    args: &[String],
+    deps: &WorkspaceCommandDeps,
+    out: &mut CliOut,
+) -> i32 {
+    (deps.set_storage_path)(None);
+
+    let Some(mut storage) = (deps.load_accounts)().await else {
+        out.error("No accounts configured.");
+        return 1;
+    };
+    if storage.accounts.is_empty() {
+        out.error("No accounts configured.");
+        return 1;
+    }
+
+    let Some(account_arg) = args.first() else {
+        out.error(
+            "Missing account index. Usage: codex-multi-auth workspace <account> [workspace]",
+        );
+        return 1;
+    };
+
+    // Require a plain positive integer (matches `switch`): parseInt would
+    // silently truncate "1.9" -> 1 or "2abc" -> 2 and operate on the wrong
+    // account, so reject anything that isn't all digits.
+    let Some(parsed_account) = parse_positive_digit_index(account_arg) else {
+        out.error(format!(
+            "Invalid account index (must be a positive integer): {account_arg}"
+        ));
+        return 1;
+    };
+
+    let account_index = (parsed_account - 1) as usize;
+    if account_index >= storage.accounts.len() {
+        out.error(format!(
+            "Account index out of range. Valid range: 1-{}",
+            storage.accounts.len()
+        ));
+        return 1;
+    }
+
+    let Some(account) = storage.accounts.get(account_index) else {
+        out.error(format!("Account {parsed_account} not found."));
+        return 1;
+    };
+    let label = format_account_label(Some(account), account_index);
+
+    let workspaces = account.workspaces.clone().unwrap_or_default();
+    if workspaces.is_empty() {
+        out.info(format!(
+            "Account {parsed_account} ({label}) has no tracked workspaces."
+        ));
+        return 0;
+    }
+
+    let Some(workspace_arg) = args.get(1) else {
+        out.info(format!("Account {parsed_account}: {label}"));
+        for line in format_workspace_lines(Some(account), "  ") {
+            out.info(line.as_str());
+        }
+        out.info("");
+        out.info(format!(
+            "Switch with: codex-multi-auth workspace {parsed_account} <workspace-number>"
+        ));
+        return 0;
+    };
+
+    let trimmed = workspace_arg.trim();
+    if trimmed.is_empty() || !trimmed.chars().all(|c| c.is_ascii_digit()) {
+        out.error(format!(
+            "Invalid workspace index (must be a positive integer). Valid range: 1-{}",
+            workspaces.len()
+        ));
+        return 1;
+    }
+    let parsed_workspace: i64 = workspace_arg.trim_start().parse().unwrap_or(-1);
+    if parsed_workspace < 1 || parsed_workspace > workspaces.len() as i64 {
+        out.error(format!(
+            "Invalid workspace index. Valid range: 1-{}",
+            workspaces.len()
+        ));
+        return 1;
+    }
+
+    let workspace_index = (parsed_workspace - 1) as usize;
+    let Some(target) = workspaces.get(workspace_index) else {
+        out.error(format!("Workspace {parsed_workspace} not found."));
+        return 1;
+    };
+
+    let target_name = target
+        .name
+        .as_deref()
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .unwrap_or("(unnamed)")
+        .to_string();
+    if !target.enabled {
+        out.error(format!(
+            "Workspace {parsed_workspace} ([{target_name}]) is disabled and cannot be selected."
+        ));
+        return 1;
+    }
+
+    if storage.accounts[account_index].current_workspace_index == Some(workspace_index as i64) {
+        out.info(format!(
+            "Account {parsed_account} is already using workspace {parsed_workspace}: [{target_name}]."
+        ));
+        return 0;
+    }
+
+    // Guard a possibly-empty id the same way formatWorkspaceLines does, in
+    // case on-disk data does not conform to the Workspace interface.
+    let id = target.id.trim().to_string();
+    storage.accounts[account_index].current_workspace_index = Some(workspace_index as i64);
+    if let Err(error) = save_accounts_with_retry_boxed(&storage, &deps.save_accounts).await {
+        out.error(error.message());
+        return 1;
+    }
+
+    let id_suffix = if id.chars().count() > 6 {
+        let count = id.chars().count();
+        let (byte_idx, _) = id.char_indices().nth(count - 6).expect("count > 6");
+        id[byte_idx..].to_string()
+    } else {
+        id
+    };
+    out.info(format!(
+        "Account {parsed_account} now using workspace {parsed_workspace}: [{target_name}]{}.",
+        if id_suffix.is_empty() {
+            String::new()
+        } else {
+            format!(" (id:{id_suffix})")
+        }
+    ));
+    0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3, Workspace};
+    use std::sync::{Arc, Mutex};
+
+    struct Harness {
+        deps: WorkspaceCommandDeps,
+        saved: Arc<Mutex<Option<AccountStorageV3>>>,
+    }
+
+    fn harness(storage: Option<AccountStorageV3>) -> Harness {
+        let saved: Arc<Mutex<Option<AccountStorageV3>>> = Arc::new(Mutex::new(None));
+        let saved_clone = Arc::clone(&saved);
+        let deps = WorkspaceCommandDeps {
+            set_storage_path: Box::new(|_| {}),
+            load_accounts: Box::new(move || {
+                let storage = storage.clone();
+                Box::pin(async move { storage })
+            }),
+            save_accounts: Box::new(move |storage| {
+                let saved = Arc::clone(&saved_clone);
+                Box::pin(async move {
+                    *saved.lock().unwrap() = Some(storage);
+                    Ok(())
+                })
+            }),
+        };
+        Harness { deps, saved }
+    }
+
+    fn workspace(id: &str, name: &str, enabled: bool) -> Workspace {
+        Workspace {
+            id: id.to_string(),
+            name: Some(name.to_string()),
+            enabled,
+            disabled_at: None,
+            is_default: None,
+        }
+    }
+
+    fn storage_with_workspaces(
+        workspaces: Vec<Workspace>,
+        current: Option<i64>,
+    ) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        let mut account = AccountMetadataV3::new("token-0", 1, 1);
+        account.email = Some("user@example.com".to_string());
+        account.workspaces = Some(workspaces);
+        account.current_workspace_index = current;
+        storage.accounts.push(account);
+        storage
+    }
+
+    fn args(values: &[&str]) -> Vec<String> {
+        values.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[tokio::test]
+    async fn missing_account_arg_errors() {
+        let h = harness(Some(storage_with_workspaces(vec![], None)));
+        let mut out = CliOut::capture();
+        assert_eq!(run_workspace_command_with(&[], &h.deps, &mut out).await, 1);
+        assert_eq!(
+            out.error_text(),
+            "Missing account index. Usage: codex-multi-auth workspace <account> [workspace]"
+        );
+    }
+
+    #[tokio::test]
+    async fn rejects_fractional_account_index() {
+        let h = harness(Some(storage_with_workspaces(vec![], None)));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1.9"]), &h.deps, &mut out).await,
+            1
+        );
+        assert_eq!(
+            out.error_text(),
+            "Invalid account index (must be a positive integer): 1.9"
+        );
+    }
+
+    #[tokio::test]
+    async fn no_tracked_workspaces_exits_zero() {
+        let h = harness(Some(storage_with_workspaces(vec![], None)));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1"]), &h.deps, &mut out).await,
+            0
+        );
+        assert_eq!(
+            out.info_text(),
+            "Account 1 (Account 1 (user@example.com)) has no tracked workspaces."
+        );
+    }
+
+    #[tokio::test]
+    async fn lists_workspaces_without_a_workspace_arg() {
+        let h = harness(Some(storage_with_workspaces(
+            vec![
+                workspace("ws-personal", "Personal", true),
+                workspace("ws-business-1", "Business", true),
+            ],
+            Some(0),
+        )));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1"]), &h.deps, &mut out).await,
+            0
+        );
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Account 1: Account 1 ([Personal], user@example.com)");
+        assert_eq!(lines[1], "  * 1. [Personal] id:rsonal (active)");
+        assert_eq!(lines[2], "  - 2. [Business] id:ness-1");
+        assert_eq!(lines[3], "");
+        assert_eq!(
+            lines[4],
+            "Switch with: codex-multi-auth workspace 1 <workspace-number>"
+        );
+        assert!(h.saved.lock().unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn disabled_workspace_cannot_be_selected() {
+        let h = harness(Some(storage_with_workspaces(
+            vec![workspace("a", "One", true), workspace("b", "Two", false)],
+            Some(0),
+        )));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1", "2"]), &h.deps, &mut out).await,
+            1
+        );
+        assert_eq!(
+            out.error_text(),
+            "Workspace 2 ([Two]) is disabled and cannot be selected."
+        );
+    }
+
+    #[tokio::test]
+    async fn already_current_workspace_is_a_no_op() {
+        let h = harness(Some(storage_with_workspaces(
+            vec![workspace("a", "One", true)],
+            Some(0),
+        )));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1", "1"]), &h.deps, &mut out).await,
+            0
+        );
+        assert_eq!(out.info_text(), "Account 1 is already using workspace 1: [One].");
+        assert!(h.saved.lock().unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn switches_workspace_and_persists() {
+        let h = harness(Some(storage_with_workspaces(
+            vec![
+                workspace("ws-personal", "Personal", true),
+                workspace("ws-business-1", "Business", true),
+            ],
+            Some(0),
+        )));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1", "2"]), &h.deps, &mut out).await,
+            0
+        );
+        let saved = h.saved.lock().unwrap().clone().expect("saved");
+        assert_eq!(saved.accounts[0].current_workspace_index, Some(1));
+        assert_eq!(
+            out.info_text(),
+            "Account 1 now using workspace 2: [Business] (id:ness-1)."
+        );
+    }
+
+    #[tokio::test]
+    async fn workspace_index_out_of_range() {
+        let h = harness(Some(storage_with_workspaces(
+            vec![workspace("a", "One", true)],
+            Some(0),
+        )));
+        let mut out = CliOut::capture();
+        assert_eq!(
+            run_workspace_command_with(&args(&["1", "9"]), &h.deps, &mut out).await,
+            1
+        );
+        assert_eq!(out.error_text(), "Invalid workspace index. Valid range: 1-1");
+    }
+}
diff --git a/crates/manager/src/dispatcher.rs b/crates/manager/src/dispatcher.rs
new file mode 100644
index 000000000..92ef084cd
--- /dev/null
+++ b/crates/manager/src/dispatcher.rs
@@ -0,0 +1,649 @@
+//! Port of `lib/codex-manager.ts` — the CLI dispatcher / dependency hub.
+//!
+//! `run_codex_multi_auth_cli(args) -> i32` reproduces the exact TS flow:
+//! first-run housekeeping (never fails a command), theme apply, `auth`-prefix
+//! normalization, exact-match handler dispatch, `Unknown command: <name>`.
+//!
+//! The TS module's dependency-injection closures (`createRepairCommandDeps`,
+//! per-handler deps objects) are absorbed per ARCHITECTURE §4 item 10: Rust
+//! command modules import their real dependencies directly; the dispatcher
+//! only routes. The pieces the TS dispatcher itself owned — the
+//! `buildSelectAccountTraced` scorer closure and the why-selected runtime
+//! snapshot `generatedAt` wrapper — are exported from here for the
+//! `why-selected` command to consume.
+
+use std::sync::Arc;
+
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::schemas::token::TokenResult;
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_rotation::selector::{
+    AccountWithMetrics, HybridSelectionTraceResult, SelectHybridAccountParams,
+    select_hybrid_account_traced,
+};
+use cma_rotation::trackers::{TrackerKey, get_health_tracker, get_token_tracker};
+use cma_storage::matching::{
+    AccountMatchOptions, AccountSelectionCandidate, find_matching_account_index,
+};
+use serde_json::Value;
+
+use crate::help::print_usage;
+use crate::registry::is_account_manager_command;
+
+// ---------------------------------------------------------------------------
+// Output plumbing shared by every command module
+// ---------------------------------------------------------------------------
+
+/// One emitted CLI line. `Info` ≙ TS `logInfo` (stdout); `Warn` ≙ `logWarn`
+/// and `Error` ≙ `logError` (both stderr).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum OutLine {
+    Info(String),
+    Warn(String),
+    Error(String),
+}
+
+/// Injectable output sink. In production (`stdio`) lines print immediately
+/// (stdout/stderr, matching the TS console sinks); in tests (`capture`) they
+/// accumulate so command tests can assert exact output without a TTY.
+#[derive(Debug, Default)]
+pub struct CliOut {
+    capture: Option<Vec<OutLine>>,
+}
+
+impl CliOut {
+    /// Production sink: print immediately.
+    pub fn stdio() -> Self {
+        CliOut { capture: None }
+    }
+
+    /// Test sink: buffer lines for assertions.
+    pub fn capture() -> Self {
+        CliOut {
+            capture: Some(Vec::new()),
+        }
+    }
+
+    pub fn info(&mut self, message: impl Into<String>) {
+        let message = message.into();
+        match &mut self.capture {
+            Some(lines) => lines.push(OutLine::Info(message)),
+            None => println!("{message}"),
+        }
+    }
+
+    pub fn warn(&mut self, message: impl Into<String>) {
+        let message = message.into();
+        match &mut self.capture {
+            Some(lines) => lines.push(OutLine::Warn(message)),
+            None => eprintln!("{message}"),
+        }
+    }
+
+    pub fn error(&mut self, message: impl Into<String>) {
+        let message = message.into();
+        match &mut self.capture {
+            Some(lines) => lines.push(OutLine::Error(message)),
+            None => eprintln!("{message}"),
+        }
+    }
+
+    /// Captured lines (empty in stdio mode).
+    pub fn lines(&self) -> &[OutLine] {
+        self.capture.as_deref().unwrap_or(&[])
+    }
+
+    /// All captured `Info` lines joined with `\n` (the TS tests'
+    /// `logInfo.mock.calls.join("\n")` idiom).
+    pub fn info_text(&self) -> String {
+        self.lines()
+            .iter()
+            .filter_map(|line| match line {
+                OutLine::Info(text) => Some(text.as_str()),
+                _ => None,
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    /// All captured `Error` lines joined with `\n`.
+    pub fn error_text(&self) -> String {
+        self.lines()
+            .iter()
+            .filter_map(|line| match line {
+                OutLine::Error(text) => Some(text.as_str()),
+                _ => None,
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    /// All captured `Warn` lines joined with `\n`.
+    pub fn warn_text(&self) -> String {
+        self.lines()
+            .iter()
+            .filter_map(|line| match line {
+                OutLine::Warn(text) => Some(text.as_str()),
+                _ => None,
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+}
+
+/// JS number → JSON value: integers render without a decimal point
+/// (`JSON.stringify(1)` is `"1"`, never `"1.0"`).
+pub fn js_number(value: f64) -> Value {
+    if value.is_finite() && value.fract() == 0.0 && value.abs() <= 9_007_199_254_740_991.0 {
+        Value::from(value as i64)
+    } else {
+        Value::from(value)
+    }
+}
+
+/// JS number → display string (`String(1)` is `"1"`, `String(1.5)` `"1.5"`).
+pub fn js_number_string(value: f64) -> String {
+    if value.is_finite() && value.fract() == 0.0 && value.abs() <= 9_007_199_254_740_991.0 {
+        format!("{}", value as i64)
+    } else {
+        format!("{value}")
+    }
+}
+
+/// JS `Number.parseFloat` — parses the longest leading float prefix
+/// (`"2abc"` → 2, `"1.5x"` → 1.5, `""`/`"abc"` → NaN). The account `weight`
+/// and budget cap flags rely on this exact leniency.
+pub fn js_parse_float(value: &str) -> f64 {
+    let s = value.trim_start();
+    let bytes = s.as_bytes();
+    let mut end = 0usize;
+    let mut seen_digit = false;
+    let mut seen_dot = false;
+    if end < bytes.len() && (bytes[end] == b'+' || bytes[end] == b'-') {
+        end += 1;
+    }
+    // JS also accepts a leading "Infinity"; parseFloat("Infinity") is +inf.
+    let after_sign = &s[end.min(s.len())..];
+    if after_sign.starts_with("Infinity") {
+        return if bytes.first() == Some(&b'-') {
+            f64::NEG_INFINITY
+        } else {
+            f64::INFINITY
+        };
+    }
+    while end < bytes.len() {
+        let b = bytes[end];
+        if b.is_ascii_digit() {
+            seen_digit = true;
+            end += 1;
+        } else if b == b'.' && !seen_dot {
+            seen_dot = true;
+            end += 1;
+        } else {
+            break;
+        }
+    }
+    if !seen_digit {
+        return f64::NAN;
+    }
+    // Optional exponent.
+    if end < bytes.len() && (bytes[end] == b'e' || bytes[end] == b'E') {
+        let mut exp_end = end + 1;
+        if exp_end < bytes.len() && (bytes[exp_end] == b'+' || bytes[exp_end] == b'-') {
+            exp_end += 1;
+        }
+        let digits_start = exp_end;
+        while exp_end < bytes.len() && bytes[exp_end].is_ascii_digit() {
+            exp_end += 1;
+        }
+        if exp_end > digits_start {
+            end = exp_end;
+        }
+    }
+    s[..end].parse::<f64>().unwrap_or(f64::NAN)
+}
+
+/// JS `String.prototype.slice(0, n)` over UTF-16 code units (the TS
+/// truncations for notes/thread names count UTF-16 units, not chars).
+pub fn js_slice_utf16(value: &str, max_units: usize) -> String {
+    let units: Vec<u16> = value.encode_utf16().collect();
+    if units.len() <= max_units {
+        return value.to_string();
+    }
+    String::from_utf16_lossy(&units[..max_units])
+}
+
+/// UTF-16 length of a string (JS `String.prototype.length`).
+pub fn js_len_utf16(value: &str) -> usize {
+    value.encode_utf16().count()
+}
+
+// ---------------------------------------------------------------------------
+// buildSelectAccountTraced (dispatcher-owned scorer for `why-selected`)
+// ---------------------------------------------------------------------------
+
+/// Port of the TS `buildSelectAccountTraced()` closure body: score every
+/// stored account through the process-global (volatile, never persisted)
+/// health/token trackers.
+pub fn select_account_traced(storage: &AccountStorageV3) -> HybridSelectionTraceResult {
+    let now = cma_core::utils::now_ms();
+    let health_tracker = get_health_tracker(None);
+    let token_tracker = get_token_tracker(None);
+    let accounts_with_metrics: Vec<AccountWithMetrics> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let enabled = account.enabled != Some(false);
+            let mut rate_limited = false;
+            if let Some(rate_limits) = &account.rate_limit_reset_times {
+                for (_, value) in rate_limits.iter() {
+                    if value > now {
+                        rate_limited = true;
+                        break;
+                    }
+                }
+            }
+            let cooling_down = matches!(account.cooling_down_until, Some(until) if until > now);
+            let is_available = enabled && !rate_limited && !cooling_down;
+            AccountWithMetrics {
+                index,
+                tracker_key: Some(match &account.account_id {
+                    Some(id) => TrackerKey::Text(id.clone()),
+                    None => TrackerKey::Number(index as i64),
+                }),
+                is_available,
+                last_used: account.last_used,
+            }
+        })
+        .collect();
+    select_hybrid_account_traced(SelectHybridAccountParams::new(
+        &accounts_with_metrics,
+        health_tracker,
+        token_tracker,
+    ))
+}
+
+/// The dispatcher's `why-selected` snapshot wrapper: the persisted runtime
+/// observability snapshot contributes ONLY `generatedAt` (number|string;
+/// anything else leaves the key absent). `None` when no snapshot exists.
+pub fn why_selected_runtime_snapshot() -> Option<Value> {
+    let snapshot = cma_runtime::observability::load_persisted_runtime_observability_snapshot()?;
+    let value = serde_json::to_value(&snapshot).ok()?;
+    let mut wrapped = serde_json::Map::new();
+    if let Some(generated_at) = value.get("generatedAt")
+        && (generated_at.is_number() || generated_at.is_string())
+    {
+        wrapped.insert("generatedAt".to_string(), generated_at.clone());
+    }
+    Some(Value::Object(wrapped))
+}
+
+// ---------------------------------------------------------------------------
+// autoSyncActiveAccountToCodex (exported; called by the wrapper)
+// ---------------------------------------------------------------------------
+
+/// Port of TS `autoSyncActiveAccountToCodex(): Promise<boolean>`.
+///
+/// Deviation note: TS lets a storage-transaction rejection propagate to the
+/// caller; the Rust boolean surface maps any transaction error to `false`
+/// (the wrapper treats both identically — "sync did not complete").
+pub async fn auto_sync_active_account_to_codex() -> bool {
+    cma_storage::facade::set_storage_path(None);
+    let Some(loaded) = cma_storage::load::load_accounts().await else {
+        return false;
+    };
+    let storage = loaded.storage;
+    if storage.accounts.is_empty() {
+        return false;
+    }
+
+    let active_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    if active_index >= storage.accounts.len() {
+        return false;
+    }
+    let account = &storage.accounts[active_index];
+    let account_match = AccountSelectionCandidate {
+        account_id: account.account_id.clone(),
+        email: account.email.clone(),
+        refresh_token: Some(account.refresh_token.clone()),
+    };
+
+    let now = cma_core::utils::now_ms();
+    let mut sync_access_token = account.access_token.clone();
+    let mut sync_refresh_token = account.refresh_token.clone();
+    let mut sync_expires_at = account.expires_at;
+    let mut sync_id_token: Option<String> = None;
+    let mut sync_account_id = account.account_id.clone();
+    let mut sync_email = account.email.clone();
+    let mut changed = false;
+    let mut next_stored_account: Option<AccountMetadataV3> = None;
+
+    if !crate::login::account_credentials::has_usable_access_token(account, now) {
+        let refresh_result = cma_auth::refresh_queue::queued_refresh(&account.refresh_token).await;
+        let TokenResult::Success(success) = refresh_result else {
+            return false;
+        };
+        let mut next = account.clone();
+        let token_account_id = extract_account_id(Some(&success.access));
+        let next_email = sanitize_email(
+            extract_account_email(Some(&success.access), success.id_token.as_deref()).as_deref(),
+        );
+        if next.refresh_token != success.refresh {
+            next.refresh_token = success.refresh.clone();
+            changed = true;
+        }
+        if next.access_token.as_deref() != Some(success.access.as_str()) {
+            next.access_token = Some(success.access.clone());
+            changed = true;
+        }
+        if next.expires_at != Some(success.expires) {
+            next.expires_at = Some(success.expires);
+            changed = true;
+        }
+        if let Some(next_email_value) = &next_email
+            && next.email.as_deref() != Some(next_email_value.as_str())
+        {
+            next.email = Some(next_email_value.clone());
+            changed = true;
+        }
+        if crate::login::account_credentials::apply_token_account_identity(
+            &mut next,
+            token_account_id.as_deref(),
+        ) {
+            changed = true;
+        }
+        sync_access_token = Some(success.access.clone());
+        sync_refresh_token = success.refresh.clone();
+        sync_expires_at = Some(success.expires);
+        sync_id_token = success.id_token.clone();
+        sync_account_id = next.account_id.clone();
+        sync_email = next.email.clone();
+        next_stored_account = Some(next);
+    }
+
+    if changed && let Some(next_stored) = next_stored_account.clone() {
+        let match_candidate = account_match.clone();
+        let persisted = cma_storage::transactions::with_account_storage_transaction(
+            move |loaded_storage, persist| async move {
+                let Some(loaded_storage) = loaded_storage else {
+                    return Ok(false);
+                };
+                let mut next_storage = loaded_storage.clone();
+                let options = AccountMatchOptions {
+                    allow_unique_account_id_fallback_without_email: true,
+                };
+                let target_index =
+                    find_matching_account_index(&next_storage.accounts, &match_candidate, options)
+                        .or_else(|| {
+                            find_matching_account_index(
+                                &next_storage.accounts,
+                                &next_stored,
+                                options,
+                            )
+                        });
+                let Some(target_index) = target_index else {
+                    return Ok(false);
+                };
+                next_storage.accounts[target_index] = next_stored.clone();
+                persist.persist(&next_storage).await?;
+                Ok(true)
+            },
+        )
+        .await;
+        if !matches!(persisted, Ok(true)) {
+            return false;
+        }
+    }
+
+    cma_cli_mirror::writer::set_codex_cli_active_selection(&cma_cli_mirror::writer::ActiveSelection {
+        account_id: sync_account_id,
+        email: sync_email,
+        access_token: sync_access_token,
+        refresh_token: Some(sync_refresh_token),
+        expires_at: sync_expires_at.map(|v| v as f64),
+        id_token: sync_id_token,
+    })
+    .await
+}
+
+// ---------------------------------------------------------------------------
+// runCodexMultiAuthCli
+// ---------------------------------------------------------------------------
+
+/// Port of TS `runCodexMultiAuthCli(rawArgs): Promise<number>` (production
+/// sink; the bin calls this).
+pub async fn run_codex_multi_auth_cli(raw_args: &[String]) -> i32 {
+    let mut out = CliOut::stdio();
+    run_codex_multi_auth_cli_with(raw_args, &mut out).await
+}
+
+/// Sink-injectable core of [`run_codex_multi_auth_cli`].
+pub async fn run_codex_multi_auth_cli_with(raw_args: &[String], out: &mut CliOut) -> i32 {
+    // Lazy install setup (audit roadmap §4.5.4). ensureFirstRunSetup never
+    // throws; no command can ever fail because of first-run housekeeping.
+    let notify: cma_runtime::app_launcher::SharedLogSink =
+        Arc::new(|message: &str| eprintln!("codex-multi-auth: {message}"));
+    let _ = cma_runtime::first_run::ensure_first_run_setup(
+        cma_runtime::first_run::FirstRunSetupDeps {
+            notify: Some(notify),
+            ..Default::default()
+        },
+    )
+    .await;
+    let startup_display_settings =
+        cma_config::dashboard_settings::load_dashboard_display_settings().await;
+    crate::settings::hub::apply_ui_theme_from_dashboard_settings(&startup_display_settings);
+
+    // `auth` prefix normalization: `codex-multi-auth status` ≡
+    // `codex-multi-auth auth status`.
+    let args: Vec<String> = match raw_args.first() {
+        Some(first)
+            if !first.is_empty() && first != "auth" && is_account_manager_command(first) =>
+        {
+            let mut prefixed = Vec::with_capacity(raw_args.len() + 1);
+            prefixed.push("auth".to_string());
+            prefixed.extend(raw_args.iter().cloned());
+            prefixed
+        }
+        _ => raw_args.to_vec(),
+    };
+
+    if args.is_empty() {
+        print_usage(out);
+        return 0;
+    }
+    if args[0] == "--help" || args[0] == "-h" {
+        print_usage(out);
+        return 0;
+    }
+
+    let root = args[0].as_str();
+    let sub = args.get(1).cloned();
+    let rest: Vec<String> = if args.len() > 2 {
+        args[2..].to_vec()
+    } else {
+        Vec::new()
+    };
+    if root != "auth" {
+        print_usage(out);
+        return 1;
+    }
+
+    let command = sub.unwrap_or_else(|| "login".to_string());
+    if command == "--help" || command == "-h" {
+        print_usage(out);
+        return 0;
+    }
+
+    dispatch_command(&command, &rest, out).await
+}
+
+/// Exact-match handler map (TS `CLI_COMMAND_HANDLERS`). Keys are unique so a
+/// `match` is behavior-identical to the TS `Map` lookup.
+async fn dispatch_command(command: &str, rest: &[String], out: &mut CliOut) -> i32 {
+    match command {
+        "login" => crate::login::flow::run_auth_login(rest, out).await,
+        "list" | "status" => {
+            let json = rest.iter().any(|arg| arg == "--json" || arg == "-j");
+            crate::commands::status::run_status_command(json, out).await
+        }
+        "switch" => crate::commands::switch::run_switch_command(rest, out).await,
+        "unpin" => crate::commands::unpin::run_unpin_command(out).await,
+        "workspace" => crate::commands::workspace::run_workspace_command(rest, out).await,
+        "check" => crate::commands::check::run_check_command(rest, out).await,
+        "features" => crate::commands::status::run_features_command(out),
+        "verify-flagged" => crate::repair::verify_flagged::run_verify_flagged(rest, out).await,
+        "forecast" => crate::commands::forecast::run_forecast_command(rest, out).await,
+        "best" => crate::commands::best::run_best_command(rest, out).await,
+        "account" => crate::commands::account::run_account_command(rest, out).await,
+        "budget" => crate::commands::budget::run_budget_command(rest, out).await,
+        "bridge" => crate::commands::bridge::run_bridge_command(rest, out).await,
+        "integrations" => crate::commands::integrations::run_integrations_command(rest, out),
+        "models" => crate::commands::models::run_models_command(rest, out).await,
+        "monitor" => crate::commands::monitor::run_monitor_command(rest, out).await,
+        "report" => crate::commands::report::run_report_command(rest, out).await,
+        "usage" => crate::commands::usage::run_usage_command(rest, out).await,
+        "rotation" => crate::commands::rotation::run_rotation_command(rest, out).await,
+        "why-selected" => crate::commands::why_selected::run_why_selected_command(rest, out).await,
+        "history" => crate::commands::history::run_history_command(rest, out),
+        "verify" => crate::commands::verify::run_verify_command(rest, out).await,
+        "fix" => crate::repair::fix::run_fix(rest, out).await,
+        "doctor" => crate::repair::doctor::run_doctor(rest, out).await,
+        "uninstall" => crate::commands::uninstall::run_uninstall_command(rest, out).await,
+        "config" => {
+            let subcommand = rest.first().map(String::as_str);
+            let config_args: Vec<String> = if rest.len() > 1 {
+                rest[1..].to_vec()
+            } else {
+                Vec::new()
+            };
+            match subcommand {
+                Some("explain") => {
+                    crate::commands::config_explain::run_config_explain_command(&config_args, out)
+                }
+                Some("template") => {
+                    crate::commands::init_config::run_init_config_command(&config_args, out).await
+                }
+                _ => {
+                    out.error(format!(
+                        "Unknown config command: {}",
+                        subcommand.unwrap_or("(missing)")
+                    ));
+                    1
+                }
+            }
+        }
+        "init-config" => crate::commands::init_config::run_init_config_command(rest, out).await,
+        "debug" => {
+            let subcommand = rest.first().map(String::as_str);
+            let debug_args: Vec<String> = if rest.len() > 1 {
+                rest[1..].to_vec()
+            } else {
+                Vec::new()
+            };
+            match subcommand {
+                Some("bundle") => {
+                    crate::commands::debug_bundle::run_debug_bundle_command(&debug_args, out).await
+                }
+                _ => {
+                    out.error(format!(
+                        "Unknown debug command: {}",
+                        subcommand.unwrap_or("(missing)")
+                    ));
+                    1
+                }
+            }
+        }
+        _ => {
+            out.error(format!("Unknown command: {command}"));
+            print_usage(out);
+            1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn js_number_renders_integers_without_decimal() {
+        assert_eq!(serde_json::to_string(&js_number(1.0)).unwrap(), "1");
+        assert_eq!(serde_json::to_string(&js_number(0.5)).unwrap(), "0.5");
+        assert_eq!(js_number_string(1.0), "1");
+        assert_eq!(js_number_string(2.5), "2.5");
+        assert_eq!(js_number_string(0.0), "0");
+    }
+
+    #[test]
+    fn js_parse_float_matches_parse_float_leniency() {
+        assert_eq!(js_parse_float("2abc"), 2.0);
+        assert_eq!(js_parse_float("1.5"), 1.5);
+        assert_eq!(js_parse_float(" 3 "), 3.0);
+        assert_eq!(js_parse_float("-0.25x"), -0.25);
+        assert!(js_parse_float("abc").is_nan());
+        assert!(js_parse_float("").is_nan());
+        assert!(js_parse_float("Infinity").is_infinite());
+        assert_eq!(js_parse_float("1e2"), 100.0);
+        assert_eq!(js_parse_float("1e"), 1.0);
+    }
+
+    #[test]
+    fn js_slice_utf16_counts_utf16_units() {
+        assert_eq!(js_slice_utf16("abcdef", 3), "abc");
+        assert_eq!(js_slice_utf16("ab", 5), "ab");
+        // '𝒳' is one surrogate pair = 2 UTF-16 units.
+        assert_eq!(js_len_utf16("𝒳"), 2);
+    }
+
+    #[test]
+    fn cliout_capture_separates_streams() {
+        let mut out = CliOut::capture();
+        out.info("a");
+        out.warn("w");
+        out.error("e");
+        out.info("b");
+        assert_eq!(out.info_text(), "a\nb");
+        assert_eq!(out.warn_text(), "w");
+        assert_eq!(out.error_text(), "e");
+    }
+
+    // Dispatcher routing tests exercising only dispatcher-owned paths (no
+    // sibling command execution): unknown config/debug subcommands.
+    #[tokio::test]
+    async fn unknown_config_subcommand_errors_with_exact_string() {
+        let mut out = CliOut::capture();
+        let code = dispatch_command("config", &args(&["bogus"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown config command: bogus");
+
+        let mut out = CliOut::capture();
+        let code = dispatch_command("config", &[], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown config command: (missing)");
+    }
+
+    #[tokio::test]
+    async fn unknown_debug_subcommand_errors_with_exact_string() {
+        let mut out = CliOut::capture();
+        let code = dispatch_command("debug", &args(&["trace"]), &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown debug command: trace");
+    }
+
+    #[tokio::test]
+    async fn unknown_command_prints_error_then_usage() {
+        let mut out = CliOut::capture();
+        let code = dispatch_command("bogus", &[], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown command: bogus");
+        assert!(out.info_text().starts_with("Codex Multi-Auth CLI"));
+    }
+}
diff --git a/crates/manager/src/forecast_report_shared.rs b/crates/manager/src/forecast_report_shared.rs
new file mode 100644
index 000000000..d65abfdc1
--- /dev/null
+++ b/crates/manager/src/forecast_report_shared.rs
@@ -0,0 +1,548 @@
+//! Port of `lib/codex-manager/forecast-report-shared.ts` (+ the shared
+//! command plumbing this crate's command modules need: log sinks and the
+//! atomic `--out` writer that report.ts/usage.ts duplicate).
+//!
+//! Behavior source: spec 08 §3 + spec 09 §4.3. CRITICAL divergent
+//! persistence strategies preserved exactly (spec 08 gotchas 2/3):
+//! - `best` uses plain `saveAccounts` for probe-refresh persistence;
+//! - `forecast` applies the in-memory patch BEFORE persisting;
+//! - `report` persists FIRST and applies in-memory only on success.
+//!
+//! The reload-clone-match-save helper here is what forecast/report share.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::pin::Pin;
+use std::time::Duration;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::code_of;
+use cma_core::schemas::account_storage::{AccountIdSource, AccountMetadataV3, AccountStorageV3};
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::temp_path::temp_path_for;
+use cma_quota::forecast::ForecastAccountResult;
+use cma_quota::probe::CodexQuotaSnapshot;
+use cma_storage::identity::AccountIdentityLike;
+use cma_storage::matching::{find_matching_account_index, AccountMatchOptions};
+use serde_json::{Map, Value};
+
+// Re-exported to preserve the historical import surface (the TS module
+// re-exports `saveAccountsWithRetry` from `lib/storage/save-retry.ts`).
+pub use cma_storage::save_retry::{save_accounts_with_retry, save_accounts_with_retry_via};
+
+// ============================================================================
+// Shared DI plumbing for the command modules (Rust-only structure; the TS
+// commands use per-file `deps` objects with `console.log`/`console.error`
+// defaults — these aliases are that pattern's Rust spelling).
+// ============================================================================
+
+/// Boxed future for injectable async deps.
+pub type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send>>;
+/// `logInfo` / `logError` / `logWarn` sink (default: stdout/stderr line).
+pub type LogFn = Box<dyn Fn(&str) + Send + Sync>;
+
+/// Default `logInfo` (TS `console.log`).
+pub fn default_log_info() -> LogFn {
+    Box::new(|message| println!("{message}"))
+}
+
+/// Default `logError` / `logWarn` (TS `console.error` / `console.warn`).
+pub fn default_log_error() -> LogFn {
+    Box::new(|message| eprintln!("{message}"))
+}
+
+/// `setStoragePath(path: string | null)` seam.
+pub type SetStoragePathFn = Box<dyn Fn(Option<&str>) + Send + Sync>;
+/// `getStoragePath(): string` seam.
+pub type GetStoragePathFn = Box<dyn Fn() -> String + Send + Sync>;
+/// `loadAccounts(): Promise<AccountStorageV3 | null>` seam.
+pub type LoadAccountsFn = Box<dyn Fn() -> BoxFuture<Option<AccountStorageV3>> + Send + Sync>;
+/// `saveAccounts(storage): Promise<void>` seam.
+pub type SaveAccountsFn =
+    Box<dyn Fn(AccountStorageV3) -> BoxFuture<Result<(), CodexError>> + Send + Sync>;
+
+/// Real `setStoragePath` (storage facade).
+pub fn default_set_storage_path() -> SetStoragePathFn {
+    Box::new(|path| cma_storage::facade::set_storage_path(path.map(Path::new)))
+}
+
+/// Real `getStoragePath` (storage facade).
+pub fn default_get_storage_path() -> GetStoragePathFn {
+    Box::new(cma_storage::facade::get_storage_path)
+}
+
+/// Real `loadAccounts` (storage half only; restore metadata is dropped —
+/// `status` wires its own loader that keeps it).
+pub fn default_load_accounts() -> LoadAccountsFn {
+    Box::new(|| {
+        Box::pin(async { cma_storage::load::load_accounts().await.map(|loaded| loaded.storage) })
+    })
+}
+
+/// Real `saveAccounts`.
+pub fn default_save_accounts() -> SaveAccountsFn {
+    Box::new(|storage| Box::pin(async move { cma_storage::save::save_accounts(&storage).await }))
+}
+
+/// `saveAccountsWithRetry(storage, deps.saveAccounts)` over the boxed seam.
+pub async fn save_accounts_with_retry_boxed(
+    storage: &AccountStorageV3,
+    save_accounts: &SaveAccountsFn,
+) -> Result<(), CodexError> {
+    save_accounts_with_retry_via(storage, |s: &AccountStorageV3| save_accounts(s.clone())).await
+}
+
+/// TS `error instanceof Error ? error.message : String(error)`.
+pub fn error_message(error: &CodexError) -> String {
+    error.message().to_string()
+}
+
+// ============================================================================
+// forecast-report-shared.ts proper
+// ============================================================================
+
+/// TS `AccountIdentityMatch = Pick<AccountMetadataV3, "accountId" | "email" |
+/// "refreshToken">`.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct AccountIdentityMatch {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: Option<String>,
+}
+
+impl AccountIdentityLike for AccountIdentityMatch {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        self.refresh_token.as_deref()
+    }
+}
+
+/// TS `RefreshedAccountPatch`.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RefreshedAccountPatch {
+    pub refresh_token: String,
+    pub access_token: String,
+    pub expires_at: i64,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub account_id_source: Option<AccountIdSource>,
+}
+
+impl AccountIdentityLike for RefreshedAccountPatch {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.refresh_token.as_str())
+    }
+}
+
+/// TS `applyRefreshedAccountPatch(account, patch)` — unconditional assign of
+/// the token triple; `email` only when truthy; `accountId` **and**
+/// `accountIdSource` only when `accountId` truthy.
+pub fn apply_refreshed_account_patch(account: &mut AccountMetadataV3, patch: &RefreshedAccountPatch) {
+    account.refresh_token = patch.refresh_token.clone();
+    account.access_token = Some(patch.access_token.clone());
+    account.expires_at = Some(patch.expires_at);
+    if patch.email.as_deref().is_some_and(|email| !email.is_empty()) {
+        account.email = patch.email.clone();
+    }
+    if patch
+        .account_id
+        .as_deref()
+        .is_some_and(|account_id| !account_id.is_empty())
+    {
+        account.account_id = patch.account_id.clone();
+        account.account_id_source = patch.account_id_source;
+    }
+}
+
+/// TS `persistRefreshedAccountPatch(storage, accountMatch, patch,
+/// loadAccounts, saveAccounts)` — reload-latest (fallback to the given
+/// storage), clone, locate by `accountMatch` then by `patch` (both with
+/// `allowUniqueAccountIdFallbackWithoutEmail: true`); unresolvable → error
+/// with the FROZEN message; apply the patch; `saveAccountsWithRetry`.
+///
+/// Note: the caller's in-memory `storage` object is *not* what gets saved.
+pub async fn persist_refreshed_account_patch<LF, LFut, SF, SFut>(
+    storage: &AccountStorageV3,
+    account_match: &AccountIdentityMatch,
+    patch: &RefreshedAccountPatch,
+    load_accounts: LF,
+    save_accounts: SF,
+) -> Result<(), CodexError>
+where
+    LF: FnOnce() -> LFut,
+    LFut: Future<Output = Option<AccountStorageV3>>,
+    SF: FnMut(&AccountStorageV3) -> SFut,
+    SFut: Future<Output = Result<(), CodexError>>,
+{
+    let latest_storage = load_accounts().await.unwrap_or_else(|| storage.clone());
+    let mut next_storage = latest_storage.clone();
+    let options = AccountMatchOptions {
+        allow_unique_account_id_fallback_without_email: true,
+    };
+    let target_index = find_matching_account_index(&next_storage.accounts, account_match, options)
+        .or_else(|| find_matching_account_index(&next_storage.accounts, patch, options));
+    let Some(target_index) = target_index else {
+        return Err(CodexError::new(
+            "Unable to resolve refreshed account for persistence",
+        ));
+    };
+    let Some(target_account) = next_storage.accounts.get_mut(target_index) else {
+        return Err(CodexError::new(
+            "Unable to resolve refreshed account for persistence",
+        ));
+    };
+    apply_refreshed_account_patch(target_account, patch);
+    save_accounts_with_retry_via(&next_storage, save_accounts).await
+}
+
+/// Serialize a [`TokenFailure`] with its `type: "failed"` tag (the TS record
+/// spreads a `TokenResult` failure object, so the tag key is present).
+pub fn token_failure_to_value(failure: &TokenFailure) -> Value {
+    serde_json::to_value(TokenResult::Failed(failure.clone())).unwrap_or(Value::Null)
+}
+
+/// TS `serializeForecastResults(results, liveQuotaByIndex, refreshFailures,
+/// formatQuotaSnapshotLine)` — the JSON rows used by `forecast --json` and
+/// `report`. `selected` is always `false` here; `report` flips one to `true`
+/// afterwards. Keys are emitted in the exact TS object-literal order and
+/// `undefined` keys are omitted (JSON.stringify semantics).
+pub fn serialize_forecast_results(
+    results: &[ForecastAccountResult],
+    live_quota_by_index: &HashMap<usize, CodexQuotaSnapshot>,
+    refresh_failures: &HashMap<usize, TokenFailure>,
+    format_quota_snapshot_line: &dyn Fn(&CodexQuotaSnapshot) -> String,
+) -> Vec<Value> {
+    results
+        .iter()
+        .map(|result| {
+            let mut row = Map::new();
+            row.insert("index".into(), Value::from(result.index as i64));
+            row.insert("label".into(), Value::from(result.label.clone()));
+            row.insert("isCurrent".into(), Value::from(result.is_current));
+            row.insert("selected".into(), Value::from(false));
+            if let Some(primary_reason) = result.reasons.first() {
+                row.insert("primaryReason".into(), Value::from(primary_reason.clone()));
+            }
+            row.insert(
+                "availability".into(),
+                serde_json::to_value(result.availability).unwrap_or(Value::Null),
+            );
+            row.insert("riskScore".into(), Value::from(result.risk_score));
+            row.insert(
+                "riskLevel".into(),
+                serde_json::to_value(result.risk_level).unwrap_or(Value::Null),
+            );
+            row.insert("waitMs".into(), Value::from(result.wait_ms));
+            row.insert(
+                "reasons".into(),
+                Value::Array(result.reasons.iter().cloned().map(Value::from).collect()),
+            );
+            if let Some(live_quota) = live_quota_by_index.get(&result.index) {
+                let mut quota = Map::new();
+                quota.insert("status".into(), Value::from(live_quota.status));
+                if let Some(plan_type) = &live_quota.plan_type {
+                    quota.insert("planType".into(), Value::from(plan_type.clone()));
+                }
+                if let Some(active_limit) = live_quota.active_limit {
+                    quota.insert("activeLimit".into(), Value::from(active_limit));
+                }
+                quota.insert("model".into(), Value::from(live_quota.model.clone()));
+                quota.insert(
+                    "summary".into(),
+                    Value::from(format_quota_snapshot_line(live_quota)),
+                );
+                row.insert("liveQuota".into(), Value::Object(quota));
+            }
+            if let Some(refresh_failure) = refresh_failures.get(&result.index) {
+                row.insert("refreshFailure".into(), token_failure_to_value(refresh_failure));
+            }
+            Value::Object(row)
+        })
+        .collect()
+}
+
+// ============================================================================
+// Atomic `--out` writer (TS `defaultWriteFile`, duplicated verbatim in
+// report.ts and usage.ts — one Rust copy, same behavior at both call sites)
+// ============================================================================
+
+const RETRYABLE_WRITE_CODES: [&str; 2] = ["EBUSY", "EPERM"];
+
+fn is_retryable_write_error(error: &std::io::Error) -> bool {
+    code_of(error).is_some_and(|code| RETRYABLE_WRITE_CODES.contains(&code))
+}
+
+/// TS `defaultWriteFile(path, contents)` — mkdir -p, write to
+/// `tempPathFor(path)`, rename with up to 5 attempts retrying only
+/// EBUSY/EPERM with `10 * 2^attempt` ms backoff; best-effort temp unlink on
+/// failure.
+pub async fn default_write_file(path: &Path, contents: &str) -> std::io::Result<()> {
+    if let Some(parent) = path.parent() {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+    let temp_path = temp_path_for(path);
+    let mut moved = false;
+    let result = async {
+        tokio::fs::write(&temp_path, contents.as_bytes()).await?;
+        let mut attempt: u32 = 0;
+        loop {
+            match tokio::fs::rename(&temp_path, path).await {
+                Ok(()) => {
+                    moved = true;
+                    return Ok(());
+                }
+                Err(error) => {
+                    if !is_retryable_write_error(&error) || attempt >= 4 {
+                        return Err(error);
+                    }
+                    tokio::time::sleep(Duration::from_millis(
+                        10u64.saturating_mul(2u64.saturating_pow(attempt)),
+                    ))
+                    .await;
+                    attempt += 1;
+                }
+            }
+        }
+    }
+    .await;
+    if !moved {
+        // Best-effort temp cleanup.
+        let _ = tokio::fs::remove_file(&temp_path).await;
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU32, Ordering};
+    use std::sync::Arc;
+
+    fn account(refresh: &str, email: Option<&str>, id: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        account.account_id = id.map(str::to_string);
+        account
+    }
+
+    fn storage_with(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage
+    }
+
+    #[test]
+    fn apply_patch_sets_token_triple_and_conditionals() {
+        let mut target = account("old-refresh", Some("old@x.com"), Some("acct-old"));
+        target.account_id_source = Some(AccountIdSource::Manual);
+        apply_refreshed_account_patch(
+            &mut target,
+            &RefreshedAccountPatch {
+                refresh_token: "new-refresh".into(),
+                access_token: "new-access".into(),
+                expires_at: 999,
+                email: None,
+                account_id: None,
+                account_id_source: None,
+            },
+        );
+        assert_eq!(target.refresh_token, "new-refresh");
+        assert_eq!(target.access_token.as_deref(), Some("new-access"));
+        assert_eq!(target.expires_at, Some(999));
+        // email / accountId untouched when the patch omits them.
+        assert_eq!(target.email.as_deref(), Some("old@x.com"));
+        assert_eq!(target.account_id.as_deref(), Some("acct-old"));
+        assert_eq!(target.account_id_source, Some(AccountIdSource::Manual));
+
+        apply_refreshed_account_patch(
+            &mut target,
+            &RefreshedAccountPatch {
+                refresh_token: "r2".into(),
+                access_token: "a2".into(),
+                expires_at: 1000,
+                email: Some("new@x.com".into()),
+                account_id: Some("acct-new".into()),
+                account_id_source: Some(AccountIdSource::Token),
+            },
+        );
+        assert_eq!(target.email.as_deref(), Some("new@x.com"));
+        assert_eq!(target.account_id.as_deref(), Some("acct-new"));
+        assert_eq!(target.account_id_source, Some(AccountIdSource::Token));
+    }
+
+    #[tokio::test]
+    async fn persist_patch_reloads_latest_and_saves_clone() {
+        // The reload returns a DIFFERENT storage than the caller's in-memory
+        // one; the save must land on the reloaded clone.
+        let in_memory = storage_with(vec![account("stale", Some("a@x.com"), None)]);
+        let latest = storage_with(vec![account("fresh", Some("a@x.com"), None)]);
+        let saved: Arc<std::sync::Mutex<Option<AccountStorageV3>>> =
+            Arc::new(std::sync::Mutex::new(None));
+        let saved_clone = Arc::clone(&saved);
+        persist_refreshed_account_patch(
+            &in_memory,
+            &AccountIdentityMatch {
+                account_id: None,
+                email: Some("a@x.com".into()),
+                refresh_token: Some("fresh".into()),
+            },
+            &RefreshedAccountPatch {
+                refresh_token: "rotated".into(),
+                access_token: "access".into(),
+                expires_at: 5,
+                email: None,
+                account_id: None,
+                account_id_source: None,
+            },
+            move || {
+                let latest = latest.clone();
+                async move { Some(latest) }
+            },
+            move |storage| {
+                let saved = Arc::clone(&saved_clone);
+                let storage = storage.clone();
+                async move {
+                    *saved.lock().unwrap() = Some(storage);
+                    Ok(())
+                }
+            },
+        )
+        .await
+        .expect("persist succeeds");
+        let saved = saved.lock().unwrap().clone().expect("saved");
+        assert_eq!(saved.accounts[0].refresh_token, "rotated");
+        assert_eq!(saved.accounts[0].access_token.as_deref(), Some("access"));
+    }
+
+    #[tokio::test]
+    async fn persist_patch_unresolvable_account_errors_with_frozen_message() {
+        let storage = storage_with(vec![]);
+        let error = persist_refreshed_account_patch(
+            &storage,
+            &AccountIdentityMatch {
+                account_id: None,
+                email: Some("missing@x.com".into()),
+                refresh_token: Some("nope".into()),
+            },
+            &RefreshedAccountPatch {
+                refresh_token: "r".into(),
+                access_token: "a".into(),
+                expires_at: 1,
+                ..Default::default()
+            },
+            || async { None },
+            |_storage| async { Ok(()) },
+        )
+        .await
+        .expect_err("must fail");
+        assert_eq!(
+            error.message(),
+            "Unable to resolve refreshed account for persistence"
+        );
+    }
+
+    #[tokio::test]
+    async fn save_accounts_with_retry_via_retries_ebusy_then_succeeds() {
+        let attempts = Arc::new(AtomicU32::new(0));
+        let attempts_clone = Arc::clone(&attempts);
+        let storage = storage_with(vec![account("r", None, None)]);
+        save_accounts_with_retry_via(&storage, move |_s| {
+            let attempts = Arc::clone(&attempts_clone);
+            async move {
+                if attempts.fetch_add(1, Ordering::SeqCst) < 2 {
+                    Err(CodexError::storage("busy", "EBUSY", "/x", "hint", None))
+                } else {
+                    Ok(())
+                }
+            }
+        })
+        .await
+        .expect("eventually succeeds");
+        assert_eq!(attempts.load(Ordering::SeqCst), 3);
+    }
+
+    #[test]
+    fn serialize_results_row_shape_and_optional_keys() {
+        use cma_quota::forecast::ForecastAccountInput;
+        let acct = account("r", Some("a@x.com"), None);
+        let results = cma_quota::forecast::evaluate_forecast_accounts(&[
+            ForecastAccountInput::new(0, &acct, true, 1_000),
+        ]);
+        let mut live = HashMap::new();
+        live.insert(
+            0usize,
+            CodexQuotaSnapshot {
+                status: 200,
+                plan_type: Some("plus".into()),
+                active_limit: None,
+                primary: Default::default(),
+                secondary: Default::default(),
+                model: "gpt-5.5".into(),
+            },
+        );
+        let mut failures = HashMap::new();
+        failures.insert(
+            0usize,
+            TokenFailure {
+                reason: None,
+                status_code: Some(401),
+                message: Some("bad".into()),
+            },
+        );
+        let rows =
+            serialize_forecast_results(&results, &live, &failures, &|_snapshot| "line".to_string());
+        assert_eq!(rows.len(), 1);
+        let row = rows[0].as_object().expect("object row");
+        let keys: Vec<&str> = row.keys().map(String::as_str).collect();
+        // primaryReason mirrors JSON.stringify semantics: present only when
+        // reasons[0] exists.
+        let mut expected = vec!["index", "label", "isCurrent", "selected"];
+        if !results[0].reasons.is_empty() {
+            expected.push("primaryReason");
+        }
+        expected.extend([
+            "availability",
+            "riskScore",
+            "riskLevel",
+            "waitMs",
+            "reasons",
+            "liveQuota",
+            "refreshFailure",
+        ]);
+        assert_eq!(keys, expected);
+        assert_eq!(row["selected"], Value::from(false));
+        let quota = row["liveQuota"].as_object().expect("liveQuota");
+        let quota_keys: Vec<&str> = quota.keys().map(String::as_str).collect();
+        assert_eq!(quota_keys, vec!["status", "planType", "model", "summary"]);
+        assert_eq!(quota["summary"], Value::from("line"));
+        let failure = row["refreshFailure"].as_object().expect("refreshFailure");
+        assert_eq!(failure["type"], Value::from("failed"));
+        assert_eq!(failure["statusCode"], Value::from(401));
+    }
+
+    #[tokio::test]
+    async fn default_write_file_writes_atomically_and_cleans_temp() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let target = dir.path().join("nested").join("report.json");
+        default_write_file(&target, "{}\n").await.expect("write ok");
+        assert_eq!(std::fs::read_to_string(&target).expect("read"), "{}\n");
+        // No stray .tmp files remain.
+        let leftovers: Vec<_> = std::fs::read_dir(target.parent().unwrap())
+            .unwrap()
+            .filter_map(Result::ok)
+            .filter(|entry| entry.file_name().to_string_lossy().ends_with(".tmp"))
+            .collect();
+        assert!(leftovers.is_empty());
+    }
+}
diff --git a/crates/manager/src/formatters/account.rs b/crates/manager/src/formatters/account.rs
new file mode 100644
index 000000000..dc02d457c
--- /dev/null
+++ b/crates/manager/src/formatters/account.rs
@@ -0,0 +1,411 @@
+//! Port of `lib/codex-manager/formatters/account-formatters.ts`.
+//!
+//! Tone precedence (danger before warning) is security/UX-relevant — a
+//! failure whose text contains "unavailable" must render red, not be
+//! downgraded to yellow. See test/codex-manager-detail-tone.test.ts (ported
+//! below).
+
+use chrono::{Datelike, TimeZone, Timelike};
+use cma_accounts::rate_limits::format_wait_time;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::RateLimitStateV3;
+use cma_quota::forecast::{ForecastAvailability, ForecastRiskLevel};
+
+use super::quota::style_quota_summary_with;
+use super::text_style::{PromptTone, StyleContext, collapse_whitespace, style_prompt_text_with};
+
+fn contains_ci(haystack: &str, needle: &str) -> bool {
+    haystack.to_lowercase().contains(needle)
+}
+
+/// Any of the (lowercase) needles present, case-insensitively.
+fn contains_any_ci(haystack: &str, needles: &[&str]) -> bool {
+    let lower = haystack.to_lowercase();
+    needles.iter().any(|needle| lower.contains(needle))
+}
+
+fn is_js_word_char(c: char) -> bool {
+    // JS `\w` = [A-Za-z0-9_].
+    c.is_ascii_alphanumeric() || c == '_'
+}
+
+/// JS `/\b(word)\b/i` for a set of all-lowercase words.
+fn contains_word_ci(haystack: &str, words: &[&str]) -> bool {
+    let lower = haystack.to_lowercase();
+    for word in words {
+        let mut search_from = 0;
+        while let Some(rel) = lower[search_from..].find(word) {
+            let start = search_from + rel;
+            let end = start + word.len();
+            let before_ok = lower[..start]
+                .chars()
+                .next_back()
+                .is_none_or(|c| !is_js_word_char(c));
+            let after_ok = lower[end..].chars().next().is_none_or(|c| !is_js_word_char(c));
+            if before_ok && after_ok {
+                return true;
+            }
+            search_from = start + 1;
+        }
+    }
+    false
+}
+
+/// Hand-rolled match for `/^(.*?)\(([^()]*\d{1,3}%[^()]*)\)(.*)$/` over the
+/// collapsed detail: the FIRST `(...)` group containing no nested parens and
+/// at least one digit run (1–3 digits, absorbed left by `[^()]*`) followed by
+/// `%`. Returns `(prefix, quota, suffix)` (untrimmed).
+fn match_quota_detail(compact: &str) -> Option<(&str, &str, &str)> {
+    let mut search_from = 0;
+    while let Some(rel) = compact[search_from..].find('(') {
+        let open = search_from + rel;
+        let rest = &compact[open + 1..];
+        // The inner group forbids both '(' and ')' — the next paren of either
+        // kind must be the closing ')'.
+        let next_paren = rest.find(['(', ')']);
+        match next_paren {
+            Some(close_rel) if rest.as_bytes()[close_rel] == b')' => {
+                let inner = &rest[..close_rel];
+                if inner_has_percent(inner) {
+                    let close = open + 1 + close_rel;
+                    return Some((&compact[..open], inner, &compact[close + 1..]));
+                }
+                search_from = open + 1;
+            }
+            _ => {
+                search_from = open + 1;
+            }
+        }
+    }
+    None
+}
+
+/// `[^()]*\d{1,3}%[^()]*` — at least one digit immediately before a `%`.
+fn inner_has_percent(inner: &str) -> bool {
+    let bytes = inner.as_bytes();
+    for (i, b) in bytes.iter().enumerate() {
+        if *b == b'%' && i > 0 && bytes[i - 1].is_ascii_digit() {
+            return true;
+        }
+    }
+    false
+}
+
+/// TS `styleAccountDetailText(detail, fallbackTone = "muted")` over an
+/// explicit context.
+pub fn style_account_detail_text_with(
+    ctx: &StyleContext,
+    detail: &str,
+    fallback_tone: PromptTone,
+) -> String {
+    let compact = collapse_whitespace(detail);
+    if compact.is_empty() {
+        return style_prompt_text_with(ctx, "", fallback_tone);
+    }
+
+    if let Some((raw_prefix, raw_quota, raw_suffix)) = match_quota_detail(&compact) {
+        let prefix = raw_prefix.trim();
+        let quota = raw_quota.trim();
+        let suffix = raw_suffix.trim();
+
+        // danger wins across the WHOLE detail: a failure keyword anywhere —
+        // even trapped inside the (…%) quota segment — must keep the prefix
+        // red, never let a "working"/"ok" prefix render green over a real
+        // failure.
+        let detail_has_failure = contains_any_ci(&compact, &["failed", "error", "rate-limited"]);
+        let prefix_tone = if detail_has_failure {
+            PromptTone::Danger
+        } else if contains_word_ci(prefix, &["ok", "working", "succeeded", "valid"]) {
+            PromptTone::Success
+        } else {
+            fallback_tone
+        };
+        // danger wins first: a real failure whose text happens to contain
+        // "unavailable"/"not available" must render red, not yellow.
+        let suffix_tone = if contains_any_ci(suffix, &["failed", "error"]) {
+            PromptTone::Danger
+        } else if contains_any_ci(
+            suffix,
+            &[
+                "re-login",
+                "stale",
+                "warning",
+                "retry",
+                "fallback",
+                "unavailable",
+                "not available",
+            ],
+        ) {
+            PromptTone::Warning
+        } else {
+            PromptTone::Muted
+        };
+
+        let mut chunks: Vec<String> = Vec::new();
+        if !prefix.is_empty() {
+            chunks.push(style_prompt_text_with(ctx, prefix, prefix_tone));
+        }
+        chunks.push(format!("({})", style_quota_summary_with(ctx, quota)));
+        if !suffix.is_empty() {
+            chunks.push(style_prompt_text_with(ctx, suffix, suffix_tone));
+        }
+        return chunks.join(" ");
+    }
+
+    if contains_ci(&compact, "rate-limited") {
+        return style_prompt_text_with(ctx, &compact, PromptTone::Danger);
+    }
+    if contains_any_ci(&compact, &["failed", "error"]) {
+        return style_prompt_text_with(ctx, &compact, PromptTone::Danger);
+    }
+    if contains_any_ci(
+        &compact,
+        &[
+            "re-login",
+            "stale",
+            "warning",
+            "fallback",
+            "unavailable",
+            "not available",
+        ],
+    ) {
+        return style_prompt_text_with(ctx, &compact, PromptTone::Warning);
+    }
+    if contains_word_ci(&compact, &["ok", "working", "succeeded", "valid"]) {
+        return style_prompt_text_with(ctx, &compact, PromptTone::Success);
+    }
+    style_prompt_text_with(ctx, &compact, fallback_tone)
+}
+
+/// TS `styleAccountDetailText(detail)` — default `"muted"` fallback tone,
+/// live context.
+pub fn style_account_detail_text(detail: &str) -> String {
+    style_account_detail_text_with(&StyleContext::live(), detail, PromptTone::Muted)
+}
+
+/// TS `styleAccountDetailText(detail, fallbackTone)` — live context.
+pub fn style_account_detail_text_with_tone(detail: &str, fallback_tone: PromptTone) -> String {
+    style_account_detail_text_with(&StyleContext::live(), detail, fallback_tone)
+}
+
+/// TS `riskTone(level)`.
+pub fn risk_tone(level: ForecastRiskLevel) -> PromptTone {
+    match level {
+        ForecastRiskLevel::Low => PromptTone::Success,
+        ForecastRiskLevel::Medium => PromptTone::Warning,
+        ForecastRiskLevel::High => PromptTone::Danger,
+    }
+}
+
+/// TS `availabilityTone(availability)`.
+pub fn availability_tone(availability: ForecastAvailability) -> PromptTone {
+    match availability {
+        ForecastAvailability::Ready => PromptTone::Success,
+        ForecastAvailability::Delayed => PromptTone::Warning,
+        ForecastAvailability::Unavailable => PromptTone::Danger,
+    }
+}
+
+/// TS `formatRateLimitEntry(account, now, family = "codex")` — delegates to
+/// the runtime helper with `formatWaitTime` injected.
+pub fn format_rate_limit_entry(
+    rate_limit_reset_times: Option<&RateLimitStateV3>,
+    now: i64,
+    family: ModelFamily,
+) -> Option<String> {
+    cma_runtime::account_status::format_rate_limit_entry(
+        rate_limit_reset_times,
+        now,
+        &format_wait_time,
+        family,
+    )
+}
+
+/// TS `formatBackupSavedAt(mtimeMs)` — `toLocaleString(undefined, {month:
+/// "short", day: "numeric", year: "numeric", hour: "numeric", minute:
+/// "2-digit"})`. Node's default locale is en-US, so the pinned rendering is
+/// `"Jul 27, 2026, 2:35 PM"` (local time); other locales diverge in TS and
+/// are deliberately not reproduced.
+pub fn format_backup_saved_at(mtime_ms: f64) -> String {
+    if !mtime_ms.is_finite() {
+        return "Invalid Date".to_string();
+    }
+    let Some(date) = chrono::Local.timestamp_millis_opt(mtime_ms as i64).single() else {
+        return "Invalid Date".to_string();
+    };
+    let (is_pm, hour12) = date.hour12();
+    format!(
+        "{} {}, {}, {}:{:02} {}",
+        date.format("%b"),
+        date.day(),
+        date.year(),
+        hour12,
+        date.minute(),
+        if is_pm { "PM" } else { "AM" }
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_tui::ansi;
+    use cma_tui::runtime_options::{
+        UiRuntimeOptionsPatch, reset_ui_runtime_options, set_ui_runtime_options,
+    };
+    use serial_test::serial;
+
+    /// Legacy renderer (v2 off) on an interactive stdout, so danger =>
+    /// ANSI red and warning => ANSI yellow exactly (mirrors the TS suite).
+    fn legacy_tty_ctx() -> StyleContext {
+        let ui = set_ui_runtime_options(UiRuntimeOptionsPatch {
+            v2_enabled: Some(false),
+            ..Default::default()
+        });
+        StyleContext::new(ui, true)
+    }
+
+    fn styled(detail: &str) -> String {
+        style_account_detail_text_with(&legacy_tty_ctx(), detail, PromptTone::Muted)
+    }
+
+    // Ported from test/codex-manager-detail-tone.test.ts.
+
+    #[test]
+    #[serial]
+    fn danger_wins_when_a_failure_detail_also_says_unavailable() {
+        let s = styled("refresh failed: service unavailable");
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::YELLOW));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn not_available_is_treated_the_same_danger_wins() {
+        let s = styled("token error (not available)");
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::YELLOW));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn normalizes_whitespace_before_matching_tone_keywords() {
+        let s = styled("  probe   failed\n  — endpoint unavailable  ");
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::YELLOW));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn still_renders_warning_when_only_unavailable_keyword_present() {
+        let s = styled("Codex not available for this account");
+        assert!(s.contains(ansi::YELLOW));
+        assert!(!s.contains(ansi::RED));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn danger_precedence_applies_to_the_quota_suffix() {
+        let s = styled("acct (12%) — refresh failed, now unavailable");
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::YELLOW));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn working_prefix_is_not_green_when_failure_is_inside_quota_segment() {
+        let s = styled("signed in and working (live check failed: timeout 0%)");
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::GREEN));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn clamps_out_of_range_quota_percent_to_100() {
+        let clamped = styled("acct (5h 999%)");
+        let hundred = styled("acct (5h 100%)");
+        assert!(clamped.contains("100%"));
+        assert!(!clamped.contains("999%"));
+        assert!(clamped.contains(ansi::GREEN));
+        assert_eq!(clamped, hundred);
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn renders_the_zero_percent_lower_bound_as_danger() {
+        let s = styled("acct (5h 0%)");
+        assert!(s.contains("0%"));
+        assert!(s.contains(ansi::RED));
+        assert!(!s.contains(ansi::GREEN));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn success_keyword_requires_word_boundaries() {
+        for detail in ["token is invalid or expired", "refresh token revoked"] {
+            let s = styled(detail);
+            assert!(!s.contains(ansi::GREEN), "{detail} must not be green");
+        }
+        let s = styled("signed in and working");
+        assert!(s.contains(ansi::GREEN));
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    fn risk_and_availability_tones_map_exactly() {
+        assert_eq!(risk_tone(ForecastRiskLevel::Low), PromptTone::Success);
+        assert_eq!(risk_tone(ForecastRiskLevel::Medium), PromptTone::Warning);
+        assert_eq!(risk_tone(ForecastRiskLevel::High), PromptTone::Danger);
+        assert_eq!(
+            availability_tone(ForecastAvailability::Ready),
+            PromptTone::Success
+        );
+        assert_eq!(
+            availability_tone(ForecastAvailability::Delayed),
+            PromptTone::Warning
+        );
+        assert_eq!(
+            availability_tone(ForecastAvailability::Unavailable),
+            PromptTone::Danger
+        );
+    }
+
+    #[test]
+    fn format_rate_limit_entry_formats_future_resets_only() {
+        let times: RateLimitStateV3 = [("codex".to_string(), 61_000_i64)].into_iter().collect();
+        let entry = format_rate_limit_entry(Some(&times), 1_000, ModelFamily::Codex);
+        assert_eq!(entry.as_deref(), Some("resets in 1m 0s"));
+        assert_eq!(
+            format_rate_limit_entry(Some(&times), 61_000, ModelFamily::Codex),
+            None
+        );
+        assert_eq!(format_rate_limit_entry(None, 0, ModelFamily::Codex), None);
+    }
+
+    #[test]
+    fn format_backup_saved_at_renders_en_us_short_datetime() {
+        use chrono::TimeZone;
+        let ms = chrono::Local
+            .with_ymd_and_hms(2026, 7, 4, 14, 5, 0)
+            .single()
+            .expect("valid local time")
+            .timestamp_millis();
+        assert_eq!(format_backup_saved_at(ms as f64), "Jul 4, 2026, 2:05 PM");
+        let midnight = chrono::Local
+            .with_ymd_and_hms(2026, 1, 1, 0, 7, 0)
+            .single()
+            .expect("valid local time")
+            .timestamp_millis();
+        assert_eq!(
+            format_backup_saved_at(midnight as f64),
+            "Jan 1, 2026, 12:07 AM"
+        );
+    }
+}
diff --git a/crates/manager/src/formatters/dashboard.rs b/crates/manager/src/formatters/dashboard.rs
new file mode 100644
index 000000000..86161100f
--- /dev/null
+++ b/crates/manager/src/formatters/dashboard.rs
@@ -0,0 +1,84 @@
+//! Port of `lib/codex-manager/dashboard-formatters.ts` (spec 09 §5.7).
+
+use cma_config::dashboard_settings::{DashboardAccountSortMode, DashboardLayoutMode};
+
+/// TS `formatDashboardSettingState(value)` — `"[x]"` / `"[ ]"`.
+pub fn format_dashboard_setting_state(value: bool) -> String {
+    if value { "[x]" } else { "[ ]" }.to_string()
+}
+
+/// TS `formatMenuSortMode(mode)` — `"Ready-First"` / `"Manual"`.
+pub fn format_menu_sort_mode(mode: DashboardAccountSortMode) -> String {
+    match mode {
+        DashboardAccountSortMode::ReadyFirst => "Ready-First",
+        DashboardAccountSortMode::Manual => "Manual",
+    }
+    .to_string()
+}
+
+/// TS `formatMenuLayoutMode(mode)` — `"Expanded Rows"` /
+/// `"Compact + Details Pane"`.
+pub fn format_menu_layout_mode(mode: DashboardLayoutMode) -> String {
+    match mode {
+        DashboardLayoutMode::ExpandedRows => "Expanded Rows",
+        DashboardLayoutMode::CompactDetails => "Compact + Details Pane",
+    }
+    .to_string()
+}
+
+/// TS `formatMenuQuotaTtl(ttlMs)` — `Nm` when divisible by 60 000 and
+/// ≥ 60 000, `Ns` when divisible by 1 000 and ≥ 1 000, else `Nms`.
+pub fn format_menu_quota_ttl(ttl_ms: i64) -> String {
+    if ttl_ms >= 60_000 && ttl_ms % 60_000 == 0 {
+        return format!("{}m", ttl_ms / 60_000);
+    }
+    if ttl_ms >= 1_000 && ttl_ms % 1_000 == 0 {
+        return format!("{}s", ttl_ms / 1_000);
+    }
+    format!("{ttl_ms}ms")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Ported from test/dashboard-formatters.test.ts.
+
+    #[test]
+    fn formats_dashboard_toggle_states() {
+        assert_eq!(format_dashboard_setting_state(true), "[x]");
+        assert_eq!(format_dashboard_setting_state(false), "[ ]");
+    }
+
+    #[test]
+    fn formats_sort_mode_labels() {
+        assert_eq!(
+            format_menu_sort_mode(DashboardAccountSortMode::ReadyFirst),
+            "Ready-First"
+        );
+        assert_eq!(
+            format_menu_sort_mode(DashboardAccountSortMode::Manual),
+            "Manual"
+        );
+    }
+
+    #[test]
+    fn formats_layout_mode_labels() {
+        assert_eq!(
+            format_menu_layout_mode(DashboardLayoutMode::ExpandedRows),
+            "Expanded Rows"
+        );
+        assert_eq!(
+            format_menu_layout_mode(DashboardLayoutMode::CompactDetails),
+            "Compact + Details Pane"
+        );
+    }
+
+    #[test]
+    fn formats_quota_ttl_across_branches() {
+        assert_eq!(format_menu_quota_ttl(120_000), "2m");
+        assert_eq!(format_menu_quota_ttl(5_000), "5s");
+        assert_eq!(format_menu_quota_ttl(500), "500ms");
+        assert_eq!(format_menu_quota_ttl(1_500), "1500ms");
+    }
+}
diff --git a/crates/manager/src/formatters/mod.rs b/crates/manager/src/formatters/mod.rs
new file mode 100644
index 000000000..4711edaaf
--- /dev/null
+++ b/crates/manager/src/formatters/mod.rs
@@ -0,0 +1,6 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account;
+pub mod dashboard;
+pub mod model;
+pub mod quota;
+pub mod text_style;
diff --git a/crates/manager/src/formatters/model.rs b/crates/manager/src/formatters/model.rs
new file mode 100644
index 000000000..f221db934
--- /dev/null
+++ b/crates/manager/src/formatters/model.rs
@@ -0,0 +1,100 @@
+//! Port of `lib/codex-manager/formatters/model-formatters.ts`.
+
+use cma_core::model_family::ModelFamily;
+use cma_request::model_map::{
+    ModelCapabilities, get_model_capabilities, get_model_profile, resolve_normalized_model,
+};
+
+/// TS `ModelInspection`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ModelInspection {
+    pub requested: String,
+    pub normalized: String,
+    pub remapped: bool,
+    pub prompt_family: ModelFamily,
+    pub capabilities: ModelCapabilities,
+}
+
+/// TS `inspectRequestedModel(requestedModel)`.
+pub fn inspect_requested_model(requested_model: &str) -> ModelInspection {
+    let normalized = resolve_normalized_model(Some(requested_model));
+    let profile = get_model_profile(Some(normalized));
+    ModelInspection {
+        requested: requested_model.to_string(),
+        normalized: normalized.to_string(),
+        remapped: requested_model != normalized,
+        prompt_family: profile.prompt_family,
+        capabilities: get_model_capabilities(Some(normalized)),
+    }
+}
+
+/// TS `formatModelInspection(model)` — FROZEN user-visible string.
+pub fn format_model_inspection(model: &ModelInspection) -> String {
+    let route = if model.remapped {
+        format!("{} -> {}", model.requested, model.normalized)
+    } else {
+        model.normalized.clone()
+    };
+    [
+        route,
+        format!("prompt family {}", model.prompt_family.as_str()),
+        format!(
+            "tool search {}",
+            if model.capabilities.tool_search { "yes" } else { "no" }
+        ),
+        format!(
+            "computer use {}",
+            if model.capabilities.computer_use { "yes" } else { "no" }
+        ),
+    ]
+    .join(" | ")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Ported from test/codex-manager-formatters.test.ts ("model formatters").
+
+    #[test]
+    fn inspect_requested_model_reports_remapping_consistently() {
+        let inspection = inspect_requested_model("gpt-5.3-codex");
+        assert_eq!(inspection.requested, "gpt-5.3-codex");
+        assert_eq!(
+            inspection.remapped,
+            inspection.requested != inspection.normalized
+        );
+    }
+
+    #[test]
+    fn format_model_inspection_shows_route_and_capability_flags() {
+        let family = inspect_requested_model("gpt-5.3-codex").prompt_family;
+        let plain = format_model_inspection(&ModelInspection {
+            requested: "m".to_string(),
+            normalized: "m".to_string(),
+            remapped: false,
+            prompt_family: family,
+            capabilities: ModelCapabilities {
+                tool_search: true,
+                computer_use: false,
+                compaction: false,
+            },
+        });
+        assert!(plain.contains("m | prompt family "));
+        assert!(plain.contains("tool search yes"));
+        assert!(plain.contains("computer use no"));
+
+        let remapped = format_model_inspection(&ModelInspection {
+            requested: "alias".to_string(),
+            normalized: "real".to_string(),
+            remapped: true,
+            prompt_family: family,
+            capabilities: ModelCapabilities {
+                tool_search: false,
+                computer_use: true,
+                compaction: false,
+            },
+        });
+        assert!(remapped.contains("alias -> real"));
+    }
+}
diff --git a/crates/manager/src/formatters/quota.rs b/crates/manager/src/formatters/quota.rs
new file mode 100644
index 000000000..b3e966f7f
--- /dev/null
+++ b/crates/manager/src/formatters/quota.rs
@@ -0,0 +1,589 @@
+//! Port of `lib/codex-manager/formatters/quota-formatters.ts`.
+//!
+//! Type notes vs the TS source:
+//! - `QuotaCacheEntry` windows are `f64` in the cache schema while
+//!   `CodexQuotaSnapshot` windows are `i64`; the TS code shares one duck-typed
+//!   shape. Conversions here truncate fractional `windowMinutes`/`resetAtMs`
+//!   (real values are always integral).
+//! - The exhaustion check reuses `cma_quota::readiness::is_quota_cache_entry_exhausted`;
+//!   snapshots have no `updatedAt`, mirrored by a `NaN` `updated_at` (the TS
+//!   `undefined` disables the staleness escape the same way).
+
+use cma_config::dashboard_settings::DashboardDisplaySettings;
+use cma_core::json_io::format_js_number;
+use cma_quota::cache::{QuotaCacheEntry, QuotaCacheWindow};
+use cma_quota::probe::{CodexQuotaSnapshot, CodexQuotaWindow, format_quota_reset_at, format_quota_snapshot_line};
+use cma_quota::readiness::{is_quota_cache_entry_exhausted, quota_left_percent_from_used};
+use cma_tui::format::{UiTextTone, quota_tone_from_left_percent};
+
+use super::text_style::{
+    PromptTone, StyleContext, collapse_whitespace, join_styled_segments_with,
+    style_prompt_text_with,
+};
+
+fn prompt_tone_from_quota_tone(tone: UiTextTone) -> PromptTone {
+    match tone {
+        UiTextTone::Danger => PromptTone::Danger,
+        UiTextTone::Warning => PromptTone::Warning,
+        _ => PromptTone::Success,
+    }
+}
+
+/// JS `\s` (incl. U+FEFF; only plain spaces survive `collapseWhitespace`).
+fn is_js_ws(c: char) -> bool {
+    c.is_whitespace() || c == '\u{feff}'
+}
+
+/// Hand-rolled match for the TS segment regex
+/// `/^([0-9a-zA-Z]+)\s+(\d{1,3})%(,\s*resets\s+\S.*)?$/`.
+/// Returns `(window_label, left_percent_digits, reset_suffix)`.
+fn parse_quota_segment(segment: &str) -> Option<(&str, &str, Option<&str>)> {
+    let bytes = segment.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() && bytes[i].is_ascii_alphanumeric() {
+        i += 1;
+    }
+    if i == 0 {
+        return None;
+    }
+    let label = &segment[..i];
+    let ws_start = i;
+    while let Some(c) = segment[i..].chars().next() {
+        if !is_js_ws(c) {
+            break;
+        }
+        i += c.len_utf8();
+    }
+    if i == ws_start {
+        return None;
+    }
+    let digit_start = i;
+    while i < bytes.len() && bytes[i].is_ascii_digit() {
+        i += 1;
+    }
+    let digit_len = i - digit_start;
+    if digit_len == 0 || digit_len > 3 {
+        return None;
+    }
+    let digits = &segment[digit_start..i];
+    if i >= bytes.len() || bytes[i] != b'%' {
+        return None;
+    }
+    i += 1;
+    if i == bytes.len() {
+        return Some((label, digits, None));
+    }
+    // Optional `,\s*resets\s+\S.*` suffix — must consume the rest exactly.
+    let suffix = &segment[i..];
+    let mut rest = suffix;
+    rest = rest.strip_prefix(',')?;
+    rest = rest.trim_start();
+    rest = rest.strip_prefix("resets")?;
+    let after_resets = rest;
+    rest = rest.trim_start();
+    if rest.len() == after_resets.len() {
+        // `\s+` requires at least one whitespace char after "resets".
+        return None;
+    }
+    // `\S` — at least one non-whitespace char must follow.
+    if rest.is_empty() {
+        return None;
+    }
+    Some((label, digits, Some(suffix)))
+}
+
+fn contains_ci(haystack: &str, needle: &str) -> bool {
+    haystack.to_lowercase().contains(&needle.to_lowercase())
+}
+
+/// TS `styleQuotaSummary(summary)` over an explicit context.
+pub fn style_quota_summary_with(ctx: &StyleContext, summary: &str) -> String {
+    let normalized = collapse_whitespace(summary);
+    if normalized.is_empty() {
+        return style_prompt_text_with(ctx, summary, PromptTone::Muted);
+    }
+    let segments: Vec<&str> = normalized
+        .split('|')
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .collect();
+    if segments.is_empty() {
+        return style_prompt_text_with(ctx, &normalized, PromptTone::Muted);
+    }
+
+    let rendered: Vec<String> = segments
+        .iter()
+        .map(|segment| {
+            if contains_ci(segment, "rate-limited") {
+                return style_prompt_text_with(ctx, segment, PromptTone::Danger);
+            }
+            let Some((label, digits, reset_suffix)) = parse_quota_segment(segment) else {
+                return style_prompt_text_with(ctx, segment, PromptTone::Muted);
+            };
+            let left_percent = digits.parse::<i64>().unwrap_or(0).clamp(0, 100);
+            let tone =
+                prompt_tone_from_quota_tone(quota_tone_from_left_percent(left_percent as f64));
+            let reset_rendered = reset_suffix
+                .map(|suffix| style_prompt_text_with(ctx, suffix, PromptTone::Muted))
+                .unwrap_or_default();
+            format!(
+                "{} {}{}",
+                style_prompt_text_with(ctx, label, PromptTone::Muted),
+                style_prompt_text_with(ctx, &format!("{left_percent}%"), tone),
+                reset_rendered
+            )
+        })
+        .collect();
+
+    join_styled_segments_with(ctx, &rendered)
+}
+
+/// TS `styleQuotaSummary(summary)` — live context.
+pub fn style_quota_summary(summary: &str) -> String {
+    style_quota_summary_with(&StyleContext::live(), summary)
+}
+
+/// Render the per-account health line printed by `codex-multi-auth check`.
+///
+/// `check` is the only caller, and unlike the dashboard rows and account menu
+/// it prints one account per line with no width pressure, so it opts into the
+/// absolute reset clock for each quota window.
+pub fn format_quota_snapshot_for_dashboard(
+    snapshot: &CodexQuotaSnapshot,
+    settings: &DashboardDisplaySettings,
+    now: i64,
+) -> String {
+    if !settings.show_quota_details {
+        return "live session OK".to_string();
+    }
+    format!(
+        "live session OK ({})",
+        format_compact_quota_snapshot(
+            snapshot,
+            now,
+            &CompactQuotaFormatOptions { show_reset: true }
+        )
+    )
+}
+
+/// TS `quotaCacheEntryToSnapshot(entry)` — maps exactly the snapshot fields.
+pub fn quota_cache_entry_to_snapshot(entry: &QuotaCacheEntry) -> CodexQuotaSnapshot {
+    let window = |w: &QuotaCacheWindow| CodexQuotaWindow {
+        used_percent: w.used_percent,
+        window_minutes: w.window_minutes.map(|m| m as i64),
+        reset_at_ms: w.reset_at_ms.map(|r| r as i64),
+    };
+    CodexQuotaSnapshot {
+        status: entry.status as u16,
+        plan_type: entry.plan_type.clone(),
+        active_limit: None,
+        primary: window(&entry.primary),
+        secondary: window(&entry.secondary),
+        model: entry.model.clone(),
+    }
+}
+
+/// TS private `formatCompactQuotaWindowLabel(windowMinutes)`.
+fn format_compact_quota_window_label(window_minutes: Option<f64>) -> String {
+    let Some(m) = window_minutes else {
+        return "quota".to_string();
+    };
+    // TS `!windowMinutes` — 0 (and NaN) is falsy.
+    if m == 0.0 || !m.is_finite() || m <= 0.0 {
+        return "quota".to_string();
+    }
+    if m % 1440.0 == 0.0 {
+        return format!("{}d", format_js_number(m / 1440.0));
+    }
+    if m % 60.0 == 0.0 {
+        return format!("{}h", format_js_number(m / 60.0));
+    }
+    format!("{}m", format_js_number(m))
+}
+
+/// Options shared by the compact quota formatters (TS
+/// `CompactQuotaFormatOptions`). `show_reset` is opt-in so space-constrained
+/// surfaces keep their single-line width while `check` appends reset clocks.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct CompactQuotaFormatOptions {
+    pub show_reset: bool,
+}
+
+/// TS private `formatCompactQuotaPart`.
+fn format_compact_quota_part(
+    window_minutes: Option<f64>,
+    used_percent: Option<f64>,
+    reset_at_ms: Option<f64>,
+    options: &CompactQuotaFormatOptions,
+    now: i64,
+) -> Option<String> {
+    let label = format_compact_quota_window_label(window_minutes);
+    let used = used_percent?;
+    if !used.is_finite() {
+        return None;
+    }
+    let left = quota_left_percent_from_used(Some(used))?;
+    let part = format!("{label} {left}%");
+    if !options.show_reset {
+        return Some(part);
+    }
+    // A missing or malformed reset timestamp must never drop the percentage.
+    let reset_ms = reset_at_ms.filter(|r| r.is_finite()).map(|r| r as i64);
+    match format_quota_reset_at(reset_ms, Some(now)) {
+        Some(reset) => Some(format!("{part}, resets {reset}")),
+        None => Some(part),
+    }
+}
+
+/// Exhaustion probe for a snapshot: the TS code passes the snapshot (which
+/// has no `updatedAt`) straight into `isQuotaCacheEntryExhausted`; `NaN`
+/// reproduces the `undefined` staleness-escape suppression.
+fn snapshot_is_exhausted(snapshot: &CodexQuotaSnapshot, now: i64) -> bool {
+    let window = |w: &CodexQuotaWindow| QuotaCacheWindow {
+        used_percent: w.used_percent,
+        window_minutes: w.window_minutes.map(|m| m as f64),
+        reset_at_ms: w.reset_at_ms.map(|r| r as f64),
+    };
+    let entry = QuotaCacheEntry {
+        updated_at: f64::NAN,
+        status: f64::from(snapshot.status),
+        model: snapshot.model.clone(),
+        plan_type: snapshot.plan_type.clone(),
+        primary: window(&snapshot.primary),
+        secondary: window(&snapshot.secondary),
+    };
+    is_quota_cache_entry_exhausted(Some(&entry), now)
+}
+
+/// TS `formatCompactQuotaSnapshot(snapshot, now, options)`.
+pub fn format_compact_quota_snapshot(
+    snapshot: &CodexQuotaSnapshot,
+    now: i64,
+    options: &CompactQuotaFormatOptions,
+) -> String {
+    let mut parts: Vec<String> = [
+        format_compact_quota_part(
+            snapshot.primary.window_minutes.map(|m| m as f64),
+            snapshot.primary.used_percent,
+            snapshot.primary.reset_at_ms.map(|r| r as f64),
+            options,
+            now,
+        ),
+        format_compact_quota_part(
+            snapshot.secondary.window_minutes.map(|m| m as f64),
+            snapshot.secondary.used_percent,
+            snapshot.secondary.reset_at_ms.map(|r| r as f64),
+            options,
+            now,
+        ),
+    ]
+    .into_iter()
+    .flatten()
+    .filter(|part| !part.is_empty())
+    .collect();
+    if snapshot.status == 429 {
+        parts.push("rate-limited".to_string());
+    }
+    if snapshot_is_exhausted(snapshot, now) {
+        parts.push("quota-exhausted".to_string());
+    }
+    if !parts.is_empty() {
+        return parts.join(" | ");
+    }
+    format_quota_snapshot_line(snapshot)
+}
+
+/// TS `formatAccountQuotaSummary(entry, now, options)`.
+pub fn format_account_quota_summary(
+    entry: &QuotaCacheEntry,
+    now: i64,
+    options: &CompactQuotaFormatOptions,
+) -> String {
+    let mut parts: Vec<String> = [
+        format_compact_quota_part(
+            entry.primary.window_minutes,
+            entry.primary.used_percent,
+            entry.primary.reset_at_ms,
+            options,
+            now,
+        ),
+        format_compact_quota_part(
+            entry.secondary.window_minutes,
+            entry.secondary.used_percent,
+            entry.secondary.reset_at_ms,
+            options,
+            now,
+        ),
+    ]
+    .into_iter()
+    .flatten()
+    .filter(|part| !part.is_empty())
+    .collect();
+    if entry.status == 429.0 {
+        parts.push("rate-limited".to_string());
+    }
+    if is_quota_cache_entry_exhausted(Some(entry), now) {
+        parts.push("quota-exhausted".to_string());
+    }
+    if !parts.is_empty() {
+        return parts.join(" | ");
+    }
+    format_quota_snapshot_line(&quota_cache_entry_to_snapshot(entry))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_config::dashboard_settings::default_dashboard_display_settings;
+    use cma_tui::runtime_options::get_ui_runtime_options;
+
+    fn plain_ctx() -> StyleContext {
+        StyleContext::new(get_ui_runtime_options(), false)
+    }
+
+    // Ported from test/codex-manager-formatters.test.ts ("quota formatters" +
+    // "compact quota reset timestamps"). Local-time expectations are derived
+    // from the same helper the formatter uses instead of hardcoding a zone.
+
+    // 2026-07-22T09:00 local; +2h stays on the same local day, +8d does not.
+    fn now_local() -> i64 {
+        use chrono::TimeZone;
+        chrono::Local
+            .with_ymd_and_hms(2026, 7, 22, 9, 0, 0)
+            .single()
+            .expect("valid local time")
+            .timestamp_millis()
+    }
+
+    fn snapshot(primary_reset: Option<i64>, secondary_reset: Option<i64>) -> CodexQuotaSnapshot {
+        CodexQuotaSnapshot {
+            status: 200,
+            plan_type: Some("plus".to_string()),
+            active_limit: None,
+            primary: CodexQuotaWindow {
+                used_percent: Some(0.0),
+                window_minutes: Some(300),
+                reset_at_ms: primary_reset,
+            },
+            secondary: CodexQuotaWindow {
+                used_percent: Some(7.0),
+                window_minutes: Some(10080),
+                reset_at_ms: secondary_reset,
+            },
+            model: "gpt-5.3-codex".to_string(),
+        }
+    }
+
+    #[test]
+    fn style_quota_summary_keeps_segments_and_clamps() {
+        let ctx = plain_ctx();
+        assert_eq!(
+            style_quota_summary_with(&ctx, "5h 80% | weekly 15%"),
+            "5h 80% | weekly 15%"
+        );
+        assert_eq!(
+            style_quota_summary_with(&ctx, "rate-limited until 18:00"),
+            "rate-limited until 18:00"
+        );
+        // \d{1,3} admits values over 100; the formatter clamps them
+        assert_eq!(style_quota_summary_with(&ctx, "5h 150%"), "5h 100%");
+        assert_eq!(style_quota_summary_with(&ctx, "   "), "   ");
+        assert_eq!(
+            style_quota_summary_with(&ctx, "no percent here"),
+            "no percent here"
+        );
+    }
+
+    #[test]
+    fn style_quota_summary_tones_segments_with_reset_suffix() {
+        let ctx = plain_ctx();
+        assert_eq!(
+            style_quota_summary_with(&ctx, "5h 80%, resets 14:05 | 7d 15%"),
+            "5h 80%, resets 14:05 | 7d 15%"
+        );
+        assert_eq!(
+            style_quota_summary_with(&ctx, "7d 150%, resets 14:05 on Jul 29"),
+            "7d 100%, resets 14:05 on Jul 29"
+        );
+        // A trailing "resets" with no value is not a reset suffix.
+        assert_eq!(
+            style_quota_summary_with(&ctx, "5h 80%, resets"),
+            "5h 80%, resets"
+        );
+    }
+
+    #[test]
+    fn quota_cache_entry_to_snapshot_maps_exactly_the_snapshot_fields() {
+        let entry = QuotaCacheEntry {
+            updated_at: 123.0,
+            status: 200.0,
+            model: "gpt-5.3-codex".to_string(),
+            plan_type: Some("plus".to_string()),
+            primary: QuotaCacheWindow {
+                used_percent: Some(20.0),
+                window_minutes: Some(300.0),
+                reset_at_ms: Some(1000.0),
+            },
+            secondary: QuotaCacheWindow {
+                used_percent: Some(5.0),
+                window_minutes: Some(10080.0),
+                reset_at_ms: Some(2000.0),
+            },
+        };
+        let snapshot = quota_cache_entry_to_snapshot(&entry);
+        assert_eq!(snapshot.status, 200);
+        assert_eq!(snapshot.plan_type.as_deref(), Some("plus"));
+        assert_eq!(snapshot.model, "gpt-5.3-codex");
+        assert_eq!(snapshot.active_limit, None);
+        assert_eq!(snapshot.primary.used_percent, Some(20.0));
+        assert_eq!(snapshot.primary.window_minutes, Some(300));
+        assert_eq!(snapshot.primary.reset_at_ms, Some(1000));
+        assert_eq!(snapshot.secondary.window_minutes, Some(10080));
+        assert_eq!(snapshot.secondary.reset_at_ms, Some(2000));
+    }
+
+    #[test]
+    fn omits_reset_times_unless_the_caller_opts_in() {
+        let now = now_local();
+        let same_day = now + 2 * 60 * 60 * 1000;
+        let next_week = now + 8 * 24 * 60 * 60 * 1000;
+        assert_eq!(
+            format_compact_quota_snapshot(
+                &snapshot(Some(same_day), Some(next_week)),
+                now,
+                &CompactQuotaFormatOptions::default()
+            ),
+            "5h 100% | 7d 93%"
+        );
+    }
+
+    #[test]
+    fn appends_a_per_window_reset_time_when_show_reset_is_set() {
+        let now = now_local();
+        let same_day = now + 2 * 60 * 60 * 1000;
+        let next_week = now + 8 * 24 * 60 * 60 * 1000;
+        let expected = format!(
+            "5h 100%, resets {} | 7d 93%, resets {}",
+            format_quota_reset_at(Some(same_day), Some(now)).unwrap(),
+            format_quota_reset_at(Some(next_week), Some(now)).unwrap(),
+        );
+        assert_eq!(
+            format_compact_quota_snapshot(
+                &snapshot(Some(same_day), Some(next_week)),
+                now,
+                &CompactQuotaFormatOptions { show_reset: true }
+            ),
+            expected
+        );
+    }
+
+    #[test]
+    fn keeps_the_percentage_when_a_reset_timestamp_is_missing() {
+        let now = now_local();
+        assert_eq!(
+            format_compact_quota_snapshot(
+                &snapshot(None, None),
+                now,
+                &CompactQuotaFormatOptions { show_reset: true }
+            ),
+            "5h 100% | 7d 93%"
+        );
+    }
+
+    #[test]
+    fn format_account_quota_summary_honors_show_reset_the_same_way() {
+        let now = now_local();
+        let same_day = now + 2 * 60 * 60 * 1000;
+        let entry = QuotaCacheEntry {
+            updated_at: now as f64,
+            status: 200.0,
+            model: "gpt-5.3-codex".to_string(),
+            plan_type: Some("plus".to_string()),
+            primary: QuotaCacheWindow {
+                used_percent: Some(0.0),
+                window_minutes: Some(300.0),
+                reset_at_ms: Some(same_day as f64),
+            },
+            secondary: QuotaCacheWindow {
+                used_percent: Some(7.0),
+                window_minutes: Some(10080.0),
+                reset_at_ms: None,
+            },
+        };
+        assert_eq!(
+            format_account_quota_summary(&entry, now, &CompactQuotaFormatOptions::default()),
+            "5h 100% | 7d 93%"
+        );
+        assert_eq!(
+            format_account_quota_summary(
+                &entry,
+                now,
+                &CompactQuotaFormatOptions { show_reset: true }
+            ),
+            format!(
+                "5h 100%, resets {} | 7d 93%",
+                format_quota_reset_at(Some(same_day), Some(now)).unwrap()
+            )
+        );
+    }
+
+    #[test]
+    fn format_quota_snapshot_for_dashboard_is_the_check_line_and_shows_resets() {
+        let now = now_local();
+        let same_day = now + 2 * 60 * 60 * 1000;
+        let next_week = now + 8 * 24 * 60 * 60 * 1000;
+        let display = default_dashboard_display_settings();
+        assert!(display.show_quota_details);
+        assert_eq!(
+            format_quota_snapshot_for_dashboard(
+                &snapshot(Some(same_day), Some(next_week)),
+                &display,
+                now
+            ),
+            format!(
+                "live session OK (5h 100%, resets {} | 7d 93%, resets {})",
+                format_quota_reset_at(Some(same_day), Some(now)).unwrap(),
+                format_quota_reset_at(Some(next_week), Some(now)).unwrap(),
+            )
+        );
+    }
+
+    #[test]
+    fn format_quota_snapshot_for_dashboard_stays_bare_when_details_off() {
+        let now = now_local();
+        let mut display = default_dashboard_display_settings();
+        display.show_quota_details = false;
+        assert_eq!(
+            format_quota_snapshot_for_dashboard(&snapshot(Some(now), Some(now)), &display, now),
+            "live session OK"
+        );
+    }
+
+    #[test]
+    fn rate_limited_and_exhausted_markers_are_appended() {
+        let now = now_local();
+        let mut s = snapshot(None, None);
+        s.status = 429;
+        assert_eq!(
+            format_compact_quota_snapshot(&s, now, &CompactQuotaFormatOptions::default()),
+            "5h 100% | 7d 93% | rate-limited"
+        );
+        // Fully-used primary window with a future reset => quota-exhausted.
+        let mut exhausted = snapshot(Some(now + 60_000), None);
+        exhausted.primary.used_percent = Some(100.0);
+        assert_eq!(
+            format_compact_quota_snapshot(&exhausted, now, &CompactQuotaFormatOptions::default()),
+            "5h 0% | 7d 93% | quota-exhausted"
+        );
+    }
+
+    #[test]
+    fn window_label_uses_duration_derived_units() {
+        assert_eq!(format_compact_quota_window_label(Some(300.0)), "5h");
+        assert_eq!(format_compact_quota_window_label(Some(10080.0)), "7d");
+        assert_eq!(format_compact_quota_window_label(Some(43200.0)), "30d");
+        assert_eq!(format_compact_quota_window_label(Some(90.0)), "90m");
+        assert_eq!(format_compact_quota_window_label(Some(0.0)), "quota");
+        assert_eq!(format_compact_quota_window_label(None), "quota");
+    }
+}
diff --git a/crates/manager/src/formatters/text_style.rs b/crates/manager/src/formatters/text_style.rs
new file mode 100644
index 000000000..167b4c1be
--- /dev/null
+++ b/crates/manager/src/formatters/text_style.rs
@@ -0,0 +1,460 @@
+//! Port of `lib/codex-manager/formatters/text-style.ts`.
+//!
+//! `stylePromptText` reads `process.stdout.isTTY` and the process-global UI
+//! runtime options live. To keep every styled formatter testable without a
+//! TTY, the styling core is a pure function over a [`StyleContext`]; the
+//! TS-named wrappers sample the live environment exactly like the TS module.
+
+use std::io::IsTerminal;
+
+use cma_core::json_io::stringify_compact;
+use cma_tui::ansi;
+use cma_tui::format::{UiTextTone, paint_ui_text};
+use cma_tui::runtime_options::{UiRuntimeOptions, get_ui_runtime_options};
+use serde_json::Value;
+
+/// TS `PromptTone = "accent" | "success" | "warning" | "danger" | "muted"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PromptTone {
+    Accent,
+    Success,
+    Warning,
+    Danger,
+    Muted,
+}
+
+impl PromptTone {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            PromptTone::Accent => "accent",
+            PromptTone::Success => "success",
+            PromptTone::Warning => "warning",
+            PromptTone::Danger => "danger",
+            PromptTone::Muted => "muted",
+        }
+    }
+}
+
+/// The live inputs `stylePromptText` sampled implicitly in TS
+/// (`process.stdout.isTTY` + `getUiRuntimeOptions()`), captured explicitly so
+/// formatters stay pure functions returning `String` (testable without a TTY).
+#[derive(Clone, Debug)]
+pub struct StyleContext {
+    pub ui: UiRuntimeOptions,
+    pub is_tty: bool,
+}
+
+impl StyleContext {
+    /// Sample the live process state (what the TS module did on every call).
+    pub fn live() -> Self {
+        StyleContext {
+            ui: get_ui_runtime_options(),
+            is_tty: std::io::stdout().is_terminal(),
+        }
+    }
+
+    pub fn new(ui: UiRuntimeOptions, is_tty: bool) -> Self {
+        StyleContext { ui, is_tty }
+    }
+}
+
+/// TS `stylePromptText(text, tone)` over an explicit context.
+pub fn style_prompt_text_with(ctx: &StyleContext, text: &str, tone: PromptTone) -> String {
+    if !ctx.is_tty {
+        return text.to_string();
+    }
+    let ui = &ctx.ui;
+    if ui.v2_enabled {
+        if tone == PromptTone::Muted {
+            return format!(
+                "{}{}{}",
+                ui.theme.colors.dim,
+                paint_ui_text(ui, text, UiTextTone::Muted),
+                ui.theme.colors.reset
+            );
+        }
+        let mapped = match tone {
+            PromptTone::Accent => UiTextTone::Primary,
+            PromptTone::Success => UiTextTone::Success,
+            PromptTone::Warning => UiTextTone::Warning,
+            PromptTone::Danger => UiTextTone::Danger,
+            // Handled above; kept exhaustive for the compiler.
+            PromptTone::Muted => UiTextTone::Muted,
+        };
+        return paint_ui_text(ui, text, mapped);
+    }
+    let legacy_code = match tone {
+        PromptTone::Accent | PromptTone::Success => ansi::GREEN,
+        PromptTone::Warning => ansi::YELLOW,
+        PromptTone::Danger => ansi::RED,
+        PromptTone::Muted => ansi::DIM,
+    };
+    format!("{legacy_code}{text}{}", ansi::RESET)
+}
+
+/// TS `stylePromptText(text, tone)` — live stdout-TTY + UI runtime sampling.
+pub fn style_prompt_text(text: &str, tone: PromptTone) -> String {
+    style_prompt_text_with(&StyleContext::live(), text, tone)
+}
+
+/// JS `\s` includes U+FEFF, which Rust's `char::is_whitespace` does not.
+fn is_js_whitespace(c: char) -> bool {
+    c.is_whitespace() || c == '\u{feff}'
+}
+
+/// TS `collapseWhitespace(value)` — `value.replace(/\s+/g, " ").trim()`.
+pub fn collapse_whitespace(value: &str) -> String {
+    let mut out = String::with_capacity(value.len());
+    let mut in_run = false;
+    for c in value.chars() {
+        if is_js_whitespace(c) {
+            if !in_run {
+                out.push(' ');
+                in_run = true;
+            }
+        } else {
+            out.push(c);
+            in_run = false;
+        }
+    }
+    out.trim_matches(' ').to_string()
+}
+
+/// TS `formatReasonLabel(reason)` — `_` → space, collapse, `None` when empty.
+pub fn format_reason_label(reason: Option<&str>) -> Option<String> {
+    let reason = reason?;
+    if reason.is_empty() {
+        return None;
+    }
+    let normalized = collapse_whitespace(&reason.replace('_', " "));
+    if normalized.is_empty() {
+        None
+    } else {
+        Some(normalized)
+    }
+}
+
+/// TS `extractErrorMessageFromPayload(payload)`.
+pub fn extract_error_message_from_payload(payload: &Value) -> Option<String> {
+    let record = payload.as_object()?;
+
+    let direct_message = record
+        .get("message")
+        .and_then(Value::as_str)
+        .map(collapse_whitespace)
+        .unwrap_or_default();
+    let direct_code = record
+        .get("code")
+        .and_then(Value::as_str)
+        .map(collapse_whitespace)
+        .unwrap_or_default();
+    if !direct_message.is_empty() {
+        if !direct_code.is_empty()
+            && !direct_message
+                .to_lowercase()
+                .contains(&direct_code.to_lowercase())
+        {
+            return Some(format!("{direct_message} [{direct_code}]"));
+        }
+        return Some(direct_message);
+    }
+
+    match record.get("error") {
+        Some(nested) if nested.is_object() => extract_error_message_from_payload(nested),
+        _ => None,
+    }
+}
+
+/// TS `parseStructuredErrorMessage(raw)` — try the trimmed string and the
+/// first `{` … last `}` slice as JSON, returning the first payload message.
+pub fn parse_structured_error_message(raw: &str) -> Option<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let mut candidates: Vec<&str> = vec![trimmed];
+    if let (Some(first_brace), Some(last_brace)) = (trimmed.find('{'), trimmed.rfind('}'))
+        && last_brace > first_brace
+    {
+        let slice = &trimmed[first_brace..=last_brace];
+        if slice != trimmed {
+            candidates.push(slice);
+        }
+    }
+
+    for candidate in candidates {
+        if let Ok(parsed) = serde_json::from_str::<Value>(candidate)
+            && let Some(message) = extract_error_message_from_payload(&parsed)
+        {
+            return Some(message);
+        }
+    }
+    None
+}
+
+/// TS `normalizeFailureDetail(message, reason)`.
+///
+/// Length bound: the TS `.length`/`.slice` operate on UTF-16 units; this port
+/// counts Unicode scalar values (identical for the ASCII detail strings that
+/// actually flow through here).
+pub fn normalize_failure_detail(message: Option<&str>, reason: Option<&str>) -> String {
+    let reason_label = format_reason_label(reason);
+    let trimmed_message = message.map(str::trim).unwrap_or_default();
+    let raw: String = if !trimmed_message.is_empty() {
+        trimmed_message.to_string()
+    } else if let Some(label) = reason_label {
+        label
+    } else {
+        "refresh failed".to_string()
+    };
+    let structured = parse_structured_error_message(&raw);
+    let normalized = collapse_whitespace(structured.as_deref().unwrap_or(&raw));
+    let char_count = normalized.chars().count();
+    let bounded = if char_count > 260 {
+        let prefix: String = normalized.chars().take(257).collect();
+        format!("{prefix}...")
+    } else {
+        normalized
+    };
+    if bounded.is_empty() {
+        "refresh failed".to_string()
+    } else {
+        bounded
+    }
+}
+
+/// TS `joinStyledSegments(parts)` over an explicit context.
+pub fn join_styled_segments_with(ctx: &StyleContext, parts: &[String]) -> String {
+    if parts.is_empty() {
+        return String::new();
+    }
+    let separator = style_prompt_text_with(ctx, " | ", PromptTone::Muted);
+    parts.join(&separator)
+}
+
+/// TS `joinStyledSegments(parts)` — live context.
+pub fn join_styled_segments(parts: &[String]) -> String {
+    join_styled_segments_with(&StyleContext::live(), parts)
+}
+
+/// One `formatResultSummary` segment (TS `{ text, tone }`).
+#[derive(Clone, Debug)]
+pub struct ResultSegment {
+    pub text: String,
+    pub tone: PromptTone,
+}
+
+impl ResultSegment {
+    pub fn new(text: impl Into<String>, tone: PromptTone) -> Self {
+        ResultSegment {
+            text: text.into(),
+            tone,
+        }
+    }
+}
+
+/// TS `formatResultSummary(segments)` over an explicit context.
+pub fn format_result_summary_with(ctx: &StyleContext, segments: &[ResultSegment]) -> String {
+    let rendered: Vec<String> = segments
+        .iter()
+        .map(|segment| style_prompt_text_with(ctx, &segment.text, segment.tone))
+        .collect();
+    format!(
+        "{} {}",
+        style_prompt_text_with(ctx, "Result:", PromptTone::Accent),
+        join_styled_segments_with(ctx, &rendered)
+    )
+}
+
+/// TS `formatResultSummary(segments)` — live context.
+pub fn format_result_summary(segments: &[ResultSegment]) -> String {
+    format_result_summary_with(&StyleContext::live(), segments)
+}
+
+/// TS `stringifyLogArgs(args)` — strings pass through raw, everything else is
+/// `JSON.stringify`-ed. (The TS cyclic-object fallback to `String(value)` is
+/// unreachable here: `serde_json::Value` cannot be cyclic.)
+pub fn stringify_log_args(args: &[Value]) -> String {
+    args.iter()
+        .map(|value| match value {
+            Value::String(s) => s.clone(),
+            other => stringify_compact(other),
+        })
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_tui::runtime_options::{
+        UiRuntimeOptionsPatch, reset_ui_runtime_options, set_ui_runtime_options,
+    };
+    use serde_json::json;
+    use serial_test::serial;
+
+    fn plain_ctx() -> StyleContext {
+        // Non-TTY: stylePromptText is a passthrough, matching the vitest runs.
+        StyleContext::new(get_ui_runtime_options(), false)
+    }
+
+    // Ported from test/codex-manager-formatters.test.ts ("text-style formatters").
+
+    #[test]
+    fn collapse_whitespace_flattens_runs_and_trims() {
+        assert_eq!(collapse_whitespace("  a\t\n b   c "), "a b c");
+        assert_eq!(collapse_whitespace("\n\t "), "");
+    }
+
+    #[test]
+    fn format_reason_label_humanizes_snake_case_and_drops_empties() {
+        assert_eq!(
+            format_reason_label(Some("invalid_grant")).as_deref(),
+            Some("invalid grant")
+        );
+        assert_eq!(
+            format_reason_label(Some("  rate__limited  ")).as_deref(),
+            Some("rate limited")
+        );
+        assert_eq!(format_reason_label(Some("")), None);
+        assert_eq!(format_reason_label(None), None);
+        assert_eq!(format_reason_label(Some("___")), None);
+    }
+
+    #[test]
+    fn extract_error_message_reads_direct_coded_and_nested_shapes() {
+        assert_eq!(
+            extract_error_message_from_payload(&json!({"message": "token  expired"})).as_deref(),
+            Some("token expired")
+        );
+        assert_eq!(
+            extract_error_message_from_payload(
+                &json!({"message": "token expired", "code": "invalid_grant"})
+            )
+            .as_deref(),
+            Some("token expired [invalid_grant]")
+        );
+        assert_eq!(
+            extract_error_message_from_payload(
+                &json!({"message": "Invalid_Grant: token expired", "code": "invalid_grant"})
+            )
+            .as_deref(),
+            Some("Invalid_Grant: token expired")
+        );
+        assert_eq!(
+            extract_error_message_from_payload(
+                &json!({"error": {"error": {"message": "deeply nested"}}})
+            )
+            .as_deref(),
+            Some("deeply nested")
+        );
+        assert_eq!(extract_error_message_from_payload(&Value::Null), None);
+        assert_eq!(extract_error_message_from_payload(&json!("string")), None);
+        assert_eq!(
+            extract_error_message_from_payload(&json!({"code": "only_code"})),
+            None
+        );
+    }
+
+    #[test]
+    fn parse_structured_error_message_finds_json_embedded_in_prose() {
+        assert_eq!(
+            parse_structured_error_message("{\"error\":{\"message\":\"quota hit\"}}").as_deref(),
+            Some("quota hit")
+        );
+        assert_eq!(
+            parse_structured_error_message(
+                "refresh failed: {\"message\":\"server says no\"} (status 400)"
+            )
+            .as_deref(),
+            Some("server says no")
+        );
+        assert_eq!(parse_structured_error_message("plain text failure"), None);
+        assert_eq!(parse_structured_error_message("   "), None);
+    }
+
+    #[test]
+    fn normalize_failure_detail_prefers_message_falls_back_and_bounds() {
+        assert_eq!(
+            normalize_failure_detail(Some("boom"), Some("invalid_grant")),
+            "boom"
+        );
+        assert_eq!(
+            normalize_failure_detail(None, Some("invalid_grant")),
+            "invalid grant"
+        );
+        assert_eq!(normalize_failure_detail(None, None), "refresh failed");
+        assert_eq!(
+            normalize_failure_detail(Some("  "), Some("")),
+            "refresh failed"
+        );
+        assert_eq!(
+            normalize_failure_detail(Some("{\"error\":{\"message\":\"unwrapped\"}}"), None),
+            "unwrapped"
+        );
+        let long = "x".repeat(300);
+        let bounded = normalize_failure_detail(Some(&long), None);
+        assert_eq!(bounded.chars().count(), 260);
+        assert!(bounded.ends_with("..."));
+    }
+
+    #[test]
+    #[serial]
+    fn join_and_result_summary_render_plain_in_non_tty() {
+        let ctx = plain_ctx();
+        assert_eq!(join_styled_segments_with(&ctx, &[]), "");
+        assert_eq!(
+            join_styled_segments_with(&ctx, &["a".to_string(), "b".to_string()]),
+            "a | b"
+        );
+        assert_eq!(
+            format_result_summary_with(
+                &ctx,
+                &[
+                    ResultSegment::new("saved", PromptTone::Success),
+                    ResultSegment::new("synced", PromptTone::Muted),
+                ]
+            ),
+            "Result: saved | synced"
+        );
+    }
+
+    #[test]
+    fn stringify_log_args_serializes_mixed_args() {
+        assert_eq!(
+            stringify_log_args(&[json!("msg"), json!({"a": 1})]),
+            "msg {\"a\":1}"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn legacy_tones_use_exact_ansi_codes_on_tty() {
+        let ui = set_ui_runtime_options(UiRuntimeOptionsPatch {
+            v2_enabled: Some(false),
+            ..Default::default()
+        });
+        let ctx = StyleContext::new(ui, true);
+        assert_eq!(
+            style_prompt_text_with(&ctx, "x", PromptTone::Danger),
+            format!("{}x{}", ansi::RED, ansi::RESET)
+        );
+        assert_eq!(
+            style_prompt_text_with(&ctx, "x", PromptTone::Warning),
+            format!("{}x{}", ansi::YELLOW, ansi::RESET)
+        );
+        assert_eq!(
+            style_prompt_text_with(&ctx, "x", PromptTone::Accent),
+            format!("{}x{}", ansi::GREEN, ansi::RESET)
+        );
+        assert_eq!(
+            style_prompt_text_with(&ctx, "x", PromptTone::Success),
+            format!("{}x{}", ansi::GREEN, ansi::RESET)
+        );
+        assert_eq!(
+            style_prompt_text_with(&ctx, "x", PromptTone::Muted),
+            format!("{}x{}", ansi::DIM, ansi::RESET)
+        );
+        reset_ui_runtime_options();
+    }
+}
diff --git a/crates/manager/src/health_check.rs b/crates/manager/src/health_check.rs
new file mode 100644
index 000000000..c14244367
--- /dev/null
+++ b/crates/manager/src/health_check.rs
@@ -0,0 +1,745 @@
+//! Port of `lib/codex-manager/health-check.ts` — the `check` command body,
+//! reused by the login dashboard's quick check / deep check actions.
+//!
+//! Behavior source: spec 09 §2. Contracts:
+//! - quick path (`!forceRefresh && hasUsableAccessToken`) RE-ENABLES a
+//!   disabled account (counts as a change);
+//! - refresh FAILURE never disables an account (that's `fix`'s job); a
+//!   still-valid session downgrades the failure to a warning row;
+//! - quick vs full check have NO re-base asymmetry: both paths save the
+//!   whole in-memory storage via `saveAccountsWithRetry` (NOT a
+//!   transaction);
+//! - quota-cache saves are best-effort (`console.warn`, never fatal);
+//! - the active account is mirrored into Codex CLI auth only when it was
+//!   refreshed/validated during this run.
+
+use cma_cli_mirror::writer::ActiveSelection;
+use cma_config::dashboard_settings::{
+    DashboardDisplaySettings, default_dashboard_display_settings,
+};
+use cma_core::errors::CodexError;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::schemas::token::TokenResult;
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::cache::QuotaCacheData;
+use cma_quota::probe::{
+    CODEX_UNAVAILABLE_PROBE_NOTE, CodexQuotaSnapshot, ProbeCodexQuotaOptions,
+    fetch_codex_quota_snapshot,
+};
+use cma_quota::readiness::build_quota_email_fallback_state;
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{
+    BoxFuture, LoadAccountsFn, SaveAccountsFn, default_load_accounts, default_save_accounts,
+    save_accounts_with_retry_boxed,
+};
+use crate::formatters::account::style_account_detail_text_with_tone;
+use crate::formatters::model::{format_model_inspection, inspect_requested_model};
+use crate::formatters::quota::format_quota_snapshot_for_dashboard;
+use crate::formatters::text_style::{
+    PromptTone, ResultSegment, format_result_summary, normalize_failure_detail, style_prompt_text,
+};
+use crate::quota_cache_helpers::DEFAULT_LIVE_PROBE_MODEL;
+use crate::repair::fix::QuotaProbeRequest;
+
+/// TS `HealthCheckOptions`.
+#[derive(Clone, Debug, Default)]
+pub struct HealthCheckOptions {
+    pub force_refresh: bool,
+    pub live_probe: bool,
+    pub model: Option<String>,
+    pub display: Option<DashboardDisplaySettings>,
+}
+
+/// Injectable I/O bundle (the TS module imports these directly; tests mock
+/// the modules).
+pub struct HealthCheckDeps {
+    pub load_accounts: LoadAccountsFn,
+    pub save_accounts: SaveAccountsFn,
+    pub queued_refresh: Box<dyn Fn(String) -> BoxFuture<TokenResult> + Send + Sync>,
+    pub fetch_codex_quota_snapshot: Box<
+        dyn Fn(QuotaProbeRequest) -> BoxFuture<Result<CodexQuotaSnapshot, CodexError>>
+            + Send
+            + Sync,
+    >,
+    pub load_quota_cache: Box<dyn Fn() -> BoxFuture<QuotaCacheData> + Send + Sync>,
+    pub save_quota_cache:
+        Box<dyn Fn(QuotaCacheData) -> BoxFuture<Result<(), CodexError>> + Send + Sync>,
+    pub set_codex_cli_active_selection:
+        Box<dyn Fn(ActiveSelection) -> BoxFuture<bool> + Send + Sync>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+}
+
+impl Default for HealthCheckDeps {
+    fn default() -> Self {
+        HealthCheckDeps {
+            load_accounts: default_load_accounts(),
+            save_accounts: default_save_accounts(),
+            queued_refresh: Box::new(|refresh_token| {
+                Box::pin(
+                    async move { cma_auth::refresh_queue::queued_refresh(&refresh_token).await },
+                )
+            }),
+            fetch_codex_quota_snapshot: Box::new(|request| {
+                Box::pin(async move {
+                    fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+                        account_id: request.account_id,
+                        access_token: request.access_token,
+                        model: Some(request.model),
+                        ..Default::default()
+                    })
+                    .await
+                })
+            }),
+            load_quota_cache: Box::new(|| Box::pin(cma_quota::cache::load_quota_cache())),
+            save_quota_cache: Box::new(|cache| {
+                Box::pin(async move {
+                    cma_quota::cache::save_quota_cache(&cache).await;
+                    Ok(())
+                })
+            }),
+            set_codex_cli_active_selection: Box::new(|selection| {
+                Box::pin(async move {
+                    cma_cli_mirror::writer::set_codex_cli_active_selection(&selection).await
+                })
+            }),
+            get_now: None,
+        }
+    }
+}
+
+impl HealthCheckDeps {
+    fn now(&self) -> i64 {
+        match &self.get_now {
+            Some(get_now) => get_now(),
+            None => cma_core::utils::now_ms(),
+        }
+    }
+}
+
+/// The `check` command seam (`run_check_command_via` expects
+/// `fn(bool) -> Future<()>`); always a live probe.
+pub async fn run_health_check(live_probe: bool) {
+    let mut out = CliOut::stdio();
+    let options = HealthCheckOptions {
+        live_probe,
+        ..Default::default()
+    };
+    run_health_check_with_deps(&options, &HealthCheckDeps::default(), &mut out).await;
+}
+
+/// TS `runHealthCheck(options)` — options entry, reused by the login
+/// dashboard quick/deep check actions (output captured through `out`).
+pub async fn run_health_check_with(options: HealthCheckOptions, out: &mut CliOut) {
+    run_health_check_with_deps(&options, &HealthCheckDeps::default(), out).await;
+}
+
+/// DI core of [`run_health_check_with`].
+pub async fn run_health_check_with_deps(
+    options: &HealthCheckOptions,
+    deps: &HealthCheckDeps,
+    out: &mut CliOut,
+) {
+    let force_refresh = options.force_refresh;
+    let live_probe = options.live_probe;
+    let probe_model = options
+        .model
+        .as_deref()
+        .map(str::trim)
+        .filter(|model| !model.is_empty())
+        .unwrap_or(DEFAULT_LIVE_PROBE_MODEL);
+    let model_inspection = inspect_requested_model(probe_model);
+    let display = options
+        .display
+        .clone()
+        .unwrap_or_else(default_dashboard_display_settings);
+    let mut working_quota_cache: Option<QuotaCacheData> = if live_probe {
+        Some((deps.load_quota_cache)().await)
+    } else {
+        None
+    };
+    let mut quota_cache_changed = false;
+    cma_storage::facade::set_storage_path(None);
+    let mut storage: AccountStorageV3 = match (deps.load_accounts)().await {
+        Some(storage) if !storage.accounts.is_empty() => storage,
+        _ => {
+            out.info("No accounts configured.");
+            return;
+        }
+    };
+    let mut quota_email_fallback_state = if live_probe {
+        Some(build_quota_email_fallback_state(&storage.accounts))
+    } else {
+        None
+    };
+
+    let mut changed = false;
+    let mut ok = 0usize;
+    let mut failed = 0usize;
+    let mut warnings = 0usize;
+    let mut codex_available = 0usize;
+    let mut signed_in_only = 0usize;
+    let active_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    let mut active_account_refreshed = false;
+    let now = deps.now();
+    out.info(style_prompt_text(
+        &if force_refresh {
+            format!(
+                "Checking {} account(s) with full refresh test...",
+                storage.accounts.len()
+            )
+        } else {
+            format!(
+                "Checking {} account(s) with quick check{}...",
+                storage.accounts.len(),
+                if live_probe { " + live check" } else { "" }
+            )
+        },
+        PromptTone::Accent,
+    ));
+    if live_probe {
+        out.info(style_prompt_text(
+            &format!("Model probe: {}", format_model_inspection(&model_inspection)),
+            PromptTone::Muted,
+        ));
+    }
+    for i in 0..storage.accounts.len() {
+        let label = crate::repair::fix::account_label(&storage.accounts[i], i);
+        let label_text = style_prompt_text(&label, PromptTone::Accent);
+        let session_likely_valid =
+            crate::login::account_credentials::has_usable_access_token(&storage.accounts[i], now);
+        if !force_refresh && session_likely_valid {
+            if storage.accounts[i].enabled == Some(false) {
+                storage.accounts[i].enabled = Some(true);
+                changed = true;
+            }
+            if i == active_index {
+                active_account_refreshed = true;
+            }
+            let mut health_detail = "signed in and working".to_string();
+            let mut health_tone = PromptTone::Success;
+            if live_probe {
+                let current_access_token = storage.accounts[i].access_token.clone();
+                let probe_account_id = current_access_token.as_ref().and_then(|token| {
+                    storage.accounts[i]
+                        .account_id
+                        .clone()
+                        .or_else(|| extract_account_id(Some(token)))
+                });
+                match (probe_account_id, current_access_token) {
+                    (Some(probe_account_id), Some(current_access_token)) => {
+                        match (deps.fetch_codex_quota_snapshot)(QuotaProbeRequest {
+                            account_id: probe_account_id,
+                            access_token: current_access_token,
+                            model: model_inspection.normalized.clone(),
+                        })
+                        .await
+                        {
+                            Ok(snapshot) => {
+                                if let Some(working) = &mut working_quota_cache {
+                                    quota_cache_changed =
+                                        crate::quota_cache_helpers::update_quota_cache_for_account(
+                                            working,
+                                            &storage.accounts[i],
+                                            &snapshot,
+                                            &storage.accounts,
+                                            quota_email_fallback_state.as_ref(),
+                                        ) || quota_cache_changed;
+                                }
+                                health_detail = format_quota_snapshot_for_dashboard(
+                                    &snapshot,
+                                    &display,
+                                    cma_core::utils::now_ms(),
+                                );
+                                codex_available += 1;
+                            }
+                            Err(error) => {
+                                warnings += 1;
+                                signed_in_only += 1;
+                                health_tone = PromptTone::Warning;
+                                if error.is_codex_unavailable() {
+                                    health_detail =
+                                        format!("signed in; {CODEX_UNAVAILABLE_PROBE_NOTE}");
+                                } else {
+                                    let message = normalize_failure_detail(
+                                        Some(error.message()),
+                                        None,
+                                    );
+                                    health_detail =
+                                        format!("signed in (live check failed: {message})");
+                                }
+                            }
+                        }
+                    }
+                    _ => {
+                        warnings += 1;
+                        signed_in_only += 1;
+                        health_tone = PromptTone::Warning;
+                        health_detail =
+                            "signed in (live check skipped: missing account ID)".to_string();
+                    }
+                }
+            }
+            if crate::login::account_credentials::has_likely_invalid_refresh_token(Some(
+                &storage.accounts[i].refresh_token,
+            )) {
+                health_detail.push_str(" (re-login suggested soon)");
+            }
+            ok += 1;
+            if display.show_per_account_rows {
+                let health_marker = if health_tone == PromptTone::Success {
+                    "✓"
+                } else {
+                    "!"
+                };
+                out.info(format!(
+                    "  {} {} {} {}",
+                    style_prompt_text(health_marker, health_tone),
+                    label_text,
+                    style_prompt_text("|", PromptTone::Muted),
+                    style_account_detail_text_with_tone(&health_detail, health_tone),
+                ));
+            }
+            continue;
+        }
+        let result = (deps.queued_refresh)(storage.accounts[i].refresh_token.clone()).await;
+        match result {
+            TokenResult::Success(success) => {
+                let token_account_id = extract_account_id(Some(&success.access));
+                let next_email = sanitize_email(
+                    extract_account_email(Some(&success.access), success.id_token.as_deref())
+                        .as_deref(),
+                );
+                let previous_email = storage.accounts[i].email.clone();
+                let mut account_identity_changed = false;
+                {
+                    let account = &mut storage.accounts[i];
+                    if account.refresh_token != success.refresh {
+                        account.refresh_token = success.refresh.clone();
+                        changed = true;
+                    }
+                    if account.access_token.as_deref() != Some(success.access.as_str()) {
+                        account.access_token = Some(success.access.clone());
+                        changed = true;
+                    }
+                    if account.expires_at != Some(success.expires) {
+                        account.expires_at = Some(success.expires);
+                        changed = true;
+                    }
+                    if let Some(next_email_value) = &next_email
+                        && account.email.as_deref() != Some(next_email_value.as_str())
+                    {
+                        account.email = Some(next_email_value.clone());
+                        changed = true;
+                        account_identity_changed = true;
+                    }
+                    if crate::login::account_credentials::apply_token_account_identity(
+                        account,
+                        token_account_id.as_deref(),
+                    ) {
+                        changed = true;
+                        account_identity_changed = true;
+                    }
+                    if account.enabled == Some(false) {
+                        account.enabled = Some(true);
+                        changed = true;
+                    }
+                }
+                if account_identity_changed && live_probe && working_quota_cache.is_some() {
+                    let next_state = build_quota_email_fallback_state(&storage.accounts);
+                    if let Some(working) = &mut working_quota_cache {
+                        quota_cache_changed =
+                            crate::quota_cache_helpers::prune_unsafe_quota_email_cache_entry(
+                                working,
+                                previous_email.as_deref(),
+                                &storage.accounts,
+                                &next_state,
+                            ) || quota_cache_changed;
+                    }
+                    quota_email_fallback_state = Some(next_state);
+                }
+                storage.accounts[i].last_used = deps.now();
+                if i == active_index {
+                    active_account_refreshed = true;
+                }
+                ok += 1;
+                let mut healthy_message = "working now".to_string();
+                let mut healthy_tone = PromptTone::Success;
+                if live_probe {
+                    let probe_account_id = storage.accounts[i]
+                        .account_id
+                        .clone()
+                        .or_else(|| token_account_id.clone());
+                    match probe_account_id {
+                        Some(probe_account_id) => {
+                            match (deps.fetch_codex_quota_snapshot)(QuotaProbeRequest {
+                                account_id: probe_account_id,
+                                access_token: success.access.clone(),
+                                model: model_inspection.normalized.clone(),
+                            })
+                            .await
+                            {
+                                Ok(snapshot) => {
+                                    if let Some(working) = &mut working_quota_cache {
+                                        quota_cache_changed = crate::quota_cache_helpers::update_quota_cache_for_account(
+                                            working,
+                                            &storage.accounts[i],
+                                            &snapshot,
+                                            &storage.accounts,
+                                            quota_email_fallback_state.as_ref(),
+                                        ) || quota_cache_changed;
+                                    }
+                                    healthy_message = format_quota_snapshot_for_dashboard(
+                                        &snapshot,
+                                        &display,
+                                        cma_core::utils::now_ms(),
+                                    );
+                                    codex_available += 1;
+                                }
+                                Err(error) => {
+                                    warnings += 1;
+                                    signed_in_only += 1;
+                                    healthy_tone = PromptTone::Warning;
+                                    if error.is_codex_unavailable() {
+                                        healthy_message =
+                                            format!("signed in; {CODEX_UNAVAILABLE_PROBE_NOTE}");
+                                    } else {
+                                        let message = normalize_failure_detail(
+                                            Some(error.message()),
+                                            None,
+                                        );
+                                        healthy_message =
+                                            format!("signed in (live check failed: {message})");
+                                    }
+                                }
+                            }
+                        }
+                        None => {
+                            warnings += 1;
+                            signed_in_only += 1;
+                            healthy_tone = PromptTone::Warning;
+                            healthy_message =
+                                "signed in (live check skipped: missing account ID)".to_string();
+                        }
+                    }
+                }
+                if display.show_per_account_rows {
+                    let healthy_marker = if healthy_tone == PromptTone::Success {
+                        "✓"
+                    } else {
+                        "!"
+                    };
+                    out.info(format!(
+                        "  {} {} {} {}",
+                        style_prompt_text(healthy_marker, healthy_tone),
+                        label_text,
+                        style_prompt_text("|", PromptTone::Muted),
+                        style_account_detail_text_with_tone(&healthy_message, healthy_tone),
+                    ));
+                }
+            }
+            TokenResult::Failed(failure) => {
+                let detail = normalize_failure_detail(
+                    failure.message.as_deref(),
+                    failure.reason.map(|reason| reason.as_str()),
+                );
+                if session_likely_valid {
+                    warnings += 1;
+                    if live_probe {
+                        signed_in_only += 1;
+                    }
+                    if display.show_per_account_rows {
+                        out.info(format!(
+                            "  {} {} {} {}",
+                            style_prompt_text("!", PromptTone::Warning),
+                            label_text,
+                            style_prompt_text("|", PromptTone::Muted),
+                            style_prompt_text(
+                                &format!(
+                                    "refresh failed ({detail}) but this account still works right now"
+                                ),
+                                PromptTone::Warning
+                            ),
+                        ));
+                    }
+                } else {
+                    failed += 1;
+                    if display.show_per_account_rows {
+                        out.info(format!(
+                            "  {} {} {} {}",
+                            style_prompt_text("✗", PromptTone::Danger),
+                            label_text,
+                            style_prompt_text("|", PromptTone::Muted),
+                            style_prompt_text(&detail, PromptTone::Danger),
+                        ));
+                    }
+                }
+            }
+        }
+    }
+
+    if !display.show_per_account_rows {
+        out.info(style_prompt_text(
+            "Per-account lines are hidden in dashboard settings.",
+            PromptTone::Muted,
+        ));
+    }
+    if quota_cache_changed
+        && let Some(working) = &working_quota_cache
+        && let Err(error) = (deps.save_quota_cache)(working.clone()).await
+    {
+        // Quota cache is a derived artifact; a transient Windows EBUSY/EPERM
+        // here must not abort the health check before account fixes commit.
+        out.warn(format!("Quota cache save failed: {}", error.message()));
+    }
+
+    if changed
+        && let Err(error) = save_accounts_with_retry_boxed(&storage, &deps.save_accounts).await
+    {
+        // TS lets the exhausted-retry rejection propagate; the Rust surface
+        // reports it on stderr instead of panicking.
+        out.error(error.message().to_string());
+        return;
+    }
+
+    if active_account_refreshed && active_index < storage.accounts.len() {
+        let active_account = &storage.accounts[active_index];
+        (deps.set_codex_cli_active_selection)(ActiveSelection {
+            account_id: active_account.account_id.clone(),
+            email: active_account.email.clone(),
+            access_token: active_account.access_token.clone(),
+            refresh_token: Some(active_account.refresh_token.clone()),
+            expires_at: active_account.expires_at.map(|value| value as f64),
+            id_token: None,
+        })
+        .await;
+    }
+
+    out.info("");
+    out.info(format_result_summary(&if live_probe {
+        vec![
+            ResultSegment::new(
+                format!("{codex_available} Codex available"),
+                if codex_available > 0 {
+                    PromptTone::Success
+                } else {
+                    PromptTone::Muted
+                },
+            ),
+            ResultSegment::new(
+                format!("{signed_in_only} signed in only"),
+                if signed_in_only > 0 {
+                    PromptTone::Warning
+                } else {
+                    PromptTone::Muted
+                },
+            ),
+            ResultSegment::new(
+                format!("{failed} need re-login"),
+                if failed > 0 {
+                    PromptTone::Danger
+                } else {
+                    PromptTone::Muted
+                },
+            ),
+        ]
+    } else {
+        vec![
+            ResultSegment::new(format!("{ok} working"), PromptTone::Success),
+            ResultSegment::new(
+                format!("{failed} need re-login"),
+                if failed > 0 {
+                    PromptTone::Danger
+                } else {
+                    PromptTone::Muted
+                },
+            ),
+            ResultSegment::new(
+                format!("{warnings} warning{}", if warnings == 1 { "" } else { "s" }),
+                if warnings > 0 {
+                    PromptTone::Warning
+                } else {
+                    PromptTone::Muted
+                },
+            ),
+        ]
+    }));
+}
+
+// ============================================================================
+// Tests — ported from test/health-check.test.ts (core paths)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_core::schemas::token::{TokenFailure, TokenSuccess};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    fn usable_account(refresh: &str, now: i64) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.access_token = Some("access".to_string());
+        // Usable = expiresAt - now > 5 minutes.
+        account.expires_at = Some(now + 10 * 60 * 1000);
+        account
+    }
+
+    fn deps_with(
+        refresh: impl Fn(String) -> TokenResult + Send + Sync + 'static,
+        refresh_calls: Arc<AtomicUsize>,
+    ) -> HealthCheckDeps {
+        HealthCheckDeps {
+            queued_refresh: Box::new(move |token| {
+                refresh_calls.fetch_add(1, Ordering::SeqCst);
+                let result = refresh(token);
+                Box::pin(async move { result })
+            }),
+            get_now: Some(Box::new(|| 1_000_000)),
+            ..HealthCheckDeps::default()
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_accounts_prints_message() {
+        let _sandbox = EnvSandbox::new();
+        let deps = HealthCheckDeps::default();
+        let mut out = CliOut::capture();
+        run_health_check_with_deps(&HealthCheckOptions::default(), &deps, &mut out).await;
+        assert_eq!(out.info_text(), "No accounts configured.");
+    }
+
+    // Quick check: a usable token skips the refresh entirely and counts as
+    // working.
+    #[tokio::test]
+    #[serial(env)]
+    async fn quick_check_skips_refresh_for_usable_tokens() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(usable_account("rt-a", 1_000_000));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let refresh_calls = Arc::new(AtomicUsize::new(0));
+        let deps = deps_with(
+            |_| {
+                TokenResult::Failed(TokenFailure {
+                    reason: None,
+                    status_code: None,
+                    message: Some("should not be called".to_string()),
+                })
+            },
+            Arc::clone(&refresh_calls),
+        );
+        let mut out = CliOut::capture();
+        run_health_check_with_deps(&HealthCheckOptions::default(), &deps, &mut out).await;
+        assert_eq!(refresh_calls.load(Ordering::SeqCst), 0);
+        let text = out.info_text();
+        assert!(text.starts_with("Checking 1 account(s) with quick check..."));
+        assert!(text.contains("signed in and working"));
+        assert!(text.contains("1 working"));
+        assert!(text.contains("0 need re-login"));
+        assert!(text.contains("0 warnings"));
+    }
+
+    // Full refresh failure NEVER disables the account (fix's job) and the
+    // singular "warning" form renders for exactly one warning.
+    #[tokio::test]
+    #[serial(env)]
+    async fn full_refresh_failure_does_not_disable_account() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage
+            .accounts
+            .push(AccountMetadataV3::new("rt-expired", 1, 1));
+        storage.accounts.push(usable_account("rt-b", 1_000_000));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let refresh_calls = Arc::new(AtomicUsize::new(0));
+        let deps = deps_with(
+            |_| {
+                TokenResult::Failed(TokenFailure {
+                    reason: None,
+                    status_code: Some(400),
+                    message: Some("invalid_grant".to_string()),
+                })
+            },
+            Arc::clone(&refresh_calls),
+        );
+        let mut out = CliOut::capture();
+        run_health_check_with_deps(
+            &HealthCheckOptions {
+                force_refresh: true,
+                ..Default::default()
+            },
+            &deps,
+            &mut out,
+        )
+        .await;
+        // Both accounts hit the refresh path under forceRefresh.
+        assert_eq!(refresh_calls.load(Ordering::SeqCst), 2);
+        let text = out.info_text();
+        assert!(text.starts_with("Checking 2 account(s) with full refresh test..."));
+        // Expired-session failure → danger row; still-valid session → the
+        // downgraded warning row.
+        assert!(text.contains("but this account still works right now"));
+        assert!(text.contains("1 need re-login"));
+        assert!(text.contains("1 warning"));
+        assert!(!text.contains("1 warnings"));
+        // No account was disabled or otherwise persisted.
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts[0].enabled, None);
+        assert_eq!(saved.accounts[1].enabled, None);
+    }
+
+    // Quick path re-enables a disabled-but-usable account and persists.
+    #[tokio::test]
+    #[serial(env)]
+    async fn quick_check_re_enables_working_disabled_accounts() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        let mut disabled = usable_account("rt-a", 1_000_000);
+        disabled.enabled = Some(false);
+        storage.accounts.push(disabled);
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let refresh_calls = Arc::new(AtomicUsize::new(0));
+        let deps = deps_with(
+            |_| {
+                TokenResult::Success(TokenSuccess {
+                    access: "unused".to_string(),
+                    refresh: "unused".to_string(),
+                    expires: 1,
+                    id_token: None,
+                    multi_account: None,
+                })
+            },
+            Arc::clone(&refresh_calls),
+        );
+        let mut out = CliOut::capture();
+        run_health_check_with_deps(&HealthCheckOptions::default(), &deps, &mut out).await;
+        assert_eq!(refresh_calls.load(Ordering::SeqCst), 0);
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts[0].enabled, Some(true));
+    }
+}
diff --git a/crates/manager/src/help.rs b/crates/manager/src/help.rs
new file mode 100644
index 000000000..4d82f708b
--- /dev/null
+++ b/crates/manager/src/help.rs
@@ -0,0 +1,442 @@
+//! Port of `lib/codex-manager/help.ts` — usage text + the `login`/`best`
+//! flag parsers. All user-visible strings are copy-exact from the TS source
+//! (clap never generates help/errors for this CLI — spec 08 / ARCHITECTURE
+//! §6.15 clap policy).
+
+use cma_core::model_family::DEFAULT_PROBE_MODEL;
+
+use crate::dispatcher::CliOut;
+
+/// TS `DEFAULT_LIVE_PROBE_MODEL = DEFAULT_PROBE_MODEL`.
+pub const DEFAULT_LIVE_PROBE_MODEL: &str = DEFAULT_PROBE_MODEL;
+
+/// The full `printUsage()` text (one string, joined with `\n`, exactly as the
+/// TS single `console.log` call emits it).
+pub fn usage_text() -> String {
+    [
+        "Codex Multi-Auth CLI",
+        "",
+        "Start here:",
+        "  codex-multi-auth login [--device-auth|--manual|--no-browser] [--org <org_id>]",
+        "  codex-multi-auth status [--json]   (list is the same command)",
+        "  codex-multi-auth check            (always live-probes)",
+        "",
+        "Daily use:",
+        "  codex-multi-auth list [--json]",
+        "  codex-multi-auth switch <index>   (pins the account for runtime routing)",
+        "  codex-multi-auth unpin            (clears the manual pin set by switch)",
+        "  codex-multi-auth workspace <account> [workspace]   (list or switch an account's workspaces)",
+        "  codex-multi-auth best [--live] [--json] [--model <model>]   (clears any manual pin set by switch)",
+        "  codex-multi-auth forecast [--live] [--json] [--explain] [--model <model>] [--no-runtime-overlay]",
+        "  codex-multi-auth account tag|untag|weight|pause|unpause|drain|undrain|note|policy list ...",
+        "",
+        "Repair:",
+        "  codex-multi-auth uninstall [--dry-run] [--json] [--clear-accounts]",
+        "  codex-multi-auth verify-flagged [--dry-run|-n] [--json] [--no-restore]",
+        "  codex-multi-auth verify [--paths | --flagged | --all] [--json]",
+        "  codex-multi-auth fix [--dry-run|-n] [--json] [--live] [--model <model>]",
+        "  codex-multi-auth doctor [--json] [--fix] [--dry-run|-n]   (--dry-run requires --fix)",
+        "",
+        "Diagnostics:",
+        "  codex-multi-auth usage [--since <time|duration>] [--by <group>] [--json|--csv] [--out <path>]",
+        "  codex-multi-auth usage rotate [--if-larger-than-bytes <n>] [--json]",
+        "  codex-multi-auth budget limit <key> --window <hour|day|week|month> [--requests N] [--tokens N] [--cost USD]",
+        "  codex-multi-auth budget check|list [--json]",
+        "  codex-multi-auth bridge token create|list|rotate|revoke [--json]",
+        "  codex-multi-auth integrations [--kind <name>] [--base-url <url>] [--model <model>] [--json]",
+        "  codex-multi-auth models [--json] [--model <model>]",
+        "  codex-multi-auth monitor [--json]",
+        "  codex-multi-auth rotation <enable|disable|status|bind-app|unbind-app|reset-runtime>",
+        "  codex-multi-auth rotation reset-rate-limits [--all | --account <idx>] [--dry-run] [--json]",
+        "  codex-multi-auth why-selected [--now|-n | --last|-l] [--json]",
+        "  codex-multi-auth history [list|show <id>] [--json]   (all local sessions, ignores /resume provider filtering)",
+        "",
+        "Advanced:",
+        "  codex-multi-auth report [--live] [--json] [--explain] [--model <model>] [--max-accounts <n>] [--max-probes <n>] [--cached-only] [--out <path>]",
+        "  codex-multi-auth config explain [--json]",
+        "  codex-multi-auth config template|init-config [modern|legacy|minimal] [--write <path>] [--stdout]",
+        "  codex-multi-auth debug bundle [--json]",
+        "  codex-multi-auth features   (partial built-in checklist; see docs/features.md for the full product map)",
+        "",
+        "Notes:",
+        "  - Uses ~/.codex/multi-auth/openai-codex-accounts.json",
+        "  - Syncs active account into Codex CLI auth state",
+    ]
+    .join("\n")
+        + "\n  - Default live probe model: "
+        + DEFAULT_LIVE_PROBE_MODEL
+        + "\n  - See docs/reference/commands.md for the full command and flag matrix"
+}
+
+/// TS `printUsage()` — a single stdout line-group.
+pub fn print_usage(out: &mut CliOut) {
+    out.info(usage_text());
+}
+
+/// TS `AuthLoginOptions`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AuthLoginOptions {
+    pub manual: bool,
+    pub device_auth: bool,
+    pub org: Option<String>,
+}
+
+/// TS `ParsedAuthLoginArgs` discriminated union.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ParsedAuthLoginArgs {
+    Ok(AuthLoginOptions),
+    Help,
+    Error(String),
+}
+
+/// TS `parseAuthLoginArgs(args)`.
+pub fn parse_auth_login_args(args: &[String]) -> ParsedAuthLoginArgs {
+    let mut options = AuthLoginOptions::default();
+    let mut manual_flags: Vec<&str> = Vec::new();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--manual" || arg == "--no-browser" {
+            options.manual = true;
+            if !manual_flags.contains(&arg) {
+                manual_flags.push(if arg == "--manual" {
+                    "--manual"
+                } else {
+                    "--no-browser"
+                });
+            }
+            i += 1;
+            continue;
+        }
+        if arg == "--device-auth" {
+            options.device_auth = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--org" || arg.starts_with("--org=") {
+            // Bind this login to a specific workspace/org id (issue #491).
+            let value: Option<String> = if arg == "--org" {
+                let next = args.get(i + 1).cloned();
+                i += 1;
+                next
+            } else {
+                Some(arg["--org=".len()..].to_string())
+            };
+            let trimmed = value.as_deref().map(str::trim).unwrap_or("");
+            if trimmed.is_empty() || trimmed.starts_with("--") {
+                return ParsedAuthLoginArgs::Error(
+                    "Missing value for --org. Usage: codex-multi-auth login --org <org_id>"
+                        .to_string(),
+                );
+            }
+            options.org = Some(trimmed.to_string());
+            i += 1;
+            continue;
+        }
+        if arg == "--help" || arg == "-h" {
+            return ParsedAuthLoginArgs::Help;
+        }
+        return ParsedAuthLoginArgs::Error(format!("Unknown login option: {arg}"));
+    }
+
+    if options.device_auth && options.manual {
+        let conflict = if manual_flags.is_empty() {
+            "--manual".to_string()
+        } else {
+            manual_flags.join(" or ")
+        };
+        return ParsedAuthLoginArgs::Error(format!("Cannot combine --device-auth with {conflict}"));
+    }
+
+    ParsedAuthLoginArgs::Ok(options)
+}
+
+/// TS `BestCliOptions`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BestCliOptions {
+    pub live: bool,
+    pub json: bool,
+    pub model: String,
+    pub model_provided: bool,
+}
+
+impl Default for BestCliOptions {
+    fn default() -> Self {
+        BestCliOptions {
+            live: false,
+            json: false,
+            model: DEFAULT_LIVE_PROBE_MODEL.to_string(),
+            model_provided: false,
+        }
+    }
+}
+
+/// TS `ParsedBestArgs` discriminated union.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ParsedBestArgs {
+    Ok(BestCliOptions),
+    Help,
+    Error(String),
+}
+
+/// The `printBestUsage()` text (identical in help.ts and commands/best.ts).
+pub fn best_usage_text() -> String {
+    [
+        "Usage:",
+        "  codex-multi-auth best [--live] [--json] [--model <model>]",
+        "",
+        "Options:",
+        "  --live, -l         Probe live quota headers via Codex backend before switching",
+        "  --json, -j         Print machine-readable JSON output",
+    ]
+    .join("\n")
+        + &format!("\n  --model, -m        Probe model for live mode (default: {DEFAULT_LIVE_PROBE_MODEL})")
+        + "\n"
+        + &[
+            "",
+            "Behavior:",
+            "  - Chooses the healthiest account using forecast scoring",
+            "  - Switches to the recommended account when it is not already active",
+        ]
+        .join("\n")
+}
+
+/// TS `printBestUsage()`.
+pub fn print_best_usage(out: &mut CliOut) {
+    out.info(best_usage_text());
+}
+
+/// TS help.ts `parseBestArgs(args)` — this variant treats `--help`/`-h` as a
+/// first-class `Help` result (the copy in commands/best.ts does not; its
+/// caller pre-checks `--help`).
+pub fn parse_best_args(args: &[String]) -> ParsedBestArgs {
+    let mut options = BestCliOptions::default();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--help" || arg == "-h" {
+            return ParsedBestArgs::Help;
+        }
+        if arg == "--live" || arg == "-l" {
+            options.live = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--json" || arg == "-j" {
+            options.json = true;
+            i += 1;
+            continue;
+        }
+        if arg == "--model" || arg == "-m" {
+            let value = args.get(i + 1).map(|v| v.trim().to_string());
+            match value {
+                Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                    options.model = v;
+                    options.model_provided = true;
+                    i += 2;
+                    continue;
+                }
+                _ => return ParsedBestArgs::Error("Missing value for --model".to_string()),
+            }
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                return ParsedBestArgs::Error("Missing value for --model".to_string());
+            }
+            options.model = value.to_string();
+            options.model_provided = true;
+            i += 1;
+            continue;
+        }
+        return ParsedBestArgs::Error(format!("Unknown option: {arg}"));
+    }
+
+    ParsedBestArgs::Ok(options)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    // Port of test/codex-manager-help.test.ts.
+
+    #[test]
+    fn parses_login_flags() {
+        assert_eq!(
+            parse_auth_login_args(&args(&["--manual"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: true,
+                device_auth: false,
+                org: None,
+            })
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--no-browser"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: true,
+                device_auth: false,
+                org: None,
+            })
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--device-auth"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: false,
+                device_auth: true,
+                org: None,
+            })
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--help"])),
+            ParsedAuthLoginArgs::Help
+        );
+    }
+
+    #[test]
+    fn parses_org_to_bind_a_workspace_491() {
+        assert_eq!(
+            parse_auth_login_args(&args(&["--org", "org-BBBB"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: false,
+                device_auth: false,
+                org: Some("org-BBBB".to_string()),
+            })
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--org=org-AAAA"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: false,
+                device_auth: false,
+                org: Some("org-AAAA".to_string()),
+            })
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--manual", "--org", "org-BBBB"])),
+            ParsedAuthLoginArgs::Ok(AuthLoginOptions {
+                manual: true,
+                device_auth: false,
+                org: Some("org-BBBB".to_string()),
+            })
+        );
+    }
+
+    #[test]
+    fn reports_a_missing_org_value_491() {
+        let expected = ParsedAuthLoginArgs::Error(
+            "Missing value for --org. Usage: codex-multi-auth login --org <org_id>".to_string(),
+        );
+        assert_eq!(parse_auth_login_args(&args(&["--org"])), expected);
+        assert_eq!(
+            parse_auth_login_args(&args(&["--org", "--manual"])),
+            expected
+        );
+    }
+
+    #[test]
+    fn reports_login_parser_errors_explicitly() {
+        assert_eq!(
+            parse_auth_login_args(&args(&["--bogus"])),
+            ParsedAuthLoginArgs::Error("Unknown login option: --bogus".to_string())
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--device-auth", "--manual"])),
+            ParsedAuthLoginArgs::Error("Cannot combine --device-auth with --manual".to_string())
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--no-browser", "--device-auth"])),
+            ParsedAuthLoginArgs::Error(
+                "Cannot combine --device-auth with --no-browser".to_string()
+            )
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--device-auth", "--no-browser"])),
+            ParsedAuthLoginArgs::Error(
+                "Cannot combine --device-auth with --no-browser".to_string()
+            )
+        );
+        assert_eq!(
+            parse_auth_login_args(&args(&["--device-auth", "--manual", "--no-browser"])),
+            ParsedAuthLoginArgs::Error(
+                "Cannot combine --device-auth with --manual or --no-browser".to_string()
+            )
+        );
+    }
+
+    #[test]
+    fn parses_best_args_and_treats_help_as_first_class() {
+        assert_eq!(
+            parse_best_args(&args(&[])),
+            ParsedBestArgs::Ok(BestCliOptions {
+                live: false,
+                json: false,
+                model: DEFAULT_PROBE_MODEL.to_string(),
+                model_provided: false,
+            })
+        );
+        assert_eq!(
+            parse_best_args(&args(&["--live", "--json", "--model", "gpt-5"])),
+            ParsedBestArgs::Ok(BestCliOptions {
+                live: true,
+                json: true,
+                model: "gpt-5".to_string(),
+                model_provided: true,
+            })
+        );
+        assert_eq!(parse_best_args(&args(&["-h"])), ParsedBestArgs::Help);
+    }
+
+    #[test]
+    fn renders_default_probe_model_in_best_usage() {
+        assert!(best_usage_text().contains(&format!("(default: {DEFAULT_PROBE_MODEL})")));
+    }
+
+    #[test]
+    fn reports_missing_model_values_and_unknown_flags() {
+        assert_eq!(
+            parse_best_args(&args(&["--model"])),
+            ParsedBestArgs::Error("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_best_args(&args(&["--bogus"])),
+            ParsedBestArgs::Error("Unknown option: --bogus".to_string())
+        );
+    }
+
+    #[test]
+    fn rejects_flag_like_value_after_model_instead_of_consuming_it() {
+        let missing = ParsedBestArgs::Error("Missing value for --model".to_string());
+        assert_eq!(parse_best_args(&args(&["--model", "--json"])), missing);
+        assert_eq!(parse_best_args(&args(&["--model", "--live"])), missing);
+        assert_eq!(parse_best_args(&args(&["--model=--json"])), missing);
+        assert_eq!(parse_best_args(&args(&["--model", "   "])), missing);
+        assert_eq!(parse_best_args(&args(&["-m", "--json"])), missing);
+        assert!(matches!(
+            parse_best_args(&args(&["-m", "gpt-5.5"])),
+            ParsedBestArgs::Ok(_)
+        ));
+    }
+
+    #[test]
+    fn usage_text_matches_frozen_lines() {
+        let text = usage_text();
+        assert!(text.starts_with("Codex Multi-Auth CLI\n"));
+        assert!(text.contains("\n  - Default live probe model: gpt-5.6-sol\n"));
+        assert!(
+            text.ends_with("  - See docs/reference/commands.md for the full command and flag matrix")
+        );
+        assert!(text.contains(
+            "  codex-multi-auth history [list|show <id>] [--json]   (all local sessions, ignores /resume provider filtering)"
+        ));
+    }
+}
diff --git a/crates/manager/src/integration_generators.rs b/crates/manager/src/integration_generators.rs
new file mode 100644
index 000000000..cefa376e7
--- /dev/null
+++ b/crates/manager/src/integration_generators.rs
@@ -0,0 +1,339 @@
+//! Port of `lib/integration-generators.ts` — static snippet generators
+//! (opencode/openclaw/python/curl/env) for the local rotation-proxy bridge.
+//!
+//! Snippet bodies are BYTE-EXACT contracts: env/curl/python end with a
+//! trailing newline; the two JSON snippets are bare `JSON.stringify(_, null,
+//! 2)` output (no trailing newline). The TS `switch` fell through to the
+//! OpenClaw snippet for unknown kinds; the Rust enum makes unknown kinds
+//! unrepresentable, so OpenClaw is simply the final arm.
+
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::DEFAULT_MODEL;
+use serde_json::json;
+
+const DEFAULT_BASE_URL: &str = "http://127.0.0.1:1456/v1";
+const DEFAULT_ENV_VAR: &str = "CODEX_MULTI_AUTH_LOCAL_KEY";
+
+/// TS `IntegrationSnippetKind`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum IntegrationSnippetKind {
+    Opencode,
+    Openclaw,
+    Python,
+    Curl,
+    Env,
+}
+
+impl IntegrationSnippetKind {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            IntegrationSnippetKind::Opencode => "opencode",
+            IntegrationSnippetKind::Openclaw => "openclaw",
+            IntegrationSnippetKind::Python => "python",
+            IntegrationSnippetKind::Curl => "curl",
+            IntegrationSnippetKind::Env => "env",
+        }
+    }
+
+    /// The TS union values (`"opencode" | "openclaw" | "python" | "curl" |
+    /// "env"`); anything else is not a kind (the TS type system enforced the
+    /// same).
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "opencode" => Some(IntegrationSnippetKind::Opencode),
+            "openclaw" => Some(IntegrationSnippetKind::Openclaw),
+            "python" => Some(IntegrationSnippetKind::Python),
+            "curl" => Some(IntegrationSnippetKind::Curl),
+            "env" => Some(IntegrationSnippetKind::Env),
+            _ => None,
+        }
+    }
+}
+
+/// TS default generation order.
+pub const DEFAULT_INTEGRATION_SNIPPET_KINDS: [IntegrationSnippetKind; 5] = [
+    IntegrationSnippetKind::Opencode,
+    IntegrationSnippetKind::Openclaw,
+    IntegrationSnippetKind::Python,
+    IntegrationSnippetKind::Curl,
+    IntegrationSnippetKind::Env,
+];
+
+/// TS `IntegrationSnippetInput`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct IntegrationSnippetInput {
+    pub base_url: Option<String>,
+    pub model: Option<String>,
+    pub env_var: Option<String>,
+}
+
+/// TS `IntegrationSnippet` — serializes as `{kind, title, body}` for the
+/// `integrations --json` output.
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
+pub struct IntegrationSnippet {
+    pub kind: IntegrationSnippetKind,
+    pub title: &'static str,
+    pub body: String,
+}
+
+struct NormalizedInput {
+    base_url: String,
+    model: String,
+    env_var: String,
+}
+
+/// TS `normalizeInput` — baseUrl: trim then strip ALL trailing `/`; each
+/// field falls back to its default when empty after trimming.
+fn normalize_input(input: &IntegrationSnippetInput) -> NormalizedInput {
+    let base_url = input
+        .base_url
+        .as_deref()
+        .map(|url| url.trim().trim_end_matches('/').to_string())
+        .filter(|url| !url.is_empty())
+        .unwrap_or_else(|| DEFAULT_BASE_URL.to_string());
+    let model = input
+        .model
+        .as_deref()
+        .map(|model| model.trim().to_string())
+        .filter(|model| !model.is_empty())
+        .unwrap_or_else(|| DEFAULT_MODEL.to_string());
+    let env_var = input
+        .env_var
+        .as_deref()
+        .map(|env_var| env_var.trim().to_string())
+        .filter(|env_var| !env_var.is_empty())
+        .unwrap_or_else(|| DEFAULT_ENV_VAR.to_string());
+    NormalizedInput {
+        base_url,
+        model,
+        env_var,
+    }
+}
+
+/// TS `generateIntegrationSnippet(kind, input)` — byte-exact bodies.
+pub fn generate_integration_snippet(
+    kind: IntegrationSnippetKind,
+    input: &IntegrationSnippetInput,
+) -> IntegrationSnippet {
+    let options = normalize_input(input);
+    match kind {
+        IntegrationSnippetKind::Env => IntegrationSnippet {
+            kind,
+            title: "Environment",
+            body: format!(
+                "{env_var}=cma_local_replace_me\nOPENAI_BASE_URL={base_url}\nOPENAI_API_KEY=${env_var}\n",
+                env_var = options.env_var,
+                base_url = options.base_url,
+            ),
+        },
+        IntegrationSnippetKind::Curl => IntegrationSnippet {
+            kind,
+            title: "curl",
+            body: [
+                format!("curl {}/responses \\", options.base_url),
+                format!("  -H \"Authorization: Bearer ${}\" \\", options.env_var),
+                "  -H \"Content-Type: application/json\" \\".to_string(),
+                format!(
+                    "  -d '{{\"model\":\"{}\",\"input\":\"Say hello from the local bridge.\"}}'",
+                    options.model
+                ),
+                String::new(),
+            ]
+            .join("\n"),
+        },
+        IntegrationSnippetKind::Python => IntegrationSnippet {
+            kind,
+            title: "Python",
+            body: [
+                "import os".to_string(),
+                "from openai import OpenAI".to_string(),
+                String::new(),
+                "client = OpenAI(".to_string(),
+                format!("    api_key=os.environ[\"{}\"],", options.env_var),
+                format!("    base_url=\"{}\",", options.base_url),
+                ")".to_string(),
+                String::new(),
+                "response = client.responses.create(".to_string(),
+                format!("    model=\"{}\",", options.model),
+                "    input=\"Say hello from the local bridge.\",".to_string(),
+                ")".to_string(),
+                "print(response.output_text)".to_string(),
+                String::new(),
+            ]
+            .join("\n"),
+        },
+        IntegrationSnippetKind::Opencode => IntegrationSnippet {
+            kind,
+            title: "OpenCode",
+            body: stringify_pretty2(&json!({
+                "provider": {
+                    "openai": {
+                        "options": {
+                            "apiKey": format!("${}", options.env_var),
+                            "baseURL": options.base_url,
+                        },
+                        "models": {
+                            (options.model.clone()): {
+                                "name": format!("{} via codex-multi-auth", options.model),
+                            },
+                        },
+                    },
+                },
+            })),
+        },
+        IntegrationSnippetKind::Openclaw => IntegrationSnippet {
+            kind,
+            title: "OpenClaw",
+            body: stringify_pretty2(&json!({
+                "providers": {
+                    "openai": {
+                        "apiKey": format!("${}", options.env_var),
+                        "baseURL": options.base_url,
+                        "defaultModel": options.model,
+                    },
+                },
+            })),
+        },
+    }
+}
+
+/// TS `generateIntegrationSnippets(kinds?, input?)` — maps in order; `None`
+/// kinds = the default 5-kind order.
+pub fn generate_integration_snippets(
+    kinds: Option<&[IntegrationSnippetKind]>,
+    input: &IntegrationSnippetInput,
+) -> Vec<IntegrationSnippet> {
+    kinds
+        .unwrap_or(&DEFAULT_INTEGRATION_SNIPPET_KINDS)
+        .iter()
+        .map(|kind| generate_integration_snippet(*kind, input))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Ported from test/integration-generators.test.ts + byte-exact body pins.
+
+    #[test]
+    fn generates_deterministic_snippets_using_the_local_key() {
+        let snippets = generate_integration_snippets(
+            None,
+            &IntegrationSnippetInput {
+                base_url: Some("http://127.0.0.1:1456/v1/".to_string()),
+                model: Some("gpt-5.3-codex".to_string()),
+                env_var: None,
+            },
+        );
+        let kinds: Vec<&str> = snippets.iter().map(|s| s.kind.as_str()).collect();
+        assert_eq!(kinds, vec!["opencode", "openclaw", "python", "curl", "env"]);
+        let combined: String = snippets
+            .iter()
+            .map(|s| s.body.as_str())
+            .collect::<Vec<_>>()
+            .join("\n");
+        assert!(combined.contains("CODEX_MULTI_AUTH_LOCAL_KEY"));
+        assert!(combined.contains("http://127.0.0.1:1456/v1"));
+        // trailing slash stripped (the env snippet pins the exact base URL)
+        assert!(combined.contains("OPENAI_BASE_URL=http://127.0.0.1:1456/v1\n"));
+        assert!(!combined.contains("OPENAI_BASE_URL=http://127.0.0.1:1456/v1/"));
+    }
+
+    #[test]
+    fn python_snippet_uses_responses_create() {
+        let snippet =
+            generate_integration_snippet(IntegrationSnippetKind::Python, &Default::default());
+        assert!(snippet.body.contains("client.responses.create"));
+        assert!(!snippet.body.contains("chat.completions"));
+    }
+
+    #[test]
+    fn env_snippet_is_byte_exact() {
+        let snippet =
+            generate_integration_snippet(IntegrationSnippetKind::Env, &Default::default());
+        assert_eq!(snippet.title, "Environment");
+        assert_eq!(
+            snippet.body,
+            "CODEX_MULTI_AUTH_LOCAL_KEY=cma_local_replace_me\nOPENAI_BASE_URL=http://127.0.0.1:1456/v1\nOPENAI_API_KEY=$CODEX_MULTI_AUTH_LOCAL_KEY\n"
+        );
+    }
+
+    #[test]
+    fn curl_snippet_is_byte_exact() {
+        let snippet =
+            generate_integration_snippet(IntegrationSnippetKind::Curl, &Default::default());
+        assert_eq!(snippet.title, "curl");
+        assert_eq!(
+            snippet.body,
+            format!(
+                "curl http://127.0.0.1:1456/v1/responses \\\n  -H \"Authorization: Bearer $CODEX_MULTI_AUTH_LOCAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{{\"model\":\"{DEFAULT_MODEL}\",\"input\":\"Say hello from the local bridge.\"}}'\n"
+            )
+        );
+    }
+
+    #[test]
+    fn python_snippet_is_byte_exact() {
+        let snippet =
+            generate_integration_snippet(IntegrationSnippetKind::Python, &Default::default());
+        assert_eq!(snippet.title, "Python");
+        assert_eq!(
+            snippet.body,
+            format!(
+                "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"CODEX_MULTI_AUTH_LOCAL_KEY\"],\n    base_url=\"http://127.0.0.1:1456/v1\",\n)\n\nresponse = client.responses.create(\n    model=\"{DEFAULT_MODEL}\",\n    input=\"Say hello from the local bridge.\",\n)\nprint(response.output_text)\n"
+            )
+        );
+    }
+
+    #[test]
+    fn opencode_snippet_is_pretty_json_without_trailing_newline() {
+        let snippet = generate_integration_snippet(
+            IntegrationSnippetKind::Opencode,
+            &IntegrationSnippetInput {
+                base_url: None,
+                model: Some("gpt-5.3-codex".to_string()),
+                env_var: None,
+            },
+        );
+        assert_eq!(snippet.title, "OpenCode");
+        assert_eq!(
+            snippet.body,
+            "{\n  \"provider\": {\n    \"openai\": {\n      \"options\": {\n        \"apiKey\": \"$CODEX_MULTI_AUTH_LOCAL_KEY\",\n        \"baseURL\": \"http://127.0.0.1:1456/v1\"\n      },\n      \"models\": {\n        \"gpt-5.3-codex\": {\n          \"name\": \"gpt-5.3-codex via codex-multi-auth\"\n        }\n      }\n    }\n  }\n}"
+        );
+        assert!(!snippet.body.ends_with('\n'));
+    }
+
+    #[test]
+    fn openclaw_snippet_is_pretty_json_without_trailing_newline() {
+        let snippet = generate_integration_snippet(
+            IntegrationSnippetKind::Openclaw,
+            &IntegrationSnippetInput {
+                base_url: None,
+                model: Some("gpt-5.3-codex".to_string()),
+                env_var: None,
+            },
+        );
+        assert_eq!(snippet.title, "OpenClaw");
+        assert_eq!(
+            snippet.body,
+            "{\n  \"providers\": {\n    \"openai\": {\n      \"apiKey\": \"$CODEX_MULTI_AUTH_LOCAL_KEY\",\n      \"baseURL\": \"http://127.0.0.1:1456/v1\",\n      \"defaultModel\": \"gpt-5.3-codex\"\n    }\n  }\n}"
+        );
+        assert!(!snippet.body.ends_with('\n'));
+    }
+
+    #[test]
+    fn normalize_input_strips_all_trailing_slashes_and_falls_back_when_empty() {
+        let snippet = generate_integration_snippet(
+            IntegrationSnippetKind::Env,
+            &IntegrationSnippetInput {
+                base_url: Some("http://localhost:9999///".to_string()),
+                model: Some("   ".to_string()),
+                env_var: Some("  MY_KEY  ".to_string()),
+            },
+        );
+        assert!(snippet.body.contains("OPENAI_BASE_URL=http://localhost:9999\n"));
+        assert!(snippet.body.starts_with("MY_KEY="));
+        assert!(snippet.body.contains("OPENAI_API_KEY=$MY_KEY\n"));
+    }
+}
diff --git a/crates/manager/src/lib.rs b/crates/manager/src/lib.rs
new file mode 100644
index 000000000..42cb1ac7c
--- /dev/null
+++ b/crates/manager/src/lib.rs
@@ -0,0 +1,16 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod commands;
+pub mod dispatcher;
+pub mod forecast_report_shared;
+pub mod formatters;
+pub mod health_check;
+pub mod help;
+pub mod integration_generators;
+pub mod login;
+pub mod oc_chatgpt;
+pub mod quota_cache_helpers;
+pub mod rate_limit_markers;
+pub mod registry;
+pub mod repair;
+pub mod settings;
+pub mod update_notice;
diff --git a/crates/manager/src/login/account_credentials.rs b/crates/manager/src/login/account_credentials.rs
new file mode 100644
index 000000000..4e15f10b5
--- /dev/null
+++ b/crates/manager/src/login/account_credentials.rs
@@ -0,0 +1,227 @@
+//! Port of `lib/codex-manager/account-credentials.ts` — token freshness and
+//! account-identity helpers shared by the manager CLI commands.
+
+use cma_core::schemas::account_storage::{AccountIdSource, AccountMetadataV3};
+use cma_core::token_utils::{resolve_request_account_id, should_update_account_id_from_token};
+
+/// `ACCESS_TOKEN_FRESH_WINDOW_MS` (private in TS; 300 000 ms).
+pub(crate) const ACCESS_TOKEN_FRESH_WINDOW_MS: i64 = 5 * 60 * 1000;
+
+/// `hasUsableAccessToken(account, now)` over a full account row.
+pub fn has_usable_access_token(account: &AccountMetadataV3, now: i64) -> bool {
+    has_usable_access_token_parts(account.access_token.as_deref(), account.expires_at, now)
+}
+
+/// `hasUsableAccessToken({accessToken, expiresAt}, now)` — token present AND
+/// `expiresAt` finite AND `expiresAt - now > 300_000` (a token expiring within
+/// 5 minutes counts as unusable). Pick-shaped variant for flagged rows.
+pub fn has_usable_access_token_parts(
+    access_token: Option<&str>,
+    expires_at: Option<i64>,
+    now: i64,
+) -> bool {
+    let Some(token) = access_token else {
+        return false;
+    };
+    if token.is_empty() {
+        return false;
+    }
+    let Some(expires_at) = expires_at else {
+        return false;
+    };
+    expires_at - now > ACCESS_TOKEN_FRESH_WINDOW_MS
+}
+
+/// `hasLikelyInvalidRefreshToken(refreshToken)` — missing → true; trimmed
+/// length < 20 → true; `"token-"` prefix (test/demo placeholder) → true.
+pub fn has_likely_invalid_refresh_token(refresh_token: Option<&str>) -> bool {
+    let Some(refresh_token) = refresh_token else {
+        return true;
+    };
+    if refresh_token.is_empty() {
+        return true;
+    }
+    let trimmed = refresh_token.trim();
+    if trimmed.len() < 20 {
+        return true;
+    }
+    trimmed.starts_with("token-")
+}
+
+/// `resolveStoredAccountIdentity(storedId, storedSource, tokenId)`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct ResolvedAccountIdentity {
+    pub account_id: Option<String>,
+    pub account_id_source: Option<AccountIdSource>,
+}
+
+pub fn resolve_stored_account_identity(
+    stored_account_id: Option<&str>,
+    stored_account_id_source: Option<AccountIdSource>,
+    token_account_id: Option<&str>,
+) -> ResolvedAccountIdentity {
+    let account_id = resolve_request_account_id(
+        stored_account_id,
+        stored_account_id_source.as_ref(),
+        token_account_id,
+    );
+    let Some(account_id) = account_id else {
+        return ResolvedAccountIdentity::default();
+    };
+
+    if !should_update_account_id_from_token(stored_account_id_source.as_ref(), stored_account_id) {
+        return ResolvedAccountIdentity {
+            account_id: Some(account_id),
+            account_id_source: stored_account_id_source,
+        };
+    }
+
+    let source = if Some(account_id.as_str()) == token_account_id {
+        Some(AccountIdSource::Token)
+    } else {
+        stored_account_id_source
+    };
+    ResolvedAccountIdentity {
+        account_id: Some(account_id),
+        account_id_source: source,
+    }
+}
+
+/// `applyTokenAccountIdentity(account, tokenId)` — mutates the account's
+/// id/source pair only when the resolution differs; never clears an id.
+/// Returns whether it changed.
+pub fn apply_token_account_identity(
+    account: &mut AccountMetadataV3,
+    token_account_id: Option<&str>,
+) -> bool {
+    let mut account_id = account.account_id.clone();
+    let mut account_id_source = account.account_id_source;
+    let changed = apply_token_account_identity_parts(
+        &mut account_id,
+        &mut account_id_source,
+        token_account_id,
+    );
+    if changed {
+        account.account_id = account_id;
+        account.account_id_source = account_id_source;
+    }
+    changed
+}
+
+/// Pick-shaped variant of [`apply_token_account_identity`] for rows that are
+/// not `AccountMetadataV3` (flagged entries).
+pub fn apply_token_account_identity_parts(
+    account_id: &mut Option<String>,
+    account_id_source: &mut Option<AccountIdSource>,
+    token_account_id: Option<&str>,
+) -> bool {
+    let next = resolve_stored_account_identity(
+        account_id.as_deref(),
+        *account_id_source,
+        token_account_id,
+    );
+    let Some(next_id) = next.account_id else {
+        return false;
+    };
+    if Some(next_id.as_str()) == account_id.as_deref()
+        && next.account_id_source == *account_id_source
+    {
+        return false;
+    }
+    *account_id = Some(next_id);
+    *account_id_source = next.account_id_source;
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn usable_access_token_needs_a_five_minute_margin() {
+        let now = 1_000_000;
+        assert!(!has_usable_access_token_parts(None, Some(now + 600_000), now));
+        assert!(!has_usable_access_token_parts(Some("tok"), None, now));
+        // Exactly at the window is NOT usable (`>` not `>=`).
+        assert!(!has_usable_access_token_parts(
+            Some("tok"),
+            Some(now + ACCESS_TOKEN_FRESH_WINDOW_MS),
+            now
+        ));
+        assert!(has_usable_access_token_parts(
+            Some("tok"),
+            Some(now + ACCESS_TOKEN_FRESH_WINDOW_MS + 1),
+            now
+        ));
+        // Struct-shaped wrapper agrees.
+        let mut account = AccountMetadataV3::new("rt-0123456789abcdefghij", 0, 0);
+        account.access_token = Some("tok".to_string());
+        account.expires_at = Some(now + 600_000);
+        assert!(has_usable_access_token(&account, now));
+    }
+
+    #[test]
+    fn likely_invalid_refresh_token_shapes() {
+        assert!(has_likely_invalid_refresh_token(None));
+        assert!(has_likely_invalid_refresh_token(Some("")));
+        assert!(has_likely_invalid_refresh_token(Some("short-token")));
+        assert!(has_likely_invalid_refresh_token(Some(
+            "token-0123456789abcdefghijklmnop"
+        )));
+        assert!(!has_likely_invalid_refresh_token(Some(
+            "rt-0123456789abcdefghijklmnop"
+        )));
+        // Whitespace is trimmed before the length check.
+        assert!(has_likely_invalid_refresh_token(Some(
+            "   short   "
+        )));
+    }
+
+    #[test]
+    fn resolve_stored_identity_prefers_token_source_when_ids_match() {
+        let resolved = resolve_stored_account_identity(None, None, Some("acc_token"));
+        assert_eq!(resolved.account_id.as_deref(), Some("acc_token"));
+        assert_eq!(resolved.account_id_source, Some(AccountIdSource::Token));
+    }
+
+    #[test]
+    fn resolve_stored_identity_keeps_manual_source() {
+        // Manual overrides are sticky: shouldUpdateAccountIdFromToken is
+        // false for manual sources, so the stored pair is kept.
+        let resolved = resolve_stored_account_identity(
+            Some("acc_manual"),
+            Some(AccountIdSource::Manual),
+            Some("acc_token"),
+        );
+        assert_eq!(resolved.account_id.as_deref(), Some("acc_manual"));
+        assert_eq!(resolved.account_id_source, Some(AccountIdSource::Manual));
+    }
+
+    #[test]
+    fn apply_token_identity_is_a_noop_when_nothing_resolves_or_changes() {
+        let mut id: Option<String> = None;
+        let mut source: Option<AccountIdSource> = None;
+        assert!(!apply_token_account_identity_parts(&mut id, &mut source, None));
+        assert_eq!(id, None);
+
+        assert!(apply_token_account_identity_parts(
+            &mut id,
+            &mut source,
+            Some("acc_1")
+        ));
+        assert_eq!(id.as_deref(), Some("acc_1"));
+        assert_eq!(source, Some(AccountIdSource::Token));
+        // Second application with the same token: unchanged.
+        assert!(!apply_token_account_identity_parts(
+            &mut id,
+            &mut source,
+            Some("acc_1")
+        ));
+
+        // Struct-shaped wrapper mutates the row.
+        let mut account = AccountMetadataV3::new("rt-0123456789abcdefghij", 0, 0);
+        assert!(apply_token_account_identity(&mut account, Some("acc_9")));
+        assert_eq!(account.account_id.as_deref(), Some("acc_9"));
+        assert_eq!(account.account_id_source, Some(AccountIdSource::Token));
+    }
+}
diff --git a/crates/manager/src/login/account_pool_write.rs b/crates/manager/src/login/account_pool_write.rs
new file mode 100644
index 000000000..c7bc430b0
--- /dev/null
+++ b/crates/manager/src/login/account_pool_write.rs
@@ -0,0 +1,493 @@
+//! Port of `lib/codex-manager/account-pool-write.ts` — the pure pool-fold
+//! logic behind `persistAccountPool` (issues #512/#491).
+//!
+//! - `inserted`: a brand new saved entry was appended.
+//! - `updated`: an existing entry was refreshed with no previously-unknown
+//!   workspace introduced (first-time workspace enrichment of a pre-#491 row
+//!   included).
+//! - `rebound`: an existing entry gained ≥1 workspace id it was not tracking
+//!   before.
+
+use cma_core::schemas::account_storage::{AccountIdSource, AccountMetadataV3, Workspace};
+
+/// `AccountPoolWriteOutcome`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AccountPoolWriteOutcome {
+    Inserted,
+    Updated,
+    Rebound,
+}
+
+impl AccountPoolWriteOutcome {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Inserted => "inserted",
+            Self::Updated => "updated",
+            Self::Rebound => "rebound",
+        }
+    }
+}
+
+/// `ResolvedAccountWrite` — identity/token fields resolved from a login
+/// result, ready to fold into the saved pool.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct ResolvedAccountWrite {
+    pub account_id: Option<String>,
+    pub account_id_source: Option<AccountIdSource>,
+    pub account_label: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: String,
+    pub access_token: Option<String>,
+    pub expires_at: Option<i64>,
+    pub workspaces: Option<Vec<Workspace>>,
+    pub now: i64,
+}
+
+/// Identity triple handed to the injected matcher.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct PoolWriteIdentity {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: Option<String>,
+}
+
+/// Injected `findMatchingAccountIndex(accounts, identity, {allowUnique...:true})`.
+pub type FindMatchingAccountIndexFn<'a> =
+    &'a dyn Fn(&[AccountMetadataV3], &PoolWriteIdentity) -> Option<usize>;
+
+/// `pickInitialWorkspaceIndex(workspaces, accountId)` — prefer the workspace
+/// whose id matches the resolved accountId, else the first enabled workspace,
+/// else index 0.
+pub fn pick_initial_workspace_index(
+    workspaces: &[Workspace],
+    account_id: Option<&str>,
+) -> usize {
+    if let Some(account_id) = account_id
+        && let Some(matching) = workspaces.iter().position(|ws| ws.id == account_id) {
+            return matching;
+        }
+    workspaces.iter().position(|ws| ws.enabled).unwrap_or(0)
+}
+
+/// `mergeAccountWorkspaces(existing, incoming)` — `incoming == None` keeps
+/// the existing list untouched; otherwise map the incoming list, carrying
+/// over the user's `enabled`/`disabledAt` for ids already tracked. Workspaces
+/// the login did not surface are dropped (only when a list was returned).
+pub fn merge_account_workspaces(
+    existing_workspaces: Option<&[Workspace]>,
+    incoming: Option<&[Workspace]>,
+) -> Option<Vec<Workspace>> {
+    let Some(incoming) = incoming else {
+        return existing_workspaces.map(<[Workspace]>::to_vec);
+    };
+    Some(
+        incoming
+            .iter()
+            .map(|new_ws| {
+                let existing_ws =
+                    existing_workspaces.and_then(|list| list.iter().find(|w| w.id == new_ws.id));
+                match existing_ws {
+                    Some(existing_ws) => Workspace {
+                        enabled: existing_ws.enabled,
+                        disabled_at: existing_ws.disabled_at,
+                        ..new_ws.clone()
+                    },
+                    None => new_ws.clone(),
+                }
+            })
+            .collect(),
+    )
+}
+
+/// `resolveCurrentWorkspaceIndex(existing, merged)` — keep the user on their
+/// current workspace if it survived, else the default workspace, else the
+/// first enabled one, else 0. No merged/empty list keeps the existing index.
+pub fn resolve_current_workspace_index(
+    existing_workspaces: Option<&[Workspace]>,
+    existing_current_workspace_index: Option<i64>,
+    merged_workspaces: Option<&[Workspace]>,
+) -> Option<i64> {
+    let merged = match merged_workspaces {
+        Some(merged) if !merged.is_empty() => merged,
+        _ => return existing_current_workspace_index,
+    };
+    let current_index = existing_current_workspace_index.unwrap_or(0);
+    let current_workspace_id = existing_workspaces.and_then(|list| {
+        usize::try_from(current_index)
+            .ok()
+            .and_then(|index| list.get(index))
+            .map(|ws| ws.id.clone())
+    });
+    if let Some(current_workspace_id) = current_workspace_id
+        && let Some(matching) = merged.iter().position(|ws| ws.id == current_workspace_id) {
+            return Some(matching as i64);
+        }
+    if let Some(default_index) = merged.iter().position(|ws| ws.is_default == Some(true)) {
+        return Some(default_index as i64);
+    }
+    if let Some(first_enabled) = merged.iter().position(|ws| ws.enabled) {
+        return Some(first_enabled as i64);
+    }
+    Some(0)
+}
+
+/// `buildInsertedAccount(write)`.
+pub fn build_inserted_account(write: &ResolvedAccountWrite) -> AccountMetadataV3 {
+    let initial_workspace_index = match &write.workspaces {
+        Some(workspaces) if !workspaces.is_empty() => Some(pick_initial_workspace_index(
+            workspaces,
+            write.account_id.as_deref(),
+        ) as i64),
+        _ => None,
+    };
+    AccountMetadataV3 {
+        account_id: write.account_id.clone(),
+        account_id_source: write.account_id_source,
+        account_label: write.account_label.clone(),
+        email: write.email.clone(),
+        refresh_token: write.refresh_token.clone(),
+        access_token: write.access_token.clone(),
+        expires_at: write.expires_at,
+        enabled: Some(true),
+        added_at: write.now,
+        last_used: write.now,
+        last_switch_reason: None,
+        rate_limit_reset_times: None,
+        cooling_down_until: None,
+        cooldown_reason: None,
+        workspaces: write.workspaces.clone(),
+        current_workspace_index: initial_workspace_index,
+    }
+}
+
+/// `buildUpdatedAccount(existing, write)` — outcome `Rebound` only when the
+/// row already tracked ≥1 workspace AND the write surfaced a new id.
+pub fn build_updated_account(
+    existing: &AccountMetadataV3,
+    write: &ResolvedAccountWrite,
+) -> (AccountMetadataV3, AccountPoolWriteOutcome) {
+    let next_email = write.email.clone().or_else(|| existing.email.clone());
+    let next_account_id = write.account_id.clone().or_else(|| existing.account_id.clone());
+    let next_account_id_source = if write.account_id.is_some() {
+        write.account_id_source.or(existing.account_id_source)
+    } else {
+        existing.account_id_source
+    };
+
+    let previous_workspace_ids: Vec<&str> = existing
+        .workspaces
+        .as_deref()
+        .unwrap_or(&[])
+        .iter()
+        .map(|ws| ws.id.as_str())
+        .collect();
+    let merged_workspaces =
+        merge_account_workspaces(existing.workspaces.as_deref(), write.workspaces.as_deref());
+    // Only a genuine *rebind* counts as "rebound": the account already
+    // tracked workspaces and the login surfaced one it had never seen (#512
+    // follow-up: first-time enrichment of a pre-#491 row stays "updated").
+    let introduced_new_workspace = !previous_workspace_ids.is_empty()
+        && write
+            .workspaces
+            .as_deref()
+            .unwrap_or(&[])
+            .iter()
+            .any(|ws| !previous_workspace_ids.contains(&ws.id.as_str()));
+    let next_current_workspace_index = resolve_current_workspace_index(
+        existing.workspaces.as_deref(),
+        existing.current_workspace_index,
+        merged_workspaces.as_deref(),
+    );
+
+    let account = AccountMetadataV3 {
+        account_id: next_account_id,
+        account_id_source: next_account_id_source,
+        account_label: write.account_label.clone().or_else(|| existing.account_label.clone()),
+        email: next_email,
+        refresh_token: write.refresh_token.clone(),
+        // Assigned unconditionally in TS — may become undefined.
+        access_token: write.access_token.clone(),
+        expires_at: write.expires_at,
+        enabled: Some(true),
+        last_used: write.now,
+        workspaces: merged_workspaces,
+        current_workspace_index: next_current_workspace_index,
+        ..existing.clone()
+    };
+    let outcome = if introduced_new_workspace {
+        AccountPoolWriteOutcome::Rebound
+    } else {
+        AccountPoolWriteOutcome::Updated
+    };
+    (account, outcome)
+}
+
+/// Result of [`apply_account_pool_results`].
+#[derive(Clone, Debug, PartialEq)]
+pub struct AccountPoolFoldResult {
+    pub accounts: Vec<AccountMetadataV3>,
+    pub active_index: i64,
+    pub outcome: Option<AccountPoolWriteOutcome>,
+}
+
+/// `applyAccountPoolResults({existing, writes, priorActiveIndex,
+/// findMatchingAccountIndex})` — the pure core of `persistAccountPool`.
+pub fn apply_account_pool_results(
+    existing: &[AccountMetadataV3],
+    writes: &[ResolvedAccountWrite],
+    prior_active_index: Option<i64>,
+    find_matching_account_index: FindMatchingAccountIndexFn<'_>,
+) -> AccountPoolFoldResult {
+    let mut accounts: Vec<AccountMetadataV3> = existing.to_vec();
+    let mut selected_account_index: Option<usize> = None;
+    let mut selected_outcome: Option<AccountPoolWriteOutcome> = None;
+
+    for write in writes {
+        let identity = PoolWriteIdentity {
+            account_id: write.account_id.clone(),
+            email: write.email.clone(),
+            refresh_token: Some(write.refresh_token.clone()),
+        };
+        let existing_index = find_matching_account_index(&accounts, &identity);
+
+        match existing_index {
+            None => {
+                let account = build_inserted_account(write);
+                selected_account_index = Some(accounts.len());
+                accounts.push(account);
+                selected_outcome = Some(AccountPoolWriteOutcome::Inserted);
+            }
+            Some(existing_index) => {
+                let Some(existing_account) = accounts.get(existing_index).cloned() else {
+                    continue;
+                };
+                let (account, outcome) = build_updated_account(&existing_account, write);
+                accounts[existing_index] = account;
+                selected_account_index = Some(existing_index);
+                selected_outcome = Some(outcome);
+            }
+        }
+    }
+
+    let clamp = |index: i64| -> i64 {
+        if accounts.is_empty() {
+            0
+        } else {
+            index.clamp(0, accounts.len() as i64 - 1).max(0)
+        }
+    };
+    let active_index = if accounts.is_empty() {
+        0
+    } else {
+        match selected_account_index {
+            Some(index) => clamp(index as i64),
+            None => clamp(prior_active_index.unwrap_or(0)),
+        }
+    };
+
+    AccountPoolFoldResult {
+        accounts,
+        active_index,
+        outcome: selected_outcome,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn workspace(id: &str, enabled: bool, is_default: bool) -> Workspace {
+        Workspace {
+            id: id.to_string(),
+            name: Some(format!("ws {id}")),
+            enabled,
+            disabled_at: None,
+            is_default: if is_default { Some(true) } else { None },
+        }
+    }
+
+    fn account(refresh_token: &str, email: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh_token.to_string(), 1_000, 1_000);
+        account.email = email.map(str::to_string);
+        account
+    }
+
+    fn write(refresh_token: &str, email: Option<&str>, now: i64) -> ResolvedAccountWrite {
+        ResolvedAccountWrite {
+            refresh_token: refresh_token.to_string(),
+            email: email.map(str::to_string),
+            now,
+            ..Default::default()
+        }
+    }
+
+    /// Matcher used in tests: refresh-token equality, then email equality.
+    fn matcher(accounts: &[AccountMetadataV3], identity: &PoolWriteIdentity) -> Option<usize> {
+        if let Some(refresh_token) = &identity.refresh_token
+            && let Some(index) = accounts
+                .iter()
+                .position(|a| &a.refresh_token == refresh_token)
+            {
+                return Some(index);
+            }
+        if let Some(email) = &identity.email
+            && let Some(index) = accounts.iter().position(|a| a.email.as_ref() == Some(email)) {
+                return Some(index);
+            }
+        None
+    }
+
+    #[test]
+    fn inserts_a_brand_new_account_and_selects_it() {
+        let result = apply_account_pool_results(
+            &[],
+            &[write("rt-new", Some("a@x.com"), 5_000)],
+            None,
+            &matcher,
+        );
+        assert_eq!(result.accounts.len(), 1);
+        assert_eq!(result.active_index, 0);
+        assert_eq!(result.outcome, Some(AccountPoolWriteOutcome::Inserted));
+        let inserted = &result.accounts[0];
+        assert_eq!(inserted.enabled, Some(true));
+        assert_eq!(inserted.added_at, 5_000);
+        assert_eq!(inserted.last_used, 5_000);
+        assert_eq!(inserted.current_workspace_index, None);
+    }
+
+    #[test]
+    fn inserted_account_seeds_workspace_tracking() {
+        let mut w = write("rt-ws", Some("a@x.com"), 5_000);
+        w.account_id = Some("acc_2".to_string());
+        w.workspaces = Some(vec![
+            workspace("acc_1", true, true),
+            workspace("acc_2", true, false),
+        ]);
+        let result = apply_account_pool_results(&[], &[w], None, &matcher);
+        // Initial index prefers the workspace matching the accountId.
+        assert_eq!(result.accounts[0].current_workspace_index, Some(1));
+    }
+
+    #[test]
+    fn same_identity_login_is_updated_not_inserted() {
+        let existing = vec![account("rt-1", Some("a@x.com"))];
+        let mut w = write("rt-1-rotated", Some("a@x.com"), 9_000);
+        w.access_token = Some("at-new".to_string());
+        w.expires_at = Some(99_000);
+        let result = apply_account_pool_results(&existing, &[w], Some(0), &matcher);
+        assert_eq!(result.accounts.len(), 1);
+        assert_eq!(result.outcome, Some(AccountPoolWriteOutcome::Updated));
+        let updated = &result.accounts[0];
+        assert_eq!(updated.refresh_token, "rt-1-rotated");
+        assert_eq!(updated.access_token.as_deref(), Some("at-new"));
+        assert_eq!(updated.expires_at, Some(99_000));
+        assert_eq!(updated.enabled, Some(true));
+        assert_eq!(updated.last_used, 9_000);
+        // addedAt survives the spread.
+        assert_eq!(updated.added_at, 1_000);
+    }
+
+    #[test]
+    fn first_time_workspace_enrichment_is_updated_not_rebound() {
+        let existing = vec![account("rt-1", Some("a@x.com"))];
+        let mut w = write("rt-1", Some("a@x.com"), 9_000);
+        w.workspaces = Some(vec![workspace("acc_1", true, true)]);
+        let result = apply_account_pool_results(&existing, &[w], Some(0), &matcher);
+        assert_eq!(result.outcome, Some(AccountPoolWriteOutcome::Updated));
+        assert_eq!(result.accounts[0].workspaces.as_ref().unwrap().len(), 1);
+    }
+
+    #[test]
+    fn new_workspace_id_on_a_tracking_row_is_rebound() {
+        let mut existing_account = account("rt-1", Some("a@x.com"));
+        existing_account.workspaces = Some(vec![workspace("acc_1", true, true)]);
+        existing_account.current_workspace_index = Some(0);
+        let mut w = write("rt-1", Some("a@x.com"), 9_000);
+        w.workspaces = Some(vec![
+            workspace("acc_1", true, true),
+            workspace("acc_9", true, false),
+        ]);
+        let result = apply_account_pool_results(&[existing_account], &[w], Some(0), &matcher);
+        assert_eq!(result.outcome, Some(AccountPoolWriteOutcome::Rebound));
+    }
+
+    #[test]
+    fn workspace_merge_preserves_user_enabled_state_and_drops_unsurfaced() {
+        let mut disabled_ws = workspace("acc_1", false, true);
+        disabled_ws.disabled_at = Some(7_777);
+        let existing = vec![Workspace {
+            ..disabled_ws.clone()
+        }, workspace("acc_gone", true, false)];
+
+        let incoming = vec![workspace("acc_1", true, true), workspace("acc_new", true, false)];
+        let merged = merge_account_workspaces(Some(&existing), Some(&incoming)).unwrap();
+        assert_eq!(merged.len(), 2);
+        // User's disabled state + disabledAt carried over.
+        assert!(!merged[0].enabled);
+        assert_eq!(merged[0].disabled_at, Some(7_777));
+        // acc_gone was not surfaced → dropped.
+        assert!(merged.iter().all(|ws| ws.id != "acc_gone"));
+
+        // No incoming list → existing untouched.
+        let untouched = merge_account_workspaces(Some(&existing), None).unwrap();
+        assert_eq!(untouched.len(), 2);
+    }
+
+    #[test]
+    fn current_workspace_index_follows_survivor_then_default_then_enabled() {
+        let existing = vec![workspace("a", true, false), workspace("b", true, false)];
+        // Current (index 1 = "b") survives at new position 0.
+        let merged = vec![workspace("b", true, false), workspace("c", true, true)];
+        assert_eq!(
+            resolve_current_workspace_index(Some(&existing), Some(1), Some(&merged)),
+            Some(0)
+        );
+        // Current gone → default wins.
+        let merged = vec![workspace("x", true, false), workspace("y", true, true)];
+        assert_eq!(
+            resolve_current_workspace_index(Some(&existing), Some(1), Some(&merged)),
+            Some(1)
+        );
+        // No default → first enabled.
+        let merged = vec![workspace("x", false, false), workspace("y", true, false)];
+        assert_eq!(
+            resolve_current_workspace_index(Some(&existing), Some(1), Some(&merged)),
+            Some(1)
+        );
+        // Nothing enabled → 0.
+        let merged = vec![workspace("x", false, false)];
+        assert_eq!(
+            resolve_current_workspace_index(Some(&existing), Some(1), Some(&merged)),
+            Some(0)
+        );
+        // Empty merged list keeps the existing index.
+        assert_eq!(
+            resolve_current_workspace_index(Some(&existing), Some(1), Some(&[])),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn outcome_is_from_the_last_write_and_active_index_follows_it() {
+        let existing = vec![account("rt-1", Some("a@x.com"))];
+        let writes = vec![
+            write("rt-2", Some("b@x.com"), 9_000), // inserted at 1
+            write("rt-1", Some("a@x.com"), 9_001), // updated at 0
+        ];
+        let result = apply_account_pool_results(&existing, &writes, Some(0), &matcher);
+        assert_eq!(result.accounts.len(), 2);
+        assert_eq!(result.outcome, Some(AccountPoolWriteOutcome::Updated));
+        assert_eq!(result.active_index, 0);
+    }
+
+    #[test]
+    fn no_writes_falls_back_to_clamped_prior_active_index() {
+        let existing = vec![account("rt-1", None), account("rt-2", None)];
+        let result = apply_account_pool_results(&existing, &[], Some(7), &matcher);
+        assert_eq!(result.active_index, 1);
+        assert_eq!(result.outcome, None);
+
+        let empty = apply_account_pool_results(&[], &[], Some(7), &matcher);
+        assert_eq!(empty.active_index, 0);
+    }
+}
diff --git a/crates/manager/src/login/action_panel.rs b/crates/manager/src/login/action_panel.rs
new file mode 100644
index 000000000..8b0717449
--- /dev/null
+++ b/crates/manager/src/login/action_panel.rs
@@ -0,0 +1,512 @@
+//! Port of `lib/codex-manager/login-action-panel.ts` — the full-screen action
+//! panel used by the login dashboard to run a menu action with captured
+//! output, plus the return-to-menu wait prompt.
+//!
+//! Capture model (deliberate port deviation, mandated by ARCHITECTURE §6.15):
+//! the TS module monkey-patched `console.log/warn/error` so action output
+//! streamed into the panel live. Rust never patches global stdout — the
+//! action receives an owned capture [`CliOut`] sink and hands it back when it
+//! finishes; the captured lines are rendered in the completion frame (the
+//! spinner still animates on the 120 ms timer while the action runs). The
+//! visible contracts are unchanged: `"! "`/`"x "` prefixes, 400-line ring
+//! buffer, `max(8, rows-8)` visible lines, done/failed status copy, and the
+//! auto-return countdown.
+
+use std::future::Future;
+use std::io::Write;
+use std::time::Duration;
+
+use cma_config::dashboard_settings::DashboardDisplaySettings;
+use cma_tui::ansi;
+use cma_tui::ui_copy;
+
+use crate::dispatcher::{CliOut, OutLine};
+use crate::formatters::text_style::{style_prompt_text, PromptTone};
+
+/// Spinner frames (TS `["-", "\\", "|", "/"]`).
+const SPINNER_FRAMES: [&str; 4] = ["-", "\\", "|", "/"];
+
+/// Captured-output ring buffer cap (TS `400`).
+const CAPTURE_CAP: usize = 400;
+
+/// Render interval for the spinner frame (TS `120` ms).
+const RENDER_INTERVAL_MS: u64 = 120;
+
+/// Countdown re-render interval (TS `80` ms).
+const COUNTDOWN_INTERVAL_MS: u64 = 80;
+
+/// TS `output.rows ?? 24`. The manager crate has no terminal-size API
+/// (crossterm is a cma-tui-internal dependency), so the Node fallback value
+/// is used unconditionally.
+const FALLBACK_TERMINAL_ROWS: i64 = 24;
+
+/// `Math.max(8, (output.rows ?? 24) - 8)`.
+pub(crate) fn max_visible_lines(rows: Option<i64>) -> usize {
+    std::cmp::max(8, rows.unwrap_or(FALLBACK_TERMINAL_ROWS) - 8) as usize
+}
+
+/// TS `capture(prefix, args)` — trim, skip empty, apply prefix.
+pub(crate) fn capture_line(prefix: &str, text: &str) -> Option<String> {
+    let line = text.trim();
+    if line.is_empty() {
+        return None;
+    }
+    if prefix.is_empty() {
+        Some(line.to_string())
+    } else {
+        Some(format!("{prefix}{line}"))
+    }
+}
+
+/// Push a captured line, keeping only the newest [`CAPTURE_CAP`] entries
+/// (TS `captured.splice(0, captured.length - 400)`).
+pub(crate) fn push_captured(captured: &mut Vec<String>, line: String) {
+    captured.push(line);
+    if captured.len() > CAPTURE_CAP {
+        let excess = captured.len() - CAPTURE_CAP;
+        captured.drain(0..excess);
+    }
+}
+
+/// Map the sink lines an action produced onto panel capture lines:
+/// `info` → bare, `warn` → `"! "`, `error` → `"x "` (the TS console
+/// replacements).
+pub(crate) fn out_lines_to_captured(lines: &[OutLine]) -> Vec<String> {
+    let mut captured: Vec<String> = Vec::new();
+    for line in lines {
+        let (prefix, text) = match line {
+            OutLine::Info(text) => ("", text.as_str()),
+            OutLine::Warn(text) => ("! ", text.as_str()),
+            OutLine::Error(text) => ("x ", text.as_str()),
+        };
+        if let Some(entry) = capture_line(prefix, text) {
+            push_captured(&mut captured, entry);
+        }
+    }
+    captured
+}
+
+/// Status line text + tone for the current panel state (TS `render`).
+pub(crate) fn panel_status(
+    running: bool,
+    failed: bool,
+    frame: usize,
+    stage: &str,
+) -> (String, PromptTone) {
+    if running {
+        let spinner = SPINNER_FRAMES[frame % SPINNER_FRAMES.len()];
+        (format!("{spinner} {stage}"), PromptTone::Accent)
+    } else if failed {
+        (ui_copy::return_flow::FAILED.to_string(), PromptTone::Danger)
+    } else {
+        (ui_copy::return_flow::DONE.to_string(), PromptTone::Success)
+    }
+}
+
+/// Build one full panel frame as a string (TS `render`, minus the terminal
+/// writes): clear screen, title, status line, blank, the last
+/// `max_visible` captured lines padded with blanks, blank, and the
+/// "Running..." hint while the action is still going.
+pub(crate) fn build_panel_frame(
+    title: &str,
+    stage: &str,
+    running: bool,
+    failed: bool,
+    captured: &[String],
+    max_visible: usize,
+    frame: usize,
+) -> String {
+    let (status_text, status_tone) = panel_status(running, failed, frame, stage);
+    let mut out = String::new();
+    out.push_str(ansi::CLEAR_SCREEN);
+    out.push_str(&ansi::move_to(1, 1));
+    out.push_str(&style_prompt_text(title, PromptTone::Accent));
+    out.push('\n');
+    out.push_str(&style_prompt_text(&status_text, status_tone));
+    out.push('\n');
+    out.push('\n');
+
+    let start = captured.len().saturating_sub(max_visible);
+    let visible = &captured[start..];
+    for line in visible {
+        out.push_str(line);
+        out.push('\n');
+    }
+    for _ in 0..max_visible.saturating_sub(visible.len()) {
+        out.push('\n');
+    }
+    out.push('\n');
+    if running {
+        out.push_str(&style_prompt_text(
+            ui_copy::return_flow::WORKING,
+            PromptTone::Muted,
+        ));
+        out.push('\n');
+    }
+    out
+}
+
+/// TS `Math.max(1, Math.ceil(remainingMs / 1000))`.
+pub(crate) fn countdown_seconds(remaining_ms: i64) -> i64 {
+    std::cmp::max(1, (remaining_ms.max(0) + 999) / 1000)
+}
+
+/// Options for [`wait_for_menu_return`] (TS `WaitForReturnOptions`).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) struct WaitForReturnOptions {
+    pub prompt_text: Option<String>,
+    pub auto_return_ms: i64,
+    pub pause_on_any_key: bool,
+}
+
+/// Resolve the wait options for the post-action prompt: failed actions block
+/// on the "Action failed" question; successful ones auto-return after
+/// `actionAutoReturnMs ?? 2_000` with `actionPauseOnKey ?? true`.
+pub(crate) fn resolve_wait_options(
+    failed: bool,
+    settings: Option<&DashboardDisplaySettings>,
+) -> WaitForReturnOptions {
+    if failed {
+        WaitForReturnOptions {
+            prompt_text: Some(ui_copy::return_flow::ACTION_FAILED_PROMPT.to_string()),
+            auto_return_ms: 0,
+            pause_on_any_key: true,
+        }
+    } else {
+        WaitForReturnOptions {
+            prompt_text: None,
+            auto_return_ms: settings.map_or(2_000, |value| value.action_auto_return_ms),
+            pause_on_any_key: settings.is_none_or(|value| value.action_pause_on_key),
+        }
+    }
+}
+
+fn write_inline_status(message: &str) {
+    let mut stdout = std::io::stdout();
+    let _ = write!(
+        stdout,
+        "\r{}{}",
+        ansi::CLEAR_LINE,
+        style_prompt_text(message, PromptTone::Muted)
+    );
+    let _ = stdout.flush();
+}
+
+fn clear_inline_status() {
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "\r{}", ansi::CLEAR_LINE);
+    let _ = stdout.flush();
+}
+
+/// TS `waitForMenuReturn`.
+///
+/// Port note: the TS "press any key to pause the countdown" behavior needs a
+/// raw-mode single-keypress read, which `cma-tui` does not currently expose
+/// (its raw-mode plumbing is internal to `select`). The countdown therefore
+/// renders and auto-returns without key interception; the `pause_on_any_key`
+/// flag only selects between the rendered countdown and a silent sleep,
+/// matching the TS timing behavior for users who never press a key.
+async fn wait_for_menu_return(options: WaitForReturnOptions) {
+    if !ansi::is_tty() {
+        return;
+    }
+
+    if options.auto_return_ms > 0 {
+        if !options.pause_on_any_key {
+            tokio::time::sleep(Duration::from_millis(options.auto_return_ms as u64)).await;
+            return;
+        }
+        let end_at = cma_core::utils::now_ms() + options.auto_return_ms;
+        let mut last_shown_seconds: i64 = -1;
+        loop {
+            let remaining_ms = end_at - cma_core::utils::now_ms();
+            if remaining_ms <= 0 {
+                break;
+            }
+            let seconds = countdown_seconds(remaining_ms);
+            if seconds != last_shown_seconds {
+                last_shown_seconds = seconds;
+                write_inline_status(&ui_copy::return_flow::auto_return(seconds));
+            }
+            let tick = std::cmp::min(remaining_ms, COUNTDOWN_INTERVAL_MS as i64);
+            tokio::time::sleep(Duration::from_millis(tick as u64)).await;
+        }
+        clear_inline_status();
+        return;
+    }
+
+    // autoReturnMs == 0 → blocking readline question.
+    let prompt_text = options
+        .prompt_text
+        .unwrap_or_else(|| ui_copy::return_flow::CONTINUE_PROMPT.to_string());
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "\r{}", ansi::CLEAR_LINE);
+    if !prompt_text.is_empty() {
+        let _ = write!(
+            stdout,
+            "{} ",
+            style_prompt_text(&prompt_text, PromptTone::Muted)
+        );
+    }
+    let _ = stdout.flush();
+    let mut answer = String::new();
+    let _ = std::io::BufRead::read_line(&mut std::io::stdin().lock(), &mut answer);
+    clear_inline_status();
+}
+
+fn write_raw(text: &str) {
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "{text}");
+    let _ = stdout.flush();
+}
+
+/// TS `runActionPanel(title, stage, action, settings?)`.
+///
+/// The action receives an owned [`CliOut`] sink (capture mode when the panel
+/// is interactive) and must return it together with its outcome; the panel
+/// renders the captured lines and re-surfaces the error to the caller AFTER
+/// the screen is restored (TS `throw failed` after `altScreenOff`).
+///
+/// Non-TTY: the action runs without any panel chrome and its captured lines
+/// are replayed into the caller's sink (the TS non-TTY path wrote straight to
+/// the console).
+pub async fn run_action_panel<E, F, Fut>(
+    title: &str,
+    stage: &str,
+    out: &mut CliOut,
+    settings: Option<&DashboardDisplaySettings>,
+    action: F,
+) -> Result<(), E>
+where
+    E: std::fmt::Display,
+    F: FnOnce(CliOut) -> Fut,
+    Fut: Future<Output = (CliOut, Result<(), E>)>,
+{
+    if !ansi::is_tty() {
+        let (action_out, result) = action(CliOut::capture()).await;
+        for line in action_out.lines() {
+            match line {
+                OutLine::Info(text) => out.info(text.clone()),
+                OutLine::Warn(text) => out.warn(text.clone()),
+                OutLine::Error(text) => out.error(text.clone()),
+            }
+        }
+        return result;
+    }
+
+    let max_visible = max_visible_lines(None);
+    let mut frame: usize = 0;
+
+    write_raw(&format!("{}{}", ansi::ALT_SCREEN_ON, ansi::HIDE));
+    // Initial frame (running, no output yet).
+    write_raw(&build_panel_frame(
+        title,
+        stage,
+        true,
+        false,
+        &[],
+        max_visible,
+        frame,
+    ));
+    frame += 1;
+
+    let action_future = action(CliOut::capture());
+    tokio::pin!(action_future);
+    let mut interval = tokio::time::interval(Duration::from_millis(RENDER_INTERVAL_MS));
+    interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    // The first tick fires immediately; consume it so the spinner advances on
+    // the 120 ms cadence after the initial frame above.
+    interval.tick().await;
+
+    let (action_out, result) = loop {
+        tokio::select! {
+            outcome = &mut action_future => break outcome,
+            _ = interval.tick() => {
+                write_raw(&build_panel_frame(
+                    title,
+                    stage,
+                    true,
+                    false,
+                    &[],
+                    max_visible,
+                    frame,
+                ));
+                frame += 1;
+            }
+        }
+    };
+
+    let mut captured = out_lines_to_captured(action_out.lines());
+    let failed_message = result.as_ref().err().map(|error| error.to_string());
+    if let Some(message) = &failed_message
+        && let Some(entry) = capture_line("x ", message) {
+            push_captured(&mut captured, entry);
+        }
+
+    // Final frame (TS `finally { running = false; render(); }`).
+    write_raw(&build_panel_frame(
+        title,
+        stage,
+        false,
+        failed_message.is_some(),
+        &captured,
+        max_visible,
+        frame,
+    ));
+
+    wait_for_menu_return(resolve_wait_options(failed_message.is_some(), settings)).await;
+
+    write_raw(&format!(
+        "{}{}{}{}",
+        ansi::ALT_SCREEN_OFF,
+        ansi::SHOW,
+        ansi::CLEAR_SCREEN,
+        ansi::move_to(1, 1)
+    ));
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn capture_line_trims_skips_empty_and_prefixes() {
+        assert_eq!(capture_line("", "  hello  "), Some("hello".to_string()));
+        assert_eq!(capture_line("! ", "warned"), Some("! warned".to_string()));
+        assert_eq!(capture_line("x ", "boom"), Some("x boom".to_string()));
+        assert_eq!(capture_line("! ", "   "), None);
+        assert_eq!(capture_line("", ""), None);
+    }
+
+    #[test]
+    fn push_captured_caps_at_400_dropping_oldest() {
+        let mut captured: Vec<String> = Vec::new();
+        for i in 0..405 {
+            push_captured(&mut captured, format!("line {i}"));
+        }
+        assert_eq!(captured.len(), 400);
+        assert_eq!(captured[0], "line 5");
+        assert_eq!(captured[399], "line 404");
+    }
+
+    #[test]
+    fn out_lines_map_to_console_prefixes() {
+        let lines = vec![
+            OutLine::Info("plain".to_string()),
+            OutLine::Warn("careful".to_string()),
+            OutLine::Error("broken".to_string()),
+            OutLine::Info("   ".to_string()),
+        ];
+        assert_eq!(
+            out_lines_to_captured(&lines),
+            vec![
+                "plain".to_string(),
+                "! careful".to_string(),
+                "x broken".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn panel_status_matches_ts_state_machine() {
+        let (text, tone) = panel_status(true, false, 0, "Comparing accounts");
+        assert_eq!(text, "- Comparing accounts");
+        assert_eq!(tone, PromptTone::Accent);
+        let (text, _) = panel_status(true, false, 1, "s");
+        assert_eq!(text, "\\ s");
+        let (text, tone) = panel_status(false, true, 7, "ignored");
+        assert_eq!(text, "Failed.");
+        assert_eq!(tone, PromptTone::Danger);
+        let (text, tone) = panel_status(false, false, 7, "ignored");
+        assert_eq!(text, "Done.");
+        assert_eq!(tone, PromptTone::Success);
+    }
+
+    #[test]
+    fn build_panel_frame_pads_to_max_visible() {
+        let captured = vec!["a".to_string(), "b".to_string()];
+        let frame = build_panel_frame("Title", "stage", true, false, &captured, 8, 0);
+        // title + status + blank + 2 lines + 6 pad + blank + working hint.
+        let newlines = frame.matches('\n').count();
+        assert_eq!(newlines, 3 + 2 + 6 + 1 + 1);
+        assert!(frame.contains("Title"));
+        assert!(frame.contains("- stage"));
+        assert!(frame.contains("Running..."));
+        // Completed frames drop the working hint.
+        let done = build_panel_frame("Title", "stage", false, false, &captured, 8, 0);
+        assert!(!done.contains("Running..."));
+        assert!(done.contains("Done."));
+    }
+
+    #[test]
+    fn build_panel_frame_shows_only_last_max_visible_lines() {
+        let captured: Vec<String> = (0..20).map(|i| format!("row {i}")).collect();
+        let frame = build_panel_frame("T", "s", false, false, &captured, 8, 0);
+        assert!(!frame.contains("row 11\n"));
+        assert!(frame.contains("row 12\n"));
+        assert!(frame.contains("row 19\n"));
+    }
+
+    #[test]
+    fn countdown_seconds_floors_at_one_and_ceils() {
+        assert_eq!(countdown_seconds(0), 1);
+        assert_eq!(countdown_seconds(1), 1);
+        assert_eq!(countdown_seconds(1000), 1);
+        assert_eq!(countdown_seconds(1001), 2);
+        assert_eq!(countdown_seconds(2000), 2);
+        assert_eq!(countdown_seconds(-50), 1);
+    }
+
+    #[test]
+    fn max_visible_lines_uses_rows_minus_8_with_floor_8() {
+        assert_eq!(max_visible_lines(None), 16);
+        assert_eq!(max_visible_lines(Some(24)), 16);
+        assert_eq!(max_visible_lines(Some(10)), 8);
+        assert_eq!(max_visible_lines(Some(40)), 32);
+    }
+
+    #[test]
+    fn resolve_wait_options_defaults() {
+        let failed = resolve_wait_options(true, None);
+        assert_eq!(
+            failed.prompt_text.as_deref(),
+            Some("Action failed. Press Enter to go back.")
+        );
+        assert_eq!(failed.auto_return_ms, 0);
+
+        let default_ok = resolve_wait_options(false, None);
+        assert_eq!(default_ok.auto_return_ms, 2_000);
+        assert!(default_ok.pause_on_any_key);
+
+        let settings = DashboardDisplaySettings {
+            action_auto_return_ms: 4_000,
+            action_pause_on_key: false,
+            ..Default::default()
+        };
+        let custom = resolve_wait_options(false, Some(&settings));
+        assert_eq!(custom.auto_return_ms, 4_000);
+        assert!(!custom.pause_on_any_key);
+    }
+
+    // Non-TTY path: the action runs with a capture sink and its lines are
+    // replayed into the caller's sink; errors surface AFTER the replay (TS
+    // non-TTY simply awaited the action).
+    #[tokio::test]
+    async fn non_tty_replays_action_output_and_returns_error() {
+        // Test processes have no TTY, so run_action_panel takes the
+        // pass-through branch deterministically.
+        let mut out = CliOut::capture();
+        let result: Result<(), String> =
+            run_action_panel("T", "stage", &mut out, None, |mut panel_out| async move {
+                panel_out.info("did a thing");
+                panel_out.warn("uh oh");
+                (panel_out, Err("exploded".to_string()))
+            })
+            .await;
+        assert_eq!(result, Err("exploded".to_string()));
+        assert_eq!(out.info_text(), "did a thing");
+        assert_eq!(out.warn_text(), "uh oh");
+    }
+}
diff --git a/crates/manager/src/login/flow.rs b/crates/manager/src/login/flow.rs
new file mode 100644
index 000000000..8b62b0a2f
--- /dev/null
+++ b/crates/manager/src/login/flow.rs
@@ -0,0 +1,994 @@
+//! Port of `lib/codex-manager/login-flow.ts` — the interactive control loop
+//! for the `login` command: the account dashboard menu and the
+//! add-account/onboarding flow.
+//!
+//! The TS closure-mutable menu quota-refresh bookkeeping is an explicit
+//! [`MenuQuotaRefreshState`]: the fire-and-forget refresh runs as a spawned
+//! tokio task sharing status/generation/skip-flag cells, and
+//! [`drain_pending_menu_quota_refresh`] awaits it on EVERY path that leaves
+//! the dashboard loop (add-account, cancel/exit, empty pool) so the cache
+//! save cannot race an account-pool write (Windows EBUSY/EPERM on sibling
+//! files) or be orphaned mid-write.
+//!
+//! The TS `LoginFlowDeps` DI shim (runForecast/createRepairCommandDeps) is
+//! absorbed per ARCHITECTURE §4 item 10 — the sibling command modules are
+//! called directly.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use cma_auth::browser::is_browser_launch_suppressed;
+use cma_config::dashboard_settings::load_dashboard_display_settings;
+use cma_core::constants::ACCOUNT_LIMITS;
+use cma_core::errors::CodexError;
+use cma_core::logger::create_logger;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountStorageV3, PersistedSwitchReason};
+use cma_core::schemas::token::TokenResult;
+use cma_core::utils::now_ms;
+use cma_quota::cache::{load_quota_cache, QuotaCacheEntry};
+use cma_runtime::account_status::resolve_active_index;
+use cma_storage::backup_restore::restore_accounts_from_backup;
+use cma_storage::clear::clear_accounts;
+use cma_storage::flagged::load_flagged_accounts;
+use cma_storage::load::load_accounts;
+use cma_storage::misc::format_storage_error_hint_for_code;
+use cma_storage::named_backups::{get_named_backups, NamedBackupSummary};
+use cma_tui::auth_menu_builder::{AuthMenuOptions, StatusMessage};
+use cma_tui::confirm::confirm;
+use cma_tui::login_prompts::{
+    prompt_add_another_account, prompt_login_mode, LoginMenuResult, LoginMode,
+};
+use cma_tui::ui_copy;
+
+use crate::dispatcher::CliOut;
+use crate::formatters::quota::{format_account_quota_summary, CompactQuotaFormatOptions};
+use crate::formatters::text_style::{style_prompt_text, PromptTone};
+use crate::help::{parse_auth_login_args, print_usage, AuthLoginOptions, ParsedAuthLoginArgs};
+use crate::login::account_pool_write::AccountPoolWriteOutcome;
+use crate::login::action_panel::run_action_panel;
+use crate::login::menu_actions::{
+    handle_manage_action, prompt_backup_restore_mode, prompt_manual_backup_selection,
+    prompt_oauth_sign_in_mode, BackupRestoreMode,
+};
+use crate::login::menu_data::{
+    count_menu_quota_refresh_targets, load_runtime_current_selection_for_storage,
+    refresh_quota_cache_for_menu, sync_codex_cli_active_selection_if_drifted,
+    to_existing_account_info,
+};
+use crate::login::oauth::{
+    is_oauth_cancellation, persist_account_pool, resolve_account_selection, run_sign_in_flow,
+    sync_selection_to_codex, OAuthSignInMode,
+};
+use crate::login::persist_selected::{
+    persist_and_sync_selected_account, PersistSelectedAccountParams,
+};
+use crate::settings::hub::apply_ui_theme_from_dashboard_settings;
+use crate::settings::persist::configure_unified_settings;
+
+/// Cells shared with the fire-and-forget quota-refresh task (the TS
+/// closure-captured `MenuQuotaRefreshState` fields that outlive one loop
+/// pass).
+struct MenuQuotaShared {
+    /// `menuQuotaRefreshStatus` — the live `Fetching account limits...
+    /// [n/total]` subtitle.
+    status: Mutex<Option<String>>,
+    /// `menuQuotaRefreshGeneration` — invalidates the in-flight refresh's
+    /// "skip next pass" side effect.
+    generation: AtomicU64,
+    /// `skipNextMenuQuotaAutoRefresh`.
+    skip_next: AtomicBool,
+}
+
+/// TS `MenuQuotaRefreshState`.
+pub(crate) struct MenuQuotaRefreshState {
+    shared: Arc<MenuQuotaShared>,
+    /// `pendingMenuQuotaRefresh` — the in-flight refresh task, if any.
+    pending: Option<tokio::task::JoinHandle<()>>,
+}
+
+impl MenuQuotaRefreshState {
+    fn new() -> Self {
+        MenuQuotaRefreshState {
+            shared: Arc::new(MenuQuotaShared {
+                status: Mutex::new(None),
+                generation: AtomicU64::new(0),
+                skip_next: AtomicBool::new(false),
+            }),
+            pending: None,
+        }
+    }
+
+    /// TS `pendingMenuQuotaRefresh !== null` (the promise nulls itself in
+    /// `.finally`; a finished join handle is equivalent).
+    fn has_pending(&self) -> bool {
+        self.pending
+            .as_ref()
+            .is_some_and(|handle| !handle.is_finished())
+    }
+}
+
+/// TS `clearMenuQuotaAutoRefreshSkip(state)`.
+fn clear_menu_quota_auto_refresh_skip(state: &MenuQuotaRefreshState) {
+    state.shared.skip_next.store(false, Ordering::SeqCst);
+    state.shared.generation.fetch_add(1, Ordering::SeqCst);
+}
+
+/// TS `drainPendingMenuQuotaRefresh(state)` — must run on every exit path
+/// from the dashboard loop. The chain never rejects (all failure paths are
+/// absorbed inside the task).
+async fn drain_pending_menu_quota_refresh(state: &mut MenuQuotaRefreshState) {
+    if let Some(handle) = state.pending.take() {
+        let _ = handle.await;
+    }
+}
+
+/// `runLoginDashboardLoop` outcome.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DashboardOutcome {
+    AddAccount,
+    Exit,
+}
+
+/// The message printed after a successful sign-in persist (issue #512: only
+/// claim a new saved slot when one was actually appended).
+pub(crate) fn outcome_message(outcome: Option<AccountPoolWriteOutcome>, count: usize) -> String {
+    match outcome {
+        Some(AccountPoolWriteOutcome::Rebound) => {
+            format!("Rebound workspace for existing account. Total: {count}")
+        }
+        Some(AccountPoolWriteOutcome::Updated) => {
+            format!("Updated existing account. Total: {count}")
+        }
+        _ => format!("Added account. Total: {count}"),
+    }
+}
+
+/// Explicit transports (`--device-auth`, `--manual`, `--no-browser`) bypass
+/// the dashboard AND every "fall back to menu" path (spec 09 gotcha 13).
+pub(crate) fn is_explicit_sign_in_mode(options: &AuthLoginOptions) -> bool {
+    options.device_auth || options.manual
+}
+
+/// Resolve the sign-in transport without prompting; `None` means "ask the
+/// user" (TS: `deviceAuth ? "device" : preferManualMode ? "manual" : prompt`).
+pub(crate) fn resolve_forced_sign_in_mode(
+    device_auth: bool,
+    prefer_manual: bool,
+) -> Option<OAuthSignInMode> {
+    if device_auth {
+        Some(OAuthSignInMode::Device)
+    } else if prefer_manual {
+        Some(OAuthSignInMode::Manual)
+    } else {
+        None
+    }
+}
+
+/// Restore-panel failure: the TS catch distinguishes `StorageError` (printed
+/// through `formatStorageErrorHint`) from every other error message.
+enum RestoreActionError {
+    Storage(CodexError),
+    Message(String),
+}
+
+impl std::fmt::Display for RestoreActionError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            RestoreActionError::Storage(error) => f.write_str(error.message()),
+            RestoreActionError::Message(message) => f.write_str(message),
+        }
+    }
+}
+
+/// `@internal runAuthLogin(args, deps)`.
+pub async fn run_auth_login(args: &[String], out: &mut CliOut) -> i32 {
+    match parse_auth_login_args(args) {
+        ParsedAuthLoginArgs::Error(message) => {
+            out.error(message);
+            print_usage(out);
+            1
+        }
+        // The parent dispatcher prints usage for `--help`; this layer returns
+        // 0 silently (TS parity).
+        ParsedAuthLoginArgs::Help => 0,
+        ParsedAuthLoginArgs::Ok(options) => {
+            // `--org <id>` binds this login to a specific workspace/org
+            // (issue #491); threaded explicitly, no env mutation.
+            if let Some(org) = &options.org {
+                out.info(format!("Binding this login to workspace org id: {org}"));
+            }
+            run_auth_login_flow(&options, out).await
+        }
+    }
+}
+
+async fn run_login_dashboard_loop(
+    menu_state: &mut MenuQuotaRefreshState,
+    out: &mut CliOut,
+) -> Result<DashboardOutcome, String> {
+    loop {
+        let existing_storage = load_accounts().await.map(|loaded| loaded.storage);
+        let Some(mut current_storage) = existing_storage else {
+            drain_pending_menu_quota_refresh(menu_state).await;
+            return Ok(DashboardOutcome::AddAccount);
+        };
+        if current_storage.accounts.is_empty() {
+            drain_pending_menu_quota_refresh(menu_state).await;
+            return Ok(DashboardOutcome::AddAccount);
+        }
+
+        let display_settings = load_dashboard_display_settings().await;
+        apply_ui_theme_from_dashboard_settings(&display_settings);
+        let quota_cache = load_quota_cache().await;
+        // The Rust settings struct bakes the `?? true` / TTL defaults in at
+        // normalize time (spec 01 §2.11), matching the TS `??` fallbacks.
+        let should_auto_fetch_limits = display_settings.menu_auto_fetch_limits;
+        let show_fetch_status = display_settings.menu_show_fetch_status;
+        let quota_ttl_ms = display_settings.menu_quota_ttl_ms;
+
+        let has_pending = menu_state.has_pending();
+        let should_skip_auto_fetch_this_pass =
+            !has_pending && menu_state.shared.skip_next.load(Ordering::SeqCst);
+        if should_skip_auto_fetch_this_pass {
+            menu_state.shared.skip_next.store(false, Ordering::SeqCst);
+        }
+        if should_auto_fetch_limits && !has_pending && !should_skip_auto_fetch_this_pass {
+            let stale_count = count_menu_quota_refresh_targets(
+                &current_storage,
+                &quota_cache,
+                quota_ttl_ms,
+                now_ms(),
+            );
+            if stale_count > 0 {
+                if show_fetch_status
+                    && let Ok(mut guard) = menu_state.shared.status.lock() {
+                        *guard = Some(format!(
+                            "{} [0/{stale_count}]",
+                            ui_copy::main_menu::LOADING_LIMITS
+                        ));
+                    }
+                let refresh_generation = menu_state.shared.generation.load(Ordering::SeqCst);
+                let progress_shared = menu_state.shared.clone();
+                let done_shared = menu_state.shared.clone();
+                let storage_clone = current_storage.clone();
+                let cache_clone = quota_cache.clone();
+                let handle = tokio::spawn(async move {
+                    let mut progress = move |current: usize, total: usize| {
+                        if !show_fetch_status {
+                            return;
+                        }
+                        if let Ok(mut guard) = progress_shared.status.lock() {
+                            *guard = Some(format!(
+                                "{} [{current}/{total}]",
+                                ui_copy::main_menu::LOADING_LIMITS
+                            ));
+                        }
+                    };
+                    // Never rejects: probe failures keep cached values and
+                    // save failures only warn (spec 09 §1.7).
+                    let _ = refresh_quota_cache_for_menu(
+                        &storage_clone,
+                        &cache_clone,
+                        quota_ttl_ms,
+                        Some(&mut progress),
+                    )
+                    .await;
+                    if refresh_generation == done_shared.generation.load(Ordering::SeqCst) {
+                        done_shared.skip_next.store(true, Ordering::SeqCst);
+                    }
+                    if let Ok(mut guard) = done_shared.status.lock() {
+                        *guard = None;
+                    }
+                });
+                menu_state.pending = Some(handle);
+            }
+        }
+
+        let flagged_storage = load_flagged_accounts().await;
+        let _ = sync_codex_cli_active_selection_if_drifted(&current_storage).await;
+        let runtime_current =
+            load_runtime_current_selection_for_storage(&current_storage, now_ms()).await;
+
+        let summary_options = CompactQuotaFormatOptions::default();
+        let summary_fn = |entry: &QuotaCacheEntry, now: i64| -> String {
+            format_account_quota_summary(entry, now, &summary_options)
+        };
+        let rows = to_existing_account_info(
+            &current_storage,
+            &quota_cache,
+            &display_settings,
+            runtime_current.as_ref(),
+            &summary_fn,
+        );
+
+        let status_shared = menu_state.shared.clone();
+        let menu_options = AuthMenuOptions {
+            flagged_count: Some(flagged_storage.accounts.len() as i64),
+            status_message: if show_fetch_status {
+                Some(StatusMessage::Dynamic(Box::new(move || {
+                    status_shared
+                        .status
+                        .lock()
+                        .ok()
+                        .and_then(|guard| guard.clone())
+                })))
+            } else {
+                None
+            },
+        };
+        let menu_result = prompt_login_mode(&rows, &menu_options)
+            .unwrap_or_else(|_| LoginMenuResult::mode(LoginMode::Cancel));
+
+        match menu_result.mode {
+            LoginMode::Cancel => {
+                out.info("Cancelled.");
+                drain_pending_menu_quota_refresh(menu_state).await;
+                return Ok(DashboardOutcome::Exit);
+            }
+            LoginMode::Check => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _: Result<(), std::convert::Infallible> = run_action_panel(
+                    "Quick Check",
+                    "Checking local session + live status",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        crate::health_check::run_health_check_with(
+                            crate::health_check::HealthCheckOptions {
+                                force_refresh: false,
+                                live_probe: true,
+                                ..Default::default()
+                            },
+                            &mut panel_out,
+                        )
+                        .await;
+                        (panel_out, Ok(()))
+                    },
+                )
+                .await;
+            }
+            LoginMode::DeepCheck => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _: Result<(), std::convert::Infallible> = run_action_panel(
+                    "Deep Check",
+                    "Refreshing and testing all accounts",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        crate::health_check::run_health_check_with(
+                            crate::health_check::HealthCheckOptions {
+                                force_refresh: true,
+                                live_probe: true,
+                                ..Default::default()
+                            },
+                            &mut panel_out,
+                        )
+                        .await;
+                        (panel_out, Ok(()))
+                    },
+                )
+                .await;
+            }
+            LoginMode::Forecast => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _: Result<(), std::convert::Infallible> = run_action_panel(
+                    "Best Account",
+                    "Comparing accounts",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        let args = vec!["--live".to_string()];
+                        let _ = crate::commands::forecast::run_forecast_command(
+                            &args,
+                            &mut panel_out,
+                        )
+                        .await;
+                        (panel_out, Ok(()))
+                    },
+                )
+                .await;
+            }
+            LoginMode::Fix => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _: Result<(), std::convert::Infallible> = run_action_panel(
+                    "Auto-Fix",
+                    "Checking and fixing common issues",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        let args = vec!["--live".to_string()];
+                        let _ = crate::repair::fix::run_fix(&args, &mut panel_out).await;
+                        (panel_out, Ok(()))
+                    },
+                )
+                .await;
+            }
+            LoginMode::Settings => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _ = configure_unified_settings(Some(&display_settings)).await;
+            }
+            LoginMode::VerifyFlagged => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let _: Result<(), std::convert::Infallible> = run_action_panel(
+                    "Problem Account Check",
+                    "Checking problem accounts",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        let _ = crate::repair::verify_flagged::run_verify_flagged(
+                            &[],
+                            &mut panel_out,
+                        )
+                        .await;
+                        (panel_out, Ok(()))
+                    },
+                )
+                .await;
+            }
+            LoginMode::Fresh => {
+                if !menu_result.delete_all {
+                    continue;
+                }
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let panel_result: Result<(), String> = run_action_panel(
+                    "Reset Accounts",
+                    "Deleting all saved accounts",
+                    out,
+                    Some(&display_settings),
+                    |mut panel_out| async move {
+                        match clear_accounts().await {
+                            Ok(()) => {
+                                panel_out.info(
+                                    "Cleared saved accounts from active storage. Recovery snapshots remain available.",
+                                );
+                                (panel_out, Ok(()))
+                            }
+                            Err(error) => (panel_out, Err(error.to_string())),
+                        }
+                    },
+                )
+                .await;
+                panel_result?;
+            }
+            LoginMode::Manage => {
+                clear_menu_quota_auto_refresh_skip(menu_state);
+                let requires_interactive_oauth = menu_result.refresh_account_index.is_some();
+                if requires_interactive_oauth {
+                    // Interactive OAuth prompts need the real terminal — the
+                    // action panel would capture output and break them.
+                    handle_manage_action(&mut current_storage, &menu_result, out)
+                        .await
+                        .map_err(|error| error.message().to_string())?;
+                } else {
+                    let storage_ref = &mut current_storage;
+                    let menu_result_ref = &menu_result;
+                    let panel_result: Result<(), CodexError> = run_action_panel(
+                        "Applying Change",
+                        "Updating selected account",
+                        out,
+                        Some(&display_settings),
+                        move |mut panel_out| async move {
+                            let result =
+                                handle_manage_action(storage_ref, menu_result_ref, &mut panel_out)
+                                    .await;
+                            (panel_out, result)
+                        },
+                    )
+                    .await;
+                    if let Err(error) = panel_result {
+                        return Err(error.message().to_string());
+                    }
+                }
+            }
+            LoginMode::Add => {
+                drain_pending_menu_quota_refresh(menu_state).await;
+                return Ok(DashboardOutcome::AddAccount);
+            }
+        }
+    }
+}
+
+/// TS `loadNamedBackupsForOnboarding` — onboarding-only discovery; a
+/// non-ENOENT failure surfaces the frozen warning string and continues with
+/// browser/manual sign-in only.
+async fn load_named_backups_for_onboarding(
+    existing_count: usize,
+    warning: &mut Option<String>,
+    out: &mut CliOut,
+) -> Vec<NamedBackupSummary> {
+    if existing_count > 0 {
+        *warning = None;
+        return Vec::new();
+    }
+    *warning = None;
+    match get_named_backups().await {
+        Ok(backups) => backups,
+        Err(error) => {
+            let code = error.code().to_string();
+            create_logger("codex-manager").debug(
+                "getNamedBackups failed, skipping restore option",
+                Some(&serde_json::json!({
+                    "code": code,
+                    "error": error.message(),
+                })),
+            );
+            if !code.is_empty() && code != "ENOENT" {
+                let text =
+                    "Named backup discovery failed. Continuing with browser or manual sign-in only.";
+                *warning = Some(text.to_string());
+                out.warn(text);
+            } else {
+                *warning = None;
+            }
+            Vec::new()
+        }
+    }
+}
+
+/// The Load Backup panel action: restore without persisting, then persist +
+/// sync through `persistAndSyncSelectedAccount` with
+/// `preserveActiveIndexByFamily: true` and switch reason `"restore"`.
+async fn restore_backup_action(
+    backup_path: &str,
+    backup_file_name: &str,
+    out: &mut CliOut,
+) -> Result<(), RestoreActionError> {
+    let restored_storage: AccountStorageV3 =
+        restore_accounts_from_backup(backup_path, Some(false))
+            .await
+            .map_err(|error| {
+                if matches!(error, CodexError::Storage { .. }) {
+                    RestoreActionError::Storage(error)
+                } else {
+                    RestoreActionError::Message(error.message().to_string())
+                }
+            })?;
+    let target_index = resolve_active_index(&restored_storage, ModelFamily::Codex);
+    if restored_storage.accounts.get(target_index).is_none() {
+        // TS: persistAndSyncSelectedAccount throws `Account ${parsed} not
+        // found.` and the restore catch prints it.
+        return Err(RestoreActionError::Message(format!(
+            "Account {} not found.",
+            target_index + 1
+        )));
+    }
+    let account_count = restored_storage.accounts.len();
+    let outcome = persist_and_sync_selected_account(PersistSelectedAccountParams {
+        storage: restored_storage,
+        target_index,
+        parsed: target_index as i64 + 1,
+        switch_reason: PersistedSwitchReason::Restore,
+        initial_sync_id_token: None,
+        preserve_active_index_by_family: true,
+        set_pin: false,
+        clear_pin: false,
+        bump_affinity_generation: false,
+    })
+    .await;
+    out.info(ui_copy::oauth::restore_backup_loaded(
+        backup_file_name,
+        account_count as i64,
+    ));
+    if !outcome.synced {
+        out.warn(ui_copy::oauth::RESTORE_BACKUP_SYNC_WARNING);
+    }
+    Ok(())
+}
+
+async fn run_auth_login_flow(login_options: &AuthLoginOptions, out: &mut CliOut) -> i32 {
+    cma_storage::facade::set_storage_path(None);
+    let mut menu_state = MenuQuotaRefreshState::new();
+    // Explicit transport flags bypass the dashboard even when accounts exist
+    // (`login --device-auth` from scripts).
+    let explicit_sign_in_mode = is_explicit_sign_in_mode(login_options);
+
+    'login_flow: loop {
+        let existing_storage = load_accounts().await.map(|loaded| loaded.storage);
+        if !explicit_sign_in_mode
+            && existing_storage
+                .as_ref()
+                .is_some_and(|storage| !storage.accounts.is_empty())
+        {
+            match run_login_dashboard_loop(&mut menu_state, out).await {
+                Ok(DashboardOutcome::Exit) => return 0,
+                Ok(DashboardOutcome::AddAccount) => {}
+                Err(message) => {
+                    // TS surfaced these as an uncaught rejection that ended
+                    // the CLI with a nonzero exit; print the message instead
+                    // of a Node stack trace.
+                    out.error(format!("Error: {message}"));
+                    return 1;
+                }
+            }
+        }
+
+        let refreshed_storage = load_accounts().await.map(|loaded| loaded.storage);
+        let mut existing_count = refreshed_storage
+            .as_ref()
+            .map_or(0, |storage| storage.accounts.len());
+        let mut force_new_login = existing_count > 0;
+        let mut onboarding_backup_discovery_warning: Option<String> = None;
+        let mut named_backups =
+            load_named_backups_for_onboarding(existing_count, &mut onboarding_backup_discovery_warning, out)
+                .await;
+
+        loop {
+            let latest_named_backup = named_backups.first().cloned();
+            let prefer_manual_mode = login_options.manual || is_browser_launch_suppressed();
+            let sign_in_mode = match resolve_forced_sign_in_mode(
+                login_options.device_auth,
+                prefer_manual_mode,
+            ) {
+                Some(mode) => mode,
+                None => prompt_oauth_sign_in_mode(
+                    latest_named_backup.as_ref(),
+                    onboarding_backup_discovery_warning.as_deref(),
+                ),
+            };
+
+            if sign_in_mode == OAuthSignInMode::Cancel {
+                if existing_count > 0 {
+                    out.info(style_prompt_text(
+                        ui_copy::oauth::CANCELLED_BACK_TO_MENU,
+                        PromptTone::Muted,
+                    ));
+                    continue 'login_flow;
+                }
+                out.info("Cancelled.");
+                return 0;
+            }
+
+            if sign_in_mode == OAuthSignInMode::RestoreBackup {
+                let Some(latest_available_backup) = named_backups.first().cloned() else {
+                    named_backups = load_named_backups_for_onboarding(
+                        existing_count,
+                        &mut onboarding_backup_discovery_warning,
+                        out,
+                    )
+                    .await;
+                    continue;
+                };
+                let restore_mode = prompt_backup_restore_mode(&latest_available_backup);
+                if restore_mode == BackupRestoreMode::Back {
+                    named_backups = load_named_backups_for_onboarding(
+                        existing_count,
+                        &mut onboarding_backup_discovery_warning,
+                        out,
+                    )
+                    .await;
+                    continue;
+                }
+
+                let selected_backup = if restore_mode == BackupRestoreMode::Manual {
+                    prompt_manual_backup_selection(&named_backups)
+                } else {
+                    Some(latest_available_backup)
+                };
+                let Some(selected_backup) = selected_backup else {
+                    named_backups = load_named_backups_for_onboarding(
+                        existing_count,
+                        &mut onboarding_backup_discovery_warning,
+                        out,
+                    )
+                    .await;
+                    continue;
+                };
+
+                let confirmed = confirm(
+                    &ui_copy::oauth::restore_backup_confirm(
+                        &selected_backup.file_name,
+                        selected_backup.account_count as i64,
+                    ),
+                    false,
+                )
+                .unwrap_or(false);
+                if !confirmed {
+                    named_backups = load_named_backups_for_onboarding(
+                        existing_count,
+                        &mut onboarding_backup_discovery_warning,
+                        out,
+                    )
+                    .await;
+                    continue;
+                }
+
+                let display_settings = load_dashboard_display_settings().await;
+                apply_ui_theme_from_dashboard_settings(&display_settings);
+                let backup_path = selected_backup.path.clone();
+                let backup_file_name = selected_backup.file_name.clone();
+                let panel_result: Result<(), RestoreActionError> = run_action_panel(
+                    "Load Backup",
+                    &format!("Loading {}", selected_backup.file_name),
+                    out,
+                    Some(&display_settings),
+                    move |mut panel_out| async move {
+                        let result =
+                            restore_backup_action(&backup_path, &backup_file_name, &mut panel_out)
+                                .await;
+                        (panel_out, result)
+                    },
+                )
+                .await;
+
+                match panel_result {
+                    Ok(()) => continue 'login_flow,
+                    Err(error) => {
+                        match &error {
+                            RestoreActionError::Storage(storage_error) => {
+                                out.error(format_storage_error_hint_for_code(
+                                    Some(storage_error.code()),
+                                    &selected_backup.path,
+                                ));
+                            }
+                            RestoreActionError::Message(message) => {
+                                out.error(format!("Backup restore failed: {message}"));
+                            }
+                        }
+                        let storage_after_restore_attempt =
+                            load_accounts().await.map(|loaded| loaded.storage);
+                        if storage_after_restore_attempt
+                            .is_some_and(|storage| !storage.accounts.is_empty())
+                        {
+                            continue 'login_flow;
+                        }
+                        named_backups = load_named_backups_for_onboarding(
+                            existing_count,
+                            &mut onboarding_backup_discovery_warning,
+                            out,
+                        )
+                        .await;
+                        continue;
+                    }
+                }
+            }
+
+            if !matches!(
+                sign_in_mode,
+                OAuthSignInMode::Browser | OAuthSignInMode::Manual | OAuthSignInMode::Device
+            ) {
+                continue;
+            }
+
+            let token_result = run_sign_in_flow(force_new_login, sign_in_mode, None).await;
+            let tokens = match token_result {
+                TokenResult::Success(tokens) => tokens,
+                failure => {
+                    if is_oauth_cancellation(&failure) {
+                        // Explicit mode bypassed the dashboard; falling back
+                        // to it would trap the user in the same transport.
+                        if explicit_sign_in_mode {
+                            out.info("Cancelled.");
+                            return 0;
+                        }
+                        if existing_count > 0 {
+                            out.info(style_prompt_text(
+                                ui_copy::oauth::CANCELLED_BACK_TO_MENU,
+                                PromptTone::Muted,
+                            ));
+                            continue 'login_flow;
+                        }
+                        out.info("Cancelled.");
+                        return 0;
+                    }
+                    let detail = match &failure {
+                        TokenResult::Failed(failed) => failed
+                            .message
+                            .clone()
+                            .or_else(|| failed.reason.map(|reason| reason.as_str().to_string()))
+                            .unwrap_or_else(|| "unknown error".to_string()),
+                        TokenResult::Success(_) => unreachable!(),
+                    };
+                    out.error(format!("Login failed: {detail}"));
+                    return 1;
+                }
+            };
+
+            let resolved = resolve_account_selection(&tokens, login_options.org.as_deref());
+            let persist_outcome = match persist_account_pool(std::slice::from_ref(&resolved), false).await {
+                Ok(outcome) => outcome,
+                Err(error) => {
+                    out.error(format!("Error: {}", error.message()));
+                    return 1;
+                }
+            };
+            sync_selection_to_codex(&resolved).await;
+
+            let latest_storage = load_accounts().await.map(|loaded| loaded.storage);
+            let count = latest_storage.map_or(1, |storage| storage.accounts.len());
+            existing_count = count;
+            named_backups = Vec::new();
+            onboarding_backup_discovery_warning = None;
+            out.info(outcome_message(persist_outcome, count));
+            out.info("Next steps:");
+            out.info("  codex-multi-auth status  Check that the wrapper is active.");
+            out.info("  codex-multi-auth check   Confirm your saved accounts look healthy.");
+            out.info("  codex-multi-auth list    Review saved accounts before switching.");
+
+            if count >= ACCOUNT_LIMITS.max_accounts {
+                out.info(format!(
+                    "Reached maximum account limit ({}).",
+                    ACCOUNT_LIMITS.max_accounts
+                ));
+                // In explicit mode the dashboard is bypassed, so falling out
+                // of the inner loop would silently start another sign-in
+                // session despite the cap.
+                if explicit_sign_in_mode {
+                    return 0;
+                }
+                break;
+            }
+
+            let add_another = prompt_add_another_account(count as i64);
+            if !add_another {
+                if explicit_sign_in_mode {
+                    return 0;
+                }
+                break;
+            }
+            force_new_login = true;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::dispatcher::OutLine;
+
+    // Port of the login-flow arg handling assertions: parse errors print the
+    // message plus usage and exit 1; --help exits 0 silently (the parent
+    // dispatcher owns the usage print).
+    #[tokio::test]
+    async fn parse_error_prints_message_and_usage_then_returns_1() {
+        let mut out = CliOut::capture();
+        let code = run_auth_login(&["--bogus".to_string()], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(out.error_text(), "Unknown login option: --bogus");
+        // printUsage output follows on stdout.
+        assert!(out.info_text().contains("Codex Multi-Auth CLI"));
+    }
+
+    #[tokio::test]
+    async fn device_auth_combined_with_manual_is_rejected() {
+        let mut out = CliOut::capture();
+        let code = run_auth_login(
+            &["--device-auth".to_string(), "--manual".to_string()],
+            &mut out,
+        )
+        .await;
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "Cannot combine --device-auth with --manual"
+        );
+    }
+
+    // Port of test/login-flow.test.ts "rejects --org without a value and
+    // prints usage".
+    #[tokio::test]
+    async fn org_without_value_is_rejected_with_usage() {
+        let mut out = CliOut::capture();
+        let code = run_auth_login(&["--org".to_string()], &mut out).await;
+        assert_eq!(code, 1);
+        assert_eq!(
+            out.error_text(),
+            "Missing value for --org. Usage: codex-multi-auth login --org <org_id>"
+        );
+        assert!(out.info_text().contains("Codex Multi-Auth CLI"));
+    }
+
+    // Port of "treats a missing backup directory as normal, without warning".
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn missing_backup_directory_is_silent() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut warning: Option<String> = None;
+        let mut out = CliOut::capture();
+        let backups = load_named_backups_for_onboarding(0, &mut warning, &mut out).await;
+        assert!(backups.is_empty());
+        assert!(warning.is_none());
+        assert_eq!(out.warn_text(), "");
+    }
+
+    // Discovery is skipped entirely (and the warning cleared) once accounts
+    // exist — onboarding-only behavior.
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn backup_discovery_skipped_when_accounts_exist() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        let mut warning = Some("stale".to_string());
+        let mut out = CliOut::capture();
+        let backups = load_named_backups_for_onboarding(2, &mut warning, &mut out).await;
+        assert!(backups.is_empty());
+        assert!(warning.is_none());
+        assert!(out.lines().is_empty());
+    }
+
+    #[tokio::test]
+    async fn help_returns_0_without_printing() {
+        let mut out = CliOut::capture();
+        let code = run_auth_login(&["--help".to_string()], &mut out).await;
+        assert_eq!(code, 0);
+        assert_eq!(out.lines(), &[] as &[OutLine]);
+    }
+
+    #[test]
+    fn outcome_message_matches_issue_512_wording() {
+        assert_eq!(
+            outcome_message(Some(AccountPoolWriteOutcome::Rebound), 3),
+            "Rebound workspace for existing account. Total: 3"
+        );
+        assert_eq!(
+            outcome_message(Some(AccountPoolWriteOutcome::Updated), 2),
+            "Updated existing account. Total: 2"
+        );
+        assert_eq!(
+            outcome_message(Some(AccountPoolWriteOutcome::Inserted), 4),
+            "Added account. Total: 4"
+        );
+        assert_eq!(outcome_message(None, 1), "Added account. Total: 1");
+    }
+
+    #[test]
+    fn explicit_mode_covers_device_and_manual_flags() {
+        let device = AuthLoginOptions {
+            manual: false,
+            device_auth: true,
+            org: None,
+        };
+        let manual = AuthLoginOptions {
+            manual: true,
+            device_auth: false,
+            org: None,
+        };
+        let neither = AuthLoginOptions {
+            manual: false,
+            device_auth: false,
+            org: None,
+        };
+        assert!(is_explicit_sign_in_mode(&device));
+        assert!(is_explicit_sign_in_mode(&manual));
+        assert!(!is_explicit_sign_in_mode(&neither));
+    }
+
+    #[test]
+    fn forced_sign_in_mode_prefers_device_then_manual() {
+        assert_eq!(
+            resolve_forced_sign_in_mode(true, true),
+            Some(OAuthSignInMode::Device)
+        );
+        assert_eq!(
+            resolve_forced_sign_in_mode(false, true),
+            Some(OAuthSignInMode::Manual)
+        );
+        assert_eq!(resolve_forced_sign_in_mode(false, false), None);
+    }
+
+    #[test]
+    fn menu_quota_state_generation_invalidates_skip() {
+        let state = MenuQuotaRefreshState::new();
+        state.shared.skip_next.store(true, Ordering::SeqCst);
+        let generation_before = state.shared.generation.load(Ordering::SeqCst);
+        clear_menu_quota_auto_refresh_skip(&state);
+        assert!(!state.shared.skip_next.load(Ordering::SeqCst));
+        assert_eq!(
+            state.shared.generation.load(Ordering::SeqCst),
+            generation_before + 1
+        );
+    }
+
+    #[tokio::test]
+    async fn drain_awaits_and_clears_the_pending_handle() {
+        let mut state = MenuQuotaRefreshState::new();
+        let shared = state.shared.clone();
+        state.pending = Some(tokio::spawn(async move {
+            shared.skip_next.store(true, Ordering::SeqCst);
+        }));
+        drain_pending_menu_quota_refresh(&mut state).await;
+        assert!(state.pending.is_none());
+        assert!(state.shared.skip_next.load(Ordering::SeqCst));
+        assert!(!state.has_pending());
+    }
+}
diff --git a/crates/manager/src/login/manual_callback.rs b/crates/manager/src/login/manual_callback.rs
new file mode 100644
index 000000000..b64a86b80
--- /dev/null
+++ b/crates/manager/src/login/manual_callback.rs
@@ -0,0 +1,133 @@
+//! Port of `lib/codex-manager/manual-callback.ts` — pure classification of a
+//! manually pasted OAuth callback.
+//!
+//! Splitting `invalid` and `state-mismatch` out from `cancelled` is the fix
+//! for the issue #512 follow-up: a malformed or wrong-attempt callback URL
+//! must NOT print `Cancelled.` and hide the real validation error.
+
+use cma_auth::oauth::parse_authorization_input;
+
+/// `ManualCallbackClassification`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ManualCallbackClassification {
+    Code { code: String },
+    Cancelled,
+    Invalid,
+    StateMismatch,
+}
+
+const CANCEL_KEYWORDS: [&str; 5] = ["", "q", "quit", "cancel", "back"];
+const ESC_CHARACTER: char = '\u{001b}';
+
+/// `classifyManualCallbackInput(answer, expectedState)` — pure and I/O-free.
+///
+/// `answer` is `None` when the input stream closed before any line was read
+/// (treated as a cancellation).
+pub fn classify_manual_callback_input(
+    answer: Option<&str>,
+    expected_state: &str,
+) -> ManualCallbackClassification {
+    let Some(answer) = answer else {
+        return ManualCallbackClassification::Cancelled;
+    };
+    if answer.contains(ESC_CHARACTER) {
+        return ManualCallbackClassification::Cancelled;
+    }
+    let normalized = answer.trim().to_lowercase();
+    if CANCEL_KEYWORDS.contains(&normalized.as_str()) {
+        return ManualCallbackClassification::Cancelled;
+    }
+    let parsed = parse_authorization_input(answer);
+    let (Some(code), Some(state)) = (parsed.code, parsed.state) else {
+        return ManualCallbackClassification::Invalid;
+    };
+    if code.is_empty() || state.is_empty() {
+        return ManualCallbackClassification::Invalid;
+    }
+    if state != expected_state {
+        return ManualCallbackClassification::StateMismatch;
+    }
+    ManualCallbackClassification::Code { code }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const STATE: &str = "state-123";
+
+    fn callback_url(code: &str, state: &str) -> String {
+        format!("http://localhost:1455/auth/callback?code={code}&state={state}")
+    }
+
+    #[test]
+    fn closed_stream_is_cancelled() {
+        assert_eq!(
+            classify_manual_callback_input(None, STATE),
+            ManualCallbackClassification::Cancelled
+        );
+    }
+
+    #[test]
+    fn esc_character_anywhere_is_cancelled() {
+        assert_eq!(
+            classify_manual_callback_input(Some("\u{001b}[A"), STATE),
+            ManualCallbackClassification::Cancelled
+        );
+        assert_eq!(
+            classify_manual_callback_input(
+                Some(&format!("{}{}", callback_url("abc", STATE), '\u{001b}')),
+                STATE
+            ),
+            ManualCallbackClassification::Cancelled
+        );
+    }
+
+    #[test]
+    fn cancel_keywords_are_cancelled_case_insensitively() {
+        for keyword in ["", "  ", "q", "Q", "quit", "QUIT", "cancel", "Back"] {
+            assert_eq!(
+                classify_manual_callback_input(Some(keyword), STATE),
+                ManualCallbackClassification::Cancelled,
+                "keyword {keyword:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn missing_code_or_state_is_invalid_not_cancelled() {
+        assert_eq!(
+            classify_manual_callback_input(Some("http://localhost:1455/auth/callback?code=abc"), STATE),
+            ManualCallbackClassification::Invalid
+        );
+        assert_eq!(
+            classify_manual_callback_input(
+                Some("http://localhost:1455/auth/callback?state=state-123"),
+                STATE
+            ),
+            ManualCallbackClassification::Invalid
+        );
+        assert_eq!(
+            classify_manual_callback_input(Some("not a url at all"), STATE),
+            ManualCallbackClassification::Invalid
+        );
+    }
+
+    #[test]
+    fn wrong_state_is_a_state_mismatch() {
+        assert_eq!(
+            classify_manual_callback_input(Some(&callback_url("abc", "other-state")), STATE),
+            ManualCallbackClassification::StateMismatch
+        );
+    }
+
+    #[test]
+    fn matching_state_extracts_the_code() {
+        assert_eq!(
+            classify_manual_callback_input(Some(&callback_url("abc123", STATE)), STATE),
+            ManualCallbackClassification::Code {
+                code: "abc123".to_string()
+            }
+        );
+    }
+}
diff --git a/crates/manager/src/login/menu_actions.rs b/crates/manager/src/login/menu_actions.rs
new file mode 100644
index 000000000..161c3cf93
--- /dev/null
+++ b/crates/manager/src/login/menu_actions.rs
@@ -0,0 +1,912 @@
+//! Port of `lib/codex-manager/login-menu-actions.ts` — per-menu-item action
+//! handlers for the login dashboard: sign-in mode and backup-restore prompts
+//! plus the manage actions (switch/delete/toggle/refresh an account row).
+
+use cma_core::errors::CodexError;
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::schemas::account_storage::{
+    AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily,
+};
+use cma_core::token_utils::sanitize_email;
+use cma_storage::matching::{
+    find_matching_account_index, reconcile_pinned_account_index, AccountMatchOptions,
+    AccountSelectionCandidate,
+};
+use cma_storage::named_backups::NamedBackupSummary;
+use cma_storage::transactions::with_account_storage_transaction;
+use cma_tui::login_prompts::LoginMenuResult;
+use cma_tui::runtime_options::get_ui_runtime_options;
+use cma_tui::select::{select, MenuColor, MenuItem, SelectInputResult, SelectOptions};
+use cma_tui::ui_copy;
+
+use crate::commands::switch::run_switch_command;
+use crate::dispatcher::CliOut;
+use crate::formatters::account::format_backup_saved_at;
+use crate::formatters::text_style::{style_prompt_text, PromptTone};
+use crate::login::oauth::{
+    persist_account_pool, resolve_account_selection, run_oauth_flow, sync_selection_to_codex,
+    OAuthSignInMode,
+};
+
+/// TS `BackupRestoreMode`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackupRestoreMode {
+    Latest,
+    Manual,
+    Back,
+}
+
+/// Hotkey mapping for the sign-in mode menu (TS inline `onInput`).
+pub(crate) fn map_sign_in_hotkey(raw: &str, has_backup: bool) -> Option<OAuthSignInMode> {
+    match raw.to_lowercase().as_str() {
+        "q" => Some(OAuthSignInMode::Cancel),
+        "1" => Some(OAuthSignInMode::Browser),
+        "2" => Some(OAuthSignInMode::Manual),
+        "3" if has_backup => Some(OAuthSignInMode::RestoreBackup),
+        _ => None,
+    }
+}
+
+/// Hotkey mapping for the backup-restore mode menu.
+pub(crate) fn map_backup_restore_hotkey(raw: &str) -> Option<BackupRestoreMode> {
+    match raw.to_lowercase().as_str() {
+        "q" => Some(BackupRestoreMode::Back),
+        "1" => Some(BackupRestoreMode::Latest),
+        "2" => Some(BackupRestoreMode::Manual),
+        _ => None,
+    }
+}
+
+/// Build the sign-in mode menu items (TS `promptOAuthSignInMode` items).
+pub(crate) fn build_sign_in_menu_items(
+    backup_option: Option<&NamedBackupSummary>,
+) -> Vec<MenuItem<OAuthSignInMode>> {
+    let mut items: Vec<MenuItem<OAuthSignInMode>> = vec![
+        MenuItem::heading(ui_copy::oauth::SIGN_IN_HEADING, OAuthSignInMode::Cancel),
+        MenuItem::new(ui_copy::oauth::OPEN_BROWSER, OAuthSignInMode::Browser)
+            .with_color(MenuColor::Green),
+        MenuItem::new(ui_copy::oauth::MANUAL_MODE, OAuthSignInMode::Manual)
+            .with_color(MenuColor::Yellow),
+    ];
+    if let Some(backup) = backup_option {
+        items.push(MenuItem::separator(OAuthSignInMode::Cancel));
+        items.push(MenuItem::heading(
+            ui_copy::oauth::RESTORE_HEADING,
+            OAuthSignInMode::Cancel,
+        ));
+        items.push(
+            MenuItem::new(
+                ui_copy::oauth::RESTORE_SAVED_BACKUP,
+                OAuthSignInMode::RestoreBackup,
+            )
+            .with_hint(ui_copy::oauth::load_last_backup_hint(
+                &backup.file_name,
+                backup.account_count as i64,
+                &format_backup_saved_at(backup.mtime_ms),
+            ))
+            .with_color(MenuColor::Cyan),
+        );
+    }
+    items.push(MenuItem::separator(OAuthSignInMode::Cancel));
+    items.push(MenuItem::new(ui_copy::oauth::BACK, OAuthSignInMode::Cancel).with_color(MenuColor::Red));
+    items
+}
+
+/// TS `promptOAuthSignInMode(backupOption, backupDiscoveryWarning)` —
+/// non-TTY → browser; `null` selection → cancel.
+pub fn prompt_oauth_sign_in_mode(
+    backup_option: Option<&NamedBackupSummary>,
+    backup_discovery_warning: Option<&str>,
+) -> OAuthSignInMode {
+    if !cma_tui::ansi::is_tty() {
+        return OAuthSignInMode::Browser;
+    }
+
+    let ui = get_ui_runtime_options();
+    let items = build_sign_in_menu_items(backup_option);
+    let has_backup = backup_option.is_some();
+
+    let mut options: SelectOptions<'_, OAuthSignInMode> =
+        SelectOptions::new(ui_copy::oauth::CHOOSE_MODE_TITLE);
+    options.subtitle = Some(match backup_discovery_warning {
+        Some(warning) => format!("{} {warning}", ui_copy::oauth::CHOOSE_MODE_SUBTITLE),
+        None => ui_copy::oauth::CHOOSE_MODE_SUBTITLE.to_string(),
+    });
+    options.help = Some(
+        if has_backup {
+            ui_copy::oauth::CHOOSE_MODE_HELP_WITH_BACKUP
+        } else {
+            ui_copy::oauth::CHOOSE_MODE_HELP
+        }
+        .to_string(),
+    );
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Minimal);
+    options.allow_escape = Some(false);
+    options.on_input = Some(Box::new(move |raw, _ctx| {
+        match map_sign_in_hotkey(raw, has_backup) {
+            Some(mode) => SelectInputResult::Finish(Some(mode)),
+            None => SelectInputResult::Ignored,
+        }
+    }));
+
+    select(&items, options)
+        .ok()
+        .flatten()
+        .unwrap_or(OAuthSignInMode::Cancel)
+}
+
+/// TS `promptBackupRestoreMode(latestBackup)` — non-TTY → latest.
+pub fn prompt_backup_restore_mode(latest_backup: &NamedBackupSummary) -> BackupRestoreMode {
+    if !cma_tui::ansi::is_tty() {
+        return BackupRestoreMode::Latest;
+    }
+
+    let ui = get_ui_runtime_options();
+    let items: Vec<MenuItem<BackupRestoreMode>> = vec![
+        MenuItem::new(ui_copy::oauth::LOAD_LAST_BACKUP, BackupRestoreMode::Latest)
+            .with_hint(format!(
+                "{}\n{}",
+                ui_copy::oauth::RESTORE_BACKUP_LATEST_HINT,
+                ui_copy::oauth::manual_backup_hint(
+                    latest_backup.account_count as i64,
+                    &format_backup_saved_at(latest_backup.mtime_ms),
+                )
+            ))
+            .with_color(MenuColor::Cyan),
+        MenuItem::new(
+            ui_copy::oauth::CHOOSE_BACKUP_MANUALLY,
+            BackupRestoreMode::Manual,
+        )
+        .with_color(MenuColor::Yellow),
+        MenuItem::new(ui_copy::oauth::BACK, BackupRestoreMode::Back).with_color(MenuColor::Red),
+    ];
+
+    let mut options: SelectOptions<'_, BackupRestoreMode> =
+        SelectOptions::new(ui_copy::oauth::RESTORE_BACKUP_TITLE);
+    options.subtitle = Some(ui_copy::oauth::RESTORE_BACKUP_SUBTITLE.to_string());
+    options.help = Some(ui_copy::oauth::RESTORE_BACKUP_HELP.to_string());
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Minimal);
+    options.allow_escape = Some(false);
+    options.on_input = Some(Box::new(|raw, _ctx| match map_backup_restore_hotkey(raw) {
+        Some(mode) => SelectInputResult::Finish(Some(mode)),
+        None => SelectInputResult::Ignored,
+    }));
+
+    select(&items, options)
+        .ok()
+        .flatten()
+        .unwrap_or(BackupRestoreMode::Back)
+}
+
+/// TS `promptManualBackupSelection(backups)` — non-TTY → first backup.
+pub fn prompt_manual_backup_selection(
+    backups: &[NamedBackupSummary],
+) -> Option<NamedBackupSummary> {
+    if !cma_tui::ansi::is_tty() {
+        return backups.first().cloned();
+    }
+
+    let ui = get_ui_runtime_options();
+    let mut items: Vec<MenuItem<Option<NamedBackupSummary>>> = backups
+        .iter()
+        .map(|backup| {
+            MenuItem::new(backup.file_name.clone(), Some(backup.clone()))
+                .with_hint(ui_copy::oauth::manual_backup_hint(
+                    backup.account_count as i64,
+                    &format_backup_saved_at(backup.mtime_ms),
+                ))
+                .with_color(MenuColor::Cyan)
+        })
+        .collect();
+    items.push(MenuItem::new(ui_copy::oauth::BACK, None).with_color(MenuColor::Red));
+
+    let mut options: SelectOptions<'_, Option<NamedBackupSummary>> =
+        SelectOptions::new(ui_copy::oauth::MANUAL_BACKUP_TITLE);
+    options.subtitle = Some(ui_copy::oauth::MANUAL_BACKUP_SUBTITLE.to_string());
+    options.help = Some(ui_copy::oauth::MANUAL_BACKUP_HELP.to_string());
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Minimal);
+    options.allow_escape = Some(false);
+    options.on_input = Some(Box::new(|raw, _ctx| {
+        if raw.to_lowercase() == "q" {
+            // TS `return null` — finish the select with a null result.
+            SelectInputResult::Finish(None)
+        } else {
+            SelectInputResult::Ignored
+        }
+    }));
+
+    select(&items, options).ok().flatten().flatten()
+}
+
+/// TS `adjustManageActionSelectionIndex(currentIndex, removedIndex,
+/// remainingCount)`.
+pub(crate) fn adjust_manage_action_selection_index(
+    current_index: Option<i64>,
+    removed_index: i64,
+    remaining_count: i64,
+) -> i64 {
+    if remaining_count <= 0 {
+        return 0;
+    }
+    let Some(current_index) = current_index else {
+        return 0;
+    };
+    if current_index < 0 {
+        return 0;
+    }
+    if current_index < removed_index {
+        return std::cmp::min(current_index, remaining_count - 1);
+    }
+    if current_index > removed_index {
+        return current_index - 1;
+    }
+    std::cmp::min(removed_index, remaining_count - 1)
+}
+
+/// TS `resetManageActionSelection(storage, removedIndex)` — remap
+/// `activeIndex` and every `activeIndexByFamily` entry after a row splice.
+pub(crate) fn reset_manage_action_selection(storage: &mut AccountStorageV3, removed_index: i64) {
+    let remaining_count = storage.accounts.len() as i64;
+    if remaining_count <= 0 {
+        storage.active_index = 0;
+        let mut by_family = ActiveIndexByFamily::default();
+        for family in MODEL_FAMILIES {
+            by_family.set(family, Some(0));
+        }
+        storage.active_index_by_family = Some(by_family);
+        return;
+    }
+
+    let previous_active_index = storage.active_index;
+    let previous_by_family = storage.active_index_by_family.clone().unwrap_or_default();
+    storage.active_index = adjust_manage_action_selection_index(
+        Some(previous_active_index),
+        removed_index,
+        remaining_count,
+    );
+    let mut by_family = ActiveIndexByFamily::default();
+    for family in MODEL_FAMILIES {
+        let previous = previous_by_family
+            .get(family)
+            .unwrap_or(previous_active_index);
+        by_family.set(
+            family,
+            Some(adjust_manage_action_selection_index(
+                Some(previous),
+                removed_index,
+                remaining_count,
+            )),
+        );
+    }
+    storage.active_index_by_family = Some(by_family);
+}
+
+/// TS `replaceManageActionStorage(target, source)` — mirror the persisted
+/// storage (including `pinnedAccountIndex`, #474) back into the caller's
+/// in-memory view. The TS `{...source.activeIndexByFamily}` spread produces
+/// an (empty) object even when the source map is undefined; port that
+/// exactly.
+pub(crate) fn replace_manage_action_storage(
+    target: &mut AccountStorageV3,
+    source: &AccountStorageV3,
+) {
+    target.version = source.version;
+    target.accounts = source.accounts.clone();
+    target.active_index = source.active_index;
+    target.active_index_by_family =
+        Some(source.active_index_by_family.clone().unwrap_or_default());
+    target.pinned_account_index = source.pinned_account_index;
+}
+
+/// TS `resolveManageActionAccountIndex(storage, fallbackIndex, account)` —
+/// identity match with unique-accountId fallback; when the account object is
+/// present a failed match returns `None` (do NOT fall back to the raw index).
+pub(crate) fn resolve_manage_action_account_index(
+    storage: &AccountStorageV3,
+    fallback_index: i64,
+    account: Option<&AccountMetadataV3>,
+) -> Option<usize> {
+    if let Some(account) = account {
+        return find_matching_account_index(
+            &storage.accounts,
+            &AccountSelectionCandidate {
+                account_id: account.account_id.clone(),
+                email: account.email.clone(),
+                refresh_token: Some(account.refresh_token.clone()),
+            },
+            AccountMatchOptions {
+                allow_unique_account_id_fallback_without_email: true,
+            },
+        );
+    }
+    if fallback_index >= 0 && (fallback_index as usize) < storage.accounts.len() {
+        Some(fallback_index as usize)
+    } else {
+        None
+    }
+}
+
+/// TS `matchesManageActionAccount(account, candidate)` — accountId equality
+/// when either has one, else refreshToken AND sanitized-email equality.
+pub(crate) fn matches_manage_action_account(
+    account: Option<&AccountMetadataV3>,
+    candidate: Option<&AccountMetadataV3>,
+) -> bool {
+    let (Some(account), Some(candidate)) = (account, candidate) else {
+        return false;
+    };
+    if account.account_id.is_some() || candidate.account_id.is_some() {
+        return account.account_id == candidate.account_id;
+    }
+    account.refresh_token == candidate.refresh_token
+        && sanitize_email(account.email.as_deref()) == sanitize_email(candidate.email.as_deref())
+}
+
+/// TS `handleManageAction(storage, menuResult)`.
+///
+/// Mutates the caller's in-memory `storage` view to mirror what was persisted
+/// (delete/toggle) and prints the user-facing confirmation lines. Storage
+/// transaction failures propagate (the TS exceptions did too).
+pub async fn handle_manage_action(
+    storage: &mut AccountStorageV3,
+    menu_result: &LoginMenuResult,
+    out: &mut CliOut,
+) -> Result<(), CodexError> {
+    if let Some(index) = menu_result.switch_account_index {
+        let _ = run_switch_command(&[(index + 1).to_string()], out).await;
+        return Ok(());
+    }
+
+    if let Some(idx) = menu_result.delete_account_index {
+        let selected_account = usize::try_from(idx)
+            .ok()
+            .and_then(|i| storage.accounts.get(i))
+            .cloned();
+        let mut deleted = false;
+        if let Some(selected_account) = selected_account {
+            let fallback = storage.clone();
+            let persisted: Option<AccountStorageV3> =
+                with_account_storage_transaction(move |loaded_storage, persist| async move {
+                    let mut next_storage = loaded_storage.unwrap_or(fallback);
+                    let Some(next_index) = resolve_manage_action_account_index(
+                        &next_storage,
+                        idx,
+                        Some(&selected_account),
+                    ) else {
+                        return Ok(None);
+                    };
+                    if !matches_manage_action_account(
+                        Some(&selected_account),
+                        next_storage.accounts.get(next_index),
+                    ) {
+                        return Ok(None);
+                    }
+                    // Capture the pinned account BEFORE the splice so the
+                    // manual pin can be followed by identity afterwards (#474).
+                    let pinned_account = next_storage
+                        .pinned_account_index
+                        .and_then(|pin| usize::try_from(pin).ok())
+                        .and_then(|pin| next_storage.accounts.get(pin))
+                        .cloned();
+                    next_storage.accounts.remove(next_index);
+                    reset_manage_action_selection(&mut next_storage, next_index as i64);
+                    next_storage.pinned_account_index = reconcile_pinned_account_index(
+                        pinned_account.as_ref(),
+                        &next_storage.accounts,
+                    )
+                    .map(|pin| pin as i64);
+                    persist.persist(&next_storage).await?;
+                    Ok(Some(next_storage))
+                })
+                .await?;
+            if let Some(next_storage) = persisted {
+                replace_manage_action_storage(storage, &next_storage);
+                deleted = true;
+            }
+        }
+        if deleted {
+            out.info(format!("Deleted account {}.", idx + 1));
+        }
+        return Ok(());
+    }
+
+    if let Some(idx) = menu_result.toggle_account_index {
+        let selected_account = usize::try_from(idx)
+            .ok()
+            .and_then(|i| storage.accounts.get(i))
+            .cloned();
+        let mut next_enabled_state: Option<bool> = None;
+        if let Some(selected_account) = selected_account {
+            let fallback = storage.clone();
+            let persisted: Option<(AccountStorageV3, bool)> =
+                with_account_storage_transaction(move |loaded_storage, persist| async move {
+                    let mut next_storage = loaded_storage.unwrap_or(fallback);
+                    let Some(next_index) = resolve_manage_action_account_index(
+                        &next_storage,
+                        idx,
+                        Some(&selected_account),
+                    ) else {
+                        return Ok(None);
+                    };
+                    if !matches_manage_action_account(
+                        Some(&selected_account),
+                        next_storage.accounts.get(next_index),
+                    ) {
+                        return Ok(None);
+                    }
+                    let Some(next_account) = next_storage.accounts.get_mut(next_index) else {
+                        return Ok(None);
+                    };
+                    // TS `nextAccount.enabled = nextAccount.enabled === false`
+                    // — flip: disabled → true, everything else → false.
+                    let flipped = next_account.enabled == Some(false);
+                    next_account.enabled = Some(flipped);
+                    let enabled_now = next_account.enabled != Some(false);
+                    persist.persist(&next_storage).await?;
+                    Ok(Some((next_storage, enabled_now)))
+                })
+                .await?;
+            if let Some((next_storage, enabled_now)) = persisted {
+                replace_manage_action_storage(storage, &next_storage);
+                next_enabled_state = Some(enabled_now);
+            }
+        }
+        if let Some(enabled) = next_enabled_state {
+            out.info(format!(
+                "{} account {}.",
+                if enabled { "Enabled" } else { "Disabled" },
+                idx + 1
+            ));
+        }
+        return Ok(());
+    }
+
+    if let Some(idx) = menu_result.refresh_account_index {
+        if usize::try_from(idx)
+            .ok()
+            .and_then(|i| storage.accounts.get(i))
+            .is_none()
+        {
+            return Ok(());
+        }
+
+        let sign_in_mode = prompt_oauth_sign_in_mode(None, None);
+        if sign_in_mode == OAuthSignInMode::Cancel {
+            out.info(style_prompt_text(
+                ui_copy::oauth::CANCELLED_BACK_TO_MENU,
+                PromptTone::Muted,
+            ));
+            return Ok(());
+        }
+        if sign_in_mode != OAuthSignInMode::Browser && sign_in_mode != OAuthSignInMode::Manual {
+            return Ok(());
+        }
+
+        let token_result = run_oauth_flow(true, sign_in_mode).await;
+        let tokens = match token_result {
+            cma_core::schemas::token::TokenResult::Success(tokens) => tokens,
+            cma_core::schemas::token::TokenResult::Failed(failure) => {
+                let detail = failure
+                    .message
+                    .clone()
+                    .or_else(|| failure.reason.map(|reason| reason.as_str().to_string()))
+                    .unwrap_or_else(|| "unknown error".to_string());
+                out.error(format!("Refresh failed: {detail}"));
+                return Ok(());
+            }
+        };
+
+        let resolved = resolve_account_selection(&tokens, None);
+        persist_account_pool(std::slice::from_ref(&resolved), false).await?;
+        sync_selection_to_codex(&resolved).await;
+        out.info(format!("Refreshed account {}.", idx + 1));
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::ModelFamily;
+    use cma_testkit::sandbox::EnvSandbox;
+    use cma_tui::login_prompts::LoginMode;
+    use serial_test::serial;
+
+    use crate::dispatcher::CliOut;
+
+    fn account(
+        refresh_token: &str,
+        account_id: Option<&str>,
+        email: Option<&str>,
+    ) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh_token.to_string(), 1, 1);
+        account.account_id = account_id.map(str::to_string);
+        account.email = email.map(str::to_string);
+        account
+    }
+
+    fn storage_with(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage
+    }
+
+    // Port of the adjustManageActionSelectionIndex table from
+    // test/login-menu-actions (delete-remap) assertions.
+    #[test]
+    fn adjust_index_remap_rules() {
+        // Empty pool → 0.
+        assert_eq!(adjust_manage_action_selection_index(Some(3), 1, 0), 0);
+        // Missing / negative current → 0.
+        assert_eq!(adjust_manage_action_selection_index(None, 1, 4), 0);
+        assert_eq!(adjust_manage_action_selection_index(Some(-2), 1, 4), 0);
+        // Below the removed index: value kept (clamped).
+        assert_eq!(adjust_manage_action_selection_index(Some(0), 2, 3), 0);
+        assert_eq!(adjust_manage_action_selection_index(Some(5), 6, 3), 2);
+        // Above the removed index: shift down one.
+        assert_eq!(adjust_manage_action_selection_index(Some(3), 1, 4), 2);
+        // Equal to the removed index: clamp to min(removed, remaining-1).
+        assert_eq!(adjust_manage_action_selection_index(Some(2), 2, 2), 1);
+        assert_eq!(adjust_manage_action_selection_index(Some(0), 0, 2), 0);
+    }
+
+    #[test]
+    fn reset_selection_empty_pool_zeroes_all_families() {
+        let mut storage = storage_with(vec![]);
+        storage.active_index = 3;
+        reset_manage_action_selection(&mut storage, 0);
+        assert_eq!(storage.active_index, 0);
+        let by_family = storage.active_index_by_family.expect("family map");
+        for family in MODEL_FAMILIES {
+            assert_eq!(by_family.get(family), Some(0));
+        }
+    }
+
+    #[test]
+    fn reset_selection_remaps_families_with_active_fallback() {
+        let mut storage = storage_with(vec![
+            account("token-a", None, None),
+            account("token-b", None, None),
+            account("token-c", None, None),
+        ]);
+        storage.active_index = 2;
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(ModelFamily::Codex, Some(1));
+        storage.active_index_by_family = Some(by_family);
+
+        // Remove index 1 (accounts len is already post-splice 3 in this
+        // synthetic setup; the remap only reads lengths).
+        reset_manage_action_selection(&mut storage, 1);
+        assert_eq!(storage.active_index, 1); // 2 > 1 → shift down.
+        let by_family = storage.active_index_by_family.expect("family map");
+        // codex had explicit 1 == removed → min(1, 2).
+        assert_eq!(by_family.get(ModelFamily::Codex), Some(1));
+        // Others fall back to previous activeIndex 2 → shifted to 1.
+        assert_eq!(by_family.get(ModelFamily::Gpt5Codex), Some(1));
+    }
+
+    #[test]
+    fn matches_account_identity_rules() {
+        let with_id = account("rt-1", Some("acc_1"), Some("a@example.com"));
+        let with_other_id = account("rt-1", Some("acc_2"), Some("a@example.com"));
+        let without_id = account("rt-1", None, Some("a@example.com"));
+        let email_case = account("rt-1", None, Some("A@Example.com "));
+        let other_token = account("rt-2", None, Some("a@example.com"));
+
+        // accountId equality wins when either side has one.
+        assert!(matches_manage_action_account(
+            Some(&with_id),
+            Some(&with_id)
+        ));
+        assert!(!matches_manage_action_account(
+            Some(&with_id),
+            Some(&with_other_id)
+        ));
+        assert!(!matches_manage_action_account(
+            Some(&with_id),
+            Some(&without_id)
+        ));
+        // Without ids: refreshToken AND sanitized email.
+        assert!(matches_manage_action_account(
+            Some(&without_id),
+            Some(&email_case)
+        ));
+        assert!(!matches_manage_action_account(
+            Some(&without_id),
+            Some(&other_token)
+        ));
+        assert!(!matches_manage_action_account(Some(&with_id), None));
+        assert!(!matches_manage_action_account(None, None));
+    }
+
+    #[test]
+    fn resolve_index_never_falls_back_to_raw_index_when_account_present() {
+        let storage = storage_with(vec![account("rt-a", None, Some("a@example.com"))]);
+        let missing = account("rt-zzz", None, Some("z@example.com"));
+        // Identity match fails → None even though fallback 0 is in range.
+        assert_eq!(
+            resolve_manage_action_account_index(&storage, 0, Some(&missing)),
+            None
+        );
+        // Without an account object the bounds-checked fallback applies.
+        assert_eq!(resolve_manage_action_account_index(&storage, 0, None), Some(0));
+        assert_eq!(resolve_manage_action_account_index(&storage, 5, None), None);
+        assert_eq!(resolve_manage_action_account_index(&storage, -1, None), None);
+    }
+
+    #[test]
+    fn replace_storage_mirrors_pin_and_materializes_family_map() {
+        let mut target = storage_with(vec![account("rt-old", None, None)]);
+        target.pinned_account_index = Some(7);
+
+        let mut source = storage_with(vec![account("rt-new", None, None)]);
+        source.active_index = 0;
+        source.pinned_account_index = None;
+        source.active_index_by_family = None;
+
+        replace_manage_action_storage(&mut target, &source);
+        assert_eq!(target.accounts.len(), 1);
+        assert_eq!(target.accounts[0].refresh_token, "rt-new");
+        // Pin cleared (mirrored from the persisted storage — #474).
+        assert_eq!(target.pinned_account_index, None);
+        // TS `{...undefined}` — an empty map object, not undefined.
+        assert_eq!(
+            target.active_index_by_family,
+            Some(ActiveIndexByFamily::default())
+        );
+    }
+
+    #[test]
+    fn sign_in_hotkeys_gate_backup_on_availability() {
+        assert_eq!(map_sign_in_hotkey("q", false), Some(OAuthSignInMode::Cancel));
+        assert_eq!(map_sign_in_hotkey("Q", false), Some(OAuthSignInMode::Cancel));
+        assert_eq!(
+            map_sign_in_hotkey("1", false),
+            Some(OAuthSignInMode::Browser)
+        );
+        assert_eq!(map_sign_in_hotkey("2", false), Some(OAuthSignInMode::Manual));
+        assert_eq!(map_sign_in_hotkey("3", false), None);
+        assert_eq!(
+            map_sign_in_hotkey("3", true),
+            Some(OAuthSignInMode::RestoreBackup)
+        );
+        assert_eq!(map_sign_in_hotkey("x", true), None);
+
+        assert_eq!(
+            map_backup_restore_hotkey("q"),
+            Some(BackupRestoreMode::Back)
+        );
+        assert_eq!(
+            map_backup_restore_hotkey("1"),
+            Some(BackupRestoreMode::Latest)
+        );
+        assert_eq!(
+            map_backup_restore_hotkey("2"),
+            Some(BackupRestoreMode::Manual)
+        );
+        assert_eq!(map_backup_restore_hotkey("9"), None);
+    }
+
+    async fn seed_disk(storage: &AccountStorageV3) {
+        cma_storage::facade::set_storage_path(None);
+        cma_storage::save::save_accounts(storage)
+            .await
+            .expect("seed accounts");
+    }
+
+    async fn disk_storage() -> AccountStorageV3 {
+        cma_storage::load::load_accounts()
+            .await
+            .expect("storage on disk")
+            .storage
+    }
+
+    // Port of test/login-menu-actions.test.ts "deletes inside the transaction
+    // and rebalances every selection index".
+    #[tokio::test]
+    #[serial(env)]
+    async fn delete_rebalances_every_selection_index() {
+        let _sandbox = EnvSandbox::new();
+        let mut storage = storage_with(vec![
+            account("rt-a", None, Some("a@example.com")),
+            account("rt-b", None, Some("b@example.com")),
+            account("rt-c", None, Some("c@example.com")),
+        ]);
+        storage.active_index = 2;
+        seed_disk(&storage).await;
+
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            delete_account_index: Some(1),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("delete succeeds");
+
+        assert_eq!(out.info_text(), "Deleted account 2.");
+        // The caller's in-memory view mirrors the persisted storage.
+        assert_eq!(storage.accounts.len(), 2);
+        assert_eq!(storage.accounts[0].refresh_token, "rt-a");
+        assert_eq!(storage.accounts[1].refresh_token, "rt-c");
+        assert_eq!(storage.active_index, 1); // 2 > removed 1 → shifted down.
+        let by_family = storage.active_index_by_family.clone().expect("family map");
+        for family in MODEL_FAMILIES {
+            assert_eq!(by_family.get(family), Some(1));
+        }
+        // And the disk agrees.
+        let persisted = disk_storage().await;
+        assert_eq!(persisted.accounts.len(), 2);
+        assert_eq!(persisted.active_index, 1);
+    }
+
+    // Port of "shifts the manual pin to follow its account when a
+    // lower-indexed account is deleted" (#474).
+    #[tokio::test]
+    #[serial(env)]
+    async fn delete_shifts_manual_pin_by_identity() {
+        let _sandbox = EnvSandbox::new();
+        let mut storage = storage_with(vec![
+            account("rt-a", Some("acc_a"), Some("a@example.com")),
+            account("rt-b", Some("acc_b"), Some("b@example.com")),
+            account("rt-c", Some("acc_c"), Some("c@example.com")),
+        ]);
+        storage.pinned_account_index = Some(2);
+        seed_disk(&storage).await;
+
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            delete_account_index: Some(0),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("delete succeeds");
+
+        assert_eq!(out.info_text(), "Deleted account 1.");
+        // The pinned account (acc_c) moved from slot 2 to slot 1.
+        assert_eq!(storage.pinned_account_index, Some(1));
+        assert_eq!(disk_storage().await.pinned_account_index, Some(1));
+    }
+
+    // Port of "clears the manual pin when the pinned account itself is
+    // deleted".
+    #[tokio::test]
+    #[serial(env)]
+    async fn delete_clears_pin_when_pinned_account_removed() {
+        let _sandbox = EnvSandbox::new();
+        let mut storage = storage_with(vec![
+            account("rt-a", Some("acc_a"), Some("a@example.com")),
+            account("rt-b", Some("acc_b"), Some("b@example.com")),
+        ]);
+        storage.pinned_account_index = Some(1);
+        seed_disk(&storage).await;
+
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            delete_account_index: Some(1),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("delete succeeds");
+
+        assert_eq!(out.info_text(), "Deleted account 2.");
+        assert_eq!(storage.pinned_account_index, None);
+        assert_eq!(disk_storage().await.pinned_account_index, None);
+    }
+
+    // Port of "becomes a no-op when the account vanished from storage":
+    // the in-memory row no longer exists on disk, so nothing is deleted and
+    // nothing is printed.
+    #[tokio::test]
+    #[serial(env)]
+    async fn delete_is_noop_when_account_vanished_from_disk() {
+        let _sandbox = EnvSandbox::new();
+        let on_disk = storage_with(vec![account("rt-a", None, Some("a@example.com"))]);
+        seed_disk(&on_disk).await;
+
+        // The caller's stale in-memory view still shows a second row.
+        let mut storage = storage_with(vec![
+            account("rt-a", None, Some("a@example.com")),
+            account("rt-gone", None, Some("gone@example.com")),
+        ]);
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            delete_account_index: Some(1),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("no-op succeeds");
+
+        assert_eq!(out.info_text(), "");
+        assert_eq!(storage.accounts.len(), 2); // untouched in-memory view
+        assert_eq!(disk_storage().await.accounts.len(), 1);
+    }
+
+    // Port of "disables an enabled account and reports the new state" +
+    // "re-enables a disabled account".
+    #[tokio::test]
+    #[serial(env)]
+    async fn toggle_flips_enabled_and_reports_state() {
+        let _sandbox = EnvSandbox::new();
+        let mut storage = storage_with(vec![account("rt-a", None, Some("a@example.com"))]);
+        seed_disk(&storage).await;
+
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            toggle_account_index: Some(0),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("toggle succeeds");
+        assert_eq!(out.info_text(), "Disabled account 1.");
+        assert_eq!(storage.accounts[0].enabled, Some(false));
+
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("toggle succeeds");
+        assert_eq!(out.info_text(), "Enabled account 1.");
+        assert_eq!(storage.accounts[0].enabled, Some(true));
+    }
+
+    // Port of "ignores a refresh request for an index that no longer exists"
+    // — returns before any OAuth prompt fires.
+    #[tokio::test]
+    #[serial(env)]
+    async fn refresh_request_for_missing_index_is_ignored() {
+        let _sandbox = EnvSandbox::new();
+        let mut storage = storage_with(vec![account("rt-a", None, Some("a@example.com"))]);
+        let menu_result = LoginMenuResult {
+            mode: LoginMode::Manage,
+            refresh_account_index: Some(5),
+            ..Default::default()
+        };
+        let mut out = CliOut::capture();
+        handle_manage_action(&mut storage, &menu_result, &mut out)
+            .await
+            .expect("ignored");
+        assert!(out.lines().is_empty());
+    }
+
+    #[test]
+    fn sign_in_menu_items_layout_matches_ts() {
+        let no_backup = build_sign_in_menu_items(None);
+        // heading, browser, manual, separator, back.
+        assert_eq!(no_backup.len(), 5);
+        assert!(no_backup[0].heading);
+        assert_eq!(no_backup[1].label, "Open Browser (Easy)");
+        assert_eq!(no_backup[2].label, "Manual / Incognito");
+        assert!(no_backup[3].separator);
+        assert_eq!(no_backup[4].label, "Back");
+
+        let backup = NamedBackupSummary {
+            path: "p".to_string(),
+            file_name: "team.json".to_string(),
+            account_count: 3,
+            mtime_ms: 0.0,
+        };
+        let with_backup = build_sign_in_menu_items(Some(&backup));
+        // + separator, restore heading, restore item.
+        assert_eq!(with_backup.len(), 8);
+        assert!(with_backup[3].separator);
+        assert!(with_backup[4].heading);
+        assert_eq!(with_backup[5].label, "Restore Saved Backup");
+        assert!(with_backup[5].hint.as_deref().unwrap_or("").contains("team.json"));
+    }
+}
diff --git a/crates/manager/src/login/menu_data.rs b/crates/manager/src/login/menu_data.rs
new file mode 100644
index 000000000..f9f9eb29e
--- /dev/null
+++ b/crates/manager/src/login/menu_data.rs
@@ -0,0 +1,748 @@
+//! Port of `lib/codex-manager/login-menu-data.ts` — the login dashboard's
+//! data layer: menu quota refresh (5-minute TTL), the account-row view-model
+//! builder with ready-first ordering (duration-derived window labels — spec
+//! 09 gotcha 10), the runtime-current resolution, and the Codex CLI drift
+//! sync.
+//!
+//! The quota-summary string formatter lives in the sibling-owned
+//! `crate::formatters::quota`; it is injected here exactly like the TS DI
+//! seams so this module stays testable in isolation.
+
+use cma_config::dashboard_settings::{
+    DashboardAccountSortMode, DashboardDisplaySettings, DashboardLayoutMode,
+};
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::token_utils::{extract_account_id, sanitize_email};
+use cma_core::utils::now_ms;
+use cma_quota::cache::{load_quota_cache, save_quota_cache, QuotaCacheData, QuotaCacheEntry};
+use cma_quota::probe::{fetch_codex_quota_snapshot, ProbeCodexQuotaOptions};
+use cma_quota::readiness::{
+    build_quota_email_fallback_state, has_safe_quota_email_fallback, has_unique_quota_account_id,
+    is_quota_cache_entry_exhausted, normalize_quota_account_id, quota_left_percent_from_used,
+};
+use cma_runtime::account_status::{format_rate_limit_entry, resolve_active_index};
+use cma_runtime::current_account::{
+    is_display_current_account, read_app_runtime_helper_account_signal,
+    resolve_account_current_markers, resolve_runtime_current_account,
+    RuntimeCurrentAccountOptions, RuntimeCurrentAccountSelection, RuntimeCurrentAccountSources,
+};
+use cma_tui::auth_menu_builder::{resolve_quota_window_label, AccountStatus};
+use cma_tui::login_prompts::ExistingAccountInfo;
+
+use crate::login::account_credentials::has_usable_access_token;
+use crate::quota_cache_helpers::{
+    clone_quota_cache_data, get_persisted_quota_view_for_account, update_quota_cache_for_account,
+    PersistedQuotaViewAccount, DEFAULT_LIVE_PROBE_MODEL,
+};
+
+/// `DEFAULT_MENU_QUOTA_REFRESH_TTL_MS` (5 minutes).
+pub const DEFAULT_MENU_QUOTA_REFRESH_TTL_MS: i64 = 5 * 60_000;
+
+/// Injected quota-summary formatter (`formatAccountQuotaSummary` from the
+/// sibling formatters cluster).
+pub type FormatAccountQuotaSummaryFn<'a> = &'a dyn Fn(&QuotaCacheEntry, i64) -> String;
+
+// ---------------------------------------------------------------------------
+// Probe eligibility (`resolveMenuQuotaProbeInput`, private in TS)
+// ---------------------------------------------------------------------------
+
+struct MenuQuotaProbeInput {
+    account_index: usize,
+    probe_account_id: String,
+    access_token: String,
+}
+
+fn resolve_menu_quota_probe_input(
+    storage: &AccountStorageV3,
+    cache: &QuotaCacheData,
+    account_index: usize,
+    max_age_ms: i64,
+    now: i64,
+    email_state: &std::collections::HashMap<String, cma_quota::readiness::QuotaEmailFallbackState>,
+) -> Option<MenuQuotaProbeInput> {
+    let account = storage.accounts.get(account_index)?;
+    // Skip disabled accounts.
+    if account.enabled == Some(false) {
+        return None;
+    }
+    // Skip accounts without a usable access token.
+    if !has_usable_access_token(account, now) {
+        return None;
+    }
+    // Skip when the persisted quota view is still fresh.
+    let view = get_persisted_quota_view_for_account(
+        Some(cache),
+        &PersistedQuotaViewAccount {
+            account_id: account.account_id.as_deref(),
+            email: account.email.as_deref(),
+            rate_limit_reset_times: account.rate_limit_reset_times.as_ref(),
+        },
+        &storage.accounts,
+        now,
+        Some(email_state),
+    );
+    if let Some(view) = view
+        && now as f64 - view.updated_at < max_age_ms as f64 {
+            return None;
+        }
+    // Skip unless the result can be stored under a safe key.
+    let has_safe_id_key = normalize_quota_account_id(account.account_id.as_deref()).is_some()
+        && has_unique_quota_account_id(&storage.accounts, account);
+    let has_safe_email_key = has_safe_quota_email_fallback(email_state, account);
+    if !has_safe_id_key && !has_safe_email_key {
+        return None;
+    }
+    // Probe id = accountId ?? extractAccountId(accessToken); both required.
+    let access_token = account.access_token.clone()?;
+    let probe_account_id = account
+        .account_id
+        .clone()
+        .or_else(|| extract_account_id(Some(&access_token)))?;
+    Some(MenuQuotaProbeInput {
+        account_index,
+        probe_account_id,
+        access_token,
+    })
+}
+
+fn collect_probe_targets(
+    storage: &AccountStorageV3,
+    cache: &QuotaCacheData,
+    max_age_ms: i64,
+    now: i64,
+) -> Vec<MenuQuotaProbeInput> {
+    let email_state = build_quota_email_fallback_state(&storage.accounts);
+    (0..storage.accounts.len())
+        .filter_map(|index| {
+            resolve_menu_quota_probe_input(storage, cache, index, max_age_ms, now, &email_state)
+        })
+        .collect()
+}
+
+/// `countMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now)`.
+pub fn count_menu_quota_refresh_targets(
+    storage: &AccountStorageV3,
+    cache: &QuotaCacheData,
+    max_age_ms: i64,
+    now: i64,
+) -> usize {
+    collect_probe_targets(storage, cache, max_age_ms, now).len()
+}
+
+/// `refreshQuotaCacheForMenu(storage, cache, maxAgeMs, onProgress)`:
+/// clone → probe stale targets → apply onto the clone → RE-LOAD the persisted
+/// cache and re-apply this run's snapshots onto it before saving (prevents
+/// last-write-wins clobbering; spec 09 gotcha 9). Save failures only warn.
+pub async fn refresh_quota_cache_for_menu(
+    storage: &AccountStorageV3,
+    cache: &QuotaCacheData,
+    max_age_ms: i64,
+    mut on_progress: Option<&mut (dyn FnMut(usize, usize) + Send)>,
+) -> QuotaCacheData {
+    if storage.accounts.is_empty() {
+        return cache.clone();
+    }
+    let now = now_ms();
+    let mut working = clone_quota_cache_data(cache);
+    let targets = collect_probe_targets(storage, cache, max_age_ms, now);
+    let total = targets.len();
+    if let Some(progress) = on_progress.as_deref_mut() {
+        progress(0, total);
+    }
+
+    // Applied snapshots: (account index, snapshot) for the re-apply pass.
+    let mut applied: Vec<(usize, cma_quota::probe::CodexQuotaSnapshot)> = Vec::new();
+    let mut changed = false;
+    for (processed, target) in targets.iter().enumerate() {
+        if let Some(progress) = on_progress.as_deref_mut() {
+            progress(processed, total);
+        }
+        let snapshot = fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+            account_id: target.probe_account_id.clone(),
+            access_token: target.access_token.clone(),
+            model: Some(DEFAULT_LIVE_PROBE_MODEL.to_string()),
+            ..Default::default()
+        })
+        .await;
+        // Probe failures silently keep the cached values.
+        if let Ok(snapshot) = snapshot {
+            let account = &storage.accounts[target.account_index];
+            if update_quota_cache_for_account(
+                &mut working,
+                account,
+                &snapshot,
+                &storage.accounts,
+                None,
+            ) {
+                changed = true;
+            }
+            applied.push((target.account_index, snapshot));
+        }
+    }
+
+    if !changed {
+        return working;
+    }
+
+    // Re-base: reload the persisted cache and re-apply this run's snapshots
+    // onto the fresh state; an empty persisted cache (read failure/empty
+    // file) falls back to the local clone.
+    let persisted = load_quota_cache().await;
+    let has_persisted_data =
+        !persisted.by_account_id.is_empty() || !persisted.by_email.is_empty();
+    let to_save = if has_persisted_data {
+        let mut rebased = persisted;
+        for (account_index, snapshot) in &applied {
+            let account = &storage.accounts[*account_index];
+            update_quota_cache_for_account(
+                &mut rebased,
+                account,
+                snapshot,
+                &storage.accounts,
+                None,
+            );
+        }
+        rebased
+    } else {
+        working
+    };
+    // `saveQuotaCache` never throws (Windows EBUSY/EPERM tolerated inside).
+    save_quota_cache(&to_save).await;
+    to_save
+}
+
+// ---------------------------------------------------------------------------
+// Account-row view model (`toExistingAccountInfo`)
+// ---------------------------------------------------------------------------
+
+fn map_account_status(
+    account: &AccountMetadataV3,
+    entry: Option<&QuotaCacheEntry>,
+    now: i64,
+    is_current: bool,
+) -> AccountStatus {
+    if account.enabled == Some(false) {
+        return AccountStatus::Disabled;
+    }
+    if account.cooling_down_until.is_some_and(|until| until > now) {
+        return AccountStatus::Cooldown;
+    }
+    if is_quota_cache_entry_exhausted(entry, now) {
+        return AccountStatus::QuotaExhausted;
+    }
+    if entry.is_some_and(|entry| entry.status == 429.0) {
+        return AccountStatus::RateLimited;
+    }
+    let rate_limit_line = format_rate_limit_entry(
+        account.rate_limit_reset_times.as_ref(),
+        now,
+        &|ms| cma_accounts::rate_limits::format_wait_time(ms),
+        cma_core::model_family::ModelFamily::Codex,
+    );
+    if rate_limit_line.is_some() {
+        return AccountStatus::RateLimited;
+    }
+    if is_current {
+        return AccountStatus::Active;
+    }
+    AccountStatus::Ok
+}
+
+/// `toExistingAccountInfo(storage, quotaCache, displaySettings,
+/// runtimeCurrent)` — builds and orders the dashboard rows.
+pub fn to_existing_account_info(
+    storage: &AccountStorageV3,
+    quota_cache: &QuotaCacheData,
+    display_settings: &DashboardDisplaySettings,
+    runtime_current: Option<&RuntimeCurrentAccountSelection>,
+    format_account_quota_summary: FormatAccountQuotaSummaryFn<'_>,
+) -> Vec<ExistingAccountInfo> {
+    let now = now_ms();
+    let active_index = resolve_active_index(storage, cma_core::model_family::ModelFamily::Codex);
+    let email_state = build_quota_email_fallback_state(&storage.accounts);
+    let layout_mode = display_settings.menu_layout_mode;
+
+    let mut rows: Vec<ExistingAccountInfo> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let entry = get_persisted_quota_view_for_account(
+                Some(quota_cache),
+                &PersistedQuotaViewAccount {
+                    account_id: account.account_id.as_deref(),
+                    email: account.email.as_deref(),
+                    rate_limit_reset_times: account.rate_limit_reset_times.as_ref(),
+                },
+                &storage.accounts,
+                now,
+                Some(&email_state),
+            );
+            let markers = resolve_account_current_markers(index, active_index, runtime_current);
+            let is_current = is_display_current_account(index, active_index, runtime_current);
+            let status = map_account_status(account, entry.as_ref(), now, is_current);
+
+            let quota_summary = if display_settings.menu_show_quota_summary {
+                entry
+                    .as_ref()
+                    .map(|entry| format_account_quota_summary(entry, now))
+            } else {
+                None
+            };
+            let tui_markers: Vec<cma_tui::auth_menu_builder::AccountCurrentMarker> = markers
+                .iter()
+                .map(|marker| match marker {
+                    cma_runtime::current_account::AccountCurrentMarker::Current => {
+                        cma_tui::auth_menu_builder::AccountCurrentMarker::Current
+                    }
+                    cma_runtime::current_account::AccountCurrentMarker::InUse => {
+                        cma_tui::auth_menu_builder::AccountCurrentMarker::InUse
+                    }
+                    cma_runtime::current_account::AccountCurrentMarker::Selected => {
+                        cma_tui::auth_menu_builder::AccountCurrentMarker::Selected
+                    }
+                })
+                .collect();
+
+            ExistingAccountInfo {
+                index: index as i64,
+                source_index: Some(index as i64),
+                quick_switch_number: None,
+                account_id: account.account_id.clone(),
+                account_label: account.account_label.clone(),
+                email: account.email.clone(),
+                added_at: Some(account.added_at),
+                last_used: Some(account.last_used),
+                status: Some(status),
+                quota_summary,
+                quota_5h_left_percent: entry
+                    .as_ref()
+                    .and_then(|entry| quota_left_percent_from_used(entry.primary.used_percent))
+                    .map(|value| value as f64),
+                quota_5h_reset_at_ms: entry.as_ref().and_then(|entry| entry.primary.reset_at_ms),
+                quota_7d_left_percent: entry
+                    .as_ref()
+                    .and_then(|entry| quota_left_percent_from_used(entry.secondary.used_percent))
+                    .map(|value| value as f64),
+                quota_7d_reset_at_ms: entry.as_ref().and_then(|entry| entry.secondary.reset_at_ms),
+                quota_primary_window_minutes: entry
+                    .as_ref()
+                    .and_then(|entry| entry.primary.window_minutes),
+                quota_secondary_window_minutes: entry
+                    .as_ref()
+                    .and_then(|entry| entry.secondary.window_minutes),
+                quota_rate_limited: Some(entry.as_ref().is_some_and(|entry| entry.status == 429.0)),
+                quota_exhausted: Some(is_quota_cache_entry_exhausted(entry.as_ref(), now)),
+                is_current_account: Some(is_current),
+                is_default_account: Some(index == active_index),
+                is_runtime_current_account: Some(
+                    runtime_current.is_some_and(|current| current.index == index),
+                ),
+                current_markers: Some(tui_markers),
+                enabled: Some(account.enabled != Some(false)),
+                show_status_badge: Some(display_settings.menu_show_status_badge),
+                show_current_badge: Some(display_settings.menu_show_current_badge),
+                show_last_used: Some(display_settings.menu_show_last_used),
+                show_quota_cooldown: Some(display_settings.menu_show_quota_cooldown),
+                show_hints_for_unselected_rows: Some(
+                    layout_mode == DashboardLayoutMode::ExpandedRows,
+                ),
+                highlight_current_row: Some(display_settings.menu_highlight_current_row),
+                focus_style: Some(match display_settings.menu_focus_style {
+                    cma_config::dashboard_settings::DashboardFocusStyle::RowInvert => {
+                        cma_tui::select::FocusStyle::RowInvert
+                    }
+                }),
+                statusline_fields: Some(
+                    display_settings
+                        .menu_statusline_fields
+                        .iter()
+                        .map(|field| field.as_str().to_string())
+                        .collect(),
+                ),
+            }
+        })
+        .collect();
+
+    apply_account_menu_ordering(&mut rows, display_settings);
+    rows
+}
+
+// ---------------------------------------------------------------------------
+// Ready-first ordering
+// ---------------------------------------------------------------------------
+
+fn readiness_bucket(account: &ExistingAccountInfo) -> i32 {
+    let mut bucket = match account.status {
+        Some(AccountStatus::Active) | Some(AccountStatus::Ok) => 0,
+        Some(AccountStatus::QuotaExhausted)
+        | Some(AccountStatus::Cooldown)
+        | Some(AccountStatus::RateLimited) => 2,
+        Some(AccountStatus::Disabled)
+        | Some(AccountStatus::Error)
+        | Some(AccountStatus::Flagged) => 3,
+        Some(AccountStatus::Unknown) | None => 1,
+    };
+    // Also forced to >= 2 when the quota view says limited/exhausted.
+    if account.quota_rate_limited == Some(true) || account.quota_exhausted == Some(true) {
+        bucket = bucket.max(2);
+    }
+    bucket
+}
+
+/// Hand-rolled equivalent of the TS regex
+/// `(?:^|\|)\s*${windowLabel}\s+(\d{1,3})%` (case-insensitive) — the `regex`
+/// crate is not a manager dependency.
+fn parse_left_percent_from_summary(summary: &str, window_label: &str) -> Option<i64> {
+    let label_lower = window_label.to_lowercase();
+    for segment in summary.split('|') {
+        let trimmed = segment.trim_start();
+        let lower = trimmed.to_lowercase();
+        let Some(rest) = lower.strip_prefix(&label_lower) else {
+            continue;
+        };
+        // Require at least one whitespace char after the label.
+        let mut chars = rest.chars();
+        let Some(first) = chars.next() else { continue };
+        if !first.is_whitespace() {
+            continue;
+        }
+        let after_ws: String = {
+            let mut s: &str = rest;
+            s = s.trim_start();
+            s.to_string()
+        };
+        // 1–3 digits immediately followed by '%'.
+        let digits: String = after_ws.chars().take_while(|c| c.is_ascii_digit()).collect();
+        if digits.is_empty() || digits.len() > 3 {
+            continue;
+        }
+        if !after_ws[digits.len()..].starts_with('%') {
+            continue;
+        }
+        return digits.parse::<i64>().ok();
+    }
+    None
+}
+
+/// `readQuotaLeftPercent` — direct numeric field clamped/rounded 0–100, else
+/// parse from the summary string using DURATION-DERIVED window labels (a 30d
+/// Business window matches `"30d"`, not the positional `"7d"`); no match →
+/// −1 (sinks to the bottom).
+fn read_quota_left_percent(account: &ExistingAccountInfo, primary_window: bool) -> i64 {
+    let direct = if primary_window {
+        account.quota_5h_left_percent
+    } else {
+        account.quota_7d_left_percent
+    };
+    if let Some(direct) = direct
+        && direct.is_finite() {
+            return (direct.round() as i64).clamp(0, 100);
+        }
+    let Some(summary) = &account.quota_summary else {
+        return -1;
+    };
+    let (window_minutes, fallback) = if primary_window {
+        (account.quota_primary_window_minutes, "5h")
+    } else {
+        (account.quota_secondary_window_minutes, "7d")
+    };
+    let label = resolve_quota_window_label(window_minutes, fallback);
+    parse_left_percent_from_summary(summary, &label).unwrap_or(-1)
+}
+
+/// `compareReadyFirstAccounts(a, b)` — readiness bucket, then higher quota
+/// floor, then higher 5h, higher 7d, more recent lastUsed, lower sourceIndex.
+pub(crate) fn compare_ready_first_accounts(
+    a: &ExistingAccountInfo,
+    b: &ExistingAccountInfo,
+) -> std::cmp::Ordering {
+    use std::cmp::Ordering;
+    let bucket = readiness_bucket(a).cmp(&readiness_bucket(b));
+    if bucket != Ordering::Equal {
+        return bucket;
+    }
+    let a5 = read_quota_left_percent(a, true);
+    let a7 = read_quota_left_percent(a, false);
+    let b5 = read_quota_left_percent(b, true);
+    let b7 = read_quota_left_percent(b, false);
+    let floor = (b5.min(b7)).cmp(&(a5.min(a7)));
+    if floor != Ordering::Equal {
+        return floor;
+    }
+    let five = b5.cmp(&a5);
+    if five != Ordering::Equal {
+        return five;
+    }
+    let seven = b7.cmp(&a7);
+    if seven != Ordering::Equal {
+        return seven;
+    }
+    let last_used = b.last_used.unwrap_or(0).cmp(&a.last_used.unwrap_or(0));
+    if last_used != Ordering::Equal {
+        return last_used;
+    }
+    a.source_index
+        .unwrap_or(0)
+        .cmp(&b.source_index.unwrap_or(0))
+}
+
+/// `applyAccountMenuOrdering` — ready-first sort (when enabled), the
+/// pin-current-when-tied rule, then display re-indexing + quick-switch
+/// numbers.
+pub(crate) fn apply_account_menu_ordering(
+    rows: &mut Vec<ExistingAccountInfo>,
+    settings: &DashboardDisplaySettings,
+) {
+    let sort_active = settings.menu_sort_enabled
+        && settings.menu_sort_mode == DashboardAccountSortMode::ReadyFirst;
+    if sort_active {
+        rows.sort_by(compare_ready_first_accounts);
+
+        if settings.menu_sort_pin_current {
+            let current_position = rows
+                .iter()
+                .position(|row| row.is_current_account == Some(true));
+            if let Some(position) = current_position
+                && position > 0 {
+                    // Move to the front ONLY when tied-or-better vs the
+                    // current first row (gotcha 11).
+                    let ordering = compare_ready_first_accounts(&rows[position], &rows[0]);
+                    if ordering != std::cmp::Ordering::Greater {
+                        let row = rows.remove(position);
+                        rows.insert(0, row);
+                    }
+                }
+        }
+    }
+
+    for (display_index, row) in rows.iter_mut().enumerate() {
+        row.index = display_index as i64;
+        row.quick_switch_number = Some(if settings.menu_sort_quick_switch_visible_row {
+            display_index as i64 + 1
+        } else {
+            row.source_index.unwrap_or(display_index as i64) + 1
+        });
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Runtime current + Codex CLI drift sync
+// ---------------------------------------------------------------------------
+
+/// `loadRuntimeCurrentSelectionForStorage(storage, now)` — merges the
+/// runtime-observability snapshot, the app-bind router status (only when
+/// running), and the app-helper signal; every source failure degrades to
+/// `None`.
+pub async fn load_runtime_current_selection_for_storage(
+    storage: &AccountStorageV3,
+    now: i64,
+) -> Option<RuntimeCurrentAccountSelection> {
+    let runtime_snapshot =
+        cma_runtime::observability::load_persisted_runtime_observability_snapshot();
+    let app_bind_status = match cma_runtime::app_bind::get_app_bind_status(
+        &cma_runtime::app_bind::AppBindOptions::default(),
+    )
+    .await
+    {
+        Ok(status) if status.running => status.router,
+        _ => None,
+    };
+    resolve_runtime_current_account(
+        storage,
+        &RuntimeCurrentAccountSources {
+            runtime_snapshot,
+            app_bind_status,
+            app_helper_status: read_app_runtime_helper_account_signal(),
+        },
+        RuntimeCurrentAccountOptions {
+            now: Some(now),
+            max_age_ms: None,
+        },
+    )
+}
+
+/// `syncCodexCliActiveSelectionIfDrifted(storage)` — pushes the manager's
+/// active account into the Codex CLI files when the identities no longer
+/// match. Match rule: trimmed accountId equality when both present; else
+/// sanitized email equality when both present; else DRIFTED. All errors →
+/// `false`.
+pub async fn sync_codex_cli_active_selection_if_drifted(storage: &AccountStorageV3) -> bool {
+    let active_index = resolve_active_index(storage, cma_core::model_family::ModelFamily::Codex);
+    let Some(account) = storage.accounts.get(active_index) else {
+        return false;
+    };
+    let Some(state) = cma_cli_mirror::state::load_codex_cli_state(true).await else {
+        return false;
+    };
+
+    let manager_id = account
+        .account_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let cli_id = state
+        .active_account_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let manager_email = sanitize_email(account.email.as_deref());
+    let cli_email = sanitize_email(state.active_email.as_deref());
+
+    let matching = match (manager_id, cli_id) {
+        (Some(manager_id), Some(cli_id)) => manager_id == cli_id,
+        _ => match (&manager_email, &cli_email) {
+            (Some(manager_email), Some(cli_email)) => manager_email == cli_email,
+            // Neither identity comparable → treat as drifted.
+            _ => false,
+        },
+    };
+    if matching {
+        return false;
+    }
+
+    cma_cli_mirror::writer::set_codex_cli_active_selection(&cma_cli_mirror::writer::ActiveSelection {
+        account_id: account.account_id.clone(),
+        email: account.email.clone(),
+        access_token: account.access_token.clone(),
+        refresh_token: Some(account.refresh_token.clone()),
+        expires_at: account.expires_at.map(|value| value as f64),
+        id_token: None,
+    })
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn row(
+        source_index: i64,
+        status: AccountStatus,
+        left_5h: Option<f64>,
+        left_7d: Option<f64>,
+        last_used: i64,
+    ) -> ExistingAccountInfo {
+        ExistingAccountInfo {
+            index: source_index,
+            source_index: Some(source_index),
+            status: Some(status),
+            quota_5h_left_percent: left_5h,
+            quota_7d_left_percent: left_7d,
+            last_used: Some(last_used),
+            ..Default::default()
+        }
+    }
+
+    fn default_settings() -> DashboardDisplaySettings {
+        DashboardDisplaySettings::default()
+    }
+
+    #[test]
+    fn ready_first_orders_by_bucket_then_quota_floor() {
+        let mut rows = vec![
+            row(0, AccountStatus::RateLimited, Some(90.0), Some(90.0), 10),
+            row(1, AccountStatus::Ok, Some(20.0), Some(80.0), 10),
+            row(2, AccountStatus::Ok, Some(70.0), Some(60.0), 10),
+            row(3, AccountStatus::Disabled, Some(100.0), Some(100.0), 10),
+        ];
+        apply_account_menu_ordering(&mut rows, &default_settings());
+        let order: Vec<i64> = rows.iter().filter_map(|r| r.source_index).collect();
+        // Ok rows first (higher floor 60 beats floor 20), then rate-limited,
+        // then disabled.
+        assert_eq!(order, vec![2, 1, 0, 3]);
+        // Display re-indexing + quick-switch numbers follow visible rows.
+        assert_eq!(rows[0].index, 0);
+        assert_eq!(rows[0].quick_switch_number, Some(1));
+        assert_eq!(rows[3].quick_switch_number, Some(4));
+    }
+
+    #[test]
+    fn quota_flags_force_the_limited_bucket() {
+        let mut limited = row(0, AccountStatus::Ok, Some(100.0), Some(100.0), 10);
+        limited.quota_rate_limited = Some(true);
+        let healthy = row(1, AccountStatus::Ok, Some(10.0), Some(10.0), 10);
+        let mut rows = vec![limited, healthy];
+        apply_account_menu_ordering(&mut rows, &default_settings());
+        assert_eq!(rows[0].source_index, Some(1));
+    }
+
+    #[test]
+    fn summary_parse_uses_duration_derived_labels() {
+        let mut business = row(0, AccountStatus::Ok, None, None, 10);
+        business.quota_summary = Some("5h 80% | 30d 70%".to_string());
+        // 30-day window: label resolves to "30d" (not the positional "7d").
+        business.quota_primary_window_minutes = Some(300.0);
+        business.quota_secondary_window_minutes = Some(30.0 * 24.0 * 60.0);
+        assert_eq!(read_quota_left_percent(&business, true), 80);
+        assert_eq!(read_quota_left_percent(&business, false), 70);
+
+        // Positional fallback when no window minutes are present.
+        let mut plain = row(1, AccountStatus::Ok, None, None, 10);
+        plain.quota_summary = Some("5h 15% | 7d 25%".to_string());
+        assert_eq!(read_quota_left_percent(&plain, true), 15);
+        assert_eq!(read_quota_left_percent(&plain, false), 25);
+
+        // No match → −1 (sinks to the bottom).
+        let mut none = row(2, AccountStatus::Ok, None, None, 10);
+        none.quota_summary = Some("rate-limited".to_string());
+        assert_eq!(read_quota_left_percent(&none, true), -1);
+    }
+
+    #[test]
+    fn direct_percent_field_wins_and_is_clamped() {
+        let mut info = row(0, AccountStatus::Ok, Some(250.0), Some(-9.0), 10);
+        info.quota_summary = Some("5h 10% | 7d 10%".to_string());
+        assert_eq!(read_quota_left_percent(&info, true), 100);
+        assert_eq!(read_quota_left_percent(&info, false), 0);
+    }
+
+    #[test]
+    fn pin_current_moves_to_front_only_when_tied() {
+        let mut settings = default_settings();
+        settings.menu_sort_pin_current = true;
+
+        // Current row equally ready → pinned to the front.
+        let mut current = row(0, AccountStatus::Active, Some(50.0), Some(50.0), 10);
+        current.is_current_account = Some(true);
+        let other = row(1, AccountStatus::Ok, Some(50.0), Some(50.0), 10);
+        let mut rows = vec![other.clone(), current.clone()];
+        apply_account_menu_ordering(&mut rows, &settings);
+        assert_eq!(rows[0].is_current_account, Some(true));
+
+        // Current row strictly worse (rate-limited) → stays where sorted.
+        let mut limited_current = row(0, AccountStatus::RateLimited, Some(0.0), Some(0.0), 10);
+        limited_current.is_current_account = Some(true);
+        let mut rows = vec![other.clone(), limited_current];
+        apply_account_menu_ordering(&mut rows, &settings);
+        assert_eq!(rows[0].is_current_account, None);
+        assert_eq!(rows[1].is_current_account, Some(true));
+    }
+
+    #[test]
+    fn quick_switch_can_follow_source_indexes() {
+        let mut settings = default_settings();
+        settings.menu_sort_quick_switch_visible_row = false;
+        let mut rows = vec![
+            row(0, AccountStatus::RateLimited, Some(10.0), Some(10.0), 10),
+            row(1, AccountStatus::Ok, Some(90.0), Some(90.0), 10),
+        ];
+        apply_account_menu_ordering(&mut rows, &settings);
+        // Visible first row is source index 1 → quick switch number stays 2.
+        assert_eq!(rows[0].source_index, Some(1));
+        assert_eq!(rows[0].quick_switch_number, Some(2));
+    }
+
+    #[test]
+    fn manual_sort_mode_keeps_source_order() {
+        let mut settings = default_settings();
+        settings.menu_sort_mode = DashboardAccountSortMode::Manual;
+        let mut rows = vec![
+            row(0, AccountStatus::Disabled, None, None, 0),
+            row(1, AccountStatus::Ok, Some(90.0), Some(90.0), 10),
+        ];
+        apply_account_menu_ordering(&mut rows, &settings);
+        assert_eq!(rows[0].source_index, Some(0));
+        assert_eq!(rows[0].quick_switch_number, Some(1));
+    }
+}
diff --git a/crates/manager/src/login/mod.rs b/crates/manager/src/login/mod.rs
new file mode 100644
index 000000000..633fdbd60
--- /dev/null
+++ b/crates/manager/src/login/mod.rs
@@ -0,0 +1,10 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_credentials;
+pub mod account_pool_write;
+pub mod action_panel;
+pub mod flow;
+pub mod manual_callback;
+pub mod menu_actions;
+pub mod menu_data;
+pub mod oauth;
+pub mod persist_selected;
diff --git a/crates/manager/src/login/oauth.rs b/crates/manager/src/login/oauth.rs
new file mode 100644
index 000000000..f9664c8c7
--- /dev/null
+++ b/crates/manager/src/login/oauth.rs
@@ -0,0 +1,539 @@
+//! Port of `lib/codex-manager/login-oauth.ts` — OAuth/device sign-in
+//! plumbing for the login flow: browser/manual OAuth, manual callback
+//! prompting, account-selection resolution, pool persistence, and the Codex
+//! CLI mirror sync.
+
+use std::io::{BufRead, IsTerminal, Write};
+
+use cma_auth::callback_guidance::{
+    describe_callback_failure, CallbackFailureContext, CallbackFailureReason,
+};
+use cma_auth::oauth::{
+    create_authorization_flow, exchange_authorization_code, redact_oauth_url_for_log,
+    AuthorizationFlowOptions, REDIRECT_URI,
+};
+use cma_cli_mirror::writer::{set_codex_cli_active_selection, ActiveSelection};
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3, Workspace};
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult, TokenSuccess};
+use cma_core::token_utils::{
+    extract_account_email, extract_account_id, get_account_id_candidates,
+    resolve_request_account_id, sanitize_email, select_best_account_candidate,
+};
+use cma_core::utils::now_ms;
+use cma_storage::matching::{find_matching_account_index, AccountMatchOptions};
+use cma_storage::transactions::with_account_storage_transaction;
+use cma_tui::format::{paint_ui_text, UiTextTone};
+use cma_tui::runtime_options::get_ui_runtime_options;
+use cma_tui::ui_copy;
+
+use crate::login::account_pool_write::{
+    apply_account_pool_results, AccountPoolWriteOutcome, PoolWriteIdentity, ResolvedAccountWrite,
+};
+use crate::login::manual_callback::{classify_manual_callback_input, ManualCallbackClassification};
+
+/// `TokenSuccessWithAccount` — a successful token exchange enriched with the
+/// resolved account binding.
+#[derive(Clone, Debug, PartialEq)]
+pub struct TokenSuccessWithAccount {
+    pub tokens: TokenSuccess,
+    pub account_id_override: Option<String>,
+    pub account_id_source: Option<AccountIdSource>,
+    pub account_label: Option<String>,
+    pub workspaces: Option<Vec<Workspace>>,
+}
+
+impl TokenSuccessWithAccount {
+    pub fn plain(tokens: TokenSuccess) -> Self {
+        TokenSuccessWithAccount {
+            tokens,
+            account_id_override: None,
+            account_id_source: None,
+            account_label: None,
+            workspaces: None,
+        }
+    }
+}
+
+/// `OAuthSignInMode`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OAuthSignInMode {
+    Browser,
+    Manual,
+    Device,
+    RestoreBackup,
+    Cancel,
+}
+
+/// `isOAuthCancellation(result)` — `(message ?? reason ?? "")` trimmed,
+/// lowercased, contains `"cancelled"` OR `"canceled"`.
+pub fn is_oauth_cancellation(result: &TokenResult) -> bool {
+    let TokenResult::Failed(failure) = result else {
+        return false;
+    };
+    let text = failure
+        .message
+        .clone()
+        .or_else(|| failure.reason.map(|reason| reason.as_str().to_string()))
+        .unwrap_or_default();
+    let normalized = text.trim().to_lowercase();
+    normalized.contains("cancelled") || normalized.contains("canceled")
+}
+
+/// `resolveAccountSelection(tokens, orgOverride?)` — builds the `workspaces`
+/// array from ALL candidates BEFORE the org branch so `--org` logins persist
+/// workspaces too (#512, spec 09 gotcha 15).
+pub fn resolve_account_selection(
+    tokens: &TokenSuccess,
+    org_override: Option<&str>,
+) -> TokenSuccessWithAccount {
+    let candidates =
+        get_account_id_candidates(Some(&tokens.access), tokens.id_token.as_deref());
+    let workspaces: Option<Vec<Workspace>> = if candidates.is_empty() {
+        None
+    } else {
+        Some(
+            candidates
+                .iter()
+                .map(|candidate| Workspace {
+                    id: candidate.account_id.clone(),
+                    name: Some(candidate.label.clone()),
+                    enabled: true,
+                    disabled_at: None,
+                    is_default: candidate.is_default,
+                })
+                .collect(),
+        )
+    };
+
+    let override_id = cma_auth::org_override::resolve_org_override(org_override);
+    if let Some(override_id) = override_id {
+        let matched_label = candidates
+            .iter()
+            .find(|candidate| candidate.account_id == override_id)
+            .map(|candidate| candidate.label.clone());
+        return TokenSuccessWithAccount {
+            tokens: tokens.clone(),
+            account_id_override: Some(override_id),
+            account_id_source: Some(AccountIdSource::Manual),
+            account_label: matched_label,
+            workspaces,
+        };
+    }
+
+    if candidates.is_empty() {
+        return TokenSuccessWithAccount::plain(tokens.clone());
+    }
+    if candidates.len() == 1 {
+        let candidate = &candidates[0];
+        return TokenSuccessWithAccount {
+            tokens: tokens.clone(),
+            account_id_override: Some(candidate.account_id.clone()),
+            account_id_source: Some(candidate.source),
+            account_label: Some(candidate.label.clone()),
+            workspaces,
+        };
+    }
+    match select_best_account_candidate(&candidates) {
+        None => TokenSuccessWithAccount::plain(tokens.clone()),
+        Some(best) => TokenSuccessWithAccount {
+            tokens: tokens.clone(),
+            account_id_override: Some(best.account_id.clone()),
+            account_id_source: Some(best.source),
+            account_label: Some(best.label.clone()),
+            workspaces,
+        },
+    }
+}
+
+fn print_toned(text: &str, tone: UiTextTone) {
+    let ui = get_ui_runtime_options();
+    println!("{}", paint_ui_text(&ui, text, tone));
+}
+
+fn question(prompt: &str) -> Option<String> {
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "{prompt}");
+    let _ = stdout.flush();
+    let mut answer = String::new();
+    match std::io::stdin().lock().read_line(&mut answer) {
+        Ok(0) => None, // stream closed before a line
+        Ok(_) => Some(answer.trim_end_matches(['\r', '\n']).to_string()),
+        Err(_) => None,
+    }
+}
+
+/// Private `promptManualCallback(state, { allowNonTty })` — interactive only
+/// when both stdin & stdout are TTY; non-TTY without `allow_non_tty` →
+/// cancelled; a closed pipe → cancelled.
+async fn prompt_manual_callback(
+    state: &str,
+    allow_non_tty: bool,
+) -> ManualCallbackClassification {
+    let interactive = std::io::stdin().is_terminal() && std::io::stdout().is_terminal();
+    if !interactive && !allow_non_tty {
+        return ManualCallbackClassification::Cancelled;
+    }
+    let answer = if interactive {
+        println!();
+        print_toned(ui_copy::oauth::PASTE_PROMPT, UiTextTone::Accent);
+        question("\u{25c6}  ")
+    } else {
+        // Manual mode piping: one line from the (possibly already-closed)
+        // pipe; EOF resolves null → cancelled.
+        question("")
+    };
+    classify_manual_callback_input(answer.as_deref(), state)
+}
+
+/// `runOAuthFlow(forceNewLogin, signInMode)` — `signInMode` restricted to
+/// browser/manual by the callers.
+pub async fn run_oauth_flow(force_new_login: bool, sign_in_mode: OAuthSignInMode) -> TokenResult {
+    let browser_mode = sign_in_mode == OAuthSignInMode::Browser;
+    let flow = create_authorization_flow(AuthorizationFlowOptions { force_new_login });
+
+    // Browser mode: the callback server never rejects; ready:false is the
+    // bind-failed fallback (manual paste).
+    let oauth_server = if browser_mode {
+        Some(cma_auth::callback_server::start_local_oauth_server(&flow.state).await)
+    } else {
+        None
+    };
+
+    // The printed URL is redacted; the FULL url still goes to the browser
+    // opener and the clipboard.
+    let display_url = redact_oauth_url_for_log(&flow.url);
+
+    if browser_mode {
+        if cma_auth::browser::open_browser_url(&flow.url) {
+            print_toned(ui_copy::oauth::BROWSER_OPENED, UiTextTone::Success);
+        } else {
+            print_toned(ui_copy::oauth::BROWSER_OPEN_FAIL, UiTextTone::Warning);
+            println!("{} {display_url}", ui_copy::oauth::GO_TO);
+            if cma_auth::browser::copy_text_to_clipboard(&flow.url) {
+                print_toned(ui_copy::oauth::COPY_OK, UiTextTone::Muted);
+            } else {
+                print_toned(ui_copy::oauth::COPY_FAIL, UiTextTone::Muted);
+            }
+        }
+    } else {
+        println!("{} {display_url}", ui_copy::oauth::GO_TO);
+        if cma_auth::browser::copy_text_to_clipboard(&flow.url) {
+            print_toned(ui_copy::oauth::COPY_OK, UiTextTone::Muted);
+        } else {
+            print_toned(ui_copy::oauth::COPY_FAIL, UiTextTone::Muted);
+        }
+    }
+
+    let waiting_for_callback = browser_mode
+        && oauth_server
+            .as_ref()
+            .is_some_and(|server| server.ready());
+    let mut code: Option<String> = None;
+    if waiting_for_callback {
+        print_toned(ui_copy::oauth::WAITING_CALLBACK, UiTextTone::Muted);
+        if let Some(server) = &oauth_server {
+            code = server
+                .wait_for_code(&flow.state)
+                .await
+                .map(|captured| captured.code);
+        }
+    }
+
+    let mut early_failure: Option<TokenResult> = None;
+    if code.is_none() {
+        if waiting_for_callback {
+            print_toned(ui_copy::oauth::CALLBACK_MISSED, UiTextTone::Warning);
+        } else if !browser_mode {
+            print_toned(ui_copy::oauth::CALLBACK_BYPASSED, UiTextTone::Muted);
+        } else {
+            print_toned(ui_copy::oauth::CALLBACK_UNAVAILABLE, UiTextTone::Warning);
+        }
+        if browser_mode {
+            let reason = if waiting_for_callback {
+                CallbackFailureReason::CallbackTimeout
+            } else {
+                CallbackFailureReason::BindFailed
+            };
+            let context = CallbackFailureContext {
+                bind_error_code: oauth_server
+                    .as_ref()
+                    .and_then(|server| server.bind_error_code().map(str::to_string)),
+            };
+            for line in describe_callback_failure(reason, &context) {
+                if line.is_empty() {
+                    println!();
+                } else {
+                    print_toned(&line, UiTextTone::Muted);
+                }
+            }
+        }
+        match prompt_manual_callback(&flow.state, sign_in_mode == OAuthSignInMode::Manual).await {
+            ManualCallbackClassification::Invalid => {
+                early_failure = Some(TokenResult::Failed(TokenFailure {
+                    reason: Some(TokenFailureReason::InvalidResponse),
+                    status_code: None,
+                    message: Some(ui_copy::oauth::CALLBACK_INVALID.to_string()),
+                }));
+            }
+            ManualCallbackClassification::StateMismatch => {
+                early_failure = Some(TokenResult::Failed(TokenFailure {
+                    reason: Some(TokenFailureReason::InvalidResponse),
+                    status_code: None,
+                    message: Some(ui_copy::oauth::CALLBACK_STATE_MISMATCH.to_string()),
+                }));
+            }
+            ManualCallbackClassification::Code { code: pasted } => code = Some(pasted),
+            ManualCallbackClassification::Cancelled => {}
+        }
+    }
+
+    // TS `finally { oauthServer?.close() }`.
+    if let Some(server) = &oauth_server {
+        server.close();
+    }
+    if let Some(failure) = early_failure {
+        return failure;
+    }
+
+    let Some(code) = code else {
+        return TokenResult::Failed(TokenFailure {
+            reason: Some(TokenFailureReason::Unknown),
+            status_code: None,
+            message: Some(ui_copy::oauth::CANCELLED.to_string()),
+        });
+    };
+    exchange_authorization_code(&code, &flow.pkce.verifier, Some(REDIRECT_URI)).await
+}
+
+/// `runSignInFlow(forceNewLogin, signInMode, options)` — device auth keeps
+/// polling until the 15-minute budget (the TS `keepAlive` ref-timer trick is
+/// a Node-ism; the tokio runtime stays alive while awaiting).
+pub async fn run_sign_in_flow(
+    force_new_login: bool,
+    sign_in_mode: OAuthSignInMode,
+    timeout_ms: Option<i64>,
+) -> TokenResult {
+    match sign_in_mode {
+        OAuthSignInMode::Device => {
+            let options = cma_auth::device_auth::DeviceAuthFlowOptions {
+                timeout_ms,
+                ..Default::default()
+            };
+            cma_auth::device_auth::run_device_auth_flow(&options).await
+        }
+        OAuthSignInMode::Browser | OAuthSignInMode::Manual => {
+            run_oauth_flow(force_new_login, sign_in_mode).await
+        }
+        // Never passed by callers (menu-only modes); treated as a cancel.
+        OAuthSignInMode::RestoreBackup | OAuthSignInMode::Cancel => {
+            TokenResult::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::Unknown),
+                status_code: None,
+                message: Some(ui_copy::oauth::CANCELLED.to_string()),
+            })
+        }
+    }
+}
+
+/// Build the `ResolvedAccountWrite` for one login result (the write-shaping
+/// half of `persistAccountPool`, split out for tests).
+pub(crate) fn build_resolved_account_write(
+    result: &TokenSuccessWithAccount,
+    now: i64,
+) -> ResolvedAccountWrite {
+    let token_account_id = extract_account_id(Some(&result.tokens.access));
+    let account_id = resolve_request_account_id(
+        result.account_id_override.as_deref(),
+        result.account_id_source.as_ref(),
+        token_account_id.as_deref(),
+    );
+    let account_id_source = if account_id.is_some() {
+        result.account_id_source.or({
+            if result.account_id_override.is_some() {
+                Some(AccountIdSource::Manual)
+            } else {
+                Some(AccountIdSource::Token)
+            }
+        })
+    } else {
+        None
+    };
+    let email = sanitize_email(
+        extract_account_email(Some(&result.tokens.access), result.tokens.id_token.as_deref())
+            .as_deref(),
+    );
+    ResolvedAccountWrite {
+        account_id,
+        account_id_source,
+        account_label: result.account_label.clone(),
+        email,
+        refresh_token: result.tokens.refresh.clone(),
+        access_token: Some(result.tokens.access.clone()),
+        expires_at: Some(result.tokens.expires),
+        workspaces: result.workspaces.clone(),
+        now,
+    }
+}
+
+/// `persistAccountPool(results, replaceAll)` — empty results → `None` (no
+/// transaction). Persists `{version: 3, accounts, activeIndex,
+/// activeIndexByFamily}` with every family set to the same active index.
+pub async fn persist_account_pool(
+    results: &[TokenSuccessWithAccount],
+    replace_all: bool,
+) -> Result<Option<AccountPoolWriteOutcome>, cma_core::errors::CodexError> {
+    if results.is_empty() {
+        return Ok(None);
+    }
+    let results = results.to_vec();
+    with_account_storage_transaction(move |loaded_storage, persist| async move {
+        let stored = if replace_all { None } else { loaded_storage };
+        let existing: Vec<_> = stored
+            .as_ref()
+            .map(|storage| storage.accounts.clone())
+            .unwrap_or_default();
+        let prior_active_index = stored.as_ref().map(|storage| storage.active_index);
+        let now = now_ms();
+        let writes: Vec<ResolvedAccountWrite> = results
+            .iter()
+            .map(|result| build_resolved_account_write(result, now))
+            .collect();
+
+        let matcher = |accounts: &[cma_core::schemas::account_storage::AccountMetadataV3],
+                       identity: &PoolWriteIdentity|
+         -> Option<usize> {
+            find_matching_account_index(
+                accounts,
+                &cma_storage::matching::AccountSelectionCandidate {
+                    account_id: identity.account_id.clone(),
+                    email: identity.email.clone(),
+                    refresh_token: identity.refresh_token.clone(),
+                },
+                AccountMatchOptions {
+                    allow_unique_account_id_fallback_without_email: true,
+                },
+            )
+        };
+        let fold = apply_account_pool_results(&existing, &writes, prior_active_index, &matcher);
+
+        let mut by_family = cma_core::schemas::account_storage::ActiveIndexByFamily::default();
+        for family in cma_core::model_family::MODEL_FAMILIES {
+            by_family.set(family, Some(fold.active_index));
+        }
+        let next_storage = AccountStorageV3 {
+            accounts: fold.accounts,
+            active_index: fold.active_index,
+            active_index_by_family: Some(by_family),
+            ..AccountStorageV3::empty()
+        };
+        persist.persist(&next_storage).await?;
+        Ok(fold.outcome)
+    })
+    .await
+}
+
+/// `syncSelectionToCodex(tokens)` — same accountId precedence, then mirror
+/// into the Codex CLI auth files.
+pub async fn sync_selection_to_codex(result: &TokenSuccessWithAccount) -> bool {
+    let token_account_id = extract_account_id(Some(&result.tokens.access));
+    let account_id = resolve_request_account_id(
+        result.account_id_override.as_deref(),
+        result.account_id_source.as_ref(),
+        token_account_id.as_deref(),
+    );
+    let email = sanitize_email(
+        extract_account_email(Some(&result.tokens.access), result.tokens.id_token.as_deref())
+            .as_deref(),
+    );
+    set_codex_cli_active_selection(&ActiveSelection {
+        account_id,
+        email,
+        access_token: Some(result.tokens.access.clone()),
+        refresh_token: Some(result.tokens.refresh.clone()),
+        expires_at: Some(result.tokens.expires as f64),
+        id_token: result.tokens.id_token.clone(),
+    })
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn failed(message: Option<&str>, reason: Option<TokenFailureReason>) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason,
+            status_code: None,
+            message: message.map(str::to_string),
+        })
+    }
+
+    #[test]
+    fn oauth_cancellation_matches_both_spellings_and_falls_back_to_reason() {
+        assert!(is_oauth_cancellation(&failed(
+            Some("Sign-in cancelled."),
+            None
+        )));
+        assert!(is_oauth_cancellation(&failed(
+            Some("user CANCELED the flow"),
+            None
+        )));
+        assert!(!is_oauth_cancellation(&failed(
+            Some("network exploded"),
+            Some(TokenFailureReason::NetworkError)
+        )));
+        // No message → reason string is checked (none of the reasons contain
+        // "cancelled", so this stays false).
+        assert!(!is_oauth_cancellation(&failed(
+            None,
+            Some(TokenFailureReason::Unknown)
+        )));
+        let success = TokenResult::Success(TokenSuccess {
+            access: "a".into(),
+            refresh: "r".into(),
+            expires: 1,
+            id_token: None,
+            multi_account: None,
+        });
+        assert!(!is_oauth_cancellation(&success));
+    }
+
+    #[test]
+    fn resolved_write_prefers_override_and_labels_manual_source() {
+        let tokens = TokenSuccess {
+            access: "not-a-jwt".into(),
+            refresh: "rt-0123456789abcdefghij".into(),
+            expires: 999,
+            id_token: None,
+            multi_account: None,
+        };
+        let result = TokenSuccessWithAccount {
+            tokens,
+            account_id_override: Some("acc_org".into()),
+            account_id_source: None,
+            account_label: Some("Org".into()),
+            workspaces: None,
+        };
+        let write = build_resolved_account_write(&result, 42);
+        assert_eq!(write.account_id.as_deref(), Some("acc_org"));
+        // No explicit source + override present → manual.
+        assert_eq!(write.account_id_source, Some(AccountIdSource::Manual));
+        assert_eq!(write.account_label.as_deref(), Some("Org"));
+        assert_eq!(write.access_token.as_deref(), Some("not-a-jwt"));
+        assert_eq!(write.expires_at, Some(999));
+        assert_eq!(write.now, 42);
+    }
+
+    #[test]
+    fn resolve_account_selection_without_candidates_returns_plain_tokens() {
+        let tokens = TokenSuccess {
+            access: "not-a-jwt".into(),
+            refresh: "rt-0123456789abcdefghij".into(),
+            expires: 1,
+            id_token: None,
+            multi_account: None,
+        };
+        let resolved = resolve_account_selection(&tokens, None);
+        assert_eq!(resolved, TokenSuccessWithAccount::plain(tokens));
+    }
+}
diff --git a/crates/manager/src/login/persist_selected.rs b/crates/manager/src/login/persist_selected.rs
new file mode 100644
index 000000000..103438ec3
--- /dev/null
+++ b/crates/manager/src/login/persist_selected.rs
@@ -0,0 +1,290 @@
+//! Port of `lib/codex-manager/persist-selected-account.ts` — persist a
+//! selected account (switch/best/restore) and mirror it into the Codex CLI
+//! auth files.
+//!
+//! Key contracts (spec 09 §1.9):
+//! - `preserveActiveIndexByFamily` only actually preserves when the flag is
+//!   set AND a family map exists AND `targetIndex === storage.activeIndex`;
+//!   even then values are clamped (non-finite/missing → targetIndex).
+//!   Otherwise EVERY family is set to `targetIndex` (gotcha 19).
+//! - `bumpAffinityGeneration` re-reads the disk generation right before save
+//!   and takes `max(inMemory, disk) + 1` (#474).
+//! - A stale access token triggers a validation refresh; failure only warns
+//!   and continues with the stale tokens.
+
+use cma_cli_mirror::writer::{set_codex_cli_active_selection, ActiveSelection};
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::schemas::account_storage::{
+    AccountStorageV3, ActiveIndexByFamily, PersistedSwitchReason,
+};
+use cma_core::schemas::token::TokenResult;
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_core::utils::now_ms;
+use cma_storage::facade::get_storage_path;
+use cma_storage::load::read_affinity_generation_from_disk;
+use cma_storage::save_retry::save_accounts_with_retry;
+
+use crate::login::account_credentials::{apply_token_account_identity, has_usable_access_token};
+
+/// Parameters (TS options object). `parsed` is the 1-based user-facing
+/// number, distinct from `target_index`.
+pub struct PersistSelectedAccountParams {
+    pub storage: AccountStorageV3,
+    pub target_index: usize,
+    pub parsed: i64,
+    pub switch_reason: PersistedSwitchReason,
+    pub initial_sync_id_token: Option<String>,
+    pub preserve_active_index_by_family: bool,
+    pub set_pin: bool,
+    pub clear_pin: bool,
+    pub bump_affinity_generation: bool,
+}
+
+/// `{ synced, wasDisabled }`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct PersistSelectedOutcome {
+    pub synced: bool,
+    pub was_disabled: bool,
+}
+
+/// Minimal local mirror of `normalizeFailureDetail` (canonical Rust home is
+/// the sibling `crate::formatters::text_style`): message-or-reason fallback,
+/// whitespace collapse, 260-char cap.
+fn normalize_failure_detail(message: Option<&str>, reason: Option<&str>) -> String {
+    let raw = message
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+        .or_else(|| reason.map(str::to_string))
+        .unwrap_or_else(|| "refresh failed".to_string());
+    let collapsed = raw.split_whitespace().collect::<Vec<_>>().join(" ");
+    let bounded = if collapsed.chars().count() > 260 {
+        let head: String = collapsed.chars().take(257).collect();
+        format!("{head}...")
+    } else {
+        collapsed
+    };
+    if bounded.is_empty() {
+        "refresh failed".to_string()
+    } else {
+        bounded
+    }
+}
+
+/// `persistAndSyncSelectedAccount(options)`.
+///
+/// Missing account → the TS throw `Account ${parsed} not found.`; callers
+/// bounds-check first, so the Rust port panics with the identical message
+/// (an uncaught TS exception aborts the command the same way).
+pub async fn persist_and_sync_selected_account(
+    params: PersistSelectedAccountParams,
+) -> PersistSelectedOutcome {
+    let PersistSelectedAccountParams {
+        mut storage,
+        target_index,
+        parsed,
+        switch_reason,
+        initial_sync_id_token,
+        preserve_active_index_by_family,
+        set_pin,
+        clear_pin,
+        bump_affinity_generation,
+    } = params;
+
+    let accounts_len = storage.accounts.len();
+    if target_index >= accounts_len {
+        panic!("Account {parsed} not found.");
+    }
+    let now = now_ms();
+
+    // --- activeIndexByFamily (gotcha 19) ------------------------------------
+    let preserve = preserve_active_index_by_family
+        && storage.active_index_by_family.is_some()
+        && target_index as i64 == storage.active_index;
+    let mut next_by_family = ActiveIndexByFamily::default();
+    if preserve {
+        let existing = storage
+            .active_index_by_family
+            .clone()
+            .unwrap_or_default();
+        let max_index = accounts_len as i64 - 1;
+        for family in MODEL_FAMILIES {
+            let value = match existing.get(family) {
+                Some(value) => value.clamp(0, max_index),
+                None => target_index as i64,
+            };
+            next_by_family.set(family, Some(value));
+        }
+    } else {
+        for family in MODEL_FAMILIES {
+            next_by_family.set(family, Some(target_index as i64));
+        }
+    }
+    storage.active_index_by_family = Some(next_by_family);
+    storage.active_index = target_index as i64;
+
+    // --- selection bookkeeping ----------------------------------------------
+    let was_disabled = storage.accounts[target_index].enabled == Some(false);
+    if was_disabled {
+        storage.accounts[target_index].enabled = Some(true);
+    }
+
+    let mut sync_access_token = storage.accounts[target_index].access_token.clone();
+    let mut sync_refresh_token = storage.accounts[target_index].refresh_token.clone();
+    let mut sync_expires_at = storage.accounts[target_index].expires_at;
+    let mut sync_id_token = initial_sync_id_token;
+
+    if !has_usable_access_token(&storage.accounts[target_index], now) {
+        let refresh_token = storage.accounts[target_index].refresh_token.clone();
+        match cma_auth::refresh_queue::queued_refresh(&refresh_token).await {
+            TokenResult::Success(success) => {
+                let account = &mut storage.accounts[target_index];
+                if account.refresh_token != success.refresh {
+                    account.refresh_token = success.refresh.clone();
+                }
+                if account.access_token.as_deref() != Some(success.access.as_str()) {
+                    account.access_token = Some(success.access.clone());
+                }
+                if account.expires_at != Some(success.expires) {
+                    account.expires_at = Some(success.expires);
+                }
+                let next_email = sanitize_email(
+                    extract_account_email(Some(&success.access), success.id_token.as_deref())
+                        .as_deref(),
+                );
+                if let Some(next_email) = &next_email
+                    && !next_email.is_empty() && account.email.as_deref() != Some(next_email) {
+                        account.email = Some(next_email.clone());
+                    }
+                let token_account_id = extract_account_id(Some(&success.access));
+                apply_token_account_identity(account, token_account_id.as_deref());
+
+                sync_access_token = Some(success.access.clone());
+                sync_refresh_token = success.refresh.clone();
+                sync_expires_at = Some(success.expires);
+                // Fresh idToken (when present) wins over the caller-supplied
+                // one for the Codex sync.
+                if success.id_token.is_some() {
+                    sync_id_token = success.id_token.clone();
+                }
+            }
+            TokenResult::Failed(failure) => {
+                eprintln!(
+                    "Switch validation refresh failed for account {parsed}: {}.",
+                    normalize_failure_detail(
+                        failure.message.as_deref(),
+                        failure.reason.map(|reason| reason.as_str())
+                    )
+                );
+            }
+        }
+    }
+
+    let switch_now = now_ms();
+    {
+        let account = &mut storage.accounts[target_index];
+        account.last_used = switch_now;
+        account.last_switch_reason = Some(switch_reason.into());
+    }
+
+    if set_pin {
+        storage.pinned_account_index = Some(target_index as i64);
+    }
+    if clear_pin {
+        storage.pinned_account_index = None;
+    }
+    if bump_affinity_generation {
+        // Re-read disk RIGHT BEFORE save to narrow the lost-update window
+        // (#474): extra bumps harmless, missed bumps dangerous.
+        let in_memory = storage.affinity_generation.unwrap_or(0);
+        let on_disk = read_affinity_generation_from_disk(get_storage_path());
+        storage.affinity_generation = Some(in_memory.max(on_disk) + 1);
+    }
+
+    if let Err(error) = save_accounts_with_retry(&storage).await {
+        // TS lets the storage error propagate as an uncaught exception; the
+        // Rust CLI surfaces it and reports the selection as unsynced.
+        eprintln!("{}", error.message());
+        return PersistSelectedOutcome {
+            synced: false,
+            was_disabled,
+        };
+    }
+
+    let account = &storage.accounts[target_index];
+    let synced = set_codex_cli_active_selection(&ActiveSelection {
+        account_id: account.account_id.clone(),
+        email: account.email.clone(),
+        access_token: sync_access_token,
+        refresh_token: Some(sync_refresh_token),
+        expires_at: sync_expires_at.map(|value| value as f64),
+        id_token: sync_id_token,
+    })
+    .await;
+
+    PersistSelectedOutcome {
+        synced,
+        was_disabled,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalize_failure_detail_prefers_message_then_reason() {
+        assert_eq!(
+            normalize_failure_detail(Some("  network   down  "), Some("network_error")),
+            "network down"
+        );
+        assert_eq!(
+            normalize_failure_detail(None, Some("http_error")),
+            "http_error"
+        );
+        assert_eq!(normalize_failure_detail(None, None), "refresh failed");
+        assert_eq!(normalize_failure_detail(Some("   "), None), "refresh failed");
+        let long = "x".repeat(300);
+        let bounded = normalize_failure_detail(Some(&long), None);
+        assert_eq!(bounded.chars().count(), 260);
+        assert!(bounded.ends_with("..."));
+    }
+
+    #[test]
+    fn family_map_building_matches_the_preserve_rules() {
+        // Indirectly cover the preserve/clamp matrix through a tiny harness:
+        // preserve applies only when flag && map exists && target == active.
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![
+            cma_core::schemas::account_storage::AccountMetadataV3::new(
+                "rt-aaaaaaaaaaaaaaaaaaaa",
+                0,
+                0,
+            ),
+            cma_core::schemas::account_storage::AccountMetadataV3::new(
+                "rt-bbbbbbbbbbbbbbbbbbbb",
+                0,
+                0,
+            ),
+        ];
+        storage.active_index = 1;
+        let mut by_family = ActiveIndexByFamily::default();
+        // A stale out-of-range family entry gets clamped when preserved.
+        by_family.set(cma_core::model_family::ModelFamily::Codex, Some(9));
+        storage.active_index_by_family = Some(by_family);
+
+        // Not preserved: target != activeIndex.
+        let preserve = storage.active_index_by_family.is_some() && 0_i64 == storage.active_index;
+        assert!(!preserve);
+        // Preserved: target == activeIndex → clamp 9 → 1, missing → target.
+        let preserve = storage.active_index_by_family.is_some() && 1_i64 == storage.active_index;
+        assert!(preserve);
+        let existing = storage.active_index_by_family.clone().unwrap();
+        let clamped = existing
+            .get(cma_core::model_family::ModelFamily::Codex)
+            .unwrap()
+            .clamp(0, storage.accounts.len() as i64 - 1);
+        assert_eq!(clamped, 1);
+        assert_eq!(existing.get(cma_core::model_family::ModelFamily::Gpt5_1), None);
+    }
+}
diff --git a/crates/manager/src/oc_chatgpt/import_adapter.rs b/crates/manager/src/oc_chatgpt/import_adapter.rs
new file mode 100644
index 000000000..ca94e49fc
--- /dev/null
+++ b/crates/manager/src/oc_chatgpt/import_adapter.rs
@@ -0,0 +1,1228 @@
+//! Port of `lib/oc-chatgpt-import-adapter.ts` — pure merge/normalize logic to
+//! export this tool's account pool into oc-chatgpt-multi-auth.
+//!
+//! Key invariants (spec 12 §11 + gotchas 14–17):
+//! - De-dup bucket ORDER defines output account order: identity bucket, then
+//!   email, then refresh-token, each insertion-ordered.
+//! - Bare accountId without email deliberately skips the accountId bucket so
+//!   a shared workspace id cannot collapse distinct business accounts.
+//! - `pickNewest` ties prefer the CURRENT/destination record.
+//! - Merge NEVER touches destination active selection
+//!   (`preserve-destination`).
+
+use std::collections::HashSet;
+
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::schemas::account_storage::{
+    AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily,
+};
+use cma_core::schemas::parse::Version3;
+use cma_storage::identity::{get_account_identity_key, normalize_email_key};
+use cma_storage::matching::{AccountMatchOptions, find_matching_account_index};
+use serde::Serialize;
+
+/// TS `MatchStrategy = "accountId" | "email" | "refreshToken"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+pub enum MatchStrategy {
+    #[serde(rename = "accountId")]
+    AccountId,
+    #[serde(rename = "email")]
+    Email,
+    #[serde(rename = "refreshToken")]
+    RefreshToken,
+}
+
+impl MatchStrategy {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            MatchStrategy::AccountId => "accountId",
+            MatchStrategy::Email => "email",
+            MatchStrategy::RefreshToken => "refreshToken",
+        }
+    }
+}
+
+/// TS `OcChatgptImportPayload = AccountStorageV3`.
+pub type OcChatgptImportPayload = AccountStorageV3;
+
+/// TS `OcChatgptAccountRef` — preview-safe reference with a masked token.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct OcChatgptAccountRef {
+    #[serde(rename = "accountId", skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub email: Option<String>,
+    #[serde(rename = "refreshTokenLast4")]
+    pub refresh_token_last4: String,
+}
+
+/// TS `OcChatgptPreviewPayload`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct OcChatgptPreviewPayload {
+    /// Literal `3`.
+    pub version: Version3,
+    #[serde(rename = "activeIndex")]
+    pub active_index: i64,
+    #[serde(
+        rename = "activeIndexByFamily",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub active_index_by_family: Option<ActiveIndexByFamily>,
+    pub accounts: Vec<OcChatgptAccountRef>,
+}
+
+/// One `toUpdate` entry.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct OcChatgptUpdateEntry {
+    pub previous: OcChatgptAccountRef,
+    pub next: OcChatgptAccountRef,
+    #[serde(rename = "matchedBy")]
+    pub matched_by: MatchStrategy,
+}
+
+/// One `toSkip` entry.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct OcChatgptSkipEntry {
+    pub source: OcChatgptAccountRef,
+    pub reason: String,
+}
+
+/// TS `OcChatgptMergePreview`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct OcChatgptMergePreview {
+    pub payload: OcChatgptPreviewPayload,
+    /// WARNING: contains raw refreshToken values — do not log directly.
+    pub merged: AccountStorageV3,
+    pub to_add: Vec<OcChatgptAccountRef>,
+    pub to_update: Vec<OcChatgptUpdateEntry>,
+    pub to_skip: Vec<OcChatgptSkipEntry>,
+    pub unchanged_destination_only: Vec<OcChatgptAccountRef>,
+    /// Always `"preserve-destination"`.
+    pub active_selection_behavior: &'static str,
+}
+
+struct NormalizedForTarget {
+    storage: AccountStorageV3,
+    skipped: Vec<OcChatgptSkipEntry>,
+}
+
+/// Adapter-local `clampIndex(index, length)` (TS defines its own).
+fn clamp_index(index: i64, length: usize) -> i64 {
+    if length == 0 {
+        return 0;
+    }
+    index.clamp(0, (length - 1) as i64)
+}
+
+/// TS `pickNewest(current, candidate)` — returns true when CANDIDATE wins:
+/// strictly larger `lastUsed`, or a `lastUsed` tie with strictly larger
+/// `addedAt`. Full ties prefer `current`.
+fn candidate_is_newest(current: &AccountMetadataV3, candidate: &AccountMetadataV3) -> bool {
+    if candidate.last_used > current.last_used {
+        return true;
+    }
+    if candidate.last_used < current.last_used {
+        return false;
+    }
+    candidate.added_at > current.added_at
+}
+
+fn trimmed_or_none(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `sanitizeAccount(account)` — `None` when the refresh token is empty
+/// after trimming; trims id/email/label; other fields spread through
+/// unchanged.
+fn sanitize_account(account: &AccountMetadataV3) -> Option<AccountMetadataV3> {
+    let refresh_token = account.refresh_token.trim();
+    if refresh_token.is_empty() {
+        return None;
+    }
+    let mut sanitized = account.clone();
+    sanitized.account_id = trimmed_or_none(account.account_id.as_deref());
+    sanitized.email = trimmed_or_none(account.email.as_deref());
+    sanitized.account_label = trimmed_or_none(account.account_label.as_deref());
+    sanitized.refresh_token = refresh_token.to_string();
+    Some(sanitized)
+}
+
+/// TS `tokenLast4(token)` — `<= 4` chars ⇒ all asterisks, else last 4.
+fn token_last4(token: &str) -> String {
+    let trimmed = token.trim();
+    let chars: Vec<char> = trimmed.chars().collect();
+    if chars.len() <= 4 {
+        return "*".repeat(chars.len());
+    }
+    chars[chars.len() - 4..].iter().collect()
+}
+
+/// TS `summarizeAccount(account)`.
+fn summarize_account(account: &AccountMetadataV3) -> OcChatgptAccountRef {
+    OcChatgptAccountRef {
+        account_id: account.account_id.clone(),
+        email: account.email.clone(),
+        refresh_token_last4: token_last4(&account.refresh_token),
+    }
+}
+
+/// TS `buildPreviewPayload(storage)`.
+fn build_preview_payload(storage: &AccountStorageV3) -> OcChatgptPreviewPayload {
+    OcChatgptPreviewPayload {
+        version: Version3::default(),
+        active_index: storage.active_index,
+        active_index_by_family: storage.active_index_by_family.clone(),
+        accounts: storage.accounts.iter().map(summarize_account).collect(),
+    }
+}
+
+/// TS `remapActiveIndex(originalAccounts, originalIndex, normalizedAccounts)`.
+fn remap_active_index(
+    original_accounts: Option<&[AccountMetadataV3]>,
+    original_index: Option<i64>,
+    normalized_accounts: &[AccountMetadataV3],
+) -> i64 {
+    let Some(original) = original_accounts.filter(|accounts| !accounts.is_empty()) else {
+        return clamp_index(0, normalized_accounts.len());
+    };
+    let safe_original_index = clamp_index(original_index.unwrap_or(0), original.len());
+    let original_active = &original[safe_original_index as usize];
+    if let Some(remapped) = find_matching_account_index(
+        normalized_accounts,
+        original_active,
+        AccountMatchOptions::default(),
+    ) {
+        return remapped as i64;
+    }
+    clamp_index(safe_original_index, normalized_accounts.len())
+}
+
+/// TS `normalizeActiveIndexByFamily(...)` — iterates `MODEL_FAMILIES` only
+/// (unknown keys are dropped by the typed map), skips missing values.
+fn normalize_active_index_by_family(
+    active_index_by_family: Option<&ActiveIndexByFamily>,
+    original_accounts: Option<&[AccountMetadataV3]>,
+    normalized_accounts: &[AccountMetadataV3],
+) -> Option<ActiveIndexByFamily> {
+    let map = active_index_by_family?;
+    let mut normalized = ActiveIndexByFamily::default();
+    for family in MODEL_FAMILIES {
+        let Some(raw) = map.get(family) else {
+            continue;
+        };
+        normalized.set(
+            family,
+            Some(remap_active_index(
+                original_accounts,
+                Some(raw),
+                normalized_accounts,
+            )),
+        );
+    }
+    if normalized.is_empty() {
+        None
+    } else {
+        Some(normalized)
+    }
+}
+
+/// Insertion-ordered map bucket (JS `Map.set` keeps the original slot when a
+/// key is replaced).
+struct Bucket {
+    entries: Vec<(String, AccountMetadataV3)>,
+}
+
+impl Bucket {
+    fn new() -> Self {
+        Bucket { entries: Vec::new() }
+    }
+
+    fn get(&self, key: &str) -> Option<&AccountMetadataV3> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, account)| account)
+    }
+
+    fn set(&mut self, key: &str, account: AccountMetadataV3) {
+        if let Some(slot) = self.entries.iter_mut().find(|(k, _)| k == key) {
+            slot.1 = account;
+        } else {
+            self.entries.push((key.to_string(), account));
+        }
+    }
+
+    fn into_values(self) -> impl Iterator<Item = AccountMetadataV3> {
+        self.entries.into_iter().map(|(_, account)| account)
+    }
+}
+
+/// TS `normalizeAccountsForTarget(accounts)`.
+fn normalize_accounts_for_target(
+    accounts: &[AccountMetadataV3],
+) -> (Vec<AccountMetadataV3>, Vec<OcChatgptSkipEntry>) {
+    let mut skipped: Vec<OcChatgptSkipEntry> = Vec::new();
+    let mut valid: Vec<AccountMetadataV3> = Vec::new();
+
+    for candidate in accounts {
+        match sanitize_account(candidate) {
+            Some(sanitized) => valid.push(sanitized),
+            None => skipped.push(OcChatgptSkipEntry {
+                source: summarize_account(candidate),
+                reason: "invalid-refresh-token".to_string(),
+            }),
+        }
+    }
+
+    let mut by_account_identity = Bucket::new();
+    let mut without_account_id: Vec<AccountMetadataV3> = Vec::new();
+
+    for account in valid {
+        if account.account_id.is_some() && normalize_email_key(account.email.as_deref()).is_some()
+        {
+            let Some(identity_key) = get_account_identity_key(&account) else {
+                without_account_id.push(account);
+                continue;
+            };
+            match by_account_identity.get(&identity_key) {
+                None => by_account_identity.set(&identity_key, account),
+                Some(existing) => {
+                    if candidate_is_newest(existing, &account) {
+                        skipped.push(OcChatgptSkipEntry {
+                            source: summarize_account(existing),
+                            reason: "duplicate-account-id".to_string(),
+                        });
+                        by_account_identity.set(&identity_key, account);
+                    } else {
+                        skipped.push(OcChatgptSkipEntry {
+                            source: summarize_account(&account),
+                            reason: "duplicate-account-id".to_string(),
+                        });
+                    }
+                }
+            }
+            continue;
+        }
+        without_account_id.push(account);
+    }
+
+    let mut by_email = Bucket::new();
+    let mut without_identity: Vec<AccountMetadataV3> = Vec::new();
+
+    for account in without_account_id {
+        if let Some(normalized_email) = normalize_email_key(account.email.as_deref()) {
+            match by_email.get(&normalized_email) {
+                None => by_email.set(&normalized_email, account),
+                Some(existing) => {
+                    if candidate_is_newest(existing, &account) {
+                        skipped.push(OcChatgptSkipEntry {
+                            source: summarize_account(existing),
+                            reason: "duplicate-email".to_string(),
+                        });
+                        by_email.set(&normalized_email, account);
+                    } else {
+                        skipped.push(OcChatgptSkipEntry {
+                            source: summarize_account(&account),
+                            reason: "duplicate-email".to_string(),
+                        });
+                    }
+                }
+            }
+            continue;
+        }
+        without_identity.push(account);
+    }
+
+    let mut by_refresh_token = Bucket::new();
+    for account in without_identity {
+        let key = account.refresh_token.clone();
+        match by_refresh_token.get(&key) {
+            None => by_refresh_token.set(&key, account),
+            Some(existing) => {
+                if candidate_is_newest(existing, &account) {
+                    skipped.push(OcChatgptSkipEntry {
+                        source: summarize_account(existing),
+                        reason: "duplicate-refresh-token".to_string(),
+                    });
+                    by_refresh_token.set(&key, account);
+                } else {
+                    skipped.push(OcChatgptSkipEntry {
+                        source: summarize_account(&account),
+                        reason: "duplicate-refresh-token".to_string(),
+                    });
+                }
+            }
+        }
+    }
+
+    let accounts: Vec<AccountMetadataV3> = by_account_identity
+        .into_values()
+        .chain(by_email.into_values())
+        .chain(by_refresh_token.into_values())
+        .collect();
+    (accounts, skipped)
+}
+
+/// TS `normalizeStorageForTarget(storage)`.
+///
+/// NOTE: the TS output literal carries only `version/accounts/activeIndex/
+/// activeIndexByFamily` — a source `pinnedAccountIndex`/`affinityGeneration`
+/// is deliberately dropped (verified against the TS source; spec 12 §14's
+/// "passes through" note describes the field's optionality, not this path).
+fn normalize_storage_for_target(storage: Option<&AccountStorageV3>) -> NormalizedForTarget {
+    let original_accounts = storage.map(|s| s.accounts.as_slice());
+    let (accounts, skipped) = normalize_accounts_for_target(original_accounts.unwrap_or(&[]));
+    let active_index = remap_active_index(
+        original_accounts,
+        storage.map(|s| s.active_index),
+        &accounts,
+    );
+    let active_index_by_family = normalize_active_index_by_family(
+        storage.and_then(|s| s.active_index_by_family.as_ref()),
+        original_accounts,
+        &accounts,
+    );
+    NormalizedForTarget {
+        storage: AccountStorageV3 {
+            version: Version3::default(),
+            accounts,
+            active_index,
+            active_index_by_family,
+            pinned_account_index: None,
+            affinity_generation: None,
+        },
+        skipped,
+    }
+}
+
+/// TS `cloneStorage(storage)`.
+fn clone_storage(storage: &AccountStorageV3) -> AccountStorageV3 {
+    AccountStorageV3 {
+        version: Version3::default(),
+        accounts: storage.accounts.clone(),
+        active_index: storage.active_index,
+        active_index_by_family: storage.active_index_by_family.clone(),
+        pinned_account_index: None,
+        affinity_generation: None,
+    }
+}
+
+/// TS `matchDestination(source, destination, usedIndexes)` — ordered rules:
+/// (a) exact accountId+email composite identity; (b) unique bare accountId
+/// (bails on multiple matches; email conflict rejects); (c) email against
+/// id-less destination rows only; (d) refreshToken against rows with neither
+/// id nor email.
+fn match_destination(
+    source: &AccountMetadataV3,
+    destination: &[AccountMetadataV3],
+    used_indexes: &HashSet<usize>,
+) -> Option<(usize, MatchStrategy)> {
+    let source_account_id = source
+        .account_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+    let source_email = normalize_email_key(source.email.as_deref());
+
+    if source_account_id.is_some() && source_email.is_some() {
+        let source_identity_key = get_account_identity_key(source);
+        for (i, account) in destination.iter().enumerate() {
+            if used_indexes.contains(&i) {
+                continue;
+            }
+            if get_account_identity_key(account) == source_identity_key {
+                return Some((i, MatchStrategy::AccountId));
+            }
+        }
+    }
+
+    if let Some(source_id) = source_account_id {
+        let mut idx: Option<usize> = None;
+        let mut matched_email: Option<String> = None;
+        for (i, account) in destination.iter().enumerate() {
+            if used_indexes.contains(&i) {
+                continue;
+            }
+            if account.account_id.as_deref().map(str::trim) != Some(source_id) {
+                continue;
+            }
+            if idx.is_some() {
+                idx = None;
+                break;
+            }
+            idx = Some(i);
+            matched_email = normalize_email_key(account.email.as_deref());
+        }
+        if let Some(i) = idx
+            && (source_email.is_none()
+                || matched_email.is_none()
+                || matched_email == source_email)
+        {
+            return Some((i, MatchStrategy::AccountId));
+        }
+    }
+
+    if let Some(source_email) = &source_email {
+        for (i, account) in destination.iter().enumerate() {
+            if used_indexes.contains(&i) {
+                continue;
+            }
+            if account.account_id.is_some() {
+                continue;
+            }
+            if normalize_email_key(account.email.as_deref()).as_ref() == Some(source_email) {
+                return Some((i, MatchStrategy::Email));
+            }
+        }
+    }
+
+    for (i, account) in destination.iter().enumerate() {
+        if used_indexes.contains(&i) {
+            continue;
+        }
+        if account.account_id.is_some() {
+            continue;
+        }
+        if normalize_email_key(account.email.as_deref()).is_some() {
+            continue;
+        }
+        if account.refresh_token == source.refresh_token {
+            return Some((i, MatchStrategy::RefreshToken));
+        }
+    }
+
+    None
+}
+
+/// TS `buildOcChatgptImportPayload(source)`.
+///
+/// WARNING: the payload includes raw `refreshToken` values — redact before
+/// logging.
+pub fn build_oc_chatgpt_import_payload(
+    source: Option<&AccountStorageV3>,
+) -> OcChatgptImportPayload {
+    normalize_storage_for_target(source).storage
+}
+
+/// TS `previewOcChatgptImportMerge({source, destination})`.
+pub fn preview_oc_chatgpt_import_merge(
+    source: Option<&AccountStorageV3>,
+    destination: Option<&AccountStorageV3>,
+) -> OcChatgptMergePreview {
+    let source_normalized = normalize_storage_for_target(source);
+    let destination_normalized = normalize_storage_for_target(destination);
+
+    let mut merged = clone_storage(&destination_normalized.storage);
+    // Match targets are a snapshot limited to the original destination length
+    // so newly appended source accounts are never match targets.
+    let destination_accounts: Vec<AccountMetadataV3> = merged
+        .accounts
+        .iter()
+        .take(destination_normalized.storage.accounts.len())
+        .cloned()
+        .collect();
+    let mut used_destination_indexes: HashSet<usize> = HashSet::new();
+
+    let mut to_add: Vec<OcChatgptAccountRef> = Vec::new();
+    let mut to_update: Vec<OcChatgptUpdateEntry> = Vec::new();
+    let mut to_skip: Vec<OcChatgptSkipEntry> = source_normalized.skipped.clone();
+    to_skip.extend(destination_normalized.skipped.iter().map(|entry| {
+        OcChatgptSkipEntry {
+            source: entry.source.clone(),
+            reason: format!("destination-{}", entry.reason),
+        }
+    }));
+
+    for account in &source_normalized.storage.accounts {
+        let Some((index, matched_by)) =
+            match_destination(account, &destination_accounts, &used_destination_indexes)
+        else {
+            merged.accounts.push(account.clone());
+            to_add.push(summarize_account(account));
+            continue;
+        };
+
+        let current = merged.accounts[index].clone();
+        used_destination_indexes.insert(index);
+        if !candidate_is_newest(&current, account) {
+            to_skip.push(OcChatgptSkipEntry {
+                source: summarize_account(account),
+                reason: "unchanged-or-older-than-destination".to_string(),
+            });
+            continue;
+        }
+
+        merged.accounts[index] = account.clone();
+        to_update.push(OcChatgptUpdateEntry {
+            previous: summarize_account(&current),
+            next: summarize_account(account),
+            matched_by,
+        });
+    }
+
+    let destination_length = destination_normalized.storage.accounts.len();
+    let mut unchanged_destination_only: Vec<OcChatgptAccountRef> = Vec::new();
+    for (i, account) in destination_normalized
+        .storage
+        .accounts
+        .iter()
+        .enumerate()
+        .take(destination_length)
+    {
+        if used_destination_indexes.contains(&i) {
+            continue;
+        }
+        unchanged_destination_only.push(summarize_account(account));
+    }
+
+    OcChatgptMergePreview {
+        payload: build_preview_payload(&source_normalized.storage),
+        merged,
+        to_add,
+        to_update,
+        to_skip,
+        unchanged_destination_only,
+        active_selection_behavior: "preserve-destination",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Ported from test/oc-chatgpt-import-adapter.test.ts.
+
+    fn account(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        refresh_token: &str,
+        added_at: i64,
+        last_used: i64,
+    ) -> AccountMetadataV3 {
+        let mut a = AccountMetadataV3::new(refresh_token, added_at, last_used);
+        a.account_id = account_id.map(str::to_string);
+        a.email = email.map(str::to_string);
+        a
+    }
+
+    fn storage(accounts: Vec<AccountMetadataV3>, active_index: i64) -> AccountStorageV3 {
+        let mut s = AccountStorageV3::empty();
+        s.accounts = accounts;
+        s.active_index = active_index;
+        s
+    }
+
+    fn ref_of(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        last4: &str,
+    ) -> OcChatgptAccountRef {
+        OcChatgptAccountRef {
+            account_id: account_id.map(str::to_string),
+            email: email.map(str::to_string),
+            refresh_token_last4: last4.to_string(),
+        }
+    }
+
+    #[test]
+    fn builds_payload_filtering_invalid_and_preserving_identity_rich_duplicates() {
+        let source = storage(
+            vec![
+                account(Some("acc-1"), Some("same@example.com"), "token-new", 5, 5),
+                account(Some("acc-1"), Some("same@example.com"), "token-old", 3, 3),
+                account(Some("acc-2"), Some("same@example.com"), "token-two", 4, 4),
+                account(None, Some("legacy@example.com"), "token-legacy-new", 2, 9),
+                account(None, Some("legacy@example.com"), "token-legacy-old", 1, 1),
+                account(None, Some("no-token@example.com"), "   ", 1, 1),
+            ],
+            0,
+        );
+
+        let payload = build_oc_chatgpt_import_payload(Some(&source));
+        assert_eq!(payload.accounts.len(), 3);
+        let acc1 = payload
+            .accounts
+            .iter()
+            .find(|a| a.account_id.as_deref() == Some("acc-1"))
+            .expect("acc-1 kept");
+        assert_eq!(acc1.refresh_token, "token-new");
+        assert!(
+            payload
+                .accounts
+                .iter()
+                .any(|a| a.account_id.as_deref() == Some("acc-2"))
+        );
+        let legacy = payload
+            .accounts
+            .iter()
+            .find(|a| a.email.as_deref() == Some("legacy@example.com"))
+            .expect("legacy kept");
+        assert_eq!(legacy.refresh_token, "token-legacy-new");
+    }
+
+    #[test]
+    fn previews_merge_with_account_id_precedence_and_preserves_destination_selection() {
+        let mut destination = storage(
+            vec![
+                account(Some("acc-1"), Some("same@example.com"), "token-old", 1, 1),
+                {
+                    let mut a =
+                        account(Some("acc-2"), Some("same@example.com"), "token-two", 2, 2);
+                    a.account_label = Some("Destination only".to_string());
+                    a
+                },
+                account(None, Some("legacy-only@example.com"), "legacy-old", 1, 1),
+            ],
+            1,
+        );
+        destination.active_index_by_family = Some(ActiveIndexByFamily {
+            codex: Some(1),
+            ..Default::default()
+        });
+
+        let source = storage(
+            vec![
+                account(Some("acc-1"), Some("same@example.com"), "token-new", 3, 5),
+                account(Some("acc-3"), Some("same@example.com"), "token-three", 4, 4),
+                account(None, Some("legacy-only@example.com"), "legacy-new", 2, 6),
+            ],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.active_selection_behavior, "preserve-destination");
+        assert_eq!(
+            preview.payload.accounts,
+            vec![
+                ref_of(Some("acc-1"), Some("same@example.com"), "-new"),
+                ref_of(Some("acc-3"), Some("same@example.com"), "hree"),
+                ref_of(None, Some("legacy-only@example.com"), "-new"),
+            ]
+        );
+        assert_eq!(preview.to_add.len(), 1);
+        assert_eq!(preview.to_update.len(), 2);
+        assert_eq!(preview.to_skip.len(), 0);
+        assert_eq!(preview.unchanged_destination_only.len(), 1);
+        assert_eq!(preview.merged.accounts.len(), 4);
+        assert_eq!(preview.merged.active_index, destination.active_index);
+        assert_eq!(
+            preview
+                .merged
+                .active_index_by_family
+                .as_ref()
+                .and_then(|f| f.codex),
+            Some(1)
+        );
+
+        let updated_acc1 = preview
+            .merged
+            .accounts
+            .iter()
+            .find(|a| a.account_id.as_deref() == Some("acc-1"))
+            .expect("acc-1 updated");
+        assert_eq!(updated_acc1.refresh_token, "token-new");
+
+        assert!(
+            preview
+                .merged
+                .accounts
+                .iter()
+                .any(|a| a.account_id.as_deref() == Some("acc-3"))
+        );
+
+        let updated_legacy = preview
+            .merged
+            .accounts
+            .iter()
+            .find(|a| a.email.as_deref() == Some("legacy-only@example.com"))
+            .expect("legacy updated");
+        assert_eq!(updated_legacy.refresh_token, "legacy-new");
+
+        let preserved = preview
+            .merged
+            .accounts
+            .iter()
+            .find(|a| a.account_id.as_deref() == Some("acc-2"))
+            .expect("destination-only preserved");
+        assert_eq!(preserved, &destination.accounts[1]);
+
+        assert_eq!(
+            preview.to_update,
+            vec![
+                OcChatgptUpdateEntry {
+                    previous: ref_of(Some("acc-1"), Some("same@example.com"), "-old"),
+                    next: ref_of(Some("acc-1"), Some("same@example.com"), "-new"),
+                    matched_by: MatchStrategy::AccountId,
+                },
+                OcChatgptUpdateEntry {
+                    previous: ref_of(None, Some("legacy-only@example.com"), "-old"),
+                    next: ref_of(None, Some("legacy-only@example.com"), "-new"),
+                    matched_by: MatchStrategy::Email,
+                },
+            ]
+        );
+        assert_eq!(
+            preview.to_add,
+            vec![ref_of(Some("acc-3"), Some("same@example.com"), "hree")]
+        );
+        assert_eq!(
+            preview.unchanged_destination_only,
+            vec![ref_of(Some("acc-2"), Some("same@example.com"), "-two")]
+        );
+    }
+
+    #[test]
+    fn does_not_collapse_identity_rich_destination_when_source_only_has_email() {
+        let destination = storage(
+            vec![account(
+                Some("acc-identity"),
+                Some("dup@example.com"),
+                "token-dest",
+                1,
+                10,
+            )],
+            0,
+        );
+        let source = storage(
+            vec![account(None, Some("dup@example.com"), "token-source", 2, 3)],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(preview.to_add.len(), 1);
+        assert_eq!(preview.to_add[0].refresh_token_last4, "urce");
+        assert_eq!(preview.merged.accounts.len(), 2);
+        let preserved = preview
+            .merged
+            .accounts
+            .iter()
+            .find(|a| a.account_id.as_deref() == Some("acc-identity"))
+            .expect("preserved");
+        assert_eq!(preserved.refresh_token, "token-dest");
+    }
+
+    #[test]
+    fn does_not_match_by_ambiguous_bare_shared_account_id() {
+        let destination = storage(
+            vec![
+                account(
+                    Some("shared-account"),
+                    Some("alpha@example.com"),
+                    "dest-alpha",
+                    1,
+                    1,
+                ),
+                account(
+                    Some("shared-account"),
+                    Some("beta@example.com"),
+                    "dest-beta",
+                    2,
+                    2,
+                ),
+            ],
+            1,
+        );
+        let source = storage(
+            vec![account(Some("shared-account"), None, "source-new", 3, 3)],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(
+            preview.to_add,
+            vec![ref_of(Some("shared-account"), None, "-new")]
+        );
+        assert_eq!(preview.unchanged_destination_only.len(), 2);
+        assert_eq!(preview.merged.accounts.len(), 3);
+        let tokens: Vec<&str> = preview
+            .merged
+            .accounts
+            .iter()
+            .map(|a| a.refresh_token.as_str())
+            .collect();
+        for expected in ["dest-alpha", "dest-beta", "source-new"] {
+            assert!(tokens.contains(&expected));
+        }
+    }
+
+    #[test]
+    fn preserves_duplicate_no_email_shared_account_id_rows_and_remaps_selection() {
+        let mut source = storage(
+            vec![
+                account(Some("shared-account"), None, "source-old", 1, 1),
+                account(
+                    Some("identity-account"),
+                    Some("gamma@example.com"),
+                    "gamma-refresh",
+                    2,
+                    2,
+                ),
+                account(Some("shared-account"), None, "source-new", 3, 3),
+            ],
+            0,
+        );
+        source.active_index_by_family = Some(ActiveIndexByFamily {
+            codex: Some(0),
+            ..Default::default()
+        });
+
+        let payload = build_oc_chatgpt_import_payload(Some(&source));
+        let empty = storage(vec![], 0);
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&empty));
+
+        let tokens: Vec<&str> = payload
+            .accounts
+            .iter()
+            .map(|a| a.refresh_token.as_str())
+            .collect();
+        assert_eq!(tokens, vec!["gamma-refresh", "source-old", "source-new"]);
+        assert_eq!(
+            payload
+                .accounts
+                .iter()
+                .filter(|a| a.account_id.as_deref() == Some("shared-account"))
+                .count(),
+            2
+        );
+        assert_eq!(payload.active_index, 1);
+        assert_eq!(
+            payload.active_index_by_family.as_ref().and_then(|f| f.codex),
+            Some(1)
+        );
+        assert_eq!(preview.payload.active_index, 1);
+        assert_eq!(
+            preview
+                .payload
+                .active_index_by_family
+                .as_ref()
+                .and_then(|f| f.codex),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn does_not_match_unique_bare_account_id_when_emails_conflict() {
+        let destination = storage(
+            vec![account(
+                Some("shared-account"),
+                Some("beta@example.com"),
+                "dest-beta",
+                1,
+                1,
+            )],
+            0,
+        );
+        let source = storage(
+            vec![account(
+                Some("shared-account"),
+                Some("alpha@example.com"),
+                "source-new",
+                2,
+                2,
+            )],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(
+            preview.to_add,
+            vec![ref_of(
+                Some("shared-account"),
+                Some("alpha@example.com"),
+                "-new"
+            )]
+        );
+        assert_eq!(preview.merged.accounts.len(), 2);
+    }
+
+    #[test]
+    fn keeps_reversed_order_shared_account_imports_distinct() {
+        let destination = storage(
+            vec![account(
+                Some("shared-account"),
+                Some("alice@example.com"),
+                "dest-alice",
+                10,
+                10,
+            )],
+            0,
+        );
+        let source = storage(
+            vec![
+                account(
+                    Some("shared-account"),
+                    Some("bob@example.com"),
+                    "source-bob",
+                    2,
+                    2,
+                ),
+                account(
+                    Some("shared-account"),
+                    Some("alice@example.com"),
+                    "source-alice-older",
+                    1,
+                    1,
+                ),
+            ],
+            1,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(
+            preview.to_add,
+            vec![ref_of(
+                Some("shared-account"),
+                Some("bob@example.com"),
+                "-bob"
+            )]
+        );
+        assert_eq!(preview.merged.accounts.len(), 2);
+        let tokens: Vec<&str> = preview
+            .merged
+            .accounts
+            .iter()
+            .map(|a| a.refresh_token.as_str())
+            .collect();
+        assert!(tokens.contains(&"dest-alice"));
+        assert!(tokens.contains(&"source-bob"));
+    }
+
+    #[test]
+    fn keeps_newer_destination_metadata_on_older_refresh_token_fallback() {
+        let destination = storage(
+            vec![{
+                let mut a = account(None, None, "shared-refresh-token", 10, 20);
+                a.account_label = Some("Destination winner".to_string());
+                a
+            }],
+            0,
+        );
+        let source = storage(
+            vec![{
+                let mut a = account(None, None, "shared-refresh-token", 5, 15);
+                a.account_label = Some("Older source".to_string());
+                a
+            }],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_add.len(), 0);
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(
+            preview.to_skip,
+            vec![OcChatgptSkipEntry {
+                source: ref_of(None, None, "oken"),
+                reason: "unchanged-or-older-than-destination".to_string(),
+            }]
+        );
+        assert_eq!(preview.unchanged_destination_only.len(), 0);
+        assert_eq!(preview.merged.accounts, destination.accounts);
+        assert_eq!(preview.merged.active_index, 0);
+    }
+
+    #[test]
+    fn refresh_token_fallback_skips_destination_rows_with_richer_identity() {
+        let destination = storage(
+            vec![{
+                let mut a = account(
+                    Some("acc-existing"),
+                    Some("existing@example.com"),
+                    "shared-refresh-token",
+                    1,
+                    2,
+                );
+                a.account_label = Some("Destination account".to_string());
+                a
+            }],
+            0,
+        );
+        let source = storage(
+            vec![{
+                let mut a = account(None, None, "shared-refresh-token", 3, 4);
+                a.account_label = Some("Source update".to_string());
+                a
+            }],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(preview.to_add.len(), 1);
+        assert_eq!(preview.to_add[0].refresh_token_last4, "oken");
+        assert_eq!(preview.merged.accounts.len(), 2);
+        assert!(preview.unchanged_destination_only.contains(&ref_of(
+            Some("acc-existing"),
+            Some("existing@example.com"),
+            "oken"
+        )));
+    }
+
+    #[test]
+    fn preserves_destination_metadata_on_timestamp_ties() {
+        let destination = storage(
+            vec![{
+                let mut a =
+                    account(Some("acc-tie"), Some("tie@example.com"), "dest-token", 10, 20);
+                a.account_label = Some("Destination label".to_string());
+                a
+            }],
+            0,
+        );
+        let source = storage(
+            vec![{
+                let mut a = account(
+                    Some("acc-tie"),
+                    Some("tie@example.com"),
+                    "source-token",
+                    10,
+                    20,
+                );
+                a.account_label = Some("Source label".to_string());
+                a
+            }],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_add.len(), 0);
+        assert_eq!(preview.to_update.len(), 0);
+        assert_eq!(preview.merged.accounts[0].refresh_token, "dest-token");
+        assert_eq!(
+            preview.merged.accounts[0].account_label.as_deref(),
+            Some("Destination label")
+        );
+    }
+
+    #[test]
+    fn records_exact_matched_by_counts_and_skip_reasons() {
+        let destination = storage(
+            vec![
+                account(Some("acc-1"), Some("match@example.com"), "token-old", 1, 1),
+                account(None, Some("dest-only@example.com"), "dest-only", 2, 2),
+            ],
+            0,
+        );
+        let source = storage(
+            vec![
+                account(Some("acc-1"), Some("match@example.com"), "token-new", 3, 5),
+                account(None, Some("new@example.com"), "token-add", 4, 4),
+                account(None, Some("bad@example.com"), "   ", 5, 5),
+            ],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert_eq!(preview.to_update.len(), 1);
+        assert_eq!(preview.to_update[0].matched_by, MatchStrategy::AccountId);
+        assert_eq!(preview.to_add.len(), 1);
+        assert_eq!(preview.to_skip.len(), 1);
+        assert_eq!(preview.to_skip[0].reason, "invalid-refresh-token");
+        assert_eq!(preview.unchanged_destination_only.len(), 1);
+        assert_eq!(preview.active_selection_behavior, "preserve-destination");
+    }
+
+    #[test]
+    fn surfaces_invalid_destination_accounts_in_to_skip() {
+        let destination = storage(
+            vec![account(None, Some("broken@example.com"), "   ", 1, 1)],
+            0,
+        );
+        let source = storage(vec![], 0);
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        assert!(preview.to_skip.contains(&OcChatgptSkipEntry {
+            source: ref_of(None, Some("broken@example.com"), ""),
+            reason: "destination-invalid-refresh-token".to_string(),
+        }));
+        assert_eq!(preview.merged.accounts.len(), 0);
+        assert_eq!(preview.unchanged_destination_only.len(), 0);
+    }
+
+    #[test]
+    fn matches_id_less_accounts_by_case_folded_email_but_not_plus_variants() {
+        let destination = storage(
+            vec![account(None, Some("user@example.com"), "dest-token", 1, 1)],
+            0,
+        );
+        let source = storage(
+            vec![
+                account(None, Some("USER@EXAMPLE.COM"), "token-case-fold", 2, 3),
+                account(None, Some("user+tag@example.com"), "token-plus", 4, 5),
+            ],
+            0,
+        );
+
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&destination));
+        let case_folded = preview
+            .to_update
+            .iter()
+            .find(|entry| entry.next.refresh_token_last4 == "fold")
+            .expect("case-folded email matched");
+        assert_eq!(case_folded.matched_by, MatchStrategy::Email);
+        assert!(preview.to_add.contains(&ref_of(
+            None,
+            Some("user+tag@example.com"),
+            "plus"
+        )));
+    }
+
+    #[test]
+    fn remaps_active_index_by_family_when_duplicates_collapse() {
+        let mut source = storage(
+            vec![
+                account(Some("acc-dup"), Some("first@example.com"), "token-old", 1, 1),
+                account(Some("acc-dup"), Some("first@example.com"), "token-new", 2, 2),
+                account(None, Some("second@example.com"), "token-second", 3, 3),
+            ],
+            2,
+        );
+        source.active_index_by_family = Some(ActiveIndexByFamily {
+            codex: Some(2),
+            gpt5_1: Some(1),
+            ..Default::default()
+        });
+
+        let payload = build_oc_chatgpt_import_payload(Some(&source));
+        let empty = storage(vec![], 0);
+        let preview = preview_oc_chatgpt_import_merge(Some(&source), Some(&empty));
+
+        assert_eq!(payload.accounts.len(), 2);
+        assert_eq!(payload.active_index, 1);
+        let families = payload.active_index_by_family.as_ref().expect("families");
+        assert_eq!(families.codex, Some(1));
+        assert_eq!(families.gpt5_1, Some(0));
+        let preview_families = preview
+            .payload
+            .active_index_by_family
+            .as_ref()
+            .expect("families");
+        assert_eq!(preview_families.codex, Some(1));
+        assert_eq!(preview_families.gpt5_1, Some(0));
+    }
+
+    #[test]
+    fn normalizes_whitespace_only_account_labels_to_none() {
+        let mut a = account(None, None, "token-label", 1, 1);
+        a.account_label = Some("   ".to_string());
+        let payload = build_oc_chatgpt_import_payload(Some(&storage(vec![a], 0)));
+        assert_eq!(payload.accounts[0].account_label, None);
+    }
+
+    #[test]
+    fn token_last4_masks_short_tokens_entirely() {
+        assert_eq!(token_last4("abcd"), "****");
+        assert_eq!(token_last4(" ab "), "**");
+        assert_eq!(token_last4(""), "");
+        assert_eq!(token_last4("refresh-token-1"), "en-1");
+    }
+}
diff --git a/crates/manager/src/oc_chatgpt/mod.rs b/crates/manager/src/oc_chatgpt/mod.rs
new file mode 100644
index 000000000..c5fb0eeb4
--- /dev/null
+++ b/crates/manager/src/oc_chatgpt/mod.rs
@@ -0,0 +1,4 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod import_adapter;
+pub mod orchestrator;
+pub mod target_detection;
diff --git a/crates/manager/src/oc_chatgpt/orchestrator.rs b/crates/manager/src/oc_chatgpt/orchestrator.rs
new file mode 100644
index 000000000..117f43a66
--- /dev/null
+++ b/crates/manager/src/oc_chatgpt/orchestrator.rs
@@ -0,0 +1,1028 @@
+//! Port of `lib/oc-chatgpt-orchestrator.ts` — plan/apply pipeline: detect
+//! target -> load -> preview merge -> atomic persist; named-backup export
+//! wrapper with EEXIST/collision mapping.
+//!
+//! Dependency injection is preserved as optional function references so the
+//! TS test doubles port 1:1. Rust has no exceptions: the TS `throw` paths are
+//! modeled as `Result::Err` from the injected closures, and the TS catch-all
+//! in `applyOcChatgptSync` (re-run detection to classify) is reproduced on
+//! the persist failure path.
+
+use std::path::Path;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::with_file_operation_retry;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::temp_path::temp_path_for;
+use cma_storage::normalize::normalize_account_storage;
+use cma_storage::public_types::AccountStorageV3;
+
+use super::import_adapter::{
+    OcChatgptMergePreview, OcChatgptPreviewPayload, preview_oc_chatgpt_import_merge,
+};
+use super::target_detection::{
+    DetectOcChatgptTargetOptions, OcChatgptTargetAmbiguous, OcChatgptTargetDescriptor,
+    OcChatgptTargetDetectionResult, OcChatgptTargetNone, detect_oc_chatgpt_multi_auth_target,
+};
+
+/// Boxed error payload (TS `error: unknown`).
+pub type OcSyncError = Box<dyn std::error::Error + Send + Sync>;
+
+/// TS `cause: "load" | "preview"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OcChatgptPlanErrorCause {
+    Load,
+    Preview,
+}
+
+impl OcChatgptPlanErrorCause {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            OcChatgptPlanErrorCause::Load => "load",
+            OcChatgptPlanErrorCause::Preview => "preview",
+        }
+    }
+}
+
+/// TS `OcChatgptSyncPlanResult`.
+// The variant sizes intentionally mirror the TS result-object shapes; the
+// enum lives briefly on one settings-menu code path, so boxing buys nothing.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug)]
+pub enum OcChatgptSyncPlanResult {
+    Ready {
+        target: OcChatgptTargetDescriptor,
+        preview: OcChatgptMergePreview,
+        payload: OcChatgptPreviewPayload,
+        destination: Option<AccountStorageV3>,
+    },
+    BlockedAmbiguous {
+        detection: OcChatgptTargetAmbiguous,
+    },
+    BlockedNone {
+        detection: OcChatgptTargetNone,
+    },
+    /// chatgpt-import-06: a structured error result so planning can report a
+    /// failure to load/preview the target (e.g. a corrupt destination file)
+    /// instead of throwing out of the planning step.
+    PlanError {
+        target: OcChatgptTargetDescriptor,
+        error: OcSyncError,
+        cause: OcChatgptPlanErrorCause,
+    },
+}
+
+/// TS `OcChatgptSyncApplyResult`.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug)]
+pub enum OcChatgptSyncApplyResult {
+    BlockedAmbiguous {
+        detection: OcChatgptTargetAmbiguous,
+    },
+    BlockedNone {
+        detection: OcChatgptTargetNone,
+    },
+    Applied {
+        target: OcChatgptTargetDescriptor,
+        preview: OcChatgptMergePreview,
+        merged: AccountStorageV3,
+        destination: Option<AccountStorageV3>,
+        /// TS `persistedPath?: string | void`.
+        persisted_path: Option<String>,
+    },
+    Error {
+        target: OcChatgptTargetDescriptor,
+        error: OcSyncError,
+    },
+}
+
+type DetectFn<'a> =
+    &'a (dyn Fn(&DetectOcChatgptTargetOptions) -> OcChatgptTargetDetectionResult + Sync);
+type PreviewFn<'a> = &'a (dyn Fn(
+    Option<&AccountStorageV3>,
+    Option<&AccountStorageV3>,
+) -> Result<OcChatgptMergePreview, OcSyncError>
+             + Sync);
+type LoadFn<'a> = &'a (dyn Fn(
+    &OcChatgptTargetDescriptor,
+) -> Result<Option<AccountStorageV3>, OcSyncError>
+             + Sync);
+type PersistFn<'a> = &'a (dyn Fn(
+    &OcChatgptTargetDescriptor,
+    &AccountStorageV3,
+) -> Result<Option<String>, OcSyncError>
+             + Sync);
+
+/// TS `PlanDependencies` (test seams; `None` = the real implementation).
+#[derive(Default)]
+pub struct PlanOcChatgptSyncDependencies<'a> {
+    pub detect_target: Option<DetectFn<'a>>,
+    pub preview_merge: Option<PreviewFn<'a>>,
+    pub load_target_storage: Option<LoadFn<'a>>,
+}
+
+/// TS `ApplyDependencies` — plan deps + `persistMerged`.
+#[derive(Default)]
+pub struct ApplyOcChatgptSyncDependencies<'a> {
+    pub detect_target: Option<DetectFn<'a>>,
+    pub preview_merge: Option<PreviewFn<'a>>,
+    pub load_target_storage: Option<LoadFn<'a>>,
+    pub persist_merged: Option<PersistFn<'a>>,
+}
+
+/// TS `PlanOcChatgptSyncOptions`.
+#[derive(Default)]
+pub struct PlanOcChatgptSyncOptions<'a> {
+    pub source: Option<&'a AccountStorageV3>,
+    /// Tri-state (spec 12 gotcha 21): `None` = property absent → read the
+    /// target from disk; `Some(None)` = `destination: null` (empty, do NOT
+    /// touch disk); `Some(Some(storage))` = provided.
+    pub destination: Option<Option<&'a AccountStorageV3>>,
+    pub detect_options: DetectOcChatgptTargetOptions,
+    pub dependencies: PlanOcChatgptSyncDependencies<'a>,
+}
+
+/// TS `ApplyOcChatgptSyncOptions`.
+#[derive(Default)]
+pub struct ApplyOcChatgptSyncOptions<'a> {
+    pub source: Option<&'a AccountStorageV3>,
+    pub destination: Option<Option<&'a AccountStorageV3>>,
+    pub detect_options: DetectOcChatgptTargetOptions,
+    pub dependencies: ApplyOcChatgptSyncDependencies<'a>,
+}
+
+enum Detected {
+    Blocked(BlockedDetection),
+    Target(OcChatgptTargetDescriptor),
+}
+
+enum BlockedDetection {
+    Ambiguous(OcChatgptTargetAmbiguous),
+    None(OcChatgptTargetNone),
+}
+
+/// TS `mapDetectionToBlocked` folded into a total match — the "Unexpected oc
+/// target detection result" invariant throw guards states that are
+/// unrepresentable with this enum.
+fn classify_detection(detection: OcChatgptTargetDetectionResult) -> Detected {
+    match detection {
+        OcChatgptTargetDetectionResult::Ambiguous(ambiguous) => {
+            Detected::Blocked(BlockedDetection::Ambiguous(ambiguous))
+        }
+        OcChatgptTargetDetectionResult::NoTarget(none) => {
+            Detected::Blocked(BlockedDetection::None(none))
+        }
+        OcChatgptTargetDetectionResult::Target { descriptor } => Detected::Target(descriptor),
+    }
+}
+
+/// TS `loadTargetStorageDefault(target)` — read + parse + normalize;
+/// `ENOENT` ⇒ `Ok(None)`; any other error propagates (⇒ plan-error "load").
+fn load_target_storage_default(
+    target: &OcChatgptTargetDescriptor,
+) -> Result<Option<AccountStorageV3>, OcSyncError> {
+    let raw = match std::fs::read_to_string(&target.account_path) {
+        Ok(raw) => raw,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => return Err(Box::new(error)),
+    };
+    let value: serde_json::Value = serde_json::from_str(&raw).map_err(OcSyncError::from)?;
+    Ok(normalize_account_storage(&value))
+}
+
+/// TS `planOcChatgptSync(options)`.
+pub async fn plan_oc_chatgpt_sync(
+    options: PlanOcChatgptSyncOptions<'_>,
+) -> OcChatgptSyncPlanResult {
+    let detection = match options.dependencies.detect_target {
+        Some(detect) => detect(&options.detect_options),
+        None => detect_oc_chatgpt_multi_auth_target(&options.detect_options),
+    };
+    let descriptor = match classify_detection(detection) {
+        Detected::Blocked(BlockedDetection::Ambiguous(detection)) => {
+            return OcChatgptSyncPlanResult::BlockedAmbiguous { detection };
+        }
+        Detected::Blocked(BlockedDetection::None(detection)) => {
+            return OcChatgptSyncPlanResult::BlockedNone { detection };
+        }
+        Detected::Target(descriptor) => descriptor,
+    };
+
+    let destination: Option<AccountStorageV3> = match options.destination {
+        Some(provided) => provided.cloned(),
+        None => {
+            let loaded = match options.dependencies.load_target_storage {
+                Some(load) => load(&descriptor),
+                None => load_target_storage_default(&descriptor),
+            };
+            match loaded {
+                Ok(destination) => destination,
+                Err(error) => {
+                    // chatgpt-import-06: a corrupt/unreadable destination must
+                    // not throw out of planning; return a structured error.
+                    return OcChatgptSyncPlanResult::PlanError {
+                        target: descriptor,
+                        error,
+                        cause: OcChatgptPlanErrorCause::Load,
+                    };
+                }
+            }
+        }
+    };
+
+    let preview = match options.dependencies.preview_merge {
+        Some(preview_merge) => preview_merge(options.source, destination.as_ref()),
+        None => Ok(preview_oc_chatgpt_import_merge(
+            options.source,
+            destination.as_ref(),
+        )),
+    };
+    let preview = match preview {
+        Ok(preview) => preview,
+        Err(error) => {
+            return OcChatgptSyncPlanResult::PlanError {
+                target: descriptor,
+                error,
+                cause: OcChatgptPlanErrorCause::Preview,
+            };
+        }
+    };
+
+    OcChatgptSyncPlanResult::Ready {
+        target: descriptor,
+        payload: preview.payload.clone(),
+        preview,
+        destination,
+    }
+}
+
+/// TS `persistMergedDefault(target, merged)` — CRITICAL byte-compat write
+/// path: 0700 parent dir, temp file at 0600, `JSON.stringify(_, null, 2)` +
+/// trailing `\n`, rename routed through `withFileOperationRetry`, retried
+/// force-rm temp cleanup (secrets must not linger).
+async fn persist_merged_default(
+    target: &OcChatgptTargetDescriptor,
+    merged: &AccountStorageV3,
+) -> Result<Option<String>, OcSyncError> {
+    let path = Path::new(&target.account_path);
+    if let Some(dir) = path.parent() {
+        create_dir_0700(dir)?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            // mkdir's mode is ignored on an already-existing dir; re-assert
+            // 0700 so a pre-existing loose-perm dir is tightened (POSIX only;
+            // win32 relies on the user-profile ACL). Errors swallowed.
+            let _ = std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700));
+        }
+    }
+    let temp_path = temp_path_for(path);
+    let content = format!("{}\n", stringify_pretty2(merged));
+
+    let result = write_and_rename(&temp_path, path, &content).await;
+
+    // finally: retried best-effort temp cleanup. force:true semantics — a
+    // missing temp (rename consumed it) is a no-op.
+    let cleanup_temp = temp_path.clone();
+    let _ = with_file_operation_retry(move || {
+        let temp = cleanup_temp.clone();
+        async move {
+            match std::fs::remove_file(&temp) {
+                Ok(()) => Ok(()),
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+                Err(error) => Err(error),
+            }
+        }
+    })
+    .await;
+
+    result?;
+    Ok(Some(target.account_path.clone()))
+}
+
+fn create_dir_0700(dir: &Path) -> Result<(), OcSyncError> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        let mut builder = std::fs::DirBuilder::new();
+        builder.recursive(true);
+        builder.mode(0o700);
+        builder.create(dir).map_err(OcSyncError::from)
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::create_dir_all(dir).map_err(OcSyncError::from)
+    }
+}
+
+async fn write_and_rename(
+    temp_path: &Path,
+    path: &Path,
+    content: &str,
+) -> Result<(), OcSyncError> {
+    write_temp_0600(temp_path, content)?;
+    // Route the atomic rename through withFileOperationRetry: on Windows the
+    // destination is a live, watched store, so a concurrent reader can hold
+    // it briefly and surface EBUSY/EPERM/ENOTEMPTY/EACCES.
+    let temp = temp_path.to_path_buf();
+    let dest = path.to_path_buf();
+    with_file_operation_retry(move || {
+        let temp = temp.clone();
+        let dest = dest.clone();
+        async move { std::fs::rename(&temp, &dest) }
+    })
+    .await
+    .map_err(OcSyncError::from)
+}
+
+fn write_temp_0600(temp_path: &Path, content: &str) -> Result<(), OcSyncError> {
+    #[cfg(unix)]
+    {
+        use std::io::Write;
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut file = std::fs::OpenOptions::new()
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .mode(0o600)
+            .open(temp_path)
+            .map_err(OcSyncError::from)?;
+        file.write_all(content.as_bytes()).map_err(OcSyncError::from)?;
+        // Re-assert 0600 (mirrors the TS explicit chmod; errors swallowed).
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(temp_path, std::fs::Permissions::from_mode(0o600));
+        Ok(())
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::write(temp_path, content).map_err(OcSyncError::from)
+    }
+}
+
+/// TS `applyOcChatgptSync(options)`.
+pub async fn apply_oc_chatgpt_sync(
+    options: ApplyOcChatgptSyncOptions<'_>,
+) -> OcChatgptSyncApplyResult {
+    let plan = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+        source: options.source,
+        destination: options.destination,
+        detect_options: options.detect_options.clone(),
+        dependencies: PlanOcChatgptSyncDependencies {
+            detect_target: options.dependencies.detect_target,
+            preview_merge: options.dependencies.preview_merge,
+            load_target_storage: options.dependencies.load_target_storage,
+        },
+    })
+    .await;
+
+    let (target, preview, destination) = match plan {
+        OcChatgptSyncPlanResult::PlanError { target, error, .. } => {
+            // Map the structured planning error onto the apply error variant.
+            return OcChatgptSyncApplyResult::Error { target, error };
+        }
+        OcChatgptSyncPlanResult::BlockedAmbiguous { detection } => {
+            return OcChatgptSyncApplyResult::BlockedAmbiguous { detection };
+        }
+        OcChatgptSyncPlanResult::BlockedNone { detection } => {
+            return OcChatgptSyncApplyResult::BlockedNone { detection };
+        }
+        OcChatgptSyncPlanResult::Ready {
+            target,
+            preview,
+            destination,
+            ..
+        } => (target, preview, destination),
+    };
+
+    let persisted = match options.dependencies.persist_merged {
+        Some(persist) => persist(&target, &preview.merged),
+        None => persist_merged_default(&target, &preview.merged).await,
+    };
+
+    match persisted {
+        Ok(persisted_path) => OcChatgptSyncApplyResult::Applied {
+            target,
+            merged: preview.merged.clone(),
+            preview,
+            destination,
+            persisted_path,
+        },
+        Err(error) => {
+            // TS catch-all: on ANY throw re-run detection to classify. A
+            // now-blocked detection wins; otherwise the FRESH descriptor is
+            // reported with the error.
+            let detection = match options.dependencies.detect_target {
+                Some(detect) => detect(&options.detect_options),
+                None => detect_oc_chatgpt_multi_auth_target(&options.detect_options),
+            };
+            match classify_detection(detection) {
+                Detected::Blocked(BlockedDetection::Ambiguous(detection)) => {
+                    OcChatgptSyncApplyResult::BlockedAmbiguous { detection }
+                }
+                Detected::Blocked(BlockedDetection::None(detection)) => {
+                    OcChatgptSyncApplyResult::BlockedNone { detection }
+                }
+                Detected::Target(descriptor) => OcChatgptSyncApplyResult::Error {
+                    target: descriptor,
+                    error,
+                },
+            }
+        }
+    }
+}
+
+type ExportBackupFn<'a> = &'a (dyn Fn(&str, bool) -> Result<String, CodexError> + Sync);
+
+/// TS `RunNamedBackupExportOptions`.
+#[derive(Default)]
+pub struct RunNamedBackupExportOptions<'a> {
+    pub name: String,
+    pub force: bool,
+    /// Test seam (TS `dependencies.exportBackup`).
+    pub export_backup: Option<ExportBackupFn<'a>>,
+}
+
+/// TS `RunNamedBackupExportResult`.
+#[derive(Debug)]
+pub enum RunNamedBackupExportResult {
+    Exported { path: String },
+    Collision { path: String },
+    Error { path: Option<String>, error: CodexError },
+}
+
+/// TS `extractCollisionPath(error)` — the Rust `CodexError` carries no errno
+/// `code`/`path` fields, so classification relies on the message contract
+/// `/already exists: (?<path>.+)$/i` (named-backup export throws
+/// `` `File already exists: ${destination}` ``, which this matches).
+fn extract_collision_path(error: &CodexError) -> Option<String> {
+    let message = error.message().trim();
+    if message.is_empty() {
+        return None;
+    }
+    // `$` without the `m` flag also matches just before a single final \n.
+    let message = message.strip_suffix('\n').unwrap_or(message);
+    // `.+` cannot cross a newline: the match must live on the final line.
+    let final_line = message.rsplit('\n').next().unwrap_or(message);
+    let lower = final_line.to_lowercase();
+    let marker = "already exists: ";
+    let idx = lower.find(marker)?;
+    let path = final_line[idx + marker.len()..].trim();
+    if path.is_empty() {
+        return None;
+    }
+    Some(path.to_string())
+}
+
+/// TS `runNamedBackupExport(options)`.
+pub async fn run_named_backup_export(
+    options: RunNamedBackupExportOptions<'_>,
+) -> RunNamedBackupExportResult {
+    let result = match options.export_backup {
+        Some(export_backup) => export_backup(&options.name, options.force),
+        None => cma_storage::named_backups::export_named_backup(&options.name, options.force)
+            .await,
+    };
+    match result {
+        Ok(path) => RunNamedBackupExportResult::Exported { path },
+        Err(error) => match extract_collision_path(&error) {
+            Some(path) => RunNamedBackupExportResult::Collision { path },
+            None => RunNamedBackupExportResult::Error { path: None, error },
+        },
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::result_large_err)] // test doubles return CodexError by value
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_testkit::remove_with_retry::remove_recursive_with_retry;
+
+    // Ported from test/oc-chatgpt-orchestrator.test.ts.
+
+    fn source_storage() -> AccountStorageV3 {
+        let mut account = AccountMetadataV3::new("refresh-token-1", 50, 100);
+        account.email = Some("user@example.com".to_string());
+        account.account_id = Some("acc_1".to_string());
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![account];
+        storage
+    }
+
+    fn destination_storage() -> AccountStorageV3 {
+        let mut account = AccountMetadataV3::new("refresh-token-dest", 5, 10);
+        account.email = Some("dest@example.com".to_string());
+        account.account_id = Some("acc_dest".to_string());
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![account];
+        storage
+    }
+
+    fn target_descriptor(root: &str) -> OcChatgptTargetDescriptor {
+        use super::super::target_detection::{
+            OcChatgptTargetResolution, OcChatgptTargetScope, OcChatgptTargetSource,
+        };
+        OcChatgptTargetDescriptor {
+            scope: OcChatgptTargetScope::Global,
+            root: root.to_string(),
+            account_path: Path::new(root)
+                .join("openai-codex-accounts.json")
+                .to_string_lossy()
+                .into_owned(),
+            backup_root: Path::new(root).join("backups").to_string_lossy().into_owned(),
+            source: OcChatgptTargetSource::DefaultGlobal,
+            resolution: OcChatgptTargetResolution::Accounts,
+        }
+    }
+
+    fn detect_target_fixture(
+        root: String,
+    ) -> impl Fn(&DetectOcChatgptTargetOptions) -> OcChatgptTargetDetectionResult + Sync {
+        move |_| OcChatgptTargetDetectionResult::Target {
+            descriptor: target_descriptor(&root),
+        }
+    }
+
+    fn none_detection() -> OcChatgptTargetNone {
+        OcChatgptTargetNone {
+            reason: "missing".to_string(),
+            tried: vec![],
+        }
+    }
+
+    fn ambiguous_detection() -> OcChatgptTargetAmbiguous {
+        OcChatgptTargetAmbiguous {
+            reason: "multiple".to_string(),
+            candidates: vec![],
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_blocked_none_when_target_is_missing() {
+        let source = source_storage();
+        let detect = |_: &DetectOcChatgptTargetOptions| {
+            OcChatgptTargetDetectionResult::NoTarget(none_detection())
+        };
+        let preview_called = std::sync::atomic::AtomicBool::new(false);
+        let preview = |_: Option<&AccountStorageV3>, _: Option<&AccountStorageV3>| {
+            preview_called.store(true, std::sync::atomic::Ordering::SeqCst);
+            Ok(preview_oc_chatgpt_import_merge(None, None))
+        };
+        let result = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+            source: Some(&source),
+            dependencies: PlanOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                preview_merge: Some(&preview),
+                load_target_storage: None,
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncPlanResult::BlockedNone { detection } => {
+                assert_eq!(detection.reason, "missing");
+            }
+            other => panic!("expected blocked-none, got {other:?}"),
+        }
+        assert!(!preview_called.load(std::sync::atomic::Ordering::SeqCst));
+    }
+
+    #[tokio::test]
+    async fn returns_blocked_ambiguous_when_target_is_ambiguous() {
+        let source = source_storage();
+        let detect = |_: &DetectOcChatgptTargetOptions| {
+            OcChatgptTargetDetectionResult::Ambiguous(ambiguous_detection())
+        };
+        let result = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+            source: Some(&source),
+            dependencies: PlanOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                preview_merge: None,
+                load_target_storage: None,
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncPlanResult::BlockedAmbiguous { detection } => {
+                assert_eq!(detection.reason, "multiple");
+            }
+            other => panic!("expected blocked-ambiguous, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_ready_preview_when_target_is_found() {
+        let source = source_storage();
+        let destination = destination_storage();
+        let detect = detect_target_fixture("C:/target".to_string());
+        let result = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: PlanOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                preview_merge: None,
+                load_target_storage: None,
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncPlanResult::Ready {
+                target,
+                preview,
+                payload,
+                destination: dest,
+            } => {
+                assert_eq!(preview.to_add.len(), 1);
+                assert_eq!(preview.to_update.len(), 0);
+                assert_eq!(preview.to_skip.len(), 0);
+                assert_eq!(preview.unchanged_destination_only.len(), 1);
+                assert_eq!(preview.active_selection_behavior, "preserve-destination");
+                assert_eq!(preview.merged.accounts.len(), 2);
+                assert_eq!(preview.merged.active_index, destination.active_index);
+                assert_eq!(payload, preview.payload);
+                assert_eq!(dest.as_ref(), Some(&destination));
+                assert!(target.account_path.contains("openai-codex-accounts.json"));
+            }
+            other => panic!("expected ready, got {other:?}"),
+        }
+    }
+
+    // chatgpt-import-06: planning must return a structured error (not
+    // panic/throw) when loading the target fails.
+    #[tokio::test]
+    async fn returns_plan_error_when_loading_the_target_fails() {
+        let source = source_storage();
+        let detect = detect_target_fixture("C:/target".to_string());
+        let load = |_: &OcChatgptTargetDescriptor| -> Result<Option<AccountStorageV3>, OcSyncError> {
+            Err("corrupt destination file".into())
+        };
+        let result = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+            source: Some(&source),
+            // destination omitted -> loadTargetStorage is invoked
+            destination: None,
+            dependencies: PlanOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                preview_merge: None,
+                load_target_storage: Some(&load),
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncPlanResult::PlanError { target, error, cause } => {
+                assert_eq!(cause, OcChatgptPlanErrorCause::Load);
+                assert!(error.to_string().contains("corrupt destination"));
+                assert!(target.account_path.contains("openai-codex-accounts.json"));
+            }
+            other => panic!("expected plan-error, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_plan_error_when_previewing_the_merge_fails() {
+        let source = source_storage();
+        let destination = destination_storage();
+        let detect = detect_target_fixture("C:/target".to_string());
+        let preview = |_: Option<&AccountStorageV3>,
+                       _: Option<&AccountStorageV3>|
+         -> Result<OcChatgptMergePreview, OcSyncError> { Err("preview boom".into()) };
+        let result = plan_oc_chatgpt_sync(PlanOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: PlanOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                preview_merge: Some(&preview),
+                load_target_storage: None,
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncPlanResult::PlanError { cause, .. } => {
+                assert_eq!(cause, OcChatgptPlanErrorCause::Preview);
+            }
+            other => panic!("expected plan-error, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_applied_when_persist_succeeds() {
+        let source = source_storage();
+        let destination = destination_storage();
+        let detect = detect_target_fixture("C:/target".to_string());
+        let persist_calls = std::sync::Mutex::new(Vec::<(String, usize)>::new());
+        let persist = |target: &OcChatgptTargetDescriptor,
+                       merged: &AccountStorageV3|
+         -> Result<Option<String>, OcSyncError> {
+            persist_calls
+                .lock()
+                .unwrap()
+                .push((target.account_path.clone(), merged.accounts.len()));
+            Ok(Some("C:/target/openai-codex-accounts.json".to_string()))
+        };
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                persist_merged: Some(&persist),
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+
+        let calls = persist_calls.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        assert!(calls[0].0.contains("openai-codex-accounts.json"));
+        assert_eq!(calls[0].1, 2);
+        match result {
+            OcChatgptSyncApplyResult::Applied {
+                persisted_path,
+                preview,
+                merged,
+                ..
+            } => {
+                assert_eq!(
+                    persisted_path.as_deref(),
+                    Some("C:/target/openai-codex-accounts.json")
+                );
+                assert_eq!(preview.to_add.len(), 1);
+                assert_eq!(preview.unchanged_destination_only.len(), 1);
+                assert!(merged.accounts.iter().any(|a| a.account_id.as_deref() == Some("acc_dest")));
+                assert!(merged.accounts.iter().any(|a| a.account_id.as_deref() == Some("acc_1")));
+            }
+            other => panic!("expected applied, got {other:?}"),
+        }
+    }
+
+    // Regression (chatgpt-import-01/02): the default persister writes the
+    // merged secret-bearing account file atomically; no temp file leaks.
+    #[tokio::test]
+    async fn default_persister_writes_the_merged_file_atomically() {
+        let dir = std::env::temp_dir().join(format!(
+            "codex-oc-persist-{}",
+            uuid::Uuid::new_v4().simple()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let account_path = dir.join("openai-codex-accounts.json");
+        let source = source_storage();
+        let destination = destination_storage();
+        let root = dir.to_string_lossy().into_owned();
+        let detect = detect_target_fixture(root);
+
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                // no persist_merged -> real persist_merged_default runs
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+
+        match &result {
+            OcChatgptSyncApplyResult::Applied { persisted_path, .. } => {
+                assert_eq!(
+                    persisted_path.as_deref(),
+                    Some(account_path.to_string_lossy().as_ref())
+                );
+            }
+            other => panic!("expected applied, got {other:?}"),
+        }
+
+        // File landed (atomic rename completed), parses, ends with "\n", and
+        // no temp file leaked behind.
+        let written = std::fs::read_to_string(&account_path).unwrap();
+        assert!(written.ends_with('\n'));
+        assert!(!written.ends_with("\n\n"));
+        let parsed: serde_json::Value = serde_json::from_str(&written).unwrap();
+        assert_eq!(parsed["version"], 3);
+        assert!(parsed["accounts"].as_array().unwrap().len() >= 2);
+        let leftovers: Vec<String> = std::fs::read_dir(&dir)
+            .unwrap()
+            .flatten()
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|name| name.ends_with(".tmp"))
+            .collect();
+        assert!(leftovers.is_empty(), "leaked temp files: {leftovers:?}");
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let mode = std::fs::metadata(&account_path).unwrap().permissions().mode() & 0o777;
+            assert_eq!(mode, 0o600);
+        }
+
+        remove_recursive_with_retry(&dir).unwrap();
+    }
+
+    #[tokio::test]
+    async fn returns_structured_error_when_persist_fails() {
+        let source = source_storage();
+        let destination = destination_storage();
+        let detect = detect_target_fixture("C:/locked".to_string());
+        let persist = |_: &OcChatgptTargetDescriptor,
+                       _: &AccountStorageV3|
+         -> Result<Option<String>, OcSyncError> {
+            Err("EACCES: permission denied, open C:/locked/openai-codex-accounts.json".into())
+        };
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                persist_merged: Some(&persist),
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncApplyResult::Error { target, error } => {
+                assert!(error.to_string().contains("EACCES"));
+                assert!(target.account_path.contains("openai-codex-accounts.json"));
+                assert!(target.root.contains("locked"));
+            }
+            other => panic!("expected error, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn persist_failure_with_now_blocked_detection_returns_blocked() {
+        // The TS catch-all re-runs detection; a now-blocked detection wins.
+        let source = source_storage();
+        let destination = destination_storage();
+        let call_count = std::sync::atomic::AtomicUsize::new(0);
+        let detect = |_: &DetectOcChatgptTargetOptions| {
+            let n = call_count.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            if n == 0 {
+                OcChatgptTargetDetectionResult::Target {
+                    descriptor: target_descriptor("C:/target"),
+                }
+            } else {
+                OcChatgptTargetDetectionResult::NoTarget(none_detection())
+            }
+        };
+        let persist = |_: &OcChatgptTargetDescriptor,
+                       _: &AccountStorageV3|
+         -> Result<Option<String>, OcSyncError> { Err("boom".into()) };
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: Some(Some(&destination)),
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                persist_merged: Some(&persist),
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+        assert!(matches!(
+            result,
+            OcChatgptSyncApplyResult::BlockedNone { .. }
+        ));
+    }
+
+    #[tokio::test]
+    async fn passes_injected_load_target_storage_through_apply_planning() {
+        let source = source_storage();
+        let loaded_destination = destination_storage();
+        let load_calls = std::sync::atomic::AtomicUsize::new(0);
+        let load = |_: &OcChatgptTargetDescriptor| -> Result<Option<AccountStorageV3>, OcSyncError> {
+            load_calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            Ok(Some(loaded_destination.clone()))
+        };
+        let detect = detect_target_fixture("C:/target".to_string());
+        let persist = |_: &OcChatgptTargetDescriptor,
+                       _: &AccountStorageV3|
+         -> Result<Option<String>, OcSyncError> {
+            Ok(Some("C:/target/openai-codex-accounts.json".to_string()))
+        };
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: None,
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                load_target_storage: Some(&load),
+                persist_merged: Some(&persist),
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+        assert_eq!(load_calls.load(std::sync::atomic::Ordering::SeqCst), 1);
+        assert!(matches!(result, OcChatgptSyncApplyResult::Applied { .. }));
+    }
+
+    #[tokio::test]
+    async fn returns_structured_error_when_load_target_storage_fails_during_apply() {
+        let source = source_storage();
+        let detect = detect_target_fixture("C:/target".to_string());
+        let load = |_: &OcChatgptTargetDescriptor| -> Result<Option<AccountStorageV3>, OcSyncError> {
+            Err("EACCES: permission denied".into())
+        };
+        let result = apply_oc_chatgpt_sync(ApplyOcChatgptSyncOptions {
+            source: Some(&source),
+            destination: None,
+            dependencies: ApplyOcChatgptSyncDependencies {
+                detect_target: Some(&detect),
+                load_target_storage: Some(&load),
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .await;
+        match result {
+            OcChatgptSyncApplyResult::Error { target, error } => {
+                assert!(error.to_string().contains("EACCES"));
+                assert_eq!(
+                    target.account_path,
+                    Path::new("C:/target")
+                        .join("openai-codex-accounts.json")
+                        .to_string_lossy()
+                );
+            }
+            other => panic!("expected error, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_collision_when_named_backup_export_collides() {
+        let export = |_: &str, _: bool| -> Result<String, CodexError> {
+            Err(CodexError::new(
+                "named backup already exists: C:/target/backups/backup-2026-03-10.json",
+            ))
+        };
+        let result = run_named_backup_export(RunNamedBackupExportOptions {
+            name: "backup-2026-03-10".to_string(),
+            force: false,
+            export_backup: Some(&export),
+        })
+        .await;
+        match result {
+            RunNamedBackupExportResult::Collision { path } => {
+                assert!(path.contains("backup-2026-03-10.json"));
+            }
+            other => panic!("expected collision, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn extracts_collision_paths_from_message_only_backup_errors() {
+        let export = |_: &str, _: bool| -> Result<String, CodexError> {
+            Err(CodexError::new(
+                "named backup already exists: C:/target/backups/backup-2026-03-11.json",
+            ))
+        };
+        let result = run_named_backup_export(RunNamedBackupExportOptions {
+            name: "backup-2026-03-11".to_string(),
+            force: false,
+            export_backup: Some(&export),
+        })
+        .await;
+        match result {
+            RunNamedBackupExportResult::Collision { path } => {
+                assert_eq!(path, "C:/target/backups/backup-2026-03-11.json");
+            }
+            other => panic!("expected collision, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_error_for_non_collision_backup_failures() {
+        let export = |_: &str, _: bool| -> Result<String, CodexError> {
+            Err(CodexError::new(
+                "EACCES: permission denied, mkdir C:/target/backups",
+            ))
+        };
+        let result = run_named_backup_export(RunNamedBackupExportOptions {
+            name: "backup-2026-03-12".to_string(),
+            force: false,
+            export_backup: Some(&export),
+        })
+        .await;
+        match result {
+            RunNamedBackupExportResult::Error { path, error } => {
+                assert_eq!(path, None);
+                assert!(error.message().contains("EACCES"));
+            }
+            other => panic!("expected error, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn extract_collision_path_matches_the_frozen_export_message() {
+        let error = CodexError::new("File already exists: /root/backups/name.json");
+        assert_eq!(
+            extract_collision_path(&error).as_deref(),
+            Some("/root/backups/name.json")
+        );
+        let no_match = CodexError::new("something else went wrong");
+        assert_eq!(extract_collision_path(&no_match), None);
+    }
+}
diff --git a/crates/manager/src/oc_chatgpt/target_detection.rs b/crates/manager/src/oc_chatgpt/target_detection.rs
new file mode 100644
index 000000000..09214c2c2
--- /dev/null
+++ b/crates/manager/src/oc_chatgpt/target_detection.rs
@@ -0,0 +1,940 @@
+//! Port of `lib/oc-chatgpt-target-detection.ts` — filesystem probing to
+//! locate the oc-chatgpt-multi-auth storage root.
+//!
+//! Tri-state `explicitRoot` (spec 12 gotcha 18): the TS code distinguishes
+//! "property absent" (env override active) from "property present but
+//! null/undefined" (env override DISABLED) via the `in` operator; the Rust
+//! port models this as `Option<Option<String>>`.
+
+use std::collections::HashSet;
+use std::path::{Component, Path, PathBuf};
+
+use cma_storage::paths::{
+    find_project_root, get_project_storage_key, resolve_project_storage_identity_root,
+};
+
+const ACCOUNT_FILE_NAME: &str = "openai-codex-accounts.json";
+const BACKUPS_DIR_NAME: &str = "backups";
+const PROJECTS_DIR_NAME: &str = "projects";
+const CANONICAL_HOME_BASENAME: &str = ".opencode";
+
+/// TS `OcChatgptTargetScope = "global" | "project"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OcChatgptTargetScope {
+    Global,
+    Project,
+}
+
+impl OcChatgptTargetScope {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            OcChatgptTargetScope::Global => "global",
+            OcChatgptTargetScope::Project => "project",
+        }
+    }
+}
+
+/// TS `OcChatgptTargetSource = "explicit" | "default-global" | "project"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OcChatgptTargetSource {
+    Explicit,
+    DefaultGlobal,
+    Project,
+}
+
+impl OcChatgptTargetSource {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            OcChatgptTargetSource::Explicit => "explicit",
+            OcChatgptTargetSource::DefaultGlobal => "default-global",
+            OcChatgptTargetSource::Project => "project",
+        }
+    }
+}
+
+/// TS `resolution: "accounts" | "signals"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OcChatgptTargetResolution {
+    Accounts,
+    Signals,
+}
+
+impl OcChatgptTargetResolution {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            OcChatgptTargetResolution::Accounts => "accounts",
+            OcChatgptTargetResolution::Signals => "signals",
+        }
+    }
+}
+
+/// TS `OcChatgptTargetDescriptor`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcChatgptTargetDescriptor {
+    pub scope: OcChatgptTargetScope,
+    pub root: String,
+    pub account_path: String,
+    pub backup_root: String,
+    pub source: OcChatgptTargetSource,
+    pub resolution: OcChatgptTargetResolution,
+}
+
+/// One `candidates` entry of the ambiguous result.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcChatgptTargetCandidateInfo {
+    pub scope: OcChatgptTargetScope,
+    pub root: String,
+    pub account_path: String,
+    pub backup_root: String,
+    pub source: OcChatgptTargetSource,
+    pub has_account_artifacts: bool,
+    pub has_signals: bool,
+}
+
+/// One `tried` entry of the none result.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcChatgptTargetTried {
+    pub scope: OcChatgptTargetScope,
+    pub source: OcChatgptTargetSource,
+    pub root: String,
+    pub account_path: String,
+    pub backup_root: String,
+}
+
+/// TS `OcChatgptTargetAmbiguous` (sans the literal `kind`).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcChatgptTargetAmbiguous {
+    pub reason: String,
+    pub candidates: Vec<OcChatgptTargetCandidateInfo>,
+}
+
+/// TS `OcChatgptTargetNone` (sans the literal `kind`).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcChatgptTargetNone {
+    pub reason: String,
+    pub tried: Vec<OcChatgptTargetTried>,
+}
+
+/// TS `OcChatgptTargetDetectionResult` (tags: `"target"`, `"ambiguous"`,
+/// `"none"`).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum OcChatgptTargetDetectionResult {
+    Target { descriptor: OcChatgptTargetDescriptor },
+    Ambiguous(OcChatgptTargetAmbiguous),
+    NoTarget(OcChatgptTargetNone),
+}
+
+/// Options for [`detect_oc_chatgpt_multi_auth_target`].
+#[derive(Clone, Debug, Default)]
+pub struct DetectOcChatgptTargetOptions {
+    /// Tri-state (TS `"explicitRoot" in options`):
+    /// - `None` — property absent: env `OC_CHATGPT_MULTI_AUTH_DIR` applies;
+    /// - `Some(None)` — `explicitRoot: null`: env override DISABLED;
+    /// - `Some(Some(root))` — explicit root forced.
+    pub explicit_root: Option<Option<String>>,
+    /// `None` → `findProjectRoot(process.cwd())` (TS `??` — a `null`
+    /// project root also falls back to detection).
+    pub project_root: Option<PathBuf>,
+}
+
+struct Candidate {
+    scope: OcChatgptTargetScope,
+    source: OcChatgptTargetSource,
+    root: String,
+    account_path: String,
+    backup_root: String,
+    has_account_artifacts: bool,
+    has_signals: bool,
+}
+
+/// TS `getResolvedUserHomeDir()` — win32 prefers USERPROFILE > HOME >
+/// HOMEDRIVE+HOMEPATH > os home; POSIX prefers HOME > os home.
+fn get_resolved_user_home_dir() -> String {
+    fn env_trimmed(key: &str) -> Option<String> {
+        let value = std::env::var(key).ok()?;
+        let trimmed = value.trim();
+        if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed.to_string())
+        }
+    }
+    let os_home = || {
+        std::env::home_dir()
+            .map(|p| p.to_string_lossy().into_owned())
+            .unwrap_or_default()
+    };
+    if cfg!(windows) {
+        if let Some(userprofile) = env_trimmed("USERPROFILE") {
+            return userprofile;
+        }
+        if let Some(home) = env_trimmed("HOME") {
+            return home;
+        }
+        if let (Some(drive), Some(path)) = (env_trimmed("HOMEDRIVE"), env_trimmed("HOMEPATH")) {
+            // `win32.resolve(`${HOMEDRIVE}\\`, HOMEPATH)` — join the drive
+            // root with the (usually root-relative) home path.
+            let joined = if path.starts_with('\\') || path.starts_with('/') {
+                format!("{drive}{path}")
+            } else {
+                format!("{drive}\\{path}")
+            };
+            return joined;
+        }
+        return os_home();
+    }
+    if let Some(home) = env_trimmed("HOME") {
+        return home;
+    }
+    os_home()
+}
+
+/// TS `isWindowsDriveRoot(candidate)` — `C:` or `C:\`.
+fn is_windows_drive_root(candidate: &str) -> bool {
+    let bytes = candidate.as_bytes();
+    match bytes.len() {
+        2 => bytes[0].is_ascii_alphabetic() && bytes[1] == b':',
+        3 => bytes[0].is_ascii_alphabetic() && bytes[1] == b':' && bytes[2] == b'\\',
+        _ => false,
+    }
+}
+
+/// Lexical `normalize(resolve(p))` — absolutize against the cwd, resolve
+/// `.`/`..` segments, and reassemble with the platform separator (Node's
+/// path.resolve does not consult the filesystem either).
+fn lexical_resolve(p: &str) -> PathBuf {
+    let path = Path::new(p);
+    let joined: PathBuf = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        let mut base = std::env::current_dir().unwrap_or_default();
+        base.push(path);
+        base
+    };
+    let mut out = PathBuf::new();
+    for component in joined.components() {
+        match component {
+            Component::Prefix(prefix) => out.push(prefix.as_os_str()),
+            Component::RootDir => out.push(Component::RootDir.as_os_str()),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                let popped = out.pop();
+                let _ = popped; // ".." above the root is dropped (Node parity)
+            }
+            Component::Normal(part) => out.push(part),
+        }
+    }
+    out
+}
+
+/// TS `normalizeCandidatePath(candidate)`.
+fn normalize_candidate_path(candidate: &str) -> String {
+    let trimmed = candidate.trim();
+    if trimmed.is_empty() {
+        return String::new();
+    }
+    let normalized = lexical_resolve(trimmed).to_string_lossy().into_owned();
+    if cfg!(windows) && is_windows_drive_root(&normalized) {
+        if normalized.ends_with('\\') {
+            return normalized;
+        }
+        return format!("{normalized}\\");
+    }
+    if normalized.chars().count() > 1
+        && (normalized.ends_with('\\') || normalized.ends_with('/'))
+    {
+        return normalized
+            .trim_end_matches(['\\', '/'])
+            .to_string();
+    }
+    normalized
+}
+
+/// TS `deduplicatePaths(paths)` — normalize, drop empties, dedup (win32:
+/// case-insensitive), first-seen order preserved.
+fn deduplicate_paths(paths: &[String]) -> Vec<String> {
+    let mut seen: HashSet<String> = HashSet::new();
+    let mut result: Vec<String> = Vec::new();
+    for candidate in paths {
+        let normalized = normalize_candidate_path(candidate);
+        if normalized.is_empty() {
+            continue;
+        }
+        let key = if cfg!(windows) {
+            normalized.to_lowercase()
+        } else {
+            normalized.clone()
+        };
+        if seen.insert(key) {
+            result.push(normalized);
+        }
+    }
+    result
+}
+
+fn join_str(root: &str, name: &str) -> String {
+    Path::new(root).join(name).to_string_lossy().into_owned()
+}
+
+/// Rotated-artifact filename filter (spec 12 gotcha 19): starts with
+/// `openai-codex-accounts.json.`, excludes `.tmp`, `.wal`, and any name
+/// containing `.rotate.`. Readdir errors are swallowed.
+fn has_rotated(dir: &str) -> bool {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return false;
+    };
+    for entry in entries.flatten() {
+        let Ok(file_type) = entry.file_type() else {
+            continue;
+        };
+        if !file_type.is_file() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if !name.starts_with(&format!("{ACCOUNT_FILE_NAME}.")) {
+            continue;
+        }
+        if name.ends_with(".tmp") || name.ends_with(".wal") || name.contains(".rotate.") {
+            continue;
+        }
+        return true;
+    }
+    false
+}
+
+/// TS `hasAccountArtifacts(root)`.
+fn has_account_artifacts(root: &str) -> bool {
+    let account_path = join_str(root, ACCOUNT_FILE_NAME);
+    if Path::new(&account_path).exists() || Path::new(&format!("{account_path}.wal")).exists() {
+        return true;
+    }
+    if has_rotated(root) {
+        return true;
+    }
+    let backups_dir = join_str(root, BACKUPS_DIR_NAME);
+    if Path::new(&join_str(&backups_dir, ACCOUNT_FILE_NAME)).exists() {
+        return true;
+    }
+    has_rotated(&backups_dir)
+}
+
+/// TS `hasStorageSignals(root)` — a `backups` or `projects` dir exists.
+fn has_storage_signals(root: &str) -> bool {
+    Path::new(&join_str(root, BACKUPS_DIR_NAME)).exists()
+        || Path::new(&join_str(root, PROJECTS_DIR_NAME)).exists()
+}
+
+/// TS `inferScopeFromRoot(root, canonicalRoot)` — `"project"` iff `root`
+/// lives under `<canonicalRoot>/projects/`.
+fn infer_scope_from_root(root: &str, canonical_root: &str) -> OcChatgptTargetScope {
+    // Node `relative(canonicalRoot, root)` compares case-insensitively on
+    // win32 when finding the common prefix.
+    let (root_key, canonical_key) = if cfg!(windows) {
+        (root.to_lowercase(), canonical_root.to_lowercase())
+    } else {
+        (root.to_string(), canonical_root.to_string())
+    };
+    let sep = std::path::MAIN_SEPARATOR;
+    let prefix = format!("{canonical_key}{sep}");
+    let Some(remainder) = root_key.strip_prefix(&prefix) else {
+        return OcChatgptTargetScope::Global;
+    };
+    if remainder.starts_with(&format!("{PROJECTS_DIR_NAME}{sep}")) {
+        OcChatgptTargetScope::Project
+    } else {
+        OcChatgptTargetScope::Global
+    }
+}
+
+/// TS `detectOcChatgptMultiAuthTarget(options)`.
+pub fn detect_oc_chatgpt_multi_auth_target(
+    options: &DetectOcChatgptTargetOptions,
+) -> OcChatgptTargetDetectionResult {
+    let explicit_from_env = std::env::var("OC_CHATGPT_MULTI_AUTH_DIR")
+        .unwrap_or_default()
+        .trim()
+        .to_string();
+    let explicit_root = match &options.explicit_root {
+        Some(inner) => inner.clone().unwrap_or_default(),
+        None => explicit_from_env,
+    }
+    .trim()
+    .to_string();
+
+    let user_home = get_resolved_user_home_dir();
+    let canonical_root = join_str(&user_home, CANONICAL_HOME_BASENAME);
+    let project_root = options.project_root.clone().or_else(|| {
+        find_project_root(&std::env::current_dir().unwrap_or_default())
+    });
+    let identity_root = project_root
+        .as_deref()
+        .map(resolve_project_storage_identity_root);
+    let project_storage_root = identity_root.map(|identity| {
+        Path::new(&canonical_root)
+            .join(PROJECTS_DIR_NAME)
+            .join(get_project_storage_key(&identity))
+            .to_string_lossy()
+            .into_owned()
+    });
+
+    let normalized_explicit_root = if explicit_root.is_empty() {
+        String::new()
+    } else {
+        normalize_candidate_path(&explicit_root)
+    };
+    let ordered_roots: Vec<String> = if !normalized_explicit_root.is_empty() {
+        vec![normalized_explicit_root.clone()]
+    } else {
+        let mut roots = vec![canonical_root.clone()];
+        if let Some(project) = &project_storage_root {
+            roots.push(project.clone());
+        }
+        deduplicate_paths(&roots)
+    };
+
+    let candidates: Vec<Candidate> = ordered_roots
+        .into_iter()
+        .map(|root| {
+            let inferred_scope = infer_scope_from_root(&root, &canonical_root);
+            let source = if root == normalized_explicit_root && !normalized_explicit_root.is_empty()
+            {
+                OcChatgptTargetSource::Explicit
+            } else if inferred_scope == OcChatgptTargetScope::Project {
+                OcChatgptTargetSource::Project
+            } else {
+                OcChatgptTargetSource::DefaultGlobal
+            };
+            let account_path = join_str(&root, ACCOUNT_FILE_NAME);
+            let backup_root = join_str(&root, BACKUPS_DIR_NAME);
+            let has_account_artifacts_flag = has_account_artifacts(&root);
+            let has_signals = has_account_artifacts_flag || has_storage_signals(&root);
+            Candidate {
+                scope: inferred_scope,
+                source,
+                root,
+                account_path,
+                backup_root,
+                has_account_artifacts: has_account_artifacts_flag,
+                has_signals,
+            }
+        })
+        .collect();
+
+    let to_descriptor = |candidate: &Candidate, resolution: OcChatgptTargetResolution| {
+        OcChatgptTargetDescriptor {
+            scope: candidate.scope,
+            source: candidate.source,
+            root: candidate.root.clone(),
+            account_path: candidate.account_path.clone(),
+            backup_root: candidate.backup_root.clone(),
+            resolution,
+        }
+    };
+    let to_candidate_info = |candidate: &Candidate| OcChatgptTargetCandidateInfo {
+        scope: candidate.scope,
+        source: candidate.source,
+        root: candidate.root.clone(),
+        account_path: candidate.account_path.clone(),
+        backup_root: candidate.backup_root.clone(),
+        has_account_artifacts: candidate.has_account_artifacts,
+        has_signals: candidate.has_signals,
+    };
+
+    let with_accounts: Vec<&Candidate> = candidates
+        .iter()
+        .filter(|candidate| candidate.has_account_artifacts)
+        .collect();
+    if with_accounts.len() == 1 {
+        return OcChatgptTargetDetectionResult::Target {
+            descriptor: to_descriptor(with_accounts[0], OcChatgptTargetResolution::Accounts),
+        };
+    }
+    if with_accounts.len() > 1 {
+        return OcChatgptTargetDetectionResult::Ambiguous(OcChatgptTargetAmbiguous {
+            reason:
+                "Multiple oc-chatgpt-multi-auth targets contain account artifacts; refusing to guess."
+                    .to_string(),
+            candidates: with_accounts.iter().map(|c| to_candidate_info(c)).collect(),
+        });
+    }
+
+    let with_signals: Vec<&Candidate> = candidates
+        .iter()
+        .filter(|candidate| candidate.has_signals)
+        .collect();
+    if with_signals.len() == 1 {
+        return OcChatgptTargetDetectionResult::Target {
+            descriptor: to_descriptor(with_signals[0], OcChatgptTargetResolution::Signals),
+        };
+    }
+    if with_signals.len() > 1 {
+        return OcChatgptTargetDetectionResult::Ambiguous(OcChatgptTargetAmbiguous {
+            reason:
+                "Multiple oc-chatgpt-multi-auth targets contain storage signals; refusing to guess."
+                    .to_string(),
+            candidates: with_signals.iter().map(|c| to_candidate_info(c)).collect(),
+        });
+    }
+
+    OcChatgptTargetDetectionResult::NoTarget(OcChatgptTargetNone {
+        reason:
+            "No oc-chatgpt-multi-auth target root found; create ~/.opencode or supply OC_CHATGPT_MULTI_AUTH_DIR."
+                .to_string(),
+        tried: candidates
+            .iter()
+            .map(|candidate| OcChatgptTargetTried {
+                scope: candidate.scope,
+                source: candidate.source,
+                root: candidate.root.clone(),
+                account_path: candidate.account_path.clone(),
+                backup_root: candidate.backup_root.clone(),
+            })
+            .collect(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::fs;
+
+    // Ported from test/oc-chatgpt-target-detection.test.ts. Every test pins
+    // HOME/USERPROFILE via the env sandbox and passes an explicit projectRoot
+    // (or explicit root) so the repo's own git checkout never leaks in.
+
+    fn assert_target(
+        result: &OcChatgptTargetDetectionResult,
+        expected_scope: OcChatgptTargetScope,
+        expected_root: &str,
+    ) -> OcChatgptTargetDescriptor {
+        match result {
+            OcChatgptTargetDetectionResult::Target { descriptor } => {
+                assert_eq!(descriptor.scope, expected_scope);
+                assert_eq!(descriptor.root, expected_root);
+                descriptor.clone()
+            }
+            other => panic!("expected target, got {other:?}"),
+        }
+    }
+
+    fn opts_with_project(project: &Path) -> DetectOcChatgptTargetOptions {
+        DetectOcChatgptTargetOptions {
+            explicit_root: None,
+            project_root: Some(project.to_path_buf()),
+        }
+    }
+
+    fn opts_with_explicit(root: &str) -> DetectOcChatgptTargetOptions {
+        DetectOcChatgptTargetOptions {
+            explicit_root: Some(Some(root.to_string())),
+            project_root: Some(std::env::temp_dir().join("cma-no-project-here")),
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn returns_project_scoped_target_when_only_project_account_storage_exists() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let home = sandbox.root().to_path_buf();
+        let project_dir = home.join("project-alpha");
+        fs::create_dir_all(project_dir.join(".git")).unwrap();
+
+        let identity_root = resolve_project_storage_identity_root(&project_dir);
+        let project_key = get_project_storage_key(&identity_root);
+        let project_root = home.join(".opencode").join("projects").join(&project_key);
+        fs::create_dir_all(&project_root).unwrap();
+        fs::write(project_root.join("openai-codex-accounts.json"), "{}").unwrap();
+
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_project(&project_dir));
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Project,
+            &project_root.to_string_lossy(),
+        );
+        assert_eq!(
+            descriptor.account_path,
+            project_root
+                .join("openai-codex-accounts.json")
+                .to_string_lossy()
+        );
+        assert_eq!(
+            descriptor.backup_root,
+            project_root.join("backups").to_string_lossy()
+        );
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Accounts);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn returns_ambiguous_when_both_global_and_project_accounts_exist() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let home = sandbox.root().to_path_buf();
+        let project_dir = home.join("project-beta");
+        fs::create_dir_all(project_dir.join(".git")).unwrap();
+
+        let identity_root = resolve_project_storage_identity_root(&project_dir);
+        let project_key = get_project_storage_key(&identity_root);
+        let project_root = home.join(".opencode").join("projects").join(&project_key);
+        fs::create_dir_all(&project_root).unwrap();
+        fs::write(project_root.join("openai-codex-accounts.json"), "{}").unwrap();
+
+        let global_root = home.join(".opencode");
+        fs::write(global_root.join("openai-codex-accounts.json"), "{}").unwrap();
+
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_project(&project_dir));
+        match result {
+            OcChatgptTargetDetectionResult::Ambiguous(ambiguous) => {
+                assert_eq!(ambiguous.candidates.len(), 2);
+                assert_eq!(
+                    ambiguous.reason,
+                    "Multiple oc-chatgpt-multi-auth targets contain account artifacts; refusing to guess."
+                );
+            }
+            other => panic!("expected ambiguous, got {other:?}"),
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn returns_explicit_target_from_storage_signals() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let override_root = sandbox.root().join("override-signals-root");
+        fs::create_dir_all(override_root.join("backups")).unwrap();
+
+        let override_str = override_root.to_string_lossy().into_owned();
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(&override_str));
+        let descriptor =
+            assert_target(&result, OcChatgptTargetScope::Global, &override_str);
+        assert_eq!(descriptor.source, OcChatgptTargetSource::Explicit);
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Signals);
+        assert_eq!(
+            descriptor.account_path,
+            override_root
+                .join("openai-codex-accounts.json")
+                .to_string_lossy()
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn explicit_root_null_disables_the_environment_override() {
+        let mut sandbox = EnvSandbox::new();
+        let home = sandbox.root().to_path_buf();
+        let override_root = home.join("env-override-root");
+        let canonical_root = home.join(".opencode");
+        fs::create_dir_all(override_root.join("backups")).unwrap();
+        fs::create_dir_all(canonical_root.join("backups")).unwrap();
+        sandbox.set_var("OC_CHATGPT_MULTI_AUTH_DIR", &override_root);
+
+        let options = DetectOcChatgptTargetOptions {
+            explicit_root: Some(None),
+            project_root: Some(home.join("no-project-here")),
+        };
+        let result = detect_oc_chatgpt_multi_auth_target(&options);
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Global,
+            &canonical_root.to_string_lossy(),
+        );
+        assert_eq!(descriptor.source, OcChatgptTargetSource::DefaultGlobal);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn explicit_env_override_is_authoritative_when_default_roots_also_qualify() {
+        let mut sandbox = EnvSandbox::new();
+        let home = sandbox.root().to_path_buf();
+        let override_root = home.join("override-root");
+        let canonical_root = home.join(".opencode");
+        fs::create_dir_all(override_root.join("backups")).unwrap();
+        fs::create_dir_all(canonical_root.join("projects")).unwrap();
+        sandbox.set_var("OC_CHATGPT_MULTI_AUTH_DIR", &override_root);
+
+        let options = DetectOcChatgptTargetOptions {
+            explicit_root: None,
+            project_root: Some(home.join("no-project-here")),
+        };
+        let result = detect_oc_chatgpt_multi_auth_target(&options);
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Global,
+            &override_root.to_string_lossy(),
+        );
+        assert_eq!(descriptor.source, OcChatgptTargetSource::Explicit);
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Signals);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn keeps_canonical_home_root_global_when_home_contains_projects_segment() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let nested_home = sandbox.root().join("projects").join("dev-home");
+        fs::create_dir_all(&nested_home).unwrap();
+        sandbox.set_var("HOME", &nested_home);
+        sandbox.set_var("USERPROFILE", &nested_home);
+
+        let canonical_root = nested_home.join(".opencode");
+        fs::create_dir_all(canonical_root.join("backups")).unwrap();
+
+        let options = DetectOcChatgptTargetOptions {
+            explicit_root: None,
+            project_root: Some(nested_home.join("no-project-here")),
+        };
+        let result = detect_oc_chatgpt_multi_auth_target(&options);
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Global,
+            &canonical_root.to_string_lossy(),
+        );
+        assert_eq!(descriptor.source, OcChatgptTargetSource::DefaultGlobal);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn keeps_explicit_roots_global_even_when_their_path_includes_projects() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let explicit_root = sandbox
+            .root()
+            .join("custom-root")
+            .join("projects")
+            .join("manual")
+            .join(".opencode");
+        fs::create_dir_all(explicit_root.join("backups")).unwrap();
+
+        let explicit_str = explicit_root.to_string_lossy().into_owned();
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(&explicit_str));
+        let descriptor = assert_target(&result, OcChatgptTargetScope::Global, &explicit_str);
+        assert_eq!(descriptor.source, OcChatgptTargetSource::Explicit);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    #[serial(env)]
+    fn preserves_windows_drive_roots_after_normalization() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        // Q:\ is (almost certainly) unmapped, so no artifacts/signals exist.
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit("Q:\\"));
+        match result {
+            OcChatgptTargetDetectionResult::NoTarget(none) => {
+                assert_eq!(none.tried[0].root, "Q:\\");
+            }
+            other => panic!("expected none, got {other:?}"),
+        }
+    }
+
+    #[cfg(windows)]
+    #[test]
+    #[serial(env)]
+    fn normalizes_mixed_windows_separators_in_explicit_roots() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(
+            "Q:\\Users/profile\\.opencode\\",
+        ));
+        match result {
+            OcChatgptTargetDetectionResult::NoTarget(none) => {
+                assert_eq!(none.tried[0].root, "Q:\\Users\\profile\\.opencode");
+            }
+            other => panic!("expected none, got {other:?}"),
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn resolves_relative_explicit_roots_before_target_detection() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let absolute_root = sandbox.root().join("relative-override").join(".opencode");
+        fs::create_dir_all(absolute_root.join("backups")).unwrap();
+
+        let cwd = std::env::current_dir().unwrap();
+        let Some(relative) = pathdiff_lexical(&cwd, &absolute_root) else {
+            // Different drives (no relative form) — nothing to exercise.
+            return;
+        };
+        let result =
+            detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(&relative));
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Global,
+            &absolute_root.to_string_lossy(),
+        );
+        assert_eq!(descriptor.source, OcChatgptTargetSource::Explicit);
+    }
+
+    /// Minimal lexical `path.relative` for the test above.
+    fn pathdiff_lexical(from: &Path, to: &Path) -> Option<String> {
+        let from_components: Vec<String> = from
+            .components()
+            .map(|c| c.as_os_str().to_string_lossy().into_owned())
+            .collect();
+        let to_components: Vec<String> = to
+            .components()
+            .map(|c| c.as_os_str().to_string_lossy().into_owned())
+            .collect();
+        if from_components.first() != to_components.first() {
+            return None; // different prefixes (drives)
+        }
+        let mut common = 0;
+        while common < from_components.len()
+            && common < to_components.len()
+            && from_components[common].to_lowercase() == to_components[common].to_lowercase()
+        {
+            common += 1;
+        }
+        let mut parts: Vec<String> = Vec::new();
+        for _ in common..from_components.len() {
+            parts.push("..".to_string());
+        }
+        parts.extend(to_components[common..].iter().cloned());
+        Some(parts.join(std::path::MAIN_SEPARATOR_STR))
+    }
+
+    #[test]
+    #[serial(env)]
+    fn prefers_explicit_override_containing_backup_artifacts() {
+        let mut sandbox = EnvSandbox::new();
+        let override_root = sandbox.root().join("override-root");
+        let backups_dir = override_root.join("backups");
+        fs::create_dir_all(&backups_dir).unwrap();
+        fs::write(
+            backups_dir.join("openai-codex-accounts.json.manual-2026-03-09"),
+            "{}",
+        )
+        .unwrap();
+        sandbox.set_var("OC_CHATGPT_MULTI_AUTH_DIR", &override_root);
+
+        let options = DetectOcChatgptTargetOptions {
+            explicit_root: None,
+            project_root: Some(sandbox.root().join("no-project-here")),
+        };
+        let result = detect_oc_chatgpt_multi_auth_target(&options);
+        let descriptor = assert_target(
+            &result,
+            OcChatgptTargetScope::Global,
+            &override_root.to_string_lossy(),
+        );
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Accounts);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn returns_none_with_guidance_when_no_targets_exist() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let options = DetectOcChatgptTargetOptions {
+            explicit_root: None,
+            project_root: Some(sandbox.root().join("no-project-here")),
+        };
+        let result = detect_oc_chatgpt_multi_auth_target(&options);
+        match result {
+            OcChatgptTargetDetectionResult::NoTarget(none) => {
+                assert!(none.reason.contains("~/.opencode"));
+                assert!(!none.tried.is_empty());
+                assert_eq!(
+                    none.reason,
+                    "No oc-chatgpt-multi-auth target root found; create ~/.opencode or supply OC_CHATGPT_MULTI_AUTH_DIR."
+                );
+            }
+            other => panic!("expected none, got {other:?}"),
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn reports_exact_global_and_project_roots_tried() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let home = sandbox.root().to_path_buf();
+        let project_dir = home.join("project-delta");
+        fs::create_dir_all(project_dir.join(".git")).unwrap();
+
+        let identity_root = resolve_project_storage_identity_root(&project_dir);
+        let project_key = get_project_storage_key(&identity_root);
+        let canonical_root = home.join(".opencode");
+        let project_root = canonical_root.join("projects").join(&project_key);
+
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_project(&project_dir));
+        match result {
+            OcChatgptTargetDetectionResult::NoTarget(none) => {
+                assert!(none.reason.contains("OC_CHATGPT_MULTI_AUTH_DIR"));
+                assert_eq!(
+                    none.tried,
+                    vec![
+                        OcChatgptTargetTried {
+                            scope: OcChatgptTargetScope::Global,
+                            source: OcChatgptTargetSource::DefaultGlobal,
+                            root: canonical_root.to_string_lossy().into_owned(),
+                            account_path: canonical_root
+                                .join("openai-codex-accounts.json")
+                                .to_string_lossy()
+                                .into_owned(),
+                            backup_root: canonical_root
+                                .join("backups")
+                                .to_string_lossy()
+                                .into_owned(),
+                        },
+                        OcChatgptTargetTried {
+                            scope: OcChatgptTargetScope::Project,
+                            source: OcChatgptTargetSource::Project,
+                            root: project_root.to_string_lossy().into_owned(),
+                            account_path: project_root
+                                .join("openai-codex-accounts.json")
+                                .to_string_lossy()
+                                .into_owned(),
+                            backup_root: project_root
+                                .join("backups")
+                                .to_string_lossy()
+                                .into_owned(),
+                        },
+                    ]
+                );
+            }
+            other => panic!("expected none, got {other:?}"),
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn signals_resolution_when_only_backup_directory_exists() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let explicit_root = sandbox.root().join("signals-only-root");
+        fs::create_dir_all(explicit_root.join("backups")).unwrap();
+
+        let explicit_str = explicit_root.to_string_lossy().into_owned();
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(&explicit_str));
+        let descriptor = assert_target(&result, OcChatgptTargetScope::Global, &explicit_str);
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Signals);
+        assert_eq!(
+            descriptor.backup_root,
+            explicit_root.join("backups").to_string_lossy()
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn ignores_rotate_and_tmp_artifacts_when_detecting_account_artifacts() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("OC_CHATGPT_MULTI_AUTH_DIR");
+        let explicit_root = sandbox.root().join("artifact-filter-root");
+        let backups_dir = explicit_root.join("backups");
+        fs::create_dir_all(&backups_dir).unwrap();
+        fs::write(backups_dir.join("openai-codex-accounts.json.rotate.1"), "{}").unwrap();
+        fs::write(backups_dir.join("openai-codex-accounts.json.tmp"), "{}").unwrap();
+        fs::write(backups_dir.join("openai-codex-accounts.json.wal"), "{}").unwrap();
+
+        let explicit_str = explicit_root.to_string_lossy().into_owned();
+        let result = detect_oc_chatgpt_multi_auth_target(&opts_with_explicit(&explicit_str));
+        let descriptor = assert_target(&result, OcChatgptTargetScope::Global, &explicit_str);
+        assert_eq!(descriptor.resolution, OcChatgptTargetResolution::Signals);
+    }
+}
diff --git a/crates/manager/src/quota_cache_helpers.rs b/crates/manager/src/quota_cache_helpers.rs
new file mode 100644
index 000000000..442fe06f2
--- /dev/null
+++ b/crates/manager/src/quota_cache_helpers.rs
@@ -0,0 +1,462 @@
+//! Port of `lib/codex-manager/quota-cache-helpers.ts`.
+//!
+//! Quota-cache lookup/update helpers shared by the manager CLI commands.
+//! Behavior source: spec 09 §4.2. Safety rules (shared with
+//! `lib/quota-readiness.ts`): an entry may be read from / written to
+//! `byAccountId[id]` only when the normalized id is non-null AND unique among
+//! the accounts; `byEmail[email]` only under the safe-email-fallback rule.
+//! Stale/unsafe email entries are actively pruned on update.
+
+use std::collections::HashMap;
+
+use cma_core::model_family::{DEFAULT_MODEL, DEFAULT_PROBE_MODEL};
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::RateLimitStateV3;
+use cma_core::utils::now_ms;
+use cma_quota::cache::{QuotaCacheData, QuotaCacheEntry, QuotaCacheWindow};
+use cma_quota::probe::CodexQuotaSnapshot;
+use cma_quota::readiness::{
+    build_quota_email_fallback_state, has_safe_quota_email_fallback, has_unique_quota_account_id,
+    normalize_quota_account_id, normalize_quota_email, QuotaCacheAccountRef,
+    QuotaEmailFallbackState,
+};
+use cma_runtime::account_status::get_rate_limit_reset_time_for_family;
+
+/// TS `DEFAULT_LIVE_PROBE_MODEL` — default model used for live quota probes
+/// across manager commands (= `DEFAULT_PROBE_MODEL` = `"gpt-5.6-sol"`).
+pub const DEFAULT_LIVE_PROBE_MODEL: &str = DEFAULT_PROBE_MODEL;
+
+/// TS private `getQuotaCacheEntryForAccount(cache, account, accounts, state?)`.
+fn get_quota_cache_entry_for_account<'c, T: QuotaCacheAccountRef>(
+    cache: &'c QuotaCacheData,
+    account: &impl QuotaCacheAccountRef,
+    accounts: &[T],
+    email_fallback_state: &HashMap<String, QuotaEmailFallbackState>,
+) -> Option<&'c QuotaCacheEntry> {
+    if let Some(account_id) = normalize_quota_account_id(account.quota_account_id())
+        && has_unique_quota_account_id(accounts, account)
+        && let Some(entry) = cache.by_account_id.get(&account_id)
+    {
+        return Some(entry);
+    }
+    if let Some(email) = normalize_quota_email(account.quota_email())
+        && has_safe_quota_email_fallback(email_fallback_state, account)
+        && let Some(entry) = cache.by_email.get(&email)
+    {
+        return Some(entry);
+    }
+    None
+}
+
+/// Account view needed by [`get_persisted_quota_view_for_account`]:
+/// TS `Pick<AccountMetadataV3, "accountId" | "email" | "rateLimitResetTimes">`.
+pub struct PersistedQuotaViewAccount<'a> {
+    pub account_id: Option<&'a str>,
+    pub email: Option<&'a str>,
+    pub rate_limit_reset_times: Option<&'a RateLimitStateV3>,
+}
+
+impl QuotaCacheAccountRef for PersistedQuotaViewAccount<'_> {
+    fn quota_account_id(&self) -> Option<&str> {
+        self.account_id
+    }
+    fn quota_email(&self) -> Option<&str> {
+        self.email
+    }
+}
+
+/// TS `getPersistedQuotaViewForAccount(cache, account, accounts, now, state?)`.
+///
+/// Fetches the cached entry (accountId key first, safe-email fallback), then
+/// overlays the persisted rate-limit reset time for family `"codex"`: when the
+/// storage tracks a future reset that the cached entry does not already cover
+/// as a 429, synthesize a 429 view so storage-tracked rate limiting always
+/// shows through the quota view.
+pub fn get_persisted_quota_view_for_account<T: QuotaCacheAccountRef>(
+    cache: Option<&QuotaCacheData>,
+    account: &PersistedQuotaViewAccount<'_>,
+    accounts: &[T],
+    now: i64,
+    email_fallback_state: Option<&HashMap<String, QuotaEmailFallbackState>>,
+) -> Option<QuotaCacheEntry> {
+    let built_state;
+    let state = match email_fallback_state {
+        Some(state) => state,
+        None => {
+            built_state = build_quota_email_fallback_state(accounts);
+            &built_state
+        }
+    };
+    let cached_entry =
+        cache.and_then(|cache| get_quota_cache_entry_for_account(cache, account, accounts, state));
+    let persisted_reset_at =
+        get_rate_limit_reset_time_for_family(account.rate_limit_reset_times, now, ModelFamily::Codex);
+    let Some(persisted_reset_at) = persisted_reset_at else {
+        return cached_entry.cloned();
+    };
+    let cached_primary_reset_at = cached_entry
+        .and_then(|entry| entry.primary.reset_at_ms)
+        .unwrap_or(0.0);
+    let cached_secondary_reset_at = cached_entry
+        .and_then(|entry| entry.secondary.reset_at_ms)
+        .unwrap_or(0.0);
+    if let Some(entry) = cached_entry
+        && entry.status == 429.0
+        && cached_primary_reset_at.max(cached_secondary_reset_at) >= persisted_reset_at as f64
+    {
+        return Some(entry.clone());
+    }
+    Some(QuotaCacheEntry {
+        updated_at: cached_entry
+            .map(|entry| entry.updated_at)
+            .unwrap_or(now as f64),
+        status: 429.0,
+        model: cached_entry
+            .map(|entry| entry.model.clone())
+            .unwrap_or_else(|| DEFAULT_MODEL.to_string()),
+        plan_type: cached_entry.and_then(|entry| entry.plan_type.clone()),
+        primary: QuotaCacheWindow {
+            used_percent: cached_entry.and_then(|entry| entry.primary.used_percent),
+            window_minutes: cached_entry.and_then(|entry| entry.primary.window_minutes),
+            reset_at_ms: Some(cached_primary_reset_at.max(persisted_reset_at as f64)),
+        },
+        secondary: cached_entry
+            .map(|entry| entry.secondary)
+            .unwrap_or_default(),
+    })
+}
+
+/// TS `updateQuotaCacheForAccount(cache, account, snapshot, accounts, state?)`
+/// — returns whether anything changed. Writes `byAccountId[id]` when the id
+/// is unique; writes `byEmail[email]` only when the email is safe AND no
+/// unique accountId (id key takes priority); otherwise an existing email key
+/// is DELETED (stale/unsafe email entries are actively pruned).
+pub fn update_quota_cache_for_account<T: QuotaCacheAccountRef>(
+    cache: &mut QuotaCacheData,
+    account: &impl QuotaCacheAccountRef,
+    snapshot: &CodexQuotaSnapshot,
+    accounts: &[T],
+    email_fallback_state: Option<&HashMap<String, QuotaEmailFallbackState>>,
+) -> bool {
+    let built_state;
+    let state = match email_fallback_state {
+        Some(state) => state,
+        None => {
+            built_state = build_quota_email_fallback_state(accounts);
+            &built_state
+        }
+    };
+    let next_entry = QuotaCacheEntry {
+        updated_at: now_ms() as f64,
+        status: snapshot.status as f64,
+        model: snapshot.model.clone(),
+        plan_type: snapshot.plan_type.clone(),
+        primary: QuotaCacheWindow {
+            used_percent: snapshot.primary.used_percent,
+            window_minutes: snapshot.primary.window_minutes.map(|v| v as f64),
+            reset_at_ms: snapshot.primary.reset_at_ms.map(|v| v as f64),
+        },
+        secondary: QuotaCacheWindow {
+            used_percent: snapshot.secondary.used_percent,
+            window_minutes: snapshot.secondary.window_minutes.map(|v| v as f64),
+            reset_at_ms: snapshot.secondary.reset_at_ms.map(|v| v as f64),
+        },
+    };
+
+    let mut changed = false;
+    let account_id = normalize_quota_account_id(account.quota_account_id());
+    let has_unique_account_id =
+        account_id.is_some() && has_unique_quota_account_id(accounts, account);
+    if has_unique_account_id {
+        // account_id is Some here by construction.
+        if let Some(account_id) = &account_id {
+            cache.by_account_id.insert(account_id.clone(), next_entry.clone());
+            changed = true;
+        }
+    }
+    let email = normalize_quota_email(account.quota_email());
+    if let Some(email) = &email
+        && has_safe_quota_email_fallback(state, account)
+        && !has_unique_account_id
+    {
+        cache.by_email.insert(email.clone(), next_entry);
+        changed = true;
+    } else if let Some(email) = &email
+        && cache.by_email.contains_key(email)
+    {
+        cache.by_email.remove(email);
+        changed = true;
+    }
+    changed
+}
+
+/// TS `cloneQuotaCacheData(cache)` — shallow spread of both maps. Safe
+/// because quota cache entries are always REPLACED whole, never mutated in
+/// place. Porters: preserve replace-not-mutate.
+pub fn clone_quota_cache_data(cache: &QuotaCacheData) -> QuotaCacheData {
+    cache.clone()
+}
+
+/// TS `pruneUnsafeQuotaEmailCacheEntry(cache, email, accounts, state)` —
+/// deletes `byEmail[normalized]` when no account with that email still has a
+/// safe fallback; used after an account's email changed identity during
+/// refresh. Returns whether an entry was removed.
+pub fn prune_unsafe_quota_email_cache_entry<T: QuotaCacheAccountRef>(
+    cache: &mut QuotaCacheData,
+    email: Option<&str>,
+    accounts: &[T],
+    email_fallback_state: &HashMap<String, QuotaEmailFallbackState>,
+) -> bool {
+    let Some(normalized_email) = normalize_quota_email(email) else {
+        return false;
+    };
+    if !cache.by_email.contains_key(&normalized_email) {
+        return false;
+    }
+    let has_safe_fallback_account = accounts.iter().any(|account| {
+        normalize_quota_email(account.quota_email()).as_deref() == Some(normalized_email.as_str())
+            && has_safe_quota_email_fallback(email_fallback_state, account)
+    });
+    if has_safe_fallback_account {
+        return false;
+    }
+    cache.by_email.remove(&normalized_email);
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_quota::probe::CodexQuotaWindow;
+    use cma_quota::readiness::QuotaAccountRef;
+
+    fn account(id: Option<&str>, email: Option<&str>) -> QuotaAccountRef {
+        QuotaAccountRef {
+            account_id: id.map(str::to_string),
+            email: email.map(str::to_string),
+        }
+    }
+
+    fn snapshot(status: u16) -> CodexQuotaSnapshot {
+        CodexQuotaSnapshot {
+            status,
+            plan_type: Some("plus".to_string()),
+            active_limit: None,
+            primary: CodexQuotaWindow {
+                used_percent: Some(10.0),
+                window_minutes: Some(300),
+                reset_at_ms: Some(1_000),
+            },
+            secondary: CodexQuotaWindow::default(),
+            model: "gpt-5.5".to_string(),
+        }
+    }
+
+    #[test]
+    fn update_prefers_unique_account_id_key() {
+        let mut cache = QuotaCacheData::default();
+        let accounts = vec![account(Some("acct-1"), Some("a@x.com"))];
+        let changed = update_quota_cache_for_account(
+            &mut cache,
+            &accounts[0],
+            &snapshot(200),
+            &accounts,
+            None,
+        );
+        assert!(changed);
+        assert!(cache.by_account_id.contains_key("acct-1"));
+        assert!(!cache.by_email.contains_key("a@x.com"));
+    }
+
+    #[test]
+    fn update_falls_back_to_safe_email_without_account_id() {
+        let mut cache = QuotaCacheData::default();
+        let accounts = vec![account(None, Some("A@X.com"))];
+        let changed = update_quota_cache_for_account(
+            &mut cache,
+            &accounts[0],
+            &snapshot(200),
+            &accounts,
+            None,
+        );
+        assert!(changed);
+        assert!(cache.by_email.contains_key("a@x.com"));
+    }
+
+    #[test]
+    fn update_deletes_stale_email_entry_when_id_key_takes_priority() {
+        let mut cache = QuotaCacheData::default();
+        let accounts = vec![account(Some("acct-1"), Some("a@x.com"))];
+        // Seed a stale email entry, then update: the id key wins and the email
+        // key is actively pruned.
+        let stale = QuotaCacheEntry {
+            updated_at: 1.0,
+            status: 200.0,
+            model: "gpt-5.5".to_string(),
+            plan_type: None,
+            primary: QuotaCacheWindow::default(),
+            secondary: QuotaCacheWindow::default(),
+        };
+        cache.by_email.insert("a@x.com".to_string(), stale);
+        let changed = update_quota_cache_for_account(
+            &mut cache,
+            &accounts[0],
+            &snapshot(200),
+            &accounts,
+            None,
+        );
+        assert!(changed);
+        assert!(cache.by_account_id.contains_key("acct-1"));
+        assert!(!cache.by_email.contains_key("a@x.com"));
+    }
+
+    #[test]
+    fn duplicate_account_ids_and_ambiguous_emails_write_nothing_but_prune() {
+        let mut cache = QuotaCacheData::default();
+        let accounts = vec![
+            account(Some("dup"), Some("a@x.com")),
+            account(Some("dup"), Some("a@x.com")),
+        ];
+        let changed = update_quota_cache_for_account(
+            &mut cache,
+            &accounts[0],
+            &snapshot(200),
+            &accounts,
+            None,
+        );
+        assert!(!changed);
+        assert!(cache.by_account_id.is_empty());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[test]
+    fn persisted_view_synthesizes_429_from_storage_reset_time() {
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", 5_000);
+        let accounts = vec![account(Some("acct-1"), Some("a@x.com"))];
+        let view = get_persisted_quota_view_for_account(
+            None,
+            &PersistedQuotaViewAccount {
+                account_id: Some("acct-1"),
+                email: Some("a@x.com"),
+                rate_limit_reset_times: Some(&times),
+            },
+            &accounts,
+            1_000,
+            None,
+        )
+        .expect("view");
+        assert_eq!(view.status, 429.0);
+        assert_eq!(view.model, DEFAULT_MODEL);
+        assert_eq!(view.updated_at, 1_000.0);
+        assert_eq!(view.primary.reset_at_ms, Some(5_000.0));
+    }
+
+    #[test]
+    fn persisted_view_keeps_cached_429_covering_the_persisted_reset() {
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", 5_000);
+        let mut cache = QuotaCacheData::default();
+        let cached = QuotaCacheEntry {
+            updated_at: 900.0,
+            status: 429.0,
+            model: "gpt-5.5".to_string(),
+            plan_type: None,
+            primary: QuotaCacheWindow {
+                used_percent: None,
+                window_minutes: None,
+                reset_at_ms: Some(9_000.0),
+            },
+            secondary: QuotaCacheWindow::default(),
+        };
+        cache.by_account_id.insert("acct-1".to_string(), cached.clone());
+        let accounts = vec![account(Some("acct-1"), Some("a@x.com"))];
+        let view = get_persisted_quota_view_for_account(
+            Some(&cache),
+            &PersistedQuotaViewAccount {
+                account_id: Some("acct-1"),
+                email: Some("a@x.com"),
+                rate_limit_reset_times: Some(&times),
+            },
+            &accounts,
+            1_000,
+            None,
+        )
+        .expect("view");
+        assert_eq!(view, cached);
+    }
+
+    #[test]
+    fn persisted_view_without_reset_time_returns_cached_entry() {
+        let accounts = vec![account(Some("acct-1"), None)];
+        let view = get_persisted_quota_view_for_account(
+            None,
+            &PersistedQuotaViewAccount {
+                account_id: Some("acct-1"),
+                email: None,
+                rate_limit_reset_times: None,
+            },
+            &accounts,
+            1_000,
+            None,
+        );
+        assert!(view.is_none());
+    }
+
+    #[test]
+    fn prune_removes_email_entry_without_safe_fallback() {
+        let mut cache = QuotaCacheData::default();
+        let entry = QuotaCacheEntry {
+            updated_at: 1.0,
+            status: 200.0,
+            model: "gpt-5.5".to_string(),
+            plan_type: None,
+            primary: QuotaCacheWindow::default(),
+            secondary: QuotaCacheWindow::default(),
+        };
+        cache.by_email.insert("a@x.com".to_string(), entry);
+        // Two accounts share the email: no safe fallback remains.
+        let accounts = vec![
+            account(Some("one"), Some("a@x.com")),
+            account(Some("two"), Some("a@x.com")),
+        ];
+        let state = build_quota_email_fallback_state(&accounts);
+        assert!(prune_unsafe_quota_email_cache_entry(
+            &mut cache,
+            Some("a@x.com"),
+            &accounts,
+            &state,
+        ));
+        assert!(!cache.by_email.contains_key("a@x.com"));
+        // Second prune is a no-op.
+        assert!(!prune_unsafe_quota_email_cache_entry(
+            &mut cache,
+            Some("a@x.com"),
+            &accounts,
+            &state,
+        ));
+    }
+
+    #[test]
+    fn prune_keeps_email_entry_with_safe_fallback() {
+        let mut cache = QuotaCacheData::default();
+        let entry = QuotaCacheEntry {
+            updated_at: 1.0,
+            status: 200.0,
+            model: "gpt-5.5".to_string(),
+            plan_type: None,
+            primary: QuotaCacheWindow::default(),
+            secondary: QuotaCacheWindow::default(),
+        };
+        cache.by_email.insert("a@x.com".to_string(), entry);
+        let accounts = vec![account(Some("one"), Some("a@x.com"))];
+        let state = build_quota_email_fallback_state(&accounts);
+        assert!(!prune_unsafe_quota_email_cache_entry(
+            &mut cache,
+            Some("a@x.com"),
+            &accounts,
+            &state,
+        ));
+        assert!(cache.by_email.contains_key("a@x.com"));
+    }
+}
diff --git a/crates/manager/src/rate_limit_markers.rs b/crates/manager/src/rate_limit_markers.rs
new file mode 100644
index 000000000..acdbc3edd
--- /dev/null
+++ b/crates/manager/src/rate_limit_markers.rs
@@ -0,0 +1,31 @@
+//! Port of `lib/codex-manager/rate-limit-markers.ts`.
+//!
+//! Behavior source: spec 08 §8 / spec 09 §4.4 — a status marker counts as
+//! "rate-limited" when it is exactly `"rate-limited"` or starts with the
+//! `"rate-limited:"` prefix (e.g. `"rate-limited:2h 5m"`).
+
+/// TS `isRateLimitedMarker(marker)`.
+pub fn is_rate_limited_marker(marker: &str) -> bool {
+    marker == "rate-limited" || marker.starts_with("rate-limited:")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn matches_bare_and_prefixed_markers() {
+        assert!(is_rate_limited_marker("rate-limited"));
+        assert!(is_rate_limited_marker("rate-limited:2h 5m"));
+        assert!(is_rate_limited_marker("rate-limited:"));
+    }
+
+    #[test]
+    fn rejects_other_markers() {
+        assert!(!is_rate_limited_marker("rate-limit"));
+        assert!(!is_rate_limited_marker("cooldown:rate-limited"));
+        assert!(!is_rate_limited_marker("quota-exhausted"));
+        assert!(!is_rate_limited_marker(""));
+        assert!(!is_rate_limited_marker("RATE-LIMITED"));
+    }
+}
diff --git a/crates/manager/src/registry.rs b/crates/manager/src/registry.rs
new file mode 100644
index 000000000..adac9aebc
--- /dev/null
+++ b/crates/manager/src/registry.rs
@@ -0,0 +1,79 @@
+//! Port of `lib/codex-manager/account-manager-commands.ts`.
+//!
+//! Canonical set of subcommands routed to the account-manager dispatcher.
+//! Kept in a small internal module (rather than exported from the CLI
+//! entrypoint) so both the dispatcher and the wrapper-routing alignment test
+//! consume the SAME source of truth (cli-manager-01/02).
+
+/// Exact TS `ACCOUNT_MANAGER_COMMANDS` set, in source order.
+///
+/// NOTE: spec 08 §2 header says "set of 28" but the TS source (authority)
+/// enumerates 29 entries; the TS set is ported verbatim.
+pub const ACCOUNT_MANAGER_COMMANDS: [&str; 29] = [
+    "login",
+    "list",
+    "status",
+    "switch",
+    "unpin",
+    "workspace",
+    "best",
+    "check",
+    "features",
+    "usage",
+    "verify-flagged",
+    "verify",
+    "forecast",
+    "report",
+    "fix",
+    "doctor",
+    "uninstall",
+    "account",
+    "budget",
+    "bridge",
+    "integrations",
+    "models",
+    "monitor",
+    "rotation",
+    "why-selected",
+    "history",
+    "config",
+    "init-config",
+    "debug",
+];
+
+/// TS `ACCOUNT_MANAGER_COMMANDS.has(command)`.
+pub fn is_account_manager_command(command: &str) -> bool {
+    ACCOUNT_MANAGER_COMMANDS.contains(&command)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn contains_every_ts_command_exactly_once() {
+        assert_eq!(ACCOUNT_MANAGER_COMMANDS.len(), 29);
+        let mut deduped: Vec<&str> = ACCOUNT_MANAGER_COMMANDS.to_vec();
+        deduped.sort_unstable();
+        deduped.dedup();
+        assert_eq!(deduped.len(), 29, "duplicate command in registry");
+    }
+
+    #[test]
+    fn membership_matches_ts_set() {
+        for command in [
+            "login",
+            "status",
+            "why-selected",
+            "verify-flagged",
+            "init-config",
+            "debug",
+        ] {
+            assert!(is_account_manager_command(command), "{command} missing");
+        }
+        assert!(!is_account_manager_command("auth"));
+        assert!(!is_account_manager_command(""));
+        assert!(!is_account_manager_command("Login"));
+        assert!(!is_account_manager_command("verify_flagged"));
+    }
+}
diff --git a/crates/manager/src/repair/doctor.rs b/crates/manager/src/repair/doctor.rs
new file mode 100644
index 000000000..5aa8213ad
--- /dev/null
+++ b/crates/manager/src/repair/doctor.rs
@@ -0,0 +1,1639 @@
+//! Port of `lib/codex-manager/repair-commands.ts` — the `doctor` command
+//! half (15 diagnostic checks + safe auto-fixes).
+//!
+//! Behavior source: spec 09 §3.5. CRITICAL contracts:
+//! - identities in check details are ALWAYS masked (`pr***@***.tld`,
+//!   `first4***last3`, `***`) — raw emails/account ids never print;
+//! - `--fix` applies only SAFE autofixes (index normalization, duplicate
+//!   token disable, email/accountId fill from token claims, all-disabled
+//!   rescue) — never deletes accounts;
+//! - the real write re-runs `applyDoctorFixes` INSIDE the transaction on
+//!   fresh disk state and re-locates the refreshed active account by
+//!   identity (clone → identity triple → clamped active index fallback);
+//! - a refreshed token is synced into Codex auth ONLY if it actually
+//!   persisted (`pendingCodexActiveSync && (!doctorRefreshMutation ||
+//!   storageFixChanged)`);
+//! - exit code is 1 when any check has `error` severity.
+
+use std::collections::{HashMap, HashSet};
+use std::path::Path;
+
+use cma_cli_mirror::writer::ActiveSelection;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::schemas::token::TokenResult;
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::forecast::{
+    ForecastAccountInput, ForecastAvailability, RuntimeForecastOverlay,
+    evaluate_forecast_accounts, recommend_forecast_account,
+};
+use cma_runtime::observability::RuntimeObservabilitySnapshot;
+use cma_storage::matching::{
+    AccountMatchOptions, AccountSelectionCandidate, find_matching_account_index,
+};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::login::account_credentials::{
+    apply_token_account_identity, has_likely_invalid_refresh_token, has_usable_access_token,
+};
+use crate::repair::fix::{
+    RepairDeps, codex_error_message, create_empty_account_storage, get_doctor_refresh_token_key,
+    has_placeholder_email, normalize_doctor_indexes,
+};
+
+// ============================================================================
+// Arg parsing
+// ============================================================================
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+struct DoctorCliOptions {
+    json: bool,
+    fix: bool,
+    dry_run: bool,
+}
+
+fn print_doctor_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth doctor [--json] [--fix] [--dry-run]",
+            "",
+            "Options:",
+            "  --json, -j         Print machine-readable JSON diagnostics",
+            "  --fix              Apply safe auto-fixes to storage",
+            "  --dry-run, -n      Preview --fix changes without writing storage",
+            "",
+            "Behavior:",
+            "  - Validates account storage readability",
+            "  - Checks active index consistency and account duplication",
+            "  - Flags placeholder/demo accounts and disabled-all scenarios",
+        ]
+        .join("\n"),
+    );
+}
+
+fn parse_doctor_args(args: &[String]) -> Result<DoctorCliOptions, String> {
+    let mut options = DoctorCliOptions {
+        json: false,
+        fix: false,
+        dry_run: false,
+    };
+    for arg in args {
+        match arg.as_str() {
+            "--json" | "-j" => options.json = true,
+            "--fix" => options.fix = true,
+            "--dry-run" | "-n" => options.dry_run = true,
+            other => return Err(format!("Unknown option: {other}")),
+        }
+    }
+    if options.dry_run && !options.fix {
+        return Err("--dry-run requires --fix".to_string());
+    }
+    Ok(options)
+}
+
+// ============================================================================
+// Check / action shapes
+// ============================================================================
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DoctorSeverity {
+    Ok,
+    Warn,
+    Error,
+}
+
+impl DoctorSeverity {
+    fn as_str(self) -> &'static str {
+        match self {
+            DoctorSeverity::Ok => "ok",
+            DoctorSeverity::Warn => "warn",
+            DoctorSeverity::Error => "error",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+struct DoctorCheck {
+    key: &'static str,
+    severity: DoctorSeverity,
+    message: String,
+    details: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct DoctorFixAction {
+    key: &'static str,
+    message: String,
+}
+
+struct DoctorRefreshMutation {
+    match_account: AccountMetadataV3,
+    access_token: String,
+    refresh_token: String,
+    expires_at: i64,
+    email: Option<String>,
+    account_id: Option<String>,
+}
+
+// ============================================================================
+// Masking helpers (privacy contract — identities in details are ALWAYS
+// masked)
+// ============================================================================
+
+fn mask_doctor_email(value: Option<&str>) -> Option<String> {
+    let value = value?;
+    if value.is_empty() {
+        return None;
+    }
+    let email = value.trim();
+    let Some(at_index) = email.find('@') else {
+        return Some("***@***".to_string());
+    };
+    let local = &email[..at_index];
+    let domain = &email[at_index + 1..];
+    let tld = domain.rsplit('.').next().unwrap_or("");
+    let prefix: String = local.chars().take(2).collect();
+    Some(format!("{prefix}***@***.{tld}"))
+}
+
+fn redact_doctor_identifier(value: Option<&str>) -> Option<String> {
+    let value = value?;
+    let identifier = value.trim();
+    if identifier.is_empty() {
+        return None;
+    }
+    if identifier.contains('@') {
+        return mask_doctor_email(Some(identifier));
+    }
+    let chars: Vec<char> = identifier.chars().collect();
+    if chars.len() <= 8 {
+        return Some("***".to_string());
+    }
+    let head: String = chars[..4].iter().collect();
+    let tail: String = chars[chars.len() - 3..].iter().collect();
+    Some(format!("{head}***{tail}"))
+}
+
+fn format_doctor_identity_summary(email: Option<&str>, account_id: Option<&str>) -> String {
+    let mut parts: Vec<String> = Vec::new();
+    if let Some(masked_email) = mask_doctor_email(email) {
+        parts.push(format!("email={masked_email}"));
+    }
+    if let Some(masked_account_id) = redact_doctor_identifier(account_id) {
+        parts.push(format!("accountId={masked_account_id}"));
+    }
+    if parts.is_empty() {
+        "unknown".to_string()
+    } else {
+        parts.join(", ")
+    }
+}
+
+// ============================================================================
+// applyDoctorFixes
+// ============================================================================
+
+/// TS `applyDoctorFixes(storage, deps)` — safe autofixes ONLY: normalize
+/// indexes, disable duplicate-token entries, fill email/accountId from token
+/// claims, all-disabled rescue, final re-normalize. Never deletes accounts.
+fn apply_doctor_fixes(storage: &mut AccountStorageV3) -> (bool, Vec<DoctorFixAction>) {
+    let mut changed = false;
+    let mut actions: Vec<DoctorFixAction> = Vec::new();
+    let record_active_index_action = |actions: &mut Vec<DoctorFixAction>| {
+        if actions.iter().any(|action| action.key == "active-index") {
+            return;
+        }
+        actions.push(DoctorFixAction {
+            key: "active-index",
+            message: "Normalized active account indexes".to_string(),
+        });
+    };
+
+    if normalize_doctor_indexes(storage) {
+        changed = true;
+        record_active_index_action(&mut actions);
+    }
+
+    let mut seen_refresh_tokens: HashMap<String, usize> = HashMap::new();
+    for i in 0..storage.accounts.len() {
+        let refresh_token = get_doctor_refresh_token_key(&storage.accounts[i].refresh_token);
+        if let Some(refresh_token) = refresh_token {
+            if let Some(existing_token_index) = seen_refresh_tokens.get(&refresh_token).copied() {
+                if storage.accounts[i].enabled != Some(false) {
+                    storage.accounts[i].enabled = Some(false);
+                    changed = true;
+                    actions.push(DoctorFixAction {
+                        key: "duplicate-refresh-token",
+                        message: format!(
+                            "Disabled duplicate token entry on account {} (kept account {})",
+                            i + 1,
+                            existing_token_index + 1
+                        ),
+                    });
+                }
+            } else {
+                seen_refresh_tokens.insert(refresh_token, i);
+            }
+        }
+
+        let token_email = sanitize_email(
+            extract_account_email(storage.accounts[i].access_token.as_deref(), None).as_deref(),
+        );
+        if let Some(token_email) = token_email
+            && (sanitize_email(storage.accounts[i].email.as_deref()).is_none()
+                || has_placeholder_email(storage.accounts[i].email.as_deref()))
+        {
+            storage.accounts[i].email = Some(token_email);
+            changed = true;
+            actions.push(DoctorFixAction {
+                key: "email-from-token",
+                message: format!("Updated account {} email from token claims", i + 1),
+            });
+        }
+
+        let token_account_id = extract_account_id(storage.accounts[i].access_token.as_deref());
+        if storage.accounts[i].account_id.is_none()
+            && let Some(token_account_id) = token_account_id
+        {
+            storage.accounts[i].account_id = Some(token_account_id);
+            storage.accounts[i].account_id_source =
+                Some(cma_core::schemas::account_storage::AccountIdSource::Token);
+            changed = true;
+            actions.push(DoctorFixAction {
+                key: "account-id-from-token",
+                message: format!("Filled missing accountId for account {}", i + 1),
+            });
+        }
+    }
+
+    let enabled_count = storage
+        .accounts
+        .iter()
+        .filter(|account| account.enabled != Some(false))
+        .count();
+    if !storage.accounts.is_empty() && enabled_count == 0 {
+        let index =
+            cma_runtime::account_status::resolve_active_index(storage, ModelFamily::Codex);
+        let candidate_index = if index < storage.accounts.len() { index } else { 0 };
+        if let Some(candidate) = storage.accounts.get_mut(candidate_index) {
+            candidate.enabled = Some(true);
+            changed = true;
+            actions.push(DoctorFixAction {
+                key: "enabled-accounts",
+                message: format!("Re-enabled account {} to avoid an all-disabled pool", index + 1),
+            });
+        }
+    }
+
+    if normalize_doctor_indexes(storage) {
+        changed = true;
+        record_active_index_action(&mut actions);
+    }
+
+    (changed, actions)
+}
+
+/// Persisted runtime-observability snapshot → forecast overlay (crate-shared
+/// copy of the forecast command's converter; string skip reasons only —
+/// `report` reuses it).
+pub(crate) fn snapshot_to_overlay(
+    snapshot: &RuntimeObservabilitySnapshot,
+) -> RuntimeForecastOverlay {
+    let string_map = |map: &serde_json::Map<String, Value>| -> HashMap<String, String> {
+        map.iter()
+            .filter_map(|(key, value)| value.as_str().map(|text| (key.clone(), text.to_string())))
+            .collect()
+    };
+    RuntimeForecastOverlay {
+        account_skip_reasons: string_map(&snapshot.account_skip_reasons),
+        last_pool_exhaustion_skip_reasons: string_map(&snapshot.last_pool_exhaustion_skip_reasons),
+        policy_blocked_indexes: snapshot
+            .policy_blocked_indexes
+            .iter()
+            .filter(|index| **index >= 0)
+            .map(|index| *index as usize)
+            .collect(),
+    }
+}
+
+// ============================================================================
+// runDoctor
+// ============================================================================
+
+/// Production entry (dispatcher wiring).
+pub async fn run_doctor(args: &[String], out: &mut CliOut) -> i32 {
+    run_doctor_with(args, &RepairDeps::default(), out).await
+}
+
+/// TS `runDoctor(args, deps)` — exit 1 when any `error`-severity check.
+pub async fn run_doctor_with(args: &[String], deps: &RepairDeps, out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_doctor_usage(out);
+        return 0;
+    }
+
+    let options = match parse_doctor_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_doctor_usage(out);
+            return 1;
+        }
+    };
+
+    cma_storage::facade::set_storage_path(None);
+    let storage_path = cma_storage::facade::get_storage_path();
+    let storage_file_exists = Path::new(&storage_path).exists();
+    let mut checks: Vec<DoctorCheck> = Vec::new();
+
+    checks.push(DoctorCheck {
+        key: "storage-file",
+        severity: if storage_file_exists {
+            DoctorSeverity::Ok
+        } else {
+            DoctorSeverity::Warn
+        },
+        message: if storage_file_exists {
+            "Account storage file found".to_string()
+        } else {
+            "Account storage file does not exist yet (first login pending)".to_string()
+        },
+        details: Some(storage_path.clone()),
+    });
+
+    if storage_file_exists {
+        match tokio::fs::metadata(&storage_path).await {
+            Ok(stat) => {
+                checks.push(DoctorCheck {
+                    key: "storage-readable",
+                    severity: if stat.len() > 0 {
+                        DoctorSeverity::Ok
+                    } else {
+                        DoctorSeverity::Warn
+                    },
+                    message: if stat.len() > 0 {
+                        "Storage file is readable".to_string()
+                    } else {
+                        "Storage file is empty".to_string()
+                    },
+                    details: Some(format!("{} bytes", stat.len())),
+                });
+            }
+            Err(error) => {
+                checks.push(DoctorCheck {
+                    key: "storage-readable",
+                    severity: DoctorSeverity::Error,
+                    message: "Unable to read storage file metadata".to_string(),
+                    details: Some(error.to_string()),
+                });
+            }
+        }
+    }
+
+    let codex_auth_path = cma_cli_mirror::state::get_codex_cli_auth_path();
+    let codex_config_path = cma_cli_mirror::state::get_codex_cli_config_path();
+    let codex_auth_file_exists = codex_auth_path.exists();
+    let codex_config_file_exists = codex_config_path.exists();
+    let mut codex_auth_email: Option<String> = None;
+    let mut codex_auth_account_id: Option<String> = None;
+
+    checks.push(DoctorCheck {
+        key: "codex-auth-file",
+        severity: if codex_auth_file_exists {
+            DoctorSeverity::Ok
+        } else {
+            DoctorSeverity::Warn
+        },
+        message: if codex_auth_file_exists {
+            "Codex auth file found".to_string()
+        } else {
+            "Codex auth file does not exist".to_string()
+        },
+        details: Some(codex_auth_path.to_string_lossy().into_owned()),
+    });
+
+    if codex_auth_file_exists {
+        match tokio::fs::read_to_string(&codex_auth_path).await {
+            Ok(raw) => match serde_json::from_str::<Value>(&raw) {
+                Ok(parsed) if parsed.is_object() => {
+                    let payload = parsed.as_object().expect("object");
+                    let tokens = payload.get("tokens").and_then(Value::as_object);
+                    let access_token = tokens
+                        .and_then(|tokens| tokens.get("access_token"))
+                        .and_then(Value::as_str);
+                    let id_token = tokens
+                        .and_then(|tokens| tokens.get("id_token"))
+                        .and_then(Value::as_str);
+                    let account_id_from_file = tokens
+                        .and_then(|tokens| tokens.get("account_id"))
+                        .and_then(Value::as_str);
+                    let email_from_file = payload.get("email").and_then(Value::as_str);
+                    codex_auth_email = sanitize_email(
+                        email_from_file
+                            .map(str::to_string)
+                            .or_else(|| extract_account_email(access_token, id_token))
+                            .as_deref(),
+                    );
+                    codex_auth_account_id = account_id_from_file
+                        .map(str::to_string)
+                        .or_else(|| extract_account_id(access_token));
+                    checks.push(DoctorCheck {
+                        key: "codex-auth-readable",
+                        severity: DoctorSeverity::Ok,
+                        message: "Codex auth file is readable".to_string(),
+                        details: if codex_auth_email.is_some() || codex_auth_account_id.is_some()
+                        {
+                            Some(format_doctor_identity_summary(
+                                codex_auth_email.as_deref(),
+                                codex_auth_account_id.as_deref(),
+                            ))
+                        } else {
+                            None
+                        },
+                    });
+                }
+                Ok(_) => {
+                    checks.push(DoctorCheck {
+                        key: "codex-auth-readable",
+                        severity: DoctorSeverity::Error,
+                        message: "Codex auth file has invalid structure".to_string(),
+                        details: Some(codex_auth_path.to_string_lossy().into_owned()),
+                    });
+                }
+                Err(error) => {
+                    checks.push(DoctorCheck {
+                        key: "codex-auth-readable",
+                        severity: DoctorSeverity::Error,
+                        message: "Unable to read Codex auth file".to_string(),
+                        details: Some(error.to_string()),
+                    });
+                }
+            },
+            Err(error) => {
+                checks.push(DoctorCheck {
+                    key: "codex-auth-readable",
+                    severity: DoctorSeverity::Error,
+                    message: "Unable to read Codex auth file".to_string(),
+                    details: Some(error.to_string()),
+                });
+            }
+        }
+    }
+
+    checks.push(DoctorCheck {
+        key: "codex-config-file",
+        severity: if codex_config_file_exists {
+            DoctorSeverity::Ok
+        } else {
+            DoctorSeverity::Warn
+        },
+        message: if codex_config_file_exists {
+            "Codex config file found".to_string()
+        } else {
+            "Codex config file does not exist".to_string()
+        },
+        details: Some(codex_config_path.to_string_lossy().into_owned()),
+    });
+
+    let mut codex_auth_store_mode: Option<String> = None;
+    if codex_config_file_exists {
+        match tokio::fs::read_to_string(&codex_config_path).await {
+            Ok(config_raw) => {
+                // Hand-rolled `/^\s*cli_auth_credentials_store\s*=\s*"([^"]+)"\s*$/m`
+                // (first matching line wins).
+                for line in config_raw.split('\n') {
+                    if let Some(value) = match_auth_store_line(line) {
+                        codex_auth_store_mode = Some(value.trim().to_string());
+                        break;
+                    }
+                }
+            }
+            Err(error) => {
+                checks.push(DoctorCheck {
+                    key: "codex-auth-store",
+                    severity: DoctorSeverity::Warn,
+                    message: "Unable to read Codex auth-store config".to_string(),
+                    details: Some(error.to_string()),
+                });
+            }
+        }
+    }
+    if !checks.iter().any(|check| check.key == "codex-auth-store") {
+        let is_file_mode = codex_auth_store_mode.as_deref() == Some("file");
+        checks.push(DoctorCheck {
+            key: "codex-auth-store",
+            severity: if is_file_mode {
+                DoctorSeverity::Ok
+            } else {
+                DoctorSeverity::Warn
+            },
+            message: if is_file_mode {
+                "Codex auth storage is set to file".to_string()
+            } else {
+                "Codex auth storage is not explicitly set to file".to_string()
+            },
+            details: Some(match &codex_auth_store_mode {
+                Some(mode) => format!("mode={mode}"),
+                None => "mode=unset".to_string(),
+            }),
+        });
+    }
+
+    let codex_cli_state = (deps.load_codex_cli_state)(true).await;
+    checks.push(DoctorCheck {
+        key: "codex-cli-state",
+        severity: if codex_cli_state.is_some() {
+            DoctorSeverity::Ok
+        } else {
+            DoctorSeverity::Warn
+        },
+        message: if codex_cli_state.is_some() {
+            "Codex CLI state loaded".to_string()
+        } else {
+            "Codex CLI state unavailable".to_string()
+        },
+        details: codex_cli_state
+            .as_ref()
+            .map(|state| state.path.to_string_lossy().into_owned()),
+    });
+
+    let loaded_storage = (deps.load_accounts)().await;
+    let mut storage_for_checks: Option<AccountStorageV3> = loaded_storage.clone();
+    let mut fix_changed = false;
+    let mut storage_fix_changed = false;
+    let mut structural_fix_actions: Vec<DoctorFixAction> = Vec::new();
+    let mut supplemental_fix_actions: Vec<DoctorFixAction> = Vec::new();
+    let mut doctor_refresh_mutation: Option<DoctorRefreshMutation> = None;
+    let mut pending_codex_active_sync: Option<ActiveSelection> = None;
+
+    if options.fix
+        && let Some(storage) = &mut storage_for_checks
+        && !storage.accounts.is_empty()
+    {
+        let (fixed_changed, fixed_actions) = apply_doctor_fixes(storage);
+        storage_fix_changed = fixed_changed;
+        structural_fix_actions = fixed_actions;
+    }
+
+    let has_accounts = storage_for_checks
+        .as_ref()
+        .is_some_and(|storage| !storage.accounts.is_empty());
+    if !has_accounts {
+        checks.push(DoctorCheck {
+            key: "accounts",
+            severity: DoctorSeverity::Warn,
+            message: "No accounts configured".to_string(),
+            details: None,
+        });
+    } else {
+        let storage_ref = storage_for_checks.as_ref().expect("storage present");
+        checks.push(DoctorCheck {
+            key: "accounts",
+            severity: DoctorSeverity::Ok,
+            message: format!("Loaded {} account(s)", storage_ref.accounts.len()),
+            details: None,
+        });
+
+        let active_index =
+            cma_runtime::account_status::resolve_active_index(storage_ref, ModelFamily::Codex);
+        let active_exists = active_index < storage_ref.accounts.len();
+        checks.push(DoctorCheck {
+            key: "active-index",
+            severity: if active_exists {
+                DoctorSeverity::Ok
+            } else {
+                DoctorSeverity::Error
+            },
+            message: if active_exists {
+                format!("Active index is valid ({})", active_index + 1)
+            } else {
+                "Active index is out of range".to_string()
+            },
+            details: None,
+        });
+
+        let disabled_count = storage_ref
+            .accounts
+            .iter()
+            .filter(|account| account.enabled == Some(false))
+            .count();
+        let all_disabled = disabled_count >= storage_ref.accounts.len();
+        checks.push(DoctorCheck {
+            key: "enabled-accounts",
+            severity: if all_disabled {
+                DoctorSeverity::Error
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if all_disabled {
+                "All accounts are disabled".to_string()
+            } else {
+                format!(
+                    "{} enabled / {} disabled",
+                    storage_ref.accounts.len() - disabled_count,
+                    disabled_count
+                )
+            },
+            details: None,
+        });
+
+        let mut seen_refresh_tokens: HashSet<String> = HashSet::new();
+        let mut duplicate_token_count = 0usize;
+        for account in &storage_ref.accounts {
+            let Some(token) = get_doctor_refresh_token_key(&account.refresh_token) else {
+                continue;
+            };
+            if !seen_refresh_tokens.insert(token) {
+                duplicate_token_count += 1;
+            }
+        }
+        checks.push(DoctorCheck {
+            key: "duplicate-refresh-token",
+            severity: if duplicate_token_count > 0 {
+                DoctorSeverity::Warn
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if duplicate_token_count > 0 {
+                format!(
+                    "Detected {} duplicate refresh token entr{}",
+                    duplicate_token_count,
+                    if duplicate_token_count == 1 { "y" } else { "ies" }
+                )
+            } else {
+                "No duplicate refresh tokens detected".to_string()
+            },
+            details: None,
+        });
+
+        let mut seen_emails: HashSet<String> = HashSet::new();
+        let mut duplicate_email_count = 0usize;
+        let mut placeholder_email_count = 0usize;
+        let mut likely_invalid_refresh_token_count = 0usize;
+        for account in &storage_ref.accounts {
+            if has_likely_invalid_refresh_token(Some(&account.refresh_token)) {
+                likely_invalid_refresh_token_count += 1;
+            }
+            let Some(email) = sanitize_email(account.email.as_deref()) else {
+                continue;
+            };
+            if seen_emails.contains(&email) {
+                duplicate_email_count += 1;
+            }
+            seen_emails.insert(email.clone());
+            if has_placeholder_email(Some(&email)) {
+                placeholder_email_count += 1;
+            }
+        }
+        checks.push(DoctorCheck {
+            key: "duplicate-email",
+            severity: if duplicate_email_count > 0 {
+                DoctorSeverity::Warn
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if duplicate_email_count > 0 {
+                format!(
+                    "Detected {} duplicate email entr{}",
+                    duplicate_email_count,
+                    if duplicate_email_count == 1 { "y" } else { "ies" }
+                )
+            } else {
+                "No duplicate emails detected".to_string()
+            },
+            details: None,
+        });
+        checks.push(DoctorCheck {
+            key: "placeholder-email",
+            severity: if placeholder_email_count > 0 {
+                DoctorSeverity::Warn
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if placeholder_email_count > 0 {
+                format!("{placeholder_email_count} account(s) appear to be placeholder/demo entries")
+            } else {
+                "No placeholder emails detected".to_string()
+            },
+            details: None,
+        });
+        checks.push(DoctorCheck {
+            key: "refresh-token-shape",
+            severity: if likely_invalid_refresh_token_count > 0 {
+                DoctorSeverity::Warn
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if likely_invalid_refresh_token_count > 0 {
+                format!(
+                    "{likely_invalid_refresh_token_count} account(s) have likely invalid refresh token format"
+                )
+            } else {
+                "Refresh token format looks normal".to_string()
+            },
+            details: None,
+        });
+
+        let now = deps.now();
+        let runtime_snapshot = (deps.load_runtime_observability_snapshot)().await;
+        let runtime_overlay = runtime_snapshot.as_ref().map(snapshot_to_overlay);
+        let quota_cache = (deps.load_quota_cache)().await;
+        let forecast_inputs: Vec<ForecastAccountInput<'_>> = storage_ref
+            .accounts
+            .iter()
+            .enumerate()
+            .map(|(index, account)| ForecastAccountInput {
+                index,
+                account,
+                is_current: index == active_index,
+                now,
+                refresh_failure: None,
+                live_quota: None,
+                quota_cache: Some(&quota_cache),
+                all_accounts: Some(&storage_ref.accounts),
+                runtime_overlay: None,
+            })
+            .collect();
+        let forecast_results = evaluate_forecast_accounts(&forecast_inputs);
+        let runtime_forecast_inputs: Vec<ForecastAccountInput<'_>> = storage_ref
+            .accounts
+            .iter()
+            .enumerate()
+            .map(|(index, account)| ForecastAccountInput {
+                index,
+                account,
+                is_current: index == active_index,
+                now,
+                refresh_failure: None,
+                live_quota: None,
+                quota_cache: Some(&quota_cache),
+                all_accounts: Some(&storage_ref.accounts),
+                runtime_overlay: runtime_overlay.as_ref(),
+            })
+            .collect();
+        let runtime_forecast_results = evaluate_forecast_accounts(&runtime_forecast_inputs);
+        drop(forecast_inputs);
+        drop(runtime_forecast_inputs);
+        let recommendation = recommend_forecast_account(&forecast_results);
+        match recommendation.recommended_index {
+            Some(recommended_index) if recommended_index != active_index => {
+                checks.push(DoctorCheck {
+                    key: "recommended-switch",
+                    severity: DoctorSeverity::Warn,
+                    message: format!(
+                        "A healthier account is available: switch to {}",
+                        recommended_index + 1
+                    ),
+                    details: Some(recommendation.reason.clone()),
+                });
+            }
+            _ => {
+                checks.push(DoctorCheck {
+                    key: "recommended-switch",
+                    severity: DoctorSeverity::Ok,
+                    message: "Current account aligns with forecast recommendation".to_string(),
+                    details: None,
+                });
+            }
+        }
+
+        let divergent: Vec<usize> = forecast_results
+            .iter()
+            .filter(|result| {
+                result.availability == ForecastAvailability::Ready
+                    && runtime_forecast_results
+                        .get(result.index)
+                        .is_some_and(|runtime_result| {
+                            runtime_result.availability == ForecastAvailability::Unavailable
+                        })
+            })
+            .map(|result| result.index)
+            .collect();
+        checks.push(DoctorCheck {
+            key: "forecast-runtime-alignment",
+            severity: if divergent.is_empty() {
+                DoctorSeverity::Ok
+            } else {
+                DoctorSeverity::Warn
+            },
+            message: if divergent.is_empty() {
+                "Forecast and runtime availability are aligned".to_string()
+            } else {
+                format!(
+                    "{} account(s) look ready on disk but unavailable in runtime state",
+                    divergent.len()
+                )
+            },
+            details: if divergent.is_empty() {
+                None
+            } else {
+                Some(
+                    divergent
+                        .iter()
+                        .map(|index| {
+                            let reasons = runtime_forecast_results
+                                .get(*index)
+                                .map(|result| result.reasons.join("; "))
+                                .unwrap_or_default();
+                            format!(
+                                "account {}: {}",
+                                index + 1,
+                                if reasons.is_empty() {
+                                    "runtime unavailable".to_string()
+                                } else {
+                                    reasons
+                                }
+                            )
+                        })
+                        .collect::<Vec<_>>()
+                        .join(" | "),
+                )
+            },
+        });
+
+        if active_exists {
+            let manager_active_email = sanitize_email(
+                storage_ref.accounts[active_index].email.as_deref(),
+            );
+            let manager_active_account_id =
+                storage_ref.accounts[active_index].account_id.clone();
+            let codex_active_email = codex_cli_state
+                .as_ref()
+                .and_then(|state| sanitize_email(state.active_email.as_deref()))
+                .or_else(|| codex_auth_email.clone());
+            let codex_active_account_id = codex_cli_state
+                .as_ref()
+                .and_then(|state| state.active_account_id.clone())
+                .or_else(|| codex_auth_account_id.clone());
+            let is_email_mismatch = manager_active_email.is_some()
+                && codex_active_email.is_some()
+                && manager_active_email != codex_active_email;
+            let is_account_id_mismatch = manager_active_account_id.is_some()
+                && codex_active_account_id.is_some()
+                && manager_active_account_id != codex_active_account_id;
+
+            checks.push(DoctorCheck {
+                key: "active-selection-sync",
+                severity: if is_email_mismatch || is_account_id_mismatch {
+                    DoctorSeverity::Warn
+                } else {
+                    DoctorSeverity::Ok
+                },
+                message: if is_email_mismatch || is_account_id_mismatch {
+                    "Manager active account and Codex active account are not aligned".to_string()
+                } else {
+                    "Manager active account and Codex active account are aligned".to_string()
+                },
+                details: Some(format!(
+                    "manager={} | codex={}",
+                    format_doctor_identity_summary(
+                        manager_active_email.as_deref(),
+                        manager_active_account_id.as_deref()
+                    ),
+                    format_doctor_identity_summary(
+                        codex_active_email.as_deref(),
+                        codex_active_account_id.as_deref()
+                    )
+                )),
+            });
+
+            if options.fix {
+                let storage_mut = storage_for_checks.as_mut().expect("storage present");
+                let active_account_match = storage_mut.accounts[active_index].clone();
+                let mut sync_access_token =
+                    storage_mut.accounts[active_index].access_token.clone();
+                let mut sync_refresh_token =
+                    storage_mut.accounts[active_index].refresh_token.clone();
+                let mut sync_expires_at = storage_mut.accounts[active_index].expires_at;
+                let mut sync_id_token: Option<String> = None;
+                let mut can_sync_active_account =
+                    has_usable_access_token(&storage_mut.accounts[active_index], now);
+
+                if !can_sync_active_account {
+                    if options.dry_run {
+                        supplemental_fix_actions.push(DoctorFixAction {
+                            key: "doctor-refresh",
+                            message: format!(
+                                "Prepared active-account token refresh for account {} (dry-run)",
+                                active_index + 1
+                            ),
+                        });
+                    } else {
+                        let refresh_result = (deps.queued_refresh)(
+                            storage_mut.accounts[active_index].refresh_token.clone(),
+                        )
+                        .await;
+                        match refresh_result {
+                            TokenResult::Success(success) => {
+                                let refreshed_email = sanitize_email(
+                                    extract_account_email(
+                                        Some(&success.access),
+                                        success.id_token.as_deref(),
+                                    )
+                                    .as_deref(),
+                                );
+                                let refreshed_account_id =
+                                    extract_account_id(Some(&success.access));
+                                let active_account = &mut storage_mut.accounts[active_index];
+                                active_account.access_token = Some(success.access.clone());
+                                active_account.refresh_token = success.refresh.clone();
+                                active_account.expires_at = Some(success.expires);
+                                if let Some(refreshed_email_value) = &refreshed_email {
+                                    active_account.email = Some(refreshed_email_value.clone());
+                                }
+                                apply_token_account_identity(
+                                    active_account,
+                                    refreshed_account_id.as_deref(),
+                                );
+                                doctor_refresh_mutation = Some(DoctorRefreshMutation {
+                                    match_account: active_account_match.clone(),
+                                    access_token: success.access.clone(),
+                                    refresh_token: success.refresh.clone(),
+                                    expires_at: success.expires,
+                                    email: refreshed_email,
+                                    account_id: refreshed_account_id,
+                                });
+                                sync_access_token = Some(success.access.clone());
+                                sync_refresh_token = success.refresh.clone();
+                                sync_expires_at = Some(success.expires);
+                                sync_id_token = success.id_token.clone();
+                                can_sync_active_account = true;
+                                storage_fix_changed = true;
+                                fix_changed = true;
+                                supplemental_fix_actions.push(DoctorFixAction {
+                                    key: "doctor-refresh",
+                                    message: format!(
+                                        "Refreshed active account tokens for account {}",
+                                        active_index + 1
+                                    ),
+                                });
+                            }
+                            TokenResult::Failed(failure) => {
+                                checks.push(DoctorCheck {
+                                    key: "doctor-refresh",
+                                    severity: DoctorSeverity::Warn,
+                                    message:
+                                        "Unable to refresh active account before Codex sync"
+                                            .to_string(),
+                                    details: Some(
+                                        crate::formatters::text_style::normalize_failure_detail(
+                                            failure.message.as_deref(),
+                                            failure.reason.map(|reason| reason.as_str()),
+                                        ),
+                                    ),
+                                });
+                            }
+                        }
+                    }
+                }
+
+                if !options.dry_run && can_sync_active_account {
+                    let active_account = &storage_mut.accounts[active_index];
+                    pending_codex_active_sync = Some(ActiveSelection {
+                        account_id: active_account.account_id.clone(),
+                        email: active_account.email.clone(),
+                        access_token: sync_access_token,
+                        refresh_token: Some(sync_refresh_token),
+                        expires_at: sync_expires_at.map(|value| value as f64),
+                        id_token: sync_id_token,
+                    });
+                } else if options.dry_run && can_sync_active_account {
+                    supplemental_fix_actions.push(DoctorFixAction {
+                        key: "codex-active-sync",
+                        message: "Prepared Codex active-account sync (dry-run)".to_string(),
+                    });
+                }
+            }
+        }
+    }
+
+    if options.fix && has_accounts && storage_fix_changed && !options.dry_run {
+        let structural_ref = &mut structural_fix_actions;
+        let storage_fix_changed_ref = &mut storage_fix_changed;
+        let refresh_mutation_ref = &doctor_refresh_mutation;
+        let transaction_result = cma_storage::transactions::with_account_storage_transaction(
+            move |loaded_storage, persist| async move {
+                let mut next_storage =
+                    loaded_storage.unwrap_or_else(create_empty_account_storage);
+                let (transaction_fixed_changed, transaction_fixed_actions) =
+                    apply_doctor_fixes(&mut next_storage);
+                *structural_ref = transaction_fixed_actions;
+                let mut transaction_changed = transaction_fixed_changed;
+                if let Some(mutation) = refresh_mutation_ref {
+                    let fallback_active_index = cma_runtime::account_status::resolve_active_index(
+                        &next_storage,
+                        ModelFamily::Codex,
+                    );
+                    let fallback_target_index =
+                        if fallback_active_index < next_storage.accounts.len() {
+                            Some(fallback_active_index)
+                        } else {
+                            None
+                        };
+                    let options = AccountMatchOptions {
+                        allow_unique_account_id_fallback_without_email: true,
+                    };
+                    let target_index = find_matching_account_index(
+                        &next_storage.accounts,
+                        &mutation.match_account,
+                        options,
+                    )
+                    .or_else(|| {
+                        find_matching_account_index(
+                            &next_storage.accounts,
+                            &AccountSelectionCandidate {
+                                account_id: mutation.account_id.clone(),
+                                email: mutation.email.clone(),
+                                refresh_token: Some(mutation.refresh_token.clone()),
+                            },
+                            options,
+                        )
+                    })
+                    .or(fallback_target_index);
+                    if let Some(target_index) = target_index
+                        && let Some(target) = next_storage.accounts.get_mut(target_index)
+                    {
+                        if target.access_token.as_deref() != Some(mutation.access_token.as_str())
+                        {
+                            target.access_token = Some(mutation.access_token.clone());
+                            transaction_changed = true;
+                        }
+                        if target.refresh_token != mutation.refresh_token {
+                            target.refresh_token = mutation.refresh_token.clone();
+                            transaction_changed = true;
+                        }
+                        if target.expires_at != Some(mutation.expires_at) {
+                            target.expires_at = Some(mutation.expires_at);
+                            transaction_changed = true;
+                        }
+                        if let Some(email) = &mutation.email
+                            && target.email.as_ref() != Some(email)
+                        {
+                            target.email = Some(email.clone());
+                            transaction_changed = true;
+                        }
+                        if apply_token_account_identity(target, mutation.account_id.as_deref()) {
+                            transaction_changed = true;
+                        }
+                    }
+                }
+                if normalize_doctor_indexes(&mut next_storage) {
+                    transaction_changed = true;
+                }
+                if !transaction_changed {
+                    structural_ref.clear();
+                    *storage_fix_changed_ref = false;
+                    return Ok(());
+                }
+                *storage_fix_changed_ref = true;
+                persist.persist(&next_storage).await
+            },
+        )
+        .await;
+        if let Err(error) = transaction_result {
+            // TS lets the transaction rejection propagate; the Rust surface
+            // reports it and exits 1.
+            out.error(codex_error_message(&error));
+            return 1;
+        }
+    }
+
+    // A refreshed token is only synced into Codex auth if it actually
+    // persisted.
+    if let Some(pending_sync) = pending_codex_active_sync
+        && (doctor_refresh_mutation.is_none() || storage_fix_changed)
+    {
+        let synced = (deps.set_codex_cli_active_selection)(pending_sync).await;
+        if synced {
+            supplemental_fix_actions.push(DoctorFixAction {
+                key: "codex-active-sync",
+                message: "Synced manager active account into Codex auth state".to_string(),
+            });
+        } else {
+            checks.push(DoctorCheck {
+                key: "codex-active-sync",
+                severity: DoctorSeverity::Warn,
+                message: "Failed to sync manager active account into Codex auth state"
+                    .to_string(),
+                details: None,
+            });
+        }
+    }
+
+    let fix_actions: Vec<DoctorFixAction> = structural_fix_actions
+        .iter()
+        .chain(supplemental_fix_actions.iter())
+        .cloned()
+        .collect();
+
+    if options.fix && has_accounts {
+        fix_changed = storage_fix_changed || !fix_actions.is_empty();
+        checks.push(DoctorCheck {
+            key: "auto-fix",
+            severity: if fix_changed {
+                DoctorSeverity::Warn
+            } else {
+                DoctorSeverity::Ok
+            },
+            message: if fix_changed {
+                if options.dry_run {
+                    format!("Prepared {} fix(es) (dry-run)", fix_actions.len())
+                } else {
+                    format!("Applied {} fix(es)", fix_actions.len())
+                }
+            } else {
+                "No safe auto-fixes needed".to_string()
+            },
+            details: None,
+        });
+    }
+
+    let mut summary_ok = 0usize;
+    let mut summary_warn = 0usize;
+    let mut summary_error = 0usize;
+    for check in &checks {
+        match check.severity {
+            DoctorSeverity::Ok => summary_ok += 1,
+            DoctorSeverity::Warn => summary_warn += 1,
+            DoctorSeverity::Error => summary_error += 1,
+        }
+    }
+
+    if options.json {
+        let mut payload = Map::new();
+        payload.insert("command".into(), Value::from("doctor"));
+        payload.insert("storagePath".into(), Value::from(storage_path.clone()));
+        let mut summary = Map::new();
+        summary.insert("ok".into(), Value::from(summary_ok as i64));
+        summary.insert("warn".into(), Value::from(summary_warn as i64));
+        summary.insert("error".into(), Value::from(summary_error as i64));
+        payload.insert("summary".into(), Value::Object(summary));
+        payload.insert(
+            "checks".into(),
+            Value::Array(
+                checks
+                    .iter()
+                    .map(|check| {
+                        let mut row = Map::new();
+                        row.insert("key".into(), Value::from(check.key));
+                        row.insert("severity".into(), Value::from(check.severity.as_str()));
+                        row.insert("message".into(), Value::from(check.message.clone()));
+                        if let Some(details) = &check.details {
+                            row.insert("details".into(), Value::from(details.clone()));
+                        }
+                        Value::Object(row)
+                    })
+                    .collect(),
+            ),
+        );
+        let mut fix = Map::new();
+        fix.insert("enabled".into(), Value::from(options.fix));
+        fix.insert("dryRun".into(), Value::from(options.dry_run));
+        fix.insert("changed".into(), Value::from(fix_changed));
+        fix.insert(
+            "actions".into(),
+            Value::Array(
+                fix_actions
+                    .iter()
+                    .map(|action| {
+                        let mut row = Map::new();
+                        row.insert("key".into(), Value::from(action.key));
+                        row.insert("message".into(), Value::from(action.message.clone()));
+                        Value::Object(row)
+                    })
+                    .collect(),
+            ),
+        );
+        payload.insert("fix".into(), Value::Object(fix));
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return if summary_error > 0 { 1 } else { 0 };
+    }
+
+    out.info("Doctor diagnostics");
+    out.info(format!("Storage: {storage_path}"));
+    out.info(format!(
+        "Summary: {summary_ok} ok, {summary_warn} warnings, {summary_error} errors"
+    ));
+    out.info("");
+    for check in &checks {
+        let marker = match check.severity {
+            DoctorSeverity::Ok => "✓",
+            DoctorSeverity::Warn => "!",
+            DoctorSeverity::Error => "✗",
+        };
+        out.info(format!("{marker} {}: {}", check.key, check.message));
+        if let Some(details) = &check.details {
+            out.info(format!("  {details}"));
+        }
+    }
+    if options.fix {
+        out.info("");
+        if !fix_actions.is_empty() {
+            out.info(format!(
+                "Auto-fix actions ({}):",
+                if options.dry_run { "dry-run" } else { "applied" }
+            ));
+            for action in &fix_actions {
+                out.info(format!("  - {}", action.message));
+            }
+        } else {
+            out.info("Auto-fix actions: none");
+        }
+    }
+
+    if summary_error > 0 { 1 } else { 0 }
+}
+
+/// Hand-rolled `/^\s*cli_auth_credentials_store\s*=\s*"([^"]+)"\s*$/m` line
+/// matcher (the `regex` crate is not a cma-manager dependency).
+fn match_auth_store_line(line: &str) -> Option<&str> {
+    let rest = line.trim_start();
+    let rest = rest.strip_prefix("cli_auth_credentials_store")?;
+    let rest = rest.trim_start();
+    let rest = rest.strip_prefix('=')?;
+    let rest = rest.trim_start();
+    let rest = rest.strip_prefix('"')?;
+    let end = rest.find('"')?;
+    if end == 0 {
+        // `([^"]+)` requires at least one character.
+        return None;
+    }
+    let value = &rest[..end];
+    let trailing = &rest[end + 1..];
+    if !trailing.chars().all(char::is_whitespace) {
+        return None;
+    }
+    Some(value)
+}
+
+// ============================================================================
+// Tests — ported from test/repair-commands.test.ts (doctor half)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenFailure;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn account(refresh: &str, email: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        account
+    }
+
+    fn base64url(data: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut encoded = String::new();
+        for chunk in data.chunks(3) {
+            let bytes = [
+                chunk[0],
+                chunk.get(1).copied().unwrap_or(0),
+                chunk.get(2).copied().unwrap_or(0),
+            ];
+            let n = (u32::from(bytes[0]) << 16) | (u32::from(bytes[1]) << 8) | u32::from(bytes[2]);
+            encoded.push(ALPHABET[(n >> 18) as usize & 63] as char);
+            encoded.push(ALPHABET[(n >> 12) as usize & 63] as char);
+            if chunk.len() > 1 {
+                encoded.push(ALPHABET[(n >> 6) as usize & 63] as char);
+            }
+            if chunk.len() > 2 {
+                encoded.push(ALPHABET[n as usize & 63] as char);
+            }
+        }
+        encoded
+    }
+
+    /// Unsigned JWT whose payload carries the OpenAI email + accountId
+    /// claims (`decode_jwt` never verifies signatures).
+    fn claims_jwt(email: &str, account_id: &str) -> String {
+        let header = serde_json::json!({ "alg": "none" });
+        let payload = serde_json::json!({
+            "email": email,
+            cma_core::constants::JWT_CLAIM_PATH: {
+                "chatgpt_account_id": account_id,
+                "email": email,
+            },
+        });
+        format!(
+            "{}.{}.sig",
+            base64url(header.to_string().as_bytes()),
+            base64url(payload.to_string().as_bytes())
+        )
+    }
+
+    fn quiet_deps() -> RepairDeps {
+        RepairDeps {
+            queued_refresh: Box::new(|_| {
+                Box::pin(async {
+                    TokenResult::Failed(TokenFailure {
+                        reason: None,
+                        status_code: Some(401),
+                        message: Some("nope".to_string()),
+                    })
+                })
+            }),
+            load_codex_cli_state: Box::new(|_| Box::pin(async { None })),
+            set_codex_cli_active_selection: Box::new(|_| Box::pin(async { false })),
+            load_runtime_observability_snapshot: Box::new(|| Box::pin(async { None })),
+            get_now: Some(Box::new(|| 1_000)),
+            ..RepairDeps::default()
+        }
+    }
+
+    fn find_check<'a>(payload: &'a Value, key: &str) -> &'a Value {
+        payload["checks"]
+            .as_array()
+            .expect("checks array")
+            .iter()
+            .find(|check| check["key"] == key)
+            .unwrap_or_else(|| panic!("missing check {key}"))
+    }
+
+    #[test]
+    fn doctor_masking_helpers_never_leak_identities() {
+        assert_eq!(
+            mask_doctor_email(Some("primary@example.com")).as_deref(),
+            Some("pr***@***.com")
+        );
+        assert_eq!(mask_doctor_email(Some("no-at-sign")).as_deref(), Some("***@***"));
+        assert_eq!(mask_doctor_email(None), None);
+        assert_eq!(redact_doctor_identifier(Some("short")), Some("***".to_string()));
+        assert_eq!(
+            redact_doctor_identifier(Some("acct_1234567890")).as_deref(),
+            Some("acct***890")
+        );
+        assert_eq!(
+            redact_doctor_identifier(Some("user@site.org")).as_deref(),
+            Some("us***@***.org")
+        );
+        assert_eq!(redact_doctor_identifier(Some("   ")), None);
+        assert_eq!(
+            format_doctor_identity_summary(None, None),
+            "unknown".to_string()
+        );
+    }
+
+    #[test]
+    fn auth_store_line_matcher_mirrors_the_regex() {
+        assert_eq!(
+            match_auth_store_line("cli_auth_credentials_store = \"file\""),
+            Some("file")
+        );
+        assert_eq!(
+            match_auth_store_line("  cli_auth_credentials_store=\"keyring\"  "),
+            Some("keyring")
+        );
+        assert_eq!(
+            match_auth_store_line("cli_auth_credentials_store = \"file\"\r"),
+            Some("file")
+        );
+        assert_eq!(match_auth_store_line("cli_auth_credentials_store = \"\""), None);
+        assert_eq!(
+            match_auth_store_line("# cli_auth_credentials_store = \"file\""),
+            None
+        );
+        assert_eq!(
+            match_auth_store_line("cli_auth_credentials_store = \"file\" # trailing"),
+            None
+        );
+    }
+
+    #[test]
+    fn dry_run_requires_fix() {
+        assert_eq!(
+            parse_doctor_args(&args(&["--dry-run"])),
+            Err("--dry-run requires --fix".to_string())
+        );
+        let options = parse_doctor_args(&args(&["--fix", "-n", "-j"])).unwrap();
+        assert!(options.fix && options.dry_run && options.json);
+    }
+
+    // First-run machine: storage missing → warn, exit 0; JSON shape stable.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_json_warns_on_missing_storage_and_exits_zero() {
+        let _sandbox = EnvSandbox::new();
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["command"], Value::from("doctor"));
+        let keys: Vec<&str> = payload
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(String::as_str)
+            .collect();
+        assert_eq!(keys, vec!["command", "storagePath", "summary", "checks", "fix"]);
+        assert_eq!(find_check(&payload, "storage-file")["severity"], Value::from("warn"));
+        assert_eq!(find_check(&payload, "accounts")["severity"], Value::from("warn"));
+        assert_eq!(payload["fix"]["enabled"], Value::from(false));
+        assert_eq!(payload["fix"]["changed"], Value::from(false));
+    }
+
+    // All-disabled pool is an error severity → exit 1.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_all_disabled_pool_is_error_and_exits_one() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        let mut disabled = account("rt-a", Some("a@x.com"));
+        disabled.enabled = Some(false);
+        storage.accounts.push(disabled);
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 1);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let check = find_check(&payload, "enabled-accounts");
+        assert_eq!(check["severity"], Value::from("error"));
+        assert_eq!(check["message"], Value::from("All accounts are disabled"));
+        assert!(payload["summary"]["error"].as_i64().unwrap() > 0);
+    }
+
+    // runDoctor uses the refresh-token validator + duplicate detection in
+    // JSON diagnostics, with masked identities only.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_warns_on_duplicates_and_placeholder_emails_without_leaking() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage
+            .accounts
+            .push(account("duplicate-token-value-1234", Some("demo@example.com")));
+        storage
+            .accounts
+            .push(account("duplicate-token-value-1234", Some("demo@example.com")));
+        // Injected loader: the storage crate's load-normalize dedupes
+        // same-token rows on disk, but doctor must still diagnose whatever
+        // the loader hands it.
+        let mut deps = quiet_deps();
+        deps.load_accounts = Box::new(move || {
+            let storage = storage.clone();
+            Box::pin(async move { Some(storage) })
+        });
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        let payload: Value = serde_json::from_str(&text).expect("json");
+        assert_eq!(
+            find_check(&payload, "duplicate-refresh-token")["message"],
+            Value::from("Detected 1 duplicate refresh token entry")
+        );
+        assert_eq!(
+            find_check(&payload, "duplicate-email")["message"],
+            Value::from("Detected 1 duplicate email entry")
+        );
+        assert_eq!(
+            find_check(&payload, "placeholder-email")["severity"],
+            Value::from("warn")
+        );
+        // Raw identities never appear anywhere in the output.
+        assert!(!text.contains("demo@example.com"));
+        assert!(!text.contains("duplicate-token-value-1234"));
+    }
+
+    // --fix fills missing email/accountId from token claims and records the
+    // frozen action messages; the write persists via the transaction
+    // (re-applied on fresh disk state).
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_fix_fills_identity_from_token_claims_and_persists() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        let mut bare = account("rt-a", None);
+        bare.access_token = Some(claims_jwt("tok@x.com", "acct_1234567890"));
+        storage.accounts.push(bare);
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json", "--fix"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["fix"]["enabled"], Value::from(true));
+        assert_eq!(payload["fix"]["changed"], Value::from(true));
+        let actions: Vec<&str> = payload["fix"]["actions"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|action| action["message"].as_str().unwrap())
+            .collect();
+        assert!(actions.contains(&"Updated account 1 email from token claims"));
+        assert!(actions.contains(&"Filled missing accountId for account 1"));
+
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts.len(), 1);
+        assert_eq!(saved.accounts[0].email.as_deref(), Some("tok@x.com"));
+        assert_eq!(
+            saved.accounts[0].account_id.as_deref(),
+            Some("acct_1234567890")
+        );
+        // The raw identities never leak into the diagnostics output.
+        assert!(!out.info_text().contains("tok@x.com"));
+    }
+
+    // --fix --dry-run prepares actions without writing.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_fix_dry_run_prepares_without_writing() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        let mut bare = account("rt-a", None);
+        bare.access_token = Some(claims_jwt("tok@x.com", "acct_1234567890"));
+        storage.accounts.push(bare);
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json", "--fix", "--dry-run"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["fix"]["dryRun"], Value::from(true));
+        assert_eq!(payload["fix"]["changed"], Value::from(true));
+        let auto_fix = find_check(&payload, "auto-fix");
+        assert!(
+            auto_fix["message"]
+                .as_str()
+                .unwrap()
+                .ends_with("(dry-run)")
+        );
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts[0].email, None);
+        assert_eq!(saved.accounts[0].account_id, None);
+    }
+
+    // Failed runtime snapshot loads are treated as aligned diagnostics.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_treats_missing_runtime_snapshot_as_aligned() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com")));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let check = find_check(&payload, "forecast-runtime-alignment");
+        assert_eq!(check["severity"], Value::from("ok"));
+        assert_eq!(
+            check["message"],
+            Value::from("Forecast and runtime availability are aligned")
+        );
+    }
+
+    // Text mode prints markers, details indentation, and the auto-fix block.
+    #[tokio::test]
+    #[serial(env)]
+    async fn doctor_text_mode_prints_summary_and_checks() {
+        let _sandbox = EnvSandbox::new();
+        let deps = quiet_deps();
+        let mut out = CliOut::capture();
+        let code = run_doctor_with(&[], &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let text = out.info_text();
+        let lines: Vec<&str> = text.split('\n').collect();
+        assert_eq!(lines[0], "Doctor diagnostics");
+        assert!(lines[1].starts_with("Storage: "));
+        assert!(lines[2].starts_with("Summary: "));
+        assert!(text.contains("! storage-file: Account storage file does not exist yet (first login pending)"));
+        // No --fix → no auto-fix block.
+        assert!(!text.contains("Auto-fix actions"));
+    }
+}
diff --git a/crates/manager/src/repair/fix.rs b/crates/manager/src/repair/fix.rs
new file mode 100644
index 000000000..2d227f5e7
--- /dev/null
+++ b/crates/manager/src/repair/fix.rs
@@ -0,0 +1,1371 @@
+//! Port of `lib/codex-manager/repair-commands.ts` — the `fix` command half,
+//! plus the repair plumbing shared with `doctor` / `verify-flagged`
+//! (`RepairDeps`, `createEmptyAccountStorage`, `normalizeDoctorIndexes`,
+//! placeholder/refresh-token helpers).
+//!
+//! Behavior source: spec 09 §3.1/§3.2/§3.4. CRITICAL contracts:
+//! - `fix` NEVER deletes accounts — hard refresh failures only disable;
+//! - all-disabled lockout guard re-enables one account and rewrites its
+//!   report to a soft warning with the frozen suffix;
+//! - persistence rebases onto fresh disk state: probe/refresh happens
+//!   OUTSIDE the storage lock, then each mutated account is RE-LOCATED BY
+//!   IDENTITY inside `with_account_storage_transaction` before overwriting
+//!   the 7 tracked fields;
+//! - quota-cache save failures are partial success (`quotaCacheSaveError`),
+//!   never fatal.
+//!
+//! The TS `RepairCommandDeps` styling/format members are absorbed as direct
+//! imports (ARCHITECTURE §4 item 10); the injectable seams kept here are the
+//! I/O ones the ported tests exercise (refresh, probe, loaders, mirrors).
+
+use std::collections::HashMap;
+
+use cma_cli_mirror::state::CodexCliState;
+use cma_cli_mirror::writer::ActiveSelection;
+use cma_core::errors::CodexError;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::model_family::{DEFAULT_PROBE_MODEL, MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::{
+    AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily,
+};
+use cma_core::schemas::flagged::FlaggedAccountStorageV1;
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_quota::cache::QuotaCacheData;
+use cma_quota::forecast::{
+    ForecastAccountInput, evaluate_forecast_accounts, is_hard_refresh_failure,
+    recommend_forecast_account,
+};
+use cma_quota::probe::{
+    CODEX_UNAVAILABLE_PROBE_NOTE, CodexQuotaSnapshot, ProbeCodexQuotaOptions,
+    fetch_codex_quota_snapshot,
+};
+use cma_quota::readiness::build_quota_email_fallback_state;
+use cma_request::model_map::resolve_normalized_model;
+use cma_runtime::observability::RuntimeObservabilitySnapshot;
+use cma_storage::matching::{AccountMatchOptions, find_matching_account_index};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::forecast_report_shared::{BoxFuture, LoadAccountsFn, default_load_accounts};
+use crate::formatters::account::style_account_detail_text_with_tone;
+use crate::formatters::quota::{CompactQuotaFormatOptions, format_compact_quota_snapshot};
+use crate::formatters::text_style::{
+    PromptTone, ResultSegment, format_result_summary, normalize_failure_detail, style_prompt_text,
+};
+
+// ============================================================================
+// Shared repair plumbing (TS repair-commands.ts privates used by all three
+// commands; doctor.rs / verify_flagged.rs import from here)
+// ============================================================================
+
+/// Input to the injectable quota probe seam (the TS
+/// `fetchCodexQuotaSnapshot({ accountId, accessToken, model })` call shape).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct QuotaProbeRequest {
+    pub account_id: String,
+    pub access_token: String,
+    pub model: String,
+}
+
+/// Injectable I/O bundle shared by `fix` / `doctor` / `verify-flagged`
+/// (Rust spelling of the TS module imports the tests mock; the styling
+/// members of the TS `RepairCommandDeps` are direct imports instead).
+pub struct RepairDeps {
+    pub load_accounts: LoadAccountsFn,
+    pub load_flagged_accounts: Box<dyn Fn() -> BoxFuture<FlaggedAccountStorageV1> + Send + Sync>,
+    pub queued_refresh: Box<dyn Fn(String) -> BoxFuture<TokenResult> + Send + Sync>,
+    pub fetch_codex_quota_snapshot: Box<
+        dyn Fn(QuotaProbeRequest) -> BoxFuture<Result<CodexQuotaSnapshot, CodexError>>
+            + Send
+            + Sync,
+    >,
+    pub load_quota_cache: Box<dyn Fn() -> BoxFuture<QuotaCacheData> + Send + Sync>,
+    pub save_quota_cache:
+        Box<dyn Fn(QuotaCacheData) -> BoxFuture<Result<(), CodexError>> + Send + Sync>,
+    pub load_codex_cli_state: Box<dyn Fn(bool) -> BoxFuture<Option<CodexCliState>> + Send + Sync>,
+    pub set_codex_cli_active_selection:
+        Box<dyn Fn(ActiveSelection) -> BoxFuture<bool> + Send + Sync>,
+    pub load_runtime_observability_snapshot:
+        Box<dyn Fn() -> BoxFuture<Option<RuntimeObservabilitySnapshot>> + Send + Sync>,
+    pub get_now: Option<Box<dyn Fn() -> i64 + Send + Sync>>,
+}
+
+impl Default for RepairDeps {
+    fn default() -> Self {
+        RepairDeps {
+            load_accounts: default_load_accounts(),
+            load_flagged_accounts: Box::new(|| {
+                Box::pin(cma_storage::flagged::load_flagged_accounts())
+            }),
+            queued_refresh: Box::new(|refresh_token| {
+                Box::pin(
+                    async move { cma_auth::refresh_queue::queued_refresh(&refresh_token).await },
+                )
+            }),
+            fetch_codex_quota_snapshot: Box::new(|request| {
+                Box::pin(async move {
+                    fetch_codex_quota_snapshot(&ProbeCodexQuotaOptions {
+                        account_id: request.account_id,
+                        access_token: request.access_token,
+                        model: Some(request.model),
+                        ..Default::default()
+                    })
+                    .await
+                })
+            }),
+            load_quota_cache: Box::new(|| Box::pin(cma_quota::cache::load_quota_cache())),
+            save_quota_cache: Box::new(|cache| {
+                Box::pin(async move {
+                    cma_quota::cache::save_quota_cache(&cache).await;
+                    Ok(())
+                })
+            }),
+            load_codex_cli_state: Box::new(|force_refresh| {
+                Box::pin(cma_cli_mirror::state::load_codex_cli_state(force_refresh))
+            }),
+            set_codex_cli_active_selection: Box::new(|selection| {
+                Box::pin(async move {
+                    cma_cli_mirror::writer::set_codex_cli_active_selection(&selection).await
+                })
+            }),
+            load_runtime_observability_snapshot: Box::new(|| {
+                Box::pin(async {
+                    cma_runtime::observability::load_persisted_runtime_observability_snapshot()
+                })
+            }),
+            get_now: None,
+        }
+    }
+}
+
+impl RepairDeps {
+    pub(crate) fn now(&self) -> i64 {
+        match &self.get_now {
+            Some(get_now) => get_now(),
+            None => cma_core::utils::now_ms(),
+        }
+    }
+}
+
+/// TS `createEmptyAccountStorage()` — `{version: 3, accounts: [],
+/// activeIndex: 0, activeIndexByFamily: {every family: 0}}`.
+pub fn create_empty_account_storage() -> AccountStorageV3 {
+    let mut by_family = ActiveIndexByFamily::default();
+    for family in MODEL_FAMILIES {
+        by_family.set(family, Some(0));
+    }
+    let mut storage = AccountStorageV3::empty();
+    storage.active_index_by_family = Some(by_family);
+    storage
+}
+
+/// TS `normalizeDoctorIndexes(storage)` — clamp `activeIndex` to
+/// `[0, total-1]` (0 when empty); ensure `activeIndexByFamily` exists; clamp
+/// every family slot (missing/non-finite → activeIndex fallback).
+pub fn normalize_doctor_indexes(storage: &mut AccountStorageV3) -> bool {
+    let total = storage.accounts.len() as i64;
+    let next_active = if total == 0 {
+        0
+    } else {
+        storage.active_index.clamp(0, total - 1)
+    };
+    let mut changed = false;
+    if storage.active_index != next_active {
+        storage.active_index = next_active;
+        changed = true;
+    }
+    if storage.active_index_by_family.is_none() {
+        storage.active_index_by_family = Some(ActiveIndexByFamily::default());
+    }
+    let active_index = storage.active_index;
+    if let Some(by_family) = &mut storage.active_index_by_family {
+        for family in MODEL_FAMILIES {
+            let raw = by_family.get(family);
+            let candidate = raw.unwrap_or(active_index);
+            let clamped = if total == 0 {
+                0
+            } else {
+                candidate.clamp(0, total - 1)
+            };
+            if by_family.get(family) != Some(clamped) {
+                by_family.set(family, Some(clamped));
+                changed = true;
+            }
+        }
+    }
+    changed
+}
+
+/// TS `getDoctorRefreshTokenKey(refreshToken)` — trimmed, non-empty.
+pub fn get_doctor_refresh_token_key(refresh_token: &str) -> Option<String> {
+    let trimmed = refresh_token.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `hasPlaceholderEmail(value)` — trimmed, lowercased, ends with
+/// `@example.com`.
+pub fn has_placeholder_email(value: Option<&str>) -> bool {
+    let Some(value) = value else {
+        return false;
+    };
+    let email = value.trim().to_lowercase();
+    if email.is_empty() {
+        return false;
+    }
+    email.ends_with("@example.com")
+}
+
+/// TS `error instanceof Error ? error.message : String(error)` over the
+/// crate error type.
+pub(crate) fn codex_error_message(error: &CodexError) -> String {
+    error.message().to_string()
+}
+
+// ============================================================================
+// Arg parsing
+// ============================================================================
+
+/// TS `FixCliOptions`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FixCliOptions {
+    pub dry_run: bool,
+    pub json: bool,
+    pub live: bool,
+    pub model: String,
+}
+
+impl Default for FixCliOptions {
+    fn default() -> Self {
+        FixCliOptions {
+            dry_run: false,
+            json: false,
+            live: false,
+            model: DEFAULT_PROBE_MODEL.to_string(),
+        }
+    }
+}
+
+fn print_fix_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:".to_string(),
+            "  codex-multi-auth fix [--dry-run] [--json] [--live] [--model <model>]".to_string(),
+            String::new(),
+            "Options:".to_string(),
+            "  --dry-run, -n      Preview changes without writing storage".to_string(),
+            "  --json, -j         Print machine-readable JSON output".to_string(),
+            "  --live, -l         Run live session probe before deciding health".to_string(),
+            format!(
+                "  --model, -m        Probe model for live mode (default: {DEFAULT_PROBE_MODEL})"
+            ),
+            String::new(),
+            "Behavior:".to_string(),
+            "  - Refreshes tokens for enabled accounts".to_string(),
+            "  - Disables hard-failed accounts (never deletes)".to_string(),
+            "  - Recommends a better current account when needed".to_string(),
+        ]
+        .join("\n"),
+    );
+}
+
+/// TS `parseFixArgs(args)` (exported).
+pub fn parse_fix_args(args: &[String]) -> Result<FixCliOptions, String> {
+    let mut options = FixCliOptions::default();
+
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        match arg {
+            "--dry-run" | "-n" => {
+                options.dry_run = true;
+                i += 1;
+                continue;
+            }
+            "--json" | "-j" => {
+                options.json = true;
+                i += 1;
+                continue;
+            }
+            "--live" | "-l" => {
+                options.live = true;
+                i += 1;
+                continue;
+            }
+            "--model" | "-m" => {
+                let value = args.get(i + 1).map(|v| v.trim().to_string());
+                match value {
+                    Some(v) if !v.is_empty() && !v.starts_with('-') => {
+                        options.model = v;
+                        i += 2;
+                        continue;
+                    }
+                    _ => return Err("Missing value for --model".to_string()),
+                }
+            }
+            _ => {}
+        }
+        if let Some(raw) = arg.strip_prefix("--model=") {
+            let value = raw.trim();
+            if value.is_empty() || value.starts_with('-') {
+                return Err("Missing value for --model".to_string());
+            }
+            options.model = value.to_string();
+            i += 1;
+            continue;
+        }
+        return Err(format!("Unknown option: {arg}"));
+    }
+
+    Ok(options)
+}
+
+// ============================================================================
+// Reports / mutation plumbing
+// ============================================================================
+
+/// TS `FixOutcome`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum FixOutcome {
+    Healthy,
+    DisabledHardFailure,
+    WarningSoftFailure,
+    AlreadyDisabled,
+}
+
+impl FixOutcome {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            FixOutcome::Healthy => "healthy",
+            FixOutcome::DisabledHardFailure => "disabled-hard-failure",
+            FixOutcome::WarningSoftFailure => "warning-soft-failure",
+            FixOutcome::AlreadyDisabled => "already-disabled",
+        }
+    }
+}
+
+/// TS `FixAccountReport`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FixAccountReport {
+    pub index: usize,
+    pub label: String,
+    pub outcome: FixOutcome,
+    pub message: String,
+}
+
+fn report_to_value(report: &FixAccountReport) -> Value {
+    let mut row = Map::new();
+    row.insert("index".into(), Value::from(report.index as i64));
+    row.insert("label".into(), Value::from(report.label.clone()));
+    row.insert("outcome".into(), Value::from(report.outcome.as_str()));
+    row.insert("message".into(), Value::from(report.message.clone()));
+    Value::Object(row)
+}
+
+struct FixSummary {
+    healthy: usize,
+    disabled: usize,
+    warnings: usize,
+    skipped: usize,
+}
+
+fn summarize_fix_reports(reports: &[FixAccountReport]) -> FixSummary {
+    let mut summary = FixSummary {
+        healthy: 0,
+        disabled: 0,
+        warnings: 0,
+        skipped: 0,
+    };
+    for report in reports {
+        match report.outcome {
+            FixOutcome::Healthy => summary.healthy += 1,
+            FixOutcome::DisabledHardFailure => summary.disabled += 1,
+            FixOutcome::WarningSoftFailure => summary.warnings += 1,
+            FixOutcome::AlreadyDisabled => summary.skipped += 1,
+        }
+    }
+    summary
+}
+
+struct AccountStorageMutation {
+    before: AccountMetadataV3,
+    after: AccountMetadataV3,
+}
+
+fn has_account_storage_mutation(before: &AccountMetadataV3, after: &AccountMetadataV3) -> bool {
+    before.refresh_token != after.refresh_token
+        || before.access_token != after.access_token
+        || before.expires_at != after.expires_at
+        || before.email != after.email
+        || before.account_id != after.account_id
+        || before.account_id_source != after.account_id_source
+        || before.enabled != after.enabled
+}
+
+fn collect_account_storage_mutations(
+    before_accounts: &[AccountMetadataV3],
+    after_accounts: &[AccountMetadataV3],
+) -> Vec<AccountStorageMutation> {
+    let mut mutations = Vec::new();
+    for (i, after) in after_accounts.iter().enumerate() {
+        let Some(before) = before_accounts.get(i) else {
+            continue;
+        };
+        if !has_account_storage_mutation(before, after) {
+            continue;
+        }
+        mutations.push(AccountStorageMutation {
+            before: before.clone(),
+            after: after.clone(),
+        });
+    }
+    mutations
+}
+
+/// Re-locate each mutated account BY IDENTITY (before, then after) in the
+/// transaction-loaded storage and overwrite the 7 tracked fields. Unmatched
+/// mutations are dropped (the account disappeared concurrently).
+fn apply_account_storage_mutations(
+    storage: &mut AccountStorageV3,
+    mutations: &[AccountStorageMutation],
+) {
+    let options = AccountMatchOptions {
+        allow_unique_account_id_fallback_without_email: true,
+    };
+    for mutation in mutations {
+        let target_index = find_matching_account_index(&storage.accounts, &mutation.before, options)
+            .or_else(|| find_matching_account_index(&storage.accounts, &mutation.after, options));
+        let Some(target_index) = target_index else {
+            continue;
+        };
+        let Some(target) = storage.accounts.get_mut(target_index) else {
+            continue;
+        };
+        target.refresh_token = mutation.after.refresh_token.clone();
+        target.access_token = mutation.after.access_token.clone();
+        target.expires_at = mutation.after.expires_at;
+        target.email = mutation.after.email.clone();
+        target.account_id = mutation.after.account_id.clone();
+        target.account_id_source = mutation.after.account_id_source;
+        target.enabled = mutation.after.enabled;
+    }
+}
+
+pub(crate) fn account_label(account: &AccountMetadataV3, index: usize) -> String {
+    cma_accounts::manager_persistence::format_account_label(
+        Some(account as &dyn cma_accounts::manager_persistence::AccountLabelSource),
+        index,
+    )
+}
+
+// ============================================================================
+// runFix
+// ============================================================================
+
+/// Production entry (dispatcher wiring).
+pub async fn run_fix(args: &[String], out: &mut CliOut) -> i32 {
+    run_fix_with(args, &RepairDeps::default(), out).await
+}
+
+/// TS `runFix(args, deps)`.
+pub async fn run_fix_with(args: &[String], deps: &RepairDeps, out: &mut CliOut) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_fix_usage(out);
+        return 0;
+    }
+
+    let options = match parse_fix_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_fix_usage(out);
+            return 1;
+        }
+    };
+    let trimmed_model = options.model.trim();
+    let probe_model = resolve_normalized_model(Some(if trimmed_model.is_empty() {
+        DEFAULT_PROBE_MODEL
+    } else {
+        trimmed_model
+    }));
+    // Deliberate: fix output is full detail — the DEFAULT display settings,
+    // NOT the user's saved dashboard settings.
+    let display = cma_config::dashboard_settings::default_dashboard_display_settings();
+    let mut working_quota_cache: Option<QuotaCacheData> = if options.live {
+        Some((deps.load_quota_cache)().await)
+    } else {
+        None
+    };
+    let mut quota_cache_changed = false;
+
+    cma_storage::facade::set_storage_path(None);
+    let mut storage: AccountStorageV3 = match (deps.load_accounts)().await {
+        Some(storage) if !storage.accounts.is_empty() => storage,
+        _ => {
+            if options.json {
+                let mut payload = Map::new();
+                payload.insert("command".into(), Value::from("fix"));
+                payload.insert("dryRun".into(), Value::from(options.dry_run));
+                payload.insert("liveProbe".into(), Value::from(options.live));
+                payload.insert("model".into(), Value::from(options.model.clone()));
+                payload.insert("changed".into(), Value::from(false));
+                let mut summary = Map::new();
+                summary.insert("healthy".into(), Value::from(0));
+                summary.insert("disabled".into(), Value::from(0));
+                summary.insert("warnings".into(), Value::from(0));
+                summary.insert("skipped".into(), Value::from(0));
+                payload.insert("summary".into(), Value::Object(summary));
+                let mut recommendation = Map::new();
+                recommendation.insert("recommendedIndex".into(), Value::Null);
+                recommendation.insert("reason".into(), Value::from("No accounts configured."));
+                payload.insert("recommendation".into(), Value::Object(recommendation));
+                payload.insert("recommendedSwitchCommand".into(), Value::Null);
+                payload.insert("reports".into(), Value::Array(Vec::new()));
+                out.info(stringify_pretty2(&Value::Object(payload)));
+            } else {
+                out.info("No accounts configured.");
+            }
+            return 0;
+        }
+    };
+    let original_accounts: Vec<AccountMetadataV3> = storage.accounts.clone();
+    let mut quota_email_fallback_state = if options.live {
+        Some(build_quota_email_fallback_state(&storage.accounts))
+    } else {
+        None
+    };
+
+    let now = deps.now();
+    let active_index =
+        cma_runtime::account_status::resolve_active_index(&storage, ModelFamily::Codex);
+    let mut account_storage_changed = false;
+    let mut reports: Vec<FixAccountReport> = Vec::new();
+    let mut refresh_failures: HashMap<usize, TokenFailure> = HashMap::new();
+    let mut hard_disabled_indexes: Vec<usize> = Vec::new();
+
+    for i in 0..storage.accounts.len() {
+        let label = account_label(&storage.accounts[i], i);
+
+        if storage.accounts[i].enabled == Some(false) {
+            reports.push(FixAccountReport {
+                index: i,
+                label,
+                outcome: FixOutcome::AlreadyDisabled,
+                message: "already disabled".to_string(),
+            });
+            continue;
+        }
+
+        if crate::login::account_credentials::has_usable_access_token(&storage.accounts[i], now) {
+            let mut refresh_after_live_probe_failure = false;
+            if options.live {
+                let current_access_token = storage.accounts[i].access_token.clone();
+                let probe_account_id = current_access_token.as_ref().and_then(|token| {
+                    storage.accounts[i]
+                        .account_id
+                        .clone()
+                        .or_else(|| extract_account_id(Some(token)))
+                });
+                if let (Some(probe_account_id), Some(current_access_token)) =
+                    (probe_account_id, current_access_token)
+                {
+                    match (deps.fetch_codex_quota_snapshot)(QuotaProbeRequest {
+                        account_id: probe_account_id,
+                        access_token: current_access_token,
+                        model: probe_model.to_string(),
+                    })
+                    .await
+                    {
+                        Ok(snapshot) => {
+                            if let Some(working) = &mut working_quota_cache {
+                                quota_cache_changed =
+                                    crate::quota_cache_helpers::update_quota_cache_for_account(
+                                        working,
+                                        &storage.accounts[i],
+                                        &snapshot,
+                                        &storage.accounts,
+                                        quota_email_fallback_state.as_ref(),
+                                    ) || quota_cache_changed;
+                            }
+                            reports.push(FixAccountReport {
+                                index: i,
+                                label,
+                                outcome: FixOutcome::Healthy,
+                                message: if display.show_quota_details {
+                                    format!(
+                                        "live session OK ({})",
+                                        format_compact_quota_snapshot(
+                                            &snapshot,
+                                            cma_core::utils::now_ms(),
+                                            &CompactQuotaFormatOptions::default(),
+                                        )
+                                    )
+                                } else {
+                                    "live session OK".to_string()
+                                },
+                            });
+                            continue;
+                        }
+                        Err(_) => {
+                            refresh_after_live_probe_failure = true;
+                        }
+                    }
+                }
+            }
+
+            if !refresh_after_live_probe_failure {
+                let refresh_warning =
+                    if crate::login::account_credentials::has_likely_invalid_refresh_token(Some(
+                        &storage.accounts[i].refresh_token,
+                    )) {
+                        " (refresh token looks stale; re-login recommended)"
+                    } else {
+                        ""
+                    };
+                reports.push(FixAccountReport {
+                    index: i,
+                    label,
+                    outcome: FixOutcome::Healthy,
+                    message: format!("access token still valid{refresh_warning}"),
+                });
+                continue;
+            }
+        }
+
+        let refresh_result = (deps.queued_refresh)(storage.accounts[i].refresh_token.clone()).await;
+        match refresh_result {
+            TokenResult::Success(success) => {
+                let next_email = sanitize_email(
+                    extract_account_email(Some(&success.access), success.id_token.as_deref())
+                        .as_deref(),
+                );
+                let next_account_id = extract_account_id(Some(&success.access));
+                let previous_email = storage.accounts[i].email.clone();
+                let mut account_changed = false;
+                let mut account_identity_changed = false;
+
+                {
+                    let account = &mut storage.accounts[i];
+                    if account.refresh_token != success.refresh {
+                        account.refresh_token = success.refresh.clone();
+                        account_changed = true;
+                    }
+                    if account.access_token.as_deref() != Some(success.access.as_str()) {
+                        account.access_token = Some(success.access.clone());
+                        account_changed = true;
+                    }
+                    if account.expires_at != Some(success.expires) {
+                        account.expires_at = Some(success.expires);
+                        account_changed = true;
+                    }
+                    if let Some(next_email_value) = &next_email
+                        && account.email.as_deref() != Some(next_email_value.as_str())
+                    {
+                        account.email = Some(next_email_value.clone());
+                        account_changed = true;
+                        account_identity_changed = true;
+                    }
+                    if crate::login::account_credentials::apply_token_account_identity(
+                        account,
+                        next_account_id.as_deref(),
+                    ) {
+                        account_changed = true;
+                        account_identity_changed = true;
+                    }
+                }
+
+                if account_changed {
+                    account_storage_changed = true;
+                }
+                if account_identity_changed && options.live {
+                    let next_state = build_quota_email_fallback_state(&storage.accounts);
+                    if let Some(working) = &mut working_quota_cache {
+                        quota_cache_changed =
+                            crate::quota_cache_helpers::prune_unsafe_quota_email_cache_entry(
+                                working,
+                                previous_email.as_deref(),
+                                &storage.accounts,
+                                &next_state,
+                            ) || quota_cache_changed;
+                    }
+                    quota_email_fallback_state = Some(next_state);
+                }
+                if options.live {
+                    let probe_account_id = storage.accounts[i]
+                        .account_id
+                        .clone()
+                        .or_else(|| next_account_id.clone());
+                    if let Some(probe_account_id) = probe_account_id {
+                        match (deps.fetch_codex_quota_snapshot)(QuotaProbeRequest {
+                            account_id: probe_account_id,
+                            access_token: success.access.clone(),
+                            model: probe_model.to_string(),
+                        })
+                        .await
+                        {
+                            Ok(snapshot) => {
+                                if let Some(working) = &mut working_quota_cache {
+                                    quota_cache_changed =
+                                        crate::quota_cache_helpers::update_quota_cache_for_account(
+                                            working,
+                                            &storage.accounts[i],
+                                            &snapshot,
+                                            &storage.accounts,
+                                            quota_email_fallback_state.as_ref(),
+                                        ) || quota_cache_changed;
+                                }
+                                reports.push(FixAccountReport {
+                                    index: i,
+                                    label,
+                                    outcome: FixOutcome::Healthy,
+                                    message: if display.show_quota_details {
+                                        format!(
+                                            "refresh + live probe succeeded ({})",
+                                            format_compact_quota_snapshot(
+                                                &snapshot,
+                                                cma_core::utils::now_ms(),
+                                                &CompactQuotaFormatOptions::default(),
+                                            )
+                                        )
+                                    } else {
+                                        "refresh + live probe succeeded".to_string()
+                                    },
+                                });
+                                continue;
+                            }
+                            Err(error) => {
+                                if error.is_codex_unavailable() {
+                                    reports.push(FixAccountReport {
+                                        index: i,
+                                        label,
+                                        outcome: FixOutcome::WarningSoftFailure,
+                                        message: format!(
+                                            "refresh succeeded ({CODEX_UNAVAILABLE_PROBE_NOTE})"
+                                        ),
+                                    });
+                                    continue;
+                                }
+                                let message = normalize_failure_detail(
+                                    Some(&codex_error_message(&error)),
+                                    None,
+                                );
+                                reports.push(FixAccountReport {
+                                    index: i,
+                                    label,
+                                    outcome: FixOutcome::WarningSoftFailure,
+                                    message: format!(
+                                        "refresh succeeded but live probe failed: {message}"
+                                    ),
+                                });
+                                continue;
+                            }
+                        }
+                    }
+                }
+                reports.push(FixAccountReport {
+                    index: i,
+                    label,
+                    outcome: FixOutcome::Healthy,
+                    message: "refresh succeeded".to_string(),
+                });
+            }
+            TokenResult::Failed(failure) => {
+                let detail = normalize_failure_detail(
+                    failure.message.as_deref(),
+                    failure.reason.map(|reason| reason.as_str()),
+                );
+                let mut recorded = failure.clone();
+                recorded.message = Some(detail.clone());
+                refresh_failures.insert(i, recorded);
+                if is_hard_refresh_failure(&failure) {
+                    storage.accounts[i].enabled = Some(false);
+                    account_storage_changed = true;
+                    hard_disabled_indexes.push(i);
+                    reports.push(FixAccountReport {
+                        index: i,
+                        label,
+                        outcome: FixOutcome::DisabledHardFailure,
+                        message: detail,
+                    });
+                } else {
+                    reports.push(FixAccountReport {
+                        index: i,
+                        label,
+                        outcome: FixOutcome::WarningSoftFailure,
+                        message: detail,
+                    });
+                }
+            }
+        }
+    }
+
+    // All-disabled lockout guard: NEVER leave the pool with zero enabled
+    // accounts because of this run's hard-disables.
+    if !hard_disabled_indexes.is_empty() {
+        let enabled_count = storage
+            .accounts
+            .iter()
+            .filter(|account| account.enabled != Some(false))
+            .count();
+        if enabled_count == 0 {
+            let fallback_index = if hard_disabled_indexes.contains(&active_index) {
+                active_index
+            } else {
+                hard_disabled_indexes[0]
+            };
+            if let Some(fallback) = storage.accounts.get_mut(fallback_index)
+                && fallback.enabled == Some(false)
+            {
+                fallback.enabled = Some(true);
+                account_storage_changed = true;
+                if let Some(existing_report) = reports.iter_mut().find(|report| {
+                    report.index == fallback_index
+                        && report.outcome == FixOutcome::DisabledHardFailure
+                }) {
+                    existing_report.outcome = FixOutcome::WarningSoftFailure;
+                    existing_report.message = format!(
+                        "{} (kept enabled to avoid lockout; re-login required)",
+                        existing_report.message
+                    );
+                }
+            }
+        }
+    }
+
+    let forecast_inputs: Vec<ForecastAccountInput<'_>> = storage
+        .accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| ForecastAccountInput {
+            index,
+            account,
+            is_current: index == active_index,
+            now,
+            refresh_failure: refresh_failures.get(&index),
+            live_quota: None,
+            quota_cache: None,
+            all_accounts: None,
+            runtime_overlay: None,
+        })
+        .collect();
+    let forecast_results = evaluate_forecast_accounts(&forecast_inputs);
+    drop(forecast_inputs);
+    let recommendation = recommend_forecast_account(&forecast_results);
+    let report_summary = summarize_fix_reports(&reports);
+    let account_mutations = collect_account_storage_mutations(&original_accounts, &storage.accounts);
+
+    if account_storage_changed && !options.dry_run {
+        let persisted = cma_storage::transactions::with_account_storage_transaction(
+            move |loaded_storage, persist| async move {
+                let mut next_storage = match loaded_storage {
+                    Some(loaded) => loaded.clone(),
+                    None => create_empty_account_storage(),
+                };
+                apply_account_storage_mutations(&mut next_storage, &account_mutations);
+                persist.persist(&next_storage).await?;
+                Ok(())
+            },
+        )
+        .await;
+        if let Err(error) = persisted {
+            // TS lets the transaction rejection propagate out of the CLI;
+            // the Rust surface reports it and exits 1 instead of panicking.
+            out.error(codex_error_message(&error));
+            return 1;
+        }
+    }
+
+    let mut quota_cache_save_error: Option<String> = None;
+    if !options.dry_run
+        && quota_cache_changed
+        && let Some(working) = &working_quota_cache
+        && let Err(error) = (deps.save_quota_cache)(working.clone()).await
+    {
+        // Partial success — account storage was already persisted above.
+        quota_cache_save_error = Some(codex_error_message(&error));
+    }
+
+    let changed = account_storage_changed;
+
+    if options.json {
+        let mut payload = Map::new();
+        payload.insert("command".into(), Value::from("fix"));
+        payload.insert("dryRun".into(), Value::from(options.dry_run));
+        payload.insert("liveProbe".into(), Value::from(options.live));
+        payload.insert("model".into(), Value::from(options.model.clone()));
+        payload.insert("changed".into(), Value::from(changed));
+        payload.insert("quotaCacheChanged".into(), Value::from(quota_cache_changed));
+        payload.insert(
+            "quotaCacheSaveError".into(),
+            quota_cache_save_error
+                .clone()
+                .map(Value::from)
+                .unwrap_or(Value::Null),
+        );
+        let mut summary = Map::new();
+        summary.insert("healthy".into(), Value::from(report_summary.healthy as i64));
+        summary.insert("disabled".into(), Value::from(report_summary.disabled as i64));
+        summary.insert("warnings".into(), Value::from(report_summary.warnings as i64));
+        summary.insert("skipped".into(), Value::from(report_summary.skipped as i64));
+        payload.insert("summary".into(), Value::Object(summary));
+        payload.insert(
+            "recommendation".into(),
+            serde_json::to_value(&recommendation).unwrap_or(Value::Null),
+        );
+        payload.insert(
+            "recommendedSwitchCommand".into(),
+            match recommendation.recommended_index {
+                Some(index) if index != active_index => {
+                    Value::from(format!("codex-multi-auth switch {}", index + 1))
+                }
+                _ => Value::Null,
+            },
+        );
+        payload.insert(
+            "reports".into(),
+            Value::Array(reports.iter().map(report_to_value).collect()),
+        );
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return 0;
+    }
+
+    out.info(style_prompt_text(
+        &format!(
+            "Auto-fix scan ({})",
+            if options.dry_run { "preview" } else { "apply" }
+        ),
+        PromptTone::Accent,
+    ));
+    out.info(format_result_summary(&[
+        ResultSegment::new(
+            format!("{} working", report_summary.healthy),
+            PromptTone::Success,
+        ),
+        ResultSegment::new(
+            format!("{} disabled", report_summary.disabled),
+            if report_summary.disabled > 0 {
+                PromptTone::Danger
+            } else {
+                PromptTone::Muted
+            },
+        ),
+        ResultSegment::new(
+            format!(
+                "{} warning{}",
+                report_summary.warnings,
+                if report_summary.warnings == 1 { "" } else { "s" }
+            ),
+            if report_summary.warnings > 0 {
+                PromptTone::Warning
+            } else {
+                PromptTone::Muted
+            },
+        ),
+        ResultSegment::new(
+            format!("{} already disabled", report_summary.skipped),
+            PromptTone::Muted,
+        ),
+    ]));
+    if let Some(save_error) = &quota_cache_save_error {
+        out.info(style_prompt_text(
+            &format!("Warning: quota cache save failed ({save_error}); account fixes were saved."),
+            PromptTone::Warning,
+        ));
+    }
+    if display.show_per_account_rows {
+        out.info("");
+        for report in &reports {
+            let prefix = match report.outcome {
+                FixOutcome::Healthy => "✓",
+                FixOutcome::DisabledHardFailure => "✗",
+                FixOutcome::WarningSoftFailure => "!",
+                FixOutcome::AlreadyDisabled => "-",
+            };
+            let tone = match report.outcome {
+                FixOutcome::Healthy => PromptTone::Success,
+                FixOutcome::DisabledHardFailure => PromptTone::Danger,
+                FixOutcome::WarningSoftFailure => PromptTone::Warning,
+                FixOutcome::AlreadyDisabled => PromptTone::Muted,
+            };
+            out.info(format!(
+                "{} {} {} {}",
+                style_prompt_text(prefix, tone),
+                style_prompt_text(
+                    &format!("{}. {}", report.index + 1, report.label),
+                    PromptTone::Accent
+                ),
+                style_prompt_text("|", PromptTone::Muted),
+                style_account_detail_text_with_tone(
+                    &report.message,
+                    if tone == PromptTone::Success {
+                        PromptTone::Muted
+                    } else {
+                        tone
+                    }
+                ),
+            ));
+        }
+    } else {
+        out.info("");
+        out.info(style_prompt_text(
+            "Per-account lines are hidden in dashboard settings.",
+            PromptTone::Muted,
+        ));
+    }
+
+    if display.show_recommendations {
+        out.info("");
+        if let Some(index) = recommendation.recommended_index {
+            let target = index + 1;
+            out.info(format!(
+                "{} {}",
+                style_prompt_text("Best next account:", PromptTone::Accent),
+                style_prompt_text(&target.to_string(), PromptTone::Success)
+            ));
+            out.info(format!(
+                "{} {}",
+                style_prompt_text("Why:", PromptTone::Accent),
+                style_prompt_text(&recommendation.reason, PromptTone::Muted)
+            ));
+            if index != active_index {
+                out.info(format!(
+                    "{} codex-multi-auth switch {target}",
+                    style_prompt_text("Switch now with:", PromptTone::Accent)
+                ));
+            }
+        } else {
+            out.info(format!(
+                "{} {}",
+                style_prompt_text("Note:", PromptTone::Accent),
+                style_prompt_text(&recommendation.reason, PromptTone::Muted)
+            ));
+        }
+    }
+
+    if account_storage_changed && options.dry_run {
+        out.info(format!(
+            "\n{}",
+            style_prompt_text("Preview only: no changes were saved.", PromptTone::Warning)
+        ));
+    } else if account_storage_changed {
+        out.info(format!(
+            "\n{}",
+            style_prompt_text("Saved updates.", PromptTone::Success)
+        ));
+    } else if quota_cache_changed {
+        out.info(format!(
+            "\n{}",
+            style_prompt_text(
+                "Quota cache refreshed (no account storage changes).",
+                PromptTone::Muted
+            )
+        ));
+    } else {
+        out.info(format!(
+            "\n{}",
+            style_prompt_text("No changes were needed.", PromptTone::Muted)
+        ));
+    }
+
+    0
+}
+
+// ============================================================================
+// Tests — ported from test/repair-commands.test.ts (fix half)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::{TokenFailureReason, TokenSuccess};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn account(refresh: &str, email: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        account
+    }
+
+    fn deps_with_refresh(
+        result: impl Fn(String) -> TokenResult + Send + Sync + 'static,
+    ) -> RepairDeps {
+        RepairDeps {
+            queued_refresh: Box::new(move |token| {
+                let result = result(token);
+                Box::pin(async move { result })
+            }),
+            get_now: Some(Box::new(|| 1_000)),
+            ..RepairDeps::default()
+        }
+    }
+
+    fn hard_failure() -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: Some(TokenFailureReason::HttpError),
+            status_code: Some(401),
+            message: Some("invalid_grant".to_string()),
+        })
+    }
+
+    fn soft_failure() -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: Some(TokenFailureReason::NetworkError),
+            status_code: None,
+            message: Some("socket hang up".to_string()),
+        })
+    }
+
+    // parseFixArgs rejects a flag-like value after --model instead of
+    // consuming it (test/repair-commands.test.ts).
+    #[test]
+    fn parse_fix_args_rejects_flag_like_model_value() {
+        assert_eq!(
+            parse_fix_args(&args(&["--model", "--json"])),
+            Err("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_fix_args(&args(&["--model="])),
+            Err("Missing value for --model".to_string())
+        );
+        assert_eq!(
+            parse_fix_args(&args(&["--bogus"])),
+            Err("Unknown option: --bogus".to_string())
+        );
+        let options = parse_fix_args(&args(&["-n", "-j", "-l", "-m", "gpt-5.5"])).unwrap();
+        assert!(options.dry_run && options.json && options.live);
+        assert_eq!(options.model, "gpt-5.5");
+    }
+
+    // runFix keeps JSON output consistent for the no-account path — the
+    // skeleton has NO quotaCacheChanged/quotaCacheSaveError keys.
+    #[tokio::test]
+    #[serial(env)]
+    async fn fix_json_no_account_skeleton_is_exact() {
+        let _sandbox = EnvSandbox::new();
+        let deps = RepairDeps::default();
+        let mut out = CliOut::capture();
+        let code = run_fix_with(&args(&["--json", "--model", "gpt-x"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let keys: Vec<&str> = payload
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(String::as_str)
+            .collect();
+        assert_eq!(
+            keys,
+            vec![
+                "command",
+                "dryRun",
+                "liveProbe",
+                "model",
+                "changed",
+                "summary",
+                "recommendation",
+                "recommendedSwitchCommand",
+                "reports"
+            ]
+        );
+        assert_eq!(payload["model"], Value::from("gpt-x"));
+        assert_eq!(
+            payload["recommendation"]["reason"],
+            Value::from("No accounts configured.")
+        );
+        assert_eq!(payload["recommendedSwitchCommand"], Value::Null);
+    }
+
+    // Hard refresh failures disable accounts but NEVER delete them; the
+    // all-disabled lockout guard re-enables one with the frozen suffix.
+    #[tokio::test]
+    #[serial(env)]
+    async fn fix_disables_hard_failures_and_lockout_guard_re_enables_one() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", Some("a@x.com")));
+        storage.accounts.push(account("rt-b", Some("b@x.com")));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = deps_with_refresh(|_| hard_failure());
+        let mut out = CliOut::capture();
+        let code = run_fix_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["changed"], Value::from(true));
+        // Account 0 (active) was re-enabled by the lockout guard.
+        assert_eq!(
+            payload["reports"][0]["outcome"],
+            Value::from("warning-soft-failure")
+        );
+        assert!(
+            payload["reports"][0]["message"]
+                .as_str()
+                .unwrap()
+                .ends_with("(kept enabled to avoid lockout; re-login required)")
+        );
+        assert_eq!(
+            payload["reports"][1]["outcome"],
+            Value::from("disabled-hard-failure")
+        );
+
+        // Fix NEVER deletes: both accounts survive on disk; exactly one is
+        // disabled.
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts.len(), 2);
+        assert_eq!(saved.accounts[0].enabled, Some(true));
+        assert_eq!(saved.accounts[1].enabled, Some(false));
+    }
+
+    // Soft failures warn without disabling.
+    #[tokio::test]
+    #[serial(env)]
+    async fn fix_soft_failures_keep_accounts_enabled() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", None));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = deps_with_refresh(|_| soft_failure());
+        let mut out = CliOut::capture();
+        let code = run_fix_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["changed"], Value::from(false));
+        assert_eq!(
+            payload["reports"][0]["outcome"],
+            Value::from("warning-soft-failure")
+        );
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts[0].enabled, None);
+    }
+
+    // Dry-run never writes storage.
+    #[tokio::test]
+    #[serial(env)]
+    async fn fix_dry_run_does_not_persist() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt-a", None));
+        storage.accounts.push(account("rt-b", None));
+        cma_storage::save::save_accounts(&storage)
+            .await
+            .expect("seed save");
+
+        let deps = deps_with_refresh(|_| hard_failure());
+        let mut out = CliOut::capture();
+        let code = run_fix_with(&args(&["--dry-run", "--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["dryRun"], Value::from(true));
+        assert_eq!(payload["changed"], Value::from(true));
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        assert_eq!(saved.accounts[0].enabled, None);
+        assert_eq!(saved.accounts[1].enabled, None);
+    }
+
+    // runFix re-locates mutated accounts by identity inside the transaction
+    // (probe-outside-lock → re-locate-by-identity): a concurrent reorder on
+    // disk must not clobber the wrong slot.
+    #[tokio::test]
+    #[serial(env)]
+    async fn fix_relocates_mutations_by_identity_in_transaction() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        // Disk order: [b, a] — the pre-scan sees [a, b] via the injected
+        // loader, so index-based application would hit the wrong account.
+        let mut disk = AccountStorageV3::empty();
+        disk.accounts.push(account("rt-b", Some("b@x.com")));
+        disk.accounts.push(account("rt-a", Some("a@x.com")));
+        cma_storage::save::save_accounts(&disk)
+            .await
+            .expect("seed save");
+
+        let mut in_memory = AccountStorageV3::empty();
+        in_memory.accounts.push(account("rt-a", Some("a@x.com")));
+        in_memory.accounts.push(account("rt-b", Some("b@x.com")));
+        let deps = RepairDeps {
+            load_accounts: Box::new(move || {
+                let storage = in_memory.clone();
+                Box::pin(async move { Some(storage) })
+            }),
+            queued_refresh: Box::new(|token| {
+                Box::pin(async move {
+                    if token == "rt-a" {
+                        hard_failure()
+                    } else {
+                        TokenResult::Success(TokenSuccess {
+                            access: "new-access".to_string(),
+                            refresh: "rt-b".to_string(),
+                            expires: 99_999_999,
+                            id_token: None,
+                            multi_account: None,
+                        })
+                    }
+                })
+            }),
+            get_now: Some(Box::new(|| 1_000)),
+            ..RepairDeps::default()
+        };
+        let mut out = CliOut::capture();
+        let code = run_fix_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let saved = cma_storage::load::load_accounts()
+            .await
+            .expect("reload")
+            .storage;
+        // Disk slot 1 holds rt-a — the hard-disable must land THERE.
+        assert_eq!(saved.accounts[1].refresh_token, "rt-a");
+        assert_eq!(saved.accounts[1].enabled, Some(false));
+        assert_eq!(saved.accounts[0].refresh_token, "rt-b");
+        assert_eq!(saved.accounts[0].access_token.as_deref(), Some("new-access"));
+    }
+
+    #[test]
+    fn normalize_doctor_indexes_clamps_and_fills_families() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account("rt", None));
+        storage.active_index = 5;
+        assert!(normalize_doctor_indexes(&mut storage));
+        assert_eq!(storage.active_index, 0);
+        let by_family = storage.active_index_by_family.as_ref().expect("families");
+        for family in MODEL_FAMILIES {
+            assert_eq!(by_family.get(family), Some(0));
+        }
+        // Second run is a no-op.
+        assert!(!normalize_doctor_indexes(&mut storage));
+    }
+
+    #[test]
+    fn placeholder_and_token_key_helpers() {
+        assert!(has_placeholder_email(Some("Demo@Example.com ")));
+        assert!(!has_placeholder_email(Some("real@company.com")));
+        assert!(!has_placeholder_email(None));
+        assert_eq!(get_doctor_refresh_token_key("  "), None);
+        assert_eq!(get_doctor_refresh_token_key(" rt "), Some("rt".to_string()));
+    }
+}
diff --git a/crates/manager/src/repair/mod.rs b/crates/manager/src/repair/mod.rs
new file mode 100644
index 000000000..379fb512f
--- /dev/null
+++ b/crates/manager/src/repair/mod.rs
@@ -0,0 +1,4 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod doctor;
+pub mod fix;
+pub mod verify_flagged;
diff --git a/crates/manager/src/repair/verify_flagged.rs b/crates/manager/src/repair/verify_flagged.rs
new file mode 100644
index 000000000..00c23dfa0
--- /dev/null
+++ b/crates/manager/src/repair/verify_flagged.rs
@@ -0,0 +1,1222 @@
+//! Port of `lib/codex-manager/repair-commands.ts` — the `verify-flagged`
+//! command half.
+//!
+//! Behavior source: spec 09 §3.3. CRITICAL contracts:
+//! - refresh-checks run OUTSIDE the storage lock (phase 1); the apply phase
+//!   re-locates every flagged entry inside the transaction and SKIPS any
+//!   check whose flagged refresh token drifted on disk since phase 1
+//!   (`hasFlaggedRefreshTokenDrift`) with the frozen skip messages;
+//! - healthy accounts are restored into active storage by default
+//!   (`--no-restore` updates them in place instead);
+//! - the pool cap (20) turns a restore into `restore-skipped` and the
+//!   flagged entry keeps fresh tokens with `lastError` = the skip message;
+//! - always exits 0 after successful arg parsing.
+
+use cma_core::json_io::stringify_pretty2;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::schemas::flagged::{FlaggedAccountMetadataV1, FlaggedAccountStorageV1};
+use cma_core::schemas::token::{TokenResult, TokenSuccess};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_storage::matching::{
+    AccountMatchOptions, AccountSelectionCandidate, find_matching_account_index,
+};
+use serde_json::{Map, Value};
+
+use crate::dispatcher::CliOut;
+use crate::formatters::account::style_account_detail_text_with_tone;
+use crate::formatters::text_style::{
+    PromptTone, ResultSegment, format_result_summary, normalize_failure_detail, style_prompt_text,
+};
+use crate::repair::fix::{
+    RepairDeps, codex_error_message, create_empty_account_storage, normalize_doctor_indexes,
+};
+
+const MAX_ACCOUNTS: usize = cma_core::constants::ACCOUNT_LIMITS.max_accounts;
+
+// ============================================================================
+// Arg parsing
+// ============================================================================
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct VerifyFlaggedCliOptions {
+    dry_run: bool,
+    json: bool,
+    restore: bool,
+}
+
+fn print_verify_flagged_usage(out: &mut CliOut) {
+    out.info(
+        [
+            "Usage:",
+            "  codex-multi-auth verify-flagged [--dry-run] [--json] [--no-restore]",
+            "",
+            "Options:",
+            "  --dry-run, -n      Preview changes without writing storage",
+            "  --json, -j         Print machine-readable JSON output",
+            "  --no-restore       Check flagged accounts without restoring healthy ones",
+            "",
+            "Behavior:",
+            "  - Refresh-checks accounts from flagged storage",
+            "  - Restores healthy accounts back to active storage by default",
+        ]
+        .join("\n"),
+    );
+}
+
+fn parse_verify_flagged_args(args: &[String]) -> Result<VerifyFlaggedCliOptions, String> {
+    let mut options = VerifyFlaggedCliOptions {
+        dry_run: false,
+        json: false,
+        restore: true,
+    };
+    for arg in args {
+        match arg.as_str() {
+            "--dry-run" | "-n" => options.dry_run = true,
+            "--json" | "-j" => options.json = true,
+            "--no-restore" => options.restore = false,
+            other => return Err(format!("Unknown option: {other}")),
+        }
+    }
+    Ok(options)
+}
+
+// ============================================================================
+// Report / mutation shapes
+// ============================================================================
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum VerifyOutcome {
+    Restored,
+    HealthyFlagged,
+    StillFlagged,
+    RestoreSkipped,
+}
+
+impl VerifyOutcome {
+    fn as_str(self) -> &'static str {
+        match self {
+            VerifyOutcome::Restored => "restored",
+            VerifyOutcome::HealthyFlagged => "healthy-flagged",
+            VerifyOutcome::StillFlagged => "still-flagged",
+            VerifyOutcome::RestoreSkipped => "restore-skipped",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+struct VerifyFlaggedReport {
+    index: usize,
+    label: String,
+    outcome: VerifyOutcome,
+    message: String,
+}
+
+struct RefreshCheck {
+    index: usize,
+    flagged: FlaggedAccountMetadataV1,
+    label: String,
+    result: TokenResult,
+}
+
+struct FlaggedStorageMutation {
+    index: usize,
+    label: String,
+    before: FlaggedAccountMetadataV1,
+    after: Option<FlaggedAccountMetadataV1>,
+}
+
+// ============================================================================
+// Matching helpers (TS privates)
+// ============================================================================
+
+fn find_existing_account_index_for_flagged(
+    storage: &AccountStorageV3,
+    flagged: &FlaggedAccountMetadataV1,
+    next_refresh_token: &str,
+    next_account_id: Option<&str>,
+    next_email: Option<&str>,
+) -> Option<usize> {
+    let flagged_email = sanitize_email(flagged.email.as_deref());
+    let candidate_account_id = next_account_id
+        .map(str::to_string)
+        .or_else(|| flagged.account_id.clone());
+    let candidate_email = sanitize_email(next_email).or(flagged_email);
+    let options = AccountMatchOptions {
+        allow_unique_account_id_fallback_without_email: true,
+    };
+    let next_match_index = find_matching_account_index(
+        &storage.accounts,
+        &AccountSelectionCandidate {
+            account_id: candidate_account_id.clone(),
+            email: candidate_email.clone(),
+            refresh_token: Some(next_refresh_token.to_string()),
+        },
+        options,
+    );
+    if next_match_index.is_some() {
+        return next_match_index;
+    }
+
+    find_matching_account_index(
+        &storage.accounts,
+        &AccountSelectionCandidate {
+            account_id: candidate_account_id,
+            email: candidate_email,
+            refresh_token: Some(flagged.refresh_token.clone()),
+        },
+        options,
+    )
+}
+
+fn find_matching_flagged_account_index(
+    accounts: &[FlaggedAccountMetadataV1],
+    target: &FlaggedAccountMetadataV1,
+) -> Option<usize> {
+    let target_email = sanitize_email(target.email.as_deref());
+    accounts.iter().position(|account| {
+        if account.refresh_token == target.refresh_token {
+            return true;
+        }
+        if let Some(target_account_id) = &target.account_id
+            && account.account_id.as_ref() == Some(target_account_id)
+        {
+            let Some(target_email) = &target_email else {
+                return true;
+            };
+            return sanitize_email(account.email.as_deref()).as_ref() == Some(target_email);
+        }
+        target_email.is_some()
+            && sanitize_email(account.email.as_deref()) == target_email
+    })
+}
+
+fn find_flagged_account_index_by_stable_identity(
+    accounts: &[FlaggedAccountMetadataV1],
+    target: &FlaggedAccountMetadataV1,
+) -> Option<usize> {
+    let target_email = sanitize_email(target.email.as_deref());
+    accounts.iter().position(|account| {
+        if let Some(target_account_id) = &target.account_id
+            && account.account_id.as_ref() == Some(target_account_id)
+        {
+            let Some(target_email) = &target_email else {
+                return true;
+            };
+            return sanitize_email(account.email.as_deref()).as_ref() == Some(target_email);
+        }
+        target_email.is_some()
+            && sanitize_email(account.email.as_deref()) == target_email
+    })
+}
+
+fn has_flagged_refresh_token_drift(
+    accounts: &[FlaggedAccountMetadataV1],
+    target: &FlaggedAccountMetadataV1,
+) -> bool {
+    let Some(target_index) = find_flagged_account_index_by_stable_identity(accounts, target)
+    else {
+        return false;
+    };
+    accounts
+        .get(target_index)
+        .is_some_and(|current| current.refresh_token != target.refresh_token)
+}
+
+/// `formatAccountLabel(flagged, i)` — flagged entries are structurally
+/// V3-compatible in TS; Rust bridges via a local adapter because
+/// `AccountLabelSource` is only implemented for pool/managed accounts.
+struct FlaggedLabelSource<'a>(&'a FlaggedAccountMetadataV1);
+
+impl cma_accounts::manager_persistence::AccountLabelSource for FlaggedLabelSource<'_> {
+    fn label_email(&self) -> Option<&str> {
+        self.0.email.as_deref()
+    }
+    fn label_account_id(&self) -> Option<&str> {
+        self.0.account_id.as_deref()
+    }
+    fn label_account_label(&self) -> Option<&str> {
+        self.0.account_label.as_deref()
+    }
+    fn label_workspaces(&self) -> Option<&[cma_core::schemas::account_storage::Workspace]> {
+        self.0.workspaces.as_deref()
+    }
+    fn label_current_workspace_index(&self) -> Option<i64> {
+        self.0.current_workspace_index
+    }
+}
+
+fn flagged_account_label(flagged: &FlaggedAccountMetadataV1, index: usize) -> String {
+    let adapter = FlaggedLabelSource(flagged);
+    cma_accounts::manager_persistence::format_account_label(
+        Some(&adapter as &dyn cma_accounts::manager_persistence::AccountLabelSource),
+        index,
+    )
+}
+
+fn apply_flagged_storage_mutations(
+    flagged_storage: &mut FlaggedAccountStorageV1,
+    mutations: &[&FlaggedStorageMutation],
+) {
+    for mutation in mutations {
+        let Some(target_index) =
+            find_matching_flagged_account_index(&flagged_storage.accounts, &mutation.before)
+        else {
+            continue;
+        };
+        match &mutation.after {
+            Some(after) => {
+                flagged_storage.accounts[target_index] = after.clone();
+            }
+            None => {
+                flagged_storage.accounts.remove(target_index);
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Upsert (restore path)
+// ============================================================================
+
+struct UpsertResult {
+    restored: bool,
+    changed: bool,
+    message: String,
+}
+
+/// TS `upsertRecoveredFlaggedAccount(storage, flagged, refreshResult, now,
+/// deps)` — field-by-field update of an existing matching account, or a new
+/// pool entry when there is room. NEVER touches other accounts.
+fn upsert_recovered_flagged_account(
+    storage: &mut AccountStorageV3,
+    flagged: &FlaggedAccountMetadataV1,
+    refresh_result: &TokenSuccess,
+    now: i64,
+) -> UpsertResult {
+    let next_email = sanitize_email(
+        extract_account_email(
+            Some(&refresh_result.access),
+            refresh_result.id_token.as_deref(),
+        )
+        .as_deref(),
+    )
+    .or_else(|| flagged.email.clone());
+    let token_account_id = extract_account_id(Some(&refresh_result.access));
+    let next_identity = crate::login::account_credentials::resolve_stored_account_identity(
+        flagged.account_id.as_deref(),
+        flagged.account_id_source,
+        token_account_id.as_deref(),
+    );
+    let existing_index = find_existing_account_index_for_flagged(
+        storage,
+        flagged,
+        &refresh_result.refresh,
+        next_identity.account_id.as_deref(),
+        next_email.as_deref(),
+    );
+
+    if let Some(existing_index) = existing_index {
+        let Some(existing) = storage.accounts.get_mut(existing_index) else {
+            return UpsertResult {
+                restored: false,
+                changed: false,
+                message: "existing account entry is missing".to_string(),
+            };
+        };
+        let mut changed = false;
+        if existing.refresh_token != refresh_result.refresh {
+            existing.refresh_token = refresh_result.refresh.clone();
+            changed = true;
+        }
+        if existing.access_token.as_deref() != Some(refresh_result.access.as_str()) {
+            existing.access_token = Some(refresh_result.access.clone());
+            changed = true;
+        }
+        if existing.expires_at != Some(refresh_result.expires) {
+            existing.expires_at = Some(refresh_result.expires);
+            changed = true;
+        }
+        if let Some(next_email_value) = &next_email
+            && existing.email.as_deref() != Some(next_email_value.as_str())
+        {
+            existing.email = Some(next_email_value.clone());
+            changed = true;
+        }
+        if let Some(next_account_id) = &next_identity.account_id
+            && (existing.account_id.as_ref() != Some(next_account_id)
+                || existing.account_id_source != next_identity.account_id_source)
+        {
+            existing.account_id = Some(next_account_id.clone());
+            existing.account_id_source = next_identity.account_id_source;
+            changed = true;
+        }
+        if existing.enabled == Some(false) {
+            existing.enabled = Some(true);
+            changed = true;
+        }
+        if let Some(flagged_label) = &flagged.account_label
+            && existing.account_label.as_ref() != Some(flagged_label)
+        {
+            existing.account_label = Some(flagged_label.clone());
+            changed = true;
+        }
+        existing.last_used = now;
+        return UpsertResult {
+            restored: true,
+            changed,
+            message: format!("restored into existing account {}", existing_index + 1),
+        };
+    }
+
+    if storage.accounts.len() >= MAX_ACCOUNTS {
+        return UpsertResult {
+            restored: false,
+            changed: false,
+            message: format!("cannot restore (max {MAX_ACCOUNTS} accounts reached)"),
+        };
+    }
+
+    let mut account = AccountMetadataV3::new(refresh_result.refresh.clone(), flagged.added_at, now);
+    account.access_token = Some(refresh_result.access.clone());
+    account.expires_at = Some(refresh_result.expires);
+    account.account_id = next_identity.account_id;
+    account.account_id_source = next_identity.account_id_source;
+    account.account_label = flagged.account_label.clone();
+    account.email = next_email;
+    account.enabled = Some(true);
+    storage.accounts.push(account);
+    UpsertResult {
+        restored: true,
+        changed: true,
+        message: format!("restored as account {}", storage.accounts.len()),
+    }
+}
+
+// ============================================================================
+// runVerifyFlagged
+// ============================================================================
+
+/// Apply-phase accumulator (the TS closure-captured locals).
+struct ApplyState {
+    storage_changed: bool,
+    flagged_changed: bool,
+    reports: Vec<VerifyFlaggedReport>,
+    next_flagged_accounts: Vec<FlaggedAccountMetadataV1>,
+    flagged_mutations: Vec<FlaggedStorageMutation>,
+}
+
+/// TS closure `applyRefreshChecks(storage, refreshChecks)`.
+fn apply_refresh_checks(
+    state: &mut ApplyState,
+    storage: &mut AccountStorageV3,
+    refresh_checks: &[&RefreshCheck],
+    restore: bool,
+    now: i64,
+) {
+    for check in refresh_checks {
+        let i = check.index;
+        let flagged = &check.flagged;
+        let label = &check.label;
+        match &check.result {
+            TokenResult::Success(success) => {
+                if !restore {
+                    let token_account_id = extract_account_id(Some(&success.access));
+                    let next_identity =
+                        crate::login::account_credentials::resolve_stored_account_identity(
+                            flagged.account_id.as_deref(),
+                            flagged.account_id_source,
+                            token_account_id.as_deref(),
+                        );
+                    let mut next_flagged = flagged.clone();
+                    next_flagged.refresh_token = success.refresh.clone();
+                    next_flagged.access_token = Some(success.access.clone());
+                    next_flagged.expires_at = Some(success.expires);
+                    next_flagged.account_id = next_identity.account_id;
+                    next_flagged.account_id_source = next_identity.account_id_source;
+                    next_flagged.email = sanitize_email(
+                        extract_account_email(Some(&success.access), success.id_token.as_deref())
+                            .as_deref(),
+                    )
+                    .or_else(|| flagged.email.clone());
+                    next_flagged.last_used = now;
+                    next_flagged.last_error = None;
+                    if next_flagged != *flagged {
+                        state.flagged_changed = true;
+                    }
+                    state.next_flagged_accounts.push(next_flagged.clone());
+                    state.flagged_mutations.push(FlaggedStorageMutation {
+                        index: i,
+                        label: label.clone(),
+                        before: flagged.clone(),
+                        after: Some(next_flagged),
+                    });
+                    state.reports.push(VerifyFlaggedReport {
+                        index: i,
+                        label: label.clone(),
+                        outcome: VerifyOutcome::HealthyFlagged,
+                        message:
+                            "session is healthy (left in flagged list due to --no-restore)"
+                                .to_string(),
+                    });
+                    continue;
+                }
+
+                let upsert_result =
+                    upsert_recovered_flagged_account(storage, flagged, success, now);
+                if upsert_result.restored {
+                    state.storage_changed = state.storage_changed || upsert_result.changed;
+                    state.flagged_changed = true;
+                    state.flagged_mutations.push(FlaggedStorageMutation {
+                        index: i,
+                        label: label.clone(),
+                        before: flagged.clone(),
+                        after: None,
+                    });
+                    state.reports.push(VerifyFlaggedReport {
+                        index: i,
+                        label: label.clone(),
+                        outcome: VerifyOutcome::Restored,
+                        message: upsert_result.message,
+                    });
+                    continue;
+                }
+
+                let token_account_id = extract_account_id(Some(&success.access));
+                let next_identity =
+                    crate::login::account_credentials::resolve_stored_account_identity(
+                        flagged.account_id.as_deref(),
+                        flagged.account_id_source,
+                        token_account_id.as_deref(),
+                    );
+                let mut updated_flagged = flagged.clone();
+                updated_flagged.refresh_token = success.refresh.clone();
+                updated_flagged.access_token = Some(success.access.clone());
+                updated_flagged.expires_at = Some(success.expires);
+                updated_flagged.account_id = next_identity.account_id;
+                updated_flagged.account_id_source = next_identity.account_id_source;
+                updated_flagged.email = sanitize_email(
+                    extract_account_email(Some(&success.access), success.id_token.as_deref())
+                        .as_deref(),
+                )
+                .or_else(|| flagged.email.clone());
+                updated_flagged.last_used = now;
+                updated_flagged.last_error = Some(upsert_result.message.clone());
+                if updated_flagged != *flagged {
+                    state.flagged_changed = true;
+                }
+                state.next_flagged_accounts.push(updated_flagged.clone());
+                state.flagged_mutations.push(FlaggedStorageMutation {
+                    index: i,
+                    label: label.clone(),
+                    before: flagged.clone(),
+                    after: Some(updated_flagged),
+                });
+                state.reports.push(VerifyFlaggedReport {
+                    index: i,
+                    label: label.clone(),
+                    outcome: VerifyOutcome::RestoreSkipped,
+                    message: upsert_result.message,
+                });
+            }
+            TokenResult::Failed(failure) => {
+                let detail = normalize_failure_detail(
+                    failure.message.as_deref(),
+                    failure.reason.map(|reason| reason.as_str()),
+                );
+                let mut failed_flagged = flagged.clone();
+                failed_flagged.last_error = Some(detail.clone());
+                state.next_flagged_accounts.push(failed_flagged.clone());
+                if flagged.last_error.as_deref().unwrap_or("") != detail {
+                    state.flagged_changed = true;
+                }
+                state.flagged_mutations.push(FlaggedStorageMutation {
+                    index: i,
+                    label: label.clone(),
+                    before: flagged.clone(),
+                    after: Some(failed_flagged),
+                });
+                state.reports.push(VerifyFlaggedReport {
+                    index: i,
+                    label: label.clone(),
+                    outcome: VerifyOutcome::StillFlagged,
+                    message: detail,
+                });
+            }
+        }
+    }
+}
+
+/// Production entry (dispatcher + `verify --flagged` delegation).
+pub async fn run_verify_flagged(args: &[String], out: &mut CliOut) -> i32 {
+    run_verify_flagged_with(args, &RepairDeps::default(), out).await
+}
+
+/// TS `runVerifyFlagged(args, deps)` — always returns 0 after parse.
+pub async fn run_verify_flagged_with(
+    args: &[String],
+    deps: &RepairDeps,
+    out: &mut CliOut,
+) -> i32 {
+    if args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_verify_flagged_usage(out);
+        return 0;
+    }
+
+    let options = match parse_verify_flagged_args(args) {
+        Ok(options) => options,
+        Err(message) => {
+            out.error(message);
+            print_verify_flagged_usage(out);
+            return 1;
+        }
+    };
+
+    cma_storage::facade::set_storage_path(None);
+    let flagged_storage = (deps.load_flagged_accounts)().await;
+    if flagged_storage.accounts.is_empty() {
+        if options.json {
+            let mut payload = Map::new();
+            payload.insert("command".into(), Value::from("verify-flagged"));
+            payload.insert("total".into(), Value::from(0));
+            payload.insert("restored".into(), Value::from(0));
+            payload.insert("healthyFlagged".into(), Value::from(0));
+            payload.insert("stillFlagged".into(), Value::from(0));
+            payload.insert("remainingFlagged".into(), Value::from(0));
+            payload.insert("changed".into(), Value::from(false));
+            payload.insert("dryRun".into(), Value::from(options.dry_run));
+            payload.insert("restore".into(), Value::from(options.restore));
+            payload.insert("reports".into(), Value::Array(Vec::new()));
+            out.info(stringify_pretty2(&Value::Object(payload)));
+            return 0;
+        }
+        out.info("No flagged accounts to check.");
+        return 0;
+    }
+
+    let mut state = ApplyState {
+        storage_changed: false,
+        flagged_changed: false,
+        reports: Vec::new(),
+        next_flagged_accounts: Vec::new(),
+        flagged_mutations: Vec::new(),
+    };
+    let now = deps.now();
+
+    // Phase 1 (network, OUTSIDE the storage lock): refresh-check every
+    // flagged account sequentially.
+    let mut refresh_checks: Vec<RefreshCheck> = Vec::new();
+    for (i, flagged) in flagged_storage.accounts.iter().enumerate() {
+        let label = flagged_account_label(flagged, i);
+        let result = (deps.queued_refresh)(flagged.refresh_token.clone()).await;
+        refresh_checks.push(RefreshCheck {
+            index: i,
+            flagged: flagged.clone(),
+            label,
+            result,
+        });
+    }
+
+    let mut remaining_flagged = 0usize;
+
+    if options.restore {
+        if options.dry_run {
+            let mut throwaway = (deps.load_accounts)()
+                .await
+                .unwrap_or_else(create_empty_account_storage);
+            let all_checks: Vec<&RefreshCheck> = refresh_checks.iter().collect();
+            apply_refresh_checks(&mut state, &mut throwaway, &all_checks, true, now);
+        } else {
+            let state_ref = &mut state;
+            let remaining_ref = &mut remaining_flagged;
+            let checks_ref = &refresh_checks;
+            let transaction_result =
+                cma_storage::transactions::with_account_and_flagged_storage_transaction(
+                    move |loaded_storage, persist, loaded_flagged_storage| async move {
+                        let mut next_storage =
+                            loaded_storage.unwrap_or_else(create_empty_account_storage);
+                        let mut next_flagged_storage = loaded_flagged_storage;
+                        // Staleness guard: any check whose flagged refresh
+                        // token drifted on disk since phase 1 is skipped.
+                        let mut safe_refresh_checks: Vec<&RefreshCheck> = Vec::new();
+                        let mut stale_refresh_checks: Vec<&RefreshCheck> = Vec::new();
+                        for check in checks_ref {
+                            if has_flagged_refresh_token_drift(
+                                &next_flagged_storage.accounts,
+                                &check.flagged,
+                            ) {
+                                stale_refresh_checks.push(check);
+                            } else {
+                                safe_refresh_checks.push(check);
+                            }
+                        }
+                        apply_refresh_checks(
+                            state_ref,
+                            &mut next_storage,
+                            &safe_refresh_checks,
+                            true,
+                            now,
+                        );
+                        for check in stale_refresh_checks {
+                            state_ref.reports.push(VerifyFlaggedReport {
+                                index: check.index,
+                                label: check.label.clone(),
+                                outcome: VerifyOutcome::RestoreSkipped,
+                                message:
+                                    "Skipped restore because flagged refresh token changed before persistence"
+                                        .to_string(),
+                            });
+                        }
+                        let mutation_refs: Vec<&FlaggedStorageMutation> =
+                            state_ref.flagged_mutations.iter().collect();
+                        apply_flagged_storage_mutations(&mut next_flagged_storage, &mutation_refs);
+                        *remaining_ref = next_flagged_storage.accounts.len();
+                        if !state_ref.storage_changed && !state_ref.flagged_changed {
+                            return Ok(());
+                        }
+                        if state_ref.storage_changed {
+                            normalize_doctor_indexes(&mut next_storage);
+                        }
+                        persist.persist(&next_storage, &next_flagged_storage).await
+                    },
+                )
+                .await;
+            if let Err(error) = transaction_result {
+                // TS lets the transaction rejection propagate; the Rust
+                // surface reports it and exits 1.
+                out.error(codex_error_message(&error));
+                return 1;
+            }
+        }
+    } else {
+        let mut throwaway = create_empty_account_storage();
+        let all_checks: Vec<&RefreshCheck> = refresh_checks.iter().collect();
+        apply_refresh_checks(&mut state, &mut throwaway, &all_checks, false, now);
+        remaining_flagged = state.next_flagged_accounts.len();
+    }
+
+    if options.dry_run {
+        remaining_flagged = state.next_flagged_accounts.len();
+    }
+
+    if !options.dry_run && !options.restore && state.flagged_changed {
+        let state_ref = &mut state;
+        let remaining_ref = &mut remaining_flagged;
+        let transaction_result = cma_storage::transactions::with_flagged_storage_transaction(
+            move |loaded_flagged_storage, persist| async move {
+                let mut next_flagged_storage = loaded_flagged_storage;
+                let mut stale = vec![false; state_ref.flagged_mutations.len()];
+                for (slot, mutation) in state_ref.flagged_mutations.iter().enumerate() {
+                    stale[slot] = has_flagged_refresh_token_drift(
+                        &next_flagged_storage.accounts,
+                        &mutation.before,
+                    );
+                }
+                for (slot, mutation) in state_ref.flagged_mutations.iter().enumerate() {
+                    if !stale[slot] {
+                        continue;
+                    }
+                    if let Some(stale_report) = state_ref.reports.iter_mut().find(|report| {
+                        report.index == mutation.index && report.label == mutation.label
+                    }) {
+                        stale_report.outcome = VerifyOutcome::RestoreSkipped;
+                        stale_report.message =
+                            "Skipped flagged update because refresh token changed before persistence"
+                                .to_string();
+                        continue;
+                    }
+                    state_ref.reports.push(VerifyFlaggedReport {
+                        index: mutation.index,
+                        label: mutation.label.clone(),
+                        outcome: VerifyOutcome::RestoreSkipped,
+                        message:
+                            "Skipped flagged update because refresh token changed before persistence"
+                                .to_string(),
+                    });
+                }
+                let safe_flagged_mutations: Vec<&FlaggedStorageMutation> = state_ref
+                    .flagged_mutations
+                    .iter()
+                    .enumerate()
+                    .filter(|(slot, _)| !stale[*slot])
+                    .map(|(_, mutation)| mutation)
+                    .collect();
+                apply_flagged_storage_mutations(&mut next_flagged_storage, &safe_flagged_mutations);
+                *remaining_ref = next_flagged_storage.accounts.len();
+                if safe_flagged_mutations.is_empty() {
+                    state_ref.flagged_changed = false;
+                    return Ok(());
+                }
+                persist.persist(&next_flagged_storage).await
+            },
+        )
+        .await;
+        if let Err(error) = transaction_result {
+            out.error(codex_error_message(&error));
+            return 1;
+        }
+    }
+
+    let restored = state
+        .reports
+        .iter()
+        .filter(|report| report.outcome == VerifyOutcome::Restored)
+        .count();
+    let healthy_flagged = state
+        .reports
+        .iter()
+        .filter(|report| report.outcome == VerifyOutcome::HealthyFlagged)
+        .count();
+    let still_flagged = state
+        .reports
+        .iter()
+        .filter(|report| report.outcome == VerifyOutcome::StillFlagged)
+        .count();
+    let changed = state.storage_changed || state.flagged_changed;
+
+    if options.json {
+        let mut payload = Map::new();
+        payload.insert("command".into(), Value::from("verify-flagged"));
+        payload.insert(
+            "total".into(),
+            Value::from(flagged_storage.accounts.len() as i64),
+        );
+        payload.insert("restored".into(), Value::from(restored as i64));
+        payload.insert("healthyFlagged".into(), Value::from(healthy_flagged as i64));
+        payload.insert("stillFlagged".into(), Value::from(still_flagged as i64));
+        payload.insert(
+            "remainingFlagged".into(),
+            Value::from(remaining_flagged as i64),
+        );
+        payload.insert("changed".into(), Value::from(changed));
+        payload.insert("dryRun".into(), Value::from(options.dry_run));
+        payload.insert("restore".into(), Value::from(options.restore));
+        payload.insert(
+            "reports".into(),
+            Value::Array(
+                state
+                    .reports
+                    .iter()
+                    .map(|report| {
+                        let mut row = Map::new();
+                        row.insert("index".into(), Value::from(report.index as i64));
+                        row.insert("label".into(), Value::from(report.label.clone()));
+                        row.insert("outcome".into(), Value::from(report.outcome.as_str()));
+                        row.insert("message".into(), Value::from(report.message.clone()));
+                        Value::Object(row)
+                    })
+                    .collect(),
+            ),
+        );
+        out.info(stringify_pretty2(&Value::Object(payload)));
+        return 0;
+    }
+
+    out.info(style_prompt_text(
+        &format!(
+            "Checking {} flagged account(s)...",
+            flagged_storage.accounts.len()
+        ),
+        PromptTone::Accent,
+    ));
+    for report in &state.reports {
+        let tone = match report.outcome {
+            VerifyOutcome::Restored => PromptTone::Success,
+            VerifyOutcome::HealthyFlagged | VerifyOutcome::RestoreSkipped => PromptTone::Warning,
+            VerifyOutcome::StillFlagged => PromptTone::Danger,
+        };
+        let marker = match report.outcome {
+            VerifyOutcome::Restored => "✓",
+            VerifyOutcome::HealthyFlagged | VerifyOutcome::RestoreSkipped => "!",
+            VerifyOutcome::StillFlagged => "✗",
+        };
+        out.info(format!(
+            "{} {} {} {}",
+            style_prompt_text(marker, tone),
+            style_prompt_text(
+                &format!("{}. {}", report.index + 1, report.label),
+                PromptTone::Accent
+            ),
+            style_prompt_text("|", PromptTone::Muted),
+            style_account_detail_text_with_tone(&report.message, tone),
+        ));
+    }
+    out.info("");
+    out.info(format_result_summary(&[
+        ResultSegment::new(
+            format!("{restored} restored"),
+            if restored > 0 {
+                PromptTone::Success
+            } else {
+                PromptTone::Muted
+            },
+        ),
+        ResultSegment::new(
+            format!("{healthy_flagged} healthy (kept flagged)"),
+            if healthy_flagged > 0 {
+                PromptTone::Warning
+            } else {
+                PromptTone::Muted
+            },
+        ),
+        ResultSegment::new(
+            format!("{still_flagged} still flagged"),
+            if still_flagged > 0 {
+                PromptTone::Danger
+            } else {
+                PromptTone::Muted
+            },
+        ),
+    ]));
+    if options.dry_run {
+        out.info(style_prompt_text(
+            "Preview only: no changes were saved.",
+            PromptTone::Warning,
+        ));
+    } else if !changed {
+        out.info(style_prompt_text(
+            "No storage changes were needed.",
+            PromptTone::Muted,
+        ));
+    }
+
+    0
+}
+
+// ============================================================================
+// Tests — ported from test/repair-commands.test.ts and
+// test/runtime-verify-flagged.test.ts (verify-flagged halves)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenFailure;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn flagged(refresh: &str, email: Option<&str>) -> FlaggedAccountMetadataV1 {
+        let mut account = AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        FlaggedAccountMetadataV1::from_account(account, 2, Some("test".to_string()), None)
+    }
+
+    fn success(refresh: &str, access: &str) -> TokenResult {
+        TokenResult::Success(TokenSuccess {
+            access: access.to_string(),
+            refresh: refresh.to_string(),
+            expires: 99_999_999,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    fn failure(message: &str) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: None,
+            status_code: Some(400),
+            message: Some(message.to_string()),
+        })
+    }
+
+    fn deps_with_refresh(
+        result: impl Fn(String) -> TokenResult + Send + Sync + 'static,
+    ) -> RepairDeps {
+        RepairDeps {
+            queued_refresh: Box::new(move |token| {
+                let result = result(token);
+                Box::pin(async move { result })
+            }),
+            get_now: Some(Box::new(|| 5_000)),
+            ..RepairDeps::default()
+        }
+    }
+
+    async fn seed_flagged(storage: &FlaggedAccountStorageV1) {
+        cma_storage::facade::set_storage_path(None);
+        cma_storage::flagged::save_flagged_accounts(storage)
+            .await
+            .expect("seed flagged");
+    }
+
+    // Empty flagged storage emits the exact JSON skeleton and exits 0.
+    #[tokio::test]
+    #[serial(env)]
+    async fn empty_flagged_json_skeleton_is_exact() {
+        let _sandbox = EnvSandbox::new();
+        let deps = RepairDeps::default();
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json", "--dry-run"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        let keys: Vec<&str> = payload
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(String::as_str)
+            .collect();
+        assert_eq!(
+            keys,
+            vec![
+                "command",
+                "total",
+                "restored",
+                "healthyFlagged",
+                "stillFlagged",
+                "remainingFlagged",
+                "changed",
+                "dryRun",
+                "restore",
+                "reports"
+            ]
+        );
+        assert_eq!(payload["command"], Value::from("verify-flagged"));
+        assert_eq!(payload["remainingFlagged"], Value::from(0));
+        assert_eq!(payload["dryRun"], Value::from(true));
+        assert_eq!(payload["restore"], Value::from(true));
+    }
+
+    // Healthy flagged accounts are restored into active storage and removed
+    // from the flagged list.
+    #[tokio::test]
+    #[serial(env)]
+    async fn restores_healthy_flagged_account_into_pool() {
+        let _sandbox = EnvSandbox::new();
+        let mut flagged_storage = FlaggedAccountStorageV1::empty();
+        flagged_storage
+            .accounts
+            .push(flagged("rt-flagged", Some("a@x.com")));
+        seed_flagged(&flagged_storage).await;
+
+        let deps = deps_with_refresh(|_| success("rt-new", "access-new"));
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["restored"], Value::from(1));
+        assert_eq!(payload["remainingFlagged"], Value::from(0));
+        assert_eq!(payload["changed"], Value::from(true));
+        assert_eq!(
+            payload["reports"][0]["message"],
+            Value::from("restored as account 1")
+        );
+
+        let accounts = cma_storage::load::load_accounts()
+            .await
+            .expect("accounts")
+            .storage;
+        assert_eq!(accounts.accounts.len(), 1);
+        assert_eq!(accounts.accounts[0].refresh_token, "rt-new");
+        assert_eq!(accounts.accounts[0].enabled, Some(true));
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert!(remaining.accounts.is_empty());
+    }
+
+    // --no-restore keeps the healthy account flagged but refreshes it in
+    // place (lastError cleared).
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_restore_updates_flagged_entry_in_place() {
+        let _sandbox = EnvSandbox::new();
+        let mut flagged_storage = FlaggedAccountStorageV1::empty();
+        let mut entry = flagged("rt-flagged", Some("a@x.com"));
+        entry.last_error = Some("old error".to_string());
+        flagged_storage.accounts.push(entry);
+        seed_flagged(&flagged_storage).await;
+
+        let deps = deps_with_refresh(|_| success("rt-new", "access-new"));
+        let mut out = CliOut::capture();
+        let code =
+            run_verify_flagged_with(&args(&["--json", "--no-restore"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["healthyFlagged"], Value::from(1));
+        assert_eq!(payload["restored"], Value::from(0));
+        assert_eq!(payload["remainingFlagged"], Value::from(1));
+        assert_eq!(
+            payload["reports"][0]["message"],
+            Value::from("session is healthy (left in flagged list due to --no-restore)")
+        );
+
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert_eq!(remaining.accounts.len(), 1);
+        assert_eq!(remaining.accounts[0].refresh_token, "rt-new");
+        assert_eq!(remaining.accounts[0].last_error, None);
+        // No account was restored into the pool.
+        assert_eq!(
+            cma_storage::load::load_accounts()
+                .await
+                .map(|loaded| loaded.storage.accounts.len())
+                .unwrap_or(0),
+            0
+        );
+    }
+
+    // Failed refreshes stay flagged with lastError = normalized detail.
+    #[tokio::test]
+    #[serial(env)]
+    async fn failed_refresh_records_last_error() {
+        let _sandbox = EnvSandbox::new();
+        let mut flagged_storage = FlaggedAccountStorageV1::empty();
+        flagged_storage
+            .accounts
+            .push(flagged("rt-flagged", Some("a@x.com")));
+        seed_flagged(&flagged_storage).await;
+
+        let deps = deps_with_refresh(|_| failure("invalid_grant"));
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["stillFlagged"], Value::from(1));
+        assert_eq!(payload["remainingFlagged"], Value::from(1));
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert!(remaining.accounts[0].last_error.is_some());
+    }
+
+    // Staleness guard: a flagged refresh token that changed on disk between
+    // phase 1 and the transaction skips the restore with the frozen message.
+    #[tokio::test]
+    #[serial(env)]
+    async fn skips_stale_restores_when_flagged_token_drifted() {
+        let _sandbox = EnvSandbox::new();
+        // Disk state has the DRIFTED token.
+        let mut disk_flagged = FlaggedAccountStorageV1::empty();
+        disk_flagged
+            .accounts
+            .push(flagged("rt-drifted", Some("a@x.com")));
+        seed_flagged(&disk_flagged).await;
+
+        // Phase 1 sees the STALE snapshot via the injected loader.
+        let mut stale_flagged = FlaggedAccountStorageV1::empty();
+        stale_flagged
+            .accounts
+            .push(flagged("rt-stale", Some("a@x.com")));
+        let deps = RepairDeps {
+            load_flagged_accounts: Box::new(move || {
+                let storage = stale_flagged.clone();
+                Box::pin(async move { storage })
+            }),
+            queued_refresh: Box::new(|_| {
+                Box::pin(async { success("rt-new", "access-new") })
+            }),
+            get_now: Some(Box::new(|| 5_000)),
+            ..RepairDeps::default()
+        };
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["restored"], Value::from(0));
+        assert_eq!(
+            payload["reports"][0]["outcome"],
+            Value::from("restore-skipped")
+        );
+        assert_eq!(
+            payload["reports"][0]["message"],
+            Value::from("Skipped restore because flagged refresh token changed before persistence")
+        );
+        // Disk flagged entry is untouched.
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert_eq!(remaining.accounts[0].refresh_token, "rt-drifted");
+        assert_eq!(
+            cma_storage::load::load_accounts()
+                .await
+                .map(|loaded| loaded.storage.accounts.len())
+                .unwrap_or(0),
+            0
+        );
+    }
+
+    // Pool cap: with 20 accounts the restore is skipped and the flagged
+    // entry keeps fresh tokens with lastError = the skip message.
+    #[tokio::test]
+    #[serial(env)]
+    async fn full_pool_skips_restore_with_frozen_message() {
+        let _sandbox = EnvSandbox::new();
+        cma_storage::facade::set_storage_path(None);
+        let mut pool = AccountStorageV3::empty();
+        for i in 0..MAX_ACCOUNTS {
+            pool.accounts
+                .push(AccountMetadataV3::new(format!("rt-{i}"), 1, 1));
+        }
+        cma_storage::save::save_accounts(&pool).await.expect("seed pool");
+        let mut flagged_storage = FlaggedAccountStorageV1::empty();
+        flagged_storage
+            .accounts
+            .push(flagged("rt-flagged", Some("solo@x.com")));
+        seed_flagged(&flagged_storage).await;
+
+        let deps = deps_with_refresh(|_| success("rt-new", "access-new"));
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["restored"], Value::from(0));
+        assert_eq!(
+            payload["reports"][0]["outcome"],
+            Value::from("restore-skipped")
+        );
+        assert_eq!(
+            payload["reports"][0]["message"],
+            Value::from("cannot restore (max 20 accounts reached)")
+        );
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert_eq!(remaining.accounts.len(), 1);
+        assert_eq!(remaining.accounts[0].refresh_token, "rt-new");
+        assert_eq!(
+            remaining.accounts[0].last_error.as_deref(),
+            Some("cannot restore (max 20 accounts reached)")
+        );
+        // Pool unchanged (never exceeds the cap).
+        let accounts = cma_storage::load::load_accounts()
+            .await
+            .expect("accounts")
+            .storage;
+        assert_eq!(accounts.accounts.len(), MAX_ACCOUNTS);
+    }
+
+    // Dry-run previews without writing either store.
+    #[tokio::test]
+    #[serial(env)]
+    async fn dry_run_writes_nothing() {
+        let _sandbox = EnvSandbox::new();
+        let mut flagged_storage = FlaggedAccountStorageV1::empty();
+        flagged_storage
+            .accounts
+            .push(flagged("rt-flagged", Some("a@x.com")));
+        seed_flagged(&flagged_storage).await;
+
+        let deps = deps_with_refresh(|_| success("rt-new", "access-new"));
+        let mut out = CliOut::capture();
+        let code = run_verify_flagged_with(&args(&["--json", "--dry-run"]), &deps, &mut out).await;
+        assert_eq!(code, 0);
+        let payload: Value = serde_json::from_str(&out.info_text()).expect("json");
+        assert_eq!(payload["dryRun"], Value::from(true));
+        assert_eq!(payload["restored"], Value::from(1));
+        let remaining = cma_storage::flagged::load_flagged_accounts().await;
+        assert_eq!(remaining.accounts.len(), 1);
+        assert_eq!(remaining.accounts[0].refresh_token, "rt-flagged");
+        assert_eq!(
+            cma_storage::load::load_accounts()
+                .await
+                .map(|loaded| loaded.storage.accounts.len())
+                .unwrap_or(0),
+            0
+        );
+    }
+
+    #[test]
+    fn parse_rejects_unknown_options() {
+        assert_eq!(
+            parse_verify_flagged_args(&args(&["--bogus"])),
+            Err("Unknown option: --bogus".to_string())
+        );
+        let options =
+            parse_verify_flagged_args(&args(&["-n", "-j", "--no-restore"])).unwrap();
+        assert!(options.dry_run && options.json && !options.restore);
+    }
+}
diff --git a/crates/manager/src/settings/backend.rs b/crates/manager/src/settings/backend.rs
new file mode 100644
index 000000000..9d29fe146
--- /dev/null
+++ b/crates/manager/src/settings/backend.rs
@@ -0,0 +1,920 @@
+//! Port of `settings-hub/backend.ts` + `backend-settings-{controller,helpers,
+//! prompt}.ts` + `backend-category-{helpers,prompt}.ts` (entry shims
+//! absorbed) — the backend settings hub, category editor, and the pure
+//! helpers around `PluginConfig`.
+
+use std::cell::RefCell;
+
+use cma_core::schemas::plugin_config::{FallbackChain, PluginConfig};
+use cma_tui::runtime_options::{get_ui_runtime_options, UiRuntimeOptions};
+use cma_tui::select::{select, MenuColor, MenuItem, SelectInputResult, SelectOptions};
+use cma_tui::ui_copy;
+use serde_json::{Map, Number, Value};
+
+use crate::settings::hub::{clamp_backend_number, format_dashboard_setting_state, is_tty_interactive};
+use crate::settings::persist::persist_backend_config_selection;
+use crate::settings::preview::highlight_preview_token;
+use crate::settings::schema::{
+    backend_defaults, backend_number_option_by_key, backend_toggle_option_by_key,
+    BackendCategoryConfigAction, BackendCategoryKey, BackendCategoryOption,
+    BackendNumberSettingKey, BackendNumberSettingOption, BackendNumberUnit,
+    BackendSettingFocusKey, BackendSettingsHubAction, BACKEND_CATEGORY_OPTIONS,
+    BACKEND_NUMBER_OPTIONS, BACKEND_TOGGLE_OPTIONS,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers (`backend-settings-helpers.ts`)
+// ---------------------------------------------------------------------------
+
+/// `cloneBackendPluginConfig(config)` — `{...BACKEND_DEFAULTS, ...config}`
+/// plus a shallow copy of `unsupportedCodexFallbackChain` (defaults to `{}`
+/// when absent). NOTE: the clone materializes ALL defaults into the object.
+pub fn clone_backend_plugin_config(config: &PluginConfig) -> PluginConfig {
+    let mut clone = PluginConfig::overlay(&backend_defaults(), config);
+    clone.unsupported_codex_fallback_chain = Some(
+        config
+            .unsupported_codex_fallback_chain
+            .clone()
+            .unwrap_or_default(),
+    );
+    clone
+}
+
+/// `backendSettingsSnapshot(config)` — plain record of all 27 schema keys
+/// with `config[key] ?? defaults[key] ?? (false | option.min)`.
+pub fn backend_settings_snapshot(config: &PluginConfig) -> Map<String, Value> {
+    let defaults = backend_defaults();
+    let mut snapshot = Map::new();
+    for option in &BACKEND_TOGGLE_OPTIONS {
+        let value = option
+            .key
+            .get(config)
+            .or_else(|| option.key.get(&defaults))
+            .unwrap_or(false);
+        snapshot.insert(option.key.as_str().to_string(), Value::Bool(value));
+    }
+    for option in &BACKEND_NUMBER_OPTIONS {
+        let value = option
+            .key
+            .get(config)
+            .or_else(|| option.key.get(&defaults))
+            .unwrap_or(option.min);
+        let number = if value.fract() == 0.0 && value.is_finite() {
+            Number::from(value as i64)
+        } else {
+            Number::from_f64(value).unwrap_or_else(|| Number::from(0))
+        };
+        snapshot.insert(option.key.as_str().to_string(), Value::Number(number));
+    }
+    snapshot
+}
+
+/// `backendSettingsEqual` — snapshot comparison over ONLY schema-managed keys.
+pub fn backend_settings_equal(left: &PluginConfig, right: &PluginConfig) -> bool {
+    backend_settings_snapshot(left) == backend_settings_snapshot(right)
+}
+
+/// `formatBackendNumberValue(option, value)` — percent → `N%`; count → `N`;
+/// ms → `Nm`/`Ns`/`Nms` by divisibility.
+pub fn format_backend_number_value(option: &BackendNumberSettingOption, value: f64) -> String {
+    match option.unit {
+        BackendNumberUnit::Percent => format!("{}%", value.round() as i64),
+        BackendNumberUnit::Count => format!("{}", value.round() as i64),
+        BackendNumberUnit::Ms => {
+            let ms = value;
+            if ms >= 60_000.0 && ms % 60_000.0 == 0.0 {
+                format!("{}m", (ms / 60_000.0).round() as i64)
+            } else if ms >= 1_000.0 && ms % 1_000.0 == 0.0 {
+                format!("{}s", (ms / 1_000.0).round() as i64)
+            } else {
+                format!("{}ms", ms.round() as i64)
+            }
+        }
+    }
+}
+
+/// `clampBackendNumberForTests(settingKey, value)` — string-keyed clamp;
+/// unknown key → `Err("Unknown backend numeric setting key: <key>")` (thrown
+/// in TS).
+pub fn clamp_backend_number_for_tests(setting_key: &str, value: f64) -> Result<f64, String> {
+    let option = BACKEND_NUMBER_OPTIONS
+        .iter()
+        .find(|option| option.key.as_str() == setting_key)
+        .ok_or_else(|| format!("Unknown backend numeric setting key: {setting_key}"))?;
+    Ok(clamp_backend_number(option, value))
+}
+
+/// `buildBackendSettingsPreview(config, ui, focus, {highlightPreviewToken})`.
+pub fn build_backend_settings_preview(
+    config: &PluginConfig,
+    ui: &UiRuntimeOptions,
+    focus: Option<BackendSettingFocusKey>,
+    highlight: &dyn Fn(&str, &UiRuntimeOptions) -> String,
+) -> (String, String) {
+    use crate::settings::schema::{BackendNumberSettingKey as N, BackendToggleSettingKey as T};
+    let defaults = backend_defaults();
+    let toggle = |key: T, fallback: bool| -> bool {
+        key.get(config).or_else(|| key.get(&defaults)).unwrap_or(fallback)
+    };
+    let number = |key: N, fallback: f64| -> f64 {
+        key.get(config).or_else(|| key.get(&defaults)).unwrap_or(fallback)
+    };
+    let live_sync = toggle(T::LiveAccountSync, true);
+    let affinity = toggle(T::SessionAffinity, true);
+    let preemptive = toggle(T::PreemptiveQuotaEnabled, true);
+    let threshold_5h = number(N::PreemptiveQuotaRemainingPercent5h, 5.0);
+    let threshold_7d = number(N::PreemptiveQuotaRemainingPercent7d, 5.0);
+    let fetch_timeout = number(N::FetchTimeoutMs, 60_000.0);
+    let stall_timeout = number(N::StreamStallTimeoutMs, 45_000.0);
+    let fetch_option = backend_number_option_by_key(N::FetchTimeoutMs);
+    let stall_option = backend_number_option_by_key(N::StreamStallTimeoutMs);
+
+    let highlight_if = |key: BackendSettingFocusKey, text: String| -> String {
+        if focus == Some(key) {
+            highlight(&text, ui)
+        } else {
+            text
+        }
+    };
+    let on_off = |value: bool| if value { "on" } else { "off" }.to_string();
+
+    let label = [
+        format!(
+            "live sync {}",
+            highlight_if(
+                BackendSettingFocusKey::Toggle(T::LiveAccountSync),
+                on_off(live_sync)
+            )
+        ),
+        format!(
+            "affinity {}",
+            highlight_if(
+                BackendSettingFocusKey::Toggle(T::SessionAffinity),
+                on_off(affinity)
+            )
+        ),
+        format!(
+            "preemptive {}",
+            highlight_if(
+                BackendSettingFocusKey::Toggle(T::PreemptiveQuotaEnabled),
+                on_off(preemptive)
+            )
+        ),
+    ]
+    .join(" | ");
+
+    let hint = [
+        format!(
+            "thresholds 5h<={}",
+            highlight_if(
+                BackendSettingFocusKey::Number(N::PreemptiveQuotaRemainingPercent5h),
+                format!("{}%", format_js_number(threshold_5h))
+            )
+        ),
+        format!(
+            "7d<={}",
+            highlight_if(
+                BackendSettingFocusKey::Number(N::PreemptiveQuotaRemainingPercent7d),
+                format!("{}%", format_js_number(threshold_7d))
+            )
+        ),
+        format!(
+            "timeouts {}/{}",
+            highlight_if(
+                BackendSettingFocusKey::Number(N::FetchTimeoutMs),
+                format_backend_number_value(fetch_option, fetch_timeout)
+            ),
+            highlight_if(
+                BackendSettingFocusKey::Number(N::StreamStallTimeoutMs),
+                format_backend_number_value(stall_option, stall_timeout)
+            )
+        ),
+    ]
+    .join(" | ");
+
+    (label, hint)
+}
+
+/// Print a JS number without a trailing `.0` for integral values (template
+/// literal `${threshold5h}` parity).
+fn format_js_number(value: f64) -> String {
+    cma_core::json_io::format_js_number(value)
+}
+
+/// `buildBackendConfigPatch(config)` — only present booleans for toggle keys,
+/// only finite numbers (clamped) for number keys; nothing else. This is the
+/// full `savePluginConfig` patch — non-schema plugin config keys are never
+/// rewritten by the settings hub.
+pub fn build_backend_config_patch(config: &PluginConfig) -> Map<String, Value> {
+    let mut patch = Map::new();
+    for option in &BACKEND_TOGGLE_OPTIONS {
+        if let Some(value) = option.key.get(config) {
+            patch.insert(option.key.as_str().to_string(), Value::Bool(value));
+        }
+    }
+    for option in &BACKEND_NUMBER_OPTIONS {
+        if let Some(value) = option.key.get(config)
+            && value.is_finite() {
+                let clamped = clamp_backend_number(option, value);
+                let number = if clamped.fract() == 0.0 {
+                    Number::from(clamped as i64)
+                } else {
+                    Number::from_f64(clamped).unwrap_or_else(|| Number::from(0))
+                };
+                patch.insert(option.key.as_str().to_string(), Value::Number(number));
+            }
+    }
+    patch
+}
+
+// ---------------------------------------------------------------------------
+// Category helpers (`backend-category-helpers.ts`)
+// ---------------------------------------------------------------------------
+
+/// `resolveFocusedBackendNumberKey(focus, numberOptions)`.
+pub fn resolve_focused_backend_number_key(
+    focus: Option<BackendSettingFocusKey>,
+    number_options: &[&'static BackendNumberSettingOption],
+) -> BackendNumberSettingKey {
+    if let Some(BackendSettingFocusKey::Number(key)) = focus
+        && number_options.iter().any(|option| option.key == key) {
+            return key;
+        }
+    number_options
+        .first()
+        .map(|option| option.key)
+        .unwrap_or(BackendNumberSettingKey::FetchTimeoutMs)
+}
+
+/// `getBackendCategory(key, categoryOptions)`.
+pub fn get_backend_category(
+    key: BackendCategoryKey,
+    category_options: &'static [BackendCategoryOption],
+) -> Option<&'static BackendCategoryOption> {
+    category_options.iter().find(|category| category.key == key)
+}
+
+/// `getBackendCategoryInitialFocus(category)` — first toggle, else first
+/// number, else `None`.
+pub fn get_backend_category_initial_focus(
+    category: &BackendCategoryOption,
+) -> Option<BackendSettingFocusKey> {
+    if let Some(first_toggle) = category.toggle_keys.first() {
+        return Some(BackendSettingFocusKey::Toggle(*first_toggle));
+    }
+    category
+        .number_keys
+        .first()
+        .map(|key| BackendSettingFocusKey::Number(*key))
+}
+
+/// `applyBackendCategoryDefaults(draft, category, deps)` — resets ONLY the
+/// category's keys to `defaults[key] ?? false` / `defaults[key] ?? option.min`.
+pub fn apply_backend_category_defaults(
+    draft: &PluginConfig,
+    category: &BackendCategoryOption,
+) -> PluginConfig {
+    let defaults = backend_defaults();
+    let mut next = draft.clone();
+    for key in category.toggle_keys {
+        key.set(&mut next, Some(key.get(&defaults).unwrap_or(false)));
+    }
+    for key in category.number_keys {
+        let option = backend_number_option_by_key(*key);
+        key.set(&mut next, Some(key.get(&defaults).unwrap_or(option.min)));
+    }
+    next
+}
+
+// ---------------------------------------------------------------------------
+// Category editor (`backend-category-prompt.ts`)
+// ---------------------------------------------------------------------------
+
+/// Result of the category editor: the (possibly edited) draft plus the last
+/// focused setting; edits are KEPT on back — save/cancel semantics live at
+/// the hub level (spec 09 gotcha 23).
+pub struct BackendCategoryPromptResult {
+    pub draft: PluginConfig,
+    pub focus_key: Option<BackendSettingFocusKey>,
+}
+
+/// `promptBackendCategorySettingsMenu` — one category's editor.
+pub fn prompt_backend_category_settings(
+    initial: &PluginConfig,
+    category: &'static BackendCategoryOption,
+    initial_focus: Option<BackendSettingFocusKey>,
+) -> BackendCategoryPromptResult {
+    let ui = get_ui_runtime_options();
+    let defaults = backend_defaults();
+    let mut draft = clone_backend_plugin_config(initial);
+
+    let belongs_to_category = |focus: BackendSettingFocusKey| -> bool {
+        match focus {
+            BackendSettingFocusKey::Toggle(key) => category.toggle_keys.contains(&key),
+            BackendSettingFocusKey::Number(key) => category.number_keys.contains(&key),
+        }
+    };
+    let mut focus_key = match initial_focus {
+        Some(focus) if belongs_to_category(focus) => Some(focus),
+        _ => get_backend_category_initial_focus(category),
+    };
+
+    let toggle_options: Vec<_> = category
+        .toggle_keys
+        .iter()
+        .map(|key| backend_toggle_option_by_key(*key))
+        .collect();
+    let number_options: Vec<&'static BackendNumberSettingOption> = category
+        .number_keys
+        .iter()
+        .map(|key| backend_number_option_by_key(*key))
+        .collect();
+
+    loop {
+        let (preview_label, preview_hint) =
+            build_backend_settings_preview(&draft, &ui, focus_key, &|text, ui| {
+                highlight_preview_token(text, ui)
+            });
+
+        let mut items: Vec<MenuItem<BackendCategoryConfigAction>> = vec![
+            MenuItem::heading(
+                ui_copy::settings::PREVIEW_HEADING,
+                BackendCategoryConfigAction::Back,
+            ),
+            {
+                let mut item = MenuItem::new(preview_label, BackendCategoryConfigAction::Back)
+                    .with_hint(preview_hint)
+                    .with_color(MenuColor::Green);
+                item.disabled = true;
+                item.hide_unavailable_suffix = true;
+                item
+            },
+            MenuItem::separator(BackendCategoryConfigAction::Back),
+            MenuItem::heading(
+                ui_copy::settings::BACKEND_TOGGLE_HEADING,
+                BackendCategoryConfigAction::Back,
+            ),
+        ];
+        for (index, option) in toggle_options.iter().enumerate() {
+            let enabled = option
+                .key
+                .get(&draft)
+                .or_else(|| option.key.get(&defaults))
+                .unwrap_or(false);
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}. {}",
+                        format_dashboard_setting_state(enabled),
+                        index + 1,
+                        option.label
+                    ),
+                    BackendCategoryConfigAction::Toggle(option.key),
+                )
+                .with_hint(option.description)
+                .with_color(if enabled {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        items.push(MenuItem::separator(BackendCategoryConfigAction::Back));
+        items.push(MenuItem::heading(
+            ui_copy::settings::BACKEND_NUMBER_HEADING,
+            BackendCategoryConfigAction::Back,
+        ));
+        for option in &number_options {
+            let raw_value = option
+                .key
+                .get(&draft)
+                .or_else(|| option.key.get(&defaults))
+                .unwrap_or(option.min);
+            let numeric = if raw_value.is_finite() {
+                raw_value
+            } else {
+                option.min
+            };
+            let clamped = clamp_backend_number(option, numeric);
+            let value_label = format_backend_number_value(option, clamped);
+            items.push(
+                MenuItem::new(
+                    format!("{}: {}", option.label, value_label),
+                    BackendCategoryConfigAction::Bump {
+                        key: option.key,
+                        direction: 1,
+                    },
+                )
+                .with_hint(format!(
+                    "{} Step {}.",
+                    option.description,
+                    format_backend_number_value(option, option.step)
+                ))
+                .with_color(MenuColor::Yellow),
+            );
+        }
+
+        let focused_number_key = resolve_focused_backend_number_key(focus_key, &number_options);
+        if !number_options.is_empty() {
+            items.push(MenuItem::separator(BackendCategoryConfigAction::Back));
+            items.push(
+                MenuItem::new(
+                    ui_copy::settings::BACKEND_DECREASE,
+                    BackendCategoryConfigAction::Bump {
+                        key: focused_number_key,
+                        direction: -1,
+                    },
+                )
+                .with_color(MenuColor::Yellow),
+            );
+            items.push(
+                MenuItem::new(
+                    ui_copy::settings::BACKEND_INCREASE,
+                    BackendCategoryConfigAction::Bump {
+                        key: focused_number_key,
+                        direction: 1,
+                    },
+                )
+                .with_color(MenuColor::Green),
+            );
+        }
+        items.push(MenuItem::separator(BackendCategoryConfigAction::Back));
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::BACKEND_RESET_CATEGORY,
+                BackendCategoryConfigAction::ResetCategory,
+            )
+            .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::BACKEND_BACK_TO_CATEGORIES,
+                BackendCategoryConfigAction::Back,
+            )
+            .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(|item| {
+            if item.separator || item.disabled || item.heading {
+                return false;
+            }
+            match item.value {
+                BackendCategoryConfigAction::Toggle(key) => {
+                    focus_key == Some(BackendSettingFocusKey::Toggle(key))
+                }
+                BackendCategoryConfigAction::Bump { key, .. } => {
+                    focus_key == Some(BackendSettingFocusKey::Number(key))
+                }
+                _ => false,
+            }
+        });
+
+        let focus_cell: RefCell<Option<BackendSettingFocusKey>> = RefCell::new(focus_key);
+        let focus_for_cursor = &focus_cell;
+        let focus_for_input = &focus_cell;
+        let number_options_for_input = number_options.clone();
+        let toggle_options_for_input = toggle_options.clone();
+
+        let mut options: SelectOptions<'_, BackendCategoryConfigAction> = SelectOptions::new(
+            format!("{}: {}", ui_copy::settings::BACKEND_CATEGORY_TITLE, category.label),
+        );
+        options.subtitle = Some(category.description.to_string());
+        options.help = Some(ui_copy::settings::BACKEND_CATEGORY_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        options.on_cursor_change = Some(Box::new(move |ctx| {
+            let focused = ctx.items.get(ctx.cursor).map(|item| &item.value);
+            match focused {
+                Some(BackendCategoryConfigAction::Toggle(key)) => {
+                    *focus_for_cursor.borrow_mut() = Some(BackendSettingFocusKey::Toggle(*key));
+                }
+                Some(BackendCategoryConfigAction::Bump { key, .. }) => {
+                    *focus_for_cursor.borrow_mut() = Some(BackendSettingFocusKey::Number(*key));
+                }
+                _ => {}
+            }
+        }));
+        options.on_input = Some(Box::new(move |raw, _ctx| {
+            let lower = raw.to_lowercase();
+            if lower == "q" {
+                return SelectInputResult::Finish(Some(BackendCategoryConfigAction::Back));
+            }
+            if lower == "r" {
+                return SelectInputResult::Finish(Some(
+                    BackendCategoryConfigAction::ResetCategory,
+                ));
+            }
+            if !number_options_for_input.is_empty()
+                && (lower == "+" || lower == "=" || lower == "]" || lower == "d")
+            {
+                return SelectInputResult::Finish(Some(BackendCategoryConfigAction::Bump {
+                    key: resolve_focused_backend_number_key(
+                        *focus_for_input.borrow(),
+                        &number_options_for_input,
+                    ),
+                    direction: 1,
+                }));
+            }
+            if !number_options_for_input.is_empty()
+                && (lower == "-" || lower == "[" || lower == "a")
+            {
+                return SelectInputResult::Finish(Some(BackendCategoryConfigAction::Bump {
+                    key: resolve_focused_backend_number_key(
+                        *focus_for_input.borrow(),
+                        &number_options_for_input,
+                    ),
+                    direction: -1,
+                }));
+            }
+            if let Ok(parsed) = raw.trim().parse::<usize>()
+                && parsed >= 1 && parsed <= toggle_options_for_input.len() {
+                    return SelectInputResult::Finish(Some(BackendCategoryConfigAction::Toggle(
+                        toggle_options_for_input[parsed - 1].key,
+                    )));
+                }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        // Adopt the focus the cursor landed on (TS mutates focusKey inside
+        // onCursorChange).
+        focus_key = *focus_cell.borrow();
+
+        let Some(result) = result else {
+            return BackendCategoryPromptResult { draft, focus_key };
+        };
+        match result {
+            BackendCategoryConfigAction::Back => {
+                return BackendCategoryPromptResult { draft, focus_key };
+            }
+            BackendCategoryConfigAction::ResetCategory => {
+                draft = apply_backend_category_defaults(&draft, category);
+                focus_key = get_backend_category_initial_focus(category);
+            }
+            BackendCategoryConfigAction::Toggle(key) => {
+                let current = key.get(&draft).or_else(|| key.get(&defaults)).unwrap_or(false);
+                key.set(&mut draft, Some(!current));
+                focus_key = Some(BackendSettingFocusKey::Toggle(key));
+            }
+            BackendCategoryConfigAction::Bump { key, direction } => {
+                let option = backend_number_option_by_key(key);
+                let current = key.get(&draft).or_else(|| key.get(&defaults)).unwrap_or(option.min);
+                let numeric = if current.is_finite() { current } else { option.min };
+                key.set(
+                    &mut draft,
+                    Some(clamp_backend_number(
+                        option,
+                        numeric + option.step * direction as f64,
+                    )),
+                );
+                focus_key = Some(BackendSettingFocusKey::Number(key));
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Backend hub (`backend-settings-prompt.ts`)
+// ---------------------------------------------------------------------------
+
+/// `promptBackendSettings(initial)` — hub over the 4 categories. Save →
+/// `Some(draft)`; cancel → `None` (discarding all category edits).
+pub fn prompt_backend_settings(initial: &PluginConfig) -> Option<PluginConfig> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let ui = get_ui_runtime_options();
+    let mut draft = clone_backend_plugin_config(initial);
+    let mut active_category = BACKEND_CATEGORY_OPTIONS[0].key;
+    let mut focus_by_category: Vec<(BackendCategoryKey, Option<BackendSettingFocusKey>)> =
+        BACKEND_CATEGORY_OPTIONS
+            .iter()
+            .map(|category| (category.key, get_backend_category_initial_focus(category)))
+            .collect();
+
+    fn focus_of(
+        map: &[(BackendCategoryKey, Option<BackendSettingFocusKey>)],
+        key: BackendCategoryKey,
+    ) -> Option<BackendSettingFocusKey> {
+        map.iter()
+            .find(|(category_key, _)| *category_key == key)
+            .and_then(|(_, focus)| *focus)
+    }
+
+    loop {
+        let preview_focus = focus_of(&focus_by_category, active_category);
+        let (preview_label, preview_hint) =
+            build_backend_settings_preview(&draft, &ui, preview_focus, &|text, ui| {
+                highlight_preview_token(text, ui)
+            });
+
+        let mut items: Vec<MenuItem<BackendSettingsHubAction>> = vec![
+            MenuItem::heading(
+                ui_copy::settings::PREVIEW_HEADING,
+                BackendSettingsHubAction::Cancel,
+            ),
+            {
+                let mut item = MenuItem::new(preview_label, BackendSettingsHubAction::Cancel)
+                    .with_hint(preview_hint)
+                    .with_color(MenuColor::Green);
+                item.disabled = true;
+                item.hide_unavailable_suffix = true;
+                item
+            },
+            MenuItem::separator(BackendSettingsHubAction::Cancel),
+            MenuItem::heading(
+                ui_copy::settings::BACKEND_CATEGORIES_HEADING,
+                BackendSettingsHubAction::Cancel,
+            ),
+        ];
+        for (index, category) in BACKEND_CATEGORY_OPTIONS.iter().enumerate() {
+            items.push(
+                MenuItem::new(
+                    format!("{}. {}", index + 1, category.label),
+                    BackendSettingsHubAction::OpenCategory(category.key),
+                )
+                .with_hint(category.description)
+                .with_color(MenuColor::Green),
+            );
+        }
+        items.push(MenuItem::separator(BackendSettingsHubAction::Cancel));
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::RESET_DEFAULT,
+                BackendSettingsHubAction::Reset,
+            )
+            .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::SAVE_AND_BACK,
+                BackendSettingsHubAction::Save,
+            )
+            .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::BACK_NO_SAVE,
+                BackendSettingsHubAction::Cancel,
+            )
+            .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(|item| {
+            if item.separator || item.disabled || item.heading {
+                return false;
+            }
+            matches!(item.value, BackendSettingsHubAction::OpenCategory(key) if key == active_category)
+        });
+
+        let active_cell: RefCell<BackendCategoryKey> = RefCell::new(active_category);
+        let mut options: SelectOptions<'_, BackendSettingsHubAction> =
+            SelectOptions::new(ui_copy::settings::BACKEND_TITLE);
+        options.subtitle = Some(ui_copy::settings::BACKEND_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::BACKEND_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        options.on_cursor_change = Some(Box::new(|ctx| {
+            if let Some(MenuItem {
+                value: BackendSettingsHubAction::OpenCategory(key),
+                ..
+            }) = ctx.items.get(ctx.cursor)
+            {
+                *active_cell.borrow_mut() = *key;
+            }
+        }));
+        options.on_input = Some(Box::new(|raw, _ctx| {
+            let lower = raw.to_lowercase();
+            if lower == "q" {
+                return SelectInputResult::Finish(Some(BackendSettingsHubAction::Cancel));
+            }
+            if lower == "s" {
+                return SelectInputResult::Finish(Some(BackendSettingsHubAction::Save));
+            }
+            if lower == "r" {
+                return SelectInputResult::Finish(Some(BackendSettingsHubAction::Reset));
+            }
+            if let Ok(parsed) = raw.trim().parse::<usize>()
+                && parsed >= 1 && parsed <= BACKEND_CATEGORY_OPTIONS.len() {
+                    return SelectInputResult::Finish(Some(
+                        BackendSettingsHubAction::OpenCategory(
+                            BACKEND_CATEGORY_OPTIONS[parsed - 1].key,
+                        ),
+                    ));
+                }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        active_category = *active_cell.borrow();
+
+        let result = result?;
+        match result {
+            BackendSettingsHubAction::Cancel => return None,
+            BackendSettingsHubAction::Save => return Some(draft),
+            BackendSettingsHubAction::Reset => {
+                draft = clone_backend_plugin_config(&backend_defaults());
+                for (category_key, focus) in focus_by_category.iter_mut() {
+                    let category = get_backend_category(*category_key, &BACKEND_CATEGORY_OPTIONS)
+                        .expect("category keys are static");
+                    *focus = get_backend_category_initial_focus(category);
+                }
+                active_category = BACKEND_CATEGORY_OPTIONS[0].key;
+            }
+            BackendSettingsHubAction::OpenCategory(key) => {
+                let Some(category) = get_backend_category(key, &BACKEND_CATEGORY_OPTIONS) else {
+                    continue;
+                };
+                active_category = category.key;
+                let focus = focus_of(&focus_by_category, category.key)
+                    .or_else(|| get_backend_category_initial_focus(category));
+                let category_result =
+                    prompt_backend_category_settings(&draft, category, focus);
+                draft = category_result.draft;
+                for (category_key, slot) in focus_by_category.iter_mut() {
+                    if *category_key == category.key {
+                        *slot = category_result.focus_key;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// `configureBackendSettings(config)` — controller: non-interactive prints
+/// `"Settings require interactive mode."`; unchanged/cancelled returns the
+/// current clone; else persists via the write queue.
+pub async fn configure_backend_settings(current_config: Option<&PluginConfig>) -> PluginConfig {
+    let current = clone_backend_plugin_config(
+        &current_config
+            .cloned()
+            .unwrap_or_else(cma_config::load::load_plugin_config),
+    );
+    if !is_tty_interactive() {
+        println!("Settings require interactive mode.");
+        return current;
+    }
+    let Some(selected) = prompt_backend_settings(&current) else {
+        return current;
+    };
+    if backend_settings_equal(&current, &selected) {
+        return current;
+    }
+    persist_backend_config_selection(&selected, "backend").await
+}
+
+// Silence an "unused" warning until the fallback-chain override is exercised
+// beyond clone (parity with the TS import surface).
+#[allow(unused)]
+fn _fallback_chain_default() -> FallbackChain {
+    FallbackChain::new()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::settings::schema::{BackendNumberSettingKey as N, BackendToggleSettingKey as T};
+
+    #[test]
+    fn clone_materializes_all_defaults_and_copies_the_fallback_chain() {
+        let config = PluginConfig {
+            fast_session: Some(true),
+            ..Default::default()
+        };
+        let clone = clone_backend_plugin_config(&config);
+        assert_eq!(clone.fast_session, Some(true));
+        // Defaults materialized:
+        assert!(clone.live_account_sync.is_some());
+        assert!(clone.fetch_timeout_ms.is_some());
+        // Absent chain → empty object, not the defaults'.
+        assert_eq!(clone.unsupported_codex_fallback_chain, Some(FallbackChain::new()));
+    }
+
+    #[test]
+    fn snapshot_equality_ignores_non_schema_keys() {
+        let left = PluginConfig {
+            codex_mode: Some(false), // NOT schema-managed
+            ..Default::default()
+        };
+        let mut right = PluginConfig::default();
+        assert!(backend_settings_equal(&left, &right));
+        right.fast_session = Some(!backend_defaults().fast_session.unwrap_or(false));
+        assert!(!backend_settings_equal(&left, &right));
+    }
+
+    #[test]
+    fn format_backend_number_value_units() {
+        let percent = backend_number_option_by_key(N::PreemptiveQuotaRemainingPercent5h);
+        assert_eq!(format_backend_number_value(percent, 12.4), "12%");
+        let count = backend_number_option_by_key(N::ParallelProbingMaxConcurrency);
+        assert_eq!(format_backend_number_value(count, 3.0), "3");
+        let ms = backend_number_option_by_key(N::FetchTimeoutMs);
+        assert_eq!(format_backend_number_value(ms, 120_000.0), "2m");
+        assert_eq!(format_backend_number_value(ms, 90_000.0), "90s");
+        assert_eq!(format_backend_number_value(ms, 1_500.0), "1500ms");
+        assert_eq!(format_backend_number_value(ms, 250.0), "250ms");
+    }
+
+    #[test]
+    fn clamp_for_tests_rejects_unknown_keys_with_the_frozen_message() {
+        assert_eq!(
+            clamp_backend_number_for_tests("fetchTimeoutMs", 1e9).unwrap(),
+            600_000.0
+        );
+        let error = clamp_backend_number_for_tests("bogusKey", 1.0).unwrap_err();
+        assert_eq!(error, "Unknown backend numeric setting key: bogusKey");
+    }
+
+    #[test]
+    fn config_patch_contains_only_typed_schema_keys_clamped() {
+        let config = PluginConfig {
+            fast_session: Some(true),
+            fetch_timeout_ms: Some(10_000_000.0), // above max → clamped
+            network_error_cooldown_ms: Some(f64::NAN), // non-finite → omitted
+            codex_mode: Some(true), // non-schema → omitted
+            ..Default::default()
+        };
+        let patch = build_backend_config_patch(&config);
+        assert_eq!(patch.get("fastSession"), Some(&Value::Bool(true)));
+        assert_eq!(
+            patch.get("fetchTimeoutMs"),
+            Some(&Value::Number(Number::from(600_000)))
+        );
+        assert!(!patch.contains_key("networkErrorCooldownMs"));
+        assert!(!patch.contains_key("codexMode"));
+    }
+
+    #[test]
+    fn category_defaults_reset_only_that_category() {
+        let mut draft = clone_backend_plugin_config(&PluginConfig::default());
+        // Mutate one key in rotation-quota and one in session-sync.
+        T::PreemptiveQuotaEnabled.set(&mut draft, Some(false));
+        N::LiveAccountSyncPollMs.set(&mut draft, Some(59_500.0));
+        let rotation = get_backend_category(BackendCategoryKey::RotationQuota, &BACKEND_CATEGORY_OPTIONS)
+            .unwrap();
+        let next = apply_backend_category_defaults(&draft, rotation);
+        // rotation-quota key reset to default...
+        assert_eq!(
+            T::PreemptiveQuotaEnabled.get(&next),
+            backend_defaults().preemptive_quota_enabled
+        );
+        // ...session-sync key untouched.
+        assert_eq!(N::LiveAccountSyncPollMs.get(&next), Some(59_500.0));
+    }
+
+    #[test]
+    fn focused_number_key_falls_back_to_first_option_then_fetch_timeout() {
+        let perf = get_backend_category(
+            BackendCategoryKey::PerformanceTimeouts,
+            &BACKEND_CATEGORY_OPTIONS,
+        )
+        .unwrap();
+        let options: Vec<_> = perf
+            .number_keys
+            .iter()
+            .map(|key| backend_number_option_by_key(*key))
+            .collect();
+        assert_eq!(
+            resolve_focused_backend_number_key(
+                Some(BackendSettingFocusKey::Number(N::FetchTimeoutMs)),
+                &options
+            ),
+            N::FetchTimeoutMs
+        );
+        // Focus on a key from another category → first option of this one.
+        assert_eq!(
+            resolve_focused_backend_number_key(
+                Some(BackendSettingFocusKey::Number(N::SessionAffinityTtlMs)),
+                &options
+            ),
+            N::FastSessionMaxInputItems
+        );
+        // Toggle focus → first option.
+        assert_eq!(
+            resolve_focused_backend_number_key(
+                Some(BackendSettingFocusKey::Toggle(T::FastSession)),
+                &options
+            ),
+            N::FastSessionMaxInputItems
+        );
+        assert_eq!(resolve_focused_backend_number_key(None, &[]), N::FetchTimeoutMs);
+    }
+
+    #[test]
+    fn backend_preview_shows_toggles_thresholds_and_timeouts() {
+        let config = clone_backend_plugin_config(&PluginConfig::default());
+        let ui = get_ui_runtime_options();
+        let no_highlight = |text: &str, _ui: &UiRuntimeOptions| text.to_string();
+        let (label, hint) = build_backend_settings_preview(&config, &ui, None, &no_highlight);
+        assert!(label.starts_with("live sync "));
+        assert!(label.contains(" | affinity "));
+        assert!(label.contains(" | preemptive "));
+        assert!(hint.starts_with("thresholds 5h<="));
+        assert!(hint.contains(" | 7d<="));
+        assert!(hint.contains(" | timeouts "));
+    }
+}
diff --git a/crates/manager/src/settings/dashboard.rs b/crates/manager/src/settings/dashboard.rs
new file mode 100644
index 000000000..a9b858b01
--- /dev/null
+++ b/crates/manager/src/settings/dashboard.rs
@@ -0,0 +1,600 @@
+//! Port of `settings-hub/dashboard.ts` (+ `dashboard-display-panel.ts`,
+//! `dashboard-settings-controller.ts`, absorbed entry shims) — the option
+//! tables, panel key sets, the account-list display panel, and the two
+//! dashboard controllers.
+
+use std::cell::RefCell;
+
+use cma_config::dashboard_settings::{
+    get_dashboard_settings_path, load_dashboard_display_settings, DashboardAccentColor,
+    DashboardAccountSortMode, DashboardDisplaySettings, DashboardLayoutMode,
+    DashboardStatuslineField, DashboardThemePreset,
+};
+use cma_tui::runtime_options::get_ui_runtime_options;
+use cma_tui::select::{select, MenuColor, MenuItem, SelectInputResult, SelectOptions};
+use cma_tui::ui_copy;
+
+use crate::settings::hub::{
+    apply_dashboard_defaults_for_keys, apply_ui_theme_from_dashboard_settings,
+    clone_dashboard_settings, dashboard_settings_equal, format_dashboard_setting_state,
+    format_menu_layout_mode, format_menu_sort_mode, is_tty_interactive, resolve_menu_layout_mode,
+    DashboardSettingKey,
+};
+use crate::settings::persist::persist_dashboard_settings_selection;
+use crate::settings::preview::{build_account_list_preview, PreviewFocusKey};
+
+// ---------------------------------------------------------------------------
+// Option tables (`settings-hub/dashboard.ts`, exact strings)
+// ---------------------------------------------------------------------------
+
+/// `DashboardDisplaySettingKey` — the 11 toggle rows of the account-list
+/// panel (note: `menuShowDetailsForUnselectedRows` is NOT a toggle row; it is
+/// controlled by the layout cycle item).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DashboardDisplaySettingKey {
+    MenuShowStatusBadge,
+    MenuShowCurrentBadge,
+    MenuShowLastUsed,
+    MenuShowQuotaSummary,
+    MenuShowQuotaCooldown,
+    MenuShowFetchStatus,
+    MenuHighlightCurrentRow,
+    MenuSortEnabled,
+    MenuSortPinCurrent,
+    MenuSortQuickSwitchVisibleRow,
+    /// Present in the TS key union but not in the option rows.
+    MenuShowDetailsForUnselectedRows,
+}
+
+impl DashboardDisplaySettingKey {
+    pub fn get(self, settings: &DashboardDisplaySettings) -> bool {
+        match self {
+            Self::MenuShowStatusBadge => settings.menu_show_status_badge,
+            Self::MenuShowCurrentBadge => settings.menu_show_current_badge,
+            Self::MenuShowLastUsed => settings.menu_show_last_used,
+            Self::MenuShowQuotaSummary => settings.menu_show_quota_summary,
+            Self::MenuShowQuotaCooldown => settings.menu_show_quota_cooldown,
+            Self::MenuShowFetchStatus => settings.menu_show_fetch_status,
+            Self::MenuHighlightCurrentRow => settings.menu_highlight_current_row,
+            Self::MenuSortEnabled => settings.menu_sort_enabled,
+            Self::MenuSortPinCurrent => settings.menu_sort_pin_current,
+            Self::MenuSortQuickSwitchVisibleRow => settings.menu_sort_quick_switch_visible_row,
+            Self::MenuShowDetailsForUnselectedRows => {
+                settings.menu_show_details_for_unselected_rows
+            }
+        }
+    }
+
+    pub fn set(self, settings: &mut DashboardDisplaySettings, value: bool) {
+        match self {
+            Self::MenuShowStatusBadge => settings.menu_show_status_badge = value,
+            Self::MenuShowCurrentBadge => settings.menu_show_current_badge = value,
+            Self::MenuShowLastUsed => settings.menu_show_last_used = value,
+            Self::MenuShowQuotaSummary => settings.menu_show_quota_summary = value,
+            Self::MenuShowQuotaCooldown => settings.menu_show_quota_cooldown = value,
+            Self::MenuShowFetchStatus => settings.menu_show_fetch_status = value,
+            Self::MenuHighlightCurrentRow => settings.menu_highlight_current_row = value,
+            Self::MenuSortEnabled => settings.menu_sort_enabled = value,
+            Self::MenuSortPinCurrent => settings.menu_sort_pin_current = value,
+            Self::MenuSortQuickSwitchVisibleRow => {
+                settings.menu_sort_quick_switch_visible_row = value
+            }
+            Self::MenuShowDetailsForUnselectedRows => {
+                settings.menu_show_details_for_unselected_rows = value
+            }
+        }
+    }
+
+    pub fn as_preview_focus(self) -> PreviewFocusKey {
+        match self {
+            Self::MenuShowStatusBadge => PreviewFocusKey::MenuShowStatusBadge,
+            Self::MenuShowCurrentBadge => PreviewFocusKey::MenuShowCurrentBadge,
+            Self::MenuShowLastUsed => PreviewFocusKey::MenuShowLastUsed,
+            Self::MenuShowQuotaSummary => PreviewFocusKey::MenuShowQuotaSummary,
+            Self::MenuShowQuotaCooldown => PreviewFocusKey::MenuShowQuotaCooldown,
+            Self::MenuShowFetchStatus => PreviewFocusKey::MenuShowFetchStatus,
+            Self::MenuHighlightCurrentRow => PreviewFocusKey::MenuHighlightCurrentRow,
+            Self::MenuSortEnabled => PreviewFocusKey::MenuSortEnabled,
+            Self::MenuSortPinCurrent => PreviewFocusKey::MenuSortPinCurrent,
+            Self::MenuSortQuickSwitchVisibleRow => PreviewFocusKey::MenuSortQuickSwitchVisibleRow,
+            Self::MenuShowDetailsForUnselectedRows => {
+                PreviewFocusKey::MenuShowDetailsForUnselectedRows
+            }
+        }
+    }
+}
+
+/// One row of `DASHBOARD_DISPLAY_OPTIONS`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DashboardDisplaySettingOption {
+    pub key: DashboardDisplaySettingKey,
+    pub label: &'static str,
+    pub description: &'static str,
+}
+
+/// `DASHBOARD_DISPLAY_OPTIONS` (11 entries; order drives numeric hotkeys).
+pub const DASHBOARD_DISPLAY_OPTIONS: [DashboardDisplaySettingOption; 10] = [
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowStatusBadge,
+        label: "Show Status Badges",
+        description: "Show [ok], [active], and similar badges.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowCurrentBadge,
+        label: "Show [current]",
+        description: "Mark the account active in Codex.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowLastUsed,
+        label: "Show Last Used",
+        description: "Show relative usage like 'today'.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowQuotaSummary,
+        label: "Show Limits (5h / 7d)",
+        description: "Show limit bars in each row.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowQuotaCooldown,
+        label: "Show Limit Cooldowns",
+        description: "Show reset timers next to 5h/7d bars.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuShowFetchStatus,
+        label: "Show Fetch Status",
+        description: "Show background limit refresh status in the menu subtitle.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuHighlightCurrentRow,
+        label: "Highlight Current Row",
+        description: "Use stronger color on the current row.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuSortEnabled,
+        label: "Enable Smart Sort",
+        description: "Sort accounts by readiness (view only).",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuSortPinCurrent,
+        label: "Pin [current] when tied",
+        description: "Keep current at top only when it is equally ready.",
+    },
+    DashboardDisplaySettingOption {
+        key: DashboardDisplaySettingKey::MenuSortQuickSwitchVisibleRow,
+        label: "Quick Switch Uses Visible Rows",
+        description: "Number keys (1-9) follow what you see in the list.",
+    },
+];
+
+/// One row of `STATUSLINE_FIELD_OPTIONS`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct StatuslineFieldOption {
+    pub key: DashboardStatuslineField,
+    pub label: &'static str,
+    pub description: &'static str,
+}
+
+pub const STATUSLINE_FIELD_OPTIONS: [StatuslineFieldOption; 3] = [
+    StatuslineFieldOption {
+        key: DashboardStatuslineField::LastUsed,
+        label: "Show Last Used",
+        description: "Example: 'today' or '2d ago'.",
+    },
+    StatuslineFieldOption {
+        key: DashboardStatuslineField::Limits,
+        label: "Show Limits (5h / 7d)",
+        description: "Uses cached limit data from checks.",
+    },
+    StatuslineFieldOption {
+        key: DashboardStatuslineField::Status,
+        label: "Show Status Text",
+        description: "Visible when badges are hidden.",
+    },
+];
+
+pub const AUTO_RETURN_OPTIONS_MS: [i64; 3] = [1_000, 2_000, 4_000];
+pub const MENU_QUOTA_TTL_OPTIONS_MS: [i64; 3] = [60_000, 5 * 60_000, 10 * 60_000];
+pub const THEME_PRESET_OPTIONS: [DashboardThemePreset; 2] =
+    [DashboardThemePreset::Green, DashboardThemePreset::Blue];
+pub const ACCENT_COLOR_OPTIONS: [DashboardAccentColor; 4] = [
+    DashboardAccentColor::Green,
+    DashboardAccentColor::Cyan,
+    DashboardAccentColor::Blue,
+    DashboardAccentColor::Yellow,
+];
+
+/// `ACCOUNT_LIST_PANEL_KEYS` (13 keys — persist/merge/reset scope).
+pub const ACCOUNT_LIST_PANEL_KEYS: [DashboardSettingKey; 13] = [
+    DashboardSettingKey::MenuShowStatusBadge,
+    DashboardSettingKey::MenuShowCurrentBadge,
+    DashboardSettingKey::MenuShowLastUsed,
+    DashboardSettingKey::MenuShowQuotaSummary,
+    DashboardSettingKey::MenuShowQuotaCooldown,
+    DashboardSettingKey::MenuShowFetchStatus,
+    DashboardSettingKey::MenuShowDetailsForUnselectedRows,
+    DashboardSettingKey::MenuHighlightCurrentRow,
+    DashboardSettingKey::MenuSortEnabled,
+    DashboardSettingKey::MenuSortMode,
+    DashboardSettingKey::MenuSortPinCurrent,
+    DashboardSettingKey::MenuSortQuickSwitchVisibleRow,
+    DashboardSettingKey::MenuLayoutMode,
+];
+
+pub const STATUSLINE_PANEL_KEYS: [DashboardSettingKey; 1] =
+    [DashboardSettingKey::MenuStatuslineFields];
+
+/// `BEHAVIOR_PANEL_KEYS` — note `menuShowFetchStatus` is in BOTH the
+/// account-list and behavior scopes (spec 09 gotcha 21).
+pub const BEHAVIOR_PANEL_KEYS: [DashboardSettingKey; 5] = [
+    DashboardSettingKey::ActionAutoReturnMs,
+    DashboardSettingKey::ActionPauseOnKey,
+    DashboardSettingKey::MenuAutoFetchLimits,
+    DashboardSettingKey::MenuShowFetchStatus,
+    DashboardSettingKey::MenuQuotaTtlMs,
+];
+
+pub const THEME_PANEL_KEYS: [DashboardSettingKey; 2] = [
+    DashboardSettingKey::UiThemePreset,
+    DashboardSettingKey::UiAccentColor,
+];
+
+// ---------------------------------------------------------------------------
+// Account-list display panel (`dashboard-display-panel.ts`)
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DashboardConfigAction {
+    Toggle(DashboardDisplaySettingKey),
+    CycleSortMode,
+    CycleLayoutMode,
+    Reset,
+    Save,
+    Cancel,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum PanelFocus {
+    Key(DashboardDisplaySettingKey),
+    SortMode,
+    LayoutMode,
+}
+
+impl PanelFocus {
+    fn as_preview_focus(self) -> PreviewFocusKey {
+        match self {
+            PanelFocus::Key(key) => key.as_preview_focus(),
+            PanelFocus::SortMode => PreviewFocusKey::MenuSortMode,
+            PanelFocus::LayoutMode => PreviewFocusKey::MenuLayoutMode,
+        }
+    }
+}
+
+/// `promptDashboardDisplayPanel` — `None` on cancel/non-TTY, the draft on
+/// save.
+// The focus re-read after `select` mirrors the TS mutable-cursor pattern
+// (same rationale as `select.rs`); some arms overwrite it, tripping the lint.
+#[allow(unused_assignments)]
+pub fn prompt_dashboard_display_panel(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let ui = get_ui_runtime_options();
+    let mut draft = clone_dashboard_settings(initial);
+    let mut focus = PanelFocus::Key(DASHBOARD_DISPLAY_OPTIONS[0].key);
+
+    loop {
+        let preview = build_account_list_preview(
+            &draft,
+            &ui,
+            &resolve_menu_layout_mode,
+            Some(focus.as_preview_focus()),
+        );
+        let mut items: Vec<MenuItem<DashboardConfigAction>> = vec![
+            MenuItem::heading(
+                ui_copy::settings::PREVIEW_HEADING,
+                DashboardConfigAction::Cancel,
+            ),
+            {
+                let mut item = MenuItem::new(preview.label.clone(), DashboardConfigAction::Cancel)
+                    .with_hint(preview.hint.clone())
+                    .with_color(MenuColor::Green);
+                item.disabled = true;
+                item.hide_unavailable_suffix = true;
+                item
+            },
+            MenuItem::separator(DashboardConfigAction::Cancel),
+            MenuItem::heading(
+                ui_copy::settings::DISPLAY_HEADING,
+                DashboardConfigAction::Cancel,
+            ),
+        ];
+        for (index, option) in DASHBOARD_DISPLAY_OPTIONS.iter().enumerate() {
+            let enabled = option.key.get(&draft);
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}. {}",
+                        format_dashboard_setting_state(enabled),
+                        index + 1,
+                        option.label
+                    ),
+                    DashboardConfigAction::Toggle(option.key),
+                )
+                .with_hint(option.description)
+                .with_color(if enabled {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        let sort_mode = draft.menu_sort_mode;
+        items.push(
+            MenuItem::new(
+                format!("Sort mode: {}", format_menu_sort_mode(sort_mode)),
+                DashboardConfigAction::CycleSortMode,
+            )
+            .with_hint("Applies when smart sort is enabled.")
+            .with_color(if sort_mode == DashboardAccountSortMode::ReadyFirst {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        );
+        let layout_mode = resolve_menu_layout_mode(&draft);
+        items.push(
+            MenuItem::new(
+                format!("Layout: {}", format_menu_layout_mode(layout_mode)),
+                DashboardConfigAction::CycleLayoutMode,
+            )
+            .with_hint("Compact shows one-line rows with a selected details pane.")
+            .with_color(if layout_mode == DashboardLayoutMode::CompactDetails {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        );
+        items.push(MenuItem::separator(DashboardConfigAction::Cancel));
+        items.push(
+            MenuItem::new(ui_copy::settings::RESET_DEFAULT, DashboardConfigAction::Reset)
+                .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::SAVE_AND_BACK, DashboardConfigAction::Save)
+                .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::BACK_NO_SAVE, DashboardConfigAction::Cancel)
+                .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(|item| match (&item.value, focus) {
+            (DashboardConfigAction::Toggle(key), PanelFocus::Key(focus_key)) => *key == focus_key,
+            (DashboardConfigAction::CycleSortMode, PanelFocus::SortMode) => true,
+            (DashboardConfigAction::CycleLayoutMode, PanelFocus::LayoutMode) => true,
+            _ => false,
+        });
+
+        let focus_cell: RefCell<PanelFocus> = RefCell::new(focus);
+        let focus_ref = &focus_cell;
+
+        let mut options: SelectOptions<'_, DashboardConfigAction> =
+            SelectOptions::new(ui_copy::settings::ACCOUNT_LIST_TITLE);
+        options.subtitle = Some(ui_copy::settings::ACCOUNT_LIST_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::ACCOUNT_LIST_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        // NOTE: the TS panel live-rewrites the preview row's label/hint inside
+        // onCursorChange; the Rust select API exposes items immutably in
+        // callbacks, so the preview refreshes on the next render loop instead
+        // (recorded deviation — visual only).
+        options.on_cursor_change = Some(Box::new(move |ctx| {
+            match ctx.items.get(ctx.cursor).map(|item| &item.value) {
+                Some(DashboardConfigAction::Toggle(key)) => {
+                    *focus_ref.borrow_mut() = PanelFocus::Key(*key);
+                }
+                Some(DashboardConfigAction::CycleSortMode) => {
+                    *focus_ref.borrow_mut() = PanelFocus::SortMode;
+                }
+                Some(DashboardConfigAction::CycleLayoutMode) => {
+                    *focus_ref.borrow_mut() = PanelFocus::LayoutMode;
+                }
+                _ => {}
+            }
+        }));
+        options.on_input = Some(Box::new(|raw, _ctx| {
+            let lower = raw.to_lowercase();
+            match lower.as_str() {
+                "q" => return SelectInputResult::Finish(Some(DashboardConfigAction::Cancel)),
+                "s" => return SelectInputResult::Finish(Some(DashboardConfigAction::Save)),
+                "r" => return SelectInputResult::Finish(Some(DashboardConfigAction::Reset)),
+                "m" => {
+                    return SelectInputResult::Finish(Some(DashboardConfigAction::CycleSortMode))
+                }
+                "l" => {
+                    return SelectInputResult::Finish(Some(DashboardConfigAction::CycleLayoutMode))
+                }
+                _ => {}
+            }
+            if let Ok(parsed) = raw.trim().parse::<usize>() {
+                if parsed >= 1 && parsed <= DASHBOARD_DISPLAY_OPTIONS.len() {
+                    return SelectInputResult::Finish(Some(DashboardConfigAction::Toggle(
+                        DASHBOARD_DISPLAY_OPTIONS[parsed - 1].key,
+                    )));
+                }
+                if parsed == DASHBOARD_DISPLAY_OPTIONS.len() + 1 {
+                    return SelectInputResult::Finish(Some(DashboardConfigAction::CycleSortMode));
+                }
+                if parsed == DASHBOARD_DISPLAY_OPTIONS.len() + 2 {
+                    return SelectInputResult::Finish(Some(
+                        DashboardConfigAction::CycleLayoutMode,
+                    ));
+                }
+            }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        focus = *focus_cell.borrow();
+
+        let result = result?;
+        match result {
+            DashboardConfigAction::Cancel => return None,
+            DashboardConfigAction::Save => return Some(draft),
+            DashboardConfigAction::Reset => {
+                draft = apply_dashboard_defaults_for_keys(&draft, &ACCOUNT_LIST_PANEL_KEYS);
+                focus = PanelFocus::Key(DASHBOARD_DISPLAY_OPTIONS[0].key);
+            }
+            DashboardConfigAction::CycleSortMode => {
+                let next_mode = match draft.menu_sort_mode {
+                    DashboardAccountSortMode::ReadyFirst => DashboardAccountSortMode::Manual,
+                    DashboardAccountSortMode::Manual => DashboardAccountSortMode::ReadyFirst,
+                };
+                draft.menu_sort_mode = next_mode;
+                if next_mode == DashboardAccountSortMode::ReadyFirst {
+                    // Selecting ready-first FORCES smart sort on.
+                    draft.menu_sort_enabled = true;
+                }
+                focus = PanelFocus::SortMode;
+            }
+            DashboardConfigAction::CycleLayoutMode => {
+                let next_layout = match resolve_menu_layout_mode(&draft) {
+                    DashboardLayoutMode::CompactDetails => DashboardLayoutMode::ExpandedRows,
+                    DashboardLayoutMode::ExpandedRows => DashboardLayoutMode::CompactDetails,
+                };
+                draft.menu_layout_mode = next_layout;
+                draft.menu_show_details_for_unselected_rows =
+                    next_layout == DashboardLayoutMode::ExpandedRows;
+                focus = PanelFocus::LayoutMode;
+            }
+            DashboardConfigAction::Toggle(key) => {
+                focus = PanelFocus::Key(key);
+                let current = key.get(&draft);
+                key.set(&mut draft, !current);
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Controllers (`dashboard-settings-controller.ts`)
+// ---------------------------------------------------------------------------
+
+async fn configure_dashboard_settings_with(
+    current_settings: Option<&DashboardDisplaySettings>,
+    prompt: impl Fn(&DashboardDisplaySettings) -> Option<DashboardDisplaySettings>,
+    keys: &[DashboardSettingKey],
+    scope: &str,
+) -> DashboardDisplaySettings {
+    let current = match current_settings {
+        Some(settings) => settings.clone(),
+        None => load_dashboard_display_settings().await,
+    };
+    if !is_tty_interactive() {
+        println!("Settings require interactive mode.");
+        println!(
+            "Settings file: {}",
+            get_dashboard_settings_path().to_string_lossy()
+        );
+        return current;
+    }
+    let Some(selected) = prompt(&current) else {
+        return current;
+    };
+    if dashboard_settings_equal(&current, &selected) {
+        return current;
+    }
+    let merged = persist_dashboard_settings_selection(&selected, keys, scope).await;
+    apply_ui_theme_from_dashboard_settings(&merged);
+    merged
+}
+
+/// `configureDashboardDisplaySettings(currentSettings?)`.
+pub async fn configure_dashboard_display_settings(
+    current_settings: Option<&DashboardDisplaySettings>,
+) -> DashboardDisplaySettings {
+    configure_dashboard_settings_with(
+        current_settings,
+        prompt_dashboard_display_panel,
+        &ACCOUNT_LIST_PANEL_KEYS,
+        "account-list",
+    )
+    .await
+}
+
+/// `configureStatuslineSettings(currentSettings?)`.
+pub async fn configure_statusline_settings(
+    current_settings: Option<&DashboardDisplaySettings>,
+) -> DashboardDisplaySettings {
+    configure_dashboard_settings_with(
+        current_settings,
+        crate::settings::panels::prompt_statusline_settings_panel,
+        &STATUSLINE_PANEL_KEYS,
+        "summary-fields",
+    )
+    .await
+}
+
+/// `promptBehaviorSettings(initial)` — thin wiring over the behavior panel.
+pub fn prompt_behavior_settings(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    crate::settings::panels::prompt_behavior_settings_panel(initial)
+}
+
+/// `promptThemeSettings(initial)` — thin wiring over the theme panel.
+pub fn prompt_theme_settings(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    crate::settings::panels::prompt_theme_settings_panel(initial)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn option_tables_are_copy_exact_and_ordered() {
+        assert_eq!(DASHBOARD_DISPLAY_OPTIONS.len(), 10);
+        assert_eq!(DASHBOARD_DISPLAY_OPTIONS[0].label, "Show Status Badges");
+        assert_eq!(
+            DASHBOARD_DISPLAY_OPTIONS[9].label,
+            "Quick Switch Uses Visible Rows"
+        );
+        assert_eq!(
+            DASHBOARD_DISPLAY_OPTIONS[8].description,
+            "Keep current at top only when it is equally ready."
+        );
+        assert_eq!(STATUSLINE_FIELD_OPTIONS.len(), 3);
+        assert_eq!(AUTO_RETURN_OPTIONS_MS, [1_000, 2_000, 4_000]);
+        assert_eq!(MENU_QUOTA_TTL_OPTIONS_MS, [60_000, 300_000, 600_000]);
+    }
+
+    #[test]
+    fn panel_key_sets_have_the_documented_scopes() {
+        assert_eq!(ACCOUNT_LIST_PANEL_KEYS.len(), 13);
+        assert_eq!(STATUSLINE_PANEL_KEYS.len(), 1);
+        assert_eq!(BEHAVIOR_PANEL_KEYS.len(), 5);
+        assert_eq!(THEME_PANEL_KEYS.len(), 2);
+        // menuShowFetchStatus is in BOTH the account-list and behavior scopes.
+        assert!(ACCOUNT_LIST_PANEL_KEYS.contains(&DashboardSettingKey::MenuShowFetchStatus));
+        assert!(BEHAVIOR_PANEL_KEYS.contains(&DashboardSettingKey::MenuShowFetchStatus));
+        // The layout cycle owns both the mode and the legacy boolean.
+        assert!(
+            ACCOUNT_LIST_PANEL_KEYS.contains(&DashboardSettingKey::MenuShowDetailsForUnselectedRows)
+        );
+        assert!(ACCOUNT_LIST_PANEL_KEYS.contains(&DashboardSettingKey::MenuLayoutMode));
+    }
+
+    #[test]
+    fn toggle_key_accessors_round_trip() {
+        let mut settings = DashboardDisplaySettings::default();
+        assert!(DashboardDisplaySettingKey::MenuShowStatusBadge.get(&settings));
+        DashboardDisplaySettingKey::MenuShowStatusBadge.set(&mut settings, false);
+        assert!(!settings.menu_show_status_badge);
+    }
+}
diff --git a/crates/manager/src/settings/experimental.rs b/crates/manager/src/settings/experimental.rs
new file mode 100644
index 000000000..c7f064529
--- /dev/null
+++ b/crates/manager/src/settings/experimental.rs
@@ -0,0 +1,704 @@
+//! Port of `settings-hub/experimental.ts` + `experimental-settings-prompt.ts`
+//! + `experimental-sync-target.ts` (entry shims absorbed) — the experimental
+//!   settings panel (oc-chatgpt sync preview/apply, named-backup export,
+//!   refresh-guardian toggle + interval).
+//!
+//! The oc-chatgpt planner/applier lives in the sibling-owned
+//! `crate::oc_chatgpt` cluster; this module mirrors the TS DI seam
+//! (`ExperimentalSettingsPromptDeps`): the plan/apply operations are injected
+//! via [`ExperimentalSyncHooks`] which the dispatcher installs at startup.
+//! Everything else (state machine, frozen strings, bounds) lives here.
+
+use std::io::{BufRead, Write};
+use std::sync::{Mutex, OnceLock};
+
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_tui::runtime_options::get_ui_runtime_options;
+use cma_tui::select::{select, MenuColor, MenuItem, SelectInputResult, SelectOptions};
+use cma_tui::ui_copy;
+
+use crate::settings::backend::clone_backend_plugin_config;
+use crate::settings::hub::is_tty_interactive;
+use crate::settings::schema::{
+    backend_number_option_by_key, map_experimental_menu_hotkey, map_experimental_status_hotkey,
+    BackendNumberSettingKey, ExperimentalSettingsAction,
+};
+
+// ---------------------------------------------------------------------------
+// Sync-target state (`experimental-sync-target.ts`) — generic over the
+// detection payload exactly like the TS `<TTargetState>` DI.
+// ---------------------------------------------------------------------------
+
+/// `ExperimentalSyncTargetState`.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ExperimentalSyncTargetState<D> {
+    BlockedAmbiguous { detection: D },
+    BlockedNone { detection: D },
+    Error { message: String },
+    Target {
+        detection: D,
+        /// `None` when the target account file does not exist yet.
+        destination: Option<AccountStorageV3>,
+    },
+}
+
+/// Detection outcome fed into [`load_experimental_sync_target_state`].
+#[derive(Clone, Debug, PartialEq)]
+pub enum SyncTargetDetection<D> {
+    Ambiguous(D),
+    None(D),
+    Target { detection: D, account_path: String },
+}
+
+/// `loadExperimentalSyncTargetState({detectTarget, readJson,
+/// normalizeAccountStorage})` — ENOENT → target with `destination: None`;
+/// normalize-null → `"Invalid target account storage format"`; other read
+/// errors → error with the message.
+pub async fn load_experimental_sync_target_state<D, ReadFut>(
+    detect_target: impl FnOnce() -> SyncTargetDetection<D>,
+    read_json: impl FnOnce(String) -> ReadFut,
+    normalize_account_storage: impl FnOnce(&serde_json::Value) -> Option<AccountStorageV3>,
+) -> ExperimentalSyncTargetState<D>
+where
+    ReadFut: std::future::Future<Output = Result<serde_json::Value, std::io::Error>>,
+{
+    let (detection, account_path) = match detect_target() {
+        SyncTargetDetection::Ambiguous(detection) => {
+            return ExperimentalSyncTargetState::BlockedAmbiguous { detection };
+        }
+        SyncTargetDetection::None(detection) => {
+            return ExperimentalSyncTargetState::BlockedNone { detection };
+        }
+        SyncTargetDetection::Target {
+            detection,
+            account_path,
+        } => (detection, account_path),
+    };
+    match read_json(account_path).await {
+        Ok(raw) => match normalize_account_storage(&raw) {
+            Some(normalized) => ExperimentalSyncTargetState::Target {
+                detection,
+                destination: Some(normalized),
+            },
+            None => ExperimentalSyncTargetState::Error {
+                message: "Invalid target account storage format".to_string(),
+            },
+        },
+        Err(error) => {
+            if cma_core::fs_retry::code_of(&error) == Some("ENOENT") {
+                return ExperimentalSyncTargetState::Target {
+                    detection,
+                    destination: None,
+                };
+            }
+            ExperimentalSyncTargetState::Error {
+                message: error.to_string(),
+            }
+        }
+    }
+}
+
+/// `readJson` binding from `experimental-sync-target-entry.ts`:
+/// `JSON.parse(readFileWithRetry(path, {EBUSY,EPERM,EAGAIN} × 4, sleep))`.
+pub async fn read_sync_target_json(path: String) -> Result<serde_json::Value, std::io::Error> {
+    let content = crate::settings::persist::read_file_with_retry(
+        std::path::Path::new(&path),
+        &["EBUSY", "EPERM", "EAGAIN"],
+        4,
+        crate::settings::write_queue::default_sleep,
+    )
+    .await?;
+    serde_json::from_str(&content)
+        .map_err(|error| std::io::Error::new(std::io::ErrorKind::InvalidData, error.to_string()))
+}
+
+// ---------------------------------------------------------------------------
+// Plan / apply data shapes + frozen-string mappers
+// (`settings-hub/experimental.ts` accessor lambdas)
+// ---------------------------------------------------------------------------
+
+/// Counts shown on the preview screen.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct ExperimentalSyncPlanPreview {
+    pub to_add: usize,
+    pub to_update: usize,
+    pub to_skip: usize,
+    pub unchanged_destination_only: usize,
+}
+
+/// Cause of a `plan-error` (chatgpt-import-06).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SyncPlanErrorCause {
+    Load,
+    Preview,
+}
+
+/// Plan outcome, shaped after the TS accessor contract.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ExperimentalSyncPlan {
+    Ready {
+        preview: ExperimentalSyncPlanPreview,
+        active_selection_behavior: String,
+    },
+    PlanError {
+        cause: SyncPlanErrorCause,
+        detail: String,
+    },
+    BlockedAmbiguous {
+        reason: Option<String>,
+    },
+    Blocked {
+        reason: Option<String>,
+    },
+}
+
+/// Apply outcome, shaped after the TS accessor contract.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ExperimentalSyncApplied {
+    Applied { account_path: Option<String> },
+    Error { message: String },
+    Other,
+}
+
+/// `getPlanBlockedReason` — frozen strings (spec 09 §5.14).
+pub fn get_plan_blocked_reason(plan: &ExperimentalSyncPlan) -> String {
+    match plan {
+        ExperimentalSyncPlan::PlanError { cause, detail } => format!(
+            "Sync failed while {}: {detail}",
+            match cause {
+                SyncPlanErrorCause::Load => "loading the target",
+                SyncPlanErrorCause::Preview => "previewing the merge",
+            }
+        ),
+        ExperimentalSyncPlan::BlockedAmbiguous { reason } => format!(
+            "Sync blocked: {}",
+            reason.as_deref().unwrap_or("unknown")
+        ),
+        ExperimentalSyncPlan::Blocked { reason } => format!(
+            "Sync unavailable: {}",
+            reason.as_deref().unwrap_or("unknown")
+        ),
+        ExperimentalSyncPlan::Ready { .. } => String::new(),
+    }
+}
+
+/// `getAppliedLabel` — label + tone color.
+pub fn get_applied_label(applied: &ExperimentalSyncApplied) -> (String, MenuColor) {
+    match applied {
+        ExperimentalSyncApplied::Applied { account_path } => (
+            format!(
+                "Applied sync to {}",
+                account_path.as_deref().unwrap_or("target")
+            ),
+            MenuColor::Green,
+        ),
+        ExperimentalSyncApplied::Error { message } => (message.clone(), MenuColor::Yellow),
+        ExperimentalSyncApplied::Other => ("Sync did not apply".to_string(), MenuColor::Yellow),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Sync hooks — the DI seam standing in for `oc-chatgpt-orchestrator` /
+// `oc-chatgpt-target-detection` (sibling cluster). The dispatcher installs
+// concrete bindings at startup.
+// ---------------------------------------------------------------------------
+
+pub type SyncPlanFuture = std::pin::Pin<Box<dyn std::future::Future<Output = ExperimentalSyncPlan> + Send>>;
+pub type SyncApplyFuture =
+    std::pin::Pin<Box<dyn std::future::Future<Output = ExperimentalSyncApplied> + Send>>;
+
+pub struct ExperimentalSyncHooks {
+    /// `planOcChatgptSync({source, destination, dependencies})` — plan for
+    /// preview. `destination` carries the pre-loaded target when the state
+    /// was `target`.
+    pub plan: Box<
+        dyn Fn(Option<AccountStorageV3>, Option<AccountStorageV3>) -> SyncPlanFuture + Send + Sync,
+    >,
+    /// `applyOcChatgptSync` — the real apply.
+    pub apply: Box<
+        dyn Fn(Option<AccountStorageV3>, Option<AccountStorageV3>) -> SyncApplyFuture + Send + Sync,
+    >,
+    /// `loadExperimentalSyncTarget()` — concrete detection + read binding.
+    pub load_target: Box<dyn Fn() -> SyncTargetFuture + Send + Sync>,
+}
+
+/// Boxed future returned by [`ExperimentalSyncHooks::load_target`].
+pub type SyncTargetFuture = std::pin::Pin<
+    Box<dyn std::future::Future<Output = ExperimentalSyncTargetState<String>> + Send>,
+>;
+
+static SYNC_HOOKS: OnceLock<Mutex<Option<ExperimentalSyncHooks>>> = OnceLock::new();
+
+/// Install the concrete oc-chatgpt bindings (dispatcher startup).
+pub fn set_experimental_sync_hooks(hooks: Option<ExperimentalSyncHooks>) {
+    let cell = SYNC_HOOKS.get_or_init(|| Mutex::new(None));
+    *cell.lock().expect("sync hooks poisoned") = hooks;
+}
+
+fn with_sync_hooks<T>(f: impl FnOnce(Option<&ExperimentalSyncHooks>) -> T) -> T {
+    let cell = SYNC_HOOKS.get_or_init(|| Mutex::new(None));
+    let guard = cell.lock().expect("sync hooks poisoned");
+    f(guard.as_ref())
+}
+
+// ---------------------------------------------------------------------------
+// Interactive panel (`experimental-settings-prompt.ts`)
+// ---------------------------------------------------------------------------
+
+/// Refresh-interval bounds derived from the `proactiveRefreshIntervalMs`
+/// schema entry with the historical fallbacks (settings-hub-01 divergence
+/// fix). The Rust schema entry always exists, so the fallbacks are dead but
+/// kept for parity documentation: 60_000 / 600_000 / 60_000.
+fn refresh_interval_bounds() -> (f64, f64, f64) {
+    let option = backend_number_option_by_key(BackendNumberSettingKey::ProactiveRefreshIntervalMs);
+    (option.min, option.max, option.step)
+}
+
+fn question(prompt: &str) -> String {
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "{prompt}");
+    let _ = stdout.flush();
+    let mut answer = String::new();
+    let _ = std::io::stdin().lock().read_line(&mut answer);
+    answer.trim_end_matches(['\r', '\n']).to_string()
+}
+
+/// Show a one-line status screen with a single Back item (`q` hotkey).
+fn show_status_screen(message: &str, color: MenuColor) {
+    let ui = get_ui_runtime_options();
+    let items = vec![
+        MenuItem::new(message.to_string(), ExperimentalSettingsAction::Back).with_color(color),
+        MenuItem::new(ui_copy::settings::BACK, ExperimentalSettingsAction::Back)
+            .with_color(MenuColor::Red),
+    ];
+    let mut options: SelectOptions<'_, ExperimentalSettingsAction> =
+        SelectOptions::new(ui_copy::settings::EXPERIMENTAL_TITLE);
+    options.subtitle = Some(ui_copy::settings::EXPERIMENTAL_SUBTITLE.to_string());
+    options.help = Some(ui_copy::settings::EXPERIMENTAL_HELP_STATUS.to_string());
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+    options.on_input = Some(Box::new(|raw, _ctx| {
+        match map_experimental_status_hotkey(raw) {
+            Some(action) => SelectInputResult::Finish(Some(action)),
+            None => SelectInputResult::Ignored,
+        }
+    }));
+    let _ = select(&items, options);
+}
+
+/// The sync flow: load target → plan → preview screen → optional apply.
+async fn run_sync_flow() {
+    let target_state =
+        with_sync_hooks(|hooks| hooks.map(|hooks| (hooks.load_target)()));
+
+    let Some(target_future) = target_state else {
+        // No bindings installed: surface the blocked-none path.
+        show_status_screen(
+            &get_plan_blocked_reason(&ExperimentalSyncPlan::Blocked { reason: None }),
+            MenuColor::Yellow,
+        );
+        return;
+    };
+    let target = target_future.await;
+    if let ExperimentalSyncTargetState::Error { message } = &target {
+        show_status_screen(message, MenuColor::Yellow);
+        return;
+    }
+    let source = cma_storage::load::load_accounts()
+        .await
+        .map(|loaded| loaded.storage);
+    let destination = match &target {
+        ExperimentalSyncTargetState::Target { destination, .. } => destination.clone(),
+        _ => None,
+    };
+    let plan = with_sync_hooks(|hooks| hooks.map(|hooks| (hooks.plan)(source.clone(), destination.clone())));
+    let Some(plan_future) = plan else {
+        show_status_screen(
+            &get_plan_blocked_reason(&ExperimentalSyncPlan::Blocked { reason: None }),
+            MenuColor::Yellow,
+        );
+        return;
+    };
+    let plan = plan_future.await;
+    let ExperimentalSyncPlan::Ready {
+        preview,
+        active_selection_behavior,
+    } = &plan
+    else {
+        show_status_screen(&get_plan_blocked_reason(&plan), MenuColor::Yellow);
+        return;
+    };
+
+    // Preview screen: apply (hotkey `a`) or back.
+    let ui = get_ui_runtime_options();
+    let items = vec![
+        MenuItem::new(
+            format!(
+                "Preview: add {} | update {} | skip {}",
+                preview.to_add, preview.to_update, preview.to_skip
+            ),
+            ExperimentalSettingsAction::Back,
+        )
+        .with_color(MenuColor::Green),
+        MenuItem::new(
+            format!(
+                "Preserve destination-only: {}",
+                preview.unchanged_destination_only
+            ),
+            ExperimentalSettingsAction::Back,
+        ),
+        MenuItem::new(
+            format!("Active selection: {active_selection_behavior}"),
+            ExperimentalSettingsAction::Back,
+        ),
+        MenuItem::new(
+            ui_copy::settings::EXPERIMENTAL_APPLY_SYNC,
+            ExperimentalSettingsAction::Apply,
+        )
+        .with_color(MenuColor::Green),
+        MenuItem::new(ui_copy::settings::BACK, ExperimentalSettingsAction::Back)
+            .with_color(MenuColor::Red),
+    ];
+    let mut options: SelectOptions<'_, ExperimentalSettingsAction> =
+        SelectOptions::new(ui_copy::settings::EXPERIMENTAL_TITLE);
+    options.subtitle = Some(ui_copy::settings::EXPERIMENTAL_SUBTITLE.to_string());
+    options.help = Some(ui_copy::settings::EXPERIMENTAL_HELP_PREVIEW.to_string());
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+    options.on_input = Some(Box::new(|raw, _ctx| {
+        let lower = raw.to_lowercase();
+        if lower == "a" {
+            return SelectInputResult::Finish(Some(ExperimentalSettingsAction::Apply));
+        }
+        if lower == "q" {
+            return SelectInputResult::Finish(Some(ExperimentalSettingsAction::Back));
+        }
+        SelectInputResult::Ignored
+    }));
+    let choice = select(&items, options).ok().flatten();
+    if choice != Some(ExperimentalSettingsAction::Apply) {
+        return;
+    }
+
+    let apply =
+        with_sync_hooks(|hooks| hooks.map(|hooks| (hooks.apply)(source.clone(), destination)));
+    let Some(apply_future) = apply else {
+        return;
+    };
+    let applied = apply_future.await;
+    let (label, color) = get_applied_label(&applied);
+    show_status_screen(&label, color);
+}
+
+/// The backup flow: name prompt → `runNamedBackupExport` → status screen.
+async fn run_backup_flow() {
+    let answer = question(ui_copy::settings::EXPERIMENTAL_BACKUP_PROMPT);
+    let trimmed = answer.trim();
+    if trimmed.is_empty() || trimmed.eq_ignore_ascii_case("q") {
+        return;
+    }
+    match cma_storage::named_backups::export_named_backup(trimmed, false).await {
+        Ok(path) => show_status_screen(&format!("Saved backup to {path}"), MenuColor::Green),
+        Err(error) => {
+            // Collision (EEXIST / "File already exists") maps to the frozen
+            // collision copy; other errors show their message.
+            let message = error.message().to_string();
+            if message.starts_with("File already exists: ") {
+                let path = message.trim_start_matches("File already exists: ");
+                show_status_screen(
+                    &format!("Backup already exists: {path}"),
+                    MenuColor::Yellow,
+                );
+            } else {
+                show_status_screen(&message, MenuColor::Yellow);
+            }
+        }
+    }
+}
+
+/// `promptExperimentalSettings(initialConfig)` — non-interactive → `None`;
+/// only "Save and back" returns the draft (spec 09 gotcha 23).
+pub async fn prompt_experimental_settings(initial_config: &PluginConfig) -> Option<PluginConfig> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let mut draft = clone_backend_plugin_config(initial_config);
+    let (min_interval, max_interval, step_interval) = refresh_interval_bounds();
+
+    loop {
+        let ui = get_ui_runtime_options();
+        let guard_enabled = draft.proactive_refresh_guardian.unwrap_or(false);
+        let interval_ms = draft.proactive_refresh_interval_ms.unwrap_or(60_000.0);
+        let interval_label =
+            cma_accounts::rate_limits::format_wait_time(interval_ms.round() as i64);
+
+        let mut items: Vec<MenuItem<ExperimentalSettingsAction>> = vec![
+            MenuItem::new(
+                ui_copy::settings::EXPERIMENTAL_SYNC,
+                ExperimentalSettingsAction::Sync,
+            )
+            .with_color(MenuColor::Yellow),
+            MenuItem::new(
+                ui_copy::settings::EXPERIMENTAL_BACKUP,
+                ExperimentalSettingsAction::Backup,
+            )
+            .with_color(MenuColor::Green),
+            MenuItem::new(
+                format!(
+                    "{} {}",
+                    if guard_enabled { "[x]" } else { "[ ]" },
+                    ui_copy::settings::EXPERIMENTAL_REFRESH_GUARD
+                ),
+                ExperimentalSettingsAction::ToggleRefreshGuardian,
+            )
+            .with_color(if guard_enabled {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        ];
+        let mut interval_row = MenuItem::new(
+            format!(
+                "{}: {}",
+                ui_copy::settings::EXPERIMENTAL_REFRESH_INTERVAL,
+                interval_label
+            ),
+            ExperimentalSettingsAction::Back,
+        );
+        interval_row.disabled = true;
+        interval_row.hide_unavailable_suffix = true;
+        items.push(interval_row);
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::EXPERIMENTAL_DECREASE_INTERVAL,
+                ExperimentalSettingsAction::DecreaseRefreshInterval,
+            )
+            .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::EXPERIMENTAL_INCREASE_INTERVAL,
+                ExperimentalSettingsAction::IncreaseRefreshInterval,
+            )
+            .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::SAVE_AND_BACK,
+                ExperimentalSettingsAction::Save,
+            )
+            .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::BACK, ExperimentalSettingsAction::Back)
+                .with_color(MenuColor::Red),
+        );
+
+        let mut options: SelectOptions<'_, ExperimentalSettingsAction> =
+            SelectOptions::new(ui_copy::settings::EXPERIMENTAL_TITLE);
+        options.subtitle = Some(ui_copy::settings::EXPERIMENTAL_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::EXPERIMENTAL_HELP_MENU.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.on_input = Some(Box::new(|raw, _ctx| {
+            match map_experimental_menu_hotkey(raw) {
+                Some(action) => SelectInputResult::Finish(Some(action)),
+                None => SelectInputResult::Ignored,
+            }
+        }));
+
+        let result = select(&items, options).ok().flatten()?;
+        match result {
+            ExperimentalSettingsAction::Back => return None,
+            ExperimentalSettingsAction::Save => return Some(draft),
+            ExperimentalSettingsAction::ToggleRefreshGuardian => {
+                draft.proactive_refresh_guardian = Some(!guard_enabled);
+            }
+            ExperimentalSettingsAction::DecreaseRefreshInterval => {
+                let next = (interval_ms - step_interval).clamp(min_interval, max_interval);
+                draft.proactive_refresh_interval_ms = Some(next);
+            }
+            ExperimentalSettingsAction::IncreaseRefreshInterval => {
+                let next = (interval_ms + step_interval).clamp(min_interval, max_interval);
+                draft.proactive_refresh_interval_ms = Some(next);
+            }
+            ExperimentalSettingsAction::Backup => {
+                run_backup_flow().await;
+            }
+            ExperimentalSettingsAction::Sync => {
+                run_sync_flow().await;
+            }
+            ExperimentalSettingsAction::Apply => {
+                // Only reachable from the preview screen; ignore here.
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn sync_target_state_classification() {
+        // Ambiguous short-circuits.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::Ambiguous("amb"),
+            |_path| async { Ok(serde_json::json!({})) },
+            |_value| None,
+        )
+        .await;
+        assert!(matches!(
+            state,
+            ExperimentalSyncTargetState::BlockedAmbiguous { detection: "amb" }
+        ));
+
+        // None short-circuits.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::None("none"),
+            |_path| async { Ok(serde_json::json!({})) },
+            |_value| None,
+        )
+        .await;
+        assert!(matches!(
+            state,
+            ExperimentalSyncTargetState::BlockedNone { detection: "none" }
+        ));
+
+        // Normalize-null → frozen invalid-format error.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::Target {
+                detection: "t",
+                account_path: "x.json".to_string(),
+            },
+            |_path| async { Ok(serde_json::json!({"bogus": true})) },
+            |_value| None,
+        )
+        .await;
+        assert_eq!(
+            state,
+            ExperimentalSyncTargetState::Error {
+                message: "Invalid target account storage format".to_string()
+            }
+        );
+
+        // ENOENT → target with destination None.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::Target {
+                detection: "t",
+                account_path: "missing.json".to_string(),
+            },
+            |_path| async {
+                Err(cma_core::fs_retry::io_error_with_code(
+                    "ENOENT",
+                    "no such file",
+                ))
+            },
+            |_value| Some(AccountStorageV3::empty()),
+        )
+        .await;
+        assert!(matches!(
+            state,
+            ExperimentalSyncTargetState::Target {
+                destination: None,
+                ..
+            }
+        ));
+
+        // Other errors → error with the message.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::Target {
+                detection: "t",
+                account_path: "busy.json".to_string(),
+            },
+            |_path| async {
+                Err(cma_core::fs_retry::io_error_with_code("EBUSY", "locked"))
+            },
+            |_value| Some(AccountStorageV3::empty()),
+        )
+        .await;
+        assert!(matches!(state, ExperimentalSyncTargetState::Error { .. }));
+
+        // Valid target parses through.
+        let state = load_experimental_sync_target_state(
+            || SyncTargetDetection::Target {
+                detection: "t",
+                account_path: "ok.json".to_string(),
+            },
+            |_path| async { Ok(serde_json::json!({"version": 3})) },
+            |_value| Some(AccountStorageV3::empty()),
+        )
+        .await;
+        assert!(matches!(
+            state,
+            ExperimentalSyncTargetState::Target {
+                destination: Some(_),
+                ..
+            }
+        ));
+    }
+
+    #[test]
+    fn plan_blocked_reasons_use_the_frozen_strings() {
+        assert_eq!(
+            get_plan_blocked_reason(&ExperimentalSyncPlan::PlanError {
+                cause: SyncPlanErrorCause::Load,
+                detail: "corrupt file".to_string(),
+            }),
+            "Sync failed while loading the target: corrupt file"
+        );
+        assert_eq!(
+            get_plan_blocked_reason(&ExperimentalSyncPlan::PlanError {
+                cause: SyncPlanErrorCause::Preview,
+                detail: "boom".to_string(),
+            }),
+            "Sync failed while previewing the merge: boom"
+        );
+        assert_eq!(
+            get_plan_blocked_reason(&ExperimentalSyncPlan::BlockedAmbiguous {
+                reason: Some("two targets".to_string()),
+            }),
+            "Sync blocked: two targets"
+        );
+        assert_eq!(
+            get_plan_blocked_reason(&ExperimentalSyncPlan::Blocked { reason: None }),
+            "Sync unavailable: unknown"
+        );
+    }
+
+    #[test]
+    fn applied_labels_use_the_frozen_strings() {
+        assert_eq!(
+            get_applied_label(&ExperimentalSyncApplied::Applied {
+                account_path: Some("/x/accounts.json".to_string()),
+            }),
+            (
+                "Applied sync to /x/accounts.json".to_string(),
+                MenuColor::Green
+            )
+        );
+        assert_eq!(
+            get_applied_label(&ExperimentalSyncApplied::Applied { account_path: None }),
+            ("Applied sync to target".to_string(), MenuColor::Green)
+        );
+        assert_eq!(
+            get_applied_label(&ExperimentalSyncApplied::Error {
+                message: "denied".to_string(),
+            }),
+            ("denied".to_string(), MenuColor::Yellow)
+        );
+        assert_eq!(
+            get_applied_label(&ExperimentalSyncApplied::Other),
+            ("Sync did not apply".to_string(), MenuColor::Yellow)
+        );
+    }
+
+    #[test]
+    fn refresh_interval_bounds_come_from_the_schema() {
+        assert_eq!(refresh_interval_bounds(), (5_000.0, 600_000.0, 5_000.0));
+    }
+}
diff --git a/crates/manager/src/settings/hub.rs b/crates/manager/src/settings/hub.rs
new file mode 100644
index 000000000..8469a8199
--- /dev/null
+++ b/crates/manager/src/settings/hub.rs
@@ -0,0 +1,487 @@
+//! Port of `lib/codex-manager/settings-hub.ts` + `settings-hub/{index,shared}.ts`
+//! (+ the absorbed `settings-hub-entry/-menu/-prompt` DI shims) — the settings
+//! hub menu and the shared normalization/clone/merge helpers.
+//!
+//! The Rust `DashboardDisplaySettings` is the fully-normalized shape (every
+//! field concrete), so `cloneDashboardSettingsData`'s "`?? default`" baking is
+//! a plain clone plus the two derived rules the TS clone applied on top:
+//! layout resolution and `menuShowDetailsForUnselectedRows = (layout ==
+//! expanded-rows)`, and statusline-field normalization (spec 09 §5.7).
+
+use cma_config::dashboard_settings::{DashboardDisplaySettings, DashboardLayoutMode};
+use cma_tui::select::{select, MenuColor, MenuItem, SelectOptions};
+use cma_tui::ui_copy;
+use std::io::IsTerminal;
+
+use crate::settings::preview::normalize_statusline_fields;
+use crate::settings::schema::BackendNumberSettingOption;
+
+// ---------------------------------------------------------------------------
+// Shared helpers (`settings-hub/shared.ts`)
+// ---------------------------------------------------------------------------
+
+/// `isTtyInteractive()` — both stdin AND stdout must be TTYs.
+pub fn is_tty_interactive() -> bool {
+    std::io::stdin().is_terminal() && std::io::stdout().is_terminal()
+}
+
+/// `keyof DashboardDisplaySettings` — every settings field, for the per-panel
+/// key sets (copy/merge/reset are keyed by these).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DashboardSettingKey {
+    ShowPerAccountRows,
+    ShowQuotaDetails,
+    ShowForecastReasons,
+    ShowRecommendations,
+    ShowLiveProbeNotes,
+    ActionAutoReturnMs,
+    ActionPauseOnKey,
+    MenuAutoFetchLimits,
+    MenuSortEnabled,
+    MenuSortMode,
+    MenuSortPinCurrent,
+    MenuSortQuickSwitchVisibleRow,
+    UiThemePreset,
+    UiAccentColor,
+    MenuShowStatusBadge,
+    MenuShowCurrentBadge,
+    MenuShowLastUsed,
+    MenuShowQuotaSummary,
+    MenuShowQuotaCooldown,
+    MenuShowFetchStatus,
+    MenuShowDetailsForUnselectedRows,
+    MenuLayoutMode,
+    MenuQuotaTtlMs,
+    MenuFocusStyle,
+    MenuHighlightCurrentRow,
+    MenuStatuslineFields,
+}
+
+/// `copyDashboardSettingValue(target, source, key)` — one key, arrays copied.
+pub fn copy_dashboard_setting_value(
+    target: &mut DashboardDisplaySettings,
+    source: &DashboardDisplaySettings,
+    key: DashboardSettingKey,
+) {
+    use DashboardSettingKey as K;
+    match key {
+        K::ShowPerAccountRows => target.show_per_account_rows = source.show_per_account_rows,
+        K::ShowQuotaDetails => target.show_quota_details = source.show_quota_details,
+        K::ShowForecastReasons => target.show_forecast_reasons = source.show_forecast_reasons,
+        K::ShowRecommendations => target.show_recommendations = source.show_recommendations,
+        K::ShowLiveProbeNotes => target.show_live_probe_notes = source.show_live_probe_notes,
+        K::ActionAutoReturnMs => target.action_auto_return_ms = source.action_auto_return_ms,
+        K::ActionPauseOnKey => target.action_pause_on_key = source.action_pause_on_key,
+        K::MenuAutoFetchLimits => target.menu_auto_fetch_limits = source.menu_auto_fetch_limits,
+        K::MenuSortEnabled => target.menu_sort_enabled = source.menu_sort_enabled,
+        K::MenuSortMode => target.menu_sort_mode = source.menu_sort_mode,
+        K::MenuSortPinCurrent => target.menu_sort_pin_current = source.menu_sort_pin_current,
+        K::MenuSortQuickSwitchVisibleRow => {
+            target.menu_sort_quick_switch_visible_row = source.menu_sort_quick_switch_visible_row
+        }
+        K::UiThemePreset => target.ui_theme_preset = source.ui_theme_preset,
+        K::UiAccentColor => target.ui_accent_color = source.ui_accent_color,
+        K::MenuShowStatusBadge => target.menu_show_status_badge = source.menu_show_status_badge,
+        K::MenuShowCurrentBadge => target.menu_show_current_badge = source.menu_show_current_badge,
+        K::MenuShowLastUsed => target.menu_show_last_used = source.menu_show_last_used,
+        K::MenuShowQuotaSummary => target.menu_show_quota_summary = source.menu_show_quota_summary,
+        K::MenuShowQuotaCooldown => {
+            target.menu_show_quota_cooldown = source.menu_show_quota_cooldown
+        }
+        K::MenuShowFetchStatus => target.menu_show_fetch_status = source.menu_show_fetch_status,
+        K::MenuShowDetailsForUnselectedRows => {
+            target.menu_show_details_for_unselected_rows =
+                source.menu_show_details_for_unselected_rows
+        }
+        K::MenuLayoutMode => target.menu_layout_mode = source.menu_layout_mode,
+        K::MenuQuotaTtlMs => target.menu_quota_ttl_ms = source.menu_quota_ttl_ms,
+        K::MenuFocusStyle => target.menu_focus_style = source.menu_focus_style,
+        K::MenuHighlightCurrentRow => {
+            target.menu_highlight_current_row = source.menu_highlight_current_row
+        }
+        K::MenuStatuslineFields => {
+            target.menu_statusline_fields = source.menu_statusline_fields.clone()
+        }
+    }
+}
+
+/// `resolveMenuLayoutMode` — explicit layout wins; the legacy-boolean fallback
+/// only matters for pre-normalized data (unreachable on the normalized Rust
+/// struct but kept for faithful behavior of merged drafts).
+pub fn resolve_menu_layout_mode(settings: &DashboardDisplaySettings) -> DashboardLayoutMode {
+    settings.menu_layout_mode
+}
+
+/// `cloneDashboardSettings` (via `cloneDashboardSettingsData`) — clone with
+/// the TS clone's derived rules re-applied: resolved layout mode, the legacy
+/// boolean re-derived from the layout, and normalized statusline fields.
+pub fn clone_dashboard_settings(settings: &DashboardDisplaySettings) -> DashboardDisplaySettings {
+    let mut clone = settings.clone();
+    let layout = resolve_menu_layout_mode(settings);
+    clone.menu_layout_mode = layout;
+    clone.menu_show_details_for_unselected_rows = layout == DashboardLayoutMode::ExpandedRows;
+    clone.menu_statusline_fields =
+        normalize_statusline_fields(Some(&settings.menu_statusline_fields));
+    clone
+}
+
+/// `dashboardSettingsEqual` — default-insensitive comparison (both sides pass
+/// through the normalizing clone first).
+pub fn dashboard_settings_equal(
+    left: &DashboardDisplaySettings,
+    right: &DashboardDisplaySettings,
+) -> bool {
+    clone_dashboard_settings(left) == clone_dashboard_settings(right)
+}
+
+/// `applyDashboardDefaultsForKeys` — clone draft, copy each listed key from
+/// the defaults.
+pub fn apply_dashboard_defaults_for_keys(
+    draft: &DashboardDisplaySettings,
+    keys: &[DashboardSettingKey],
+) -> DashboardDisplaySettings {
+    let mut next = clone_dashboard_settings(draft);
+    let defaults = clone_dashboard_settings(&DashboardDisplaySettings::default());
+    for key in keys {
+        copy_dashboard_setting_value(&mut next, &defaults, *key);
+    }
+    next
+}
+
+/// `mergeDashboardSettingsForKeys` — clone base, copy listed keys from
+/// selected, clone again (re-normalizes the derived fields).
+pub fn merge_dashboard_settings_for_keys(
+    base: &DashboardDisplaySettings,
+    selected: &DashboardDisplaySettings,
+    keys: &[DashboardSettingKey],
+) -> DashboardDisplaySettings {
+    let mut next = clone_dashboard_settings(base);
+    for key in keys {
+        copy_dashboard_setting_value(&mut next, selected, *key);
+    }
+    clone_dashboard_settings(&next)
+}
+
+/// `clampBackendNumber(option, value)` = `max(min, min(max, round(value)))`.
+pub fn clamp_backend_number(option: &BackendNumberSettingOption, value: f64) -> f64 {
+    option.min.max(option.max.min(value.round()))
+}
+
+// -------------------------------------------------------------------------
+// Local mirrors of `dashboard-formatters.ts` (canonical Rust home is the
+// sibling-owned `crate::formatters::dashboard`; these crate-private copies
+// keep the settings cluster self-contained until integration).
+// -------------------------------------------------------------------------
+
+/// `formatDashboardSettingState(v)` → `"[x]"` / `"[ ]"`.
+pub(crate) fn format_dashboard_setting_state(value: bool) -> &'static str {
+    if value {
+        "[x]"
+    } else {
+        "[ ]"
+    }
+}
+
+/// `formatMenuSortMode(mode)` → `"Ready-First"` / `"Manual"`.
+pub(crate) fn format_menu_sort_mode(
+    mode: cma_config::dashboard_settings::DashboardAccountSortMode,
+) -> &'static str {
+    match mode {
+        cma_config::dashboard_settings::DashboardAccountSortMode::ReadyFirst => "Ready-First",
+        cma_config::dashboard_settings::DashboardAccountSortMode::Manual => "Manual",
+    }
+}
+
+/// `formatMenuLayoutMode(mode)` → `"Expanded Rows"` / `"Compact + Details Pane"`.
+pub(crate) fn format_menu_layout_mode(mode: DashboardLayoutMode) -> &'static str {
+    match mode {
+        DashboardLayoutMode::ExpandedRows => "Expanded Rows",
+        DashboardLayoutMode::CompactDetails => "Compact + Details Pane",
+    }
+}
+
+/// `formatMenuQuotaTtl(ms)` — `Nm` / `Ns` / `Nms` by divisibility, not
+/// magnitude (90_000 → `"90s"`, spec 09 gotcha 34).
+pub(crate) fn format_menu_quota_ttl(ttl_ms: i64) -> String {
+    if ttl_ms >= 60_000 && ttl_ms % 60_000 == 0 {
+        return format!("{}m", ttl_ms / 60_000);
+    }
+    if ttl_ms >= 1_000 && ttl_ms % 1_000 == 0 {
+        return format!("{}s", ttl_ms / 1_000);
+    }
+    format!("{ttl_ms}ms")
+}
+
+/// `applyUiThemeFromDashboardSettings(settings)` — preserves runtime-detected
+/// capabilities (v2 flag, color profile, glyph mode) and swaps only the
+/// palette/accent from the dashboard settings. (TS source:
+/// `settings-hub/dashboard.ts`; exposed from the hub module because the
+/// dispatcher and login flow consume it from here.)
+pub fn apply_ui_theme_from_dashboard_settings(settings: &DashboardDisplaySettings) {
+    use cma_config::dashboard_settings::{DashboardAccentColor, DashboardThemePreset};
+    use cma_tui::theme::{UiAccent, UiPalette};
+    let current = cma_tui::runtime_options::get_ui_runtime_options();
+    let palette = match settings.ui_theme_preset {
+        DashboardThemePreset::Green => UiPalette::Green,
+        DashboardThemePreset::Blue => UiPalette::Blue,
+    };
+    let accent = match settings.ui_accent_color {
+        DashboardAccentColor::Green => UiAccent::Green,
+        DashboardAccentColor::Cyan => UiAccent::Cyan,
+        DashboardAccentColor::Blue => UiAccent::Blue,
+        DashboardAccentColor::Yellow => UiAccent::Yellow,
+    };
+    cma_tui::runtime_options::set_ui_runtime_options(cma_tui::runtime_options::UiRuntimeOptionsPatch {
+        v2_enabled: Some(current.v2_enabled),
+        color_profile: Some(current.color_profile),
+        glyph_mode: Some(current.glyph_mode),
+        palette: Some(palette),
+        accent: Some(accent),
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Hub menu (`settings-hub-menu.ts` / `settings-hub-prompt.ts`)
+// ---------------------------------------------------------------------------
+
+/// `SettingsHubMenuAction` / `SettingsHubAction` — one shared enum in Rust.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SettingsHubAction {
+    AccountList,
+    SummaryFields,
+    Behavior,
+    Theme,
+    Experimental,
+    Backend,
+    Back,
+}
+
+impl SettingsHubAction {
+    pub fn type_str(self) -> &'static str {
+        match self {
+            Self::AccountList => "account-list",
+            Self::SummaryFields => "summary-fields",
+            Self::Behavior => "behavior",
+            Self::Theme => "theme",
+            Self::Experimental => "experimental",
+            Self::Backend => "backend",
+            Self::Back => "back",
+        }
+    }
+}
+
+/// `buildSettingsHubItems(UI_COPY.settings)` — fixed layout.
+pub fn build_settings_hub_items() -> Vec<MenuItem<SettingsHubAction>> {
+    vec![
+        MenuItem::heading(ui_copy::settings::SECTION_TITLE, SettingsHubAction::Back),
+        MenuItem::new(ui_copy::settings::ACCOUNT_LIST, SettingsHubAction::AccountList)
+            .with_color(MenuColor::Green),
+        MenuItem::new(
+            ui_copy::settings::SUMMARY_FIELDS,
+            SettingsHubAction::SummaryFields,
+        )
+        .with_color(MenuColor::Green),
+        MenuItem::new(ui_copy::settings::BEHAVIOR, SettingsHubAction::Behavior)
+            .with_color(MenuColor::Green),
+        MenuItem::new(ui_copy::settings::THEME, SettingsHubAction::Theme)
+            .with_color(MenuColor::Green),
+        MenuItem::separator(SettingsHubAction::Back),
+        MenuItem::heading(ui_copy::settings::ADVANCED_TITLE, SettingsHubAction::Back),
+        MenuItem::new(
+            ui_copy::settings::EXPERIMENTAL,
+            SettingsHubAction::Experimental,
+        )
+        .with_color(MenuColor::Yellow),
+        MenuItem::new(ui_copy::settings::BACKEND, SettingsHubAction::Backend)
+            .with_color(MenuColor::Green),
+        MenuItem::separator(SettingsHubAction::Back),
+        MenuItem::heading(ui_copy::settings::EXIT_TITLE, SettingsHubAction::Back),
+        MenuItem::new(ui_copy::settings::BACK, SettingsHubAction::Back).with_color(MenuColor::Red),
+    ]
+}
+
+/// `findSettingsHubInitialCursor` — first non-separator/disabled/heading item
+/// with the requested action type.
+pub fn find_settings_hub_initial_cursor(
+    items: &[MenuItem<SettingsHubAction>],
+    initial_focus: SettingsHubAction,
+) -> Option<i64> {
+    items
+        .iter()
+        .position(|item| {
+            if item.separator || item.disabled || item.heading {
+                return false;
+            }
+            item.value == initial_focus
+        })
+        .map(|index| index as i64)
+}
+
+/// `promptSettingsHubMenu` — non-interactive → `None`; hotkey `q` → back.
+pub fn prompt_settings_hub_menu(initial_focus: SettingsHubAction) -> Option<SettingsHubAction> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let ui = cma_tui::runtime_options::get_ui_runtime_options();
+    let items = build_settings_hub_items();
+    let initial_cursor = find_settings_hub_initial_cursor(&items, initial_focus);
+
+    let mut options: SelectOptions<'_, SettingsHubAction> =
+        SelectOptions::new(ui_copy::settings::TITLE);
+    options.subtitle = Some(ui_copy::settings::SUBTITLE.to_string());
+    options.help = Some(ui_copy::settings::HELP.to_string());
+    options.clear_screen = true;
+    options.theme = Some(ui.theme.clone());
+    options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+    options.initial_cursor = initial_cursor;
+    options.on_input = Some(Box::new(|raw, _ctx| {
+        if raw.to_lowercase() == "q" {
+            cma_tui::select::SelectInputResult::Finish(Some(SettingsHubAction::Back))
+        } else {
+            cma_tui::select::SelectInputResult::Ignored
+        }
+    }));
+
+    select(&items, options).ok().flatten()
+}
+
+/// `promptSettingsHub(initialFocus = "account-list")`.
+pub fn prompt_settings_hub(initial_focus: SettingsHubAction) -> Option<SettingsHubAction> {
+    prompt_settings_hub_menu(initial_focus)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_config::dashboard_settings::{
+        DashboardAccountSortMode, DashboardStatuslineField, DashboardThemePreset,
+    };
+
+    #[test]
+    fn hub_items_have_the_fixed_layout() {
+        let items = build_settings_hub_items();
+        assert_eq!(items.len(), 12);
+        assert!(items[0].heading);
+        assert_eq!(items[0].label, "Basic");
+        assert_eq!(items[1].value, SettingsHubAction::AccountList);
+        assert_eq!(items[1].color, Some(MenuColor::Green));
+        assert_eq!(items[4].value, SettingsHubAction::Theme);
+        assert!(items[5].separator);
+        assert_eq!(items[6].label, "Advanced");
+        assert_eq!(items[7].value, SettingsHubAction::Experimental);
+        assert_eq!(items[7].color, Some(MenuColor::Yellow));
+        assert_eq!(items[8].value, SettingsHubAction::Backend);
+        assert!(items[9].separator);
+        assert_eq!(items[10].label, "Back");
+        assert_eq!(items[11].value, SettingsHubAction::Back);
+        assert_eq!(items[11].color, Some(MenuColor::Red));
+    }
+
+    #[test]
+    fn initial_cursor_skips_headings_and_separators() {
+        let items = build_settings_hub_items();
+        assert_eq!(
+            find_settings_hub_initial_cursor(&items, SettingsHubAction::AccountList),
+            Some(1)
+        );
+        assert_eq!(
+            find_settings_hub_initial_cursor(&items, SettingsHubAction::Backend),
+            Some(8)
+        );
+        // "back" resolves to the LAST item (headings/separators carry the
+        // back value but are filtered out).
+        assert_eq!(
+            find_settings_hub_initial_cursor(&items, SettingsHubAction::Back),
+            Some(11)
+        );
+    }
+
+    #[test]
+    fn clone_derives_legacy_boolean_from_layout() {
+        let settings = DashboardDisplaySettings {
+            menu_layout_mode: DashboardLayoutMode::ExpandedRows,
+            menu_show_details_for_unselected_rows: false, // stale
+            ..Default::default()
+        };
+        let clone = clone_dashboard_settings(&settings);
+        assert!(clone.menu_show_details_for_unselected_rows);
+        assert_eq!(clone.menu_layout_mode, DashboardLayoutMode::ExpandedRows);
+    }
+
+    #[test]
+    fn clone_normalizes_statusline_fields() {
+        let settings = DashboardDisplaySettings {
+            menu_statusline_fields: vec![
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Limits,
+            ],
+            ..Default::default()
+        };
+        let clone = clone_dashboard_settings(&settings);
+        assert_eq!(
+            clone.menu_statusline_fields,
+            vec![DashboardStatuslineField::Limits]
+        );
+    }
+
+    #[test]
+    fn equality_is_normalization_insensitive() {
+        let left = DashboardDisplaySettings::default();
+        let mut right = DashboardDisplaySettings {
+            menu_statusline_fields: vec![
+                DashboardStatuslineField::LastUsed,
+                DashboardStatuslineField::LastUsed,
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Status,
+            ],
+            ..Default::default()
+        };
+        assert!(dashboard_settings_equal(&left, &right));
+        right.menu_sort_mode = DashboardAccountSortMode::Manual;
+        assert!(!dashboard_settings_equal(&left, &right));
+    }
+
+    #[test]
+    fn merge_copies_only_the_listed_keys() {
+        let base = DashboardDisplaySettings::default();
+        let selected = DashboardDisplaySettings {
+            menu_show_fetch_status: false,
+            ui_theme_preset: DashboardThemePreset::Blue,
+            ..Default::default()
+        };
+        let merged = merge_dashboard_settings_for_keys(
+            &base,
+            &selected,
+            &[DashboardSettingKey::MenuShowFetchStatus],
+        );
+        assert!(!merged.menu_show_fetch_status);
+        // ui_theme_preset was NOT in the key set — stays at base value.
+        assert_eq!(merged.ui_theme_preset, DashboardThemePreset::Green);
+    }
+
+    #[test]
+    fn apply_defaults_resets_only_the_listed_keys() {
+        let draft = DashboardDisplaySettings {
+            menu_show_fetch_status: false,
+            action_auto_return_ms: 4_000,
+            ..Default::default()
+        };
+        let reset = apply_dashboard_defaults_for_keys(
+            &draft,
+            &[DashboardSettingKey::MenuShowFetchStatus],
+        );
+        assert!(reset.menu_show_fetch_status);
+        assert_eq!(reset.action_auto_return_ms, 4_000);
+    }
+
+    #[test]
+    fn clamp_backend_number_rounds_then_clamps() {
+        let option = crate::settings::schema::backend_number_option_by_key(
+            crate::settings::schema::BackendNumberSettingKey::ParallelProbingMaxConcurrency,
+        );
+        assert_eq!(clamp_backend_number(option, 2.4), 2.0);
+        assert_eq!(clamp_backend_number(option, 99.0), 5.0);
+        assert_eq!(clamp_backend_number(option, -3.0), 1.0);
+        assert_eq!(clamp_backend_number(option, 2.6), 3.0);
+    }
+}
diff --git a/crates/manager/src/settings/mod.rs b/crates/manager/src/settings/mod.rs
new file mode 100644
index 000000000..a4284a3f3
--- /dev/null
+++ b/crates/manager/src/settings/mod.rs
@@ -0,0 +1,10 @@
+//! cma-manager - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod backend;
+pub mod dashboard;
+pub mod experimental;
+pub mod hub;
+pub mod panels;
+pub mod persist;
+pub mod preview;
+pub mod schema;
+pub mod write_queue;
diff --git a/crates/manager/src/settings/panels.rs b/crates/manager/src/settings/panels.rs
new file mode 100644
index 000000000..ca1f1ab27
--- /dev/null
+++ b/crates/manager/src/settings/panels.rs
@@ -0,0 +1,720 @@
+//! Port of `settings-panels.ts` + `behavior-settings-panel.ts` +
+//! `statusline-settings-panel.ts` + `theme-settings-panel.ts` (entry shims
+//! absorbed) — the remaining interactive settings panels.
+//!
+//! Shared panel contract (spec 09 §5.10): TTY-gate (`None` when not fully
+//! TTY), clone-into-draft, `select` loop with `clearScreen`, focus restored
+//! via `initialCursor`, and: `None` on cancel (`q`/escape/null), the draft on
+//! save (`s`), reset (`r`) re-applies the panel's key-set defaults. The theme
+//! panel applies theme changes LIVE and restores the baseline on cancel.
+
+use std::cell::RefCell;
+
+use cma_config::dashboard_settings::{
+    DashboardAccentColor, DashboardDisplaySettings, DashboardStatuslineField, DashboardThemePreset,
+};
+use cma_tui::runtime_options::get_ui_runtime_options;
+use cma_tui::select::{select, MenuColor, MenuItem, SelectInputResult, SelectOptions};
+use cma_tui::ui_copy;
+
+use crate::settings::dashboard::{
+    ACCENT_COLOR_OPTIONS, AUTO_RETURN_OPTIONS_MS, BEHAVIOR_PANEL_KEYS, MENU_QUOTA_TTL_OPTIONS_MS,
+    STATUSLINE_FIELD_OPTIONS, STATUSLINE_PANEL_KEYS, THEME_PANEL_KEYS, THEME_PRESET_OPTIONS,
+};
+use crate::settings::hub::{
+    apply_dashboard_defaults_for_keys, apply_ui_theme_from_dashboard_settings,
+    clone_dashboard_settings, format_dashboard_setting_state, format_menu_quota_ttl,
+    is_tty_interactive, resolve_menu_layout_mode,
+};
+use crate::settings::preview::{
+    build_account_list_preview, normalize_statusline_fields, PreviewFocusKey,
+};
+
+// ---------------------------------------------------------------------------
+// Pure helpers (`settings-panels.ts`)
+// ---------------------------------------------------------------------------
+
+/// `reorderStatuslineField(fields, key, direction)` — swap with the
+/// neighbor; out-of-range or missing → the input unchanged.
+pub fn reorder_statusline_field(
+    fields: &[DashboardStatuslineField],
+    key: DashboardStatuslineField,
+    direction: i32,
+) -> Vec<DashboardStatuslineField> {
+    let Some(index) = fields.iter().position(|field| *field == key) else {
+        return fields.to_vec();
+    };
+    let target = index as i64 + direction as i64;
+    if target < 0 || target >= fields.len() as i64 {
+        return fields.to_vec();
+    }
+    let mut next = fields.to_vec();
+    next.swap(index, target as usize);
+    next
+}
+
+/// `formatAutoReturnDelayLabel(delayMs)` — `<= 0` → `"Instant return"`, else
+/// `"<round(ms/1000)>s auto-return"`.
+pub fn format_auto_return_delay_label(delay_ms: i64) -> String {
+    if delay_ms <= 0 {
+        "Instant return".to_string()
+    } else {
+        format!("{}s auto-return", ((delay_ms as f64) / 1000.0).round() as i64)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Behavior panel (`behavior-settings-panel.ts`)
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum BehaviorConfigAction {
+    SetDelay(i64),
+    TogglePause,
+    ToggleMenuLimitFetch,
+    ToggleMenuFetchStatus,
+    SetMenuQuotaTtl(i64),
+    Reset,
+    Save,
+    Cancel,
+}
+
+/// `promptBehaviorSettingsPanel`.
+// The focus re-read after `select` mirrors the TS mutable-cursor pattern
+// (same rationale as `select.rs`); some arms overwrite it, tripping the lint.
+#[allow(unused_assignments)]
+pub fn prompt_behavior_settings_panel(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let ui = get_ui_runtime_options();
+    let mut draft = clone_dashboard_settings(initial);
+    let mut focus = BehaviorConfigAction::SetDelay(draft.action_auto_return_ms);
+
+    loop {
+        let current_delay = draft.action_auto_return_ms;
+        let pause_on_key = draft.action_pause_on_key;
+        let auto_fetch_limits = draft.menu_auto_fetch_limits;
+        let fetch_status_visible = draft.menu_show_fetch_status;
+        let menu_quota_ttl_ms = draft.menu_quota_ttl_ms;
+
+        let mut items: Vec<MenuItem<BehaviorConfigAction>> = vec![MenuItem::heading(
+            ui_copy::settings::ACTION_TIMING,
+            BehaviorConfigAction::Cancel,
+        )];
+        for delay_ms in AUTO_RETURN_OPTIONS_MS {
+            let selected = current_delay == delay_ms;
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}",
+                        if selected { "[x]" } else { "[ ]" },
+                        format_auto_return_delay_label(delay_ms)
+                    ),
+                    BehaviorConfigAction::SetDelay(delay_ms),
+                )
+                .with_hint(match delay_ms {
+                    1_000 => "Fastest loop for frequent actions.",
+                    2_000 => "Balanced default for most users.",
+                    _ => "More time to read action output.",
+                })
+                .with_color(if selected {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        items.push(MenuItem::separator(BehaviorConfigAction::Cancel));
+        items.push(
+            MenuItem::new(
+                format!(
+                    "{} Pause on key press",
+                    if pause_on_key { "[x]" } else { "[ ]" }
+                ),
+                BehaviorConfigAction::TogglePause,
+            )
+            .with_hint("Press any key to stop auto-return.")
+            .with_color(if pause_on_key {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        );
+        items.push(
+            MenuItem::new(
+                format!(
+                    "{} Auto-fetch limits on menu open (5m cache)",
+                    if auto_fetch_limits { "[x]" } else { "[ ]" }
+                ),
+                BehaviorConfigAction::ToggleMenuLimitFetch,
+            )
+            .with_hint("Refreshes account limits automatically when opening the menu.")
+            .with_color(if auto_fetch_limits {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        );
+        items.push(
+            MenuItem::new(
+                format!(
+                    "{} Show limit refresh status",
+                    if fetch_status_visible { "[x]" } else { "[ ]" }
+                ),
+                BehaviorConfigAction::ToggleMenuFetchStatus,
+            )
+            .with_hint("Shows background fetch progress like [2/7] in menu subtitle.")
+            .with_color(if fetch_status_visible {
+                MenuColor::Green
+            } else {
+                MenuColor::Yellow
+            }),
+        );
+        items.push(
+            MenuItem::new(
+                format!(
+                    "Limit cache TTL: {}",
+                    format_menu_quota_ttl(menu_quota_ttl_ms)
+                ),
+                BehaviorConfigAction::SetMenuQuotaTtl(menu_quota_ttl_ms),
+            )
+            .with_hint("How fresh cached quota data must be before refresh runs.")
+            .with_color(MenuColor::Yellow),
+        );
+        items.push(MenuItem::separator(BehaviorConfigAction::Cancel));
+        items.push(
+            MenuItem::new(ui_copy::settings::RESET_DEFAULT, BehaviorConfigAction::Reset)
+                .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::SAVE_AND_BACK, BehaviorConfigAction::Save)
+                .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::BACK_NO_SAVE, BehaviorConfigAction::Cancel)
+                .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(|item| item.value == focus);
+
+        let focus_cell: RefCell<BehaviorConfigAction> = RefCell::new(focus);
+        let focus_ref = &focus_cell;
+
+        let mut options: SelectOptions<'_, BehaviorConfigAction> =
+            SelectOptions::new(ui_copy::settings::BEHAVIOR_TITLE);
+        options.subtitle = Some(ui_copy::settings::BEHAVIOR_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::BEHAVIOR_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        options.on_cursor_change = Some(Box::new(move |ctx| {
+            if let Some(item) = ctx.items.get(ctx.cursor)
+                && !item.separator && !item.heading {
+                    *focus_ref.borrow_mut() = item.value;
+                }
+        }));
+        options.on_input = Some(Box::new(move |raw, _ctx| {
+            let lower = raw.to_lowercase();
+            match lower.as_str() {
+                "q" => return SelectInputResult::Finish(Some(BehaviorConfigAction::Cancel)),
+                "s" => return SelectInputResult::Finish(Some(BehaviorConfigAction::Save)),
+                "r" => return SelectInputResult::Finish(Some(BehaviorConfigAction::Reset)),
+                "p" => return SelectInputResult::Finish(Some(BehaviorConfigAction::TogglePause)),
+                "l" => {
+                    return SelectInputResult::Finish(Some(
+                        BehaviorConfigAction::ToggleMenuLimitFetch,
+                    ))
+                }
+                "f" => {
+                    return SelectInputResult::Finish(Some(
+                        BehaviorConfigAction::ToggleMenuFetchStatus,
+                    ))
+                }
+                "t" => {
+                    return SelectInputResult::Finish(Some(BehaviorConfigAction::SetMenuQuotaTtl(
+                        menu_quota_ttl_ms,
+                    )))
+                }
+                _ => {}
+            }
+            if let Ok(parsed) = raw.trim().parse::<usize>()
+                && parsed >= 1 && parsed <= AUTO_RETURN_OPTIONS_MS.len() {
+                    return SelectInputResult::Finish(Some(BehaviorConfigAction::SetDelay(
+                        AUTO_RETURN_OPTIONS_MS[parsed - 1],
+                    )));
+                }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        focus = *focus_cell.borrow();
+
+        let result = result?;
+        match result {
+            BehaviorConfigAction::Cancel => return None,
+            BehaviorConfigAction::Save => return Some(draft),
+            BehaviorConfigAction::Reset => {
+                draft = apply_dashboard_defaults_for_keys(&draft, &BEHAVIOR_PANEL_KEYS);
+                focus = BehaviorConfigAction::SetDelay(draft.action_auto_return_ms);
+            }
+            BehaviorConfigAction::TogglePause => {
+                draft.action_pause_on_key = !draft.action_pause_on_key;
+                focus = result;
+            }
+            BehaviorConfigAction::ToggleMenuLimitFetch => {
+                draft.menu_auto_fetch_limits = !draft.menu_auto_fetch_limits;
+                focus = result;
+            }
+            BehaviorConfigAction::ToggleMenuFetchStatus => {
+                draft.menu_show_fetch_status = !draft.menu_show_fetch_status;
+                focus = result;
+            }
+            BehaviorConfigAction::SetMenuQuotaTtl(_) => {
+                let current_index = MENU_QUOTA_TTL_OPTIONS_MS
+                    .iter()
+                    .position(|value| *value == menu_quota_ttl_ms);
+                let next_index = match current_index {
+                    None => 0,
+                    Some(index) => (index + 1) % MENU_QUOTA_TTL_OPTIONS_MS.len(),
+                };
+                let next_ttl = MENU_QUOTA_TTL_OPTIONS_MS[next_index];
+                draft.menu_quota_ttl_ms = next_ttl;
+                focus = BehaviorConfigAction::SetMenuQuotaTtl(next_ttl);
+            }
+            BehaviorConfigAction::SetDelay(delay_ms) => {
+                draft.action_auto_return_ms = delay_ms;
+                focus = result;
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Statusline panel (`statusline-settings-panel.ts`)
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum StatuslineConfigAction {
+    Toggle(DashboardStatuslineField),
+    MoveUp(DashboardStatuslineField),
+    MoveDown(DashboardStatuslineField),
+    Reset,
+    Save,
+    Cancel,
+}
+
+/// `promptStatuslineSettingsPanel` — toggling off the LAST remaining field is
+/// prevented (the field set never becomes empty).
+// See prompt_behavior_settings_panel for the unused_assignments rationale.
+#[allow(unused_assignments)]
+pub fn prompt_statusline_settings_panel(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let ui = get_ui_runtime_options();
+    let mut draft = clone_dashboard_settings(initial);
+    let mut focus_key = draft
+        .menu_statusline_fields
+        .first()
+        .copied()
+        .unwrap_or(DashboardStatuslineField::LastUsed);
+
+    loop {
+        let preview = build_account_list_preview(
+            &draft,
+            &ui,
+            &resolve_menu_layout_mode,
+            Some(PreviewFocusKey::from_statusline_field(focus_key)),
+        );
+        let ordered = normalize_statusline_fields(Some(&draft.menu_statusline_fields));
+
+        let mut items: Vec<MenuItem<StatuslineConfigAction>> = vec![
+            MenuItem::heading(
+                ui_copy::settings::PREVIEW_HEADING,
+                StatuslineConfigAction::Cancel,
+            ),
+            {
+                let mut item = MenuItem::new(preview.label.clone(), StatuslineConfigAction::Cancel)
+                    .with_hint(preview.hint.clone())
+                    .with_color(MenuColor::Green);
+                item.disabled = true;
+                item.hide_unavailable_suffix = true;
+                item
+            },
+            MenuItem::separator(StatuslineConfigAction::Cancel),
+            MenuItem::heading(
+                ui_copy::settings::DISPLAY_HEADING,
+                StatuslineConfigAction::Cancel,
+            ),
+        ];
+        for (index, option) in STATUSLINE_FIELD_OPTIONS.iter().enumerate() {
+            let enabled = ordered.contains(&option.key);
+            let rank = ordered.iter().position(|field| *field == option.key);
+            let rank_suffix = match rank {
+                Some(rank) => format!(" (order {})", rank + 1),
+                None => String::new(),
+            };
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}. {}{}",
+                        format_dashboard_setting_state(enabled),
+                        index + 1,
+                        option.label,
+                        rank_suffix
+                    ),
+                    StatuslineConfigAction::Toggle(option.key),
+                )
+                .with_hint(option.description)
+                .with_color(if enabled {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        items.push(MenuItem::separator(StatuslineConfigAction::Cancel));
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::MOVE_UP,
+                StatuslineConfigAction::MoveUp(focus_key),
+            )
+            .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::MOVE_DOWN,
+                StatuslineConfigAction::MoveDown(focus_key),
+            )
+            .with_color(MenuColor::Green),
+        );
+        items.push(MenuItem::separator(StatuslineConfigAction::Cancel));
+        items.push(
+            MenuItem::new(
+                ui_copy::settings::RESET_DEFAULT,
+                StatuslineConfigAction::Reset,
+            )
+            .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::SAVE_AND_BACK, StatuslineConfigAction::Save)
+                .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::BACK_NO_SAVE, StatuslineConfigAction::Cancel)
+                .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(
+            |item| matches!(item.value, StatuslineConfigAction::Toggle(key) if key == focus_key),
+        );
+
+        let focus_cell: RefCell<DashboardStatuslineField> = RefCell::new(focus_key);
+        let focus_for_cursor = &focus_cell;
+        let focus_for_input = &focus_cell;
+
+        let mut options: SelectOptions<'_, StatuslineConfigAction> =
+            SelectOptions::new(ui_copy::settings::SUMMARY_TITLE);
+        options.subtitle = Some(ui_copy::settings::SUMMARY_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::SUMMARY_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        options.on_cursor_change = Some(Box::new(move |ctx| {
+            if let Some(StatuslineConfigAction::Toggle(key)) =
+                ctx.items.get(ctx.cursor).map(|item| item.value)
+            {
+                *focus_for_cursor.borrow_mut() = key;
+            }
+        }));
+        options.on_input = Some(Box::new(move |raw, _ctx| {
+            let lower = raw.to_lowercase();
+            match lower.as_str() {
+                "q" => return SelectInputResult::Finish(Some(StatuslineConfigAction::Cancel)),
+                "s" => return SelectInputResult::Finish(Some(StatuslineConfigAction::Save)),
+                "r" => return SelectInputResult::Finish(Some(StatuslineConfigAction::Reset)),
+                "[" => {
+                    return SelectInputResult::Finish(Some(StatuslineConfigAction::MoveUp(
+                        *focus_for_input.borrow(),
+                    )))
+                }
+                "]" => {
+                    return SelectInputResult::Finish(Some(StatuslineConfigAction::MoveDown(
+                        *focus_for_input.borrow(),
+                    )))
+                }
+                _ => {}
+            }
+            if let Ok(parsed) = raw.trim().parse::<usize>()
+                && parsed >= 1 && parsed <= STATUSLINE_FIELD_OPTIONS.len() {
+                    return SelectInputResult::Finish(Some(StatuslineConfigAction::Toggle(
+                        STATUSLINE_FIELD_OPTIONS[parsed - 1].key,
+                    )));
+                }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        focus_key = *focus_cell.borrow();
+
+        let result = result?;
+        match result {
+            StatuslineConfigAction::Cancel => return None,
+            StatuslineConfigAction::Save => return Some(draft),
+            StatuslineConfigAction::Reset => {
+                draft = apply_dashboard_defaults_for_keys(&draft, &STATUSLINE_PANEL_KEYS);
+                focus_key = draft
+                    .menu_statusline_fields
+                    .first()
+                    .copied()
+                    .unwrap_or(DashboardStatuslineField::LastUsed);
+            }
+            StatuslineConfigAction::MoveUp(key) => {
+                let fields = normalize_statusline_fields(Some(&draft.menu_statusline_fields));
+                draft.menu_statusline_fields = reorder_statusline_field(&fields, key, -1);
+                focus_key = key;
+            }
+            StatuslineConfigAction::MoveDown(key) => {
+                let fields = normalize_statusline_fields(Some(&draft.menu_statusline_fields));
+                draft.menu_statusline_fields = reorder_statusline_field(&fields, key, 1);
+                focus_key = key;
+            }
+            StatuslineConfigAction::Toggle(key) => {
+                focus_key = key;
+                let fields = normalize_statusline_fields(Some(&draft.menu_statusline_fields));
+                if fields.contains(&key) {
+                    let next: Vec<_> =
+                        fields.iter().copied().filter(|field| *field != key).collect();
+                    draft.menu_statusline_fields =
+                        if next.is_empty() { vec![key] } else { next };
+                } else {
+                    let mut next = fields;
+                    next.push(key);
+                    draft.menu_statusline_fields = next;
+                }
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Theme panel (`theme-settings-panel.ts`)
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ThemeConfigAction {
+    SetPalette(DashboardThemePreset),
+    SetAccent(DashboardAccentColor),
+    Reset,
+    Save,
+    Cancel,
+}
+
+/// `promptThemeSettingsPanel` — every palette/accent/reset change applies the
+/// theme LIVE; cancel restores the baseline theme before returning `None`.
+// See prompt_behavior_settings_panel for the unused_assignments rationale.
+#[allow(unused_assignments)]
+pub fn prompt_theme_settings_panel(
+    initial: &DashboardDisplaySettings,
+) -> Option<DashboardDisplaySettings> {
+    if !is_tty_interactive() {
+        return None;
+    }
+    let baseline = clone_dashboard_settings(initial);
+    let mut draft = clone_dashboard_settings(initial);
+    let mut focus = ThemeConfigAction::SetPalette(draft.ui_theme_preset);
+
+    loop {
+        // Re-read every iteration so the menu renders in the just-applied
+        // theme.
+        let ui = get_ui_runtime_options();
+        let palette = draft.ui_theme_preset;
+        let accent = draft.ui_accent_color;
+
+        let mut items: Vec<MenuItem<ThemeConfigAction>> = vec![MenuItem::heading(
+            ui_copy::settings::BASE_THEME,
+            ThemeConfigAction::Cancel,
+        )];
+        for (index, candidate) in THEME_PRESET_OPTIONS.iter().enumerate() {
+            let selected = palette == *candidate;
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}. {}",
+                        if selected { "[x]" } else { "[ ]" },
+                        index + 1,
+                        match candidate {
+                            DashboardThemePreset::Green => "Green base",
+                            DashboardThemePreset::Blue => "Blue base",
+                        }
+                    ),
+                    ThemeConfigAction::SetPalette(*candidate),
+                )
+                .with_hint(match candidate {
+                    DashboardThemePreset::Green => "High-contrast default.",
+                    DashboardThemePreset::Blue => "Codex-style blue look.",
+                })
+                .with_color(if selected {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        items.push(MenuItem::separator(ThemeConfigAction::Cancel));
+        items.push(MenuItem::heading(
+            ui_copy::settings::ACCENT_COLOR,
+            ThemeConfigAction::Cancel,
+        ));
+        for candidate in ACCENT_COLOR_OPTIONS {
+            let selected = accent == candidate;
+            items.push(
+                MenuItem::new(
+                    format!(
+                        "{} {}",
+                        if selected { "[x]" } else { "[ ]" },
+                        candidate.as_str()
+                    ),
+                    ThemeConfigAction::SetAccent(candidate),
+                )
+                .with_color(if selected {
+                    MenuColor::Green
+                } else {
+                    MenuColor::Yellow
+                }),
+            );
+        }
+        items.push(MenuItem::separator(ThemeConfigAction::Cancel));
+        items.push(
+            MenuItem::new(ui_copy::settings::RESET_DEFAULT, ThemeConfigAction::Reset)
+                .with_color(MenuColor::Yellow),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::SAVE_AND_BACK, ThemeConfigAction::Save)
+                .with_color(MenuColor::Green),
+        );
+        items.push(
+            MenuItem::new(ui_copy::settings::BACK_NO_SAVE, ThemeConfigAction::Cancel)
+                .with_color(MenuColor::Red),
+        );
+
+        let initial_cursor = items.iter().position(|item| item.value == focus);
+
+        let focus_cell: RefCell<ThemeConfigAction> = RefCell::new(focus);
+        let focus_ref = &focus_cell;
+
+        let mut options: SelectOptions<'_, ThemeConfigAction> =
+            SelectOptions::new(ui_copy::settings::THEME_TITLE);
+        options.subtitle = Some(ui_copy::settings::THEME_SUBTITLE.to_string());
+        options.help = Some(ui_copy::settings::THEME_HELP.to_string());
+        options.clear_screen = true;
+        options.theme = Some(ui.theme.clone());
+        options.selected_emphasis = Some(cma_tui::select::SelectedEmphasis::Chip);
+        options.initial_cursor = initial_cursor.map(|cursor| cursor as i64);
+        options.on_cursor_change = Some(Box::new(move |ctx| {
+            if let Some(item) = ctx.items.get(ctx.cursor)
+                && !item.separator && !item.heading {
+                    *focus_ref.borrow_mut() = item.value;
+                }
+        }));
+        options.on_input = Some(Box::new(|raw, _ctx| {
+            let lower = raw.to_lowercase();
+            match lower.as_str() {
+                "q" => return SelectInputResult::Finish(Some(ThemeConfigAction::Cancel)),
+                "s" => return SelectInputResult::Finish(Some(ThemeConfigAction::Save)),
+                "r" => return SelectInputResult::Finish(Some(ThemeConfigAction::Reset)),
+                _ => {}
+            }
+            if raw == "1" {
+                return SelectInputResult::Finish(Some(ThemeConfigAction::SetPalette(
+                    DashboardThemePreset::Green,
+                )));
+            }
+            if raw == "2" {
+                return SelectInputResult::Finish(Some(ThemeConfigAction::SetPalette(
+                    DashboardThemePreset::Blue,
+                )));
+            }
+            SelectInputResult::Ignored
+        }));
+
+        let result = select(&items, options).ok().flatten();
+        focus = *focus_cell.borrow();
+
+        let Some(result) = result else {
+            apply_ui_theme_from_dashboard_settings(&baseline);
+            return None;
+        };
+        match result {
+            ThemeConfigAction::Cancel => {
+                apply_ui_theme_from_dashboard_settings(&baseline);
+                return None;
+            }
+            ThemeConfigAction::Save => return Some(draft),
+            ThemeConfigAction::Reset => {
+                draft = apply_dashboard_defaults_for_keys(&draft, &THEME_PANEL_KEYS);
+                focus = ThemeConfigAction::SetPalette(draft.ui_theme_preset);
+                apply_ui_theme_from_dashboard_settings(&draft);
+            }
+            ThemeConfigAction::SetPalette(palette) => {
+                draft.ui_theme_preset = palette;
+                focus = result;
+                apply_ui_theme_from_dashboard_settings(&draft);
+            }
+            ThemeConfigAction::SetAccent(accent) => {
+                draft.ui_accent_color = accent;
+                focus = result;
+                apply_ui_theme_from_dashboard_settings(&draft);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use DashboardStatuslineField as F;
+
+    #[test]
+    fn reorder_swaps_neighbors_and_ignores_out_of_range() {
+        let fields = [F::LastUsed, F::Limits, F::Status];
+        assert_eq!(
+            reorder_statusline_field(&fields, F::Limits, -1),
+            vec![F::Limits, F::LastUsed, F::Status]
+        );
+        assert_eq!(
+            reorder_statusline_field(&fields, F::Limits, 1),
+            vec![F::LastUsed, F::Status, F::Limits]
+        );
+        // First item up / last item down → unchanged.
+        assert_eq!(
+            reorder_statusline_field(&fields, F::LastUsed, -1),
+            fields.to_vec()
+        );
+        assert_eq!(
+            reorder_statusline_field(&fields, F::Status, 1),
+            fields.to_vec()
+        );
+        // Missing key → unchanged.
+        assert_eq!(
+            reorder_statusline_field(&[F::LastUsed], F::Status, 1),
+            vec![F::LastUsed]
+        );
+    }
+
+    #[test]
+    fn auto_return_delay_labels() {
+        assert_eq!(format_auto_return_delay_label(0), "Instant return");
+        assert_eq!(format_auto_return_delay_label(-5), "Instant return");
+        assert_eq!(format_auto_return_delay_label(1_000), "1s auto-return");
+        assert_eq!(format_auto_return_delay_label(2_000), "2s auto-return");
+        assert_eq!(format_auto_return_delay_label(1_500), "2s auto-return");
+    }
+}
diff --git a/crates/manager/src/settings/persist.rs b/crates/manager/src/settings/persist.rs
new file mode 100644
index 000000000..3477a50d7
--- /dev/null
+++ b/crates/manager/src/settings/persist.rs
@@ -0,0 +1,273 @@
+//! Port of `lib/codex-manager/settings-persist-utils.ts` +
+//! `unified-settings-controller.ts` (+ the persistence halves of
+//! `settings-hub/shared.ts`) — reload-merge of per-panel key sets ONLY,
+//! under the per-path write queue, plus the unified settings controller.
+
+use cma_config::dashboard_settings::{
+    get_dashboard_settings_path, load_dashboard_display_settings, save_dashboard_display_settings,
+    DashboardDisplaySettings,
+};
+use cma_core::schemas::plugin_config::PluginConfig;
+
+use crate::settings::backend::{
+    backend_settings_equal, build_backend_config_patch, clone_backend_plugin_config,
+    configure_backend_settings,
+};
+use crate::settings::dashboard::{
+    configure_dashboard_display_settings, configure_statusline_settings, prompt_behavior_settings,
+    prompt_theme_settings, BEHAVIOR_PANEL_KEYS, THEME_PANEL_KEYS,
+};
+use crate::settings::experimental::prompt_experimental_settings;
+use crate::settings::hub::{
+    apply_ui_theme_from_dashboard_settings, clone_dashboard_settings, dashboard_settings_equal,
+    merge_dashboard_settings_for_keys, prompt_settings_hub, DashboardSettingKey, SettingsHubAction,
+};
+use crate::settings::write_queue::{with_queued_retry, SettingsWriteError};
+
+/// `resolvePluginConfigSavePathKey()` — `CODEX_MULTI_AUTH_CONFIG_PATH` env
+/// (trimmed) when non-empty, else the unified settings path. Used only as
+/// the write-queue key.
+pub fn resolve_plugin_config_save_path_key() -> String {
+    let env_path = std::env::var("CODEX_MULTI_AUTH_CONFIG_PATH")
+        .unwrap_or_default()
+        .trim()
+        .to_string();
+    if !env_path.is_empty() {
+        return env_path;
+    }
+    cma_config::unified_settings::get_unified_settings_path()
+        .to_string_lossy()
+        .to_string()
+}
+
+/// `formatPersistError(error)`.
+pub fn format_persist_error(error: &dyn std::fmt::Display) -> String {
+    error.to_string()
+}
+
+/// `warnPersistFailure(scope, error)` — frozen console.warn text.
+pub fn warn_persist_failure(scope: &str, error: &dyn std::fmt::Display) {
+    eprintln!(
+        "Settings save failed ({scope}) after retries: {}",
+        format_persist_error(error)
+    );
+}
+
+/// `readFileWithRetry(path, {retryableCodes, maxAttempts, sleep})` — utf-8
+/// read; **ENOENT always rethrown immediately**; other listed codes retried
+/// with `25 * 2^attempt` ms; non-retryable rethrown.
+pub async fn read_file_with_retry<Sleep, SleepFut>(
+    path: &std::path::Path,
+    retryable_codes: &[&str],
+    max_attempts: u32,
+    sleep: Sleep,
+) -> std::io::Result<String>
+where
+    Sleep: Fn(i64) -> SleepFut,
+    SleepFut: std::future::Future<Output = ()>,
+{
+    let mut attempt: u32 = 0;
+    loop {
+        match std::fs::read_to_string(path) {
+            Ok(content) => return Ok(content),
+            Err(error) => {
+                let code = cma_core::fs_retry::code_of(&error);
+                if code == Some("ENOENT") {
+                    return Err(error);
+                }
+                let retryable = code.is_some_and(|code| retryable_codes.contains(&code));
+                if !retryable || attempt >= max_attempts.saturating_sub(1) {
+                    return Err(error);
+                }
+                sleep(25_i64.saturating_mul(1 << attempt.min(30))).await;
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// `persistDashboardSettingsSelection(selected, keys, scope)` — reload-latest
+/// + merge ONLY this panel's keys under the per-path queue. A failed save
+///   warns and returns the draft clone so the UI keeps the user's choices.
+pub async fn persist_dashboard_settings_selection(
+    selected: &DashboardDisplaySettings,
+    keys: &[DashboardSettingKey],
+    scope: &str,
+) -> DashboardDisplaySettings {
+    let fallback = clone_dashboard_settings(selected);
+    let path_key = get_dashboard_settings_path().to_string_lossy().to_string();
+    let result: Result<DashboardDisplaySettings, SettingsWriteError> = with_queued_retry(
+        &path_key,
+        || async {
+            let latest = clone_dashboard_settings(&load_dashboard_display_settings().await);
+            let merged = merge_dashboard_settings_for_keys(&latest, selected, keys);
+            save_dashboard_display_settings(&merged)
+                .await
+                .map_err(|error| SettingsWriteError::from_io(&error))?;
+            Ok(merged)
+        },
+        crate::settings::write_queue::default_sleep,
+    )
+    .await;
+    match result {
+        Ok(merged) => merged,
+        Err(error) => {
+            warn_persist_failure(scope, &error);
+            fallback
+        }
+    }
+}
+
+/// `persistBackendConfigSelection(selected, scope)` — writes ONLY the
+/// whitelisted, clamped schema keys via `savePluginConfig`; always returns a
+/// clone of the selection; errors only warn.
+pub async fn persist_backend_config_selection(
+    selected: &PluginConfig,
+    scope: &str,
+) -> PluginConfig {
+    let fallback = clone_backend_plugin_config(selected);
+    let path_key = resolve_plugin_config_save_path_key();
+    let result: Result<(), SettingsWriteError> = with_queued_retry(
+        &path_key,
+        || async {
+            let patch = build_backend_config_patch(selected);
+            cma_config::save::save_plugin_config(&patch)
+                .await
+                .map_err(|error| {
+                    use cma_core::fs_retry::HasErrorCode;
+                    SettingsWriteError {
+                        message: error.to_string(),
+                        code: error.error_code().map(str::to_string),
+                        status: None,
+                        retry_after_ms: None,
+                    }
+                })?;
+            Ok(())
+        },
+        crate::settings::write_queue::default_sleep,
+    )
+    .await;
+    if let Err(error) = result {
+        warn_persist_failure(scope, &error);
+    }
+    fallback
+}
+
+/// `configureUnifiedSettingsController` / `configureUnifiedSettings` — the
+/// settings-hub main loop. Re-entering the hub restores the cursor to the
+/// last chosen action.
+pub async fn configure_unified_settings(
+    initial_settings: Option<&DashboardDisplaySettings>,
+) -> DashboardDisplaySettings {
+    let mut current = clone_dashboard_settings(&match initial_settings {
+        Some(settings) => settings.clone(),
+        None => load_dashboard_display_settings().await,
+    });
+    let mut backend_config = clone_backend_plugin_config(&cma_config::load::load_plugin_config());
+    apply_ui_theme_from_dashboard_settings(&current);
+    let mut hub_focus = SettingsHubAction::AccountList;
+
+    loop {
+        let action = prompt_settings_hub(hub_focus);
+        let Some(action) = action else {
+            return current;
+        };
+        if action == SettingsHubAction::Back {
+            return current;
+        }
+        hub_focus = action;
+
+        match action {
+            SettingsHubAction::AccountList => {
+                current = configure_dashboard_display_settings(Some(&current)).await;
+            }
+            SettingsHubAction::SummaryFields => {
+                current = configure_statusline_settings(Some(&current)).await;
+            }
+            SettingsHubAction::Behavior => {
+                let selected = prompt_behavior_settings(&current);
+                if let Some(selected) = selected
+                    && !dashboard_settings_equal(&current, &selected) {
+                        current = persist_dashboard_settings_selection(
+                            &selected,
+                            &BEHAVIOR_PANEL_KEYS,
+                            "behavior",
+                        )
+                        .await;
+                    }
+            }
+            SettingsHubAction::Theme => {
+                let selected = prompt_theme_settings(&current);
+                if let Some(selected) = selected
+                    && !dashboard_settings_equal(&current, &selected) {
+                        current = persist_dashboard_settings_selection(
+                            &selected,
+                            &THEME_PANEL_KEYS,
+                            "theme",
+                        )
+                        .await;
+                        apply_ui_theme_from_dashboard_settings(&current);
+                    }
+            }
+            SettingsHubAction::Experimental => {
+                let selected = prompt_experimental_settings(&backend_config).await;
+                if let Some(selected) = selected {
+                    if !backend_settings_equal(&backend_config, &selected) {
+                        backend_config =
+                            persist_backend_config_selection(&selected, "experimental").await;
+                    } else {
+                        // Unchanged-but-returned: adopt the draft without
+                        // writing.
+                        backend_config = selected;
+                    }
+                }
+            }
+            SettingsHubAction::Backend => {
+                backend_config = configure_backend_settings(Some(&backend_config)).await;
+            }
+            SettingsHubAction::Back => unreachable!("handled above"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    #[serial(env)]
+    fn plugin_config_save_path_key_prefers_the_env_override() {
+        let mut sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", "  C:/tmp/custom.json  ");
+        assert_eq!(resolve_plugin_config_save_path_key(), "C:/tmp/custom.json");
+        sandbox.set_var("CODEX_MULTI_AUTH_CONFIG_PATH", "   ");
+        let fallback = resolve_plugin_config_save_path_key();
+        assert!(fallback.ends_with("settings.json"), "fallback: {fallback}");
+    }
+
+    #[tokio::test]
+    async fn read_file_with_retry_rethrows_enoent_immediately() {
+        let dir = tempfile::tempdir().unwrap();
+        let missing = dir.path().join("missing.json");
+        let sleeps = std::cell::Cell::new(0_u32);
+        let result = read_file_with_retry(&missing, &["EBUSY", "EPERM", "EAGAIN"], 4, |_ms| {
+            sleeps.set(sleeps.get() + 1);
+            std::future::ready(())
+        })
+        .await;
+        assert!(result.is_err());
+        assert_eq!(sleeps.get(), 0);
+    }
+
+    #[tokio::test]
+    async fn read_file_with_retry_reads_content() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("data.json");
+        std::fs::write(&path, "{\"ok\":true}").unwrap();
+        let content = read_file_with_retry(&path, &["EBUSY"], 4, |_ms| std::future::ready(()))
+            .await
+            .unwrap();
+        assert_eq!(content, "{\"ok\":true}");
+    }
+}
diff --git a/crates/manager/src/settings/preview.rs b/crates/manager/src/settings/preview.rs
new file mode 100644
index 000000000..d4f7ce8a1
--- /dev/null
+++ b/crates/manager/src/settings/preview.rs
@@ -0,0 +1,439 @@
+//! Port of `lib/codex-manager/settings-preview.ts` — pure preview builders for
+//! the settings panels. Preview literals are copy-exact (spec 09 §5.9).
+
+use cma_config::dashboard_settings::{DashboardDisplaySettings, DashboardStatuslineField};
+use cma_tui::runtime_options::UiRuntimeOptions;
+
+/// `DEFAULT_STATUSLINE_FIELDS`.
+pub const DEFAULT_STATUSLINE_FIELDS: [DashboardStatuslineField; 3] = [
+    DashboardStatuslineField::LastUsed,
+    DashboardStatuslineField::Limits,
+    DashboardStatuslineField::Status,
+];
+
+const PREVIEW_ACCOUNT_EMAIL: &str = "demo@example.com";
+const PREVIEW_LAST_USED: &str = "today";
+const PREVIEW_STATUS: &str = "active";
+const PREVIEW_LIMITS: &str = "5h \u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2592}\u{2592}\u{2592}\u{2592} 62% | 7d \u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2592}\u{2592}\u{2592}\u{2592}\u{2592} 49%";
+const PREVIEW_LIMIT_COOLDOWNS: &str = "5h reset 1h 20m | 7d reset 2d 04h";
+
+/// `PreviewFocusKey` — statusline field, the panel toggle keys, the two cycle
+/// items. The TS `null` becomes `Option::<PreviewFocusKey>::None` at the call
+/// sites.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PreviewFocusKey {
+    // DashboardStatuslineField members
+    LastUsed,
+    Limits,
+    Status,
+    // menu* toggle keys
+    MenuShowStatusBadge,
+    MenuShowCurrentBadge,
+    MenuShowLastUsed,
+    MenuShowQuotaSummary,
+    MenuShowQuotaCooldown,
+    MenuShowFetchStatus,
+    MenuShowDetailsForUnselectedRows,
+    MenuHighlightCurrentRow,
+    MenuSortEnabled,
+    MenuSortPinCurrent,
+    MenuSortQuickSwitchVisibleRow,
+    // cycle items
+    MenuSortMode,
+    MenuLayoutMode,
+}
+
+impl PreviewFocusKey {
+    pub fn from_statusline_field(field: DashboardStatuslineField) -> Self {
+        match field {
+            DashboardStatuslineField::LastUsed => Self::LastUsed,
+            DashboardStatuslineField::Limits => Self::Limits,
+            DashboardStatuslineField::Status => Self::Status,
+        }
+    }
+}
+
+/// Testable core of [`highlight_preview_token`] with the TTY probe injected.
+pub(crate) fn highlight_preview_token_with_tty(
+    text: &str,
+    ui: &UiRuntimeOptions,
+    stdout_is_tty: bool,
+) -> String {
+    if !stdout_is_tty {
+        return text.to_string();
+    }
+    if ui.v2_enabled {
+        return format!(
+            "{}{}{}{}",
+            ui.theme.colors.accent,
+            cma_tui::ansi::BOLD,
+            text,
+            ui.theme.colors.reset
+        );
+    }
+    format!(
+        "{}{}{}{}",
+        cma_tui::ansi::CYAN,
+        cma_tui::ansi::BOLD,
+        text,
+        cma_tui::ansi::RESET
+    )
+}
+
+/// `highlightPreviewToken` — plain text on a non-TTY stdout; v2 theme accent
+/// or legacy cyan+bold otherwise.
+pub fn highlight_preview_token(text: &str, ui: &UiRuntimeOptions) -> String {
+    highlight_preview_token_with_tty(text, ui, cma_tui::ansi::is_tty())
+}
+
+fn is_last_used_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(
+        focus,
+        Some(PreviewFocusKey::MenuShowLastUsed) | Some(PreviewFocusKey::LastUsed)
+    )
+}
+
+fn is_limits_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(
+        focus,
+        Some(PreviewFocusKey::MenuShowQuotaSummary) | Some(PreviewFocusKey::Limits)
+    )
+}
+
+fn is_limits_cooldown_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(focus, Some(PreviewFocusKey::MenuShowQuotaCooldown))
+}
+
+fn is_status_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(
+        focus,
+        Some(PreviewFocusKey::MenuShowStatusBadge) | Some(PreviewFocusKey::Status)
+    )
+}
+
+fn is_current_badge_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(focus, Some(PreviewFocusKey::MenuShowCurrentBadge))
+}
+
+fn is_current_row_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(focus, Some(PreviewFocusKey::MenuHighlightCurrentRow))
+}
+
+fn is_expanded_rows_focus(focus: Option<PreviewFocusKey>) -> bool {
+    matches!(
+        focus,
+        Some(PreviewFocusKey::MenuShowDetailsForUnselectedRows)
+            | Some(PreviewFocusKey::MenuLayoutMode)
+    )
+}
+
+/// `normalizeStatuslineFields` — default when `None`; dedupe keeping the
+/// first occurrence; empty result → fresh copy of defaults.
+pub fn normalize_statusline_fields(
+    fields: Option<&[DashboardStatuslineField]>,
+) -> Vec<DashboardStatuslineField> {
+    let source: &[DashboardStatuslineField] = fields.unwrap_or(&DEFAULT_STATUSLINE_FIELDS);
+    let mut normalized: Vec<DashboardStatuslineField> = Vec::new();
+    for field in source {
+        if !normalized.contains(field) {
+            normalized.push(*field);
+        }
+    }
+    if normalized.is_empty() {
+        return DEFAULT_STATUSLINE_FIELDS.to_vec();
+    }
+    normalized
+}
+
+fn build_summary_preview_text_with_tty(
+    settings: &DashboardDisplaySettings,
+    ui: &UiRuntimeOptions,
+    focus: Option<PreviewFocusKey>,
+    stdout_is_tty: bool,
+) -> String {
+    let highlight =
+        |text: &str| -> String { highlight_preview_token_with_tty(text, ui, stdout_is_tty) };
+
+    let mut parts_by_field: Vec<(DashboardStatuslineField, String)> = Vec::new();
+    // Normalized settings are always fully populated, so `!== false` becomes
+    // the plain boolean.
+    if settings.menu_show_last_used {
+        let part = format!("last used: {PREVIEW_LAST_USED}");
+        let part = if is_last_used_focus(focus) {
+            highlight(&part)
+        } else {
+            part
+        };
+        parts_by_field.push((DashboardStatuslineField::LastUsed, part));
+    }
+    if settings.menu_show_quota_summary {
+        let limits_text = if !settings.menu_show_quota_cooldown {
+            PREVIEW_LIMITS.to_string()
+        } else {
+            format!("{PREVIEW_LIMITS} | {PREVIEW_LIMIT_COOLDOWNS}")
+        };
+        let part = format!("limits: {limits_text}");
+        let part = if is_limits_focus(focus) || is_limits_cooldown_focus(focus) {
+            highlight(&part)
+        } else {
+            part
+        };
+        parts_by_field.push((DashboardStatuslineField::Limits, part));
+    }
+    if !settings.menu_show_status_badge {
+        let part = format!("status: {PREVIEW_STATUS}");
+        let part = if is_status_focus(focus) {
+            highlight(&part)
+        } else {
+            part
+        };
+        parts_by_field.push((DashboardStatuslineField::Status, part));
+    }
+
+    let normalized = normalize_statusline_fields(Some(&settings.menu_statusline_fields));
+    let ordered_parts: Vec<String> = normalized
+        .iter()
+        .filter_map(|field| {
+            parts_by_field
+                .iter()
+                .find(|(part_field, _)| part_field == field)
+                .map(|(_, part)| part.clone())
+        })
+        .filter(|part| !part.is_empty())
+        .collect();
+    if !ordered_parts.is_empty() {
+        return ordered_parts.join(" | ");
+    }
+
+    let shows_status_field = normalized.contains(&DashboardStatuslineField::Status);
+    if shows_status_field && settings.menu_show_status_badge {
+        let note = "status text appears only when status badges are hidden";
+        return if is_status_focus(focus) {
+            highlight(note)
+        } else {
+            note.to_string()
+        };
+    }
+    "no summary text is visible with current account-list settings".to_string()
+}
+
+/// `buildSummaryPreviewText`. (The TS `resolveMenuLayoutMode` parameter is
+/// unused by the summary builder and is dropped here.)
+pub fn build_summary_preview_text(
+    settings: &DashboardDisplaySettings,
+    ui: &UiRuntimeOptions,
+    focus: Option<PreviewFocusKey>,
+) -> String {
+    build_summary_preview_text_with_tty(settings, ui, focus, cma_tui::ansi::is_tty())
+}
+
+/// Result of [`build_account_list_preview`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AccountListPreview {
+    pub label: String,
+    pub hint: String,
+}
+
+fn build_account_list_preview_with_tty(
+    settings: &DashboardDisplaySettings,
+    ui: &UiRuntimeOptions,
+    resolve_menu_layout_mode: &dyn Fn(
+        &DashboardDisplaySettings,
+    ) -> cma_config::dashboard_settings::DashboardLayoutMode,
+    focus: Option<PreviewFocusKey>,
+    stdout_is_tty: bool,
+) -> AccountListPreview {
+    use cma_config::dashboard_settings::DashboardLayoutMode;
+    let highlight =
+        |text: &str| -> String { highlight_preview_token_with_tty(text, ui, stdout_is_tty) };
+
+    let mut badges: Vec<String> = Vec::new();
+    if settings.menu_show_current_badge {
+        let current_badge = "[current]";
+        badges.push(if is_current_badge_focus(focus) {
+            highlight(current_badge)
+        } else {
+            current_badge.to_string()
+        });
+    }
+    if settings.menu_show_status_badge {
+        let status_badge = "[active]";
+        badges.push(if is_status_focus(focus) {
+            highlight(status_badge)
+        } else {
+            status_badge.to_string()
+        });
+    }
+    let badge_suffix = if badges.is_empty() {
+        String::new()
+    } else {
+        format!(" {}", badges.join(" "))
+    };
+    let account_email = if is_current_row_focus(focus) {
+        highlight(PREVIEW_ACCOUNT_EMAIL)
+    } else {
+        PREVIEW_ACCOUNT_EMAIL.to_string()
+    };
+    let row_detail_mode = match resolve_menu_layout_mode(settings) {
+        DashboardLayoutMode::ExpandedRows => "details shown on all rows",
+        DashboardLayoutMode::CompactDetails => "details shown on selected row only",
+    };
+    let detail_mode_text = if is_expanded_rows_focus(focus) {
+        highlight(row_detail_mode)
+    } else {
+        row_detail_mode.to_string()
+    };
+    AccountListPreview {
+        label: format!("1. {account_email}{badge_suffix}"),
+        hint: format!(
+            "{}\n{}",
+            build_summary_preview_text_with_tty(settings, ui, focus, stdout_is_tty),
+            detail_mode_text
+        ),
+    }
+}
+
+/// `buildAccountListPreview`.
+pub fn build_account_list_preview(
+    settings: &DashboardDisplaySettings,
+    ui: &UiRuntimeOptions,
+    resolve_menu_layout_mode: &dyn Fn(
+        &DashboardDisplaySettings,
+    ) -> cma_config::dashboard_settings::DashboardLayoutMode,
+    focus: Option<PreviewFocusKey>,
+) -> AccountListPreview {
+    build_account_list_preview_with_tty(
+        settings,
+        ui,
+        resolve_menu_layout_mode,
+        focus,
+        cma_tui::ansi::is_tty(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_config::dashboard_settings::DashboardLayoutMode;
+    use cma_tui::runtime_options::get_ui_runtime_options;
+
+    fn defaults() -> DashboardDisplaySettings {
+        DashboardDisplaySettings::default()
+    }
+
+    fn resolver(settings: &DashboardDisplaySettings) -> DashboardLayoutMode {
+        crate::settings::hub::resolve_menu_layout_mode(settings)
+    }
+
+    #[test]
+    fn normalize_statusline_fields_defaults_dedupes_and_backfills() {
+        assert_eq!(
+            normalize_statusline_fields(None),
+            DEFAULT_STATUSLINE_FIELDS.to_vec()
+        );
+        assert_eq!(
+            normalize_statusline_fields(Some(&[
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Status,
+            ])),
+            vec![
+                DashboardStatuslineField::Limits,
+                DashboardStatuslineField::Status
+            ]
+        );
+        assert_eq!(
+            normalize_statusline_fields(Some(&[])),
+            DEFAULT_STATUSLINE_FIELDS.to_vec()
+        );
+    }
+
+    #[test]
+    fn summary_preview_orders_parts_and_hides_status_behind_badges() {
+        let ui = get_ui_runtime_options();
+        let settings = defaults();
+        // Defaults: last-used + limits (with cooldowns); status hidden because
+        // badges are shown.
+        let text = build_summary_preview_text_with_tty(&settings, &ui, None, false);
+        assert_eq!(
+            text,
+            format!(
+                "last used: {PREVIEW_LAST_USED} | limits: {PREVIEW_LIMITS} | {PREVIEW_LIMIT_COOLDOWNS}"
+            )
+        );
+    }
+
+    #[test]
+    fn summary_preview_shows_status_text_only_when_badges_hidden() {
+        let ui = get_ui_runtime_options();
+        let mut settings = defaults();
+        settings.menu_show_status_badge = false;
+        settings.menu_show_last_used = false;
+        settings.menu_show_quota_summary = false;
+        let text = build_summary_preview_text_with_tty(&settings, &ui, None, false);
+        assert_eq!(text, "status: active");
+    }
+
+    #[test]
+    fn summary_preview_cooldowns_can_be_suppressed() {
+        let ui = get_ui_runtime_options();
+        let mut settings = defaults();
+        settings.menu_show_quota_cooldown = false;
+        settings.menu_show_last_used = false;
+        let text = build_summary_preview_text_with_tty(&settings, &ui, None, false);
+        assert_eq!(text, format!("limits: {PREVIEW_LIMITS}"));
+    }
+
+    #[test]
+    fn summary_preview_empty_note_when_status_configured_but_badged() {
+        let ui = get_ui_runtime_options();
+        let mut settings = defaults();
+        settings.menu_show_last_used = false;
+        settings.menu_show_quota_summary = false;
+        // status stays in the field list but badges are shown.
+        let text = build_summary_preview_text_with_tty(&settings, &ui, None, false);
+        assert_eq!(
+            text,
+            "status text appears only when status badges are hidden"
+        );
+        // Without the status field at all:
+        settings.menu_statusline_fields = vec![DashboardStatuslineField::LastUsed];
+        let text = build_summary_preview_text_with_tty(&settings, &ui, None, false);
+        assert_eq!(
+            text,
+            "no summary text is visible with current account-list settings"
+        );
+    }
+
+    #[test]
+    fn account_list_preview_badges_and_layout_note() {
+        let ui = get_ui_runtime_options();
+        let settings = defaults();
+        let preview =
+            build_account_list_preview_with_tty(&settings, &ui, &resolver, None, false);
+        assert_eq!(preview.label, "1. demo@example.com [current] [active]");
+        assert!(preview.hint.ends_with("details shown on selected row only"));
+
+        let mut expanded = defaults();
+        expanded.menu_layout_mode = DashboardLayoutMode::ExpandedRows;
+        let preview =
+            build_account_list_preview_with_tty(&expanded, &ui, &resolver, None, false);
+        assert!(preview.hint.ends_with("details shown on all rows"));
+
+        let mut no_badges = defaults();
+        no_badges.menu_show_current_badge = false;
+        no_badges.menu_show_status_badge = false;
+        let preview =
+            build_account_list_preview_with_tty(&no_badges, &ui, &resolver, None, false);
+        assert_eq!(preview.label, "1. demo@example.com");
+    }
+
+    #[test]
+    fn highlight_is_plain_without_tty() {
+        let ui = get_ui_runtime_options();
+        assert_eq!(highlight_preview_token_with_tty("x", &ui, false), "x");
+        let highlighted = highlight_preview_token_with_tty("x", &ui, true);
+        assert!(highlighted.contains('x'));
+        assert!(highlighted.contains("\u{1b}["));
+    }
+}
diff --git a/crates/manager/src/settings/schema.rs b/crates/manager/src/settings/schema.rs
new file mode 100644
index 000000000..55e944034
--- /dev/null
+++ b/crates/manager/src/settings/schema.rs
@@ -0,0 +1,713 @@
+//! Port of `lib/codex-manager/backend-settings-schema.ts` +
+//! `experimental-settings-schema.ts` — the hand-rolled schema for the 11
+//! backend toggles, 16 bounded numerics, and the 4 category groupings, plus
+//! the experimental panel's action union and hotkey mappers.
+//!
+//! Labels, descriptions, bounds, steps, and units are copy-exact from the TS
+//! source (spec 09 §5.13/§5.14). `BACKEND_DEFAULTS` is
+//! `getDefaultPluginConfig()` evaluated on demand (TS evaluates once at module
+//! load; the Rust accessor is pure so the distinction is unobservable).
+
+use cma_core::schemas::plugin_config::PluginConfig;
+
+// ---------------------------------------------------------------------------
+// Keys
+// ---------------------------------------------------------------------------
+
+/// `BackendToggleSettingKey` (11 keys).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum BackendToggleSettingKey {
+    LiveAccountSync,
+    SessionAffinity,
+    ProactiveRefreshGuardian,
+    RetryAllAccountsRateLimited,
+    ParallelProbing,
+    StorageBackupEnabled,
+    PreemptiveQuotaEnabled,
+    FastSession,
+    SessionRecovery,
+    AutoResume,
+    PerProjectAccounts,
+}
+
+impl BackendToggleSettingKey {
+    /// The camelCase TS key string.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::LiveAccountSync => "liveAccountSync",
+            Self::SessionAffinity => "sessionAffinity",
+            Self::ProactiveRefreshGuardian => "proactiveRefreshGuardian",
+            Self::RetryAllAccountsRateLimited => "retryAllAccountsRateLimited",
+            Self::ParallelProbing => "parallelProbing",
+            Self::StorageBackupEnabled => "storageBackupEnabled",
+            Self::PreemptiveQuotaEnabled => "preemptiveQuotaEnabled",
+            Self::FastSession => "fastSession",
+            Self::SessionRecovery => "sessionRecovery",
+            Self::AutoResume => "autoResume",
+            Self::PerProjectAccounts => "perProjectAccounts",
+        }
+    }
+
+    /// Read this toggle from a `PluginConfig`.
+    pub fn get(self, config: &PluginConfig) -> Option<bool> {
+        match self {
+            Self::LiveAccountSync => config.live_account_sync,
+            Self::SessionAffinity => config.session_affinity,
+            Self::ProactiveRefreshGuardian => config.proactive_refresh_guardian,
+            Self::RetryAllAccountsRateLimited => config.retry_all_accounts_rate_limited,
+            Self::ParallelProbing => config.parallel_probing,
+            Self::StorageBackupEnabled => config.storage_backup_enabled,
+            Self::PreemptiveQuotaEnabled => config.preemptive_quota_enabled,
+            Self::FastSession => config.fast_session,
+            Self::SessionRecovery => config.session_recovery,
+            Self::AutoResume => config.auto_resume,
+            Self::PerProjectAccounts => config.per_project_accounts,
+        }
+    }
+
+    /// Write this toggle into a `PluginConfig`.
+    pub fn set(self, config: &mut PluginConfig, value: Option<bool>) {
+        match self {
+            Self::LiveAccountSync => config.live_account_sync = value,
+            Self::SessionAffinity => config.session_affinity = value,
+            Self::ProactiveRefreshGuardian => config.proactive_refresh_guardian = value,
+            Self::RetryAllAccountsRateLimited => config.retry_all_accounts_rate_limited = value,
+            Self::ParallelProbing => config.parallel_probing = value,
+            Self::StorageBackupEnabled => config.storage_backup_enabled = value,
+            Self::PreemptiveQuotaEnabled => config.preemptive_quota_enabled = value,
+            Self::FastSession => config.fast_session = value,
+            Self::SessionRecovery => config.session_recovery = value,
+            Self::AutoResume => config.auto_resume = value,
+            Self::PerProjectAccounts => config.per_project_accounts = value,
+        }
+    }
+}
+
+/// `BackendNumberSettingKey` (16 keys).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum BackendNumberSettingKey {
+    LiveAccountSyncDebounceMs,
+    LiveAccountSyncPollMs,
+    SessionAffinityTtlMs,
+    SessionAffinityMaxEntries,
+    ProactiveRefreshIntervalMs,
+    ProactiveRefreshBufferMs,
+    ParallelProbingMaxConcurrency,
+    FastSessionMaxInputItems,
+    NetworkErrorCooldownMs,
+    ServerErrorCooldownMs,
+    FetchTimeoutMs,
+    StreamStallTimeoutMs,
+    TokenRefreshSkewMs,
+    PreemptiveQuotaRemainingPercent5h,
+    PreemptiveQuotaRemainingPercent7d,
+    PreemptiveQuotaMaxDeferralMs,
+}
+
+impl BackendNumberSettingKey {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::LiveAccountSyncDebounceMs => "liveAccountSyncDebounceMs",
+            Self::LiveAccountSyncPollMs => "liveAccountSyncPollMs",
+            Self::SessionAffinityTtlMs => "sessionAffinityTtlMs",
+            Self::SessionAffinityMaxEntries => "sessionAffinityMaxEntries",
+            Self::ProactiveRefreshIntervalMs => "proactiveRefreshIntervalMs",
+            Self::ProactiveRefreshBufferMs => "proactiveRefreshBufferMs",
+            Self::ParallelProbingMaxConcurrency => "parallelProbingMaxConcurrency",
+            Self::FastSessionMaxInputItems => "fastSessionMaxInputItems",
+            Self::NetworkErrorCooldownMs => "networkErrorCooldownMs",
+            Self::ServerErrorCooldownMs => "serverErrorCooldownMs",
+            Self::FetchTimeoutMs => "fetchTimeoutMs",
+            Self::StreamStallTimeoutMs => "streamStallTimeoutMs",
+            Self::TokenRefreshSkewMs => "tokenRefreshSkewMs",
+            Self::PreemptiveQuotaRemainingPercent5h => "preemptiveQuotaRemainingPercent5h",
+            Self::PreemptiveQuotaRemainingPercent7d => "preemptiveQuotaRemainingPercent7d",
+            Self::PreemptiveQuotaMaxDeferralMs => "preemptiveQuotaMaxDeferralMs",
+        }
+    }
+
+    pub fn get(self, config: &PluginConfig) -> Option<f64> {
+        match self {
+            Self::LiveAccountSyncDebounceMs => config.live_account_sync_debounce_ms,
+            Self::LiveAccountSyncPollMs => config.live_account_sync_poll_ms,
+            Self::SessionAffinityTtlMs => config.session_affinity_ttl_ms,
+            Self::SessionAffinityMaxEntries => config.session_affinity_max_entries,
+            Self::ProactiveRefreshIntervalMs => config.proactive_refresh_interval_ms,
+            Self::ProactiveRefreshBufferMs => config.proactive_refresh_buffer_ms,
+            Self::ParallelProbingMaxConcurrency => config.parallel_probing_max_concurrency,
+            Self::FastSessionMaxInputItems => config.fast_session_max_input_items,
+            Self::NetworkErrorCooldownMs => config.network_error_cooldown_ms,
+            Self::ServerErrorCooldownMs => config.server_error_cooldown_ms,
+            Self::FetchTimeoutMs => config.fetch_timeout_ms,
+            Self::StreamStallTimeoutMs => config.stream_stall_timeout_ms,
+            Self::TokenRefreshSkewMs => config.token_refresh_skew_ms,
+            Self::PreemptiveQuotaRemainingPercent5h => config.preemptive_quota_remaining_percent_5h,
+            Self::PreemptiveQuotaRemainingPercent7d => config.preemptive_quota_remaining_percent_7d,
+            Self::PreemptiveQuotaMaxDeferralMs => config.preemptive_quota_max_deferral_ms,
+        }
+    }
+
+    pub fn set(self, config: &mut PluginConfig, value: Option<f64>) {
+        match self {
+            Self::LiveAccountSyncDebounceMs => config.live_account_sync_debounce_ms = value,
+            Self::LiveAccountSyncPollMs => config.live_account_sync_poll_ms = value,
+            Self::SessionAffinityTtlMs => config.session_affinity_ttl_ms = value,
+            Self::SessionAffinityMaxEntries => config.session_affinity_max_entries = value,
+            Self::ProactiveRefreshIntervalMs => config.proactive_refresh_interval_ms = value,
+            Self::ProactiveRefreshBufferMs => config.proactive_refresh_buffer_ms = value,
+            Self::ParallelProbingMaxConcurrency => config.parallel_probing_max_concurrency = value,
+            Self::FastSessionMaxInputItems => config.fast_session_max_input_items = value,
+            Self::NetworkErrorCooldownMs => config.network_error_cooldown_ms = value,
+            Self::ServerErrorCooldownMs => config.server_error_cooldown_ms = value,
+            Self::FetchTimeoutMs => config.fetch_timeout_ms = value,
+            Self::StreamStallTimeoutMs => config.stream_stall_timeout_ms = value,
+            Self::TokenRefreshSkewMs => config.token_refresh_skew_ms = value,
+            Self::PreemptiveQuotaRemainingPercent5h => {
+                config.preemptive_quota_remaining_percent_5h = value
+            }
+            Self::PreemptiveQuotaRemainingPercent7d => {
+                config.preemptive_quota_remaining_percent_7d = value
+            }
+            Self::PreemptiveQuotaMaxDeferralMs => config.preemptive_quota_max_deferral_ms = value,
+        }
+    }
+}
+
+/// `BackendSettingFocusKey = BackendToggleSettingKey | BackendNumberSettingKey | null`
+/// (`None` = the TS `null`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackendSettingFocusKey {
+    Toggle(BackendToggleSettingKey),
+    Number(BackendNumberSettingKey),
+}
+
+// ---------------------------------------------------------------------------
+// Option tables
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct BackendToggleSettingOption {
+    pub key: BackendToggleSettingKey,
+    pub label: &'static str,
+    pub description: &'static str,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct BackendNumberSettingOption {
+    pub key: BackendNumberSettingKey,
+    pub label: &'static str,
+    pub description: &'static str,
+    pub min: f64,
+    pub max: f64,
+    pub step: f64,
+    pub unit: BackendNumberUnit,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackendNumberUnit {
+    Ms,
+    Percent,
+    Count,
+}
+
+/// `BACKEND_TOGGLE_OPTIONS` — order matters for numeric hotkeys.
+pub const BACKEND_TOGGLE_OPTIONS: [BackendToggleSettingOption; 11] = [
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::LiveAccountSync,
+        label: "Enable Live Sync",
+        description: "Keep accounts synced when files change in another window.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::SessionAffinity,
+        label: "Enable Session Affinity",
+        description: "Try to keep each conversation on the same account.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::ProactiveRefreshGuardian,
+        label: "Enable Token Refresh Guard",
+        description: "Refresh tokens early in the background.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::RetryAllAccountsRateLimited,
+        label: "Retry When All Rate-Limited",
+        description: "If all accounts are limited, wait and try again.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::ParallelProbing,
+        label: "Enable Parallel Probing",
+        description: "Check multiple accounts at the same time.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::StorageBackupEnabled,
+        label: "Enable Storage Backups",
+        description: "Create a backup before account data changes.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::PreemptiveQuotaEnabled,
+        label: "Enable Quota Deferral",
+        description: "Delay requests before limits are fully exhausted.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::FastSession,
+        label: "Enable Fast Session Mode",
+        description: "Use lighter request handling for faster responses.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::SessionRecovery,
+        label: "Enable Session Recovery",
+        description: "Restore recoverable sessions after restart.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::AutoResume,
+        label: "Enable Auto Resume",
+        description: "Resume the most recent recoverable session automatically.",
+    },
+    BackendToggleSettingOption {
+        key: BackendToggleSettingKey::PerProjectAccounts,
+        label: "Enable Per-Project Accounts",
+        description: "Use repo-specific account storage instead of a global pool.",
+    },
+];
+
+/// `BACKEND_NUMBER_OPTIONS` — bounds table from spec 09 §5.13.
+pub const BACKEND_NUMBER_OPTIONS: [BackendNumberSettingOption; 16] = [
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::LiveAccountSyncDebounceMs,
+        label: "Live Sync Debounce",
+        description: "Delay before reacting to file changes.",
+        min: 50.0,
+        max: 10_000.0,
+        step: 50.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::LiveAccountSyncPollMs,
+        label: "Live Sync Poll Interval",
+        description: "Polling fallback interval for external file changes.",
+        min: 500.0,
+        max: 60_000.0,
+        step: 500.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::SessionAffinityTtlMs,
+        label: "Session Affinity TTL",
+        description: "How long affinity survives without activity.",
+        min: 1_000.0,
+        max: 86_400_000.0,
+        step: 60_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::SessionAffinityMaxEntries,
+        label: "Session Affinity Max Entries",
+        description: "Upper bound for tracked affinity sessions.",
+        min: 8.0,
+        max: 4_096.0,
+        step: 32.0,
+        unit: BackendNumberUnit::Count,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::ProactiveRefreshIntervalMs,
+        label: "Refresh Guard Interval",
+        description: "How often the guard scans for refresh work.",
+        min: 5_000.0,
+        max: 600_000.0,
+        step: 5_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::ProactiveRefreshBufferMs,
+        label: "Refresh Guard Buffer",
+        description: "How early tokens should refresh before expiry.",
+        min: 30_000.0,
+        max: 600_000.0,
+        step: 30_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::ParallelProbingMaxConcurrency,
+        label: "Parallel Probe Concurrency",
+        description: "Maximum simultaneous account probes.",
+        min: 1.0,
+        max: 5.0,
+        step: 1.0,
+        unit: BackendNumberUnit::Count,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::FastSessionMaxInputItems,
+        label: "Fast Session Max Inputs",
+        description: "Maximum prompt items kept in fast-session mode.",
+        min: 8.0,
+        max: 200.0,
+        step: 2.0,
+        unit: BackendNumberUnit::Count,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::NetworkErrorCooldownMs,
+        label: "Network Error Cooldown",
+        description: "Cooldown applied after network failures.",
+        min: 0.0,
+        max: 120_000.0,
+        step: 500.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::ServerErrorCooldownMs,
+        label: "Server Error Cooldown",
+        description: "Cooldown applied after upstream server failures.",
+        min: 0.0,
+        max: 120_000.0,
+        step: 500.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::FetchTimeoutMs,
+        label: "Request Timeout",
+        description: "Max time to wait for a request.",
+        min: 1_000.0,
+        // TS: (10 * 60 * 60_000) / 60 = 600_000.
+        max: (10.0 * 60.0 * 60_000.0) / 60.0,
+        step: 5_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::StreamStallTimeoutMs,
+        label: "Stream Stall Timeout",
+        description: "Max wait before a stuck stream is retried.",
+        min: 1_000.0,
+        max: (10.0 * 60.0 * 60_000.0) / 60.0,
+        step: 5_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::TokenRefreshSkewMs,
+        label: "Token Refresh Buffer",
+        description: "Refresh this long before token expiry.",
+        min: 0.0,
+        max: (10.0 * 60.0 * 60_000.0) / 60.0,
+        step: 10_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::PreemptiveQuotaRemainingPercent5h,
+        label: "5h Remaining Threshold",
+        description: "Start delaying when 5h remaining reaches this percent.",
+        min: 0.0,
+        max: 100.0,
+        step: 1.0,
+        unit: BackendNumberUnit::Percent,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::PreemptiveQuotaRemainingPercent7d,
+        label: "7d Remaining Threshold",
+        description: "Start delaying when weekly remaining reaches this percent.",
+        min: 0.0,
+        max: 100.0,
+        step: 1.0,
+        unit: BackendNumberUnit::Percent,
+    },
+    BackendNumberSettingOption {
+        key: BackendNumberSettingKey::PreemptiveQuotaMaxDeferralMs,
+        label: "Max Preemptive Deferral",
+        description: "Maximum time allowed for quota-based delay.",
+        min: 1_000.0,
+        max: 24.0 * 60.0 * 60_000.0,
+        step: 60_000.0,
+        unit: BackendNumberUnit::Ms,
+    },
+];
+
+// ---------------------------------------------------------------------------
+// Categories
+// ---------------------------------------------------------------------------
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum BackendCategoryKey {
+    SessionSync,
+    RotationQuota,
+    RefreshRecovery,
+    PerformanceTimeouts,
+}
+
+impl BackendCategoryKey {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SessionSync => "session-sync",
+            Self::RotationQuota => "rotation-quota",
+            Self::RefreshRecovery => "refresh-recovery",
+            Self::PerformanceTimeouts => "performance-timeouts",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct BackendCategoryOption {
+    pub key: BackendCategoryKey,
+    pub label: &'static str,
+    pub description: &'static str,
+    pub toggle_keys: &'static [BackendToggleSettingKey],
+    pub number_keys: &'static [BackendNumberSettingKey],
+}
+
+/// `BACKEND_CATEGORY_OPTIONS` (4 categories, member order preserved).
+pub const BACKEND_CATEGORY_OPTIONS: [BackendCategoryOption; 4] = [
+    BackendCategoryOption {
+        key: BackendCategoryKey::SessionSync,
+        label: "Session & Sync",
+        description: "Sync and session behavior.",
+        toggle_keys: &[
+            BackendToggleSettingKey::LiveAccountSync,
+            BackendToggleSettingKey::SessionAffinity,
+            BackendToggleSettingKey::PerProjectAccounts,
+            BackendToggleSettingKey::SessionRecovery,
+            BackendToggleSettingKey::AutoResume,
+        ],
+        number_keys: &[
+            BackendNumberSettingKey::LiveAccountSyncDebounceMs,
+            BackendNumberSettingKey::LiveAccountSyncPollMs,
+            BackendNumberSettingKey::SessionAffinityTtlMs,
+            BackendNumberSettingKey::SessionAffinityMaxEntries,
+        ],
+    },
+    BackendCategoryOption {
+        key: BackendCategoryKey::RotationQuota,
+        label: "Rotation & Quota",
+        description: "Quota and retry behavior.",
+        toggle_keys: &[
+            BackendToggleSettingKey::PreemptiveQuotaEnabled,
+            BackendToggleSettingKey::RetryAllAccountsRateLimited,
+        ],
+        number_keys: &[
+            BackendNumberSettingKey::PreemptiveQuotaRemainingPercent5h,
+            BackendNumberSettingKey::PreemptiveQuotaRemainingPercent7d,
+            BackendNumberSettingKey::PreemptiveQuotaMaxDeferralMs,
+        ],
+    },
+    BackendCategoryOption {
+        key: BackendCategoryKey::RefreshRecovery,
+        label: "Refresh & Recovery",
+        description: "Token refresh and recovery safety.",
+        toggle_keys: &[
+            BackendToggleSettingKey::ProactiveRefreshGuardian,
+            BackendToggleSettingKey::StorageBackupEnabled,
+        ],
+        number_keys: &[
+            BackendNumberSettingKey::ProactiveRefreshIntervalMs,
+            BackendNumberSettingKey::ProactiveRefreshBufferMs,
+            BackendNumberSettingKey::TokenRefreshSkewMs,
+        ],
+    },
+    BackendCategoryOption {
+        key: BackendCategoryKey::PerformanceTimeouts,
+        label: "Performance & Timeouts",
+        description: "Speed, probing, and timeout controls.",
+        toggle_keys: &[
+            BackendToggleSettingKey::FastSession,
+            BackendToggleSettingKey::ParallelProbing,
+        ],
+        number_keys: &[
+            BackendNumberSettingKey::FastSessionMaxInputItems,
+            BackendNumberSettingKey::ParallelProbingMaxConcurrency,
+            BackendNumberSettingKey::FetchTimeoutMs,
+            BackendNumberSettingKey::StreamStallTimeoutMs,
+            BackendNumberSettingKey::NetworkErrorCooldownMs,
+            BackendNumberSettingKey::ServerErrorCooldownMs,
+        ],
+    },
+];
+
+/// `BACKEND_DEFAULTS` — `getDefaultPluginConfig()`.
+pub fn backend_defaults() -> PluginConfig {
+    cma_config::load::get_default_plugin_config()
+}
+
+/// `BACKEND_TOGGLE_OPTION_BY_KEY` lookup.
+pub fn backend_toggle_option_by_key(
+    key: BackendToggleSettingKey,
+) -> &'static BackendToggleSettingOption {
+    BACKEND_TOGGLE_OPTIONS
+        .iter()
+        .find(|option| option.key == key)
+        .expect("every toggle key has an option row")
+}
+
+/// `BACKEND_NUMBER_OPTION_BY_KEY` lookup.
+pub fn backend_number_option_by_key(
+    key: BackendNumberSettingKey,
+) -> &'static BackendNumberSettingOption {
+    BACKEND_NUMBER_OPTIONS
+        .iter()
+        .find(|option| option.key == key)
+        .expect("every number key has an option row")
+}
+
+// ---------------------------------------------------------------------------
+// Action unions
+// ---------------------------------------------------------------------------
+
+/// `BackendCategoryConfigAction`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackendCategoryConfigAction {
+    Toggle(BackendToggleSettingKey),
+    Bump {
+        key: BackendNumberSettingKey,
+        direction: i32,
+    },
+    ResetCategory,
+    Back,
+}
+
+/// `BackendSettingsHubAction`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackendSettingsHubAction {
+    OpenCategory(BackendCategoryKey),
+    Reset,
+    Save,
+    Cancel,
+}
+
+// ---------------------------------------------------------------------------
+// Experimental settings schema (`experimental-settings-schema.ts`)
+// ---------------------------------------------------------------------------
+
+/// `ExperimentalSettingsAction`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ExperimentalSettingsAction {
+    Sync,
+    Backup,
+    ToggleRefreshGuardian,
+    DecreaseRefreshInterval,
+    IncreaseRefreshInterval,
+    Apply,
+    Save,
+    Back,
+}
+
+/// `mapExperimentalMenuHotkey`.
+pub fn map_experimental_menu_hotkey(raw: &str) -> Option<ExperimentalSettingsAction> {
+    match raw {
+        "1" => return Some(ExperimentalSettingsAction::Sync),
+        "2" => return Some(ExperimentalSettingsAction::Backup),
+        "3" => return Some(ExperimentalSettingsAction::ToggleRefreshGuardian),
+        "[" | "-" => return Some(ExperimentalSettingsAction::DecreaseRefreshInterval),
+        "]" | "+" => return Some(ExperimentalSettingsAction::IncreaseRefreshInterval),
+        _ => {}
+    }
+    match raw.to_lowercase().as_str() {
+        "q" => Some(ExperimentalSettingsAction::Back),
+        "s" => Some(ExperimentalSettingsAction::Save),
+        _ => None,
+    }
+}
+
+/// `mapExperimentalStatusHotkey`.
+pub fn map_experimental_status_hotkey(raw: &str) -> Option<ExperimentalSettingsAction> {
+    if raw.to_lowercase() == "q" {
+        Some(ExperimentalSettingsAction::Back)
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn option_tables_have_schema_cardinality_and_order() {
+        assert_eq!(BACKEND_TOGGLE_OPTIONS.len(), 11);
+        assert_eq!(BACKEND_NUMBER_OPTIONS.len(), 16);
+        assert_eq!(BACKEND_CATEGORY_OPTIONS.len(), 4);
+        assert_eq!(
+            BACKEND_TOGGLE_OPTIONS[0].key,
+            BackendToggleSettingKey::LiveAccountSync
+        );
+        assert_eq!(
+            BACKEND_TOGGLE_OPTIONS[10].key,
+            BackendToggleSettingKey::PerProjectAccounts
+        );
+        // Every toggle/number key appears in exactly one category.
+        for option in BACKEND_TOGGLE_OPTIONS {
+            let count = BACKEND_CATEGORY_OPTIONS
+                .iter()
+                .filter(|category| category.toggle_keys.contains(&option.key))
+                .count();
+            assert_eq!(count, 1, "{} in exactly one category", option.key.as_str());
+        }
+        for option in BACKEND_NUMBER_OPTIONS {
+            let count = BACKEND_CATEGORY_OPTIONS
+                .iter()
+                .filter(|category| category.number_keys.contains(&option.key))
+                .count();
+            assert_eq!(count, 1, "{} in exactly one category", option.key.as_str());
+        }
+    }
+
+    #[test]
+    fn fetch_timeout_bounds_match_the_ts_expression() {
+        let option = backend_number_option_by_key(BackendNumberSettingKey::FetchTimeoutMs);
+        assert_eq!(option.min, 1_000.0);
+        assert_eq!(option.max, 600_000.0);
+        assert_eq!(option.step, 5_000.0);
+        let deferral =
+            backend_number_option_by_key(BackendNumberSettingKey::PreemptiveQuotaMaxDeferralMs);
+        assert_eq!(deferral.max, 86_400_000.0);
+    }
+
+    #[test]
+    fn refresh_interval_schema_entry_is_the_experimental_source_of_truth() {
+        // Spec 09 §5.14 / gotcha 24: 5_000 / 600_000 / 5_000.
+        let option = backend_number_option_by_key(BackendNumberSettingKey::ProactiveRefreshIntervalMs);
+        assert_eq!((option.min, option.max, option.step), (5_000.0, 600_000.0, 5_000.0));
+    }
+
+    #[test]
+    fn experimental_hotkeys_map_exactly() {
+        use ExperimentalSettingsAction as A;
+        assert_eq!(map_experimental_menu_hotkey("1"), Some(A::Sync));
+        assert_eq!(map_experimental_menu_hotkey("2"), Some(A::Backup));
+        assert_eq!(
+            map_experimental_menu_hotkey("3"),
+            Some(A::ToggleRefreshGuardian)
+        );
+        assert_eq!(
+            map_experimental_menu_hotkey("["),
+            Some(A::DecreaseRefreshInterval)
+        );
+        assert_eq!(
+            map_experimental_menu_hotkey("-"),
+            Some(A::DecreaseRefreshInterval)
+        );
+        assert_eq!(
+            map_experimental_menu_hotkey("]"),
+            Some(A::IncreaseRefreshInterval)
+        );
+        assert_eq!(
+            map_experimental_menu_hotkey("+"),
+            Some(A::IncreaseRefreshInterval)
+        );
+        assert_eq!(map_experimental_menu_hotkey("Q"), Some(A::Back));
+        assert_eq!(map_experimental_menu_hotkey("s"), Some(A::Save));
+        assert_eq!(map_experimental_menu_hotkey("x"), None);
+        assert_eq!(map_experimental_status_hotkey("q"), Some(A::Back));
+        assert_eq!(map_experimental_status_hotkey("s"), None);
+    }
+
+    #[test]
+    fn toggle_and_number_accessors_round_trip() {
+        let mut config = PluginConfig::default();
+        BackendToggleSettingKey::FastSession.set(&mut config, Some(true));
+        assert_eq!(config.fast_session, Some(true));
+        assert_eq!(
+            BackendToggleSettingKey::FastSession.get(&config),
+            Some(true)
+        );
+        BackendNumberSettingKey::FetchTimeoutMs.set(&mut config, Some(42_000.0));
+        assert_eq!(config.fetch_timeout_ms, Some(42_000.0));
+        assert_eq!(
+            BackendNumberSettingKey::FetchTimeoutMs.get(&config),
+            Some(42_000.0)
+        );
+    }
+}
diff --git a/crates/manager/src/settings/write_queue.rs b/crates/manager/src/settings/write_queue.rs
new file mode 100644
index 000000000..90058b160
--- /dev/null
+++ b/crates/manager/src/settings/write_queue.rs
@@ -0,0 +1,415 @@
+//! Port of `lib/codex-manager/settings-write-queue.ts` — per-path serialized
+//! settings writes with a bounded retry loop for Windows share-violation
+//! errno codes and HTTP-ish 429 hints.
+//!
+//! Contracts (spec 09 §5.5):
+//! - `SETTINGS_WRITE_MAX_ATTEMPTS = 4`, base delay 50 ms, ×2 exponential,
+//!   capped at 30 000 ms; `retryAfterMs`-style hints are honored, rounded and
+//!   clamped into `[10, 30_000]`.
+//! - Retryable = status 429 (from `status`/`statusCode`) OR errno code in
+//!   {EBUSY, EPERM, EAGAIN, ENOTEMPTY, EACCES}.
+//! - Per-`pathKey` FIFO: a new task waits for every previously queued task on
+//!   the same key (even failed ones); different keys proceed independently;
+//!   every retry of a task stays ahead of the next queued task.
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::sync::{Arc, Mutex, OnceLock};
+
+pub const SETTINGS_WRITE_MAX_ATTEMPTS: u32 = 4;
+pub const SETTINGS_WRITE_BASE_DELAY_MS: i64 = 50;
+pub const SETTINGS_WRITE_MAX_DELAY_MS: i64 = 30_000;
+pub const RETRYABLE_SETTINGS_WRITE_CODES: [&str; 5] =
+    ["EBUSY", "EPERM", "EAGAIN", "ENOTEMPTY", "EACCES"];
+
+/// Error introspection surface mirroring the duck-typed TS checks over
+/// `status`/`statusCode`, `code`, and the four `retryAfter*` spellings
+/// (already collapsed to one accessor here — TS coalesces them in order).
+pub trait SettingsWriteErrorLike {
+    fn status_code(&self) -> Option<i64> {
+        None
+    }
+    fn errno_code(&self) -> Option<String> {
+        None
+    }
+    fn retry_after_ms(&self) -> Option<f64> {
+        None
+    }
+}
+
+/// Concrete error carrier used by the settings persistence call sites (and
+/// tests): message plus the retry-relevant metadata the TS duck-typing read.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct SettingsWriteError {
+    pub message: String,
+    pub code: Option<String>,
+    pub status: Option<i64>,
+    pub retry_after_ms: Option<f64>,
+}
+
+impl SettingsWriteError {
+    pub fn message(message: impl Into<String>) -> Self {
+        SettingsWriteError {
+            message: message.into(),
+            ..Default::default()
+        }
+    }
+
+    pub fn with_code(message: impl Into<String>, code: impl Into<String>) -> Self {
+        SettingsWriteError {
+            message: message.into(),
+            code: Some(code.into()),
+            ..Default::default()
+        }
+    }
+
+    pub fn from_io(error: &std::io::Error) -> Self {
+        SettingsWriteError {
+            message: error.to_string(),
+            code: cma_core::fs_retry::code_of(error).map(str::to_string),
+            status: None,
+            retry_after_ms: None,
+        }
+    }
+}
+
+impl std::fmt::Display for SettingsWriteError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for SettingsWriteError {}
+
+impl SettingsWriteErrorLike for SettingsWriteError {
+    fn status_code(&self) -> Option<i64> {
+        self.status
+    }
+    fn errno_code(&self) -> Option<String> {
+        self.code.clone()
+    }
+    fn retry_after_ms(&self) -> Option<f64> {
+        self.retry_after_ms
+    }
+}
+
+impl SettingsWriteErrorLike for std::io::Error {
+    fn errno_code(&self) -> Option<String> {
+        cma_core::fs_retry::code_of(self).map(str::to_string)
+    }
+}
+
+/// `isRetryableSettingsWriteError`.
+pub fn is_retryable_settings_write_error<E: SettingsWriteErrorLike + ?Sized>(error: &E) -> bool {
+    if error.status_code() == Some(429) {
+        return true;
+    }
+    match error.errno_code() {
+        Some(code) => RETRYABLE_SETTINGS_WRITE_CODES.contains(&code.as_str()),
+        None => false,
+    }
+}
+
+/// `resolveRetryDelayMs` — retry-after hint (rounded, clamped `[10, 30_000]`)
+/// wins; else `min(30_000, 50 * 2^attempt)` with `attempt` 0-based.
+pub fn resolve_retry_delay_ms<E: SettingsWriteErrorLike + ?Sized>(error: &E, attempt: u32) -> i64 {
+    if let Some(retry_after_ms) = error.retry_after_ms()
+        && retry_after_ms.is_finite() && retry_after_ms > 0.0 {
+            let rounded = retry_after_ms.round() as i64;
+            return rounded.clamp(10, SETTINGS_WRITE_MAX_DELAY_MS);
+        }
+    let exp = SETTINGS_WRITE_BASE_DELAY_MS.saturating_mul(1_i64 << attempt.min(62));
+    exp.min(SETTINGS_WRITE_MAX_DELAY_MS)
+}
+
+// ---------------------------------------------------------------------------
+// Per-path FIFO queue
+// ---------------------------------------------------------------------------
+
+// TS keeps a promise-chain tail per pathKey. A fair (FIFO) `tokio::sync::Mutex`
+// per key reproduces the semantics: submitters queue in arrival order, a
+// failed predecessor never blocks the successor, and the whole retry loop of
+// one task runs while holding the key. The map entry is dropped once no other
+// waiter holds a reference (TS deletes the tail when it is still current).
+fn queues() -> &'static Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>> {
+    static QUEUES: OnceLock<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>> = OnceLock::new();
+    QUEUES.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn queue_for(path_key: &str) -> Arc<tokio::sync::Mutex<()>> {
+    let mut map = queues().lock().expect("settings write queue poisoned");
+    map.entry(path_key.to_string())
+        .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
+        .clone()
+}
+
+fn release_queue(path_key: &str, queue: &Arc<tokio::sync::Mutex<()>>) {
+    let mut map = queues().lock().expect("settings write queue poisoned");
+    if let Some(current) = map.get(path_key) {
+        // Two strong refs (map + our local clone) means nobody else is
+        // waiting; mirror the TS "delete only when still the tail" cleanup.
+        if Arc::ptr_eq(current, queue) && Arc::strong_count(queue) <= 2 {
+            map.remove(path_key);
+        }
+    }
+}
+
+/// `withQueuedRetry(pathKey, task, { sleep })` — the module's only real
+/// export. The sleep function is injected exactly like the TS deps object so
+/// tests can record delays without waiting.
+pub async fn with_queued_retry<T, E, Task, TaskFut, Sleep, SleepFut>(
+    path_key: &str,
+    mut task: Task,
+    sleep: Sleep,
+) -> Result<T, E>
+where
+    E: SettingsWriteErrorLike,
+    Task: FnMut() -> TaskFut,
+    TaskFut: Future<Output = Result<T, E>>,
+    Sleep: Fn(i64) -> SleepFut,
+    SleepFut: Future<Output = ()>,
+{
+    let queue = queue_for(path_key);
+    let guard = queue.lock().await;
+
+    let mut last_error: Option<E> = None;
+    let mut attempt: u32 = 0;
+    let result = loop {
+        if attempt >= SETTINGS_WRITE_MAX_ATTEMPTS {
+            break Err(last_error.expect("retry loop always records an error"));
+        }
+        match task().await {
+            Ok(value) => break Ok(value),
+            Err(error) => {
+                if !is_retryable_settings_write_error(&error) {
+                    break Err(error);
+                }
+                if attempt >= SETTINGS_WRITE_MAX_ATTEMPTS - 1 {
+                    break Err(error);
+                }
+                let delay = resolve_retry_delay_ms(&error, attempt);
+                last_error = Some(error);
+                sleep(delay).await;
+            }
+        }
+        attempt += 1;
+    };
+
+    drop(guard);
+    release_queue(path_key, &queue);
+    result
+}
+
+/// Default sleep implementation for production call sites (`lib/utils.sleep`).
+pub async fn default_sleep(ms: i64) {
+    if ms > 0 {
+        tokio::time::sleep(std::time::Duration::from_millis(ms as u64)).await;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::RefCell;
+    use std::rc::Rc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    fn recording_sleep() -> (
+        Rc<RefCell<Vec<i64>>>,
+        impl Fn(i64) -> std::future::Ready<()>,
+    ) {
+        let delays: Rc<RefCell<Vec<i64>>> = Rc::new(RefCell::new(Vec::new()));
+        let recorded = Rc::clone(&delays);
+        (delays, move |ms: i64| {
+            recorded.borrow_mut().push(ms);
+            std::future::ready(())
+        })
+    }
+
+    #[tokio::test]
+    async fn returns_the_task_result_without_sleeping_on_first_try_success() {
+        let (delays, sleep) = recording_sleep();
+        let result: Result<i32, SettingsWriteError> =
+            with_queued_retry("wq-first-try", || async { Ok(41) }, sleep).await;
+        assert_eq!(result.unwrap(), 41);
+        assert!(delays.borrow().is_empty());
+    }
+
+    #[tokio::test]
+    async fn retries_windows_sharing_violations_with_exponential_backoff() {
+        let (delays, sleep) = recording_sleep();
+        let attempts = AtomicUsize::new(0);
+        let result: Result<&str, SettingsWriteError> = with_queued_retry(
+            "wq-ebusy",
+            || {
+                let n = attempts.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    if n < 3 {
+                        Err(SettingsWriteError::with_code("resource busy", "EBUSY"))
+                    } else {
+                        Ok("saved")
+                    }
+                }
+            },
+            sleep,
+        )
+        .await;
+        assert_eq!(result.unwrap(), "saved");
+        assert_eq!(attempts.load(Ordering::SeqCst), 4);
+        // 50 * 2^attempt for attempts 0..=2.
+        assert_eq!(*delays.borrow(), vec![50, 100, 200]);
+    }
+
+    #[tokio::test]
+    async fn honors_a_429_retry_after_hint_clamped_into_the_sane_range() {
+        let (delays, sleep) = recording_sleep();
+        let attempts = AtomicUsize::new(0);
+        let result: Result<&str, SettingsWriteError> = with_queued_retry(
+            "wq-429",
+            || {
+                let n = attempts.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    match n {
+                        0 => Err(SettingsWriteError {
+                            message: "throttled".into(),
+                            status: Some(429),
+                            retry_after_ms: Some(120_000.0), // above the cap
+                            ..Default::default()
+                        }),
+                        1 => Err(SettingsWriteError {
+                            message: "throttled".into(),
+                            status: Some(429),
+                            retry_after_ms: Some(3.0), // below the floor
+                            ..Default::default()
+                        }),
+                        _ => Ok("saved"),
+                    }
+                }
+            },
+            sleep,
+        )
+        .await;
+        assert_eq!(result.unwrap(), "saved");
+        assert_eq!(*delays.borrow(), vec![30_000, 10]);
+    }
+
+    #[tokio::test]
+    async fn rethrows_non_retryable_errors_immediately() {
+        let (delays, sleep) = recording_sleep();
+        let attempts = AtomicUsize::new(0);
+        let result: Result<(), SettingsWriteError> = with_queued_retry(
+            "wq-fatal",
+            || {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                async { Err(SettingsWriteError::with_code("no entry", "ENOENT")) }
+            },
+            sleep,
+        )
+        .await;
+        let error = result.unwrap_err();
+        assert_eq!(error.code.as_deref(), Some("ENOENT"));
+        assert_eq!(attempts.load(Ordering::SeqCst), 1);
+        assert!(delays.borrow().is_empty());
+    }
+
+    #[tokio::test]
+    async fn gives_up_with_the_last_error_after_four_retryable_attempts() {
+        let (delays, sleep) = recording_sleep();
+        let attempts = AtomicUsize::new(0);
+        let result: Result<(), SettingsWriteError> = with_queued_retry(
+            "wq-give-up",
+            || {
+                let n = attempts.fetch_add(1, Ordering::SeqCst);
+                async move { Err(SettingsWriteError::with_code(format!("busy #{n}"), "EPERM")) }
+            },
+            sleep,
+        )
+        .await;
+        let error = result.unwrap_err();
+        assert_eq!(error.message, "busy #3");
+        assert_eq!(attempts.load(Ordering::SeqCst), 4);
+        assert_eq!(*delays.borrow(), vec![50, 100, 200]);
+    }
+
+    #[tokio::test]
+    async fn does_not_let_a_failed_predecessor_block_the_next_write() {
+        let (_, sleep) = recording_sleep();
+        let first: Result<(), SettingsWriteError> = with_queued_retry(
+            "wq-fail-then-ok",
+            || async { Err(SettingsWriteError::message("boom")) },
+            &sleep,
+        )
+        .await;
+        assert!(first.is_err());
+        let second: Result<i32, SettingsWriteError> =
+            with_queued_retry("wq-fail-then-ok", || async { Ok(7) }, &sleep).await;
+        assert_eq!(second.unwrap(), 7);
+    }
+
+    #[tokio::test]
+    async fn lets_different_paths_proceed_independently() {
+        // Task on path A blocks until we release it; a task on path B must be
+        // able to finish while A is still held.
+        let queue_a = queue_for("wq-independent-a");
+        let guard_a = queue_a.lock().await;
+
+        let (_, sleep) = recording_sleep();
+        let b: Result<&str, SettingsWriteError> =
+            with_queued_retry("wq-independent-b", || async { Ok("b done") }, sleep).await;
+        assert_eq!(b.unwrap(), "b done");
+
+        drop(guard_a);
+        release_queue("wq-independent-a", &queue_a);
+    }
+
+    #[tokio::test]
+    async fn keeps_every_retry_of_a_task_ahead_of_the_next_queued_task() {
+        let log: Arc<std::sync::Mutex<Vec<String>>> = Arc::new(std::sync::Mutex::new(Vec::new()));
+
+        let log_a = Arc::clone(&log);
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let attempts_a = Arc::clone(&attempts);
+        let first = with_queued_retry(
+            "wq-retry-ahead",
+            move || {
+                let log = Arc::clone(&log_a);
+                let n = attempts_a.fetch_add(1, Ordering::SeqCst);
+                async move {
+                    log.lock().unwrap().push(format!("a{n}"));
+                    if n < 2 {
+                        Err(SettingsWriteError::with_code("busy", "EBUSY"))
+                    } else {
+                        Ok::<_, SettingsWriteError>("a done")
+                    }
+                }
+            },
+            |_ms| async {
+                // Yield inside the retry sleep so an unfair implementation
+                // would let the queued task run in between.
+                tokio::task::yield_now().await;
+            },
+        );
+
+        let log_b = Arc::clone(&log);
+        let second = with_queued_retry(
+            "wq-retry-ahead",
+            move || {
+                let log = Arc::clone(&log_b);
+                async move {
+                    log.lock().unwrap().push("b0".to_string());
+                    Ok::<_, SettingsWriteError>("b done")
+                }
+            },
+            |_ms| async {},
+        );
+
+        let (first, second) = tokio::join!(first, second);
+        assert_eq!(first.unwrap(), "a done");
+        assert_eq!(second.unwrap(), "b done");
+        assert_eq!(
+            *log.lock().unwrap(),
+            vec!["a0", "a1", "a2", "b0"],
+            "every retry of task A must run before task B starts"
+        );
+    }
+}
diff --git a/crates/manager/src/update_notice.rs b/crates/manager/src/update_notice.rs
new file mode 100644
index 000000000..b038b7ed4
--- /dev/null
+++ b/crates/manager/src/update_notice.rs
@@ -0,0 +1,784 @@
+//! Port of `lib/update-notice.ts` — npm-registry update check with a 24h
+//! on-disk cache (`<cache-dir>/update-check-cache.json`).
+//!
+//! Byte contract: the cache is `JSON.stringify(cache, null, 2)` with **no
+//! trailing newline** (golden: `update-check-cache.json`); `latestVersion`
+//! serializes as JSON `null` when a fetch failed (failures are cached for
+//! 24h too); `clearUpdateCache` overwrites the file with the literal `{}`.
+//!
+//! Deviations from TS (recorded in the port notes):
+//! - `CACHE_DIR` was computed once at module load in TS; here it is derived
+//!   per call from `get_codex_cache_dir()` so the env sandbox works. In
+//!   production the env never changes mid-process, so behavior is identical.
+//! - The module-level promise write queue is a process-global mutex; retry
+//!   delays block the locking thread (bounded: 15+30+60 ms worst case).
+//! - `getCurrentVersion` walks up from the running executable's directory
+//!   (the TS walked from the compiled module dir) looking for the
+//!   `codex-multi-auth` package.json.
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use cma_core::fs_retry::code_of;
+use cma_core::json_io::stringify_pretty2;
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::runtime_paths::get_codex_cache_dir;
+use cma_core::temp_path::temp_path_for;
+use cma_core::utils::now_ms;
+use serde::Serialize;
+use serde_json::{Value, json};
+
+const PACKAGE_NAME: &str = "codex-multi-auth";
+const NPM_REGISTRY_URL: &str = "https://registry.npmjs.org/codex-multi-auth/latest";
+const CACHE_FILE_NAME: &str = "update-check-cache.json";
+const CHECK_INTERVAL_MS: i64 = 24 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS: u64 = 5_000;
+/// Narrower than fs-retry's shared set: no EAGAIN/EACCES.
+const RETRYABLE_WRITE_ERRORS: [&str; 3] = ["EBUSY", "EPERM", "ENOTEMPTY"];
+
+/// Serializes cache writes within the process (TS `updateCacheWriteQueue`).
+static UPDATE_CACHE_WRITE_QUEUE: Mutex<()> = Mutex::new(());
+
+fn logger() -> ScopedLogger {
+    create_logger("update-notice")
+}
+
+fn cache_file() -> PathBuf {
+    get_codex_cache_dir().join(CACHE_FILE_NAME)
+}
+
+/// On-disk cache shape (`lastCheck` / `latestVersion` / `currentVersion`).
+/// `latest_version` must serialize as literal `null` when absent — no skip.
+#[derive(Clone, Debug, Serialize)]
+struct UpdateCheckCache {
+    #[serde(rename = "lastCheck")]
+    last_check: i64,
+    #[serde(rename = "latestVersion")]
+    latest_version: Option<String>,
+    #[serde(rename = "currentVersion")]
+    current_version: String,
+}
+
+/// Leniently-read cache (the TS cast the parsed JSON without validation; a
+/// cleared `{}` cache parses fine and every field reads as absent).
+struct LoadedCache {
+    last_check: Option<f64>,
+    latest_version: Option<String>,
+    current_version: Option<String>,
+}
+
+/// TS `UpdateCheckResult`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct UpdateCheckResult {
+    pub has_update: bool,
+    pub current_version: String,
+    pub latest_version: Option<String>,
+    /// Always `"npm install -g codex-multi-auth@latest"`.
+    pub update_command: String,
+}
+
+/// TS `writeCacheContents(serialized)` — mkdir, temp write + rename, up to 4
+/// attempts with 15/30/60 ms delays on EBUSY/EPERM/ENOTEMPTY; best-effort
+/// temp unlink after a final failure.
+fn write_cache_contents(serialized: &str) -> std::io::Result<()> {
+    let cache_dir = get_codex_cache_dir();
+    let cache_path = cache_file();
+    let mut temp_path: Option<PathBuf> = None;
+    let mut wrote_temp = false;
+    let result = (|| {
+        if !cache_dir.exists() {
+            std::fs::create_dir_all(&cache_dir)?;
+        }
+        let temp = temp_path_for(&cache_path);
+        temp_path = Some(temp.clone());
+        let mut last_error: Option<std::io::Error> = None;
+        for attempt in 0..4u32 {
+            let step = std::fs::write(&temp, serialized)
+                .and_then(|()| std::fs::rename(&temp, &cache_path));
+            match step {
+                Ok(()) => {
+                    wrote_temp = false;
+                    return Ok(());
+                }
+                Err(error) => {
+                    let code = code_of(&error).unwrap_or("");
+                    wrote_temp = true;
+                    let retryable = RETRYABLE_WRITE_ERRORS.contains(&code);
+                    if !retryable || attempt >= 3 {
+                        return Err(error);
+                    }
+                    last_error = Some(error);
+                    std::thread::sleep(std::time::Duration::from_millis(15 * (1 << attempt)));
+                }
+            }
+        }
+        match last_error {
+            Some(error) => Err(error),
+            None => Ok(()),
+        }
+    })();
+    if wrote_temp && let Some(temp) = &temp_path {
+        // Best-effort temp cleanup.
+        let _ = std::fs::remove_file(temp);
+    }
+    result
+}
+
+/// TS `resolvePackageRootFromModuleDir(moduleDir)` — walk up (max 8 levels)
+/// to the `package.json` whose `name` is `codex-multi-auth`; fallback is
+/// `join(moduleDir, "..")`. Exported for tests.
+pub fn resolve_package_root_from_module_dir(module_dir: &Path) -> PathBuf {
+    let mut current = module_dir.to_path_buf();
+    for _depth in 0..8 {
+        let package_json_path = current.join("package.json");
+        if package_json_path.exists()
+            && let Ok(raw) = std::fs::read_to_string(&package_json_path)
+            && let Ok(parsed) = serde_json::from_str::<Value>(&raw)
+            && parsed.get("name").and_then(Value::as_str) == Some(PACKAGE_NAME)
+        {
+            return current;
+        }
+        // Keep walking; malformed metadata should not break startup notices.
+        let Some(parent) = current.parent().map(Path::to_path_buf) else {
+            break;
+        };
+        if parent == current {
+            break;
+        }
+        current = parent;
+    }
+    module_dir.join("..")
+}
+
+fn get_module_dir() -> PathBuf {
+    std::env::current_exe()
+        .ok()
+        .and_then(|exe| exe.parent().map(Path::to_path_buf))
+        .unwrap_or_else(|| PathBuf::from("."))
+}
+
+fn get_package_root() -> PathBuf {
+    use std::sync::OnceLock;
+    static CACHED_PACKAGE_ROOT: OnceLock<PathBuf> = OnceLock::new();
+    CACHED_PACKAGE_ROOT
+        .get_or_init(|| resolve_package_root_from_module_dir(&get_module_dir()))
+        .clone()
+}
+
+/// TS `getCurrentVersion()` — any error ⇒ `"0.0.0"` (debug-logged).
+fn get_current_version() -> String {
+    let package_json_path = get_package_root().join("package.json");
+    let read = std::fs::read_to_string(&package_json_path)
+        .map_err(|e| e.to_string())
+        .and_then(|raw| serde_json::from_str::<Value>(&raw).map_err(|e| e.to_string()))
+        .and_then(|parsed| {
+            parsed
+                .get("version")
+                .and_then(Value::as_str)
+                .map(str::to_string)
+                .ok_or_else(|| "missing version".to_string())
+        });
+    match read {
+        Ok(version) => version,
+        Err(error) => {
+            logger().debug(
+                "Failed to read current package version",
+                Some(&json!({ "error": error })),
+            );
+            "0.0.0".to_string()
+        }
+    }
+}
+
+/// TS `loadCache()` — missing/corrupt ⇒ `None` (debug-logged).
+fn load_cache() -> Option<LoadedCache> {
+    let cache_path = cache_file();
+    if !cache_path.exists() {
+        return None;
+    }
+    let parsed: Result<Value, String> = std::fs::read_to_string(&cache_path)
+        .map_err(|e| e.to_string())
+        .and_then(|content| serde_json::from_str::<Value>(&content).map_err(|e| e.to_string()));
+    match parsed {
+        Ok(value) => Some(LoadedCache {
+            last_check: value.get("lastCheck").and_then(Value::as_f64),
+            latest_version: value
+                .get("latestVersion")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            current_version: value
+                .get("currentVersion")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+        }),
+        Err(error) => {
+            logger().debug("Failed to load update cache", Some(&json!({ "error": error })));
+            None
+        }
+    }
+}
+
+/// TS `saveCache(cache)` — queued write; failures logged at `warn` and
+/// swallowed.
+fn save_cache(cache: &UpdateCheckCache) {
+    let _guard = UPDATE_CACHE_WRITE_QUEUE
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Err(error) = write_cache_contents(&stringify_pretty2(cache)) {
+        logger().warn(
+            "Failed to save update cache",
+            Some(&json!({ "error": error.to_string() })),
+        );
+    }
+}
+
+struct ParsedSemver {
+    core: [i64; 3],
+    prerelease: Vec<String>,
+}
+
+/// TS `parseSemver(version)`.
+fn parse_semver(version: &str) -> ParsedSemver {
+    let normalized = version.trim();
+    let normalized = normalized
+        .strip_prefix('v')
+        .or_else(|| normalized.strip_prefix('V'))
+        .unwrap_or(normalized);
+    let without_build = normalized.split('+').next().unwrap_or("0.0.0");
+    // JS `split("-", 2)` TRUNCATES: "1.0.0-beta-2" → ["1.0.0", "beta"] — the
+    // prerelease keeps only the segment before the SECOND hyphen.
+    let mut dash_parts = without_build.splitn(3, '-');
+    let core_part = dash_parts.next().unwrap_or(without_build);
+    let prerelease_part = dash_parts.next();
+    let core_part = if core_part.is_empty() { "0.0.0" } else { core_part };
+
+    let to_safe_int = |value: &str| -> i64 {
+        if !value.chars().all(|c| c.is_ascii_digit()) || value.is_empty() {
+            return 0;
+        }
+        value.parse::<i64>().unwrap_or(0)
+    };
+
+    let mut parts = core_part.split('.');
+    let major = parts.next().unwrap_or("0");
+    let minor = parts.next().unwrap_or("0");
+    let patch = parts.next().unwrap_or("0");
+
+    ParsedSemver {
+        core: [to_safe_int(major), to_safe_int(minor), to_safe_int(patch)],
+        prerelease: match prerelease_part {
+            Some(p) if !p.trim().is_empty() => p
+                .split('.')
+                .filter(|segment| !segment.is_empty())
+                .map(str::to_string)
+                .collect(),
+            _ => Vec::new(),
+        },
+    }
+}
+
+/// Approximation of `latestPart.localeCompare(currentPart, "en",
+/// {sensitivity: "case"})`: case-insensitive primary comparison with a
+/// lowercase-first tiebreak (matches en collation for the alnum tags npm
+/// actually publishes).
+fn locale_compare_en_case(latest: &str, current: &str) -> std::cmp::Ordering {
+    let primary = latest.to_lowercase().cmp(&current.to_lowercase());
+    if primary != std::cmp::Ordering::Equal {
+        return primary;
+    }
+    for (l, c) in latest.chars().zip(current.chars()) {
+        if l == c {
+            continue;
+        }
+        let l_lower = l.is_lowercase();
+        let c_lower = c.is_lowercase();
+        if l_lower != c_lower {
+            // lowercase sorts first in en collation (caseFirst: false)
+            return if l_lower {
+                std::cmp::Ordering::Less
+            } else {
+                std::cmp::Ordering::Greater
+            };
+        }
+        return l.cmp(&c);
+    }
+    latest.len().cmp(&current.len())
+}
+
+/// TS `comparePrerelease(current, latest)`.
+fn compare_prerelease(current: &[String], latest: &[String]) -> i32 {
+    let max_len = current.len().max(latest.len());
+    for i in 0..max_len {
+        let current_part = current.get(i);
+        let latest_part = latest.get(i);
+        match (current_part, latest_part) {
+            (None, None) => return 0,
+            (None, Some(_)) => return 1,
+            (Some(_), None) => return -1,
+            (Some(c), Some(l)) => {
+                if c == l {
+                    continue;
+                }
+                let current_is_numeric = !c.is_empty() && c.chars().all(|ch| ch.is_ascii_digit());
+                let latest_is_numeric = !l.is_empty() && l.chars().all(|ch| ch.is_ascii_digit());
+                if current_is_numeric && latest_is_numeric {
+                    let current_num = c.parse::<i64>().unwrap_or(0);
+                    let latest_num = l.parse::<i64>().unwrap_or(0);
+                    if latest_num > current_num {
+                        return 1;
+                    }
+                    if latest_num < current_num {
+                        return -1;
+                    }
+                    continue;
+                }
+                if current_is_numeric && !latest_is_numeric {
+                    return 1;
+                }
+                if !current_is_numeric && latest_is_numeric {
+                    return -1;
+                }
+                match locale_compare_en_case(l, c) {
+                    std::cmp::Ordering::Greater => return 1,
+                    std::cmp::Ordering::Less => return -1,
+                    std::cmp::Ordering::Equal => {}
+                }
+            }
+        }
+    }
+    0
+}
+
+/// TS `compareVersions(current, latest)` — `> 0` iff `latest` is newer.
+fn compare_versions(current: &str, latest: &str) -> i32 {
+    let parsed_current = parse_semver(current);
+    let parsed_latest = parse_semver(latest);
+
+    for i in 0..3 {
+        let current_part = parsed_current.core[i];
+        let latest_part = parsed_latest.core[i];
+        if latest_part > current_part {
+            return 1;
+        }
+        if latest_part < current_part {
+            return -1;
+        }
+    }
+
+    let current_has_prerelease = !parsed_current.prerelease.is_empty();
+    let latest_has_prerelease = !parsed_latest.prerelease.is_empty();
+    if !current_has_prerelease && latest_has_prerelease {
+        return -1;
+    }
+    if current_has_prerelease && !latest_has_prerelease {
+        return 1;
+    }
+    compare_prerelease(&parsed_current.prerelease, &parsed_latest.prerelease)
+}
+
+/// TS `fetchLatestVersion(timeoutMs)` — non-OK / wrong package name / any
+/// error ⇒ `None` (debug-logged).
+async fn fetch_latest_version(timeout_ms: u64) -> Option<String> {
+    let result: Result<Option<String>, String> = async {
+        let client = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_millis(timeout_ms))
+            .build()
+            .map_err(|e| e.to_string())?;
+        let response = client
+            .get(NPM_REGISTRY_URL)
+            .header("Accept", "application/json")
+            .send()
+            .await
+            .map_err(|e| e.to_string())?;
+        if !response.status().is_success() {
+            logger().debug(
+                "Failed to fetch npm registry",
+                Some(&json!({ "status": response.status().as_u16() })),
+            );
+            return Ok(None);
+        }
+        let data: Value = response.json().await.map_err(|e| e.to_string())?;
+        if data.get("name").and_then(Value::as_str) == Some(PACKAGE_NAME) {
+            Ok(data
+                .get("version")
+                .and_then(Value::as_str)
+                .map(str::to_string))
+        } else {
+            Ok(None)
+        }
+    }
+    .await;
+    match result {
+        Ok(version) => version,
+        Err(error) => {
+            logger().debug(
+                "Failed to check for updates",
+                Some(&json!({ "error": error })),
+            );
+            None
+        }
+    }
+}
+
+fn build_manual_update_command() -> String {
+    format!("npm install -g {PACKAGE_NAME}@latest")
+}
+
+/// TS `formatManualUpdateNotice(result)` — FROZEN user-visible string.
+pub fn format_manual_update_notice(result: &UpdateCheckResult) -> String {
+    // TS interpolates `v${result.latestVersion}` — a null renders as "null".
+    let latest = result.latest_version.as_deref().unwrap_or("null");
+    [
+        format!("codex-multi-auth update available: v{latest}"),
+        format!("current: v{}", result.current_version),
+        format!("run: {}", result.update_command),
+    ]
+    .join("; ")
+}
+
+/// Core of `checkForUpdates` with the network fetch injected (Rust-only test
+/// seam; the TS tests stubbed global `fetch`).
+async fn check_for_updates_with<F, Fut>(
+    force: bool,
+    current_version: String,
+    now: i64,
+    fetcher: F,
+) -> UpdateCheckResult
+where
+    F: FnOnce() -> Fut,
+    Fut: std::future::Future<Output = Option<String>>,
+{
+    let cache = load_cache();
+    let update_command = build_manual_update_command();
+
+    if !force
+        && let Some(cache) = &cache
+        && cache.current_version.as_deref() == Some(current_version.as_str())
+        && let Some(last_check) = cache.last_check
+        && ((now as f64) - last_check) < CHECK_INTERVAL_MS as f64
+    {
+        let has_update = match &cache.latest_version {
+            Some(latest) => compare_versions(&current_version, latest) > 0,
+            None => false,
+        };
+        return UpdateCheckResult {
+            has_update,
+            current_version,
+            latest_version: cache.latest_version.clone(),
+            update_command,
+        };
+    }
+
+    let latest_version = fetcher().await;
+    // Cache even a failed fetch (latestVersion: null) for 24h.
+    save_cache(&UpdateCheckCache {
+        last_check: now,
+        latest_version: latest_version.clone(),
+        current_version: current_version.clone(),
+    });
+
+    let has_update = match &latest_version {
+        Some(latest) => compare_versions(&current_version, latest) > 0,
+        None => false,
+    };
+
+    UpdateCheckResult {
+        has_update,
+        current_version,
+        latest_version,
+        update_command,
+    }
+}
+
+/// TS `checkForUpdates(force = false, fetchTimeoutMs = 5000)`.
+pub async fn check_for_updates(force: bool, fetch_timeout_ms: Option<u64>) -> UpdateCheckResult {
+    let timeout_ms = fetch_timeout_ms.unwrap_or(UPDATE_CHECK_TIMEOUT_MS);
+    check_for_updates_with(force, get_current_version(), now_ms(), || {
+        fetch_latest_version(timeout_ms)
+    })
+    .await
+}
+
+/// Toast sink for [`check_and_notify`] (TS `showToast(message, variant)`;
+/// variant is `"info" | "warning"`).
+pub type ShowToastFn<'a> = &'a (dyn Fn(&str, &str) + Send + Sync);
+
+/// TS `checkAndNotify(showToast?)` — logs the manual notice at `info` and
+/// (when provided) shows a toast; all failures swallowed at `debug`.
+pub async fn check_and_notify(show_toast: Option<ShowToastFn<'_>>) {
+    let result = check_for_updates(false, None).await;
+    if result.has_update && result.latest_version.is_some() {
+        let message = format_manual_update_notice(&result);
+        logger().info(&message, None);
+        if let Some(show_toast) = show_toast {
+            let latest = result.latest_version.as_deref().unwrap_or("null");
+            show_toast(
+                &format!(
+                    "Plugin update available: v{latest}. Run: {}",
+                    result.update_command
+                ),
+                "info",
+            );
+        }
+    }
+}
+
+/// TS `clearUpdateCache()` — queued overwrite with the literal `{}` (only
+/// when the file exists); all errors swallowed.
+pub fn clear_update_cache() {
+    let _guard = UPDATE_CACHE_WRITE_QUEUE
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if cache_file().exists() {
+        let _ = write_cache_contents("{}");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::goldens::read_golden_string;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    // Ported from test/update-notice.test.ts (the fs/fetch mock harness maps
+    // onto the env sandbox + the injected fetcher seam).
+
+    async fn run_check(
+        force: bool,
+        current: &str,
+        now: i64,
+        fetch_result: Option<&str>,
+    ) -> (UpdateCheckResult, bool) {
+        let fetched = std::cell::Cell::new(false);
+        let result = check_for_updates_with(force, current.to_string(), now, || {
+            fetched.set(true);
+            let value = fetch_result.map(str::to_string);
+            async move { value }
+        })
+        .await;
+        (result, fetched.get())
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn reports_newer_registry_versions_and_the_manual_install_command() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000; // 2026-01-30T12:00:00Z
+        let (result, fetched) = run_check(true, "4.12.0", now, Some("5.0.0")).await;
+        assert!(fetched);
+        assert!(result.has_update);
+        assert_eq!(result.current_version, "4.12.0");
+        assert_eq!(result.latest_version.as_deref(), Some("5.0.0"));
+        assert_eq!(
+            result.update_command,
+            "npm install -g codex-multi-auth@latest"
+        );
+        assert_eq!(
+            format_manual_update_notice(&result),
+            "codex-multi-auth update available: v5.0.0; current: v4.12.0; run: npm install -g codex-multi-auth@latest"
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn handles_semver_comparison_table() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000;
+        // (latest, has_update, current)
+        let cases: &[(&str, bool, &str)] = &[
+            ("4.11.0", false, "4.12.0"),
+            ("4.12.0", false, "4.12.0"),
+            ("v4.13.0", true, "4.12.0"),
+            ("0.1.0", true, "0.1.0-beta.0"),
+            ("0.1.0-beta.1", false, "0.1.0"),
+        ];
+        for (latest, has_update, current) in cases {
+            let (result, _) = run_check(true, current, now, Some(latest)).await;
+            assert_eq!(
+                result.has_update, *has_update,
+                "latest={latest} current={current}"
+            );
+        }
+    }
+
+    #[test]
+    fn compare_versions_covers_prerelease_ordering_rules() {
+        // release beats prerelease
+        assert!(compare_versions("1.0.0-alpha", "1.0.0") > 0);
+        assert!(compare_versions("1.0.0", "1.0.0-alpha") < 0);
+        // numeric vs numeric
+        assert!(compare_versions("1.0.0-beta.1", "1.0.0-beta.2") > 0);
+        // numeric < alphanumeric
+        assert!(compare_versions("1.0.0-1", "1.0.0-alpha") > 0);
+        assert!(compare_versions("1.0.0-alpha", "1.0.0-1") < 0);
+        // missing segment loses (shorter list is older)
+        assert!(compare_versions("1.0.0-beta", "1.0.0-beta.1") > 0);
+        assert!(compare_versions("1.0.0-beta.1", "1.0.0-beta") < 0);
+        // lexical fallback
+        assert!(compare_versions("1.0.0-alpha", "1.0.0-beta") > 0);
+        // build metadata ignored
+        assert_eq!(compare_versions("1.0.0+build.1", "1.0.0+build.2"), 0);
+        // equal
+        assert_eq!(compare_versions("1.2.3", "1.2.3"), 0);
+        // JS split("-", 2) truncation: everything after the second hyphen is
+        // dropped, so "1.0.0-beta-2" parses identically to "1.0.0-beta".
+        assert_eq!(compare_versions("1.0.0-beta-2", "1.0.0-beta"), 0);
+        assert_eq!(compare_versions("1.0.0-beta", "1.0.0-beta-9"), 0);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn reuses_the_daily_cache_without_another_registry_fetch() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000_i64;
+        save_cache(&UpdateCheckCache {
+            last_check: now - 1_000,
+            latest_version: Some("5.0.0".to_string()),
+            current_version: "4.12.0".to_string(),
+        });
+
+        let (result, fetched) = run_check(false, "4.12.0", now, Some("9.9.9")).await;
+        assert!(!fetched, "cache hit must not fetch");
+        assert!(result.has_update);
+        assert_eq!(result.latest_version.as_deref(), Some("5.0.0"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn refreshes_the_daily_cache_when_the_installed_version_changes() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000_i64;
+        save_cache(&UpdateCheckCache {
+            last_check: now - 1_000,
+            latest_version: Some("4.13.0".to_string()),
+            current_version: "4.11.0".to_string(),
+        });
+
+        let (result, fetched) = run_check(false, "4.12.0", now, Some("5.0.0")).await;
+        assert!(fetched, "version change must refetch");
+        assert_eq!(result.latest_version.as_deref(), Some("5.0.0"));
+        assert!(result.has_update);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn refreshes_stale_cache_entries_and_writes_the_new_result() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000_i64;
+        save_cache(&UpdateCheckCache {
+            last_check: now - 25 * 60 * 60 * 1_000,
+            latest_version: Some("4.13.0".to_string()),
+            current_version: "4.12.0".to_string(),
+        });
+
+        let (result, fetched) = run_check(false, "4.12.0", now, Some("5.0.0")).await;
+        assert!(fetched);
+        assert_eq!(result.latest_version.as_deref(), Some("5.0.0"));
+        let written = std::fs::read_to_string(cache_file()).unwrap();
+        assert!(written.contains("\"latestVersion\": \"5.0.0\""));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn caches_failed_fetches_as_null_for_24_hours() {
+        let _sandbox = EnvSandbox::new();
+        let now = 1_769_774_400_000_i64;
+        let (result, _) = run_check(true, "4.12.0", now, None).await;
+        assert!(!result.has_update);
+        assert_eq!(result.latest_version, None);
+
+        let written = std::fs::read_to_string(cache_file()).unwrap();
+        assert!(written.contains("\"latestVersion\": null"));
+
+        // The cached failure short-circuits the next non-forced check.
+        let (cached, fetched) = run_check(false, "4.12.0", now + 1_000, Some("9.9.9")).await;
+        assert!(!fetched);
+        assert_eq!(cached.latest_version, None);
+        assert!(!cached.has_update);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn cache_serialization_matches_the_ts_golden_bytes() {
+        let _sandbox = EnvSandbox::new();
+        save_cache(&UpdateCheckCache {
+            last_check: 1_750_000_000_000,
+            latest_version: Some("9.9.9".to_string()),
+            current_version: "2.7.1".to_string(),
+        });
+        let written = std::fs::read(cache_file()).unwrap();
+        let golden = read_golden_string("update-check-cache.json");
+        assert_eq!(String::from_utf8(written).unwrap(), golden);
+        assert!(!golden.ends_with('\n'), "cache must have NO trailing newline");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn clears_the_cached_notice_file_to_a_literal_empty_object() {
+        let _sandbox = EnvSandbox::new();
+        // No-op when the file does not exist.
+        clear_update_cache();
+        assert!(!cache_file().exists());
+
+        save_cache(&UpdateCheckCache {
+            last_check: 1,
+            latest_version: Some("5.0.0".to_string()),
+            current_version: "4.12.0".to_string(),
+        });
+        clear_update_cache();
+        let written = std::fs::read_to_string(cache_file()).unwrap();
+        assert_eq!(written, "{}");
+
+        // A cleared cache is treated as stale (fields all absent).
+        let now = 1_769_774_400_000_i64;
+        let (_, fetched) = run_check(false, "4.12.0", now, Some("5.0.0")).await;
+        assert!(fetched, "cleared cache must force a refetch");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn resolves_the_package_root_by_walking_up_to_package_metadata() {
+        let sandbox = EnvSandbox::new();
+        let package_root = sandbox.root().join("node_modules").join("codex-multi-auth");
+        let module_dir = package_root.join("dist").join("lib");
+        std::fs::create_dir_all(&module_dir).unwrap();
+        std::fs::write(
+            package_root.join("package.json"),
+            "{\"name\": \"codex-multi-auth\", \"version\": \"4.12.0\"}",
+        )
+        .unwrap();
+
+        assert_eq!(
+            resolve_package_root_from_module_dir(&module_dir),
+            package_root
+        );
+
+        // Wrong-name package.json keeps walking; no match falls back to "..".
+        let other_dir = sandbox.root().join("other").join("dist");
+        std::fs::create_dir_all(&other_dir).unwrap();
+        std::fs::write(
+            sandbox.root().join("other").join("package.json"),
+            "{\"name\": \"other-package\", \"version\": \"1.0.0\"}",
+        )
+        .unwrap();
+        assert_eq!(
+            resolve_package_root_from_module_dir(&other_dir),
+            other_dir.join("..")
+        );
+    }
+
+    #[test]
+    fn format_manual_update_notice_is_the_frozen_string() {
+        let result = UpdateCheckResult {
+            has_update: true,
+            current_version: "4.12.0".to_string(),
+            latest_version: Some("5.0.0".to_string()),
+            update_command: build_manual_update_command(),
+        };
+        assert_eq!(
+            format_manual_update_notice(&result),
+            "codex-multi-auth update available: v5.0.0; current: v4.12.0; run: npm install -g codex-multi-auth@latest"
+        );
+    }
+}
diff --git a/crates/proxy/Cargo.toml b/crates/proxy/Cargo.toml
new file mode 100644
index 000000000..66e74a779
--- /dev/null
+++ b/crates/proxy/Cargo.toml
@@ -0,0 +1,49 @@
+[package]
+name = "cma-proxy"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-storage = { path = "../storage" }
+cma-auth = { path = "../auth" }
+cma-accounts = { path = "../accounts" }
+cma-rotation = { path = "../rotation" }
+cma-request = { path = "../request" }
+cma-quota = { path = "../quota" }
+cma-cli-mirror = { path = "../climirror" }
+cma-usage = { path = "../usage" }
+cma-runtime = { path = "../runtime" }
+serde.workspace = true
+serde_json.workspace = true
+axum.workspace = true
+hyper.workspace = true
+hyper-util.workspace = true
+http.workspace = true
+http-body.workspace = true
+http-body-util.workspace = true
+subtle.workspace = true
+tokio.workspace = true
+bytes.workspace = true
+futures.workspace = true
+reqwest.workspace = true
+uuid.workspace = true
+rand.workspace = true
+sha2.workspace = true
+base64.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+wiremock.workspace = true
+base64.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/proxy/src/client_auth.rs b/crates/proxy/src/client_auth.rs
new file mode 100644
index 000000000..a755c54a2
--- /dev/null
+++ b/crates/proxy/src/client_auth.rs
@@ -0,0 +1,193 @@
+//! Client-key authentication for the runtime rotation proxy — port of the
+//! auth half of `lib/runtime-rotation-proxy.ts` (`safeEqual`,
+//! `isAuthorizedClient`) plus the per-process key generator
+//! (`createRuntimeRotationProxyClientApiKey` from `scripts/codex.js`).
+//!
+//! Spec 04 §9 (gotcha 22): the comparison is constant-time with an explicit
+//! length-equality check, and client auth runs BEFORE path routing so an
+//! unknown caller can never enumerate endpoints (always 401, never 404).
+
+use http::HeaderMap;
+use rand::TryRngCore;
+use subtle::ConstantTimeEq;
+
+/// TS `createRuntimeRotationProxyClientApiKey()` (`scripts/codex.js`):
+/// `randomBytes(32).toString("hex")` — 64 lowercase hex chars from an
+/// OS-CSPRNG.
+pub fn create_runtime_rotation_proxy_client_api_key() -> String {
+    let mut bytes = [0u8; 32];
+    rand::rngs::OsRng
+        .try_fill_bytes(&mut bytes)
+        .expect("OS RNG unavailable");
+    let mut out = String::with_capacity(64);
+    for byte in bytes {
+        use std::fmt::Write;
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+/// TS `safeEqual(left, right)` — constant-time compare over buffers padded to
+/// `max(left.len, right.len, 1)`, AND-ed with a length-equality check. The
+/// padding keeps the constant-time comparison running over equal-length
+/// inputs so a length mismatch cannot short-circuit it.
+pub fn safe_equal(left: &str, right: &str) -> bool {
+    let left_bytes = left.as_bytes();
+    let right_bytes = right.as_bytes();
+    let compare_length = left_bytes.len().max(right_bytes.len()).max(1);
+    let mut padded_left = vec![0u8; compare_length];
+    let mut padded_right = vec![0u8; compare_length];
+    padded_left[..left_bytes.len()].copy_from_slice(left_bytes);
+    padded_right[..right_bytes.len()].copy_from_slice(right_bytes);
+    let equal: bool = padded_left.ct_eq(&padded_right).into();
+    equal && left_bytes.len() == right_bytes.len()
+}
+
+/// TS private `isAuthorizedClient(headers, clientApiKey)` — accepts
+/// `Authorization: Bearer <key>` (scheme case-insensitive, value trimmed;
+/// regex `/^Bearer\s+(.+)$/i`) or `x-api-key: <key>`, both compared with
+/// [`safe_equal`].
+pub fn is_authorized_client(headers: &HeaderMap, client_api_key: &str) -> bool {
+    let authorization = headers
+        .get("authorization")
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or("");
+    if let Some(bearer) = parse_bearer(authorization)
+        && !bearer.is_empty()
+        && safe_equal(bearer, client_api_key)
+    {
+        return true;
+    }
+    match headers.get("x-api-key").and_then(|value| value.to_str().ok()) {
+        Some(api_key) => safe_equal(api_key, client_api_key),
+        None => false,
+    }
+}
+
+/// `/^Bearer\s+(.+)$/i` — scheme match is case-insensitive, at least one
+/// whitespace char, remainder captured then trimmed (the TS `.trim()` on the
+/// capture).
+fn parse_bearer(authorization: &str) -> Option<&str> {
+    let rest = strip_prefix_ignore_ascii_case(authorization, "Bearer")?;
+    // `\s+` — require at least one leading whitespace char after the scheme.
+    if !rest.starts_with(|c: char| c.is_whitespace()) {
+        return None;
+    }
+    let captured = rest.trim_start_matches(|c: char| c.is_whitespace());
+    // `(.+)` — the capture must be non-empty before trimming.
+    if captured.is_empty() {
+        return None;
+    }
+    Some(captured.trim())
+}
+
+fn strip_prefix_ignore_ascii_case<'a>(value: &'a str, prefix: &str) -> Option<&'a str> {
+    if value.len() >= prefix.len() && value[..prefix.len()].eq_ignore_ascii_case(prefix) {
+        Some(&value[prefix.len()..])
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::HeaderValue;
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.append(
+                name.parse::<http::header::HeaderName>().unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn generated_client_keys_are_64_hex_chars_and_unique() {
+        let first = create_runtime_rotation_proxy_client_api_key();
+        let second = create_runtime_rotation_proxy_client_api_key();
+        assert_eq!(first.len(), 64);
+        assert!(first.bytes().all(|b| b.is_ascii_hexdigit()));
+        assert!(first.bytes().all(|b| !b.is_ascii_uppercase()));
+        assert_ne!(first, second);
+    }
+
+    #[test]
+    fn safe_equal_matches_only_identical_strings() {
+        assert!(safe_equal("runtime-secret", "runtime-secret"));
+        assert!(!safe_equal("runtime-secret", "runtime-secreT"));
+        // Mismatched lengths compare over padded buffers and return false
+        // (the TS safe-equal test asserts timingSafeEqual still ran on
+        // equal-length padded buffers — structurally guaranteed here by
+        // ct_eq over the padded vectors).
+        assert!(!safe_equal("short", "runtime-secret-with-longer-length"));
+        assert!(!safe_equal("runtime-secret-with-longer-length", "short"));
+    }
+
+    #[test]
+    fn safe_equal_handles_empty_inputs_like_ts() {
+        // TS: compareLength = max(0, 0, 1) = 1 — two zero buffers are equal
+        // and the length check (0 === 0) passes.
+        assert!(safe_equal("", ""));
+        assert!(!safe_equal("", "x"));
+        assert!(!safe_equal("x", ""));
+    }
+
+    #[test]
+    fn authorizes_bearer_case_insensitively_and_trims() {
+        let key = "runtime-secret";
+        assert!(is_authorized_client(
+            &headers(&[("authorization", "Bearer runtime-secret")]),
+            key
+        ));
+        assert!(is_authorized_client(
+            &headers(&[("authorization", "bearer runtime-secret")]),
+            key
+        ));
+        assert!(is_authorized_client(
+            &headers(&[("authorization", "BEARER   runtime-secret  ")]),
+            key
+        ));
+        // No whitespace after the scheme -> not a bearer credential.
+        assert!(!is_authorized_client(
+            &headers(&[("authorization", "Bearerruntime-secret")]),
+            key
+        ));
+        assert!(!is_authorized_client(
+            &headers(&[("authorization", "Basic runtime-secret")]),
+            key
+        ));
+        assert!(!is_authorized_client(&headers(&[]), key));
+    }
+
+    #[test]
+    fn authorizes_via_x_api_key_header() {
+        let key = "runtime-secret";
+        assert!(is_authorized_client(
+            &headers(&[("x-api-key", "runtime-secret")]),
+            key
+        ));
+        // x-api-key is NOT trimmed in TS (`headers.get` returns the raw value).
+        assert!(!is_authorized_client(
+            &headers(&[("x-api-key", " runtime-secret ")]),
+            key
+        ));
+        assert!(!is_authorized_client(
+            &headers(&[("x-api-key", "wrong")]),
+            key
+        ));
+    }
+
+    #[test]
+    fn bearer_takes_precedence_but_falls_back_to_x_api_key() {
+        let key = "runtime-secret";
+        // Wrong bearer + right x-api-key still authorizes (TS falls through).
+        assert!(is_authorized_client(
+            &headers(&[("authorization", "Bearer wrong"), ("x-api-key", key)]),
+            key
+        ));
+    }
+}
diff --git a/crates/proxy/src/lib.rs b/crates/proxy/src/lib.rs
new file mode 100644
index 000000000..247e8ee74
--- /dev/null
+++ b/crates/proxy/src/lib.rs
@@ -0,0 +1,8 @@
+//! cma-proxy - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod client_auth;
+pub mod local_bridge;
+pub mod model_fallback;
+pub mod pipeline;
+pub mod retry_loop;
+pub mod router;
+pub mod server;
diff --git a/crates/proxy/src/local_bridge.rs b/crates/proxy/src/local_bridge.rs
new file mode 100644
index 000000000..5ca7939cc
--- /dev/null
+++ b/crates/proxy/src/local_bridge.rs
@@ -0,0 +1,630 @@
+//! Port of `lib/local-bridge.ts` — the loopback HTTP façade in front of the
+//! runtime rotation proxy (spec 07 §10; ARCHITECTURE §6.13).
+//!
+//! Surfaces ONLY `/health`, `GET /v1/models`, and `POST /v1/responses`;
+//! everything else is a 404. Invariants (all frozen strings / stable codes):
+//! - bind host AND `runtimeBaseUrl` must both be loopback (egress guard —
+//!   runtime-proxy-02);
+//! - `runtimeClientApiKey` set ⇒ `requireAuth` MUST be true (otherwise the
+//!   bridge becomes an open local capability proxy);
+//! - inbound `x-api-key`/`cookie`/`proxy-authorization` never cross the
+//!   bridge; the inbound `authorization` is REPLACED by the runtime client
+//!   key (or dropped entirely when none is configured);
+//! - bearer auth via `cma_auth::local_client_tokens`;
+//! - usage ledger rows with `source: "local-bridge"`;
+//! - error codes: `local_bridge_unauthorized` (401),
+//!   `local_bridge_upstream_error` (502), `local_bridge_not_found` (404),
+//!   `local_bridge_error` (500).
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex as StdMutex};
+
+use bytes::Bytes;
+use futures::StreamExt;
+use futures::future::BoxFuture;
+use http::{HeaderMap, Request, Response};
+use http_body_util::combinators::BoxBody;
+use http_body_util::{BodyExt, Full, StreamBody};
+use hyper::body::Incoming;
+use serde_json::json;
+
+use cma_auth::local_client_tokens::{LocalClientTokenRecord, verify_local_client_bearer_token};
+use cma_core::json_io::stringify_compact;
+use cma_usage::ledger::append_usage_ledger_row;
+use cma_usage::types::UsageLedgerAppendInput;
+
+/// The bridge's response body type (buffered JSON or streamed upstream body).
+pub type BridgeBody = BoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>>;
+
+fn full_body(text: impl Into<Bytes>) -> BridgeBody {
+    Full::new(text.into())
+        .map_err(|never| match never {})
+        .boxed()
+}
+
+/// Injectable `verifyBearerToken` seam (TS default:
+/// `verifyLocalClientBearerToken`). Arguments: the raw `authorization`
+/// header value (if any) and `startedAt` (epoch ms).
+pub type VerifyBearerTokenFn = Arc<
+    dyn Fn(Option<String>, i64) -> BoxFuture<'static, std::io::Result<Option<LocalClientTokenRecord>>>
+        + Send
+        + Sync,
+>;
+
+/// TS `LocalBridgeOptions`.
+#[derive(Clone, Default)]
+pub struct LocalBridgeOptions {
+    /// Default `"127.0.0.1"`.
+    pub host: Option<String>,
+    /// Default `0` (ephemeral, OS-assigned).
+    pub port: Option<u16>,
+    /// REQUIRED; must be loopback.
+    pub runtime_base_url: String,
+    /// Replaces the TS `fetchImpl` seam.
+    pub fetch_client: Option<reqwest::Client>,
+    /// Default `true`.
+    pub require_auth: Option<bool>,
+    /// Default: [`verify_local_client_bearer_token`].
+    pub verify_bearer_token: Option<VerifyBearerTokenFn>,
+    /// Client API key for an auth-enabled runtime proxy (runtime-proxy-03).
+    pub runtime_client_api_key: Option<String>,
+}
+
+/// TS `LocalBridgeServer`.
+pub struct LocalBridgeServer {
+    /// Bind host in its RAW literal form (`"::1"`, not `"[::1]"`).
+    pub host: String,
+    pub port: u16,
+    /// `http://<urlHost>:<port>` with the BRACKETED IPv6 form.
+    pub base_url: String,
+    accept_task: tokio::task::JoinHandle<()>,
+    connections: Arc<StdMutex<Vec<tokio::task::AbortHandle>>>,
+    closed: AtomicBool,
+}
+
+impl std::fmt::Debug for LocalBridgeServer {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LocalBridgeServer")
+            .field("host", &self.host)
+            .field("port", &self.port)
+            .field("base_url", &self.base_url)
+            .finish()
+    }
+}
+
+impl LocalBridgeServer {
+    /// TS `close()` — stop accepting and destroy every tracked connection.
+    pub async fn close(&self) {
+        if self.closed.swap(true, Ordering::SeqCst) {
+            return;
+        }
+        self.accept_task.abort();
+        let handles: Vec<tokio::task::AbortHandle> = {
+            let mut connections = self
+                .connections
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            connections.drain(..).collect()
+        };
+        for handle in handles {
+            handle.abort();
+        }
+    }
+}
+
+impl Drop for LocalBridgeServer {
+    fn drop(&mut self) {
+        self.accept_task.abort();
+        let mut connections = self
+            .connections
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        for handle in connections.drain(..) {
+            handle.abort();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Host / header helpers (TS parity — the bridge has its OWN copies)
+// ---------------------------------------------------------------------------
+
+fn is_loopback_host(host: &str) -> bool {
+    let normalized = host.trim().to_lowercase();
+    // `new URL("http://[::1]:p").hostname` yields the bracketed form, so the
+    // IPv6 loopback runtimeBaseUrl must match here too.
+    normalized == "127.0.0.1"
+        || normalized == "localhost"
+        || normalized == "::1"
+        || normalized == "[::1]"
+}
+
+fn strip_ipv6_brackets(host: &str) -> &str {
+    let trimmed = host.trim();
+    if let Some(stripped) = trimmed.strip_prefix('[')
+        && let Some(stripped) = stripped.strip_suffix(']')
+    {
+        return stripped;
+    }
+    trimmed
+}
+
+fn to_bind_host(host: &str) -> String {
+    strip_ipv6_brackets(host).to_string()
+}
+
+fn to_url_host(host: &str) -> String {
+    let bare = strip_ipv6_brackets(host);
+    if bare.contains(':') {
+        format!("[{bare}]")
+    } else {
+        bare.to_string()
+    }
+}
+
+const HOP_BY_HOP_HEADERS: [&str; 10] = [
+    "connection",
+    "content-length",
+    "expect",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+];
+
+/// TS bridge-local `responseHeadersForClient` — drops hop-by-hop headers AND
+/// `content-encoding` (the HTTP client auto-decodes; keeping the header would
+/// corrupt the client's view). Deliberately does NOT strip anything else —
+/// this is the bridge's own filter, not the proxy's.
+fn response_headers_for_client(headers: &HeaderMap) -> Vec<(String, String)> {
+    let mut result: Vec<(String, String)> = Vec::new();
+    for (name, value) in headers {
+        let key = name.as_str();
+        if HOP_BY_HOP_HEADERS.contains(&key) || key == "content-encoding" {
+            continue;
+        }
+        let Ok(value) = value.to_str() else {
+            continue;
+        };
+        result.push((key.to_string(), value.to_string()));
+    }
+    result
+}
+
+/// TS `forwardHeaders(headers, runtimeClientApiKey)` — order matters.
+fn forward_headers(headers: &HeaderMap, runtime_client_api_key: Option<&str>) -> HeaderMap {
+    let mut result = headers.clone();
+    for name in HOP_BY_HOP_HEADERS {
+        result.remove(name);
+    }
+    result.remove("host");
+    // runtime-proxy-02: never forward inbound client credentials upstream.
+    result.remove("x-api-key");
+    result.remove("cookie");
+    result.remove("proxy-authorization");
+    // runtime-proxy-03: present the runtime proxy's client token — replace
+    // the (already validated) inbound Authorization, or strip it entirely.
+    match runtime_client_api_key.map(str::trim).filter(|key| !key.is_empty()) {
+        Some(key) => {
+            if let Ok(value) = http::header::HeaderValue::from_str(&format!("Bearer {key}")) {
+                result.insert("authorization", value);
+            }
+        }
+        None => {
+            result.remove("authorization");
+        }
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// JSON responses (stable error codes)
+// ---------------------------------------------------------------------------
+
+fn json_response(status: u16, content_type: &str, payload: &serde_json::Value) -> Response<BridgeBody> {
+    Response::builder()
+        .status(status)
+        .header("content-type", content_type)
+        .body(full_body(stringify_compact(payload)))
+        .expect("static response")
+}
+
+fn unauthorized_response() -> Response<BridgeBody> {
+    json_response(
+        401,
+        "application/json; charset=utf-8",
+        &json!({
+            "error": {
+                "message": "Local bridge rejected an unauthenticated request.",
+                "code": "local_bridge_unauthorized",
+            }
+        }),
+    )
+}
+
+fn upstream_error_response() -> Response<BridgeBody> {
+    json_response(
+        502,
+        "application/json; charset=utf-8",
+        &json!({
+            "error": {
+                "message": "Local bridge failed to reach the runtime proxy.",
+                "code": "local_bridge_upstream_error",
+            }
+        }),
+    )
+}
+
+fn not_found_response() -> Response<BridgeBody> {
+    json_response(
+        404,
+        "application/json",
+        &json!({
+            "error": {
+                "message": "Local bridge only accepts /health, /v1/models, and /v1/responses.",
+                "code": "local_bridge_not_found",
+            }
+        }),
+    )
+}
+
+/// TS handler-level 500 (`local_bridge_error`) — note the trailing `\n`.
+fn bridge_error_response() -> Response<BridgeBody> {
+    let payload = json!({
+        "error": {
+            "message": "Local bridge failed before forwarding the request.",
+            "code": "local_bridge_error",
+        }
+    });
+    Response::builder()
+        .status(500)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(full_body(format!("{}\n", stringify_compact(&payload))))
+        .expect("static response")
+}
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+
+struct BridgeShared {
+    runtime_base_url: String,
+    fetch_client: reqwest::Client,
+    require_auth: bool,
+    verify_bearer_token: VerifyBearerTokenFn,
+    runtime_client_api_key: Option<String>,
+}
+
+/// TS `startLocalBridge(options)`. Startup validation failures return the
+/// exact TS `Error` message strings.
+pub async fn start_local_bridge(options: LocalBridgeOptions) -> Result<LocalBridgeServer, String> {
+    let host = options
+        .host
+        .clone()
+        .unwrap_or_else(|| "127.0.0.1".to_string());
+    if !is_loopback_host(&host) {
+        return Err("Local bridge only supports loopback hosts.".to_string());
+    }
+    let bind_host = to_bind_host(&host);
+    let url_host = to_url_host(&host);
+    let runtime_base_url = options
+        .runtime_base_url
+        .trim()
+        .trim_end_matches('/')
+        .to_string();
+    if runtime_base_url.is_empty() {
+        return Err("Local bridge requires a runtimeBaseUrl.".to_string());
+    }
+    // Egress guard (runtime-proxy-02): the bridge forwards credentials to
+    // runtimeBaseUrl — it must be the loopback runtime proxy, never remote.
+    let runtime_host = match reqwest::Url::parse(&runtime_base_url) {
+        Ok(url) => url
+            .host_str()
+            .map(str::to_string)
+            .unwrap_or_default(),
+        Err(_) => {
+            return Err(format!(
+                "Local bridge runtimeBaseUrl is not a valid URL: {runtime_base_url}"
+            ));
+        }
+    };
+    if !is_loopback_host(&runtime_host) {
+        return Err(format!(
+            "Local bridge refuses to forward to non-loopback runtimeBaseUrl host \"{runtime_host}\". It must target the loopback runtime proxy."
+        ));
+    }
+    let port = options.port.unwrap_or(0);
+    let require_auth = options.require_auth.unwrap_or(true);
+    let runtime_client_api_key = options
+        .runtime_client_api_key
+        .as_deref()
+        .map(str::trim)
+        .filter(|key| !key.is_empty())
+        .map(str::to_string);
+    if runtime_client_api_key.is_some() && !require_auth {
+        // Security: key injection without inbound auth = open local
+        // capability proxy. Fail fast.
+        return Err(
+            "Local bridge requires requireAuth=true when runtimeClientApiKey is configured."
+                .to_string(),
+        );
+    }
+    let verify_bearer_token: VerifyBearerTokenFn =
+        options.verify_bearer_token.clone().unwrap_or_else(|| {
+            Arc::new(|authorization, started_at| {
+                Box::pin(async move {
+                    verify_local_client_bearer_token(authorization.as_deref(), Some(started_at))
+                        .await
+                })
+            })
+        });
+    let shared = Arc::new(BridgeShared {
+        runtime_base_url,
+        fetch_client: options.fetch_client.clone().unwrap_or_default(),
+        require_auth,
+        verify_bearer_token,
+        runtime_client_api_key,
+    });
+
+    let listener = tokio::net::TcpListener::bind((bind_host.as_str(), port))
+        .await
+        .map_err(|error| format!("listen {bind_host}:{port}: {error}"))?;
+    let resolved_port = listener
+        .local_addr()
+        .map(|address| address.port())
+        .unwrap_or(port);
+
+    let connections: Arc<StdMutex<Vec<tokio::task::AbortHandle>>> =
+        Arc::new(StdMutex::new(Vec::new()));
+    let accept_connections = Arc::clone(&connections);
+    let accept_shared = Arc::clone(&shared);
+    let accept_task = tokio::spawn(async move {
+        loop {
+            match listener.accept().await {
+                Ok((stream, _addr)) => {
+                    let connection_shared = Arc::clone(&accept_shared);
+                    let handle = tokio::spawn(async move {
+                        let io = hyper_util::rt::TokioIo::new(stream);
+                        let service = hyper::service::service_fn(move |req: Request<Incoming>| {
+                            let shared = Arc::clone(&connection_shared);
+                            async move {
+                                Ok::<_, std::convert::Infallible>(handle_request(shared, req).await)
+                            }
+                        });
+                        let _ = hyper::server::conn::http1::Builder::new()
+                            .serve_connection(io, service)
+                            .await;
+                    });
+                    let mut tracked = accept_connections
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    tracked.retain(|existing| !existing.is_finished());
+                    tracked.push(handle.abort_handle());
+                }
+                Err(_) => {
+                    // Accept errors are transient; keep serving (the TS
+                    // server had no error path here at all).
+                }
+            }
+        }
+    });
+
+    Ok(LocalBridgeServer {
+        host: bind_host,
+        port: resolved_port,
+        base_url: format!("http://{url_host}:{resolved_port}"),
+        accept_task,
+        connections,
+        closed: AtomicBool::new(false),
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Request handling
+// ---------------------------------------------------------------------------
+
+async fn handle_request(shared: Arc<BridgeShared>, req: Request<Incoming>) -> Response<BridgeBody> {
+    let method = req.method().clone();
+    let path = req.uri().path().to_string();
+
+    if method == http::Method::GET && path == "/health" {
+        return json_response(
+            200,
+            "application/json",
+            &json!({
+                "ok": true,
+                "service": "codex-multi-auth-local-bridge",
+                "runtimeBaseUrl": shared.runtime_base_url,
+            }),
+        );
+    }
+    let target_path = if method == http::Method::GET && path == "/v1/models" {
+        "/v1/models"
+    } else if method == http::Method::POST && path == "/v1/responses" {
+        "/v1/responses"
+    } else {
+        return not_found_response();
+    };
+    forward(shared, req, target_path).await
+}
+
+async fn forward(
+    shared: Arc<BridgeShared>,
+    req: Request<Incoming>,
+    target_path: &str,
+) -> Response<BridgeBody> {
+    let started_at = cma_core::utils::now_ms();
+    let (parts, body) = req.into_parts();
+
+    if shared.require_auth {
+        let authorization = parts
+            .headers
+            .get("authorization")
+            .and_then(|value| value.to_str().ok())
+            .map(str::to_string);
+        match (shared.verify_bearer_token)(authorization, started_at).await {
+            Ok(Some(_record)) => {}
+            Ok(None) => return unauthorized_response(),
+            // TS: a rejected verify promise escapes `forward` and hits the
+            // server-level handler → 500 `local_bridge_error`.
+            Err(_) => return bridge_error_response(),
+        }
+    }
+
+    // Body: fully buffered inbound bytes (NOT streamed upstream — TS parity).
+    let body_bytes: Option<Bytes> =
+        if parts.method == http::Method::GET || parts.method == http::Method::HEAD {
+            None
+        } else {
+            match body.collect().await {
+                Ok(collected) => Some(collected.to_bytes()),
+                Err(_) => return bridge_error_response(),
+            }
+        };
+
+    let operation = if target_path == "/v1/models" {
+        "models"
+    } else {
+        "responses"
+    };
+    let target_url = format!("{}{}", shared.runtime_base_url, target_path);
+    let mut request_builder = shared
+        .fetch_client
+        .request(parts.method.clone(), &target_url)
+        .headers(forward_headers(
+            &parts.headers,
+            shared.runtime_client_api_key.as_deref(),
+        ));
+    if let Some(bytes) = body_bytes {
+        request_builder = request_builder.body(bytes);
+    }
+    let upstream = match request_builder.send().await {
+        Ok(upstream) => upstream,
+        Err(_) => {
+            let _ = append_usage_ledger_row(&UsageLedgerAppendInput {
+                source: Some("local-bridge".to_string()),
+                operation: Some(operation.to_string()),
+                outcome: Some("failure".to_string()),
+                status_code: Some(502.0),
+                error_code: Some("local_bridge_upstream_error".to_string()),
+                duration_ms: Some((cma_core::utils::now_ms() - started_at) as f64),
+                ..Default::default()
+            })
+            .await;
+            return upstream_error_response();
+        }
+    };
+
+    let status = upstream.status().as_u16();
+    let ok = upstream.status().is_success();
+    let _ = append_usage_ledger_row(&UsageLedgerAppendInput {
+        source: Some("local-bridge".to_string()),
+        operation: Some(operation.to_string()),
+        outcome: Some(if ok { "success" } else { "failure" }.to_string()),
+        status_code: Some(status as f64),
+        duration_ms: Some((cma_core::utils::now_ms() - started_at) as f64),
+        ..Default::default()
+    })
+    .await;
+
+    // Respond with upstream status, filtered headers, and the STREAMED body
+    // (SSE flows through).
+    let client_headers = response_headers_for_client(upstream.headers());
+    let stream = upstream.bytes_stream().map(|item| {
+        item.map(hyper::body::Frame::data)
+            .map_err(|error| -> Box<dyn std::error::Error + Send + Sync> { Box::new(error) })
+    });
+    let body: BridgeBody = BodyExt::boxed(StreamBody::new(stream));
+    let mut builder = Response::builder().status(status);
+    for (name, value) in client_headers {
+        builder = builder.header(name, value);
+    }
+    builder.body(body).unwrap_or_else(|_| bridge_error_response())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.append(
+                name.parse::<http::header::HeaderName>().unwrap(),
+                http::header::HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn forward_headers_replace_authorization_with_runtime_key() {
+        let inbound = headers(&[
+            ("authorization", "Bearer cma_local_token"),
+            ("x-api-key", "leak"),
+            ("cookie", "sid=1"),
+            ("proxy-authorization", "Basic x"),
+            ("host", "127.0.0.1:9"),
+            ("connection", "keep-alive"),
+            ("content-type", "application/json"),
+        ]);
+        let forwarded = forward_headers(&inbound, Some("  runtime-key  "));
+        assert_eq!(forwarded.get("authorization").unwrap(), "Bearer runtime-key");
+        assert!(forwarded.get("x-api-key").is_none());
+        assert!(forwarded.get("cookie").is_none());
+        assert!(forwarded.get("proxy-authorization").is_none());
+        assert!(forwarded.get("host").is_none());
+        assert!(forwarded.get("connection").is_none());
+        assert_eq!(forwarded.get("content-type").unwrap(), "application/json");
+    }
+
+    #[test]
+    fn forward_headers_drop_authorization_without_runtime_key() {
+        let inbound = headers(&[("authorization", "Bearer cma_local_token")]);
+        assert!(forward_headers(&inbound, None).get("authorization").is_none());
+        // Blank key behaves like no key.
+        assert!(
+            forward_headers(&inbound, Some("   "))
+                .get("authorization")
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn response_headers_drop_hop_by_hop_and_content_encoding_only() {
+        let upstream = headers(&[
+            ("content-type", "text/event-stream"),
+            ("content-encoding", "gzip"),
+            ("transfer-encoding", "chunked"),
+            ("x-request-id", "req_1"),
+            // The bridge does NOT strip private account headers — that is the
+            // runtime proxy's job (TS parity).
+            ("x-codex-multi-auth-account-id", "acc_1"),
+        ]);
+        let mut filtered = response_headers_for_client(&upstream);
+        filtered.sort();
+        assert_eq!(
+            filtered,
+            vec![
+                ("content-type".to_string(), "text/event-stream".to_string()),
+                (
+                    "x-codex-multi-auth-account-id".to_string(),
+                    "acc_1".to_string()
+                ),
+                ("x-request-id".to_string(), "req_1".to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn loopback_matrix_includes_bracketed_ipv6() {
+        for host in ["127.0.0.1", "localhost", "::1", "[::1]"] {
+            assert!(is_loopback_host(host), "{host}");
+        }
+        assert!(!is_loopback_host("example.com"));
+        assert!(!is_loopback_host("0.0.0.0"));
+    }
+}
diff --git a/crates/proxy/src/model_fallback.rs b/crates/proxy/src/model_fallback.rs
new file mode 100644
index 000000000..3b556311b
--- /dev/null
+++ b/crates/proxy/src/model_fallback.rs
@@ -0,0 +1,466 @@
+//! Unsupported-model traversal + fallback chains (index.ts §5.5.3 step 3).
+//!
+//! Port of the model-fallback half of the `index.ts` custom-fetch state
+//! machine (spec 13 §5.5.3, gotchas 9–11):
+//!
+//! - the **spark** forced-fallback rule (`gpt-5.3-codex-spark`, exact match
+//!   OR substring) which additionally SKIPS the try-other-accounts-first
+//!   traversal;
+//! - the **gpt-5.5 family** forced-fallback rule (exact-match list of 6 ids
+//!   incl. dateless, dashed-date and compact-date variants, pro and
+//!   non-pro);
+//! - the decision ladder: try other accounts first → resolve fallback model
+//!   → strict block → bookkeeping-only;
+//! - fallback body reconstruction: `{ ...transformedBody, model }` when a
+//!   parsed body exists, else re-parse the raw request body and override
+//!   `model`, else `{ "model": <fallback> }` alone (gotcha 10);
+//! - `previousModel` defaulting to `"gpt-5.3-codex"` (gotcha 11).
+//!
+//! Everything here is pure — the pipeline applies the side effects
+//! (entitlement blocks, capability records, token refunds, metrics).
+
+use cma_core::schemas::plugin_config::FallbackChain;
+use cma_request::error_classification::{
+    ResolveUnsupportedCodexFallbackOptions, UnsupportedCodexModelInfo,
+    resolve_unsupported_codex_fallback_model,
+};
+use serde_json::{Map, Value};
+
+/// The spark model id (spec 13 §5.5.3): forced fallback, skips the
+/// try-other-accounts-first traversal because spark is commonly unavailable
+/// on non-Pro/Business workspaces.
+pub const SPARK_MODEL: &str = "gpt-5.3-codex-spark";
+
+/// The exact-match gpt-5.5 forced-fallback list (spec 13 gotcha 9). Order
+/// matches the TS `||` chain in `index.ts`.
+pub const GPT55_FORCED_FALLBACK_MODELS: [&str; 6] = [
+    "gpt-5.5",
+    "gpt-5.5-pro",
+    "gpt-5.5-2026-04-23",
+    "gpt-5.5-pro-2026-04-23",
+    "gpt-5.5-20260423",
+    "gpt-5.5-pro-20260423",
+];
+
+/// `previousModel` default when `model` was undefined at fallback time
+/// (spec 13 gotcha 11).
+pub const DEFAULT_PREVIOUS_MODEL: &str = "gpt-5.3-codex";
+
+/// TS `shouldForceSparkFallback` — exact match OR substring on the
+/// lowercased blocked model name.
+pub fn should_force_spark_fallback(blocked_model_lower: &str) -> bool {
+    blocked_model_lower == SPARK_MODEL || blocked_model_lower.contains(SPARK_MODEL)
+}
+
+/// TS `shouldForceGpt55Fallback` — exact-match only against the 6-id list.
+pub fn should_force_gpt55_fallback(blocked_model_lower: &str) -> bool {
+    GPT55_FORCED_FALLBACK_MODELS.contains(&blocked_model_lower)
+}
+
+/// Inputs to [`plan_unsupported_model`] — everything the §5.5.3 step-3
+/// ladder reads.
+pub struct UnsupportedModelContext<'a> {
+    /// `getUnsupportedCodexModelInfo(errorBody)` output.
+    pub info: &'a UnsupportedCodexModelInfo,
+    /// The raw error body (needed by the chain resolver).
+    pub error_body: &'a Value,
+    /// The request's current `model` (post any earlier fallback swap).
+    pub model: Option<&'a str>,
+    /// `attempted.size < max(1, accountCount)` at decision time.
+    pub has_remaining_accounts: bool,
+    /// Config: `unsupportedCodexPolicy === "fallback"`.
+    pub fallback_on_unsupported_codex_model: bool,
+    /// Config: `fallbackToGpt52OnUnsupportedGpt53`.
+    pub fallback_to_gpt52_on_unsupported_gpt53: bool,
+    /// Config: `unsupportedCodexFallbackChain` (custom chain overrides).
+    pub custom_chain: Option<&'a FallbackChain>,
+    /// Models already attempted via fallback restarts (outer-loop set).
+    pub attempted_models: &'a [String],
+}
+
+/// The §5.5.3 step-3 decision. Side effects are listed per variant in the
+/// order the TS applied them.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum UnsupportedModelPlan {
+    /// Error body is not an unsupported-model error: fall through to the
+    /// remaining `!response.ok` ladder.
+    NotUnsupported,
+    /// Rotate to the next account before considering fallback (entitlements
+    /// differ per account/workspace). Effects: `markBlocked(unsupported-model)`
+    /// + `recordUnsupported` + refund + `recordFailure` (both stores) +
+    ///   `forgetSession` + `lastSwitchReason = "rotation"` + set
+    ///   `retryNextAccountBeforeFallback` and break the inner loop.
+    TryOtherAccountsFirst { blocked_model: String },
+    /// Swap models and restart the FULL account traversal. Effects:
+    /// add both models to the attempted set, `markBlocked(previous)` +
+    /// `recordUnsupported(previous)`, refund against the PREVIOUS
+    /// family/model, rebuild the body, toast, set
+    /// `restartAccountTraversalWithFallback`.
+    Fallback {
+        blocked_model: String,
+        /// `model ?? "gpt-5.3-codex"` (gotcha 11).
+        previous_model: String,
+        fallback_model: String,
+    },
+    /// Strict policy blocked automatic fallback. Effects: `markBlocked` +
+    /// `recordUnsupported` + toast; execution FALLS THROUGH to the generic
+    /// error return.
+    StrictBlock { blocked_model: String },
+    /// Unsupported + fallback allowed + no remaining accounts + no fallback
+    /// model resolved: `markBlocked` + `recordUnsupported` only, then fall
+    /// through to the generic error return.
+    BookkeepOnly { blocked_model: String },
+}
+
+/// The §5.5.3 step-3 ladder, verbatim ordering:
+///
+/// 1. not unsupported → [`UnsupportedModelPlan::NotUnsupported`];
+/// 2. unsupported AND accounts remain AND NOT spark-forced →
+///    [`UnsupportedModelPlan::TryOtherAccountsFirst`];
+/// 3. `resolveUnsupportedCodexFallbackModel` (with
+///    `fallbackOnUnsupportedCodexModel = allowUnsupportedFallback`) →
+///    [`UnsupportedModelPlan::Fallback`];
+/// 4. no fallback allowed → [`UnsupportedModelPlan::StrictBlock`];
+/// 5. else → [`UnsupportedModelPlan::BookkeepOnly`].
+pub fn plan_unsupported_model(ctx: &UnsupportedModelContext<'_>) -> UnsupportedModelPlan {
+    if !ctx.info.is_unsupported {
+        return UnsupportedModelPlan::NotUnsupported;
+    }
+
+    // blockedModel = info.unsupportedModel ?? model ?? "requested model"
+    let blocked_model = ctx
+        .info
+        .unsupported_model
+        .clone()
+        .or_else(|| ctx.model.map(str::to_string))
+        .unwrap_or_else(|| "requested model".to_string());
+    let blocked_model_lower = blocked_model.to_lowercase();
+
+    let force_spark = should_force_spark_fallback(&blocked_model_lower);
+    let force_gpt55 = should_force_gpt55_fallback(&blocked_model_lower);
+    let allow_unsupported_fallback =
+        ctx.fallback_on_unsupported_codex_model || force_spark || force_gpt55;
+
+    // Try other accounts first (entitlements differ per account/workspace).
+    // Spark is special-cased to skip traversal (spec 13 gotcha 9).
+    if ctx.has_remaining_accounts && !force_spark {
+        return UnsupportedModelPlan::TryOtherAccountsFirst { blocked_model };
+    }
+
+    let fallback_model =
+        resolve_unsupported_codex_fallback_model(&ResolveUnsupportedCodexFallbackOptions {
+            requested_model: ctx.model,
+            error_body: ctx.error_body,
+            attempted_models: ctx.attempted_models,
+            fallback_on_unsupported_codex_model: allow_unsupported_fallback,
+            fallback_to_gpt52_on_unsupported_gpt53: ctx.fallback_to_gpt52_on_unsupported_gpt53,
+            custom_chain: ctx.custom_chain,
+        });
+
+    if let Some(fallback_model) = fallback_model {
+        let previous_model = ctx
+            .model
+            .map(str::to_string)
+            .unwrap_or_else(|| DEFAULT_PREVIOUS_MODEL.to_string());
+        return UnsupportedModelPlan::Fallback {
+            blocked_model,
+            previous_model,
+            fallback_model,
+        };
+    }
+
+    if !allow_unsupported_fallback {
+        return UnsupportedModelPlan::StrictBlock { blocked_model };
+    }
+
+    UnsupportedModelPlan::BookkeepOnly { blocked_model }
+}
+
+/// Fallback body reconstruction (spec 13 gotchas 10–11).
+///
+/// - `transformed_body` is a JSON object → `{ ...transformedBody, model }`;
+/// - else parse `raw_body` as JSON and override `model` (non-object parse
+///   results fall through);
+/// - parse failure → `{ "model": <fallback> }` alone.
+///
+/// Returns `(new_transformed_body, serialized_string)` — the serialized form
+/// is what goes on the wire (TS `JSON.stringify`, compact).
+pub fn rebuild_body_with_model(
+    transformed_body: Option<&Value>,
+    raw_body: &[u8],
+    fallback_model: &str,
+) -> (Value, String) {
+    let with_model = |mut map: Map<String, Value>| -> Value {
+        map.insert(
+            "model".to_string(),
+            Value::String(fallback_model.to_string()),
+        );
+        Value::Object(map)
+    };
+
+    let rebuilt = match transformed_body {
+        Some(Value::Object(map)) => with_model(map.clone()),
+        _ => match serde_json::from_slice::<Value>(raw_body) {
+            Ok(Value::Object(map)) => with_model(map),
+            // Parse failure (or non-object JSON): `{ model }` alone.
+            _ => {
+                let mut map = Map::new();
+                map.insert(
+                    "model".to_string(),
+                    Value::String(fallback_model.to_string()),
+                );
+                Value::Object(map)
+            }
+        },
+    };
+    let serialized = serde_json::to_string(&rebuilt).unwrap_or_else(|_| {
+        // Unreachable for Value inputs; keep the wire contract anyway.
+        format!("{{\"model\":\"{fallback_model}\"}}")
+    });
+    (rebuilt, serialized)
+}
+
+/// FROZEN user-visible strings for the fallback paths (spec 13 §5.5.3;
+/// gotcha 29 — byte-for-byte contract).
+pub fn fallback_last_error(previous_model: &str, fallback_model: &str) -> String {
+    format!("Model fallback: {previous_model} -> {fallback_model}")
+}
+
+/// Toast shown when a fallback model is applied.
+pub fn fallback_toast_message(previous_model: &str, fallback_model: &str) -> String {
+    format!(
+        "Model {previous_model} is not available for this account. Retrying with {fallback_model}."
+    )
+}
+
+/// Toast shown when strict policy blocks automatic fallback.
+pub fn strict_block_toast_message(blocked_model: &str) -> String {
+    format!(
+        "Model {blocked_model} is not available for this account. Strict policy blocked automatic fallback."
+    )
+}
+
+/// `lastError` for the rotate-before-fallback path.
+pub fn unsupported_rotation_last_error(account_number: i64, blocked_model: &str) -> String {
+    format!("Unsupported model on account {account_number}: {blocked_model}")
+}
+
+/// `lastError` for the strict-block path.
+pub fn strict_block_last_error(blocked_model: &str) -> String {
+    format!("Unsupported model (strict): {blocked_model}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_request::error_classification::get_unsupported_codex_model_info;
+    use serde_json::json;
+
+    fn unsupported_body(model: &str) -> Value {
+        json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": format!(
+                    "The '{model}' model is not supported when using Codex with a ChatGPT account."
+                ),
+            }
+        })
+    }
+
+    fn ctx<'a>(
+        info: &'a UnsupportedCodexModelInfo,
+        error_body: &'a Value,
+        model: Option<&'a str>,
+        has_remaining_accounts: bool,
+        fallback_enabled: bool,
+        attempted: &'a [String],
+    ) -> UnsupportedModelContext<'a> {
+        UnsupportedModelContext {
+            info,
+            error_body,
+            model,
+            has_remaining_accounts,
+            fallback_on_unsupported_codex_model: fallback_enabled,
+            fallback_to_gpt52_on_unsupported_gpt53: true,
+            custom_chain: None,
+            attempted_models: attempted,
+        }
+    }
+
+    #[test]
+    fn not_unsupported_error_falls_through() {
+        let body = json!({"error": {"message": "boom"}});
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted: Vec<String> = vec![];
+        let plan = plan_unsupported_model(&ctx(
+            &info,
+            &body,
+            Some("gpt-5.3-codex"),
+            true,
+            true,
+            &attempted,
+        ));
+        assert_eq!(plan, UnsupportedModelPlan::NotUnsupported);
+    }
+
+    #[test]
+    fn tries_other_accounts_before_fallback_when_accounts_remain() {
+        let body = unsupported_body("gpt-5.3-codex");
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted = vec!["gpt-5.3-codex".to_string()];
+        let plan = plan_unsupported_model(&ctx(
+            &info,
+            &body,
+            Some("gpt-5.3-codex"),
+            true,
+            true,
+            &attempted,
+        ));
+        assert!(matches!(
+            plan,
+            UnsupportedModelPlan::TryOtherAccountsFirst { ref blocked_model }
+                if blocked_model == "gpt-5.3-codex"
+        ));
+    }
+
+    #[test]
+    fn spark_skips_account_traversal_even_with_accounts_remaining() {
+        // Spec 13 gotcha 9: spark goes straight to fallback.
+        let body = unsupported_body(SPARK_MODEL);
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted = vec![SPARK_MODEL.to_string()];
+        let plan = plan_unsupported_model(&ctx(
+            &info,
+            &body,
+            Some(SPARK_MODEL),
+            true,
+            false,
+            &attempted,
+        ));
+        match plan {
+            UnsupportedModelPlan::Fallback {
+                blocked_model,
+                previous_model,
+                fallback_model,
+            } => {
+                assert_eq!(blocked_model, SPARK_MODEL);
+                assert_eq!(previous_model, SPARK_MODEL);
+                assert_ne!(fallback_model, SPARK_MODEL);
+            }
+            other => panic!("expected Fallback, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn spark_substring_matches_force_fallback() {
+        assert!(should_force_spark_fallback("openai/gpt-5.3-codex-spark"));
+        assert!(should_force_spark_fallback(SPARK_MODEL));
+        assert!(!should_force_spark_fallback("gpt-5.3-codex"));
+    }
+
+    #[test]
+    fn gpt55_forced_fallback_list_is_exact_match_only() {
+        for id in GPT55_FORCED_FALLBACK_MODELS {
+            assert!(should_force_gpt55_fallback(id), "{id} must force fallback");
+        }
+        // Exact-match only: substrings and other variants do NOT force.
+        assert!(!should_force_gpt55_fallback("gpt-5.5-something"));
+        assert!(!should_force_gpt55_fallback("openai/gpt-5.5"));
+        assert!(!should_force_gpt55_fallback("gpt-5.4"));
+    }
+
+    #[test]
+    fn gpt55_forces_fallback_under_strict_policy() {
+        // Port of index.test.ts "forces GPT-5.5 fallback to gpt-5.4 even when
+        // strict policy disables generic unsupported fallback".
+        let body = unsupported_body("gpt-5.5");
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted = vec!["gpt-5.5".to_string()];
+        let plan = plan_unsupported_model(&ctx(
+            &info,
+            &body,
+            Some("gpt-5.5"),
+            false,
+            false,
+            &attempted,
+        ));
+        assert!(
+            matches!(plan, UnsupportedModelPlan::Fallback { .. }),
+            "expected forced fallback, got {plan:?}"
+        );
+    }
+
+    #[test]
+    fn strict_policy_blocks_generic_fallback() {
+        let body = unsupported_body("gpt-5.3-codex");
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted = vec!["gpt-5.3-codex".to_string()];
+        let plan = plan_unsupported_model(&ctx(
+            &info,
+            &body,
+            Some("gpt-5.3-codex"),
+            false,
+            false,
+            &attempted,
+        ));
+        assert!(matches!(plan, UnsupportedModelPlan::StrictBlock { .. }));
+    }
+
+    #[test]
+    fn previous_model_defaults_to_gpt53_codex() {
+        // Gotcha 11: previousModel defaults when model was undefined.
+        let body = unsupported_body("gpt-5.3-codex");
+        let info = get_unsupported_codex_model_info(&body);
+        let attempted: Vec<String> = vec![];
+        let plan = plan_unsupported_model(&ctx(&info, &body, None, false, true, &attempted));
+        if let UnsupportedModelPlan::Fallback { previous_model, .. } = plan {
+            assert_eq!(previous_model, DEFAULT_PREVIOUS_MODEL);
+        } else {
+            panic!("expected Fallback, got {plan:?}");
+        }
+    }
+
+    #[test]
+    fn rebuild_body_prefers_transformed_body() {
+        let transformed = json!({"model": "gpt-5.3-codex", "stream": true, "input": []});
+        let (value, serialized) =
+            rebuild_body_with_model(Some(&transformed), b"ignored", "gpt-5.2-codex");
+        assert_eq!(value["model"], "gpt-5.2-codex");
+        assert_eq!(value["stream"], true);
+        assert!(serialized.contains("\"gpt-5.2-codex\""));
+    }
+
+    #[test]
+    fn rebuild_body_parses_raw_body_when_no_transformed_body() {
+        let raw = br#"{"model":"gpt-5.3-codex","instructions":"keep me"}"#;
+        let (value, _) = rebuild_body_with_model(None, raw, "gpt-5.2-codex");
+        assert_eq!(value["model"], "gpt-5.2-codex");
+        assert_eq!(value["instructions"], "keep me");
+    }
+
+    #[test]
+    fn rebuild_body_parse_failure_sends_model_alone() {
+        // Gotcha 10: parse failure → `{ "model": <fallback> }` alone.
+        let (value, serialized) = rebuild_body_with_model(None, b"not json", "gpt-5.2-codex");
+        assert_eq!(value, json!({"model": "gpt-5.2-codex"}));
+        assert_eq!(serialized, "{\"model\":\"gpt-5.2-codex\"}");
+    }
+
+    #[test]
+    fn frozen_strings() {
+        assert_eq!(fallback_last_error("a", "b"), "Model fallback: a -> b");
+        assert_eq!(
+            fallback_toast_message("a", "b"),
+            "Model a is not available for this account. Retrying with b."
+        );
+        assert_eq!(
+            strict_block_toast_message("m"),
+            "Model m is not available for this account. Strict policy blocked automatic fallback."
+        );
+        assert_eq!(
+            unsupported_rotation_last_error(2, "m"),
+            "Unsupported model on account 2: m"
+        );
+        assert_eq!(strict_block_last_error("m"), "Unsupported model (strict): m");
+    }
+}
diff --git a/crates/proxy/src/pipeline.rs b/crates/proxy/src/pipeline.rs
new file mode 100644
index 000000000..56d312893
--- /dev/null
+++ b/crates/proxy/src/pipeline.rs
@@ -0,0 +1,3531 @@
+//! THE merged per-request rotation pipeline (ARCHITECTURE §3 row 1).
+//!
+//! One pipeline implements the UNION of the two TS rotation loops:
+//! - `index.ts` `auth.loader` custom fetch (spec 13 §5 — AUTHORITATIVE for
+//!   the request loop; all 29 gotchas of §15 apply), and
+//! - the request-loop half of `lib/runtime-rotation-proxy.ts` (spec 04 §9 —
+//!   authoritative for the HTTP surface: status mapping, stable error
+//!   codes, header scrubbing).
+//!
+//! Invoked by (a) the proxy HTTP surface (`server.rs`), (b) the wrapper's
+//! in-process client, (c) the local bridge (via the proxy). The server owns
+//! client auth, routing, the 64 MiB cap and the models/thread-goal routes;
+//! this module owns everything that happens to a `/responses` request after
+//! `RequestContext` construction, INCLUDING the usage-ledger record for the
+//! responses operation (the server must not double-record it).
+//!
+//! Stage order (spec 13 §5 ∪ spec 04):
+//! upstream-URL join → response-continuation injection → policy gate
+//! (FAIL-OPEN) → pool-exhaustion/server-burst fast-fail → outbound attempt
+//! budget (cap 6) → account selection (pin > sequential > affinity > hybrid,
+//! capability/policy/sticky boosts) → token refresh (auth-failure removal
+//! policy) → identity/entitlement gates → preemptive quota deferral → local
+//! token bucket → upstream fetch → status ladder (context overflow →
+//! unsupported-model traversal + fallback chains → workspace rotation → 403
+//! entitlement → 5xx rotation → 429 short-retry MARK-BEFORE-SLEEP → 401
+//! token-invalidation no-rotate + 300 s cooldown) → stream failover (cap 1,
+//! only before first byte) → empty-response retries → terminal synthetic
+//! bodies → session-affinity writes → metrics/observability.
+//!
+//! Counters SURVIVE model-fallback restarts (spec 13 gotcha 7). The local
+//! token bucket is per-process and never persisted (gotcha 6); every
+//! cooldown/rate-limit mark is followed by a debounced save (spec 04
+//! gotcha 19; the `record_success` "healed" seam schedules its own save via
+//! `SharedAccountManager`).
+
+use std::collections::{HashMap, HashSet};
+use std::sync::atomic::{AtomicI64, Ordering};
+use std::sync::{Arc, Mutex as StdMutex};
+
+use cma_accounts::capability_policy::CapabilityPolicyStore;
+use cma_accounts::entitlement_cache::{
+    EntitlementAccountRef, EntitlementBlockReason, EntitlementCache,
+    resolve_entitlement_account_key,
+};
+use cma_accounts::manager::ManagedAccount;
+use cma_accounts::manager_persistence::{
+    AccountLabelSource, SAVE_DEBOUNCE_DEFAULT_MS, SharedAccountManager, format_account_label,
+};
+use cma_accounts::rate_limits::{format_wait_time, parse_rate_limit_reason};
+use cma_accounts::session_affinity::SessionAffinityStore;
+use cma_config::getters;
+use cma_core::schemas::plugin_config::FallbackChain;
+use cma_core::constants::ACCOUNT_LIMITS;
+use cma_core::logger::{log_info, log_warn};
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{CooldownReason, RateLimitReason, SwitchReason};
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_core::token_utils::{
+    ResolveRuntimeRequestIdentityInput, resolve_runtime_request_identity,
+};
+use cma_core::utils::now_ms;
+use cma_quota::preemptive_scheduler::{PreemptiveQuotaScheduler, read_quota_scheduler_snapshot};
+use cma_quota::runtime_policy::{
+    EvaluateRuntimePolicyInput, RuntimePolicyAccount, RuntimePolicyDecision,
+    RuntimeUsageRecordInput, RuntimeUsageRecorder, RuntimeUsageRecorderOptions,
+    create_runtime_usage_recorder, evaluate_runtime_policy, load_runtime_policy_state,
+};
+use cma_request::attempt_budget::{
+    OutboundRequestAttemptBudgetParams, cap_stream_failover_max,
+    compute_outbound_request_attempt_budget,
+};
+use cma_request::context_overflow::handle_context_overflow;
+use cma_request::error_classification::{
+    get_unsupported_codex_model_info, is_workspace_disabled_error,
+};
+use cma_request::failover_config::{parse_env_int, parse_failover_mode};
+use cma_request::failure_policy::{
+    FailoverMode, FailurePolicyInput, FailurePolicyOverrides, FailureKind,
+    evaluate_failure_policy,
+};
+use cma_request::fetch_helpers::{ErrorHandlingOptions, handle_error_response};
+use cma_request::fetch_helpers::handle_success_response;
+use cma_request::model_map::get_model_family;
+use cma_request::rate_limit_backoff::{
+    RateLimitBackoffOverrides, configure_rate_limit_backoff,
+    configured_rate_limit_short_retry_threshold_ms, get_rate_limit_backoff,
+    reset_rate_limit_backoff,
+};
+use cma_request::rate_limit_decision::{
+    build_token_invalidation_body, get_quota_near_exhaustion_wait_ms,
+    is_token_invalidation_error, normalize_exhaustion_status,
+};
+use cma_request::resilience::{
+    AdaptiveFailoverAccount, arm_pool_exhaustion_cooldown,
+    build_adaptive_stream_failover_candidate_order, clear_pool_exhaustion_cooldown,
+    clear_server_burst_cooldown, get_pool_exhaustion_cooldown_remaining,
+    get_server_burst_cooldown_remaining, record_server_burst_failure,
+};
+use cma_request::response_handler::{
+    BodyStream, ConvertSseOptions, StreamResponse, is_empty_response,
+};
+use cma_request::response_metadata::parse_retry_after_hint_ms;
+use cma_request::stream_failover::{StreamFailoverOptions, with_streaming_failover};
+use cma_request::wait_utils::abortable_sleep;
+use cma_rotation::selector::add_jitter;
+use cma_runtime::observability::{
+    RuntimeMetricsSnapshot, mutate_runtime_observability_snapshot,
+    record_runtime_account_recovery, record_runtime_pool_exhaustion,
+};
+use cma_runtime::rotation::account_selection::{ChooseAccountParams, choose_account};
+use cma_runtime::rotation::proxy_state::{RotationProxyState, recover_stale_runtime_state};
+use cma_runtime::rotation::server_types::{
+    ExhaustionReason, RequestContext, SchedulingStrategy,
+};
+use cma_runtime::rotation::token_refresh::{
+    DEFAULT_AUTH_FAILURE_COOLDOWN_MS, EnsureFreshAccessTokenParams,
+    EnsureFreshAccessTokenResult, apply_monotonic_auth_cooldown, ensure_fresh_access_token,
+};
+use cma_runtime::toast::{ToastVariant, show_runtime_toast};
+use cma_rotation::routing_mutex::RoutingMutexMode;
+use cma_usage::types::{UsageLedgerOperation, UsageLedgerOutcome, UsageLedgerSource};
+use futures::StreamExt;
+use http::HeaderMap;
+use http::header::HeaderValue;
+use serde_json::Value;
+
+use crate::model_fallback::{
+    self, UnsupportedModelContext, UnsupportedModelPlan, plan_unsupported_model,
+    rebuild_body_with_model,
+};
+use crate::retry_loop::{
+    self, OutboundAttemptBudget, RateLimit429Decision, RetryCounters, decide_rate_limit_429,
+    error_message_body, synthetic_json_headers,
+};
+
+/// `MIN_BACKOFF_MS` (spec 13 §10) — floor for network/server same-account
+/// retry delays and the short-429 sleep.
+pub const MIN_BACKOFF_MS: i64 = 100;
+
+/// Stream-failover defaults by mode (spec 13 §3). The effective max is
+/// clamped to 1 by `cap_stream_failover_max` (gotcha 1).
+const STREAM_FAILOVER_MAX_BY_MODE: [(FailoverMode, i64); 3] = [
+    (FailoverMode::Aggressive, 1),
+    (FailoverMode::Balanced, 2),
+    (FailoverMode::Conservative, 2),
+];
+const STREAM_FAILOVER_SOFT_TIMEOUT_BY_MODE: [(FailoverMode, i64); 3] = [
+    (FailoverMode::Aggressive, 10_000),
+    (FailoverMode::Balanced, 15_000),
+    (FailoverMode::Conservative, 20_000),
+];
+
+fn mode_lookup(table: &[(FailoverMode, i64); 3], mode: FailoverMode) -> i64 {
+    table
+        .iter()
+        .find(|(m, _)| *m == mode)
+        .map(|(_, v)| *v)
+        .unwrap_or(table[1].1)
+}
+
+// ===========================================================================
+// RuntimeMetrics (spec 13 §3)
+// ===========================================================================
+
+/// TS `RuntimeMetrics` — per-process request metrics mirrored into the
+/// observability snapshot on every state transition.
+#[derive(Debug, Clone)]
+pub struct RuntimeMetrics {
+    pub started_at: i64,
+    pub total_requests: i64,
+    pub successful_requests: i64,
+    pub failed_requests: i64,
+    pub responses_requests: i64,
+    pub auth_refresh_requests: i64,
+    pub diagnostic_probe_requests: i64,
+    pub outbound_request_attempt_budget: Option<i64>,
+    pub outbound_request_attempts_consumed: i64,
+    pub request_attempt_budget_exhaustions: i64,
+    pub pool_exhaustion_fast_fails: i64,
+    pub server_burst_fast_fails: i64,
+    pub rate_limited_responses: i64,
+    pub server_errors: i64,
+    pub network_errors: i64,
+    pub user_aborts: i64,
+    pub auth_refresh_failures: i64,
+    pub empty_response_retries: i64,
+    pub account_rotations: i64,
+    pub same_account_retries: i64,
+    pub stream_failover_attempts: i64,
+    pub stream_failover_candidates_considered: i64,
+    pub last_stream_failover_candidate_count: i64,
+    pub stream_failover_recoveries: i64,
+    pub stream_failover_cross_account_recoveries: i64,
+    pub cumulative_latency_ms: i64,
+    pub last_request_at: Option<i64>,
+    pub last_error: Option<String>,
+}
+
+impl RuntimeMetrics {
+    pub fn new(started_at: i64) -> Self {
+        Self {
+            started_at,
+            total_requests: 0,
+            successful_requests: 0,
+            failed_requests: 0,
+            responses_requests: 0,
+            auth_refresh_requests: 0,
+            diagnostic_probe_requests: 0,
+            outbound_request_attempt_budget: None,
+            outbound_request_attempts_consumed: 0,
+            request_attempt_budget_exhaustions: 0,
+            pool_exhaustion_fast_fails: 0,
+            server_burst_fast_fails: 0,
+            rate_limited_responses: 0,
+            server_errors: 0,
+            network_errors: 0,
+            user_aborts: 0,
+            auth_refresh_failures: 0,
+            empty_response_retries: 0,
+            account_rotations: 0,
+            same_account_retries: 0,
+            stream_failover_attempts: 0,
+            stream_failover_candidates_considered: 0,
+            last_stream_failover_candidate_count: 0,
+            stream_failover_recoveries: 0,
+            stream_failover_cross_account_recoveries: 0,
+            cumulative_latency_ms: 0,
+            last_request_at: None,
+            last_error: None,
+        }
+    }
+
+    /// Shallow copy into the persisted observability shape.
+    pub fn to_snapshot(&self) -> RuntimeMetricsSnapshot {
+        RuntimeMetricsSnapshot {
+            started_at: self.started_at,
+            total_requests: self.total_requests,
+            successful_requests: self.successful_requests,
+            failed_requests: self.failed_requests,
+            responses_requests: self.responses_requests,
+            auth_refresh_requests: self.auth_refresh_requests,
+            diagnostic_probe_requests: self.diagnostic_probe_requests,
+            outbound_request_attempt_budget: self.outbound_request_attempt_budget,
+            outbound_request_attempts_consumed: self.outbound_request_attempts_consumed,
+            request_attempt_budget_exhaustions: self.request_attempt_budget_exhaustions,
+            pool_exhaustion_fast_fails: self.pool_exhaustion_fast_fails,
+            server_burst_fast_fails: self.server_burst_fast_fails,
+            rate_limited_responses: self.rate_limited_responses,
+            server_errors: self.server_errors,
+            network_errors: self.network_errors,
+            user_aborts: self.user_aborts,
+            auth_refresh_failures: self.auth_refresh_failures,
+            empty_response_retries: self.empty_response_retries,
+            account_rotations: self.account_rotations,
+            same_account_retries: self.same_account_retries,
+            stream_failover_attempts: self.stream_failover_attempts,
+            stream_failover_candidates_considered: self.stream_failover_candidates_considered,
+            last_stream_failover_candidate_count: self.last_stream_failover_candidate_count,
+            stream_failover_recoveries: self.stream_failover_recoveries,
+            stream_failover_cross_account_recoveries: self
+                .stream_failover_cross_account_recoveries,
+            cumulative_latency_ms: self.cumulative_latency_ms,
+            last_request_at: self.last_request_at,
+            last_error: self.last_error.clone(),
+            extra: serde_json::Map::new(),
+        }
+    }
+}
+
+// ===========================================================================
+// PipelineConfig (loader-time resolution — spec 13 §4 steps 11–13)
+// ===========================================================================
+
+/// Config the loader resolved ONCE (per loader call in TS; per pipeline
+/// construction here). Spec-04 fields (fetch timeout, cooldowns, skew,
+/// invalidation cooldown, pid offset, scheduling) live on
+/// [`RotationProxyState`] — this struct carries only the spec-13 extras.
+#[derive(Debug, Clone)]
+pub struct PipelineConfig {
+    pub rate_limit_toast_debounce_ms: i64,
+    pub retry_all_accounts_rate_limited: bool,
+    pub retry_all_accounts_max_wait_ms: i64,
+    pub retry_all_accounts_max_retries: i64,
+    pub fallback_on_unsupported_codex_model: bool,
+    pub fallback_to_gpt52_on_unsupported_gpt53: bool,
+    pub unsupported_codex_fallback_chain: Option<FallbackChain>,
+    pub toast_duration_ms: i64,
+    pub failover_mode: FailoverMode,
+    /// Effective max ≤ 1 (spec 13 gotcha 1).
+    pub stream_failover_max: u32,
+    pub stream_failover_soft_timeout_ms: i64,
+    pub stream_failover_hard_timeout_ms: i64,
+    /// conservative 2 / balanced 1 / aggressive 0.
+    pub max_same_account_retries: u32,
+    pub empty_response_max_retries: i64,
+    pub empty_response_retry_delay_ms: i64,
+    pub response_continuation_enabled: bool,
+}
+
+/// Resolve the pipeline config from plugin config + env (spec 13 §4 steps
+/// 11–13). Also applies `configureRateLimitBackoff` — the module-level
+/// backoff config the short-retry threshold getter reads (gotcha:
+/// `getConfiguredRateLimitShortRetryThresholdMs` ≠ the config getter).
+pub fn load_pipeline_config(plugin_config: &PluginConfig) -> PipelineConfig {
+    configure_rate_limit_backoff(RateLimitBackoffOverrides {
+        dedup_window_ms: Some(getters::get_rate_limit_dedup_window_ms(plugin_config)),
+        state_reset_ms: Some(getters::get_rate_limit_state_reset_ms(plugin_config)),
+        max_backoff_ms: Some(getters::get_rate_limit_max_backoff_ms(plugin_config)),
+        short_retry_threshold_ms: Some(getters::get_rate_limit_short_retry_threshold_ms(
+            plugin_config,
+        )),
+    });
+
+    let stream_stall_timeout_ms = getters::get_stream_stall_timeout_ms(plugin_config);
+    let failover_mode = parse_failover_mode(std::env::var("CODEX_AUTH_FAILOVER_MODE").ok().as_deref());
+    let stream_failover_max = {
+        let configured = parse_env_int(
+            std::env::var("CODEX_AUTH_STREAM_FAILOVER_MAX").ok().as_deref(),
+        )
+        .unwrap_or_else(|| mode_lookup(&STREAM_FAILOVER_MAX_BY_MODE, failover_mode));
+        // capStreamFailoverMax clamps to [0, 1] (MAX_STREAM_FAILOVERS = 1),
+        // then Math.max(0, …) — spec 13 gotcha 1.
+        cap_stream_failover_max(configured as f64)
+    };
+    let stream_failover_soft_timeout_ms = parse_env_int(
+        std::env::var("CODEX_AUTH_STREAM_STALL_SOFT_TIMEOUT_MS")
+            .ok()
+            .as_deref(),
+    )
+    .unwrap_or_else(|| mode_lookup(&STREAM_FAILOVER_SOFT_TIMEOUT_BY_MODE, failover_mode))
+    .max(1_000);
+    let stream_failover_hard_timeout_ms = parse_env_int(
+        std::env::var("CODEX_AUTH_STREAM_STALL_HARD_TIMEOUT_MS")
+            .ok()
+            .as_deref(),
+    )
+    .unwrap_or(stream_stall_timeout_ms as i64)
+    .max(stream_failover_soft_timeout_ms);
+    let max_same_account_retries = match failover_mode {
+        FailoverMode::Conservative => 2,
+        FailoverMode::Balanced => 1,
+        FailoverMode::Aggressive => 0,
+    };
+
+    PipelineConfig {
+        rate_limit_toast_debounce_ms: getters::get_rate_limit_toast_debounce_ms(plugin_config)
+            as i64,
+        retry_all_accounts_rate_limited: getters::get_retry_all_accounts_rate_limited(
+            plugin_config,
+        ),
+        retry_all_accounts_max_wait_ms: getters::get_retry_all_accounts_max_wait_ms(plugin_config)
+            as i64,
+        retry_all_accounts_max_retries: getters::get_retry_all_accounts_max_retries(plugin_config)
+            as i64,
+        fallback_on_unsupported_codex_model: getters::get_fallback_on_unsupported_codex_model(
+            plugin_config,
+        ),
+        fallback_to_gpt52_on_unsupported_gpt53:
+            getters::get_fallback_to_gpt52_on_unsupported_gpt53(plugin_config),
+        unsupported_codex_fallback_chain: Some(getters::get_unsupported_codex_fallback_chain(
+            plugin_config,
+        )),
+        toast_duration_ms: getters::get_toast_duration_ms(plugin_config) as i64,
+        failover_mode,
+        stream_failover_max,
+        stream_failover_soft_timeout_ms,
+        stream_failover_hard_timeout_ms,
+        max_same_account_retries,
+        empty_response_max_retries: getters::get_empty_response_max_retries(plugin_config) as i64,
+        empty_response_retry_delay_ms: getters::get_empty_response_retry_delay_ms(plugin_config)
+            as i64,
+        response_continuation_enabled: getters::get_response_continuation(plugin_config),
+    }
+}
+
+// ===========================================================================
+// ProxyPipeline
+// ===========================================================================
+
+/// Shared pipeline state — the union of the `index.ts` factory closure state
+/// (spec 13 §3) and the proxy's `RotationProxyState` (spec 04). Cheap-clone
+/// handle; every clone shares the same state.
+#[derive(Clone)]
+pub struct ProxyPipeline {
+    inner: Arc<PipelineShared>,
+}
+
+struct PipelineShared {
+    state: tokio::sync::Mutex<RotationProxyState>,
+    config: PipelineConfig,
+    metrics: StdMutex<RuntimeMetrics>,
+    entitlement_cache: StdMutex<EntitlementCache>,
+    capability_policy: StdMutex<CapabilityPolicyStore>,
+    preemptive_scheduler: StdMutex<PreemptiveQuotaScheduler>,
+    /// Per-request monotonic session-affinity write version (spec 13 §3).
+    session_affinity_write_version: AtomicI64,
+}
+
+/// Outcome of a failover attempt shared between the pump closure and the
+/// (possibly already finished) bookkeeping (same benign race as TS —
+/// `successAccountForResponse` mutated by the failover fn during streaming).
+#[derive(Debug, Clone)]
+struct FailoverSuccess {
+    index: i64,
+    entitlement_key: String,
+    cross_account: bool,
+}
+
+/// How the caller must finish the usage-ledger row for a `/responses` run.
+enum RunCompletion {
+    /// Record the row immediately (TS `finally` semantics).
+    Record(RuntimeUsageRecordInput),
+    /// STREAMING upstream success: the record is deferred to the
+    /// client-forward stage (`forwarded ? success : stream_forward_failed`),
+    /// which also owns the network-failure account cleanup on a forward
+    /// stall (TS runtime-rotation-proxy.ts:1424-1450 onStreamError).
+    DeferStream {
+        success_completion: RuntimeUsageRecordInput,
+        account_index: i64,
+        family: ModelFamily,
+        model: Option<String>,
+        session_key: Option<String>,
+    },
+}
+
+/// Deferred bookkeeping for a STREAMING `/responses` success handed to the
+/// server's client-forward stage: on a mid-stream stall / upstream read
+/// error / client write error the serving account gets recordFailure + a
+/// network-error cooldown, session affinity is forgotten, and the ledger row
+/// becomes failure/`stream_forward_failed`; on a clean forward the row is
+/// the success completion (TS runtime-rotation-proxy.ts:1424-1450).
+pub struct ResponsesStreamBookkeeping {
+    pub recorder: RuntimeUsageRecorder,
+    pub success_completion: RuntimeUsageRecordInput,
+    pub account_index: i64,
+    pub family: ModelFamily,
+    pub model: Option<String>,
+    pub session_key: Option<String>,
+}
+
+/// Result of [`ProxyPipeline::handle_responses_for_server`].
+pub struct ResponsesOutcome {
+    pub response: StreamResponse,
+    /// `Some` only for a streaming upstream success — everything else was
+    /// already recorded by the pipeline.
+    pub deferred: Option<ResponsesStreamBookkeeping>,
+}
+
+impl ProxyPipeline {
+    pub fn new(state: RotationProxyState, config: PipelineConfig) -> Self {
+        let started_at = now_ms();
+        Self {
+            inner: Arc::new(PipelineShared {
+                state: tokio::sync::Mutex::new(state),
+                config,
+                metrics: StdMutex::new(RuntimeMetrics::new(started_at)),
+                entitlement_cache: StdMutex::new(EntitlementCache::new()),
+                capability_policy: StdMutex::new(CapabilityPolicyStore::new()),
+                preemptive_scheduler: StdMutex::new(PreemptiveQuotaScheduler::default()),
+                session_affinity_write_version: AtomicI64::new(0),
+            }),
+        }
+    }
+
+    /// The proxy state (server surface reads status / thread goals here).
+    pub async fn state(&self) -> tokio::sync::MutexGuard<'_, RotationProxyState> {
+        self.inner.state.lock().await
+    }
+
+    pub fn config(&self) -> &PipelineConfig {
+        &self.inner.config
+    }
+
+    /// Snapshot of the runtime metrics (codex-metrics / report surfaces).
+    pub fn metrics_snapshot(&self) -> RuntimeMetricsSnapshot {
+        self.lock_metrics().to_snapshot()
+    }
+
+    fn lock_metrics(&self) -> std::sync::MutexGuard<'_, RuntimeMetrics> {
+        self.inner
+            .metrics
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner())
+    }
+
+    /// `syncRuntimeObservability(requestId)` — mirror metrics + cooldowns
+    /// into the shared observability snapshot (spec 13 §3).
+    fn sync_runtime_observability(&self, request_id: Option<&str>) {
+        let now = now_ms();
+        let pool_remaining = get_pool_exhaustion_cooldown_remaining(now);
+        let burst_remaining = get_server_burst_cooldown_remaining(now);
+        let metrics = self.lock_metrics().clone();
+        let request_id = request_id.map(str::to_string);
+        mutate_runtime_observability_snapshot(move |snapshot| {
+            snapshot.current_request_id = request_id.clone();
+            snapshot.pool_exhaustion_cooldown_until =
+                (pool_remaining > 0).then_some(now + pool_remaining);
+            snapshot.server_burst_cooldown_until =
+                (burst_remaining > 0).then_some(now + burst_remaining);
+            snapshot.responses_requests = metrics.responses_requests;
+            snapshot.auth_refresh_requests = metrics.auth_refresh_requests;
+            snapshot.diagnostic_probe_requests = metrics.diagnostic_probe_requests;
+            snapshot.runtime_metrics = metrics.to_snapshot();
+        });
+    }
+
+    fn forget_session(&self, affinity: &Option<Arc<StdMutex<SessionAffinityStore>>>, key: Option<&str>) {
+        if let Some(store) = affinity {
+            store
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner())
+                .forget_session(key);
+        }
+    }
+
+    /// Entry point for `/responses` requests from callers that consume the
+    /// response themselves (tests, in-process clients). Records the
+    /// usage-ledger row (source `runtime-proxy`, operation `responses`)
+    /// exactly once — a deferred streaming-success row is recorded here
+    /// because no separate forward stage exists for these callers.
+    pub async fn handle_responses(
+        &self,
+        ctx: RequestContext,
+        trace_id: Option<String>,
+    ) -> StreamResponse {
+        let outcome = self.handle_responses_for_server(ctx, trace_id).await;
+        if let Some(deferred) = outcome.deferred {
+            deferred.recorder.record(deferred.success_completion).await;
+        }
+        outcome.response
+    }
+
+    /// `/responses` entry point for the HTTP server: like
+    /// [`Self::handle_responses`], but for a STREAMING upstream success the
+    /// usage-ledger record and the network-failure account cleanup are
+    /// DEFERRED to the caller's client-forward stage — the row is
+    /// `forwarded ? success : failure/stream_forward_failed` and a
+    /// mid-stream stall cools the serving account down and forgets session
+    /// affinity (TS runtime-rotation-proxy.ts:1424-1450). Mirrors metrics
+    /// into observability on exit (the TS `finally`).
+    pub async fn handle_responses_for_server(
+        &self,
+        ctx: RequestContext,
+        trace_id: Option<String>,
+    ) -> ResponsesOutcome {
+        let started_at = now_ms();
+        {
+            let mut metrics = self.lock_metrics();
+            metrics.last_request_at = Some(started_at);
+        }
+        self.sync_runtime_observability(trace_id.as_deref());
+
+        // Policy gate runs inside `run`; the recorder needs the decision's
+        // project key, so `run` creates it and returns the completion.
+        let (response, recorder, completion) = self.run(ctx, trace_id.as_deref()).await;
+        let deferred = match completion {
+            RunCompletion::Record(completion) => {
+                recorder.record(completion).await;
+                None
+            }
+            RunCompletion::DeferStream {
+                success_completion,
+                account_index,
+                family,
+                model,
+                session_key,
+            } => Some(ResponsesStreamBookkeeping {
+                recorder,
+                success_completion,
+                account_index,
+                family,
+                model,
+                session_key,
+            }),
+        };
+        self.sync_runtime_observability(None);
+        ResponsesOutcome { response, deferred }
+    }
+
+    /// The merged request state machine. Returns the response plus the
+    /// usage recorder + completion (recorded by the caller — TS `finally`).
+    async fn run(
+        &self,
+        mut ctx: RequestContext,
+        trace_id: Option<&str>,
+    ) -> (StreamResponse, RuntimeUsageRecorder, RunCompletion) {
+        let config = &self.inner.config;
+
+        // ------------------------------------------------------------------
+        // §5.1 setup
+        // ------------------------------------------------------------------
+        let (shared_manager, upstream_base_url, fetch_client, affinity, env) = {
+            let state = self.inner.state.lock().await;
+            (
+                state.active_account_manager.clone(),
+                state.upstream_base_url.clone(),
+                state.fetch_client.clone(),
+                state.session_affinity_store.clone(),
+                StateEnv {
+                    fetch_timeout_ms: state.fetch_timeout_ms.max(0) as u64,
+                    stream_stall_timeout_ms: state.stream_stall_timeout_ms,
+                    token_refresh_skew_ms: state.token_refresh_skew_ms,
+                    network_error_cooldown_ms: state.network_error_cooldown_ms,
+                    server_error_cooldown_ms: state.server_error_cooldown_ms,
+                    token_invalidation_cooldown_ms: state.token_invalidation_cooldown_ms,
+                    min_rotation_interval_ms: state.min_rotation_interval_ms,
+                    pid_offset_enabled: state.pid_offset_enabled,
+                    max_runtime_account_attempts: state.max_runtime_account_attempts,
+                    quota_remaining_percent_threshold: state.quota_remaining_percent_threshold,
+                    routing_mutex_mode: state.routing_mutex_mode,
+                    scheduling_strategy: state.scheduling_strategy,
+                    forced_account_index: state.forced_account_index,
+                },
+            )
+        };
+
+        // Upstream URL: base (trailing slashes stripped) + upstream path.
+        // `upstream_path` carries the incoming query string when present
+        // (spec 04 "incoming query string preserved" — the server encodes it
+        // into the path). Equivalent output to `rewriteUrlForCodex` for the
+        // default base URL.
+        let url = format!(
+            "{}{}",
+            upstream_base_url.trim_end_matches('/'),
+            ctx.upstream_path
+        );
+
+        let is_streaming = ctx.stream;
+        let mut model: Option<String> = ctx.model.clone();
+        let mut model_family: ModelFamily = ctx.family;
+        let mut quota_key = build_quota_key(model_family, model.as_deref());
+        let session_key: Option<String> = ctx.session_key.clone();
+        let session_affinity_version = self
+            .inner
+            .session_affinity_write_version
+            .fetch_add(1, Ordering::SeqCst)
+            + 1;
+
+        // Parsed request body (`transformedBody` analogue). The proxy
+        // surface forwards Codex-shaped bodies verbatim — the identity
+        // transform (see module docs / deviations).
+        let mut transformed_body: Option<Value> = serde_json::from_slice(&ctx.body).ok();
+
+        // §5.1 step 7 — response continuation injection.
+        if config.response_continuation_enabled
+            && let Some(Value::Object(body)) = transformed_body.as_mut()
+            && !body.contains_key("previous_response_id")
+            && let Some(store) = affinity.as_ref()
+        {
+            let last_id = store
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner())
+                .get_last_response_id(session_key.as_deref(), now_ms());
+            if let Some(last_id) = last_id {
+                body.insert(
+                    "previous_response_id".to_string(),
+                    Value::String(last_id),
+                );
+                if let Ok(serialized) = serde_json::to_vec(&Value::Object(body.clone())) {
+                    ctx.body = serialized;
+                }
+            }
+        }
+        if let Some(store) = affinity.as_ref() {
+            store
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner())
+                .prune(now_ms());
+        }
+
+        // ------------------------------------------------------------------
+        // §5.2 runtime policy gate (FAIL-OPEN)
+        // ------------------------------------------------------------------
+        let policy_decision: Option<RuntimePolicyDecision> = {
+            let accounts: Vec<RuntimePolicyAccount> = {
+                let mut manager = shared_manager.lock().await;
+                manager
+                    .get_accounts_snapshot()
+                    .iter()
+                    .map(|account| RuntimePolicyAccount {
+                        index: account.index as i64,
+                        account_id: account.meta.account_id.clone(),
+                        email: account.meta.email.clone(),
+                    })
+                    .collect()
+            };
+            let cwd = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
+            let state = load_runtime_policy_state(&cwd).await;
+            // `capability_policy` lives behind a std mutex that must NOT be
+            // held across `evaluate_runtime_policy`'s internal await
+            // (`evaluate_budgets` file IO). The store's only contribution
+            // there is the capability-unsupported blocking rule
+            // (quota-forecast-01), which runs strictly AFTER that await —
+            // so evaluate with `None` and apply the identical rule
+            // synchronously on the returned decision.
+            match evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+                state: &state,
+                accounts: &accounts,
+                model: model.as_deref(),
+                capability_policy: None,
+                now: None,
+            })
+            .await
+            {
+                Ok(mut decision) => {
+                    let capability = self
+                        .inner
+                        .capability_policy
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    for account in &accounts {
+                        let capability_key =
+                            resolve_entitlement_account_key(&EntitlementAccountRef {
+                                account_id: account.account_id.clone(),
+                                email: account.email.clone(),
+                                refresh_token: None,
+                                index: Some(account.index),
+                            });
+                        if let Some(snapshot) = capability.get_snapshot(
+                            &capability_key,
+                            model.as_deref().unwrap_or("unknown"),
+                        ) && snapshot.unsupported > 0
+                        {
+                            decision.blocked_account_indexes.insert(account.index);
+                        }
+                    }
+                    Some(decision)
+                }
+                Err(error) => {
+                    let data = serde_json::json!({ "error": error.to_string() });
+                    log_warn("Runtime policy evaluation failed open.", Some(&data));
+                    None
+                }
+            }
+        };
+
+        let recorder = create_runtime_usage_recorder(RuntimeUsageRecorderOptions {
+            source: UsageLedgerSource::RuntimeProxy,
+            operation: UsageLedgerOperation::Responses,
+            model: model.clone(),
+            project_key: policy_decision
+                .as_ref()
+                .and_then(|decision| decision.project_key.clone()),
+            request_id: trace_id.map(str::to_string),
+            started_at: Some(now_ms()),
+            append: None,
+        });
+        // Default completion (spec 13 §5.2).
+        let failure_completion = |status: Option<i64>, code: &str| {
+            RunCompletion::Record(RuntimeUsageRecordInput {
+                outcome: Some(UsageLedgerOutcome::Failure),
+                status_code: status,
+                error_code: Some(code.to_string()),
+                ..Default::default()
+            })
+        };
+
+        if let Some(decision) = policy_decision.as_ref().filter(|decision| !decision.allowed) {
+            {
+                let mut metrics = self.lock_metrics();
+                metrics.failed_requests += 1;
+                metrics.last_error = Some("Runtime policy blocked request".to_string());
+            }
+            let code = decision
+                .error_code
+                .clone()
+                .unwrap_or_else(|| "policy_blocked".to_string());
+            let body = serde_json::to_string(&serde_json::json!({
+                "error": {
+                    "message": "Runtime policy blocked this local request.",
+                    "code": code,
+                    "reasons": decision.reasons,
+                }
+            }))
+            .unwrap_or_default();
+            let completion = RunCompletion::Record(RuntimeUsageRecordInput {
+                outcome: Some(UsageLedgerOutcome::Blocked),
+                status_code: Some(decision.status_code as i64),
+                error_code: Some(code),
+                ..Default::default()
+            });
+            return (
+                StreamResponse::from_text(
+                    decision.status_code,
+                    "",
+                    synthetic_json_headers(),
+                    body,
+                ),
+                recorder,
+                completion,
+            );
+        }
+
+        // ------------------------------------------------------------------
+        // §5.3 fast-fail cooldowns
+        // ------------------------------------------------------------------
+        let now = now_ms();
+        let pool_remaining = get_pool_exhaustion_cooldown_remaining(now);
+        if pool_remaining > 0 {
+            {
+                let mut metrics = self.lock_metrics();
+                metrics.failed_requests += 1;
+                metrics.pool_exhaustion_fast_fails += 1;
+                metrics.last_error = Some("Pool exhaustion cooldown active".to_string());
+            }
+            let body = error_message_body(&retry_loop::pool_exhaustion_cooldown_message(
+                &format_wait_time(pool_remaining),
+            ));
+            return (
+                StreamResponse::from_text(429, "", synthetic_json_headers(), body),
+                recorder,
+                failure_completion(Some(429), "pool_exhaustion_cooldown"),
+            );
+        }
+        let burst_remaining = get_server_burst_cooldown_remaining(now);
+        if burst_remaining > 0 {
+            {
+                let mut metrics = self.lock_metrics();
+                metrics.failed_requests += 1;
+                metrics.server_burst_fast_fails += 1;
+                metrics.last_error = Some("Server burst cooldown active".to_string());
+            }
+            let body = error_message_body(&retry_loop::server_burst_cooldown_message(
+                &format_wait_time(burst_remaining),
+            ));
+            return (
+                StreamResponse::from_text(503, "", synthetic_json_headers(), body),
+                recorder,
+                failure_completion(Some(503), "server_burst_cooldown"),
+            );
+        }
+
+        // ------------------------------------------------------------------
+        // §5.4 outbound attempt budget (cap 6)
+        // ------------------------------------------------------------------
+        let mut account_count = { shared_manager.lock().await.get_account_count() };
+        let budget_value = compute_outbound_request_attempt_budget(
+            OutboundRequestAttemptBudgetParams {
+                account_count: account_count as f64,
+                max_same_account_retries: config.max_same_account_retries as f64,
+                empty_response_max_retries: config.empty_response_max_retries as f64,
+                stream_failover_max: config.stream_failover_max as f64,
+            },
+        );
+        let budget = Arc::new(OutboundAttemptBudget::new(budget_value));
+        {
+            let mut metrics = self.lock_metrics();
+            // `??=` — only the first request records the budget (gotcha 15).
+            metrics
+                .outbound_request_attempt_budget
+                .get_or_insert(budget_value as i64);
+        }
+
+        // Transient attempt budget (spec 04): default 4.
+        let transient_attempt_limit = env
+            .max_runtime_account_attempts
+            .min(account_count.max(1) as i64)
+            .max(1);
+
+        // Pin/affinity meta (spec 04 per-request read).
+        let (pinned_index, is_pinned) = {
+            let mut state = self.inner.state.lock().await;
+            let meta = cma_runtime::rotation::storage_meta::read_storage_meta_from_disk(None);
+            if meta.affinity_generation > state.last_observed_affinity_generation {
+                if let Some(store) = state.session_affinity_store.as_ref() {
+                    store
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner())
+                        .clear_all();
+                }
+                state.last_observed_affinity_generation = meta.affinity_generation;
+            }
+            let pinned = env.forced_account_index.or(meta.pinned_account_index);
+            (pinned, env.forced_account_index.or(meta.pinned_account_index).is_some())
+        };
+
+        // Counters OUTSIDE the outer loop (gotcha 7).
+        let mut counters = RetryCounters::default();
+        let mut attempted_unsupported_fallback_models: Vec<String> = Vec::new();
+        if let Some(model) = model.as_deref() {
+            attempted_unsupported_fallback_models.push(model.to_string());
+        }
+
+        // ------------------------------------------------------------------
+        // §5.5 outer loop — model-fallback restarts
+        // ------------------------------------------------------------------
+        'outer: loop {
+            let mut attempted: HashSet<i64> = HashSet::new();
+            let mut skip_reasons: HashMap<i64, String> = HashMap::new();
+            let mut restart_with_fallback = false;
+            let mut retry_next_account_before_fallback = false;
+            let mut transient_attempts: i64 = 0;
+            let mut exhaustion_reason = ExhaustionReason::NoAccount;
+            let mut transient_exhaustion_reason: Option<ExhaustionReason> = None;
+            let mut reloaded_after_no_account = false;
+
+            // Capability + policy score boosts (merged additively). The
+            // sticky min-rotation boost is NOT folded in here: TS recomputes
+            // it on EVERY iteration of the account-attempt while-loop
+            // (runtime-rotation-proxy.ts:956-961), re-reading
+            // lastGlobalAccountIndex/lastGlobalSwitchAt, so attempts that
+            // span the min-rotation window (429 short-retry sleeps,
+            // stream-failover waits) or race a concurrent request drop or
+            // retarget the boost mid-request.
+            let base_score_boost_by_account: HashMap<i64, f64> = {
+                let mut manager = shared_manager.lock().await;
+                let snapshot = manager.get_accounts_snapshot();
+                let capability = self
+                    .inner
+                    .capability_policy
+                    .lock()
+                    .unwrap_or_else(|poison| poison.into_inner());
+                let now = now_ms();
+                let mut boosts: HashMap<i64, f64> = snapshot
+                    .iter()
+                    .map(|account| {
+                        let key = entitlement_key_for(account);
+                        let boost_model = model
+                            .clone()
+                            .unwrap_or_else(|| model_family.as_str().to_string());
+                        (
+                            account.index as i64,
+                            capability.get_boost(&key, &boost_model, now),
+                        )
+                    })
+                    .collect();
+                if let Some(decision) = policy_decision.as_ref() {
+                    for (index, boost) in &decision.score_boost_by_account {
+                        *boosts.entry(*index).or_insert(0.0) += *boost;
+                    }
+                }
+                boosts
+            };
+
+            // --------------------------------------------------------------
+            // §5.5.1 account attempt loop
+            // --------------------------------------------------------------
+            'account: while attempted.len() < account_count.max(1)
+                && transient_attempts < transient_attempt_limit
+            {
+                // Sticky min-rotation boost (spec 04 rotation loop step 1) —
+                // recomputed PER ATTEMPT into a fresh clone of the base map
+                // (never += into a persistent map: that would stack +1000 per
+                // attempt).
+                let score_boost_by_account: HashMap<i64, f64> = {
+                    let state = self.inner.state.lock().await;
+                    merge_sticky_min_rotation_boost(
+                        &base_score_boost_by_account,
+                        env.min_rotation_interval_ms,
+                        state.last_global_account_index,
+                        state.last_global_switch_at,
+                        now_ms(),
+                    )
+                };
+
+                // Selection (pin > sequential > affinity > hybrid).
+                let selected: Option<ManagedAccount> = {
+                    let mut manager = shared_manager.lock().await;
+                    // Block-scope the std MutexGuard so the async Send
+                    // analysis sees it released before the await below
+                    // (an explicit `drop()` is not enough for the generator
+                    // Send check; the guard type is !Send).
+                    let candidate = {
+                        let mut affinity_guard = affinity
+                            .as_ref()
+                            .map(|store| store.lock().unwrap_or_else(|poison| poison.into_inner()));
+                        choose_account(ChooseAccountParams {
+                            account_manager: &mut manager,
+                            session_affinity_store: affinity_guard.as_deref_mut(),
+                            session_key: session_key.as_deref(),
+                            family: model_family,
+                            model: model.as_deref(),
+                            attempted_indexes: &attempted,
+                            now: now_ms(),
+                            policy: policy_decision.as_ref(),
+                            pinned_index,
+                            skip_reasons: Some(&mut skip_reasons),
+                            sticky_boost_by_account: Some(&score_boost_by_account),
+                            pid_offset_enabled: env.pid_offset_enabled,
+                            scheduling_strategy: env.scheduling_strategy,
+                        })
+                    };
+                    // Enabled-mutex cursor commit inside the same lock scope
+                    // (spec 04 gotcha 7): skip when pinned or sequential.
+                    if let Some(candidate) = candidate.as_ref()
+                        && env.routing_mutex_mode == RoutingMutexMode::Enabled
+                        && pinned_index.is_none()
+                        && env.scheduling_strategy != SchedulingStrategy::Sequential
+                    {
+                        manager
+                            .mark_switched_locked(
+                                candidate.index as i64,
+                                SwitchReason::Rotation,
+                                model_family,
+                                None,
+                            )
+                            .await;
+                    }
+                    candidate
+                };
+
+                let Some(account) = selected else {
+                    // One-shot stale-state recovery (issue #606; spec 04
+                    // step 3).
+                    let policy_blocked_empty = policy_decision
+                        .as_ref()
+                        .map(|decision| decision.blocked_account_indexes.is_empty())
+                        .unwrap_or(true);
+                    let has_policy_skip = skip_reasons
+                        .values()
+                        .any(|reason| reason == "policy-blocked");
+                    if !reloaded_after_no_account
+                        && !is_pinned
+                        && account_count > 0
+                        && exhaustion_reason == ExhaustionReason::NoAccount
+                        && policy_blocked_empty
+                        && !has_policy_skip
+                    {
+                        reloaded_after_no_account = true;
+                        let recovered = {
+                            let mut state = self.inner.state.lock().await;
+                            recover_stale_runtime_state(&mut state).await
+                        };
+                        if let Some(_reloaded) = recovered {
+                            account_count =
+                                shared_manager.lock().await.get_account_count();
+                            skip_reasons.clear();
+                            attempted.clear();
+                            continue 'account;
+                        }
+                    }
+                    break 'account;
+                };
+
+                let account_index = account.index as i64;
+                if attempted.contains(&account_index) {
+                    break 'account;
+                }
+                attempted.insert(account_index);
+                if policy_decision
+                    .as_ref()
+                    .is_some_and(|decision| decision.blocked_account_indexes.contains(&account_index))
+                {
+                    continue 'account;
+                }
+
+                // ------------------------------------------------------
+                // Token refresh (spec 13 order: refresh BEFORE bucket).
+                // ------------------------------------------------------
+                let needs_refresh = {
+                    let access_empty = account
+                        .meta
+                        .access_token
+                        .as_deref()
+                        .unwrap_or("")
+                        .trim()
+                        .is_empty();
+                    let expires = account.meta.expires_at.unwrap_or(0);
+                    access_empty
+                        || expires <= now_ms() + env.token_refresh_skew_ms.max(0)
+                };
+                if needs_refresh {
+                    self.lock_metrics().auth_refresh_requests += 1;
+                }
+                let fresh = ensure_fresh_access_token(EnsureFreshAccessTokenParams {
+                    account_manager: &shared_manager,
+                    account: &account,
+                    family: model_family,
+                    model: model.as_deref(),
+                    now: now_ms(),
+                    token_refresh_skew_ms: env.token_refresh_skew_ms,
+                    token_invalidation_cooldown_ms: env.token_invalidation_cooldown_ms,
+                })
+                .await;
+                let (access_token, mut account) = match fresh {
+                    EnsureFreshAccessTokenResult::Ok {
+                        access_token,
+                        account,
+                    } => (access_token, account),
+                    EnsureFreshAccessTokenResult::Failed {
+                        retryable,
+                        invalidated,
+                    } => {
+                        {
+                            let mut metrics = self.lock_metrics();
+                            metrics.auth_refresh_failures += 1;
+                            metrics.failed_requests += 1;
+                            metrics.account_rotations += 1;
+                            metrics.last_error =
+                                Some("Failed to refresh token, authentication required".to_string());
+                        }
+                        self.forget_session(&affinity, session_key.as_deref());
+                        exhaustion_reason = ExhaustionReason::AuthFailure;
+                        if invalidated {
+                            // Token invalidation: STOP the cascade (spec 04
+                            // gotcha 10) — no rotation, 401 token_invalidated.
+                            let body = build_token_invalidation_body("");
+                            return (
+                                StreamResponse::from_text(
+                                    401,
+                                    "",
+                                    synthetic_json_headers(),
+                                    body,
+                                ),
+                                recorder,
+                                failure_completion(Some(401), "token_invalidated"),
+                            );
+                        }
+                        if retryable {
+                            self.lock_metrics().network_errors += 1;
+                            transient_attempts += 1;
+                            transient_exhaustion_reason = Some(ExhaustionReason::AuthFailure);
+                            let mut state = self.inner.state.lock().await;
+                            state.status.retries += 1;
+                            state.status.rotations += 1;
+                            continue 'account;
+                        }
+                        // Non-retryable: auth-failure removal policy
+                        // (spec 13 §5.5.1 — union seam).
+                        let failures = {
+                            let manager = shared_manager.lock().await;
+                            manager
+                                .get_account_by_index(account_index)
+                                .and_then(|account| account.runtime.consecutive_auth_failures)
+                                .unwrap_or(0)
+                        };
+                        let policy = evaluate_failure_policy(
+                            &FailurePolicyInput {
+                                kind: Some(FailureKind::AuthRefresh),
+                                consecutive_auth_failures: Some(failures as f64),
+                                max_auth_failures_before_removal: None,
+                                server_retry_after_ms: None,
+                                failover_mode: Some(config.failover_mode),
+                            },
+                            None,
+                        );
+                        if policy.remove_account {
+                            let label = {
+                                let mut manager = shared_manager.lock().await;
+                                let label = format_account_label(
+                                    manager
+                                        .get_account_by_index(account_index)
+                                        .map(|account| account as &dyn AccountLabelSource),
+                                    account_index as usize,
+                                );
+                                if let Some(store) = affinity.as_ref() {
+                                    let mut store = store
+                                        .lock()
+                                        .unwrap_or_else(|poison| poison.into_inner());
+                                    store.forget_account(account_index);
+                                    manager.remove_account_by_index(account_index);
+                                    store.reindex_after_removal(account_index);
+                                } else {
+                                    manager.remove_account_by_index(account_index);
+                                }
+                                label
+                            };
+                            account_count =
+                                shared_manager.lock().await.get_account_count();
+                            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                            show_runtime_toast(
+                                &retry_loop::auth_failure_removal_toast(&label, failures),
+                                ToastVariant::Error,
+                            );
+                            continue 'account;
+                        }
+                        if let (Some(cooldown_ms), Some(reason)) =
+                            (policy.cooldown_ms, policy.cooldown_reason)
+                        {
+                            let mut manager = shared_manager.lock().await;
+                            manager.mark_account_cooling_down(
+                                account_index,
+                                cooldown_ms,
+                                reason,
+                            );
+                            drop(manager);
+                            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                        }
+                        continue 'account;
+                    }
+                };
+
+                // ------------------------------------------------------
+                // Identity resolution (spec 13 §5.5.1).
+                // ------------------------------------------------------
+                let current_workspace = account.get_current_workspace().cloned();
+                let stored_account_id = current_workspace
+                    .as_ref()
+                    .map(|workspace| workspace.id.clone())
+                    .or_else(|| account.meta.account_id.clone());
+                let stored_source = if current_workspace.is_some() {
+                    Some(cma_core::schemas::account_storage::AccountIdSource::Manual)
+                } else {
+                    account.meta.account_id_source
+                };
+                let identity = resolve_runtime_request_identity(
+                    ResolveRuntimeRequestIdentityInput {
+                        stored_account_id: stored_account_id.as_deref(),
+                        source: stored_source,
+                        stored_email: account.meta.email.as_deref(),
+                        access_token: Some(access_token.as_str()),
+                        id_token: None,
+                    },
+                );
+                let Some(resolved_account_id) =
+                    identity.account_id.clone().filter(|id| !id.trim().is_empty())
+                else {
+                    {
+                        let mut manager = shared_manager.lock().await;
+                        manager.refund_token(account_index, model_family, model.as_deref());
+                        manager.record_failure(account_index, model_family, model.as_deref());
+                        manager.mark_account_cooling_down(
+                            account_index,
+                            ACCOUNT_LIMITS.auth_failure_cooldown_ms,
+                            CooldownReason::AuthFailure,
+                        );
+                    }
+                    shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                    exhaustion_reason = ExhaustionReason::AuthFailure;
+                    transient_attempts += 1;
+                    continue 'account;
+                };
+                let entitlement_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+                    account_id: Some(
+                        stored_account_id
+                            .clone()
+                            .unwrap_or_else(|| resolved_account_id.clone()),
+                    ),
+                    email: identity.email.clone(),
+                    refresh_token: Some(account.meta.refresh_token.clone()),
+                    index: Some(account_index),
+                });
+                let capability_model_key = model
+                    .clone()
+                    .unwrap_or_else(|| model_family.as_str().to_string());
+
+                // Entitlement cached block (spec 13 §5.5.1).
+                let block = {
+                    let mut cache = self
+                        .inner
+                        .entitlement_cache
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    cache.is_blocked(&entitlement_key, &capability_model_key, now_ms())
+                };
+                if block.blocked {
+                    {
+                        let mut metrics = self.lock_metrics();
+                        metrics.account_rotations += 1;
+                        metrics.last_error = Some(format!(
+                            "Entitlement cached block for account {}",
+                            account_index + 1
+                        ));
+                    }
+                    let data = serde_json::json!({
+                        "accountIndex": account_index,
+                        "waitTime": format_wait_time(block.wait_ms),
+                    });
+                    log_warn("Entitlement cached block; rotating.", Some(&data));
+                    continue 'account;
+                }
+
+                // Identity write-back (NOT persisted here — hitchhikes on
+                // later debounced saves, spec 13 §5.5.1).
+                {
+                    let mut manager = shared_manager.lock().await;
+                    if let Some(live) = manager.get_account_by_index_mut(account_index) {
+                        let had_account_id = live
+                            .meta
+                            .account_id
+                            .as_deref()
+                            .is_some_and(|id| !id.trim().is_empty());
+                        live.meta.account_id = Some(resolved_account_id.clone());
+                        if !had_account_id
+                            && identity
+                                .token_account_id
+                                .as_deref()
+                                .is_some_and(|token_id| token_id == resolved_account_id)
+                        {
+                            live.meta.account_id_source = stored_source.or(Some(
+                                cma_core::schemas::account_storage::AccountIdSource::Token,
+                            ));
+                        }
+                        if let Some(email) = identity.email.clone() {
+                            live.meta.email = Some(email);
+                        }
+                    }
+                }
+                // Mirror the write-back onto the local clone: TS mutates the
+                // LIVE account object (`account.accountId = accountId`,
+                // index.ts:1467-1478), so later reads through `account` —
+                // e.g. the 429 backoff stable key
+                // (`account.accountId ?? account.email ?? null`) — always
+                // see the resolved id even when the stored metadata had none.
+                {
+                    let had_account_id = account
+                        .meta
+                        .account_id
+                        .as_deref()
+                        .is_some_and(|id| !id.trim().is_empty());
+                    account.meta.account_id = Some(resolved_account_id.clone());
+                    if !had_account_id
+                        && identity
+                            .token_account_id
+                            .as_deref()
+                            .is_some_and(|token_id| token_id == resolved_account_id)
+                    {
+                        account.meta.account_id_source = stored_source.or(Some(
+                            cma_core::schemas::account_storage::AccountIdSource::Token,
+                        ));
+                    }
+                    if let Some(email) = identity.email.clone() {
+                        account.meta.email = Some(email);
+                    }
+                }
+
+                // Account toast (spec 13 §5.5.1).
+                if account_count > 1 {
+                    let mut manager = shared_manager.lock().await;
+                    if manager.should_show_account_toast(
+                        account_index,
+                        Some(config.rate_limit_toast_debounce_ms),
+                    ) {
+                        let label = format_account_label(
+                            manager
+                                .get_account_by_index(account_index)
+                                .map(|account| account as &dyn AccountLabelSource),
+                            account_index as usize,
+                        );
+                        manager.mark_toast_shown(account_index);
+                        drop(manager);
+                        show_runtime_toast(
+                            &format!(
+                                "Using {label} ({}/{account_count})",
+                                account_index + 1
+                            ),
+                            ToastVariant::Info,
+                        );
+                    }
+                }
+
+                // Outbound headers (spec 04 step 9 — HTTP-surface
+                // authoritative: scrub + auth + originator).
+                let headers = build_outbound_headers(
+                    &ctx.headers,
+                    &access_token,
+                    &resolved_account_id,
+                );
+
+                // Record identity into proxy status (spec 04 step 8).
+                {
+                    let mut state = self.inner.state.lock().await;
+                    state.status.last_account_index = Some(account_index);
+                    state.status.last_account_label =
+                        Some(format!("Account {}", account_index + 1));
+                    state.status.last_account_id = Some(resolved_account_id.clone());
+                    state.status.last_account_updated_at = Some(now_ms());
+                }
+
+                // Preemptive quota deferral (spec 13 §5.5.1).
+                let quota_schedule_key =
+                    format!("{entitlement_key}:{capability_model_key}");
+                let deferral = {
+                    let mut scheduler = self
+                        .inner
+                        .preemptive_scheduler
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    scheduler.get_deferral(&quota_schedule_key, now_ms())
+                };
+                if deferral.defer && deferral.wait_ms > 0 {
+                    {
+                        let mut manager = shared_manager.lock().await;
+                        manager.mark_rate_limited_with_reason(
+                            account_index,
+                            deferral.wait_ms,
+                            model_family,
+                            RateLimitReason::Quota,
+                            model.as_deref(),
+                        );
+                        manager.record_rate_limit(
+                            account_index,
+                            model_family,
+                            model.as_deref(),
+                        );
+                    }
+                    {
+                        let mut metrics = self.lock_metrics();
+                        metrics.account_rotations += 1;
+                        metrics.last_error = Some(format!(
+                            "Preemptive quota deferral for account {}",
+                            account_index + 1
+                        ));
+                    }
+                    shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                    exhaustion_reason = ExhaustionReason::RateLimit;
+                    continue 'account;
+                }
+
+                // Local token bucket (per-process, NEVER persisted —
+                // gotcha 6 / spec 04 gotcha 1).
+                let consumed = {
+                    let mut manager = shared_manager.lock().await;
+                    manager.consume_token(account_index, model_family, model.as_deref())
+                };
+                if !consumed {
+                    {
+                        let mut manager = shared_manager.lock().await;
+                        manager.record_rate_limit(
+                            account_index,
+                            model_family,
+                            model.as_deref(),
+                        );
+                    }
+                    {
+                        let mut metrics = self.lock_metrics();
+                        metrics.account_rotations += 1;
+                        metrics.last_error = Some(format!(
+                            "Local token bucket depleted for account {} ({quota_key})",
+                            account_index + 1
+                        ));
+                    }
+                    log_warn("Local token bucket depleted.", None);
+                    skip_reasons.insert(account_index, "token-exhausted".to_string());
+                    exhaustion_reason = ExhaustionReason::RateLimit;
+                    continue 'account;
+                }
+
+                // ------------------------------------------------------
+                // §5.5.2 inner same-account retry loop
+                // ------------------------------------------------------
+                let mut same_account_retry_count: u32 = 0;
+                let mut short_rate_limit_retry_count: u32 = 0;
+
+                'inner: loop {
+                    // Budget consume ("primary").
+                    if !budget.try_consume() {
+                        let last_error = budget.exhausted_last_error();
+                        {
+                            let mut metrics = self.lock_metrics();
+                            metrics.request_attempt_budget_exhaustions += 1;
+                            metrics.last_error = Some(last_error.clone());
+                        }
+                        log_warn("Request attempt budget exhausted.", None);
+                        let body = error_message_body(
+                            &retry_loop::budget_exhausted_response_message(Some(
+                                &last_error,
+                            )),
+                        );
+                        return (
+                            StreamResponse::from_text(
+                                503,
+                                "",
+                                synthetic_json_headers(),
+                                body,
+                            ),
+                            recorder,
+                            failure_completion(Some(503), "plugin_host_request_failed"),
+                        );
+                    }
+                    self.lock_metrics().outbound_request_attempts_consumed += 1;
+
+                    {
+                        let mut metrics = self.lock_metrics();
+                        metrics.total_requests += 1;
+                        metrics.responses_requests += 1;
+                    }
+                    {
+                        let mut state = self.inner.state.lock().await;
+                        state.status.upstream_requests += 1;
+                    }
+                    self.sync_runtime_observability(trace_id);
+
+                    let fetch_start = std::time::Instant::now();
+                    let fetch_result = tokio::time::timeout(
+                        std::time::Duration::from_millis(env.fetch_timeout_ms),
+                        fetch_client
+                            .post(&url)
+                            .headers(headers.clone())
+                            .body(ctx.body.clone())
+                            .send(),
+                    )
+                    .await;
+
+                    let upstream = match fetch_result {
+                        Ok(Ok(response)) => response,
+                        Ok(Err(error)) => {
+                            match self
+                                .handle_network_failure(
+                                    &shared_manager,
+                                    &affinity,
+                                    account_index,
+                                    model_family,
+                                    model.as_deref(),
+                                    session_key.as_deref(),
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                    error.to_string(),
+                                    same_account_retry_count,
+                                    &env,
+                                )
+                                .await
+                            {
+                                NetworkFailureNext::RetrySameAccount => {
+                                    same_account_retry_count += 1;
+                                    continue 'inner;
+                                }
+                                NetworkFailureNext::NextAccount => {
+                                    exhaustion_reason = ExhaustionReason::NetworkError;
+                                    transient_attempts += 1;
+                                    transient_exhaustion_reason =
+                                        Some(ExhaustionReason::NetworkError);
+                                    let mut state = self.inner.state.lock().await;
+                                    state.status.retries += 1;
+                                    state.status.rotations += 1;
+                                    drop(state);
+                                    break 'inner;
+                                }
+                            }
+                        }
+                        Err(_elapsed) => {
+                            // Timeout-triggered abort is a network failure
+                            // (frozen message — spec 13 gotcha 20).
+                            match self
+                                .handle_network_failure(
+                                    &shared_manager,
+                                    &affinity,
+                                    account_index,
+                                    model_family,
+                                    model.as_deref(),
+                                    session_key.as_deref(),
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                    "Request timeout".to_string(),
+                                    same_account_retry_count,
+                                    &env,
+                                )
+                                .await
+                            {
+                                NetworkFailureNext::RetrySameAccount => {
+                                    same_account_retry_count += 1;
+                                    continue 'inner;
+                                }
+                                NetworkFailureNext::NextAccount => {
+                                    exhaustion_reason = ExhaustionReason::NetworkError;
+                                    transient_attempts += 1;
+                                    transient_exhaustion_reason =
+                                        Some(ExhaustionReason::NetworkError);
+                                    let mut state = self.inner.state.lock().await;
+                                    state.status.retries += 1;
+                                    state.status.rotations += 1;
+                                    drop(state);
+                                    break 'inner;
+                                }
+                            }
+                        }
+                    };
+
+                    let fetch_latency_ms = fetch_start.elapsed().as_millis() as i64;
+                    let response = stream_response_from_reqwest(upstream);
+                    let response_headers = response.headers.clone();
+                    let status = response.status;
+
+                    // Quota scheduler snapshot (ok AND error responses).
+                    if let Some(snapshot) =
+                        read_quota_scheduler_snapshot(&response_headers, status, now_ms())
+                    {
+                        let mut scheduler = self
+                            .inner
+                            .preemptive_scheduler
+                            .lock()
+                            .unwrap_or_else(|poison| poison.into_inner());
+                        scheduler.update(&quota_schedule_key, snapshot);
+                    }
+
+                    if !response.ok() {
+                        // ----------------------------------------------
+                        // §5.5.3 error precedence ladder
+                        // ----------------------------------------------
+                        // 1. Context overflow.
+                        let outcome =
+                            handle_context_overflow(response, model.as_deref()).await;
+                        let response = match outcome {
+                            cma_request::context_overflow::ContextOverflowOutcome::Handled {
+                                response,
+                            } => {
+                                // TS returns early WITHOUT updating
+                                // usageCompletion, so the finally block
+                                // records the initialized default row:
+                                // failure / plugin_host_request_failed /
+                                // statusCode null (looks like a TS oversight,
+                                // but the ledger shape must match — change
+                                // both sides together if this is ever fixed).
+                                return (
+                                    response,
+                                    recorder,
+                                    failure_completion(
+                                        None,
+                                        "plugin_host_request_failed",
+                                    ),
+                                );
+                            }
+                            cma_request::context_overflow::ContextOverflowOutcome::NotHandled {
+                                response,
+                            } => response,
+                        };
+
+                        // Raw upstream body (pre-normalization) for the
+                        // token-invalidation vector: spec 04 feeds
+                        // `readErrorBody` output (NOT the normalized payload
+                        // with the login hint appended) to
+                        // `isTokenInvalidationError` and
+                        // `buildTokenInvalidationBody`. Capture it BEFORE
+                        // `handle_error_response` consumes the body, then
+                        // rebuild the response for the ladder.
+                        let mut response = response;
+                        let raw_error_body_text =
+                            response.collect_text().await.unwrap_or_default();
+                        let response = StreamResponse::from_text(
+                            response.status,
+                            response.status_text.clone(),
+                            response.headers.clone(),
+                            raw_error_body_text.clone(),
+                        );
+
+                        // 2. handleErrorResponse.
+                        let error_result = handle_error_response(
+                            response,
+                            Some(&ErrorHandlingOptions {
+                                request_correlation_id: trace_id.map(str::to_string),
+                                thread_id: session_key.clone(),
+                            }),
+                        )
+                        .await;
+                        let error_body_value = error_result
+                            .error_body
+                            .clone()
+                            .unwrap_or(Value::Null);
+                        // The ladder keys off the REMAPPED status
+                        // (mapUsageLimit404WithBody rewrites structured 404
+                        // usage-limit bodies to 429 and 404 entitlement
+                        // bodies to 403): TS reads `errorResponse.status` in
+                        // the workspace-disabled, 403-entitlement, 429 and
+                        // step-10 catch-all predicates. The RAW `status`
+                        // stays in place everywhere TS also reads
+                        // `response.status` (quota-scheduler snapshot, 5xx
+                        // check, lastError, failure completion) and for the
+                        // 401 vector (the remap never produces 401).
+                        let mapped_status = error_result.response.status;
+
+                        // 3. Unsupported model traversal + fallback chains.
+                        let info = get_unsupported_codex_model_info(&error_body_value);
+                        let has_remaining_accounts =
+                            attempted.len() < account_count.max(1);
+                        let plan = plan_unsupported_model(&UnsupportedModelContext {
+                            info: &info,
+                            error_body: &error_body_value,
+                            model: model.as_deref(),
+                            has_remaining_accounts,
+                            fallback_on_unsupported_codex_model: config
+                                .fallback_on_unsupported_codex_model,
+                            fallback_to_gpt52_on_unsupported_gpt53: config
+                                .fallback_to_gpt52_on_unsupported_gpt53,
+                            custom_chain: config.unsupported_codex_fallback_chain.as_ref(),
+                            attempted_models: &attempted_unsupported_fallback_models,
+                        });
+                        match plan {
+                            UnsupportedModelPlan::NotUnsupported => {}
+                            UnsupportedModelPlan::TryOtherAccountsFirst { blocked_model } => {
+                                self.mark_unsupported(
+                                    &entitlement_key,
+                                    &blocked_model,
+                                );
+                                {
+                                    let mut manager = shared_manager.lock().await;
+                                    manager.refund_token(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                    manager.record_failure(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                    if let Some(live) =
+                                        manager.get_account_by_index_mut(account_index)
+                                    {
+                                        live.meta.last_switch_reason =
+                                            Some(SwitchReason::Rotation);
+                                    }
+                                }
+                                self.record_capability_failure(
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                );
+                                self.forget_session(&affinity, session_key.as_deref());
+                                self.lock_metrics().last_error =
+                                    Some(model_fallback::unsupported_rotation_last_error(
+                                        account_index + 1,
+                                        &blocked_model,
+                                    ));
+                                let data = serde_json::json!({
+                                    "requestedModel": model,
+                                    "fallbackApplied": false,
+                                    "fallbackReason": "unsupported-model-entitlement",
+                                });
+                                log_warn(
+                                    "Unsupported model on account; trying other accounts first.",
+                                    Some(&data),
+                                );
+                                retry_next_account_before_fallback = true;
+                                break 'inner;
+                            }
+                            UnsupportedModelPlan::Fallback {
+                                previous_model,
+                                fallback_model,
+                                ..
+                            } => {
+                                if !attempted_unsupported_fallback_models
+                                    .contains(&previous_model)
+                                {
+                                    attempted_unsupported_fallback_models
+                                        .push(previous_model.clone());
+                                }
+                                if !attempted_unsupported_fallback_models
+                                    .contains(&fallback_model)
+                                {
+                                    attempted_unsupported_fallback_models
+                                        .push(fallback_model.clone());
+                                }
+                                self.mark_unsupported(&entitlement_key, &previous_model);
+                                let previous_family = model
+                                    .as_deref()
+                                    .map(get_model_family)
+                                    .unwrap_or(model_family);
+                                {
+                                    let mut manager = shared_manager.lock().await;
+                                    manager.refund_token(
+                                        account_index,
+                                        previous_family,
+                                        model.as_deref(),
+                                    );
+                                }
+                                // Swap model/family/quota keys + rebuild body
+                                // (gotchas 10–11).
+                                let (rebuilt, serialized) = rebuild_body_with_model(
+                                    transformed_body.as_ref(),
+                                    &ctx.body,
+                                    &fallback_model,
+                                );
+                                transformed_body = Some(rebuilt);
+                                ctx.body = serialized.into_bytes();
+                                model = Some(fallback_model.clone());
+                                model_family = get_model_family(&fallback_model);
+                                quota_key =
+                                    build_quota_key(model_family, model.as_deref());
+                                self.lock_metrics().last_error =
+                                    Some(model_fallback::fallback_last_error(
+                                        &previous_model,
+                                        &fallback_model,
+                                    ));
+                                log_warn("Applying model fallback.", None);
+                                show_runtime_toast(
+                                    &model_fallback::fallback_toast_message(
+                                        &previous_model,
+                                        &fallback_model,
+                                    ),
+                                    ToastVariant::Warning,
+                                );
+                                restart_with_fallback = true;
+                                break 'inner;
+                            }
+                            UnsupportedModelPlan::StrictBlock { blocked_model } => {
+                                self.mark_unsupported(&entitlement_key, &blocked_model);
+                                self.lock_metrics().last_error = Some(
+                                    model_fallback::strict_block_last_error(&blocked_model),
+                                );
+                                show_runtime_toast(
+                                    &model_fallback::strict_block_toast_message(
+                                        &blocked_model,
+                                    ),
+                                    ToastVariant::Warning,
+                                );
+                                // FALLS THROUGH to the generic return below.
+                            }
+                            UnsupportedModelPlan::BookkeepOnly { blocked_model } => {
+                                self.mark_unsupported(&entitlement_key, &blocked_model);
+                            }
+                        }
+
+                        // 4. Workspace disabled (spec 13 §5.5.3 step 4).
+                        let error_code_value = error_body_value
+                            .pointer("/error/code")
+                            .cloned()
+                            .unwrap_or(Value::String(String::new()));
+                        let error_message_text = error_body_value
+                            .pointer("/error/message")
+                            .and_then(Value::as_str)
+                            .unwrap_or("")
+                            .to_string();
+                        if !info.is_unsupported
+                            && is_workspace_disabled_error(
+                                mapped_status,
+                                &error_code_value,
+                                &error_message_text,
+                            )
+                        {
+                            {
+                                let mut metrics = self.lock_metrics();
+                                metrics.failed_requests += 1;
+                                metrics.last_error = Some(format!(
+                                    "Workspace disabled for account {}",
+                                    account_index + 1
+                                ));
+                            }
+                            let has_workspaces = account
+                                .meta
+                                .workspaces
+                                .as_ref()
+                                .is_some_and(|workspaces| !workspaces.is_empty());
+                            if !has_workspaces {
+                                log_warn(
+                                    "Workspace disabled but account tracks no workspaces. Leaving account enabled.",
+                                    None,
+                                );
+                                if attempted.len() < account_count.max(1) {
+                                    continue 'account;
+                                }
+                                return (
+                                    error_result.response.into_stream_response(),
+                                    recorder,
+                                    failure_completion(
+                                        Some(status as i64),
+                                        "plugin_host_request_failed",
+                                    ),
+                                );
+                            }
+                            // Disable current workspace + rotate.
+                            let rotated = {
+                                let mut manager = shared_manager.lock().await;
+                                if let Some(live) =
+                                    manager.get_account_by_index_mut(account_index)
+                                {
+                                    let current_id = current_workspace
+                                        .as_ref()
+                                        .map(|workspace| workspace.id.clone());
+                                    live.disable_current_workspace(current_id.as_deref());
+                                    live.rotate_to_next_workspace().map(|workspace| {
+                                        workspace
+                                            .name
+                                            .clone()
+                                            .unwrap_or_else(|| workspace.id.clone())
+                                    })
+                                } else {
+                                    None
+                                }
+                            };
+                            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                            if let Some(next_name) = rotated {
+                                let old_name = current_workspace
+                                    .as_ref()
+                                    .and_then(|workspace| workspace.name.clone())
+                                    .unwrap_or_else(|| "workspace".to_string());
+                                show_runtime_toast(
+                                    &format!(
+                                        "Workspace {old_name} disabled. Switched to {next_name}."
+                                    ),
+                                    ToastVariant::Warning,
+                                );
+                                log_info("Workspace rotated after disable.", None);
+                                // Same account becomes selectable again
+                                // (gotcha 8).
+                                attempted.remove(&account_index);
+                                continue 'account;
+                            }
+                            {
+                                let mut manager = shared_manager.lock().await;
+                                manager.set_account_enabled(account_index, false);
+                            }
+                            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                            show_runtime_toast(
+                                &format!(
+                                    "All workspaces disabled for account {}. Switching to another account.",
+                                    account_index + 1
+                                ),
+                                ToastVariant::Warning,
+                            );
+                            self.forget_session(&affinity, session_key.as_deref());
+                            exhaustion_reason = ExhaustionReason::Deactivated;
+                            continue 'account;
+                        }
+
+                        // 5. 403 (not unsupported, not workspace):
+                        // plan-entitlement block. Mapped status: a
+                        // 404-entitlement body remapped to 403 must cache the
+                        // block exactly like a raw 403 (TS index.ts:2114).
+                        if mapped_status == 403 && !info.is_unsupported {
+                            {
+                                let mut cache = self
+                                    .inner
+                                    .entitlement_cache
+                                    .lock()
+                                    .unwrap_or_else(|poison| poison.into_inner());
+                                cache.mark_blocked(
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                    EntitlementBlockReason::PlanEntitlement,
+                                    None,
+                                    now_ms(),
+                                );
+                            }
+                            self.record_capability_failure(
+                                &entitlement_key,
+                                &capability_model_key,
+                            );
+                        }
+
+                        // 7. 5xx rotation (spec 13 §5.5.3 step 7 ∪ spec 04).
+                        if (500..=599).contains(&status) {
+                            let data = serde_json::json!({
+                                "status": status,
+                                "accountIndex": account_index,
+                            });
+                            log_warn("Server error; rotating to next account.", Some(&data));
+                            {
+                                let mut metrics = self.lock_metrics();
+                                metrics.failed_requests += 1;
+                                metrics.server_errors += 1;
+                                metrics.account_rotations += 1;
+                                metrics.last_error = Some(format!("HTTP {status}"));
+                            }
+                            let server_retry_after_ms =
+                                parse_retry_after_hint_ms(&response_headers);
+                            let policy = evaluate_failure_policy(
+                                &FailurePolicyInput {
+                                    kind: Some(FailureKind::Server),
+                                    consecutive_auth_failures: None,
+                                    max_auth_failures_before_removal: None,
+                                    server_retry_after_ms: server_retry_after_ms
+                                        .map(|ms| ms as f64),
+                                    failover_mode: Some(config.failover_mode),
+                                },
+                                Some(&FailurePolicyOverrides {
+                                    network_cooldown_ms: None,
+                                    server_cooldown_ms: Some(
+                                        env.server_error_cooldown_ms as f64,
+                                    ),
+                                }),
+                            );
+                            let armed_until =
+                                record_server_burst_failure(account_index as usize, now_ms());
+                            if armed_until > 0 {
+                                self.lock_metrics().last_error = Some(
+                                    "Repeated upstream server errors across the account pool"
+                                        .to_string(),
+                                );
+                            }
+                            if matches!(status, 502 | 503 | 529)
+                                && let Some(cooldown_ms) = policy.cooldown_ms
+                            {
+                                let mut scheduler = self
+                                    .inner
+                                    .preemptive_scheduler
+                                    .lock()
+                                    .unwrap_or_else(|poison| poison.into_inner());
+                                scheduler.mark_rate_limited(
+                                    &quota_schedule_key,
+                                    cooldown_ms as f64,
+                                    now_ms(),
+                                );
+                            }
+                            {
+                                let mut manager = shared_manager.lock().await;
+                                if policy.refund_token {
+                                    manager.refund_token(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                }
+                                if policy.record_failure {
+                                    manager.record_failure(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                }
+                            }
+                            if policy.record_failure {
+                                self.record_capability_failure(
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                );
+                            }
+                            if policy.retry_same_account
+                                && same_account_retry_count < config.max_same_account_retries
+                            {
+                                same_account_retry_count += 1;
+                                self.lock_metrics().same_account_retries += 1;
+                                let delay =
+                                    policy.retry_delay_ms.unwrap_or(500).max(MIN_BACKOFF_MS);
+                                let _ = abortable_sleep(
+                                    add_jitter(delay as f64, 0.2) as u64,
+                                    None,
+                                )
+                                .await;
+                                continue 'inner;
+                            }
+                            if let (Some(cooldown_ms), Some(reason)) =
+                                (policy.cooldown_ms, policy.cooldown_reason)
+                            {
+                                let mut manager = shared_manager.lock().await;
+                                manager.mark_account_cooling_down(
+                                    account_index,
+                                    cooldown_ms,
+                                    reason,
+                                );
+                                drop(manager);
+                                shared_manager
+                                    .save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                            }
+                            self.forget_session(&affinity, session_key.as_deref());
+                            exhaustion_reason = ExhaustionReason::ServerError;
+                            transient_attempts += 1;
+                            transient_exhaustion_reason =
+                                Some(ExhaustionReason::ServerError);
+                            {
+                                let mut state = self.inner.state.lock().await;
+                                state.status.retries += 1;
+                                state.status.rotations += 1;
+                            }
+                            break 'inner;
+                        }
+
+                        // 8. 429 with rate-limit metadata (MARK-BEFORE-SLEEP).
+                        // Mapped status: upstream reports quota exhaustion as
+                        // a structured 404 on this endpoint, which
+                        // handle_error_response remaps to 429 — that response
+                        // MUST take the rate-limit path (mark + rotate), not
+                        // the generic return (TS index.ts:2241).
+                        if mapped_status == 429 && let Some(rate_limit) = error_result.rate_limit.as_ref() {
+                            self.lock_metrics().rate_limited_responses += 1;
+                            let retry_after_ms = if rate_limit.retry_after_ms > 0 {
+                                rate_limit.retry_after_ms
+                            } else {
+                                60_000
+                            };
+                            let stable_key = account
+                                .meta
+                                .account_id
+                                .clone()
+                                .or_else(|| account.meta.email.clone());
+                            let backoff = get_rate_limit_backoff(
+                                account_index as usize,
+                                &quota_key,
+                                Some(retry_after_ms as f64),
+                                stable_key.as_deref(),
+                            );
+                            let cooldown_ms = backoff.delay_ms.max(retry_after_ms);
+                            {
+                                let mut scheduler = self
+                                    .inner
+                                    .preemptive_scheduler
+                                    .lock()
+                                    .unwrap_or_else(|poison| poison.into_inner());
+                                scheduler.mark_rate_limited(
+                                    &quota_schedule_key,
+                                    cooldown_ms as f64,
+                                    now_ms(),
+                                );
+                            }
+                            let threshold =
+                                configured_rate_limit_short_retry_threshold_ms();
+                            let reason =
+                                parse_rate_limit_reason(rate_limit.code.as_deref());
+                            match decide_rate_limit_429(
+                                cooldown_ms,
+                                threshold,
+                                short_rate_limit_retry_count,
+                            ) {
+                                RateLimit429Decision::ShortRetry => {
+                                    short_rate_limit_retry_count += 1;
+                                    // MARK BEFORE SLEEP (AUDIT-H3 / D-07,
+                                    // gotcha 5) + debounced save so a crash
+                                    // mid-sleep cannot lose the cooldown.
+                                    {
+                                        let mut manager = shared_manager.lock().await;
+                                        manager.mark_rate_limited_with_reason(
+                                            account_index,
+                                            cooldown_ms,
+                                            model_family,
+                                            reason,
+                                            model.as_deref(),
+                                        );
+                                        manager.record_rate_limit(
+                                            account_index,
+                                            model_family,
+                                            model.as_deref(),
+                                        );
+                                    }
+                                    shared_manager
+                                        .save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                                    // Per-account 30s debounce gate (TS
+                                    // index.ts:2292-2305): at most one
+                                    // rate-limit toast per account per
+                                    // debounce window.
+                                    {
+                                        let mut manager = shared_manager.lock().await;
+                                        if manager.should_show_account_toast(
+                                            account_index,
+                                            Some(config.rate_limit_toast_debounce_ms),
+                                        ) {
+                                            manager.mark_toast_shown(account_index);
+                                            drop(manager);
+                                            show_runtime_toast(
+                                                &retry_loop::short_retry_toast(
+                                                    &format_wait_time(cooldown_ms),
+                                                    short_rate_limit_retry_count,
+                                                ),
+                                                ToastVariant::Warning,
+                                            );
+                                        }
+                                    }
+                                    let _ = abortable_sleep(
+                                        add_jitter(
+                                            cooldown_ms.max(MIN_BACKOFF_MS) as f64,
+                                            0.2,
+                                        ) as u64,
+                                        None,
+                                    )
+                                    .await;
+                                    continue 'inner;
+                                }
+                                RateLimit429Decision::Rotate => {
+                                    {
+                                        let mut manager = shared_manager.lock().await;
+                                        manager.mark_rate_limited_with_reason(
+                                            account_index,
+                                            cooldown_ms,
+                                            model_family,
+                                            reason,
+                                            model.as_deref(),
+                                        );
+                                        manager.record_rate_limit(
+                                            account_index,
+                                            model_family,
+                                            model.as_deref(),
+                                        );
+                                        if let Some(live) =
+                                            manager.get_account_by_index_mut(account_index)
+                                        {
+                                            live.meta.last_switch_reason =
+                                                Some(SwitchReason::RateLimit);
+                                        }
+                                    }
+                                    self.forget_session(
+                                        &affinity,
+                                        session_key.as_deref(),
+                                    );
+                                    self.lock_metrics().account_rotations += 1;
+                                    shared_manager
+                                        .save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                                    log_warn("Rate limited. Rotating account.", None);
+                                    // Count check ANDs with the per-account
+                                    // debounce gate (TS index.ts:2338-2352).
+                                    if account_count > 1 {
+                                        let mut manager = shared_manager.lock().await;
+                                        if manager.should_show_account_toast(
+                                            account_index,
+                                            Some(config.rate_limit_toast_debounce_ms),
+                                        ) {
+                                            manager.mark_toast_shown(account_index);
+                                            drop(manager);
+                                            show_runtime_toast(
+                                                &retry_loop::rate_limit_rotation_toast(
+                                                    &format_wait_time(cooldown_ms),
+                                                ),
+                                                ToastVariant::Warning,
+                                            );
+                                        }
+                                    }
+                                    // 429 does NOT refund the token (spec 04
+                                    // gotcha 17).
+                                    exhaustion_reason = ExhaustionReason::RateLimit;
+                                    transient_attempts += 1;
+                                    transient_exhaustion_reason =
+                                        Some(ExhaustionReason::RateLimit);
+                                    {
+                                        let mut state = self.inner.state.lock().await;
+                                        state.status.retries += 1;
+                                        state.status.rotations += 1;
+                                    }
+                                    break 'inner;
+                                }
+                            }
+                        }
+
+                        // 9. 401 — token invalidation (spec 04, union
+                        // insert): no-rotate + 300 s cooldown.
+                        if status == 401 {
+                            {
+                                let mut manager = shared_manager.lock().await;
+                                manager.refund_token(
+                                    account_index,
+                                    model_family,
+                                    model.as_deref(),
+                                );
+                                manager.record_failure(
+                                    account_index,
+                                    model_family,
+                                    model.as_deref(),
+                                );
+                            }
+                            if is_token_invalidation_error(&raw_error_body_text) {
+                                {
+                                    let mut manager = shared_manager.lock().await;
+                                    apply_monotonic_auth_cooldown(
+                                        &mut manager,
+                                        &account,
+                                        env.token_invalidation_cooldown_ms,
+                                    );
+                                }
+                                self.forget_session(&affinity, session_key.as_deref());
+                                shared_manager
+                                    .save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                                self.lock_metrics().failed_requests += 1;
+                                let body = build_token_invalidation_body(&raw_error_body_text);
+                                // TS builds the reply from
+                                // responseHeadersForClient(upstream.headers)
+                                // (scrubbed diagnostics like x-request-id
+                                // survive) and sets content-type to exactly
+                                // "application/json" (no charset) — mirror
+                                // server.rs's upstream-401 path.
+                                let mut client_headers = HeaderMap::new();
+                                for (name, value) in
+                                    cma_request::stream_failover_runtime::response_headers_for_client(
+                                        &response_headers,
+                                    )
+                                {
+                                    if name == "content-type" {
+                                        continue;
+                                    }
+                                    if let (Ok(header_name), Ok(header_value)) = (
+                                        name.parse::<http::header::HeaderName>(),
+                                        http::header::HeaderValue::from_str(&value),
+                                    ) {
+                                        client_headers.append(header_name, header_value);
+                                    }
+                                }
+                                client_headers.insert(
+                                    http::header::CONTENT_TYPE,
+                                    http::header::HeaderValue::from_static(
+                                        "application/json",
+                                    ),
+                                );
+                                return (
+                                    StreamResponse::from_text(
+                                        401,
+                                        "",
+                                        client_headers,
+                                        body,
+                                    ),
+                                    recorder,
+                                    failure_completion(Some(401), "token_invalidated"),
+                                );
+                            }
+                            {
+                                let mut manager = shared_manager.lock().await;
+                                apply_monotonic_auth_cooldown(
+                                    &mut manager,
+                                    &account,
+                                    DEFAULT_AUTH_FAILURE_COOLDOWN_MS,
+                                );
+                            }
+                            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                            self.lock_metrics().failed_requests += 1;
+                            exhaustion_reason = ExhaustionReason::AuthFailure;
+                            transient_attempts += 1;
+                            transient_exhaustion_reason =
+                                Some(ExhaustionReason::AuthFailure);
+                            {
+                                let mut state = self.inner.state.lock().await;
+                                state.status.retries += 1;
+                                state.status.rotations += 1;
+                            }
+                            break 'inner;
+                        }
+
+                        // 10. Everything else → return the sanitized error
+                        // response. `mapped_status != 403` — TS keys the
+                        // catch-all guard off errorResponse.status
+                        // (index.ts:2358), so a mapped 403 never records a
+                        // capability failure here.
+                        if error_result.rate_limit.is_none()
+                            && !info.is_unsupported
+                            && mapped_status != 403
+                        {
+                            self.record_capability_failure(
+                                &entitlement_key,
+                                &capability_model_key,
+                            );
+                        }
+                        {
+                            let mut metrics = self.lock_metrics();
+                            metrics.failed_requests += 1;
+                            metrics.last_error = Some(format!("HTTP {status}"));
+                        }
+                        return (
+                            error_result.response.into_stream_response(),
+                            recorder,
+                            failure_completion(
+                                Some(status as i64),
+                                "plugin_host_request_failed",
+                            ),
+                        );
+                    }
+
+                    // --------------------------------------------------
+                    // §5.5.4 success path
+                    // --------------------------------------------------
+                    // TS resetRateLimitBackoff(idx, quotaKey) — no stable
+                    // account key (parity with the 2-arg TS call).
+                    reset_rate_limit_backoff(account_index as usize, &quota_key, None);
+                    self.lock_metrics().cumulative_latency_ms += fetch_latency_ms;
+
+                    let failover_success: Arc<StdMutex<Option<FailoverSuccess>>> =
+                        Arc::new(StdMutex::new(None));
+                    let response_for_success = if is_streaming
+                        && config.stream_failover_max > 0
+                    {
+                        let candidate_order = {
+                            let mut manager = shared_manager.lock().await;
+                            let snapshot: Vec<AdaptiveFailoverAccount> = manager
+                                .get_accounts_snapshot()
+                                .iter()
+                                .map(|account| AdaptiveFailoverAccount {
+                                    index: account.index,
+                                    last_used: Some(account.meta.last_used),
+                                    enabled: account.meta.enabled,
+                                    cooling_down_until: account.meta.cooling_down_until,
+                                    rate_limit_reset_times: account
+                                        .rate_limit_reset_times
+                                        .clone(),
+                                })
+                                .collect();
+                            build_adaptive_stream_failover_candidate_order(
+                                account_index as usize,
+                                &snapshot,
+                                now_ms(),
+                            )
+                        };
+                        {
+                            let mut metrics = self.lock_metrics();
+                            metrics.last_stream_failover_candidate_count =
+                                candidate_order.len() as i64;
+                            metrics.stream_failover_candidates_considered +=
+                                candidate_order.len() as i64;
+                        }
+                        let failover_ctx = FailoverCtx {
+                            pipeline: self.clone(),
+                            shared_manager: shared_manager.clone(),
+                            candidates: candidate_order
+                                .into_iter()
+                                .map(|index| index as i64)
+                                .collect(),
+                            primary_index: account_index,
+                            family: model_family,
+                            model: model.clone(),
+                            quota_key: quota_key.clone(),
+                            quota_schedule_key_base: model
+                                .clone()
+                                .unwrap_or_else(|| model_family.as_str().to_string()),
+                            client_headers: ctx.headers.clone(),
+                            body: ctx.body.clone(),
+                            url: url.clone(),
+                            budget: budget.clone(),
+                            fetch_client: fetch_client.clone(),
+                            env: env.clone(),
+                            success: failover_success.clone(),
+                            affinity: affinity.clone(),
+                            session_key: session_key.clone(),
+                            session_affinity_version,
+                            response_continuation_enabled: config
+                                .response_continuation_enabled,
+                        };
+                        with_streaming_failover(
+                            response,
+                            move |attempt, emitted_bytes| {
+                                let ctx = failover_ctx.clone();
+                                async move {
+                                    failover_attempt(ctx, attempt, emitted_bytes).await
+                                }
+                            },
+                            StreamFailoverOptions {
+                                max_failovers: Some(config.stream_failover_max as f64),
+                                stall_timeout_ms: None,
+                                soft_timeout_ms: Some(
+                                    config.stream_failover_soft_timeout_ms as f64,
+                                ),
+                                hard_timeout_ms: Some(
+                                    config.stream_failover_hard_timeout_ms as f64,
+                                ),
+                                request_instance_id: trace_id.map(str::to_string),
+                            },
+                        )
+                    } else {
+                        response
+                    };
+
+                    // Response-id capture → session affinity writes.
+                    let stored_response_id = Arc::new(std::sync::atomic::AtomicBool::new(false));
+                    let on_response_id: Option<
+                        cma_request::response_handler::ResponseIdCallback,
+                    > = if config.response_continuation_enabled {
+                        let affinity = affinity.clone();
+                        let session_key = session_key.clone();
+                        let stored_flag = stored_response_id.clone();
+                        let success_state = failover_success.clone();
+                        let primary_index = account_index;
+                        let version = session_affinity_version;
+                        Some(Arc::new(move |response_id: &str| {
+                            let index = success_state
+                                .lock()
+                                .unwrap_or_else(|poison| poison.into_inner())
+                                .as_ref()
+                                .map(|success| success.index)
+                                .unwrap_or(primary_index);
+                            if let Some(store) = affinity.as_ref() {
+                                let mut store = store
+                                    .lock()
+                                    .unwrap_or_else(|poison| poison.into_inner());
+                                let now = now_ms();
+                                store.remember_with_version(
+                                    session_key.as_deref(),
+                                    index,
+                                    now,
+                                    Some(version),
+                                );
+                                store.update_last_response_id(
+                                    session_key.as_deref(),
+                                    Some(response_id),
+                                    now,
+                                    Some(version),
+                                );
+                            }
+                            stored_flag.store(true, Ordering::SeqCst);
+                        }))
+                    } else {
+                        None
+                    };
+
+                    let success_response = match handle_success_response(
+                        response_for_success,
+                        is_streaming,
+                        ConvertSseOptions {
+                            on_response_id,
+                            stream_stall_timeout_ms: Some(env.stream_stall_timeout_ms as f64),
+                        },
+                    )
+                    .await
+                    {
+                        Ok(response) => response,
+                        Err(error) => {
+                            // Body-less upstream success — treat like a
+                            // network failure on this account.
+                            match self
+                                .handle_network_failure(
+                                    &shared_manager,
+                                    &affinity,
+                                    account_index,
+                                    model_family,
+                                    model.as_deref(),
+                                    session_key.as_deref(),
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                    error.to_string(),
+                                    same_account_retry_count,
+                                    &env,
+                                )
+                                .await
+                            {
+                                NetworkFailureNext::RetrySameAccount => {
+                                    same_account_retry_count += 1;
+                                    continue 'inner;
+                                }
+                                NetworkFailureNext::NextAccount => {
+                                    exhaustion_reason = ExhaustionReason::NetworkError;
+                                    transient_attempts += 1;
+                                    break 'inner;
+                                }
+                            }
+                        }
+                    };
+
+                    // Empty-response retry (non-streaming only).
+                    let mut success_response = success_response;
+                    if !is_streaming && config.empty_response_max_retries > 0 {
+                        let bytes = success_response.collect_bytes().await.unwrap_or_default();
+                        // TS parity: `bodyText ? JSON.parse(bodyText) : null`
+                        // runs inside a try/catch — an EMPTY body is empty,
+                        // but a non-empty body that fails to parse THROWS and
+                        // is swallowed, i.e. it is NOT an empty response.
+                        let empty = if bytes.is_empty() {
+                            true
+                        } else {
+                            match serde_json::from_slice::<Value>(&bytes) {
+                                Ok(parsed) => is_empty_response(Some(&parsed)),
+                                Err(_) => false,
+                            }
+                        };
+                        // Rebuild the (buffered) response either way —
+                        // clone-before-return semantics (gotcha 21).
+                        let rebuilt = StreamResponse::from_bytes(
+                            success_response.status,
+                            success_response.status_text.clone(),
+                            success_response.headers.clone(),
+                            bytes.clone().into(),
+                        );
+                        if empty {
+                            if counters.empty_response_retries
+                                < config.empty_response_max_retries
+                            {
+                                counters.empty_response_retries += 1;
+                                self.lock_metrics().empty_response_retries += 1;
+                                log_warn("Empty response. Retrying.", None);
+                                show_runtime_toast(
+                                    &retry_loop::empty_response_retry_toast(
+                                        counters.empty_response_retries,
+                                        config.empty_response_max_retries,
+                                    ),
+                                    ToastVariant::Warning,
+                                );
+                                {
+                                    let mut manager = shared_manager.lock().await;
+                                    manager.refund_token(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                    manager.record_failure(
+                                        account_index,
+                                        model_family,
+                                        model.as_deref(),
+                                    );
+                                }
+                                self.record_capability_failure(
+                                    &entitlement_key,
+                                    &capability_model_key,
+                                );
+                                let policy = evaluate_failure_policy(
+                                    &FailurePolicyInput {
+                                        kind: Some(FailureKind::EmptyResponse),
+                                        consecutive_auth_failures: None,
+                                        max_auth_failures_before_removal: None,
+                                        server_retry_after_ms: None,
+                                        failover_mode: Some(config.failover_mode),
+                                    },
+                                    None,
+                                );
+                                match retry_loop::decide_empty_response_retry(
+                                    policy.retry_same_account,
+                                    policy.retry_delay_ms,
+                                    same_account_retry_count,
+                                    config.max_same_account_retries,
+                                    config.empty_response_retry_delay_ms,
+                                ) {
+                                    retry_loop::EmptyResponseRetryAction::SameAccount {
+                                        delay_ms,
+                                    } => {
+                                        same_account_retry_count += 1;
+                                        self.lock_metrics().same_account_retries += 1;
+                                        if delay_ms > 0 {
+                                            let _ = abortable_sleep(
+                                                add_jitter(delay_ms as f64, 0.2) as u64,
+                                                None,
+                                            )
+                                            .await;
+                                        }
+                                        continue 'inner;
+                                    }
+                                    retry_loop::EmptyResponseRetryAction::NextAccount => {
+                                        self.forget_session(
+                                            &affinity,
+                                            session_key.as_deref(),
+                                        );
+                                        let _ = abortable_sleep(
+                                            add_jitter(
+                                                config.empty_response_retry_delay_ms as f64,
+                                                0.2,
+                                            )
+                                                as u64,
+                                            None,
+                                        )
+                                        .await;
+                                        break 'inner;
+                                    }
+                                }
+                            }
+                            // Retries exhausted.
+                            if success_response.status >= 500 {
+                                let armed =
+                                    record_server_burst_failure(account_index as usize, now_ms());
+                                if armed > 0 {
+                                    {
+                                        let mut metrics = self.lock_metrics();
+                                        metrics.server_burst_fast_fails += 1;
+                                        metrics.last_error = Some(
+                                            "Repeated upstream server errors across the account pool"
+                                                .to_string(),
+                                        );
+                                    }
+                                    // Wait label computed at response-build
+                                    // time (gotcha 22).
+                                    let wait =
+                                        get_server_burst_cooldown_remaining(now_ms());
+                                    let body = error_message_body(
+                                        &retry_loop::empty_response_server_burst_message(
+                                            &format_wait_time(wait),
+                                        ),
+                                    );
+                                    return (
+                                        StreamResponse::from_text(
+                                            503,
+                                            "",
+                                            synthetic_json_headers(),
+                                            body,
+                                        ),
+                                        recorder,
+                                        failure_completion(
+                                            Some(503),
+                                            "server_burst_cooldown",
+                                        ),
+                                    );
+                                }
+                            }
+                            log_warn("Empty response after retries. Returning as-is.", None);
+                        }
+                        success_response = rebuilt;
+                    }
+
+                    // Final bookkeeping (spec 13 §5.5.4 step 5 ∪ spec 04
+                    // success mapping).
+                    let success = failover_success
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner())
+                        .clone();
+                    let (success_index, success_key, cross_account) = match success {
+                        Some(success) => (
+                            success.index,
+                            success.entitlement_key,
+                            success.cross_account,
+                        ),
+                        None => (account_index, entitlement_key.clone(), false),
+                    };
+                    if cross_account {
+                        let mut manager = shared_manager.lock().await;
+                        manager.mark_switched(
+                            success_index,
+                            SwitchReason::Rotation,
+                            model_family,
+                        );
+                    }
+                    // record_success — the "healed" seam schedules the
+                    // debounced save (SharedAccountManager::record_success).
+                    shared_manager
+                        .record_success(success_index, model_family, model.as_deref())
+                        .await;
+                    {
+                        let mut capability = self
+                            .inner
+                            .capability_policy
+                            .lock()
+                            .unwrap_or_else(|poison| poison.into_inner());
+                        capability.record_success(
+                            &success_key,
+                            &capability_model_key,
+                            now_ms(),
+                        );
+                    }
+                    {
+                        let mut cache = self
+                            .inner
+                            .entitlement_cache
+                            .lock()
+                            .unwrap_or_else(|poison| poison.into_inner());
+                        cache.clear(&success_key, Some(&capability_model_key));
+                    }
+                    record_runtime_account_recovery(success_index);
+
+                    // Near-exhaustion preemptive rate limit (spec 04 success
+                    // mapping) — else affinity remember + sticky window.
+                    let near_exhaustion_wait = get_quota_near_exhaustion_wait_ms(
+                        &response_headers,
+                        env.quota_remaining_percent_threshold,
+                        now_ms(),
+                    );
+                    if near_exhaustion_wait > 0 {
+                        {
+                            let mut manager = shared_manager.lock().await;
+                            manager.mark_rate_limited_with_reason(
+                                success_index,
+                                near_exhaustion_wait,
+                                model_family,
+                                RateLimitReason::Quota,
+                                model.as_deref(),
+                            );
+                        }
+                        self.forget_session(&affinity, session_key.as_deref());
+                        shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                    } else {
+                        // Session-affinity remember rule (gotcha 14).
+                        if (!config.response_continuation_enabled
+                            || (!is_streaming
+                                && !stored_response_id.load(Ordering::SeqCst)))
+                            && let Some(store) = affinity.as_ref()
+                        {
+                            store
+                                .lock()
+                                .unwrap_or_else(|poison| poison.into_inner())
+                                .remember_with_version(
+                                    session_key.as_deref(),
+                                    success_index,
+                                    now_ms(),
+                                    Some(session_affinity_version),
+                                );
+                        }
+                        let mut state = self.inner.state.lock().await;
+                        state.last_global_account_index = Some(success_index);
+                        state.last_global_switch_at = now_ms();
+                    }
+
+                    // persistRuntimeActiveAccount (spec 04 step 12): pinned
+                    // requests never commit/persist/sync (#474); enabled
+                    // mode already committed under the mutex; sequential
+                    // never advances the drain-first primary (#509).
+                    if !(is_pinned && Some(success_index) == pinned_index) {
+                        if env.routing_mutex_mode != RoutingMutexMode::Enabled
+                            && env.scheduling_strategy != SchedulingStrategy::Sequential
+                        {
+                            let mut manager = shared_manager.lock().await;
+                            manager
+                                .mark_switched_locked(
+                                    success_index,
+                                    SwitchReason::Rotation,
+                                    model_family,
+                                    None,
+                                )
+                                .await;
+                        }
+                        shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                        let sync_manager = shared_manager.clone();
+                        tokio::spawn(async move {
+                            let manager = sync_manager.lock().await;
+                            manager
+                                .sync_codex_cli_active_selection_for_index(success_index)
+                                .await;
+                        });
+                    }
+
+                    {
+                        let mut metrics = self.lock_metrics();
+                        metrics.successful_requests += 1;
+                        metrics.last_error = None;
+                    }
+                    clear_pool_exhaustion_cooldown();
+                    clear_server_burst_cooldown();
+                    self.sync_runtime_observability(trace_id);
+
+                    let (final_account_id, final_email) = {
+                        let manager = shared_manager.lock().await;
+                        manager
+                            .get_account_by_index(success_index)
+                            .map(|account| {
+                                (
+                                    account.meta.account_id.clone(),
+                                    account.meta.email.clone(),
+                                )
+                            })
+                            .unwrap_or((None, None))
+                    };
+                    let completion = RuntimeUsageRecordInput {
+                        outcome: Some(UsageLedgerOutcome::Success),
+                        status_code: Some(success_response.status as i64),
+                        error_code: None,
+                        account: Some(RuntimePolicyAccount {
+                            index: success_index,
+                            account_id: final_account_id,
+                            email: final_email,
+                        }),
+                        ..Default::default()
+                    };
+                    // Streaming: the ledger row is decided by the client
+                    // forward (`forwarded ? success : stream_forward_failed`)
+                    // and the forward stage owns the network-error cleanup —
+                    // recording Success here would permanently say success
+                    // for a mid-stream stall (TS records after
+                    // forwardStreamingResponse resolves).
+                    if is_streaming {
+                        return (
+                            success_response,
+                            recorder,
+                            RunCompletion::DeferStream {
+                                success_completion: completion,
+                                account_index: success_index,
+                                family: model_family,
+                                model: model.clone(),
+                                session_key: session_key.clone(),
+                            },
+                        );
+                    }
+                    return (success_response, recorder, RunCompletion::Record(completion));
+                } // 'inner
+
+                if retry_next_account_before_fallback {
+                    retry_next_account_before_fallback = false;
+                    continue 'account;
+                }
+                if restart_with_fallback {
+                    break 'account;
+                }
+            } // 'account
+
+            if restart_with_fallback {
+                continue 'outer;
+            }
+
+            // --------------------------------------------------------------
+            // §5.5.5 pool exhausted (∪ spec 04 loop exit)
+            // --------------------------------------------------------------
+            if transient_attempts >= transient_attempt_limit
+                && attempted.len() < account_count.max(1)
+            {
+                exhaustion_reason = ExhaustionReason::Budget;
+            } else if exhaustion_reason == ExhaustionReason::Deactivated
+                && let Some(transient) = transient_exhaustion_reason
+            {
+                exhaustion_reason = transient;
+            }
+
+            let wait_ms = {
+                let mut manager = shared_manager.lock().await;
+                manager.get_min_wait_time_for_family(model_family, model.as_deref())
+            };
+
+            // Pinned: hard-fail 503 (never falls through to rotation, #474).
+            if is_pinned && let Some(pinned) = pinned_index {
+                let pinned_reason = skip_reasons.get(&pinned).cloned();
+                if pinned_reason.is_none() {
+                    let mut state = self.inner.state.lock().await;
+                    state.status.last_error = Some(format!(
+                        "pinned-503 missing skip reason (pinnedIndex={pinned})"
+                    ));
+                }
+                let skip_list: Vec<(usize, String)> = skip_reasons
+                    .iter()
+                    .filter(|(index, _)| **index >= 0)
+                    .map(|(index, reason)| (*index as usize, reason.clone()))
+                    .collect();
+                let body = cma_request::rate_limit_decision::build_pinned_unavailable_error_body(
+                    Some(pinned),
+                    &skip_list,
+                );
+                let body_json = serde_json::to_string(&serde_json::json!({ "error": body }))
+                    .unwrap_or_default();
+                self.lock_metrics().failed_requests += 1;
+                return (
+                    StreamResponse::from_text(503, "", synthetic_json_headers(), body_json),
+                    recorder,
+                    failure_completion(Some(503), "codex_pinned_account_unavailable"),
+                );
+            }
+
+            // Wait-and-retry when every account is rate-limited (spec 13).
+            if config.retry_all_accounts_rate_limited
+                && account_count > 0
+                && wait_ms > 0
+                && (config.retry_all_accounts_max_wait_ms == 0
+                    || wait_ms <= config.retry_all_accounts_max_wait_ms)
+                && counters.all_rate_limited_retries < config.retry_all_accounts_max_retries
+            {
+                let message = retry_loop::all_rate_limited_countdown_message(account_count);
+                show_runtime_toast(&message, ToastVariant::Warning);
+                let _ = abortable_sleep(add_jitter(wait_ms as f64, 0.2) as u64, None).await;
+                counters.all_rate_limited_retries += 1;
+                continue 'outer;
+            }
+
+            // Terminal exhaustion: arm the pool cooldown (spec 13) + emit
+            // the spec-04 machine-readable body (HTTP-surface contract).
+            let now = now_ms();
+            let pool_cooldown_until = if account_count > 0 && wait_ms > 0 {
+                arm_pool_exhaustion_cooldown(wait_ms as f64, now)
+            } else {
+                0
+            };
+            let effective_wait_ms = if pool_cooldown_until > 0 {
+                (pool_cooldown_until - now).max(0)
+            } else {
+                wait_ms
+            };
+            let wait_label = if effective_wait_ms > 0 {
+                format_wait_time(effective_wait_ms)
+            } else {
+                "a bit".to_string()
+            };
+            let message = retry_loop::terminal_pool_message(
+                account_count,
+                effective_wait_ms,
+                &wait_label,
+            );
+            {
+                let mut metrics = self.lock_metrics();
+                metrics.failed_requests += 1;
+                metrics.last_error = Some(message);
+            }
+            let skip_map: serde_json::Map<String, Value> = skip_reasons
+                .iter()
+                .map(|(index, reason)| (index.to_string(), Value::String(reason.clone())))
+                .collect();
+            record_runtime_pool_exhaustion(
+                exhaustion_reason.as_str(),
+                wait_ms,
+                &skip_map,
+            );
+            let status = normalize_exhaustion_status(exhaustion_reason.as_str());
+            let body = retry_loop::build_pool_exhausted_body(
+                exhaustion_reason.as_str(),
+                wait_ms,
+                &skip_reasons,
+                account_count,
+            );
+            return (
+                StreamResponse::from_text(status, "", synthetic_json_headers(), body),
+                recorder,
+                failure_completion(
+                    Some(status as i64),
+                    "codex_runtime_rotation_pool_exhausted",
+                ),
+            );
+        } // 'outer
+    }
+
+    fn mark_unsupported(&self, entitlement_key: &str, blocked_model: &str) {
+        {
+            let mut cache = self
+                .inner
+                .entitlement_cache
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            cache.mark_blocked(
+                entitlement_key,
+                blocked_model,
+                EntitlementBlockReason::UnsupportedModel,
+                None,
+                now_ms(),
+            );
+        }
+        let mut capability = self
+            .inner
+            .capability_policy
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        capability.record_unsupported(entitlement_key, blocked_model, now_ms());
+    }
+
+    fn record_capability_failure(&self, entitlement_key: &str, capability_model_key: &str) {
+        let mut capability = self
+            .inner
+            .capability_policy
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        capability.record_failure(entitlement_key, capability_model_key, now_ms());
+    }
+
+    /// Network-error handling (spec 13 §5.5.2 step 4, non-abort branch).
+    #[allow(clippy::too_many_arguments)]
+    async fn handle_network_failure(
+        &self,
+        shared_manager: &SharedAccountManager,
+        affinity: &Option<Arc<StdMutex<SessionAffinityStore>>>,
+        account_index: i64,
+        family: ModelFamily,
+        model: Option<&str>,
+        session_key: Option<&str>,
+        entitlement_key: &str,
+        capability_model_key: &str,
+        message: String,
+        same_account_retry_count: u32,
+        env: &StateEnv,
+    ) -> NetworkFailureNext {
+        log_warn(
+            &format!(
+                "Network error for account {}: {message}",
+                account_index + 1
+            ),
+            None,
+        );
+        {
+            let mut metrics = self.lock_metrics();
+            metrics.failed_requests += 1;
+            metrics.network_errors += 1;
+            metrics.account_rotations += 1;
+            metrics.last_error = Some(message);
+        }
+        let policy = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Network),
+                consecutive_auth_failures: None,
+                max_auth_failures_before_removal: None,
+                server_retry_after_ms: None,
+                failover_mode: Some(self.inner.config.failover_mode),
+            },
+            Some(&FailurePolicyOverrides {
+                network_cooldown_ms: Some(env.network_error_cooldown_ms as f64),
+                server_cooldown_ms: None,
+            }),
+        );
+        {
+            let mut manager = shared_manager.lock().await;
+            if policy.refund_token {
+                manager.refund_token(account_index, family, model);
+            }
+            if policy.record_failure {
+                manager.record_failure(account_index, family, model);
+            }
+        }
+        if policy.record_failure {
+            self.record_capability_failure(entitlement_key, capability_model_key);
+        }
+        if policy.retry_same_account
+            && same_account_retry_count < self.inner.config.max_same_account_retries
+        {
+            self.lock_metrics().same_account_retries += 1;
+            let delay = policy.retry_delay_ms.unwrap_or(250).max(MIN_BACKOFF_MS);
+            let _ = abortable_sleep(add_jitter(delay as f64, 0.2) as u64, None).await;
+            return NetworkFailureNext::RetrySameAccount;
+        }
+        if let (Some(cooldown_ms), Some(reason)) = (policy.cooldown_ms, policy.cooldown_reason) {
+            let mut manager = shared_manager.lock().await;
+            manager.mark_account_cooling_down(account_index, cooldown_ms, reason);
+            drop(manager);
+            shared_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        }
+        self.forget_session(affinity, session_key);
+        NetworkFailureNext::NextAccount
+    }
+}
+
+enum NetworkFailureNext {
+    RetrySameAccount,
+    NextAccount,
+}
+
+/// Spec-04 fields resolved at proxy startup, snapshotted per request.
+#[derive(Clone)]
+struct StateEnv {
+    fetch_timeout_ms: u64,
+    stream_stall_timeout_ms: i64,
+    token_refresh_skew_ms: i64,
+    network_error_cooldown_ms: i64,
+    server_error_cooldown_ms: i64,
+    token_invalidation_cooldown_ms: i64,
+    min_rotation_interval_ms: i64,
+    pid_offset_enabled: bool,
+    max_runtime_account_attempts: i64,
+    quota_remaining_percent_threshold: f64,
+    routing_mutex_mode: RoutingMutexMode,
+    scheduling_strategy: SchedulingStrategy,
+    forced_account_index: Option<i64>,
+}
+
+fn build_quota_key(family: ModelFamily, model: Option<&str>) -> String {
+    match model {
+        Some(model) => format!("{}:{model}", family.as_str()),
+        None => family.as_str().to_string(),
+    }
+}
+
+fn entitlement_key_for(account: &ManagedAccount) -> String {
+    resolve_entitlement_account_key(&EntitlementAccountRef {
+        account_id: account.meta.account_id.clone(),
+        email: account.meta.email.clone(),
+        refresh_token: Some(account.meta.refresh_token.clone()),
+        index: Some(account.index as i64),
+    })
+}
+
+/// Outbound header construction (spec 04 step 9 — the HTTP-surface
+/// authoritative scrub): copy incoming, delete hop-by-hop + `host` +
+/// `x-api-key` + `cookie` + `proxy-authorization`, set `authorization`,
+/// `chatgpt-account-id`, `OpenAI-Beta: responses=experimental`,
+/// `originator: codex_cli_rs` (load-bearing — backend gates some models per
+/// originator).
+pub fn build_outbound_headers(
+    incoming: &HeaderMap,
+    access_token: &str,
+    account_id: &str,
+) -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    for (name, value) in incoming {
+        let lower = name.as_str().to_ascii_lowercase();
+        if cma_request::stream_failover_runtime::is_hop_by_hop_header(&lower)
+            || matches!(
+                lower.as_str(),
+                "host" | "x-api-key" | "cookie" | "proxy-authorization" | "authorization"
+                    | "content-length"
+            )
+        {
+            continue;
+        }
+        headers.append(name.clone(), value.clone());
+    }
+    if let Ok(value) = HeaderValue::from_str(&format!("Bearer {access_token}")) {
+        headers.insert(http::header::AUTHORIZATION, value);
+    }
+    if let Ok(value) = HeaderValue::from_str(account_id) {
+        headers.insert("chatgpt-account-id", value);
+    }
+    headers.insert("openai-beta", HeaderValue::from_static("responses=experimental"));
+    headers.insert("originator", HeaderValue::from_static("codex_cli_rs"));
+    headers
+}
+
+/// Convert a `reqwest::Response` into the crate-standard [`StreamResponse`].
+fn stream_response_from_reqwest(response: reqwest::Response) -> StreamResponse {
+    let status = response.status();
+    let status_text = status.canonical_reason().unwrap_or("").to_string();
+    let headers = response.headers().clone();
+    let stream: BodyStream = response
+        .bytes_stream()
+        .map(|chunk| {
+            chunk.map_err(|error| {
+                Box::new(error) as cma_request::response_handler::BoxError
+            })
+        })
+        .boxed();
+    StreamResponse::new(status.as_u16(), status_text, headers, Some(stream))
+}
+
+// ===========================================================================
+// Stream failover attempt (spec 13 §5.5.4 step 2)
+// ===========================================================================
+
+#[derive(Clone)]
+struct FailoverCtx {
+    pipeline: ProxyPipeline,
+    shared_manager: SharedAccountManager,
+    candidates: Vec<i64>,
+    primary_index: i64,
+    family: ModelFamily,
+    model: Option<String>,
+    quota_key: String,
+    quota_schedule_key_base: String,
+    client_headers: HeaderMap,
+    body: Vec<u8>,
+    url: String,
+    budget: Arc<OutboundAttemptBudget>,
+    fetch_client: reqwest::Client,
+    env: StateEnv,
+    success: Arc<StdMutex<Option<FailoverSuccess>>>,
+    affinity: Option<Arc<StdMutex<SessionAffinityStore>>>,
+    session_key: Option<String>,
+    session_affinity_version: i64,
+    response_continuation_enabled: bool,
+}
+
+async fn failover_attempt(
+    ctx: FailoverCtx,
+    attempt: u32,
+    emitted_bytes: u64,
+) -> Result<Option<StreamResponse>, cma_request::response_handler::BoxError> {
+    ctx.pipeline.lock_metrics().stream_failover_attempts += 1;
+    for candidate_index in &ctx.candidates {
+        let candidate_index = *candidate_index;
+        // Availability + account snapshot.
+        let account = {
+            let mut manager = ctx.shared_manager.lock().await;
+            if !manager.is_account_available_for_family(
+                candidate_index,
+                ctx.family,
+                ctx.model.as_deref(),
+            ) {
+                continue;
+            }
+            match manager.get_account_by_index(candidate_index) {
+                Some(account) => account.clone(),
+                None => continue,
+            }
+        };
+        // Refresh (failure → warn + skip).
+        let fresh = ensure_fresh_access_token(EnsureFreshAccessTokenParams {
+            account_manager: &ctx.shared_manager,
+            account: &account,
+            family: ctx.family,
+            model: ctx.model.as_deref(),
+            now: now_ms(),
+            token_refresh_skew_ms: ctx.env.token_refresh_skew_ms,
+            token_invalidation_cooldown_ms: ctx.env.token_invalidation_cooldown_ms,
+        })
+        .await;
+        let (access_token, account) = match fresh {
+            EnsureFreshAccessTokenResult::Ok {
+                access_token,
+                account,
+            } => (access_token, account),
+            EnsureFreshAccessTokenResult::Failed { .. } => {
+                log_warn("Stream failover: token refresh failed; skipping candidate.", None);
+                continue;
+            }
+        };
+        // Identity (skip if none).
+        let current_workspace = account.get_current_workspace().cloned();
+        let stored_account_id = current_workspace
+            .as_ref()
+            .map(|workspace| workspace.id.clone())
+            .or_else(|| account.meta.account_id.clone());
+        let stored_source = if current_workspace.is_some() {
+            Some(cma_core::schemas::account_storage::AccountIdSource::Manual)
+        } else {
+            account.meta.account_id_source
+        };
+        let identity = resolve_runtime_request_identity(ResolveRuntimeRequestIdentityInput {
+            stored_account_id: stored_account_id.as_deref(),
+            source: stored_source,
+            stored_email: account.meta.email.as_deref(),
+            access_token: Some(access_token.as_str()),
+            id_token: None,
+        });
+        let Some(account_id) = identity
+            .account_id
+            .clone()
+            .filter(|id| !id.trim().is_empty())
+        else {
+            continue;
+        };
+        let entitlement_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: Some(stored_account_id.clone().unwrap_or_else(|| account_id.clone())),
+            email: identity.email.clone(),
+            refresh_token: Some(account.meta.refresh_token.clone()),
+            index: Some(candidate_index),
+        });
+        // Entitlement block check (skip + warn).
+        let blocked = {
+            let mut cache = ctx
+                .pipeline
+                .inner
+                .entitlement_cache
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            cache
+                .is_blocked(&entitlement_key, &ctx.quota_schedule_key_base, now_ms())
+                .blocked
+        };
+        if blocked {
+            log_warn("Stream failover: entitlement block; skipping candidate.", None);
+            continue;
+        }
+        // Budget consume ("stream-failover") — exhaustion ends failover
+        // entirely (returns None).
+        if !ctx.budget.try_consume() {
+            let mut metrics = ctx.pipeline.lock_metrics();
+            metrics.request_attempt_budget_exhaustions += 1;
+            metrics.last_error = Some(ctx.budget.exhausted_last_error());
+            return Ok(None);
+        }
+        ctx.pipeline.lock_metrics().outbound_request_attempts_consumed += 1;
+        // Local token bucket.
+        let consumed = {
+            let mut manager = ctx.shared_manager.lock().await;
+            manager.consume_token(candidate_index, ctx.family, ctx.model.as_deref())
+        };
+        if !consumed {
+            continue;
+        }
+        // Identity write-back (same rules as primary).
+        {
+            let mut manager = ctx.shared_manager.lock().await;
+            if let Some(live) = manager.get_account_by_index_mut(candidate_index) {
+                let had_account_id = live
+                    .meta
+                    .account_id
+                    .as_deref()
+                    .is_some_and(|id| !id.trim().is_empty());
+                live.meta.account_id = Some(account_id.clone());
+                if !had_account_id
+                    && identity
+                        .token_account_id
+                        .as_deref()
+                        .is_some_and(|token_id| token_id == account_id)
+                {
+                    live.meta.account_id_source = stored_source.or(Some(
+                        cma_core::schemas::account_storage::AccountIdSource::Token,
+                    ));
+                }
+                if let Some(email) = identity.email.clone() {
+                    live.meta.email = Some(email);
+                }
+            }
+        }
+        let headers = build_outbound_headers(&ctx.client_headers, &access_token, &account_id);
+        {
+            let mut metrics = ctx.pipeline.lock_metrics();
+            metrics.total_requests += 1;
+            metrics.responses_requests += 1;
+        }
+        let fetch_result = tokio::time::timeout(
+            std::time::Duration::from_millis(ctx.env.fetch_timeout_ms),
+            ctx.fetch_client
+                .post(&ctx.url)
+                .headers(headers)
+                .body(ctx.body.clone())
+                .send(),
+        )
+        .await;
+        let upstream = match fetch_result {
+            Ok(Ok(response)) => response,
+            Ok(Err(error)) => {
+                let mut manager = ctx.shared_manager.lock().await;
+                manager.refund_token(candidate_index, ctx.family, ctx.model.as_deref());
+                manager.record_failure(candidate_index, ctx.family, ctx.model.as_deref());
+                drop(manager);
+                ctx.pipeline
+                    .record_capability_failure(&entitlement_key, &ctx.quota_schedule_key_base);
+                log_warn(
+                    &format!("Stream failover fetch error: {error}"),
+                    None,
+                );
+                continue;
+            }
+            Err(_elapsed) => {
+                let mut manager = ctx.shared_manager.lock().await;
+                manager.refund_token(candidate_index, ctx.family, ctx.model.as_deref());
+                manager.record_failure(candidate_index, ctx.family, ctx.model.as_deref());
+                drop(manager);
+                ctx.pipeline
+                    .record_capability_failure(&entitlement_key, &ctx.quota_schedule_key_base);
+                continue;
+            }
+        };
+        let response = stream_response_from_reqwest(upstream);
+        // Quota scheduler update with the FALLBACK key.
+        let fallback_schedule_key =
+            format!("{entitlement_key}:{}", ctx.quota_schedule_key_base);
+        if let Some(snapshot) =
+            read_quota_scheduler_snapshot(&response.headers, response.status, now_ms())
+        {
+            let mut scheduler = ctx
+                .pipeline
+                .inner
+                .preemptive_scheduler
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            scheduler.update(&fallback_schedule_key, snapshot);
+        }
+        if !response.ok() {
+            let handled = handle_error_response(response, None).await;
+            if handled.response.status == 429 {
+                let retry_after_ms = handled
+                    .rate_limit
+                    .as_ref()
+                    .map(|info| info.retry_after_ms)
+                    .filter(|ms| *ms > 0)
+                    .unwrap_or(60_000);
+                // No stable-account-key 4th arg on the failover path
+                // (gotcha 12); reason hardcoded "quota".
+                let backoff = get_rate_limit_backoff(
+                    candidate_index as usize,
+                    &ctx.quota_key,
+                    Some(retry_after_ms as f64),
+                    None,
+                );
+                let cooldown_ms = backoff.delay_ms.max(retry_after_ms);
+                {
+                    let mut scheduler = ctx
+                        .pipeline
+                        .inner
+                        .preemptive_scheduler
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    scheduler.mark_rate_limited(
+                        &fallback_schedule_key,
+                        cooldown_ms as f64,
+                        now_ms(),
+                    );
+                }
+                {
+                    let mut manager = ctx.shared_manager.lock().await;
+                    manager.mark_rate_limited_with_reason(
+                        candidate_index,
+                        cooldown_ms,
+                        ctx.family,
+                        RateLimitReason::Quota,
+                        ctx.model.as_deref(),
+                    );
+                    manager.record_rate_limit(
+                        candidate_index,
+                        ctx.family,
+                        ctx.model.as_deref(),
+                    );
+                }
+                ctx.shared_manager
+                    .save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            } else {
+                let mut manager = ctx.shared_manager.lock().await;
+                manager.record_failure(candidate_index, ctx.family, ctx.model.as_deref());
+                drop(manager);
+                ctx.pipeline
+                    .record_capability_failure(&entitlement_key, &ctx.quota_schedule_key_base);
+            }
+            continue;
+        }
+        // Fallback success.
+        let cross_account = candidate_index != ctx.primary_index;
+        {
+            let mut success = ctx
+                .success
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            *success = Some(FailoverSuccess {
+                index: candidate_index,
+                entitlement_key: entitlement_key.clone(),
+                cross_account,
+            });
+        }
+        {
+            let mut metrics = ctx.pipeline.lock_metrics();
+            metrics.stream_failover_recoveries += 1;
+            if cross_account {
+                metrics.stream_failover_cross_account_recoveries += 1;
+                metrics.account_rotations += 1;
+            }
+        }
+        if cross_account
+            && !ctx.response_continuation_enabled
+            && let Some(store) = ctx.affinity.as_ref()
+        {
+            store
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner())
+                .remember_with_version(
+                    ctx.session_key.as_deref(),
+                    candidate_index,
+                    now_ms(),
+                    Some(ctx.session_affinity_version),
+                );
+        }
+        let data = serde_json::json!({ "emittedBytes": emitted_bytes });
+        log_info(
+            &format!(
+                "Recovered stream via failover attempt {attempt} using account {}.",
+                candidate_index + 1
+            ),
+            Some(&data),
+        );
+        return Ok(Some(response));
+    }
+    Ok(None)
+}
+
+/// Sticky min-rotation boost (spec 04 rotation loop step 1), merged into a
+/// FRESH clone of the base capability+policy boost map. TS recomputes this on
+/// EVERY iteration of the account-attempt while-loop
+/// (runtime-rotation-proxy.ts:956-961), re-reading `lastGlobalAccountIndex` /
+/// `lastGlobalSwitchAt` — so attempts that span the min-rotation window (429
+/// short-retry sleeps, stream-failover waits) or race a concurrent request
+/// drop or retarget the boost mid-request instead of applying a frozen one.
+/// Cloning per call (instead of `+=` into a persistent map) also guarantees
+/// the boost can never stack across attempts.
+fn merge_sticky_min_rotation_boost(
+    base: &HashMap<i64, f64>,
+    min_rotation_interval_ms: i64,
+    last_global_account_index: Option<i64>,
+    last_global_switch_at: i64,
+    now_ms: i64,
+) -> HashMap<i64, f64> {
+    let mut boosts = base.clone();
+    if min_rotation_interval_ms > 0
+        && let Some(last_index) = last_global_account_index
+        && now_ms - last_global_switch_at < min_rotation_interval_ms
+    {
+        *boosts.entry(last_index).or_insert(0.0) += 1_000.0;
+    }
+    boosts
+}
+
+#[cfg(test)]
+mod sticky_boost_tests {
+    use super::*;
+
+    /// Finding: the sticky boost must be recomputed per attempt from the
+    /// CURRENT rotation state, not frozen per traversal — and re-merging
+    /// must never stack +1000 across attempts.
+    #[test]
+    fn sticky_boost_is_recomputed_per_attempt_and_never_stacks() {
+        let mut base = HashMap::new();
+        base.insert(0_i64, 5.0_f64);
+
+        // Within the min-rotation window: +1000 on the sticky account.
+        let attempt1 = merge_sticky_min_rotation_boost(&base, 60_000, Some(0), 1_000, 2_000);
+        assert_eq!(attempt1.get(&0), Some(&1_005.0));
+
+        // A later attempt re-reads state: window expired -> boost dropped
+        // (a frozen per-traversal map would still carry +1000 here).
+        let attempt2 = merge_sticky_min_rotation_boost(&base, 60_000, Some(0), 1_000, 61_001);
+        assert_eq!(attempt2.get(&0), Some(&5.0));
+
+        // Concurrent request moved the sticky index: boost retargets.
+        let attempt3 = merge_sticky_min_rotation_boost(&base, 60_000, Some(1), 2_500, 3_000);
+        assert_eq!(attempt3.get(&0), Some(&5.0));
+        assert_eq!(attempt3.get(&1), Some(&1_000.0));
+
+        // Re-merging from the same base never stacks (fresh clone per call).
+        for _ in 0..3 {
+            let again = merge_sticky_min_rotation_boost(&base, 60_000, Some(0), 1_000, 2_000);
+            assert_eq!(again.get(&0), Some(&1_005.0));
+        }
+        // Base map untouched.
+        assert_eq!(base.get(&0), Some(&5.0));
+
+        // Disabled interval or no sticky index: base passes through.
+        assert_eq!(
+            merge_sticky_min_rotation_boost(&base, 0, Some(0), 1_000, 1_500),
+            base
+        );
+        assert_eq!(
+            merge_sticky_min_rotation_boost(&base, 60_000, None, 1_000, 1_500),
+            base
+        );
+    }
+}
diff --git a/crates/proxy/src/retry_loop.rs b/crates/proxy/src/retry_loop.rs
new file mode 100644
index 000000000..d049600f9
--- /dev/null
+++ b/crates/proxy/src/retry_loop.rs
@@ -0,0 +1,508 @@
+//! Retry counters, attempt budgets and terminal synthetic bodies for the
+//! merged rotation pipeline (index.ts §5.3–§5.5.5 ∪ proxy loop, spec 13+04).
+//!
+//! Owns:
+//! - the outer-loop retry counters that SURVIVE model-fallback restarts
+//!   (spec 13 gotcha 7);
+//! - the per-request outbound attempt budget bookkeeping (spec 13 §5.4;
+//!   cap 6 via `compute_outbound_request_attempt_budget`);
+//! - the 429 short-retry decision (`MAX_SHORT_RETRY_ATTEMPTS = 3`,
+//!   cooldown ≤ threshold) — the MARK-BEFORE-SLEEP side effects live in the
+//!   pipeline, the decision here (spec 13 §5.5.3 step 8, gotcha 5);
+//! - every terminal synthetic JSON body: pool-exhaustion / server-burst
+//!   fast-fails, budget exhaustion, the spec-04 `writePoolExhausted`
+//!   contract body, and the spec-13 terminal messages (frozen strings,
+//!   spec 13 gotcha 29 / spec 04 §14).
+
+use std::collections::HashMap;
+
+use cma_request::fetch_helpers::SyntheticResponse;
+use cma_request::rate_limit_backoff::MAX_SHORT_RETRY_ATTEMPTS;
+use http::HeaderMap;
+use http::header::HeaderValue;
+use serde_json::{Map, Value, json};
+
+/// Counters that live OUTSIDE the outer (model-fallback) loop — they do NOT
+/// reset when a fallback restarts account traversal (spec 13 gotcha 7).
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct RetryCounters {
+    /// `allRateLimitedRetries` — wait-and-retry cycles after full pool
+    /// rate-limit exhaustion (§5.5.5).
+    pub all_rate_limited_retries: i64,
+    /// `emptyResponseRetries` — outer counter, distinct from the metric of
+    /// the same name (§5.5.4 step 4).
+    pub empty_response_retries: i64,
+}
+
+/// Per-request outbound attempt budget (spec 13 §5.4). The pipeline
+/// increments its metrics alongside; this struct is the pure remaining-count
+/// bookkeeping shared with the stream-failover closure.
+#[derive(Debug)]
+pub struct OutboundAttemptBudget {
+    budget: u32,
+    remaining: std::sync::atomic::AtomicI64,
+}
+
+impl OutboundAttemptBudget {
+    pub fn new(budget: u32) -> Self {
+        Self {
+            budget,
+            remaining: std::sync::atomic::AtomicI64::new(budget as i64),
+        }
+    }
+
+    /// The computed budget (recorded into `runtimeMetrics
+    /// .outboundRequestAttemptBudget` via `??=` — first request only,
+    /// spec 13 gotcha 15).
+    pub fn budget(&self) -> u32 {
+        self.budget
+    }
+
+    /// `tryConsumeOutboundRequestAttempt` minus the metrics/log side
+    /// effects: `false` when the budget is exhausted.
+    pub fn try_consume(&self) -> bool {
+        self.remaining
+            .fetch_update(
+                std::sync::atomic::Ordering::SeqCst,
+                std::sync::atomic::Ordering::SeqCst,
+                |remaining| (remaining > 0).then_some(remaining - 1),
+            )
+            .is_ok()
+    }
+
+    /// `lastError` set when consumption fails (frozen string).
+    pub fn exhausted_last_error(&self) -> String {
+        format!(
+            "Request attempt budget exhausted after {} outbound request(s)",
+            self.budget
+        )
+    }
+}
+
+/// 429 short-retry decision (spec 13 §5.5.3 step 8). The caller MUST apply
+/// mark-before-sleep on `ShortRetry` (mark rate-limited + debounced save
+/// BEFORE sleeping — AUDIT-H3 / D-07, spec 13 gotcha 5).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RateLimit429Decision {
+    /// Same-account retry after `sleep(addJitter(max(100, cooldownMs), 0.2))`.
+    ShortRetry,
+    /// Full rotation to the next account.
+    Rotate,
+}
+
+/// `cooldownMs <= shortRetryThresholdMs && shortRateLimitRetryCount <
+/// MAX_SHORT_RETRY_ATTEMPTS` → short retry.
+pub fn decide_rate_limit_429(
+    cooldown_ms: i64,
+    short_retry_threshold_ms: i64,
+    short_rate_limit_retry_count: u32,
+) -> RateLimit429Decision {
+    if cooldown_ms <= short_retry_threshold_ms
+        && short_rate_limit_retry_count < MAX_SHORT_RETRY_ATTEMPTS
+    {
+        RateLimit429Decision::ShortRetry
+    } else {
+        RateLimit429Decision::Rotate
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Synthetic JSON bodies (frozen strings)
+// ---------------------------------------------------------------------------
+
+/// `content-type: application/json; charset=utf-8` header map used by every
+/// synthetic response emitted from the pipeline.
+pub fn synthetic_json_headers() -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        http::header::CONTENT_TYPE,
+        HeaderValue::from_static("application/json; charset=utf-8"),
+    );
+    headers
+}
+
+/// `{"error":{"message": <message>}}` (compact — TS `JSON.stringify`).
+pub fn error_message_body(message: &str) -> String {
+    serde_json::to_string(&json!({"error": {"message": message}}))
+        .expect("static shape serializes")
+}
+
+/// Build a buffered synthetic response with the standard JSON content type.
+pub fn synthetic_json_response(status: u16, body: String) -> SyntheticResponse {
+    SyntheticResponse {
+        status,
+        status_text: String::new(),
+        headers: synthetic_json_headers(),
+        body,
+    }
+}
+
+/// Pool-exhaustion fast-fail 429 message (spec 13 §5.3).
+pub fn pool_exhaustion_cooldown_message(wait_label: &str) -> String {
+    format!(
+        "The account pool is cooling down after recent rate-limit exhaustion. Try again in {wait_label} or inspect `codex-multi-auth status`."
+    )
+}
+
+/// Server-burst fast-fail 503 message (spec 13 §5.3).
+pub fn server_burst_cooldown_message(wait_label: &str) -> String {
+    format!(
+        "Multiple accounts recently failed with upstream server errors. Try again in {wait_label} or inspect `codex-multi-auth report --json`."
+    )
+}
+
+/// Empty-response-exhausted server-burst 503 message (spec 13 §5.5.4 step 4;
+/// gotcha 22 — wait label computed at response-build time).
+pub fn empty_response_server_burst_message(wait_label: &str) -> String {
+    format!(
+        "Upstream server failures were observed across multiple accounts. Pausing retries for {wait_label}. Check `codex-multi-auth report --json` for runtime metrics."
+    )
+}
+
+/// Budget-exhausted 503 message (spec 13 §5.4).
+pub fn budget_exhausted_response_message(last_error: Option<&str>) -> String {
+    match last_error {
+        Some(detail) => format!("{detail}. Try again after the current retries settle."),
+        None => "Request attempt budget exhausted. Try again shortly.".to_string(),
+    }
+}
+
+/// Terminal pool-exhaustion messages (spec 13 §5.5.5) — become
+/// `runtimeMetrics.lastError` and drive the fast-fail cooldown arming.
+pub fn terminal_pool_message(count: usize, effective_wait_ms: i64, wait_label: &str) -> String {
+    if count == 0 {
+        "No Codex accounts configured. Run `codex-multi-auth login`.".to_string()
+    } else if effective_wait_ms > 0 {
+        format!(
+            "All {count} account(s) are rate-limited. A short pool cooldown is now active for {wait_label}. Try again later or inspect `codex-multi-auth status`."
+        )
+    } else {
+        format!(
+            "All {count} account(s) failed (server errors or auth issues). Check account health with `codex-multi-auth report --json`."
+        )
+    }
+}
+
+/// Countdown toast prefix for the all-rate-limited wait (spec 13 §5.5.5).
+pub fn all_rate_limited_countdown_message(count: usize) -> String {
+    format!("All {count} account(s) rate-limited. Waiting")
+}
+
+/// The spec-04 `writePoolExhausted` body (stable machine-readable contract,
+/// spec 04 §14 / lib/runtime-rotation-proxy.ts):
+///
+/// ```json
+/// {"error":{"message":"All managed Codex accounts are temporarily unavailable for this runtime request.",
+///   "code":"codex_runtime_rotation_pool_exhausted","reason":"...",
+///   "retry_after_ms":N,"account_skip_reasons":{"0":"..."},"hint":"..."}}
+/// ```
+///
+/// Key order matches the TS object literal (serde_json preserve_order).
+pub fn build_pool_exhausted_body(
+    reason: &str,
+    retry_after_ms: i64,
+    account_skip_reasons: &HashMap<i64, String>,
+    account_count: usize,
+) -> String {
+    let hint = pool_exhausted_hint(reason, account_count);
+    let mut skip_map = Map::new();
+    let mut indexes: Vec<&i64> = account_skip_reasons.keys().collect();
+    indexes.sort();
+    for index in indexes {
+        skip_map.insert(
+            index.to_string(),
+            Value::String(account_skip_reasons[index].clone()),
+        );
+    }
+    let mut error = Map::new();
+    error.insert(
+        "message".to_string(),
+        Value::String(
+            "All managed Codex accounts are temporarily unavailable for this runtime request."
+                .to_string(),
+        ),
+    );
+    error.insert(
+        "code".to_string(),
+        Value::String("codex_runtime_rotation_pool_exhausted".to_string()),
+    );
+    error.insert("reason".to_string(), Value::String(reason.to_string()));
+    error.insert("retry_after_ms".to_string(), Value::from(retry_after_ms));
+    error.insert("account_skip_reasons".to_string(), Value::Object(skip_map));
+    error.insert("hint".to_string(), Value::String(hint));
+    let mut root = Map::new();
+    root.insert("error".to_string(), Value::Object(error));
+    serde_json::to_string(&Value::Object(root)).expect("static shape serializes")
+}
+
+/// The exact hint strings from `writePoolExhausted` (spec 04).
+pub fn pool_exhausted_hint(reason: &str, account_count: usize) -> String {
+    if reason == "no-account" && account_count > 0 {
+        "Accounts exist but all failed runtime availability checks. Run `codex-multi-auth report --json` to inspect runtime skip reasons, or `codex-multi-auth rotation reset-runtime` to reload the runtime proxy.".to_string()
+    } else {
+        "Run `codex-multi-auth rotation status` to inspect account state.".to_string()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Empty-response retry decision (spec 13 §5.5.4 step 4)
+// ---------------------------------------------------------------------------
+
+/// What to do after `isEmptyResponse(parsed)` returned true with retries
+/// remaining. Effects (refund + recordFailure + capability recordFailure +
+/// metrics + toast) are the pipeline's; the policy fork is decided here.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EmptyResponseRetryAction {
+    /// `policy.retrySameAccount && sameAccountRetryCount <
+    /// maxSameAccountRetries` — sleep `delay` (jittered only when > 0) and
+    /// continue the inner loop.
+    SameAccount { delay_ms: i64 },
+    /// Forget the session, sleep `addJitter(emptyResponseRetryDelayMs, 0.2)`,
+    /// break to the next account.
+    NextAccount,
+}
+
+/// Decide the empty-response retry fork from the failure-policy decision.
+pub fn decide_empty_response_retry(
+    policy_retry_same_account: bool,
+    policy_retry_delay_ms: Option<i64>,
+    same_account_retry_count: u32,
+    max_same_account_retries: u32,
+    empty_response_retry_delay_ms: i64,
+) -> EmptyResponseRetryAction {
+    if policy_retry_same_account && same_account_retry_count < max_same_account_retries {
+        let delay = policy_retry_delay_ms
+            .unwrap_or(empty_response_retry_delay_ms)
+            .max(0);
+        EmptyResponseRetryAction::SameAccount { delay_ms: delay }
+    } else {
+        EmptyResponseRetryAction::NextAccount
+    }
+}
+
+/// "Empty response. Retrying (<i>/<max>)..." toast (spec 13 §5.5.4).
+pub fn empty_response_retry_toast(attempt: i64, max: i64) -> String {
+    format!("Empty response. Retrying ({attempt}/{max})...")
+}
+
+/// Rate-limit short-retry toast (spec 13 §5.5.3 step 8).
+pub fn short_retry_toast(wait_label: &str, attempt: u32) -> String {
+    format!("Rate limited. Retrying in {wait_label} (attempt {attempt})...")
+}
+
+/// Rate-limit rotation toast (spec 13 §5.5.3 step 8).
+pub fn rate_limit_rotation_toast(wait_label: &str) -> String {
+    format!("Rate limited. Switching accounts (retry in {wait_label}).")
+}
+
+/// Account-removal toast after consecutive auth failures (spec 13 §5.5.1).
+pub fn auth_failure_removal_toast(label: &str, failures: u32) -> String {
+    format!(
+        "Removed {label} after {failures} consecutive auth failures. Run 'codex-multi-auth login' to re-add."
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn budget_consumes_down_to_zero() {
+        let budget = OutboundAttemptBudget::new(2);
+        assert!(budget.try_consume());
+        assert!(budget.try_consume());
+        assert!(!budget.try_consume());
+        assert!(!budget.try_consume());
+        assert_eq!(budget.budget(), 2);
+        assert_eq!(
+            budget.exhausted_last_error(),
+            "Request attempt budget exhausted after 2 outbound request(s)"
+        );
+    }
+
+    #[test]
+    fn short_retry_decision_honors_threshold_and_cap() {
+        assert_eq!(
+            decide_rate_limit_429(1_000, 5_000, 0),
+            RateLimit429Decision::ShortRetry
+        );
+        // Above threshold → rotate.
+        assert_eq!(
+            decide_rate_limit_429(6_000, 5_000, 0),
+            RateLimit429Decision::Rotate
+        );
+        // Cap of MAX_SHORT_RETRY_ATTEMPTS (3).
+        assert_eq!(
+            decide_rate_limit_429(1_000, 5_000, 2),
+            RateLimit429Decision::ShortRetry
+        );
+        assert_eq!(
+            decide_rate_limit_429(1_000, 5_000, 3),
+            RateLimit429Decision::Rotate
+        );
+        // Equal to threshold is a short retry (`<=`).
+        assert_eq!(
+            decide_rate_limit_429(5_000, 5_000, 0),
+            RateLimit429Decision::ShortRetry
+        );
+    }
+
+    #[test]
+    fn error_body_shape_is_compact_json() {
+        assert_eq!(
+            error_message_body("boom"),
+            r#"{"error":{"message":"boom"}}"#
+        );
+    }
+
+    #[test]
+    fn frozen_fast_fail_messages() {
+        assert_eq!(
+            pool_exhaustion_cooldown_message("2m"),
+            "The account pool is cooling down after recent rate-limit exhaustion. Try again in 2m or inspect `codex-multi-auth status`."
+        );
+        assert_eq!(
+            server_burst_cooldown_message("30s"),
+            "Multiple accounts recently failed with upstream server errors. Try again in 30s or inspect `codex-multi-auth report --json`."
+        );
+        assert_eq!(
+            empty_response_server_burst_message("30s"),
+            "Upstream server failures were observed across multiple accounts. Pausing retries for 30s. Check `codex-multi-auth report --json` for runtime metrics."
+        );
+    }
+
+    #[test]
+    fn budget_exhausted_message_variants() {
+        assert_eq!(
+            budget_exhausted_response_message(Some("Request attempt budget exhausted after 6 outbound request(s)")),
+            "Request attempt budget exhausted after 6 outbound request(s). Try again after the current retries settle."
+        );
+        assert_eq!(
+            budget_exhausted_response_message(None),
+            "Request attempt budget exhausted. Try again shortly."
+        );
+    }
+
+    #[test]
+    fn terminal_pool_messages() {
+        assert_eq!(
+            terminal_pool_message(0, 0, "a bit"),
+            "No Codex accounts configured. Run `codex-multi-auth login`."
+        );
+        assert_eq!(
+            terminal_pool_message(3, 60_000, "1m"),
+            "All 3 account(s) are rate-limited. A short pool cooldown is now active for 1m. Try again later or inspect `codex-multi-auth status`."
+        );
+        assert_eq!(
+            terminal_pool_message(2, 0, "a bit"),
+            "All 2 account(s) failed (server errors or auth issues). Check account health with `codex-multi-auth report --json`."
+        );
+        assert_eq!(
+            all_rate_limited_countdown_message(4),
+            "All 4 account(s) rate-limited. Waiting"
+        );
+    }
+
+    #[test]
+    fn pool_exhausted_body_matches_ts_contract() {
+        let mut skip = HashMap::new();
+        skip.insert(0i64, "rate-limited".to_string());
+        skip.insert(1i64, "cooling-down:server-error".to_string());
+        let body = build_pool_exhausted_body("rate-limit", 12_345, &skip, 2);
+        let parsed: Value = serde_json::from_str(&body).unwrap();
+        let error = &parsed["error"];
+        assert_eq!(
+            error["message"],
+            "All managed Codex accounts are temporarily unavailable for this runtime request."
+        );
+        assert_eq!(error["code"], "codex_runtime_rotation_pool_exhausted");
+        assert_eq!(error["reason"], "rate-limit");
+        assert_eq!(error["retry_after_ms"], 12_345);
+        assert_eq!(error["account_skip_reasons"]["0"], "rate-limited");
+        assert_eq!(
+            error["account_skip_reasons"]["1"],
+            "cooling-down:server-error"
+        );
+        assert_eq!(
+            error["hint"],
+            "Run `codex-multi-auth rotation status` to inspect account state."
+        );
+        // Key order: message, code, reason, retry_after_ms,
+        // account_skip_reasons, hint (TS object-literal order).
+        let keys: Vec<&String> = error.as_object().unwrap().keys().collect();
+        assert_eq!(
+            keys,
+            [
+                "message",
+                "code",
+                "reason",
+                "retry_after_ms",
+                "account_skip_reasons",
+                "hint"
+            ]
+        );
+    }
+
+    #[test]
+    fn pool_exhausted_hint_no_account_with_accounts_present() {
+        assert_eq!(
+            pool_exhausted_hint("no-account", 2),
+            "Accounts exist but all failed runtime availability checks. Run `codex-multi-auth report --json` to inspect runtime skip reasons, or `codex-multi-auth rotation reset-runtime` to reload the runtime proxy."
+        );
+        assert_eq!(
+            pool_exhausted_hint("no-account", 0),
+            "Run `codex-multi-auth rotation status` to inspect account state."
+        );
+        assert_eq!(
+            pool_exhausted_hint("rate-limit", 2),
+            "Run `codex-multi-auth rotation status` to inspect account state."
+        );
+    }
+
+    #[test]
+    fn empty_response_retry_forks() {
+        assert_eq!(
+            decide_empty_response_retry(true, Some(200), 0, 1, 750),
+            EmptyResponseRetryAction::SameAccount { delay_ms: 200 }
+        );
+        // Policy delay missing → config delay.
+        assert_eq!(
+            decide_empty_response_retry(true, None, 0, 1, 750),
+            EmptyResponseRetryAction::SameAccount { delay_ms: 750 }
+        );
+        // Same-account retries exhausted → next account.
+        assert_eq!(
+            decide_empty_response_retry(true, Some(200), 1, 1, 750),
+            EmptyResponseRetryAction::NextAccount
+        );
+        assert_eq!(
+            decide_empty_response_retry(false, Some(200), 0, 1, 750),
+            EmptyResponseRetryAction::NextAccount
+        );
+        // Negative policy delay clamps at 0 (`max(0, floor(...))`).
+        assert_eq!(
+            decide_empty_response_retry(true, Some(-5), 0, 1, 750),
+            EmptyResponseRetryAction::SameAccount { delay_ms: 0 }
+        );
+    }
+
+    #[test]
+    fn frozen_toasts() {
+        assert_eq!(
+            empty_response_retry_toast(1, 2),
+            "Empty response. Retrying (1/2)..."
+        );
+        assert_eq!(
+            short_retry_toast("5s", 1),
+            "Rate limited. Retrying in 5s (attempt 1)..."
+        );
+        assert_eq!(
+            rate_limit_rotation_toast("1m"),
+            "Rate limited. Switching accounts (retry in 1m)."
+        );
+        assert_eq!(
+            auth_failure_removal_toast("user@example.com", 3),
+            "Removed user@example.com after 3 consecutive auth failures. Run 'codex-multi-auth login' to re-add."
+        );
+    }
+}
diff --git a/crates/proxy/src/router.rs b/crates/proxy/src/router.rs
new file mode 100644
index 000000000..fc158605e
--- /dev/null
+++ b/crates/proxy/src/router.rs
@@ -0,0 +1,672 @@
+//! Port of `scripts/codex-app-router.js` — the detached app-bind router
+//! process (ARCHITECTURE R3: new `codex-multi-auth-app-router` binary).
+//!
+//! Responsibilities:
+//! - parse `--host/--port/--status/--state/--log/--max-log-bytes`;
+//! - read the app-bind state JSON (host/port/clientApiKey/statusPath) and
+//!   refuse to run without a valid loopback host, port, and client token
+//!   (frozen error messages);
+//! - start the runtime rotation proxy ([`crate::server`]);
+//! - write the app-bind status JSON (`runtime-rotation-app-bind-status.json`,
+//!   kind `codex-app-runtime-rotation-router`, 2-space JSON + trailing `\n`,
+//!   0600, atomic temp+rename, best-effort) on a heartbeat;
+//! - bound its own log file size (1 MiB default, checked every 60 s);
+//! - clean shutdown on SIGINT (130) / SIGTERM / SIGHUP (0);
+//! - idle-exit via `CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS` (R3 merge of the
+//!   TS app-helper idle loop: default 12 h, floor 50 ms, activity = the
+//!   proxy's `totalRequests` advancing; exits with status state
+//!   `"idle-timeout"`).
+
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use serde_json::{Map, Value, json};
+
+use cma_core::json_io::stringify_pretty2;
+use cma_core::utils::now_ms;
+use cma_runtime::rotation::server_types::{
+    RuntimeRotationProxyOptions, RuntimeRotationProxyStatus,
+};
+
+use crate::server::{RuntimeRotationProxyServer, start_runtime_rotation_proxy};
+
+/// TS `DEFAULT_MAX_LOG_BYTES`.
+pub const DEFAULT_MAX_LOG_BYTES: u64 = 1024 * 1024;
+/// TS `LOG_SIZE_CHECK_INTERVAL_MS`.
+pub const LOG_SIZE_CHECK_INTERVAL_MS: i64 = 60_000;
+/// TS `DEFAULT_APP_RUNTIME_HELPER_IDLE_MS` (scripts/codex.js) — 12 hours.
+pub const DEFAULT_IDLE_TIMEOUT_MS: i64 = 12 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Argument / state parsing
+// ---------------------------------------------------------------------------
+
+/// TS `parsePort` — digits-only 0..=65535, else invalid (`NaN` → `None`).
+pub fn parse_port(value: Option<&str>) -> Option<u16> {
+    let text = value?.trim();
+    if text.is_empty() || !text.bytes().all(|byte| byte.is_ascii_digit()) {
+        return None;
+    }
+    let port: u64 = text.parse().ok()?;
+    u16::try_from(port).ok()
+}
+
+/// TS `parseArgs` result.
+#[derive(Debug, Clone, PartialEq)]
+pub struct RouterArgs {
+    pub host: String,
+    /// `None` = the TS `NaN` (invalid/absent `--port` value).
+    pub port: Option<u16>,
+    pub status_path: String,
+    pub state_path: String,
+    pub log_path: String,
+    pub max_log_bytes: u64,
+}
+
+/// TS `parseArgs(argv)`.
+pub fn parse_args(argv: &[String]) -> RouterArgs {
+    let mut result = RouterArgs {
+        host: "127.0.0.1".to_string(),
+        port: Some(0),
+        status_path: String::new(),
+        state_path: String::new(),
+        log_path: String::new(),
+        max_log_bytes: DEFAULT_MAX_LOG_BYTES,
+    };
+    let mut index = 0;
+    while index < argv.len() {
+        let arg = argv[index].as_str();
+        let next = argv.get(index + 1).map(String::as_str).unwrap_or("");
+        match arg {
+            "--host" => {
+                result.host = next.to_string();
+                index += 1;
+            }
+            "--port" => {
+                result.port = parse_port(Some(next));
+                index += 1;
+            }
+            "--status" => {
+                result.status_path = next.to_string();
+                index += 1;
+            }
+            "--state" => {
+                result.state_path = next.to_string();
+                index += 1;
+            }
+            "--max-log-bytes" => {
+                result.max_log_bytes = match next.trim().parse::<i64>() {
+                    Ok(parsed) if parsed > 0 => parsed as u64,
+                    _ => DEFAULT_MAX_LOG_BYTES,
+                };
+                index += 1;
+            }
+            "--log" => {
+                result.log_path = next.to_string();
+                index += 1;
+            }
+            _ => {}
+        }
+        index += 1;
+    }
+    result
+}
+
+/// TS `readState(path)` — unreadable/unparseable → `None`.
+fn read_state(path: &str) -> Option<Map<String, Value>> {
+    if path.is_empty() {
+        return None;
+    }
+    let raw = std::fs::read_to_string(path).ok()?;
+    match serde_json::from_str::<Value>(&raw).ok()? {
+        Value::Object(map) => Some(map),
+        _ => None,
+    }
+}
+
+/// TS `readTrimmedString(record, key)`.
+fn read_trimmed_string(record: Option<&Map<String, Value>>, key: &str) -> Option<String> {
+    let value = record?.get(key)?.as_str()?.trim();
+    if value.is_empty() {
+        None
+    } else {
+        Some(value.to_string())
+    }
+}
+
+/// TS router-local `isLoopbackHost` — unbracket, then 127.0.0.1/::1/localhost.
+fn is_loopback_host(host: &str) -> bool {
+    let normalized = host.trim().to_lowercase();
+    let unbracketed = if normalized.starts_with('[') && normalized.ends_with(']') {
+        normalized[1..normalized.len() - 1].to_string()
+    } else {
+        normalized
+    };
+    unbracketed == "127.0.0.1" || unbracketed == "::1" || unbracketed == "localhost"
+}
+
+/// TS `resolveRuntimeRotationAppHelperIdleMs` — positive int → `max(50, v)`,
+/// else the 12 h default.
+pub fn resolve_idle_timeout_ms(raw: Option<&str>) -> i64 {
+    match raw.and_then(|value| value.trim().parse::<i64>().ok()) {
+        Some(parsed) if parsed > 0 => parsed.max(50),
+        _ => DEFAULT_IDLE_TIMEOUT_MS,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Status file (best-effort atomic write, 0600)
+// ---------------------------------------------------------------------------
+
+/// TS `createStatusPayload` — key order is the JS property insertion order.
+fn create_status_payload(
+    state: &str,
+    proxy_base_url: Option<&str>,
+    proxy_status: Option<&RuntimeRotationProxyStatus>,
+    error: Option<&str>,
+    state_record: Option<&Map<String, Value>>,
+) -> Value {
+    let last_account_index = proxy_status.and_then(|status| status.last_account_index);
+    // Privacy: never publish a label containing `@` (an email leak).
+    let last_account_label = match proxy_status.and_then(|status| status.last_account_label.clone())
+    {
+        Some(label) if !label.contains('@') => Some(label),
+        _ => last_account_index.map(|index| format!("Account {}", index + 1)),
+    };
+    let base_url: Value = match proxy_base_url {
+        Some(url) => Value::String(url.to_string()),
+        None => state_record
+            .and_then(|record| record.get("baseUrl"))
+            .cloned()
+            .unwrap_or(Value::Null),
+    };
+    let last_error: Value = match error {
+        Some(error) => Value::String(error.to_string()),
+        None => proxy_status
+            .and_then(|status| status.last_error.clone())
+            .map(Value::String)
+            .unwrap_or(Value::Null),
+    };
+    json!({
+        "version": 1,
+        "kind": "codex-app-runtime-rotation-router",
+        "state": state,
+        "pid": std::process::id(),
+        "updatedAt": now_ms(),
+        "baseUrl": base_url,
+        "totalRequests": proxy_status.map(|status| status.total_requests).unwrap_or(0),
+        "upstreamRequests": proxy_status.map(|status| status.upstream_requests).unwrap_or(0),
+        "retries": proxy_status.map(|status| status.retries).unwrap_or(0),
+        "rotations": proxy_status.map(|status| status.rotations).unwrap_or(0),
+        "lastAccountIndex": last_account_index,
+        "lastAccountLabel": last_account_label,
+        "lastAccountId": proxy_status.and_then(|status| status.last_account_id.clone()),
+        "lastAccountUpdatedAt": proxy_status.and_then(|status| status.last_account_updated_at),
+        "lastError": last_error,
+    })
+}
+
+/// TS `writeStatus` — temp `.<basename>.<pid>.<now>.tmp`, 0600, 2-space JSON
+/// plus `\n`, atomic rename; every failure swallowed (status is best-effort:
+/// the router must keep serving if telemetry is locked).
+fn write_status(status_path: &str, payload: &Value) {
+    if status_path.is_empty() {
+        return;
+    }
+    let status_path = PathBuf::from(status_path);
+    let Some(status_dir) = status_path.parent() else {
+        return;
+    };
+    let basename = status_path
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default();
+    let temp_path = status_dir.join(format!(
+        ".{basename}.{}.{}.tmp",
+        std::process::id(),
+        now_ms()
+    ));
+    let content = format!("{}\n", stringify_pretty2(payload));
+    let result: std::io::Result<()> = (|| {
+        std::fs::create_dir_all(status_dir)?;
+        write_owner_only(&temp_path, &content)?;
+        std::fs::rename(&temp_path, &status_path)?;
+        set_owner_only(&status_path);
+        Ok(())
+    })();
+    if result.is_err() {
+        let _ = std::fs::remove_file(&temp_path);
+    }
+}
+
+fn write_owner_only(path: &Path, content: &str) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::io::Write;
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut file = std::fs::OpenOptions::new()
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .mode(0o600)
+            .open(path)?;
+        file.write_all(content.as_bytes())?;
+        return Ok(());
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::write(path, content)
+    }
+}
+
+fn set_owner_only(path: &Path) {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Log bounds
+// ---------------------------------------------------------------------------
+
+/// TS `truncateLogPathIfTooLarge` — truncate the log file to 0 when it
+/// exceeds `max_bytes`; all errors swallowed.
+fn truncate_log_path_if_too_large(log_path: &str, max_bytes: u64) -> bool {
+    if log_path.is_empty() || max_bytes == 0 {
+        return false;
+    }
+    let Ok(stats) = std::fs::metadata(log_path) else {
+        return false;
+    };
+    if !stats.is_file() || stats.len() <= max_bytes {
+        return false;
+    }
+    match std::fs::OpenOptions::new().write(true).open(log_path) {
+        Ok(file) => file.set_len(0).is_ok(),
+        Err(_) => false,
+    }
+}
+
+/// The truncation marker (TS wrote it to fd 1, which the spawner redirects
+/// into the log file — stdout here is that same redirect).
+fn check_log_bounds(log_path: &str, max_bytes: u64) {
+    if truncate_log_path_if_too_large(log_path, max_bytes) {
+        println!(
+            "codex-multi-auth app router log truncated after exceeding {max_bytes} bytes"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Signals
+// ---------------------------------------------------------------------------
+
+/// Resolves on SIGTERM/SIGHUP (unix); pending forever elsewhere.
+async fn terminate_signal() {
+    #[cfg(unix)]
+    {
+        use tokio::signal::unix::{SignalKind, signal};
+        let term = signal(SignalKind::terminate());
+        let hup = signal(SignalKind::hangup());
+        match (term, hup) {
+            (Ok(mut term), Ok(mut hup)) => {
+                tokio::select! {
+                    _ = term.recv() => {}
+                    _ = hup.recv() => {}
+                }
+            }
+            _ => std::future::pending::<()>().await,
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        std::future::pending::<()>().await
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/// The router process body (TS `main()` + error trailer). Returns the exit
+/// code for the thin binary main.
+pub async fn run(argv: &[String]) -> i32 {
+    match run_inner(argv).await {
+        Ok(code) => code,
+        Err(message) => {
+            eprintln!("codex-multi-auth app router failed: {message}");
+            1
+        }
+    }
+}
+
+async fn run_inner(argv: &[String]) -> Result<i32, String> {
+    let args = parse_args(argv);
+    check_log_bounds(&args.log_path, args.max_log_bytes);
+
+    let state_record = read_state(&args.state_path);
+    if !args.state_path.is_empty() && state_record.is_none() {
+        let message =
+            "Codex app runtime router state is unreadable; refusing to bind an ephemeral port."
+                .to_string();
+        write_status(
+            &args.status_path,
+            &create_status_payload("error", None, None, Some(&message), None),
+        );
+        return Err(message);
+    }
+    let host = read_trimmed_string(state_record.as_ref(), "host").unwrap_or(args.host.clone());
+    let state_port = state_record
+        .as_ref()
+        .and_then(|record| record.get("port"))
+        .and_then(|value| match value {
+            Value::Number(number) => parse_port(Some(&number.to_string())),
+            Value::String(text) => parse_port(Some(text)),
+            _ => None,
+        });
+    let port = state_port.or(args.port);
+    let client_api_key = read_trimmed_string(state_record.as_ref(), "clientApiKey");
+    let Some(port) = port else {
+        return Err(
+            "A valid --port in the range 0-65535 is required for the Codex app runtime router."
+                .to_string(),
+        );
+    };
+    if !is_loopback_host(&host) {
+        return Err(
+            "Codex app runtime router host must be loopback-only (127.0.0.1, ::1, or localhost)."
+                .to_string(),
+        );
+    }
+    let Some(client_api_key) = client_api_key else {
+        return Err("Codex app runtime router state is missing its client token.".to_string());
+    };
+
+    // Status writes prefer `--status`, then the state file's `statusPath`.
+    let status_path = if !args.status_path.is_empty() {
+        args.status_path.clone()
+    } else {
+        read_trimmed_string(state_record.as_ref(), "statusPath").unwrap_or_default()
+    };
+
+    let proxy: RuntimeRotationProxyServer = match start_runtime_rotation_proxy(
+        RuntimeRotationProxyOptions {
+            host: Some(host),
+            port: Some(port),
+            client_api_key,
+            ..Default::default()
+        },
+    )
+    .await
+    {
+        Ok(proxy) => proxy,
+        Err(error) => {
+            let message = error.to_string();
+            write_status(
+                &status_path,
+                &create_status_payload("error", None, None, Some(&message), state_record.as_ref()),
+            );
+            return Err(message);
+        }
+    };
+
+    let publish = |state: &str, status: Option<&RuntimeRotationProxyStatus>| {
+        write_status(
+            &status_path,
+            &create_status_payload(
+                state,
+                Some(&proxy.base_url),
+                status,
+                None,
+                state_record.as_ref(),
+            ),
+        );
+    };
+    {
+        let status = proxy.get_status().await;
+        publish("running", Some(&status));
+    }
+
+    // Idle-exit (R3): activity = the proxy's totalRequests advancing.
+    let idle_timeout_ms = resolve_idle_timeout_ms(
+        std::env::var("CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS").ok().as_deref(),
+    );
+    let tick_ms = 1_000.min((idle_timeout_ms / 2).max(50)) as u64;
+    let mut last_activity_at = now_ms();
+    let mut last_request_count = proxy.get_status().await.total_requests;
+    let mut last_log_check_at = now_ms();
+
+    let mut ticker = tokio::time::interval(Duration::from_millis(tick_ms.max(1)));
+    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    ticker.tick().await; // the immediate first tick
+
+    let ctrl_c = tokio::signal::ctrl_c();
+    tokio::pin!(ctrl_c);
+    let term = terminate_signal();
+    tokio::pin!(term);
+
+    loop {
+        tokio::select! {
+            _ = &mut ctrl_c => {
+                let _ = proxy.close().await;
+                let status = proxy.get_status().await;
+                publish("stopped", Some(&status));
+                return Ok(130);
+            }
+            _ = &mut term => {
+                let _ = proxy.close().await;
+                let status = proxy.get_status().await;
+                publish("stopped", Some(&status));
+                return Ok(0);
+            }
+            _ = ticker.tick() => {
+                let current_time = now_ms();
+                let status = proxy.get_status().await;
+                if status.total_requests != last_request_count {
+                    last_request_count = status.total_requests;
+                    last_activity_at = current_time;
+                }
+                publish("running", Some(&status));
+                if current_time - last_log_check_at >= LOG_SIZE_CHECK_INTERVAL_MS {
+                    last_log_check_at = current_time;
+                    check_log_bounds(&args.log_path, args.max_log_bytes);
+                }
+                if current_time - last_activity_at >= idle_timeout_ms {
+                    let _ = proxy.close().await;
+                    let status = proxy.get_status().await;
+                    publish("idle-timeout", Some(&status));
+                    return Ok(0);
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    fn args(list: &[&str]) -> Vec<String> {
+        list.iter().map(|item| item.to_string()).collect()
+    }
+
+    #[test]
+    fn parse_port_accepts_digit_strings_in_range_only() {
+        assert_eq!(parse_port(Some("0")), Some(0));
+        assert_eq!(parse_port(Some("65535")), Some(65535));
+        assert_eq!(parse_port(Some(" 1456 ")), Some(1456));
+        assert_eq!(parse_port(Some("65536")), None);
+        assert_eq!(parse_port(Some("-1")), None);
+        assert_eq!(parse_port(Some("12.5")), None);
+        assert_eq!(parse_port(Some("abc")), None);
+        assert_eq!(parse_port(Some("")), None);
+        assert_eq!(parse_port(None), None);
+    }
+
+    #[test]
+    fn parse_args_defaults_and_flags() {
+        let parsed = parse_args(&args(&[]));
+        assert_eq!(
+            parsed,
+            RouterArgs {
+                host: "127.0.0.1".to_string(),
+                port: Some(0),
+                status_path: String::new(),
+                state_path: String::new(),
+                log_path: String::new(),
+                max_log_bytes: DEFAULT_MAX_LOG_BYTES,
+            }
+        );
+
+        let parsed = parse_args(&args(&[
+            "--host", "::1", "--port", "1456", "--status", "C:/tmp/status.json", "--state",
+            "C:/tmp/state.json", "--log", "C:/tmp/router.log", "--max-log-bytes", "2048",
+        ]));
+        assert_eq!(parsed.host, "::1");
+        assert_eq!(parsed.port, Some(1456));
+        assert_eq!(parsed.status_path, "C:/tmp/status.json");
+        assert_eq!(parsed.state_path, "C:/tmp/state.json");
+        assert_eq!(parsed.log_path, "C:/tmp/router.log");
+        assert_eq!(parsed.max_log_bytes, 2048);
+
+        // Invalid --port keeps the TS NaN semantics (None), and an invalid
+        // --max-log-bytes falls back to the default.
+        let parsed = parse_args(&args(&["--port", "notaport", "--max-log-bytes", "-5"]));
+        assert_eq!(parsed.port, None);
+        assert_eq!(parsed.max_log_bytes, DEFAULT_MAX_LOG_BYTES);
+    }
+
+    #[test]
+    fn loopback_check_unbrackets_ipv6() {
+        assert!(is_loopback_host("127.0.0.1"));
+        assert!(is_loopback_host("[::1]"));
+        assert!(is_loopback_host("::1"));
+        assert!(is_loopback_host("LOCALHOST"));
+        assert!(!is_loopback_host("0.0.0.0"));
+        assert!(!is_loopback_host("example.com"));
+    }
+
+    #[test]
+    fn idle_timeout_resolution_clamps_and_defaults() {
+        assert_eq!(resolve_idle_timeout_ms(None), DEFAULT_IDLE_TIMEOUT_MS);
+        assert_eq!(resolve_idle_timeout_ms(Some("")), DEFAULT_IDLE_TIMEOUT_MS);
+        assert_eq!(resolve_idle_timeout_ms(Some("0")), DEFAULT_IDLE_TIMEOUT_MS);
+        assert_eq!(resolve_idle_timeout_ms(Some("-5")), DEFAULT_IDLE_TIMEOUT_MS);
+        assert_eq!(resolve_idle_timeout_ms(Some("10")), 50);
+        assert_eq!(resolve_idle_timeout_ms(Some("1000")), 1000);
+    }
+
+    #[test]
+    fn status_payload_shape_and_label_privacy() {
+        let status = RuntimeRotationProxyStatus {
+            started_at: 1,
+            total_requests: 7,
+            upstream_requests: 5,
+            retries: 2,
+            rotations: 3,
+            streams_started: 1,
+            last_error: Some("boom".to_string()),
+            last_account_index: Some(1),
+            last_account_label: Some("user@example.com".to_string()),
+            last_account_id: Some("acc_2".to_string()),
+            last_account_updated_at: Some(123),
+        };
+        let payload = create_status_payload(
+            "running",
+            Some("http://127.0.0.1:9999"),
+            Some(&status),
+            None,
+            None,
+        );
+        assert_eq!(payload["version"], 1);
+        assert_eq!(payload["kind"], "codex-app-runtime-rotation-router");
+        assert_eq!(payload["state"], "running");
+        assert_eq!(payload["baseUrl"], "http://127.0.0.1:9999");
+        assert_eq!(payload["totalRequests"], 7);
+        assert_eq!(payload["upstreamRequests"], 5);
+        assert_eq!(payload["retries"], 2);
+        assert_eq!(payload["rotations"], 3);
+        assert_eq!(payload["lastAccountIndex"], 1);
+        // Labels containing "@" are replaced with the index-derived label.
+        assert_eq!(payload["lastAccountLabel"], "Account 2");
+        assert_eq!(payload["lastAccountId"], "acc_2");
+        assert_eq!(payload["lastError"], "boom");
+
+        // Error argument overrides the proxy lastError; missing proxy state
+        // zeroes the counters and nulls the identity fields.
+        let payload = create_status_payload("error", None, None, Some("bad state"), None);
+        assert_eq!(payload["state"], "error");
+        assert_eq!(payload["baseUrl"], Value::Null);
+        assert_eq!(payload["totalRequests"], 0);
+        assert_eq!(payload["lastAccountIndex"], Value::Null);
+        assert_eq!(payload["lastAccountLabel"], Value::Null);
+        assert_eq!(payload["lastError"], "bad state");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn run_fails_with_frozen_messages_for_bad_state() {
+        let sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        let dir = sandbox.root().to_path_buf();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            // Unreadable state file → error status written + exit 1.
+            let state_path = dir.join("state.json");
+            std::fs::write(&state_path, "{ not json").unwrap();
+            let status_path = dir.join("status.json");
+            let code = run(&[
+                "--state".to_string(),
+                state_path.to_string_lossy().into_owned(),
+                "--status".to_string(),
+                status_path.to_string_lossy().into_owned(),
+            ])
+            .await;
+            assert_eq!(code, 1);
+            let written: Value =
+                serde_json::from_str(&std::fs::read_to_string(&status_path).unwrap()).unwrap();
+            assert_eq!(written["state"], "error");
+            assert_eq!(written["kind"], "codex-app-runtime-rotation-router");
+            assert_eq!(
+                written["lastError"],
+                "Codex app runtime router state is unreadable; refusing to bind an ephemeral port."
+            );
+
+            // Missing client token in a readable state → exit 1 (no status
+            // write required on this path).
+            std::fs::write(
+                &state_path,
+                r#"{"host":"127.0.0.1","port":0,"statusPath":""}"#,
+            )
+            .unwrap();
+            let code = run(&[
+                "--state".to_string(),
+                state_path.to_string_lossy().into_owned(),
+            ])
+            .await;
+            assert_eq!(code, 1);
+
+            // Non-loopback host → exit 1.
+            std::fs::write(
+                &state_path,
+                r#"{"host":"0.0.0.0","port":0,"clientApiKey":"key"}"#,
+            )
+            .unwrap();
+            let code = run(&[
+                "--state".to_string(),
+                state_path.to_string_lossy().into_owned(),
+            ])
+            .await;
+            assert_eq!(code, 1);
+        });
+    }
+}
diff --git a/crates/proxy/src/server.rs b/crates/proxy/src/server.rs
new file mode 100644
index 000000000..0538527f4
--- /dev/null
+++ b/crates/proxy/src/server.rs
@@ -0,0 +1,2616 @@
+//! Port of `lib/runtime-rotation-proxy.ts` — the loopback rotation proxy HTTP
+//! surface (spec 04 §9; ARCHITECTURE §6.13).
+//!
+//! A loopback-only HTTP server that authenticates local clients with a shared
+//! API key and serves three route families:
+//! - `POST /responses` (+ aliases) — handed to [`crate::pipeline::ProxyPipeline`]
+//!   (the merged index.ts ∪ proxy request loop, ARCHITECTURE §3 row 1), which
+//!   owns selection/refresh/forward/rotation AND the usage-ledger record;
+//! - `GET /models` and `/thread/goal/*` — served by this module's own
+//!   spec-04 rotation loop (selection, refresh, status mapping, thread-goal
+//!   local fallback, pool-exhaustion bodies);
+//! - everything else — 404.
+//!
+//! Contract highlights (spec 04):
+//! - loopback-only bind with NO opt-out (`CodexValidationError` field `host`)
+//!   and a required `clientApiKey` (field `clientApiKey`), validated BEFORE
+//!   serving;
+//! - IPv6 normalized ONCE at startup: bind uses the raw literal (`::1`), the
+//!   baseUrl uses the bracketed literal (`[::1]`);
+//! - client auth (timing-safe, Bearer or `x-api-key`) runs BEFORE path
+//!   routing — unknown callers always get 401, never 404 (gotcha 22);
+//! - 64 MiB body cap → 413; stable `error.code` payloads per spec 14 §7;
+//! - header scrubbing via `cma_request::stream_failover_runtime`.
+
+use std::collections::{HashMap, HashSet, VecDeque};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex as StdMutex};
+
+use bytes::Bytes;
+use futures::StreamExt;
+use http::{HeaderMap, Request, Response};
+use http_body_util::combinators::BoxBody;
+use http_body_util::{BodyExt, Full, StreamBody};
+use hyper::body::Incoming;
+use serde_json::{Map, Value, json};
+use tokio::sync::{mpsc, oneshot};
+
+use cma_accounts::manager::{AccountManager, ManagedAccount};
+use cma_accounts::manager_persistence::{SAVE_DEBOUNCE_DEFAULT_MS, SharedAccountManager};
+use cma_accounts::session_affinity::{SessionAffinityOptions, SessionAffinityStore};
+use cma_config::getters::{
+    get_fetch_timeout_ms, get_min_rotation_interval_ms, get_network_error_cooldown_ms,
+    get_pid_offset_enabled, get_retry_all_accounts_max_retries, get_routing_mutex_mode,
+    get_scheduling_strategy, get_server_error_cooldown_ms, get_session_affinity,
+    get_session_affinity_max_entries, get_session_affinity_ttl_ms, get_stream_stall_timeout_ms,
+    get_token_invalidation_cooldown_ms, get_token_refresh_skew_ms,
+};
+use cma_config::load::load_plugin_config;
+use cma_core::constants::{
+    CODEX_BASE_URL, HTTP_STATUS, OPENAI_HEADER_VALUES, OPENAI_HEADERS, URL_PATHS,
+};
+use cma_core::errors::CodexError;
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{create_logger, mask_string, run_with_correlation_id};
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{CooldownReason, RateLimitReason, SwitchReason};
+use cma_core::schemas::plugin_config as core_config;
+use cma_core::token_utils::extract_account_id;
+use cma_quota::runtime_policy::{
+    EvaluateRuntimePolicyInput, RuntimePolicyAccount, RuntimePolicyDecision,
+    RuntimeUsageRecordInput, RuntimeUsageRecorder, RuntimeUsageRecorderOptions,
+    create_runtime_usage_recorder, evaluate_runtime_policy, load_runtime_policy_state,
+};
+use cma_request::error_classification::is_workspace_disabled_error;
+use cma_request::model_map::CURRENT_CODEX_MODEL;
+use cma_request::prompts::codex::get_model_family;
+use cma_request::rate_limit_decision::{
+    build_pinned_unavailable_error_body, build_token_invalidation_body,
+    extract_error_code_from_body, get_quota_near_exhaustion_wait_ms, is_token_invalidation_error,
+    normalize_exhaustion_status, parse_retry_after_body_ms, parse_retry_after_header_ms,
+};
+use cma_request::response_handler::{BodyStream, BoxError, StreamResponse};
+use cma_request::stream_failover_runtime::{
+    ClientStreamWriter, HOP_BY_HOP_HEADERS, StreamForwardStatus, forward_streaming_response,
+    read_error_body, response_headers_for_client, with_timeout,
+};
+use cma_rotation::routing_mutex::{RoutingMutexMode, with_routing_mutex};
+use cma_runtime::observability::{
+    mutate_runtime_observability_snapshot, record_runtime_account_recovery,
+    record_runtime_pool_exhaustion,
+};
+use cma_runtime::rotation::account_selection::{
+    ChooseAccountParams, choose_account, normalize_forced_account_index,
+    normalize_forced_account_index_number,
+};
+use cma_runtime::rotation::proxy_state::{
+    RotationProxyState, RotationProxyStateInit, create_rotation_proxy_state,
+    recover_stale_runtime_state,
+};
+use cma_runtime::rotation::server_types::{
+    ExhaustionReason, NowFn, RequestContext, RequestMethod, RuntimeProxyHttpError,
+    RuntimeRotationProxyOptions, RuntimeRotationProxyStatus, SchedulingStrategy,
+};
+use cma_runtime::rotation::storage_meta::read_storage_meta_from_disk;
+use cma_runtime::rotation::token_refresh::{
+    DEFAULT_AUTH_FAILURE_COOLDOWN_MS, EnsureFreshAccessTokenParams, EnsureFreshAccessTokenResult,
+    apply_monotonic_auth_cooldown, ensure_fresh_access_token,
+};
+use cma_usage::types::{UsageLedgerOperation, UsageLedgerOutcome, UsageLedgerSource};
+
+use crate::client_auth::is_authorized_client;
+use crate::pipeline::{ProxyPipeline, load_pipeline_config};
+
+// ---------------------------------------------------------------------------
+// Module constants (TS parity)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_HOST: &str = "127.0.0.1";
+const DEFAULT_QUOTA_REMAINING_THRESHOLD: f64 = 10.0;
+const DEFAULT_MAX_RUNTIME_ACCOUNT_ATTEMPTS: i64 = 4;
+/// TS `MAX_REQUEST_BODY_BYTES` = 64 MiB.
+pub const MAX_REQUEST_BODY_BYTES: usize = 64 * 1024 * 1024;
+/// TS `MAX_THREAD_GOAL_FALLBACKS` — LRU cap of the local thread-goal map.
+pub const MAX_THREAD_GOAL_FALLBACKS: usize = 512;
+
+/// The proxy's response body type: either a buffered JSON payload or the
+/// streamed upstream body.
+pub type ProxyBody = BoxBody<Bytes, BoxError>;
+
+fn full_body(text: impl Into<Bytes>) -> ProxyBody {
+    BodyExt::boxed(Full::new(text.into()).map_err(|never| match never {}))
+}
+
+// ---------------------------------------------------------------------------
+// Host normalization (TS `isLoopbackHost` / `toBindHost` / `toUrlHost`)
+// ---------------------------------------------------------------------------
+
+fn is_loopback_host(host: &str) -> bool {
+    let normalized = host.trim().to_lowercase();
+    normalized == "127.0.0.1"
+        || normalized == "localhost"
+        || normalized == "::1"
+        || normalized == "[::1]"
+}
+
+fn strip_ipv6_brackets(host: &str) -> &str {
+    let trimmed = host.trim();
+    if let Some(stripped) = trimmed.strip_prefix('[')
+        && let Some(stripped) = stripped.strip_suffix(']')
+    {
+        return stripped;
+    }
+    trimmed
+}
+
+/// Raw literal suitable for the listener bind: `"[::1]"` → `"::1"`.
+fn to_bind_host(host: &str) -> String {
+    strip_ipv6_brackets(host).to_string()
+}
+
+/// URL authority host: IPv6 literals bracketed (`"::1"` → `"[::1]"`).
+fn to_url_host(host: &str) -> String {
+    let bare = strip_ipv6_brackets(host);
+    if bare.contains(':') {
+        format!("[{bare}]")
+    } else {
+        bare.to_string()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Path discrimination
+// ---------------------------------------------------------------------------
+
+fn is_responses_path(pathname: &str) -> bool {
+    pathname == URL_PATHS.responses
+        || pathname == URL_PATHS.codex_responses
+        || pathname == "/v1/responses"
+        || pathname == "/v1/codex/responses"
+}
+
+fn is_models_path(pathname: &str) -> bool {
+    pathname == URL_PATHS.models || pathname == "/v1/models"
+}
+
+fn is_thread_goal_path(pathname: &str) -> bool {
+    matches!(
+        pathname,
+        "/thread/goal/get"
+            | "/thread/goal/set"
+            | "/codex/thread/goal/get"
+            | "/codex/thread/goal/set"
+    )
+}
+
+fn normalize_thread_goal_upstream_path(pathname: &str) -> String {
+    if pathname.starts_with("/codex/") {
+        pathname.to_string()
+    } else {
+        format!("/codex{pathname}")
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Shared proxy handle
+// ---------------------------------------------------------------------------
+
+/// The pipeline (which owns [`RotationProxyState`]) plus the server-local
+/// insertion-order queue for the thread-goal LRU
+/// (`RotationProxyState.thread_goal_fallbacks` is a `HashMap`; the TS `Map`
+/// was insertion-ordered). Lock order: `thread_goal_order` BEFORE
+/// `pipeline.state()`.
+struct ProxyShared {
+    pipeline: ProxyPipeline,
+    thread_goal_order: tokio::sync::Mutex<VecDeque<String>>,
+}
+
+/// Immutable per-instance configuration snapshot taken once per request.
+#[derive(Clone)]
+struct ReqConfig {
+    client_api_key: String,
+    upstream_base_url: String,
+    fetch_client: reqwest::Client,
+    now: NowFn,
+    routing_mutex_mode: RoutingMutexMode,
+    scheduling_strategy: SchedulingStrategy,
+    pid_offset_enabled: bool,
+    token_refresh_skew_ms: i64,
+    network_error_cooldown_ms: i64,
+    server_error_cooldown_ms: i64,
+    token_invalidation_cooldown_ms: i64,
+    min_rotation_interval_ms: i64,
+    fetch_timeout_ms: i64,
+    stream_stall_timeout_ms: i64,
+    max_runtime_account_attempts: i64,
+    max_request_body_bytes: usize,
+    quota_remaining_percent_threshold: f64,
+    session_affinity_store: Option<Arc<StdMutex<SessionAffinityStore>>>,
+    forced_account_index: Option<i64>,
+}
+
+// ---------------------------------------------------------------------------
+// Server handle
+// ---------------------------------------------------------------------------
+
+/// TS `RuntimeRotationProxyServer` — the handle returned by
+/// [`start_runtime_rotation_proxy`].
+pub struct RuntimeRotationProxyServer {
+    /// Bind host in its RAW literal form (`"::1"`, not `"[::1]"`).
+    pub host: String,
+    pub port: u16,
+    /// `http://<urlHost>:<port>` with the BRACKETED IPv6 form.
+    pub base_url: String,
+    shared: Arc<ProxyShared>,
+    accept_task: tokio::task::JoinHandle<()>,
+    connections: Arc<StdMutex<Vec<tokio::task::AbortHandle>>>,
+    closed: AtomicBool,
+}
+
+impl RuntimeRotationProxyServer {
+    /// TS `close()` — stop accepting, destroy every tracked connection, then
+    /// `flushPendingSave()` on the active account manager (propagating its
+    /// error, as the TS promise did).
+    pub async fn close(&self) -> Result<(), CodexError> {
+        if self.closed.swap(true, Ordering::SeqCst) {
+            return Ok(());
+        }
+        self.accept_task.abort();
+        let handles: Vec<tokio::task::AbortHandle> = {
+            let mut connections = self
+                .connections
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner());
+            connections.drain(..).collect()
+        };
+        for handle in handles {
+            handle.abort();
+        }
+        let manager = {
+            let state = self.shared.pipeline.state().await;
+            state.active_account_manager.clone()
+        };
+        manager.flush_pending_save().await
+    }
+
+    /// TS `getStatus()` — snapshot copy with `lastError` passed through
+    /// `maskString` (errors-logging-08).
+    pub async fn get_status(&self) -> RuntimeRotationProxyStatus {
+        let state = self.shared.pipeline.state().await;
+        let mut status = state.status.clone();
+        status.last_error = status.last_error.map(|error| mask_string(&error));
+        status
+    }
+
+    /// The pipeline handle serving this proxy's `/responses` route (metrics
+    /// and state surfaces for the wrapper / report commands).
+    pub fn pipeline(&self) -> ProxyPipeline {
+        self.shared.pipeline.clone()
+    }
+}
+
+impl std::fmt::Debug for RuntimeRotationProxyServer {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RuntimeRotationProxyServer")
+            .field("host", &self.host)
+            .field("port", &self.port)
+            .field("base_url", &self.base_url)
+            .finish()
+    }
+}
+
+impl Drop for RuntimeRotationProxyServer {
+    fn drop(&mut self) {
+        self.accept_task.abort();
+        let mut connections = self
+            .connections
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        for handle in connections.drain(..) {
+            handle.abort();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+
+fn map_routing_mutex_mode(mode: core_config::RoutingMutexMode) -> RoutingMutexMode {
+    match mode {
+        core_config::RoutingMutexMode::Enabled => RoutingMutexMode::Enabled,
+        core_config::RoutingMutexMode::Legacy => RoutingMutexMode::Legacy,
+    }
+}
+
+fn map_scheduling_strategy(strategy: core_config::SchedulingStrategy) -> SchedulingStrategy {
+    match strategy {
+        core_config::SchedulingStrategy::Hybrid => SchedulingStrategy::Hybrid,
+        core_config::SchedulingStrategy::Sequential => SchedulingStrategy::Sequential,
+    }
+}
+
+/// TS `startRuntimeRotationProxy(options)`.
+pub async fn start_runtime_rotation_proxy(
+    options: RuntimeRotationProxyOptions,
+) -> Result<RuntimeRotationProxyServer, CodexError> {
+    let plugin_config = load_plugin_config();
+    let active_account_manager = match options.account_manager.clone() {
+        Some(manager) => manager,
+        None => SharedAccountManager::new(AccountManager::load_from_disk(None).await),
+    };
+    let routing_mutex_mode = map_routing_mutex_mode(get_routing_mutex_mode(&plugin_config));
+    {
+        let mut manager = active_account_manager.lock().await;
+        manager.set_routing_mutex_mode(routing_mutex_mode);
+    }
+    let scheduling_strategy = map_scheduling_strategy(get_scheduling_strategy(&plugin_config));
+    let fetch_client = options.fetch_client.clone().unwrap_or_default();
+    let host = options
+        .host
+        .clone()
+        .unwrap_or_else(|| DEFAULT_HOST.to_string());
+    // Defense in depth (runtime-proxy-01): loopback-only with NO opt-out.
+    if !is_loopback_host(&host) {
+        let mut context = Map::new();
+        context.insert("host".to_string(), Value::String(host.clone()));
+        return Err(CodexError::validation(format!(
+            "Runtime rotation proxy refuses to bind non-loopback host \"{host}\". It forwards managed OAuth tokens and is loopback-only."
+        ))
+        .with_field("host")
+        .with_expected("a loopback host")
+        .with_context(context));
+    }
+    let bind_host = to_bind_host(&host);
+    let url_host = to_url_host(&host);
+    let port = options.port.unwrap_or(0);
+    let upstream_base_url = options
+        .upstream_base_url
+        .clone()
+        .unwrap_or_else(|| CODEX_BASE_URL.to_string());
+    let client_api_key = options.client_api_key.trim().to_string();
+    if client_api_key.is_empty() {
+        return Err(
+            CodexError::validation("Runtime rotation proxy requires a clientApiKey.")
+                .with_field("clientApiKey")
+                .with_expected("a non-empty string"),
+        );
+    }
+    let now: NowFn = options
+        .now
+        .clone()
+        .unwrap_or_else(|| Arc::new(cma_core::utils::now_ms));
+    // Ephemeral per-invocation pin (issue #623): explicit option (even 0)
+    // wins; `None` defers to the launcher's env. Invalid values collapse to
+    // None instead of throwing (chooseAccount reports per-request).
+    let forced_account_index = match options.forced_account_index {
+        Some(value) => normalize_forced_account_index_number(Some(value as f64)),
+        // The launcher explicitly resolved "no pin" (no `--account`): a
+        // stray/inherited CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX (nested
+        // wrapper inside a forced run, leftover export) must NOT silently
+        // pin the proxy — TS scrubs the var from process.env in this case,
+        // so rotation stays normal.
+        None if options.suppress_env_forced_account_index => None,
+        None => normalize_forced_account_index(
+            std::env::var("CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX")
+                .ok()
+                .as_deref(),
+        ),
+    };
+    let token_refresh_skew_ms = get_token_refresh_skew_ms(&plugin_config) as i64;
+    let network_error_cooldown_ms = get_network_error_cooldown_ms(&plugin_config) as i64;
+    let server_error_cooldown_ms = get_server_error_cooldown_ms(&plugin_config) as i64;
+    let token_invalidation_cooldown_ms = get_token_invalidation_cooldown_ms(&plugin_config) as i64;
+    let min_rotation_interval_ms = get_min_rotation_interval_ms(&plugin_config) as i64;
+    let pid_offset_enabled = get_pid_offset_enabled(&plugin_config);
+    let fetch_timeout_ms = options
+        .fetch_timeout_ms
+        .unwrap_or_else(|| get_fetch_timeout_ms(&plugin_config) as i64);
+    let stream_stall_timeout_ms = options
+        .stream_stall_timeout_ms
+        .unwrap_or_else(|| get_stream_stall_timeout_ms(&plugin_config) as i64);
+    let configured_max_retries = get_retry_all_accounts_max_retries(&plugin_config) as i64;
+    let max_runtime_account_attempts = if configured_max_retries > 0 {
+        configured_max_retries + 1
+    } else {
+        DEFAULT_MAX_RUNTIME_ACCOUNT_ATTEMPTS
+    };
+    let max_request_body_bytes = options
+        .max_request_body_bytes
+        .unwrap_or(MAX_REQUEST_BODY_BYTES);
+    let quota_remaining_percent_threshold = options
+        .quota_remaining_percent_threshold
+        .unwrap_or(DEFAULT_QUOTA_REMAINING_THRESHOLD);
+    let session_affinity_store = if get_session_affinity(&plugin_config) {
+        Some(Arc::new(StdMutex::new(SessionAffinityStore::new(
+            SessionAffinityOptions {
+                ttl_ms: Some(get_session_affinity_ttl_ms(&plugin_config) as i64),
+                max_entries: Some(get_session_affinity_max_entries(&plugin_config) as i64),
+            },
+        ))))
+    } else {
+        None
+    };
+    // Initialize from disk so the proxy starts in sync with the stored
+    // affinity generation; per-request reads detect later CLI bumps (#474).
+    let last_observed_affinity_generation = read_storage_meta_from_disk(None).affinity_generation;
+    let state = create_rotation_proxy_state(RotationProxyStateInit {
+        active_account_manager,
+        routing_mutex_mode,
+        scheduling_strategy,
+        fetch_client,
+        upstream_base_url,
+        client_api_key,
+        now,
+        token_refresh_skew_ms,
+        network_error_cooldown_ms,
+        server_error_cooldown_ms,
+        token_invalidation_cooldown_ms,
+        min_rotation_interval_ms,
+        pid_offset_enabled,
+        fetch_timeout_ms,
+        stream_stall_timeout_ms,
+        max_runtime_account_attempts,
+        max_request_body_bytes,
+        quota_remaining_percent_threshold,
+        session_affinity_store,
+        last_observed_affinity_generation,
+        forced_account_index,
+    });
+    // SEAM: the pipeline owns the rotation state; the HTTP surface reads it
+    // through `pipeline.state()` and routes `/responses` through
+    // `pipeline.handle_responses`.
+    let pipeline = ProxyPipeline::new(state, load_pipeline_config(&plugin_config));
+    let shared = Arc::new(ProxyShared {
+        pipeline,
+        thread_goal_order: tokio::sync::Mutex::new(VecDeque::new()),
+    });
+
+    let listener = tokio::net::TcpListener::bind((bind_host.as_str(), port))
+        .await
+        .map_err(|error| CodexError::new(format!("listen {bind_host}:{port}: {error}")))?;
+    let resolved_port = listener
+        .local_addr()
+        .map(|address| address.port())
+        .unwrap_or(port);
+
+    let connections: Arc<StdMutex<Vec<tokio::task::AbortHandle>>> =
+        Arc::new(StdMutex::new(Vec::new()));
+    let accept_shared = Arc::clone(&shared);
+    let accept_connections = Arc::clone(&connections);
+    let accept_task = tokio::spawn(async move {
+        loop {
+            match listener.accept().await {
+                Ok((stream, _addr)) => {
+                    let connection_shared = Arc::clone(&accept_shared);
+                    let handle = tokio::spawn(async move {
+                        let io = hyper_util::rt::TokioIo::new(stream);
+                        let service = hyper::service::service_fn(move |req: Request<Incoming>| {
+                            let shared = Arc::clone(&connection_shared);
+                            async move {
+                                Ok::<_, std::convert::Infallible>(handle_request(shared, req).await)
+                            }
+                        });
+                        let _ = hyper::server::conn::http1::Builder::new()
+                            .serve_connection(io, service)
+                            .await;
+                    });
+                    let mut tracked = accept_connections
+                        .lock()
+                        .unwrap_or_else(|poison| poison.into_inner());
+                    tracked.retain(|existing| !existing.is_finished());
+                    tracked.push(handle.abort_handle());
+                }
+                Err(error) => {
+                    // TS post-startup `server.on("error")` — record and keep
+                    // serving.
+                    let mut state = accept_shared.pipeline.state().await;
+                    state.status.last_error = Some(error.to_string());
+                }
+            }
+        }
+    });
+
+    Ok(RuntimeRotationProxyServer {
+        host: bind_host,
+        port: resolved_port,
+        base_url: format!("http://{url_host}:{resolved_port}"),
+        shared,
+        accept_task,
+        connections,
+        closed: AtomicBool::new(false),
+    })
+}
+
+// ---------------------------------------------------------------------------
+// JSON response helpers (TS `writeJson` — compact JSON + trailing `\n`)
+// ---------------------------------------------------------------------------
+
+fn json_response(status: u16, payload: &Value) -> Response<ProxyBody> {
+    Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(full_body(format!("{}\n", stringify_compact(payload))))
+        .expect("static response")
+}
+
+fn proxy_error_response() -> Response<ProxyBody> {
+    json_response(
+        500,
+        &json!({
+            "error": {
+                "message": "Runtime rotation proxy failed before forwarding the request.",
+                "code": "codex_runtime_rotation_proxy_error",
+            }
+        }),
+    )
+}
+
+fn write_unauthorized() -> Response<ProxyBody> {
+    json_response(
+        HTTP_STATUS.unauthorized,
+        &json!({
+            "error": {
+                "message": "Runtime rotation proxy rejected an unauthenticated local request.",
+                "code": "runtime_rotation_proxy_unauthorized",
+            }
+        }),
+    )
+}
+
+fn write_method_or_path_error() -> Response<ProxyBody> {
+    json_response(
+        404,
+        &json!({
+            "error": {
+                "message": "Runtime rotation proxy only accepts Responses API, model discovery, and Codex thread goal requests.",
+                "code": "runtime_rotation_proxy_not_found",
+            }
+        }),
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Request-context construction
+// ---------------------------------------------------------------------------
+
+fn parse_request_body(body: &[u8]) -> Option<Map<String, Value>> {
+    if body.is_empty() {
+        return None;
+    }
+    match serde_json::from_slice::<Value>(body) {
+        Ok(Value::Object(map)) => Some(map),
+        _ => None,
+    }
+}
+
+fn read_string_record_value(record: &Map<String, Value>, key: &str) -> Option<String> {
+    let value = record.get(key)?.as_str()?.trim();
+    if value.is_empty() {
+        None
+    } else {
+        Some(value.to_string())
+    }
+}
+
+fn header_str<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+    headers.get(name).and_then(|value| value.to_str().ok())
+}
+
+fn resolve_session_key(
+    headers: &HeaderMap,
+    parsed_body: Option<&Map<String, Value>>,
+) -> Option<String> {
+    let header_key = header_str(headers, OPENAI_HEADERS.session_id)
+        .or_else(|| header_str(headers, OPENAI_HEADERS.conversation_id));
+    if let Some(key) = header_key {
+        let trimmed = key.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+    }
+    let body = parsed_body?;
+    if let Some(key) = body.get("prompt_cache_key").and_then(Value::as_str) {
+        let trimmed = key.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+    }
+    if let Some(key) = body.get("previous_response_id").and_then(Value::as_str) {
+        let trimmed = key.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+    }
+    if let Some(metadata) = body.get("metadata").and_then(Value::as_object) {
+        return read_string_record_value(metadata, "session_id")
+            .or_else(|| read_string_record_value(metadata, "conversation_id"))
+            .or_else(|| read_string_record_value(metadata, "thread_id"));
+    }
+    None
+}
+
+fn read_string_search_param(query: Option<&str>, key: &str) -> Option<String> {
+    let query = query?;
+    for pair in query.split('&') {
+        let mut parts = pair.splitn(2, '=');
+        let name = parts.next().unwrap_or("");
+        if name != key {
+            continue;
+        }
+        let raw = parts.next().unwrap_or("");
+        let decoded = percent_decode(raw);
+        let trimmed = decoded.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+        return None;
+    }
+    None
+}
+
+/// Minimal `application/x-www-form-urlencoded` component decode (`+` → space,
+/// `%XX` → byte) — enough for `URLSearchParams.get` parity on thread ids.
+fn percent_decode(raw: &str) -> String {
+    let mut out: Vec<u8> = Vec::with_capacity(raw.len());
+    let bytes = raw.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'+' => {
+                out.push(b' ');
+                i += 1;
+            }
+            b'%' if i + 2 < bytes.len() => match u8::from_str_radix(&raw[i + 1..i + 3], 16) {
+                Ok(byte) => {
+                    out.push(byte);
+                    i += 3;
+                }
+                Err(_) => {
+                    out.push(b'%');
+                    i += 1;
+                }
+            },
+            other => {
+                out.push(other);
+                i += 1;
+            }
+        }
+    }
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+fn build_responses_request_context(headers: HeaderMap, body: Vec<u8>) -> RequestContext {
+    let parsed_body = parse_request_body(&body);
+    let model = parsed_body
+        .as_ref()
+        .and_then(|parsed| parsed.get("model"))
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|model| !model.is_empty())
+        .map(str::to_string);
+    let session_key = resolve_session_key(&headers, parsed_body.as_ref());
+    let stream = parsed_body
+        .as_ref()
+        .and_then(|parsed| parsed.get("stream"))
+        .and_then(Value::as_bool)
+        == Some(true);
+    // A model-less request buckets into the CODEX family (fall back to the
+    // current codex model, NOT the general default model — gotcha 16).
+    let family = get_model_family(model.as_deref().unwrap_or(CURRENT_CODEX_MODEL));
+    RequestContext {
+        body,
+        headers,
+        method: RequestMethod::Post,
+        upstream_path: URL_PATHS.codex_responses.to_string(),
+        model,
+        family,
+        stream,
+        session_key,
+    }
+}
+
+fn build_models_request_context(headers: HeaderMap) -> RequestContext {
+    RequestContext {
+        body: Vec::new(),
+        headers,
+        method: RequestMethod::Get,
+        upstream_path: URL_PATHS.models.to_string(),
+        model: None,
+        family: ModelFamily::Codex,
+        stream: false,
+        session_key: None,
+    }
+}
+
+fn build_thread_goal_request_context(
+    headers: HeaderMap,
+    body: Vec<u8>,
+    pathname: &str,
+    query: Option<&str>,
+    is_get: bool,
+) -> RequestContext {
+    let parsed_body = parse_request_body(&body);
+    let query_thread_key = read_string_search_param(query, "thread_id")
+        .or_else(|| read_string_search_param(query, "threadId"));
+    let body_thread_key = parsed_body.as_ref().and_then(|parsed| {
+        read_string_record_value(parsed, "thread_id")
+            .or_else(|| read_string_record_value(parsed, "threadId"))
+    });
+    let session_key = body_thread_key
+        .or(query_thread_key)
+        .or_else(|| resolve_session_key(&headers, parsed_body.as_ref()));
+    RequestContext {
+        body,
+        headers,
+        method: if is_get {
+            RequestMethod::Get
+        } else {
+            RequestMethod::Post
+        },
+        upstream_path: normalize_thread_goal_upstream_path(pathname),
+        model: None,
+        family: ModelFamily::Codex,
+        stream: false,
+        session_key,
+    }
+}
+
+fn build_upstream_url(
+    upstream_base_url: &str,
+    upstream_path: &str,
+    query: Option<&str>,
+) -> Result<String, HandlerError> {
+    let mut upstream = reqwest::Url::parse(upstream_base_url)
+        .map_err(|error| HandlerError::Other(format!("Invalid URL: {error}")))?;
+    let base_path = upstream.path().trim_end_matches('/').to_string();
+    upstream.set_path(&format!("{base_path}{upstream_path}"));
+    upstream.set_query(query.filter(|value| !value.is_empty()));
+    Ok(upstream.to_string())
+}
+
+// ---------------------------------------------------------------------------
+// Thread-goal LRU (TS Map insertion-order semantics over the state HashMap)
+// ---------------------------------------------------------------------------
+
+fn set_thread_goal_fallback(
+    state: &mut RotationProxyState,
+    order: &mut VecDeque<String>,
+    key: &str,
+    goal: Option<String>,
+) {
+    if state.thread_goal_fallbacks.contains_key(key) {
+        state.thread_goal_fallbacks.remove(key);
+        order.retain(|existing| existing != key);
+    }
+    state.thread_goal_fallbacks.insert(key.to_string(), goal);
+    order.push_back(key.to_string());
+    while state.thread_goal_fallbacks.len() > MAX_THREAD_GOAL_FALLBACKS {
+        let Some(oldest) = order.pop_front() else {
+            break;
+        };
+        state.thread_goal_fallbacks.remove(&oldest);
+    }
+}
+
+fn get_thread_goal_fallback(
+    state: &mut RotationProxyState,
+    order: &mut VecDeque<String>,
+    key: &str,
+) -> Option<String> {
+    if !state.thread_goal_fallbacks.contains_key(key) {
+        return None;
+    }
+    let goal = state.thread_goal_fallbacks.remove(key).unwrap_or(None);
+    order.retain(|existing| existing != key);
+    state
+        .thread_goal_fallbacks
+        .insert(key.to_string(), goal.clone());
+    order.push_back(key.to_string());
+    goal
+}
+
+// ---------------------------------------------------------------------------
+// Skip-reason bookkeeping (JS Map insertion order over choose_account's map)
+// ---------------------------------------------------------------------------
+
+fn sync_skip_order(ordered: &mut Vec<(i64, String)>, map: &HashMap<i64, String>) {
+    for (index, reason) in ordered.iter_mut() {
+        if let Some(updated) = map.get(index) {
+            *reason = updated.clone();
+        }
+    }
+    let mut new_keys: Vec<i64> = map
+        .keys()
+        .copied()
+        .filter(|key| !ordered.iter().any(|(existing, _)| existing == key))
+        .collect();
+    new_keys.sort_unstable();
+    for key in new_keys {
+        ordered.push((key, map[&key].clone()));
+    }
+}
+
+fn record_skip(
+    ordered: &mut Vec<(i64, String)>,
+    map: &mut HashMap<i64, String>,
+    index: i64,
+    reason: &str,
+) {
+    map.insert(index, reason.to_string());
+    sync_skip_order(ordered, map);
+}
+
+fn skip_reasons_to_json(ordered: &[(i64, String)]) -> Map<String, Value> {
+    let mut reasons = Map::new();
+    for (index, reason) in ordered {
+        reasons.insert(index.to_string(), Value::String(reason.clone()));
+    }
+    reasons
+}
+
+// ---------------------------------------------------------------------------
+// Outbound headers (TS `createOutboundHeaders`)
+// ---------------------------------------------------------------------------
+
+fn create_outbound_headers(incoming: &HeaderMap, access_token: &str, account_id: &str) -> HeaderMap {
+    let mut headers = incoming.clone();
+    for name in HOP_BY_HOP_HEADERS {
+        headers.remove(name);
+    }
+    headers.remove("host");
+    headers.remove("x-api-key");
+    // Never forward inbound client credentials upstream.
+    headers.remove("cookie");
+    headers.remove("proxy-authorization");
+    let set = |headers: &mut HeaderMap, name: &str, value: &str| {
+        if let (Ok(name), Ok(value)) = (
+            http::header::HeaderName::from_bytes(name.as_bytes()),
+            http::header::HeaderValue::from_str(value),
+        ) {
+            headers.insert(name, value);
+        }
+    };
+    set(
+        &mut headers,
+        "authorization",
+        &format!("Bearer {access_token}"),
+    );
+    set(&mut headers, OPENAI_HEADERS.account_id, account_id);
+    set(
+        &mut headers,
+        OPENAI_HEADERS.beta,
+        OPENAI_HEADER_VALUES.beta_responses,
+    );
+    set(
+        &mut headers,
+        OPENAI_HEADERS.originator,
+        OPENAI_HEADER_VALUES.originator_codex,
+    );
+    headers
+}
+
+fn read_trimmed_string(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Streaming plumbing (Node ServerResponse analogue over an mpsc channel)
+// ---------------------------------------------------------------------------
+
+/// The head handed from the streaming writer to the HTTP response builder:
+/// `(status, headers)`.
+type ResponseHead = (u16, Vec<(String, String)>);
+
+struct ChannelWriter {
+    head_tx: Option<oneshot::Sender<ResponseHead>>,
+    body_tx: Option<mpsc::Sender<Result<Bytes, BoxError>>>,
+    /// A clone kept alive for `closed()` after `end()`/`destroy()`.
+    closed_probe: mpsc::Sender<Result<Bytes, BoxError>>,
+    pending: Option<Bytes>,
+    destroyed: bool,
+}
+
+impl ClientStreamWriter for ChannelWriter {
+    fn write_head(&mut self, status: u16, headers: Vec<(String, String)>) {
+        if let Some(tx) = self.head_tx.take() {
+            let _ = tx.send((status, headers));
+        }
+    }
+
+    fn writable_ended(&self) -> bool {
+        self.body_tx.is_none()
+    }
+
+    fn destroyed(&self) -> bool {
+        self.destroyed
+    }
+
+    fn write(&mut self, chunk: &[u8]) -> Result<bool, BoxError> {
+        if self.destroyed {
+            return Err("write after destroy".into());
+        }
+        let Some(tx) = self.body_tx.as_ref() else {
+            return Err("write after end".into());
+        };
+        match tx.try_send(Ok(Bytes::copy_from_slice(chunk))) {
+            Ok(()) => Ok(true),
+            Err(mpsc::error::TrySendError::Full(value)) => {
+                // Chunk accepted; delivered during wait_for_drain
+                // (backpressure).
+                if let Ok(bytes) = value {
+                    self.pending = Some(bytes);
+                }
+                Ok(false)
+            }
+            Err(mpsc::error::TrySendError::Closed(_)) => Err("client connection closed".into()),
+        }
+    }
+
+    fn wait_for_drain(&mut self) -> futures::future::BoxFuture<'_, ()> {
+        let pending = self.pending.take();
+        let tx = self.body_tx.clone();
+        Box::pin(async move {
+            if let (Some(chunk), Some(tx)) = (pending, tx) {
+                // Resolves on capacity OR channel close — a disconnected
+                // client cannot park the forwarder forever.
+                let _ = tx.send(Ok(chunk)).await;
+            }
+        })
+    }
+
+    fn end(&mut self) {
+        self.body_tx = None;
+    }
+
+    fn destroy(&mut self, error: Option<BoxError>) {
+        if let Some(tx) = self.body_tx.take() {
+            let _ = tx.try_send(Err(error.unwrap_or_else(|| "destroyed".into())));
+        }
+        self.destroyed = true;
+    }
+
+    fn closed(&self) -> futures::future::BoxFuture<'static, ()> {
+        let probe = self.closed_probe.clone();
+        Box::pin(async move {
+            probe.closed().await;
+        })
+    }
+}
+
+/// Buffered [`StreamForwardStatus`] — applied to the shared status after the
+/// forward completes (the canonical status lives behind the async state
+/// lock, which the sync trait methods cannot take).
+#[derive(Default)]
+struct StatusBuffer {
+    streams_started: i64,
+    last_error: Option<String>,
+}
+
+impl StreamForwardStatus for StatusBuffer {
+    fn increment_streams_started(&mut self) {
+        self.streams_started += 1;
+    }
+
+    fn set_last_error(&mut self, message: String) {
+        self.last_error = Some(message);
+    }
+}
+
+/// Post-stream-failure cleanup data (the TS `onStreamFailure` closure body,
+/// run after `forward_streaming_response` reports failure).
+enum StreamCleanup {
+    None,
+    NetworkFailure {
+        account_index: i64,
+        family: ModelFamily,
+        model: Option<String>,
+        session_key: Option<String>,
+        cooldown_ms: i64,
+    },
+}
+
+struct StreamUsage {
+    recorder: Arc<RuntimeUsageRecorder>,
+    status_code: u16,
+    account: Option<RuntimePolicyAccount>,
+    /// (`outcome`, `errorCode`) when the forward succeeds.
+    on_success: (UsageLedgerOutcome, Option<String>),
+    /// (`outcome`, `errorCode`) when the forward fails.
+    on_failure: (UsageLedgerOutcome, Option<String>),
+}
+
+/// Stream `upstream` to the client: spawns the pump task, waits for the
+/// response head, and returns the streaming client response while the pump
+/// (and its cleanup + usage record) continues in the background.
+///
+/// `usage` is `None` on the `/responses` path — the pipeline owns that
+/// route's usage-ledger record.
+async fn stream_upstream_to_client(
+    shared: Arc<ProxyShared>,
+    manager: SharedAccountManager,
+    upstream: StreamResponse,
+    stream_stall_timeout_ms: i64,
+    cleanup: StreamCleanup,
+    usage: Option<StreamUsage>,
+) -> Response<ProxyBody> {
+    let (head_tx, head_rx) = oneshot::channel::<(u16, Vec<(String, String)>)>();
+    let (body_tx, mut body_rx) = mpsc::channel::<Result<Bytes, BoxError>>(16);
+    let closed_probe = body_tx.clone();
+    let mut writer = ChannelWriter {
+        head_tx: Some(head_tx),
+        body_tx: Some(body_tx),
+        closed_probe,
+        pending: None,
+        destroyed: false,
+    };
+    tokio::spawn(async move {
+        let mut status_buffer = StatusBuffer::default();
+        let forwarded = forward_streaming_response(
+            upstream,
+            &mut writer,
+            &mut status_buffer,
+            || {},
+            stream_stall_timeout_ms.max(1) as u64,
+        )
+        .await;
+        drop(writer);
+        {
+            let mut state = shared.pipeline.state().await;
+            state.status.streams_started += status_buffer.streams_started;
+            if let Some(error) = status_buffer.last_error {
+                state.status.last_error = Some(error);
+            }
+        }
+        if !forwarded
+            && let StreamCleanup::NetworkFailure {
+                account_index,
+                family,
+                model,
+                session_key,
+                cooldown_ms,
+            } = cleanup
+        {
+            {
+                let mut mgr = manager.lock().await;
+                mgr.record_failure(account_index, family, model.as_deref());
+                mgr.mark_account_cooling_down(
+                    account_index,
+                    cooldown_ms,
+                    CooldownReason::NetworkError,
+                );
+            }
+            forget_affinity(&shared, session_key.as_deref()).await;
+            manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        }
+        if let Some(usage) = usage {
+            let (outcome, error_code) = if forwarded {
+                usage.on_success
+            } else {
+                usage.on_failure
+            };
+            usage
+                .recorder
+                .record(RuntimeUsageRecordInput {
+                    outcome: Some(outcome),
+                    status_code: Some(usage.status_code as i64),
+                    error_code,
+                    account: usage.account,
+                    ..Default::default()
+                })
+                .await;
+        }
+    });
+    match head_rx.await {
+        Ok((status, headers)) => {
+            let stream = futures::stream::poll_fn(move |cx| body_rx.poll_recv(cx));
+            let body: ProxyBody = BodyExt::boxed(StreamBody::new(
+                stream.map(|item| item.map(hyper::body::Frame::data)),
+            ));
+            let mut builder = Response::builder().status(status);
+            for (name, value) in headers {
+                builder = builder.header(name, value);
+            }
+            builder.body(body).unwrap_or_else(|_| proxy_error_response())
+        }
+        Err(_) => proxy_error_response(),
+    }
+}
+
+async fn forget_affinity(shared: &Arc<ProxyShared>, session_key: Option<&str>) {
+    let store = {
+        let state = shared.pipeline.state().await;
+        state.session_affinity_store.clone()
+    };
+    if let Some(store) = store {
+        let mut store = store.lock().unwrap_or_else(|poison| poison.into_inner());
+        store.forget_session(session_key);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Upstream fetch → StreamResponse
+// ---------------------------------------------------------------------------
+
+fn to_stream_response(response: reqwest::Response) -> StreamResponse {
+    let status = response.status().as_u16();
+    let status_text = response
+        .status()
+        .canonical_reason()
+        .unwrap_or("")
+        .to_string();
+    let headers = response.headers().clone();
+    let body: BodyStream = response
+        .bytes_stream()
+        .map(|item| item.map_err(|error| -> BoxError { Box::new(error) }))
+        .boxed();
+    StreamResponse {
+        status,
+        status_text,
+        headers,
+        body: Some(body),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Persist-active-account (TS `persistRuntimeActiveAccount`)
+// ---------------------------------------------------------------------------
+
+async fn persist_runtime_active_account(
+    manager: &SharedAccountManager,
+    account_index: i64,
+    family: ModelFamily,
+    is_pinned: bool,
+    scheduling_strategy: SchedulingStrategy,
+) {
+    if is_pinned {
+        // #474: pinned requests never commit/persist/sync anything.
+        return;
+    }
+    // Whole body is try/catch-ignore in TS — forwarding must not fail after a
+    // valid upstream response.
+    let mode = {
+        let manager = manager.lock().await;
+        manager.get_routing_mutex_mode()
+    };
+    if mode != RoutingMutexMode::Enabled && scheduling_strategy != SchedulingStrategy::Sequential {
+        let mut mgr = manager.lock().await;
+        mgr.mark_switched_locked(account_index, SwitchReason::Rotation, family, None)
+            .await;
+    }
+    manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+    let mgr = manager.lock().await;
+    mgr.sync_codex_cli_active_selection_for_index(account_index)
+        .await;
+}
+
+// ---------------------------------------------------------------------------
+// Request handling
+// ---------------------------------------------------------------------------
+
+enum HandlerError {
+    Http(RuntimeProxyHttpError),
+    Other(String),
+}
+
+async fn read_request_body(body: Incoming, max_bytes: usize) -> Result<Vec<u8>, HandlerError> {
+    let mut body = body;
+    let mut collected: Vec<u8> = Vec::new();
+    loop {
+        let Some(frame) = body.frame().await else {
+            break;
+        };
+        let frame = frame.map_err(|error| HandlerError::Other(error.to_string()))?;
+        if let Ok(data) = frame.into_data() {
+            if collected.len() + data.len() > max_bytes {
+                return Err(HandlerError::Http(RuntimeProxyHttpError::new(
+                    "Runtime rotation proxy request body is too large.",
+                    HTTP_STATUS.payload_too_large,
+                    "runtime_rotation_proxy_payload_too_large",
+                )));
+            }
+            collected.extend_from_slice(&data);
+        }
+    }
+    Ok(collected)
+}
+
+async fn handle_request(shared: Arc<ProxyShared>, req: Request<Incoming>) -> Response<ProxyBody> {
+    let trace_id = uuid::Uuid::new_v4().to_string();
+    run_with_correlation_id(
+        Some(trace_id.clone()),
+        handle_request_inner(shared, req, trace_id),
+    )
+    .await
+}
+
+async fn handle_request_inner(
+    shared: Arc<ProxyShared>,
+    req: Request<Incoming>,
+    trace_id: String,
+) -> Response<ProxyBody> {
+    let usage_slot: Arc<StdMutex<Option<Arc<RuntimeUsageRecorder>>>> =
+        Arc::new(StdMutex::new(None));
+    match run_request(Arc::clone(&shared), req, &trace_id, Arc::clone(&usage_slot)).await {
+        Ok(response) => response,
+        Err(error) => {
+            let (raw_message, code, http_error) = match &error {
+                HandlerError::Http(http_error) => (
+                    http_error.message.clone(),
+                    http_error.code.clone(),
+                    Some(http_error.clone()),
+                ),
+                HandlerError::Other(message) => (
+                    message.clone(),
+                    "codex_runtime_rotation_proxy_error".to_string(),
+                    None,
+                ),
+            };
+            // errors-logging-08: redact before status/log consumers see it.
+            let masked = mask_string(&raw_message);
+            {
+                let mut state = shared.pipeline.state().await;
+                state.status.last_error = Some(masked.clone());
+            }
+            create_logger("runtime-proxy").error(
+                "runtime proxy request failed",
+                Some(&json!({
+                    "traceId": trace_id,
+                    "code": code,
+                    "error": masked,
+                })),
+            );
+            let recorder = usage_slot
+                .lock()
+                .unwrap_or_else(|poison| poison.into_inner())
+                .clone();
+            match http_error {
+                Some(http_error) => {
+                    if let Some(recorder) = recorder {
+                        recorder
+                            .record(RuntimeUsageRecordInput {
+                                outcome: Some(UsageLedgerOutcome::Failure),
+                                status_code: Some(http_error.status_code as i64),
+                                error_code: Some(http_error.code.clone()),
+                                ..Default::default()
+                            })
+                            .await;
+                    }
+                    json_response(
+                        http_error.status_code,
+                        &json!({
+                            "error": { "message": http_error.message, "code": http_error.code }
+                        }),
+                    )
+                }
+                None => {
+                    if let Some(recorder) = recorder {
+                        recorder
+                            .record(RuntimeUsageRecordInput {
+                                outcome: Some(UsageLedgerOutcome::Failure),
+                                status_code: Some(500),
+                                error_code: Some("codex_runtime_rotation_proxy_error".to_string()),
+                                ..Default::default()
+                            })
+                            .await;
+                    }
+                    proxy_error_response()
+                }
+            }
+        }
+    }
+}
+
+fn account_ref(account: &ManagedAccount) -> RuntimePolicyAccount {
+    RuntimePolicyAccount {
+        index: account.index as i64,
+        account_id: account.meta.account_id.clone(),
+        email: account.meta.email.clone(),
+    }
+}
+
+async fn record_usage(
+    recorder: &Arc<RuntimeUsageRecorder>,
+    outcome: UsageLedgerOutcome,
+    status_code: u16,
+    error_code: Option<&str>,
+    account: Option<RuntimePolicyAccount>,
+) {
+    recorder
+        .record(RuntimeUsageRecordInput {
+            outcome: Some(outcome),
+            status_code: Some(status_code as i64),
+            error_code: error_code.map(str::to_string),
+            account,
+            ..Default::default()
+        })
+        .await;
+}
+
+async fn bump_transient_counters(shared: &Arc<ProxyShared>) {
+    let mut state = shared.pipeline.state().await;
+    state.status.retries += 1;
+    state.status.rotations += 1;
+}
+
+#[expect(
+    clippy::too_many_lines,
+    reason = "direct port of the TS handleRequestInner rotation loop; splitting \
+              would scatter the status-mapping contract the spec pins as one unit"
+)]
+async fn run_request(
+    shared: Arc<ProxyShared>,
+    req: Request<Incoming>,
+    trace_id: &str,
+    usage_slot: Arc<StdMutex<Option<Arc<RuntimeUsageRecorder>>>>,
+) -> Result<Response<ProxyBody>, HandlerError> {
+    let (parts, incoming_body) = req.into_parts();
+    let method = parts.method;
+    let pathname = parts.uri.path().to_string();
+    let query = parts.uri.query().map(str::to_string);
+    let incoming_headers = parts.headers;
+
+    // Per-request config snapshot + manager handle (one short lock).
+    let config: ReqConfig = {
+        let state = shared.pipeline.state().await;
+        ReqConfig {
+            client_api_key: state.client_api_key.clone(),
+            upstream_base_url: state.upstream_base_url.clone(),
+            fetch_client: state.fetch_client.clone(),
+            now: state.now.clone(),
+            routing_mutex_mode: state.routing_mutex_mode,
+            scheduling_strategy: state.scheduling_strategy,
+            pid_offset_enabled: state.pid_offset_enabled,
+            token_refresh_skew_ms: state.token_refresh_skew_ms,
+            network_error_cooldown_ms: state.network_error_cooldown_ms,
+            server_error_cooldown_ms: state.server_error_cooldown_ms,
+            token_invalidation_cooldown_ms: state.token_invalidation_cooldown_ms,
+            min_rotation_interval_ms: state.min_rotation_interval_ms,
+            fetch_timeout_ms: state.fetch_timeout_ms,
+            stream_stall_timeout_ms: state.stream_stall_timeout_ms,
+            max_runtime_account_attempts: state.max_runtime_account_attempts,
+            max_request_body_bytes: state.max_request_body_bytes,
+            quota_remaining_percent_threshold: state.quota_remaining_percent_threshold,
+            session_affinity_store: state.session_affinity_store.clone(),
+            forced_account_index: state.forced_account_index,
+        }
+    };
+    let now = || (config.now)();
+
+    // Authenticate BEFORE discriminating path/method (gotcha 22): an unknown
+    // caller always gets 401, never a path-confirming 404.
+    if !is_authorized_client(&incoming_headers, &config.client_api_key) {
+        return Ok(write_unauthorized());
+    }
+
+    let is_responses_request = method == http::Method::POST && is_responses_path(&pathname);
+    let is_models_request = method == http::Method::GET && is_models_path(&pathname);
+    let is_thread_goal_request = (method == http::Method::GET || method == http::Method::POST)
+        && is_thread_goal_path(&pathname);
+    if !is_responses_request && !is_models_request && !is_thread_goal_request {
+        return Ok(write_method_or_path_error());
+    }
+
+    {
+        let mut state = shared.pipeline.state().await;
+        state.status.total_requests += 1;
+    }
+
+    let request_body =
+        if is_responses_request || (is_thread_goal_request && method == http::Method::POST) {
+            read_request_body(incoming_body, config.max_request_body_bytes).await?
+        } else {
+            Vec::new()
+        };
+
+    // ---- SEAM: `/responses` goes through the merged pipeline ----
+    // The pipeline owns selection/refresh/forward/rotation AND the
+    // usage-ledger record (source runtime-proxy, operation responses); the
+    // server contributes auth, routing, the body cap, and the client-side
+    // stream forward. The incoming query string rides on `upstream_path`.
+    if is_responses_request {
+        let mut context = build_responses_request_context(incoming_headers, request_body);
+        if let Some(query) = query.as_deref()
+            && !query.is_empty()
+        {
+            context.upstream_path = format!("{}?{query}", context.upstream_path);
+        }
+        let outcome = shared
+            .pipeline
+            .handle_responses_for_server(context, Some(trace_id.to_string()))
+            .await;
+        let manager = {
+            let state = shared.pipeline.state().await;
+            state.active_account_manager.clone()
+        };
+        let crate::pipeline::ResponsesOutcome { response: upstream, deferred } = outcome;
+        // Streaming success: the forward stage decides the ledger row
+        // (`forwarded ? success : stream_forward_failed`) and owns the
+        // network-error cleanup on a mid-stream stall — exactly like the
+        // thread-goal forward below (TS runtime-rotation-proxy.ts:1424-1450).
+        let (cleanup, usage) = match deferred {
+            Some(deferred) => (
+                StreamCleanup::NetworkFailure {
+                    account_index: deferred.account_index,
+                    family: deferred.family,
+                    model: deferred.model,
+                    session_key: deferred.session_key,
+                    cooldown_ms: config.network_error_cooldown_ms,
+                },
+                Some(StreamUsage {
+                    recorder: Arc::new(deferred.recorder),
+                    status_code: upstream.status,
+                    account: deferred.success_completion.account,
+                    on_success: (UsageLedgerOutcome::Success, None),
+                    on_failure: (
+                        UsageLedgerOutcome::Failure,
+                        Some("stream_forward_failed".to_string()),
+                    ),
+                }),
+            ),
+            None => (StreamCleanup::None, None),
+        };
+        return Ok(stream_upstream_to_client(
+            Arc::clone(&shared),
+            manager,
+            upstream,
+            config.stream_stall_timeout_ms,
+            cleanup,
+            usage,
+        )
+        .await);
+    }
+
+    // ---- Server-owned routes: /models and /thread/goal/* ----
+    let context = if is_models_request {
+        build_models_request_context(incoming_headers.clone())
+    } else {
+        build_thread_goal_request_context(
+            incoming_headers.clone(),
+            request_body,
+            &pathname,
+            query.as_deref(),
+            method == http::Method::GET,
+        )
+    };
+    let request_started_at = now();
+
+    let mut account_manager: SharedAccountManager = {
+        let state = shared.pipeline.state().await;
+        state.active_account_manager.clone()
+    };
+
+    // Runtime policy gate (server-owned routes FAIL CLOSED — spec 04).
+    let mut policy_decision: Option<RuntimePolicyDecision> = None;
+    let mut policy_error: Option<String> = None;
+    let project_key: Option<String>;
+    {
+        let start_dir = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
+        let policy_state = load_runtime_policy_state(&start_dir).await;
+        project_key = policy_state.project.project_key.clone();
+        let accounts: Vec<RuntimePolicyAccount> = {
+            let mut manager = account_manager.lock().await;
+            manager
+                .get_accounts_snapshot()
+                .iter()
+                .map(account_ref)
+                .collect()
+        };
+        match evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &accounts,
+            model: context.model.as_deref(),
+            capability_policy: None,
+            now: Some(request_started_at),
+        })
+        .await
+        {
+            Ok(decision) => {
+                let mut blocked: Vec<i64> =
+                    decision.blocked_account_indexes.iter().copied().collect();
+                blocked.sort_unstable();
+                mutate_runtime_observability_snapshot(|snapshot| {
+                    snapshot.policy_blocked_indexes = blocked.clone();
+                    let mut reasons = Map::new();
+                    for index in &blocked {
+                        reasons.insert(
+                            index.to_string(),
+                            Value::String("policy-blocked".to_string()),
+                        );
+                    }
+                    snapshot.policy_blocked_reasons = reasons;
+                });
+                policy_decision = Some(decision);
+            }
+            Err(error) => {
+                let message = error.to_string();
+                policy_error = Some(message.clone());
+                let mut state = shared.pipeline.state().await;
+                state.status.last_error = Some(message);
+            }
+        }
+    }
+    let usage_recorder = Arc::new(create_runtime_usage_recorder(RuntimeUsageRecorderOptions {
+        source: UsageLedgerSource::RuntimeProxy,
+        operation: if is_models_request {
+            UsageLedgerOperation::Models
+        } else {
+            UsageLedgerOperation::ThreadGoal
+        },
+        model: context.model.clone(),
+        project_key,
+        request_id: Some(trace_id.to_string()),
+        started_at: Some(request_started_at),
+        append: None,
+    }));
+    *usage_slot
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner()) = Some(Arc::clone(&usage_recorder));
+    if policy_error.is_some() {
+        record_usage(
+            &usage_recorder,
+            UsageLedgerOutcome::Failure,
+            HTTP_STATUS.service_unavailable,
+            Some("runtime_policy_unavailable"),
+            None,
+        )
+        .await;
+        return Ok(json_response(
+            HTTP_STATUS.service_unavailable,
+            &json!({
+                "error": {
+                    "message": "Runtime policy could not be loaded for this local request.",
+                    "code": "runtime_policy_unavailable",
+                }
+            }),
+        ));
+    }
+    if let Some(decision) = policy_decision.as_ref()
+        && !decision.allowed
+    {
+        record_usage(
+            &usage_recorder,
+            UsageLedgerOutcome::Blocked,
+            decision.status_code,
+            decision.error_code.as_deref(),
+            None,
+        )
+        .await;
+        return Ok(json_response(
+            decision.status_code,
+            &json!({
+                "error": {
+                    "message": "Runtime policy blocked this local request.",
+                    "code": decision
+                        .error_code
+                        .clone()
+                        .unwrap_or_else(|| "policy_blocked".to_string()),
+                    "reasons": decision.reasons,
+                }
+            }),
+        ));
+    }
+
+    let upstream_url = build_upstream_url(
+        &config.upstream_base_url,
+        &context.upstream_path,
+        query.as_deref(),
+    )?;
+
+    let mut attempted_indexes: HashSet<i64> = HashSet::new();
+    let mut exhaustion_reason = ExhaustionReason::NoAccount;
+    let mut account_count = account_manager.lock().await.get_account_count() as i64;
+    let mut transient_attempt_limit = account_count
+        .min(config.max_runtime_account_attempts)
+        .max(1);
+    let mut transient_attempts: i64 = 0;
+    let mut transient_exhaustion_reason: Option<ExhaustionReason> = None;
+    let mut skip_map: HashMap<i64, String> = HashMap::new();
+    let mut skip_order: Vec<(i64, String)> = Vec::new();
+    let mut reloaded_after_no_account = false;
+
+    // Per-request pin/affinity read (sha1-content-hash cached — #474/#623).
+    // Forced index 0 must win, hence `.or(...)` (TS `??`).
+    let storage_meta = read_storage_meta_from_disk(None);
+    let pinned_index = config
+        .forced_account_index
+        .or(storage_meta.pinned_account_index);
+    let is_pinned = pinned_index.is_some();
+    {
+        let mut state = shared.pipeline.state().await;
+        if storage_meta.affinity_generation > state.last_observed_affinity_generation {
+            if let Some(store) = state.session_affinity_store.clone() {
+                store
+                    .lock()
+                    .unwrap_or_else(|poison| poison.into_inner())
+                    .clear_all();
+            }
+            state.last_observed_affinity_generation = storage_meta.affinity_generation;
+        }
+    }
+
+    while (attempted_indexes.len() as i64) < account_count
+        && transient_attempts < transient_attempt_limit
+    {
+        // Sticky boost: keep the proxy on the last-served account within the
+        // min-rotation window (flat 1000).
+        let rotation_sticky_boost: HashMap<i64, f64> = {
+            let state = shared.pipeline.state().await;
+            match state.last_global_account_index {
+                Some(last_index)
+                    if config.min_rotation_interval_ms > 0
+                        && now() - state.last_global_switch_at
+                            < config.min_rotation_interval_ms =>
+                {
+                    let mut boost = HashMap::new();
+                    boost.insert(last_index, 1000.0);
+                    boost
+                }
+                _ => HashMap::new(),
+            }
+        };
+
+        // Selection. In `enabled` mode, run selection AND the cursor
+        // re-commit inside ONE routing-mutex acquisition (L4 fix); the inner
+        // `mark_switched_locked` runs inline via the reentrancy flag. Skips:
+        // pinned (#474) and sequential (#509).
+        let selected: Option<ManagedAccount> = {
+            let manager = account_manager.clone();
+            let affinity = config.session_affinity_store.clone();
+            let session_key = context.session_key.as_deref();
+            let family = context.family;
+            let model = context.model.as_deref();
+            let attempted = &attempted_indexes;
+            let policy = policy_decision.as_ref();
+            let skip = &mut skip_map;
+            let boost = &rotation_sticky_boost;
+            let selection_now = now();
+            if config.routing_mutex_mode == RoutingMutexMode::Enabled {
+                with_routing_mutex(RoutingMutexMode::Enabled, || async move {
+                    let mut mgr = manager.lock().await;
+                    let candidate = {
+                        let mut affinity_guard = affinity
+                            .as_ref()
+                            .map(|store| store.lock().unwrap_or_else(|poison| poison.into_inner()));
+                        choose_account(ChooseAccountParams {
+                            account_manager: &mut mgr,
+                            session_affinity_store: affinity_guard.as_deref_mut(),
+                            session_key,
+                            family,
+                            model,
+                            attempted_indexes: attempted,
+                            now: selection_now,
+                            policy,
+                            pinned_index,
+                            skip_reasons: Some(skip),
+                            sticky_boost_by_account: Some(boost),
+                            pid_offset_enabled: config.pid_offset_enabled,
+                            scheduling_strategy: config.scheduling_strategy,
+                        })
+                    };
+                    if let Some(candidate) = &candidate
+                        && pinned_index.is_none()
+                        && config.scheduling_strategy != SchedulingStrategy::Sequential
+                    {
+                        mgr.mark_switched_locked(
+                            candidate.index as i64,
+                            SwitchReason::Rotation,
+                            family,
+                            None,
+                        )
+                        .await;
+                    }
+                    candidate
+                })
+                .await
+            } else {
+                let mut mgr = manager.lock().await;
+                let mut affinity_guard = affinity
+                    .as_ref()
+                    .map(|store| store.lock().unwrap_or_else(|poison| poison.into_inner()));
+                choose_account(ChooseAccountParams {
+                    account_manager: &mut mgr,
+                    session_affinity_store: affinity_guard.as_deref_mut(),
+                    session_key,
+                    family,
+                    model,
+                    attempted_indexes: attempted,
+                    now: selection_now,
+                    policy,
+                    pinned_index,
+                    skip_reasons: Some(skip),
+                    sticky_boost_by_account: Some(boost),
+                    pid_offset_enabled: config.pid_offset_enabled,
+                    scheduling_strategy: config.scheduling_strategy,
+                })
+            }
+        };
+        sync_skip_order(&mut skip_order, &skip_map);
+
+        let Some(selected) = selected else {
+            // One-shot stale-state recovery (issue #606). Only policy blocks
+            // suppress it; transient "rate-limited"/"cooling-down*" reasons
+            // deliberately do NOT.
+            let policy_blocked_empty = policy_decision
+                .as_ref()
+                .is_none_or(|decision| decision.blocked_account_indexes.is_empty());
+            let has_policy_skip = skip_map.values().any(|reason| reason == "policy-blocked");
+            if !reloaded_after_no_account
+                && !is_pinned
+                && account_count > 0
+                && exhaustion_reason == ExhaustionReason::NoAccount
+                && policy_blocked_empty
+                && !has_policy_skip
+            {
+                reloaded_after_no_account = true;
+                let reloaded = {
+                    let mut state = shared.pipeline.state().await;
+                    recover_stale_runtime_state(&mut state).await
+                };
+                if let Some(reloaded_manager) = reloaded {
+                    account_manager = reloaded_manager;
+                    account_count = account_manager.lock().await.get_account_count() as i64;
+                    transient_attempt_limit = account_count
+                        .min(config.max_runtime_account_attempts)
+                        .max(1);
+                    skip_map.clear();
+                    skip_order.clear();
+                    attempted_indexes.clear();
+                    continue;
+                }
+            }
+            break;
+        };
+        let selected_index = selected.index as i64;
+        attempted_indexes.insert(selected_index);
+
+        // Local token bucket — a refusal is NOT a transient attempt.
+        let consumed = {
+            let mut mgr = account_manager.lock().await;
+            mgr.consume_token(selected_index, context.family, context.model.as_deref())
+        };
+        if !consumed {
+            record_skip(
+                &mut skip_order,
+                &mut skip_map,
+                selected_index,
+                "token-exhausted",
+            );
+            exhaustion_reason = ExhaustionReason::RateLimit;
+            continue;
+        }
+
+        // Token freshness.
+        let refreshed = ensure_fresh_access_token(EnsureFreshAccessTokenParams {
+            account_manager: &account_manager,
+            account: &selected,
+            family: context.family,
+            model: context.model.as_deref(),
+            now: now(),
+            token_refresh_skew_ms: config.token_refresh_skew_ms,
+            token_invalidation_cooldown_ms: config.token_invalidation_cooldown_ms,
+        })
+        .await;
+        let (access_token, refreshed_account) = match refreshed {
+            EnsureFreshAccessTokenResult::Failed {
+                retryable,
+                invalidated,
+            } => {
+                {
+                    let mut mgr = account_manager.lock().await;
+                    mgr.refund_token(selected_index, context.family, context.model.as_deref());
+                }
+                exhaustion_reason = ExhaustionReason::AuthFailure;
+                if invalidated {
+                    // Refresh endpoint explicitly revoked the token — STOP the
+                    // cascade: 401 to the client, no rotation (gotcha 10).
+                    forget_affinity(&shared, context.session_key.as_deref()).await;
+                    record_usage(
+                        &usage_recorder,
+                        UsageLedgerOutcome::Failure,
+                        HTTP_STATUS.unauthorized,
+                        Some("token_invalidated"),
+                        Some(account_ref(&selected)),
+                    )
+                    .await;
+                    return Ok(Response::builder()
+                        .status(HTTP_STATUS.unauthorized)
+                        .header("content-type", "application/json")
+                        .body(full_body(build_token_invalidation_body("")))
+                        .unwrap_or_else(|_| proxy_error_response()));
+                }
+                if !retryable {
+                    continue;
+                }
+                transient_attempts += 1;
+                transient_exhaustion_reason = Some(ExhaustionReason::AuthFailure);
+                bump_transient_counters(&shared).await;
+                continue;
+            }
+            EnsureFreshAccessTokenResult::Ok {
+                access_token,
+                account,
+            } => (access_token, account),
+        };
+        let refreshed_index = refreshed_account.index as i64;
+
+        // Account id.
+        let account_id = read_trimmed_string(refreshed_account.meta.account_id.as_deref())
+            .or_else(|| {
+                extract_account_id(Some(access_token.as_str()))
+                    .map(|id| id.trim().to_string())
+                    .filter(|id| !id.is_empty())
+            });
+        let Some(account_id) = account_id else {
+            {
+                let mut mgr = account_manager.lock().await;
+                mgr.refund_token(refreshed_index, context.family, context.model.as_deref());
+                mgr.record_failure(refreshed_index, context.family, context.model.as_deref());
+                mgr.mark_account_cooling_down(
+                    refreshed_index,
+                    DEFAULT_AUTH_FAILURE_COOLDOWN_MS,
+                    CooldownReason::AuthFailure,
+                );
+            }
+            // Cooldowns are serialized in the V3 snapshot — persist like
+            // every other cooldown branch (gotcha 19).
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            exhaustion_reason = ExhaustionReason::AuthFailure;
+            transient_attempts += 1;
+            transient_exhaustion_reason = Some(ExhaustionReason::AuthFailure);
+            bump_transient_counters(&shared).await;
+            continue;
+        };
+
+        // Record the served identity (label only — email intentionally null).
+        let identity_updated_at = now();
+        let identity_label = format!("Account {}", refreshed_index + 1);
+        let identity_account_id = read_trimmed_string(refreshed_account.meta.account_id.as_deref());
+        {
+            let mut state = shared.pipeline.state().await;
+            state.status.last_account_index = Some(refreshed_index);
+            state.status.last_account_label = Some(identity_label.clone());
+            state.status.last_account_id = identity_account_id.clone();
+            state.status.last_account_updated_at = Some(identity_updated_at);
+        }
+        mutate_runtime_observability_snapshot(|snapshot| {
+            snapshot.last_account_index = Some(refreshed_index);
+            snapshot.last_account_label = Some(identity_label.clone());
+            snapshot.last_account_email = None;
+            snapshot.last_account_id = identity_account_id.clone();
+            snapshot.last_account_updated_at = Some(identity_updated_at);
+        });
+
+        let outbound_headers = create_outbound_headers(&context.headers, &access_token, &account_id);
+
+        // Upstream fetch.
+        {
+            let mut state = shared.pipeline.state().await;
+            state.status.upstream_requests += 1;
+        }
+        let request_builder = config
+            .fetch_client
+            .request(
+                match context.method {
+                    RequestMethod::Post => reqwest::Method::POST,
+                    RequestMethod::Get => reqwest::Method::GET,
+                },
+                &upstream_url,
+            )
+            .headers(outbound_headers);
+        let request_builder = if context.method == RequestMethod::Post {
+            request_builder.body(context.body.clone())
+        } else {
+            request_builder
+        };
+        let timeout_message =
+            format!("upstream fetch timed out after {}ms", config.fetch_timeout_ms);
+        let fetch_result = with_timeout(
+            request_builder.send(),
+            config.fetch_timeout_ms as f64,
+            || {},
+            &timeout_message,
+        )
+        .await;
+        let upstream_response = match fetch_result {
+            Ok(Ok(response)) => response,
+            Ok(Err(error)) => {
+                handle_fetch_failure(
+                    &shared,
+                    &account_manager,
+                    &config,
+                    &context,
+                    refreshed_index,
+                    error.to_string(),
+                )
+                .await;
+                exhaustion_reason = ExhaustionReason::NetworkError;
+                transient_attempts += 1;
+                transient_exhaustion_reason = Some(ExhaustionReason::NetworkError);
+                bump_transient_counters(&shared).await;
+                continue;
+            }
+            Err(timeout_error) => {
+                handle_fetch_failure(
+                    &shared,
+                    &account_manager,
+                    &config,
+                    &context,
+                    refreshed_index,
+                    timeout_error.to_string(),
+                )
+                .await;
+                exhaustion_reason = ExhaustionReason::NetworkError;
+                transient_attempts += 1;
+                transient_exhaustion_reason = Some(ExhaustionReason::NetworkError);
+                bump_transient_counters(&shared).await;
+                continue;
+            }
+        };
+        let mut upstream = to_stream_response(upstream_response);
+        let upstream_status = upstream.status;
+
+        // ---- Status mapping (exact order) ----
+        if upstream_status == HTTP_STATUS.too_many_requests {
+            let body_text =
+                read_error_body(&mut upstream, config.stream_stall_timeout_ms as f64, None).await;
+            let retry_after_ms = parse_retry_after_header_ms(&upstream.headers, now())
+                .or_else(|| parse_retry_after_body_ms(&body_text, now()))
+                .unwrap_or(60_000);
+            // 429 = genuine quota consumption: token NOT refunded (gotcha 17).
+            {
+                let mut mgr = account_manager.lock().await;
+                mgr.record_rate_limit(refreshed_index, context.family, context.model.as_deref());
+                mgr.mark_rate_limited_with_reason(
+                    refreshed_index,
+                    retry_after_ms,
+                    context.family,
+                    RateLimitReason::Quota,
+                    context.model.as_deref(),
+                );
+            }
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            exhaustion_reason = ExhaustionReason::RateLimit;
+            transient_attempts += 1;
+            transient_exhaustion_reason = Some(ExhaustionReason::RateLimit);
+            bump_transient_counters(&shared).await;
+            continue;
+        }
+
+        if upstream_status == 402 || upstream_status == HTTP_STATUS.forbidden {
+            let body_text =
+                read_error_body(&mut upstream, config.stream_stall_timeout_ms as f64, None).await;
+            let error_code = extract_error_code_from_body(&body_text);
+            let code_value = error_code.clone().map(Value::String).unwrap_or(Value::Null);
+            if is_workspace_disabled_error(upstream_status, &code_value, &body_text) {
+                let account_was_enabled = {
+                    let mgr = account_manager.lock().await;
+                    !matches!(
+                        mgr.get_account_by_index(refreshed_index),
+                        Some(account) if !account.is_enabled()
+                    )
+                };
+                {
+                    let mut mgr = account_manager.lock().await;
+                    mgr.refund_token(refreshed_index, context.family, context.model.as_deref());
+                    if account_was_enabled {
+                        mgr.record_failure(
+                            refreshed_index,
+                            context.family,
+                            context.model.as_deref(),
+                        );
+                        mgr.set_account_enabled(refreshed_index, false);
+                    }
+                }
+                if account_was_enabled {
+                    account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                }
+                forget_affinity(&shared, context.session_key.as_deref()).await;
+                exhaustion_reason = ExhaustionReason::Deactivated;
+                // Deactivation bumps retries/rotations but NOT the transient
+                // budget.
+                bump_transient_counters(&shared).await;
+                continue;
+            }
+
+            if is_thread_goal_request && upstream_status == HTTP_STATUS.forbidden {
+                // Local memory of goals when upstream forbids them.
+                let parsed_goal_body = parse_request_body(&context.body);
+                let goal = parsed_goal_body
+                    .as_ref()
+                    .and_then(|body| body.get("goal"))
+                    .and_then(Value::as_str)
+                    .map(str::to_string);
+                match context.session_key.clone() {
+                    None => {
+                        if context.upstream_path.ends_with("/get") {
+                            let response = json_response(HTTP_STATUS.ok, &json!({ "goal": null }));
+                            record_usage(
+                                &usage_recorder,
+                                UsageLedgerOutcome::Failure,
+                                upstream_status,
+                                Some("thread_goal_session_key_required"),
+                                Some(account_ref(&refreshed_account)),
+                            )
+                            .await;
+                            return Ok(response);
+                        }
+                        record_usage(
+                            &usage_recorder,
+                            UsageLedgerOutcome::Failure,
+                            HTTP_STATUS.bad_request,
+                            Some("thread_goal_session_key_required"),
+                            Some(account_ref(&refreshed_account)),
+                        )
+                        .await;
+                        return Ok(json_response(
+                            HTTP_STATUS.bad_request,
+                            &json!({
+                                "error": {
+                                    "message": "Thread goal fallback requires a thread_id, threadId, or session header.",
+                                    "code": "thread_goal_session_key_required",
+                                }
+                            }),
+                        ));
+                    }
+                    Some(fallback_key) => {
+                        record_usage(
+                            &usage_recorder,
+                            UsageLedgerOutcome::Failure,
+                            upstream_status,
+                            Some("thread_goal_upstream_blocked"),
+                            Some(account_ref(&refreshed_account)),
+                        )
+                        .await;
+                        if context.upstream_path.ends_with("/set") {
+                            {
+                                let mut order = shared.thread_goal_order.lock().await;
+                                let mut state = shared.pipeline.state().await;
+                                set_thread_goal_fallback(
+                                    &mut state,
+                                    &mut order,
+                                    &fallback_key,
+                                    goal.clone(),
+                                );
+                            }
+                            return Ok(json_response(
+                                HTTP_STATUS.ok,
+                                &json!({ "ok": true, "goal": goal }),
+                            ));
+                        }
+                        let stored = {
+                            let mut order = shared.thread_goal_order.lock().await;
+                            let mut state = shared.pipeline.state().await;
+                            get_thread_goal_fallback(&mut state, &mut order, &fallback_key)
+                        };
+                        return Ok(json_response(HTTP_STATUS.ok, &json!({ "goal": stored })));
+                    }
+                }
+            }
+
+            if is_thread_goal_request && context.upstream_path.ends_with("/get") {
+                let response = json_response(HTTP_STATUS.ok, &json!({ "goal": null }));
+                record_usage(
+                    &usage_recorder,
+                    UsageLedgerOutcome::Failure,
+                    upstream_status,
+                    error_code.as_deref(),
+                    Some(account_ref(&refreshed_account)),
+                )
+                .await;
+                return Ok(response);
+            }
+            // Forward the client-safe headers + body verbatim.
+            let mut builder = Response::builder().status(upstream_status);
+            for (name, value) in response_headers_for_client(&upstream.headers) {
+                builder = builder.header(name, value);
+            }
+            let response = builder
+                .body(full_body(body_text))
+                .unwrap_or_else(|_| proxy_error_response());
+            record_usage(
+                &usage_recorder,
+                UsageLedgerOutcome::Failure,
+                upstream_status,
+                error_code.as_deref(),
+                Some(account_ref(&refreshed_account)),
+            )
+            .await;
+            return Ok(response);
+        }
+
+        if upstream_status == HTTP_STATUS.unauthorized {
+            let body_text =
+                read_error_body(&mut upstream, config.stream_stall_timeout_ms as f64, None).await;
+            {
+                let mut mgr = account_manager.lock().await;
+                mgr.refund_token(refreshed_index, context.family, context.model.as_deref());
+                mgr.record_failure(refreshed_index, context.family, context.model.as_deref());
+            }
+            if is_token_invalidation_error(&body_text) {
+                // Explicit upstream revocation: long cooldown, no rotation
+                // (cascade-invalidation defense), 401 straight to the client.
+                {
+                    let mut mgr = account_manager.lock().await;
+                    apply_monotonic_auth_cooldown(
+                        &mut mgr,
+                        &refreshed_account,
+                        config.token_invalidation_cooldown_ms,
+                    );
+                }
+                forget_affinity(&shared, context.session_key.as_deref()).await;
+                account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                let mut client_headers = response_headers_for_client(&upstream.headers);
+                client_headers.retain(|(name, _)| name != "content-type");
+                client_headers.push(("content-type".to_string(), "application/json".to_string()));
+                let mut builder = Response::builder().status(upstream_status);
+                for (name, value) in client_headers {
+                    builder = builder.header(name, value);
+                }
+                let response = builder
+                    .body(full_body(build_token_invalidation_body(&body_text)))
+                    .unwrap_or_else(|_| proxy_error_response());
+                record_usage(
+                    &usage_recorder,
+                    UsageLedgerOutcome::Failure,
+                    upstream_status,
+                    Some("token_invalidated"),
+                    Some(account_ref(&refreshed_account)),
+                )
+                .await;
+                return Ok(response);
+            }
+            {
+                let mut mgr = account_manager.lock().await;
+                apply_monotonic_auth_cooldown(
+                    &mut mgr,
+                    &refreshed_account,
+                    DEFAULT_AUTH_FAILURE_COOLDOWN_MS,
+                );
+            }
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            exhaustion_reason = ExhaustionReason::AuthFailure;
+            transient_attempts += 1;
+            transient_exhaustion_reason = Some(ExhaustionReason::AuthFailure);
+            bump_transient_counters(&shared).await;
+            continue;
+        }
+
+        if upstream_status >= 500 {
+            let _ =
+                read_error_body(&mut upstream, config.stream_stall_timeout_ms as f64, None).await;
+            {
+                let mut mgr = account_manager.lock().await;
+                mgr.refund_token(refreshed_index, context.family, context.model.as_deref());
+                mgr.record_failure(refreshed_index, context.family, context.model.as_deref());
+                mgr.mark_account_cooling_down(
+                    refreshed_index,
+                    config.server_error_cooldown_ms,
+                    CooldownReason::ServerError,
+                );
+            }
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            exhaustion_reason = ExhaustionReason::ServerError;
+            transient_attempts += 1;
+            transient_exhaustion_reason = Some(ExhaustionReason::ServerError);
+            bump_transient_counters(&shared).await;
+            continue;
+        }
+
+        if is_thread_goal_request && upstream_status >= 400 {
+            if context.upstream_path.ends_with("/get") {
+                let response = json_response(HTTP_STATUS.ok, &json!({ "goal": null }));
+                record_usage(
+                    &usage_recorder,
+                    UsageLedgerOutcome::Failure,
+                    upstream_status,
+                    Some("thread_goal_upstream_error"),
+                    Some(account_ref(&refreshed_account)),
+                )
+                .await;
+                return Ok(response);
+            }
+            return Ok(stream_upstream_to_client(
+                Arc::clone(&shared),
+                account_manager.clone(),
+                upstream,
+                config.stream_stall_timeout_ms,
+                StreamCleanup::None,
+                Some(StreamUsage {
+                    recorder: Arc::clone(&usage_recorder),
+                    status_code: upstream_status,
+                    account: Some(account_ref(&refreshed_account)),
+                    on_success: (
+                        UsageLedgerOutcome::Failure,
+                        Some("thread_goal_upstream_error".to_string()),
+                    ),
+                    on_failure: (
+                        UsageLedgerOutcome::Failure,
+                        Some("stream_forward_failed".to_string()),
+                    ),
+                }),
+            )
+            .await);
+        }
+
+        // ---- Success (2xx/3xx) ----
+        account_manager
+            .record_success(refreshed_index, context.family, context.model.as_deref())
+            .await;
+        // Clear any persisted runtime skip-reason overlay (no-op when none —
+        // the hot path stays write-free).
+        record_runtime_account_recovery(refreshed_index);
+        let near_exhaustion_wait_ms = get_quota_near_exhaustion_wait_ms(
+            &upstream.headers,
+            config.quota_remaining_percent_threshold,
+            now(),
+        );
+        if near_exhaustion_wait_ms > 0 {
+            {
+                let mut mgr = account_manager.lock().await;
+                mgr.mark_rate_limited_with_reason(
+                    refreshed_index,
+                    near_exhaustion_wait_ms,
+                    context.family,
+                    RateLimitReason::Quota,
+                    context.model.as_deref(),
+                );
+            }
+            forget_affinity(&shared, context.session_key.as_deref()).await;
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        } else {
+            if let Some(store) = config.session_affinity_store.as_ref() {
+                store
+                    .lock()
+                    .unwrap_or_else(|poison| poison.into_inner())
+                    .remember(context.session_key.as_deref(), refreshed_index, now());
+            }
+            let mut state = shared.pipeline.state().await;
+            if state.last_global_account_index != Some(refreshed_index) {
+                state.last_global_account_index = Some(refreshed_index);
+            }
+            state.last_global_switch_at = now();
+        }
+        persist_runtime_active_account(
+            &account_manager,
+            refreshed_index,
+            context.family,
+            is_pinned && pinned_index == Some(refreshed_index),
+            config.scheduling_strategy,
+        )
+        .await;
+
+        return Ok(stream_upstream_to_client(
+            Arc::clone(&shared),
+            account_manager.clone(),
+            upstream,
+            config.stream_stall_timeout_ms,
+            StreamCleanup::NetworkFailure {
+                account_index: refreshed_index,
+                family: context.family,
+                model: context.model.clone(),
+                session_key: context.session_key.clone(),
+                cooldown_ms: config.network_error_cooldown_ms,
+            },
+            Some(StreamUsage {
+                recorder: Arc::clone(&usage_recorder),
+                status_code: upstream_status,
+                account: Some(account_ref(&refreshed_account)),
+                on_success: (UsageLedgerOutcome::Success, None),
+                on_failure: (
+                    UsageLedgerOutcome::Failure,
+                    Some("stream_forward_failed".to_string()),
+                ),
+            }),
+        )
+        .await);
+    }
+
+    // ---- Loop exit / exhaustion ----
+    if transient_attempts >= transient_attempt_limit
+        && (attempted_indexes.len() as i64) < account_count
+    {
+        exhaustion_reason = ExhaustionReason::Budget;
+    } else if exhaustion_reason == ExhaustionReason::Deactivated
+        && let Some(transient) = transient_exhaustion_reason
+    {
+        exhaustion_reason = transient;
+    }
+
+    // Pinned: hard-fail 503 — never silently fall through to rotation (#474;
+    // structured reason per #486).
+    if is_pinned {
+        let ordered: Vec<(usize, String)> = skip_order
+            .iter()
+            .filter(|(index, _)| *index >= 0)
+            .map(|(index, reason)| (*index as usize, reason.clone()))
+            .collect();
+        let error_body = build_pinned_unavailable_error_body(pinned_index, &ordered);
+        if error_body.reason.is_none() {
+            let mut state = shared.pipeline.state().await;
+            state.status.last_error = Some(format!(
+                "pinned-503 missing skip reason (pinnedIndex={})",
+                pinned_index.unwrap_or_default()
+            ));
+        }
+        record_usage(
+            &usage_recorder,
+            UsageLedgerOutcome::Failure,
+            HTTP_STATUS.service_unavailable,
+            Some("codex_pinned_account_unavailable"),
+            None,
+        )
+        .await;
+        return Ok(json_response(
+            HTTP_STATUS.service_unavailable,
+            &json!({ "error": serde_json::to_value(&error_body).unwrap_or(Value::Null) }),
+        ));
+    }
+
+    let is_thread_goal_get = is_thread_goal_request && context.upstream_path.ends_with("/get");
+    record_usage(
+        &usage_recorder,
+        UsageLedgerOutcome::Failure,
+        normalize_exhaustion_status(exhaustion_reason.as_str()),
+        Some(if is_thread_goal_get {
+            "thread_goal_pool_exhausted"
+        } else {
+            exhaustion_reason.as_str()
+        }),
+        None,
+    )
+    .await;
+    if is_thread_goal_get {
+        return Ok(json_response(HTTP_STATUS.ok, &json!({ "goal": null })));
+    }
+
+    // TS `writePoolExhausted`.
+    let (wait_ms, final_account_count) = {
+        let mut mgr = account_manager.lock().await;
+        (
+            mgr.get_min_wait_time_for_family(context.family, context.model.as_deref()),
+            mgr.get_account_count() as i64,
+        )
+    };
+    let skip_reasons_json = skip_reasons_to_json(&skip_order);
+    record_runtime_pool_exhaustion(exhaustion_reason.as_str(), wait_ms, &skip_reasons_json);
+    let hint = if exhaustion_reason == ExhaustionReason::NoAccount && final_account_count > 0 {
+        "Accounts exist but all failed runtime availability checks. Run `codex-multi-auth report --json` to inspect runtime skip reasons, or `codex-multi-auth rotation reset-runtime` to reload the runtime proxy."
+    } else {
+        "Run `codex-multi-auth rotation status` to inspect account state."
+    };
+    Ok(json_response(
+        normalize_exhaustion_status(exhaustion_reason.as_str()),
+        &json!({
+            "error": {
+                "message": "All managed Codex accounts are temporarily unavailable for this runtime request.",
+                "code": "codex_runtime_rotation_pool_exhausted",
+                "reason": exhaustion_reason.as_str(),
+                "retry_after_ms": wait_ms,
+                "account_skip_reasons": skip_reasons_json,
+                "hint": hint,
+            }
+        }),
+    ))
+}
+
+/// Shared fetch-failure bookkeeping (TS catch around the upstream fetch).
+async fn handle_fetch_failure(
+    shared: &Arc<ProxyShared>,
+    account_manager: &SharedAccountManager,
+    config: &ReqConfig,
+    context: &RequestContext,
+    account_index: i64,
+    message: String,
+) {
+    {
+        let mut state = shared.pipeline.state().await;
+        state.status.last_error = Some(message);
+    }
+    {
+        let mut mgr = account_manager.lock().await;
+        mgr.refund_token(account_index, context.family, context.model.as_deref());
+        mgr.record_failure(account_index, context.family, context.model.as_deref());
+        mgr.mark_account_cooling_down(
+            account_index,
+            config.network_error_cooldown_ms,
+            CooldownReason::NetworkError,
+        );
+    }
+    account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loopback_host_matrix_matches_ts() {
+        for host in ["127.0.0.1", "localhost", "::1", "[::1]", " LOCALHOST "] {
+            assert!(is_loopback_host(host), "{host} should be loopback");
+        }
+        for host in ["0.0.0.0", "192.168.1.10", "example.com", ""] {
+            assert!(!is_loopback_host(host), "{host} should NOT be loopback");
+        }
+    }
+
+    #[test]
+    fn ipv6_bind_and_url_hosts_normalize_once() {
+        assert_eq!(to_bind_host("[::1]"), "::1");
+        assert_eq!(to_bind_host("::1"), "::1");
+        assert_eq!(to_bind_host("127.0.0.1"), "127.0.0.1");
+        assert_eq!(to_url_host("::1"), "[::1]");
+        assert_eq!(to_url_host("[::1]"), "[::1]");
+        assert_eq!(to_url_host("localhost"), "localhost");
+    }
+
+    #[test]
+    fn path_discrimination_matches_the_allowed_sets() {
+        for path in [
+            "/responses",
+            "/codex/responses",
+            "/v1/responses",
+            "/v1/codex/responses",
+        ] {
+            assert!(is_responses_path(path), "{path}");
+        }
+        assert!(!is_responses_path("/foo/responses"));
+        assert!(!is_responses_path("/responses/"));
+        assert!(is_models_path("/models"));
+        assert!(is_models_path("/v1/models"));
+        assert!(!is_models_path("/v2/models"));
+        for path in [
+            "/thread/goal/get",
+            "/thread/goal/set",
+            "/codex/thread/goal/get",
+            "/codex/thread/goal/set",
+        ] {
+            assert!(is_thread_goal_path(path), "{path}");
+        }
+        assert_eq!(
+            normalize_thread_goal_upstream_path("/thread/goal/set"),
+            "/codex/thread/goal/set"
+        );
+        assert_eq!(
+            normalize_thread_goal_upstream_path("/codex/thread/goal/get"),
+            "/codex/thread/goal/get"
+        );
+    }
+
+    #[test]
+    fn session_key_resolution_precedence() {
+        let mut headers = HeaderMap::new();
+        headers.insert("session_id", "  header-key  ".parse().unwrap());
+        let body = parse_request_body(br#"{"prompt_cache_key":"body-key"}"#);
+        assert_eq!(
+            resolve_session_key(&headers, body.as_ref()),
+            Some("header-key".to_string())
+        );
+
+        let headers = HeaderMap::new();
+        let body =
+            parse_request_body(br#"{"prompt_cache_key":" cache ","previous_response_id":"prev"}"#);
+        assert_eq!(
+            resolve_session_key(&headers, body.as_ref()),
+            Some("cache".to_string())
+        );
+
+        let body = parse_request_body(br#"{"metadata":{"thread_id":"meta-thread"}}"#);
+        assert_eq!(
+            resolve_session_key(&HeaderMap::new(), body.as_ref()),
+            Some("meta-thread".to_string())
+        );
+        assert_eq!(resolve_session_key(&HeaderMap::new(), None), None);
+    }
+
+    #[test]
+    fn upstream_url_preserves_query_and_strips_trailing_base_slashes() {
+        let url = build_upstream_url(
+            "https://example.test/backend-api///",
+            "/codex/responses",
+            Some("a=1&b=2"),
+        )
+        .ok()
+        .unwrap();
+        assert_eq!(
+            url,
+            "https://example.test/backend-api/codex/responses?a=1&b=2"
+        );
+        let url = build_upstream_url("https://example.test/backend-api", "/models", None)
+            .ok()
+            .unwrap();
+        assert_eq!(url, "https://example.test/backend-api/models");
+    }
+
+    #[test]
+    fn outbound_headers_scrub_credentials_and_set_account_headers() {
+        let mut incoming = HeaderMap::new();
+        incoming.insert("cookie", "secret=1".parse().unwrap());
+        incoming.insert("x-api-key", "local".parse().unwrap());
+        incoming.insert("proxy-authorization", "Basic x".parse().unwrap());
+        incoming.insert("host", "127.0.0.1".parse().unwrap());
+        incoming.insert("connection", "keep-alive".parse().unwrap());
+        incoming.insert("x-custom", "kept".parse().unwrap());
+        let headers = create_outbound_headers(&incoming, "token-1", "acc_1");
+        assert!(headers.get("cookie").is_none());
+        assert!(headers.get("x-api-key").is_none());
+        assert!(headers.get("proxy-authorization").is_none());
+        assert!(headers.get("host").is_none());
+        assert!(headers.get("connection").is_none());
+        assert_eq!(headers.get("x-custom").unwrap(), "kept");
+        assert_eq!(headers.get("authorization").unwrap(), "Bearer token-1");
+        assert_eq!(headers.get("chatgpt-account-id").unwrap(), "acc_1");
+        assert_eq!(headers.get("OpenAI-Beta").unwrap(), "responses=experimental");
+        assert_eq!(headers.get("originator").unwrap(), "codex_cli_rs");
+    }
+
+    #[test]
+    fn thread_goal_lru_evicts_oldest_and_get_reinserts() {
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            let mut state = create_rotation_proxy_state(RotationProxyStateInit {
+                active_account_manager: SharedAccountManager::new(AccountManager::new(None, None)),
+                routing_mutex_mode: RoutingMutexMode::Legacy,
+                scheduling_strategy: SchedulingStrategy::Hybrid,
+                fetch_client: reqwest::Client::new(),
+                upstream_base_url: "https://example.test".to_string(),
+                client_api_key: "key".to_string(),
+                now: Arc::new(cma_core::utils::now_ms),
+                token_refresh_skew_ms: 0,
+                network_error_cooldown_ms: 0,
+                server_error_cooldown_ms: 0,
+                token_invalidation_cooldown_ms: 0,
+                min_rotation_interval_ms: 0,
+                pid_offset_enabled: false,
+                fetch_timeout_ms: 1_000,
+                stream_stall_timeout_ms: 1_000,
+                max_runtime_account_attempts: 4,
+                max_request_body_bytes: 1024,
+                quota_remaining_percent_threshold: 10.0,
+                session_affinity_store: None,
+                last_observed_affinity_generation: 0,
+                forced_account_index: None,
+            });
+            let mut order = VecDeque::new();
+            for index in 0..MAX_THREAD_GOAL_FALLBACKS + 1 {
+                set_thread_goal_fallback(
+                    &mut state,
+                    &mut order,
+                    &format!("key-{index}"),
+                    Some("g".into()),
+                );
+            }
+            assert_eq!(state.thread_goal_fallbacks.len(), MAX_THREAD_GOAL_FALLBACKS);
+            // key-0 (oldest) evicted.
+            assert!(!state.thread_goal_fallbacks.contains_key("key-0"));
+            // Stored null goals are distinguishable from absent keys.
+            set_thread_goal_fallback(&mut state, &mut order, "null-goal", None);
+            assert_eq!(
+                get_thread_goal_fallback(&mut state, &mut order, "null-goal"),
+                None
+            );
+            assert!(state.thread_goal_fallbacks.contains_key("null-goal"));
+            assert_eq!(
+                get_thread_goal_fallback(&mut state, &mut order, "absent"),
+                None
+            );
+            assert!(!state.thread_goal_fallbacks.contains_key("absent"));
+        });
+    }
+
+    #[test]
+    fn percent_decode_handles_plus_and_hex() {
+        assert_eq!(percent_decode("a+b"), "a b");
+        assert_eq!(percent_decode("thread%2Did"), "thread-id");
+        assert_eq!(percent_decode("plain"), "plain");
+        assert_eq!(percent_decode("bad%zz"), "bad%zz");
+    }
+}
diff --git a/crates/proxy/tests/local_bridge_test.rs b/crates/proxy/tests/local_bridge_test.rs
new file mode 100644
index 000000000..b8aefe3f5
--- /dev/null
+++ b/crates/proxy/tests/local_bridge_test.rs
@@ -0,0 +1,354 @@
+//! Port of `test/local-bridge.test.ts` — loopback + requireAuth invariants,
+//! header hygiene, upstream failure mapping, and usage-ledger rows with
+//! `source: "local-bridge"`.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use cma_auth::local_client_tokens::{LocalClientTokenRecord, create_local_client_token_record};
+use cma_proxy::local_bridge::{LocalBridgeOptions, VerifyBearerTokenFn, start_local_bridge};
+use cma_testkit::sandbox::EnvSandbox;
+use serde_json::{Value, json};
+use serial_test::serial;
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+fn record() -> LocalClientTokenRecord {
+    create_local_client_token_record(Some("test"), None).record
+}
+
+/// A verify seam that accepts everything and counts invocations.
+fn accept_all(counter: Arc<AtomicUsize>) -> VerifyBearerTokenFn {
+    Arc::new(move |_authorization, _now| {
+        counter.fetch_add(1, Ordering::SeqCst);
+        Box::pin(async move { Ok(Some(record())) })
+    })
+}
+
+/// A verify seam that rejects everything (returns `None`).
+fn reject_all() -> VerifyBearerTokenFn {
+    Arc::new(|_authorization, _now| Box::pin(async move { Ok(None) }))
+}
+
+async fn body_json(response: reqwest::Response) -> Value {
+    serde_json::from_str(&response.text().await.expect("body text")).expect("json body")
+}
+
+fn read_ledger_rows(sandbox: &EnvSandbox) -> Vec<Value> {
+    let path = sandbox
+        .codex_multi_auth_dir()
+        .join("usage")
+        .join("usage-ledger.jsonl");
+    match std::fs::read_to_string(path) {
+        Ok(content) => content
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .map(|line| serde_json::from_str(line).expect("ledger row json"))
+            .collect(),
+        Err(_) => Vec::new(),
+    }
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn startup_validation_uses_the_frozen_error_messages() {
+    let _sandbox = EnvSandbox::new();
+
+    let error = start_local_bridge(LocalBridgeOptions {
+        host: Some("0.0.0.0".to_string()),
+        runtime_base_url: "http://127.0.0.1:1456".to_string(),
+        ..Default::default()
+    })
+    .await
+    .expect_err("non-loopback bind host");
+    assert_eq!(error, "Local bridge only supports loopback hosts.");
+
+    let error = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "   ".to_string(),
+        ..Default::default()
+    })
+    .await
+    .expect_err("empty runtimeBaseUrl");
+    assert_eq!(error, "Local bridge requires a runtimeBaseUrl.");
+
+    let error = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "not a url".to_string(),
+        ..Default::default()
+    })
+    .await
+    .expect_err("invalid runtimeBaseUrl");
+    assert_eq!(
+        error,
+        "Local bridge runtimeBaseUrl is not a valid URL: not a url"
+    );
+
+    let error = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "https://example.com/backend".to_string(),
+        ..Default::default()
+    })
+    .await
+    .expect_err("non-loopback runtimeBaseUrl");
+    assert_eq!(
+        error,
+        "Local bridge refuses to forward to non-loopback runtimeBaseUrl host \"example.com\". It must target the loopback runtime proxy."
+    );
+
+    let error = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "http://127.0.0.1:1456".to_string(),
+        runtime_client_api_key: Some("runtime-key".to_string()),
+        require_auth: Some(false),
+        ..Default::default()
+    })
+    .await
+    .expect_err("key without inbound auth");
+    assert_eq!(
+        error,
+        "Local bridge requires requireAuth=true when runtimeClientApiKey is configured."
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn health_needs_no_auth_and_reports_the_trimmed_runtime_base_url() {
+    let _sandbox = EnvSandbox::new();
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "http://127.0.0.1:1456///".to_string(),
+        verify_bearer_token: Some(reject_all()),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+
+    let response = reqwest::get(format!("{}/health", bridge.base_url))
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    let body = body_json(response).await;
+    assert_eq!(body["ok"], true);
+    assert_eq!(body["service"], "codex-multi-auth-local-bridge");
+    // Trailing slashes stripped at startup.
+    assert_eq!(body["runtimeBaseUrl"], "http://127.0.0.1:1456");
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn unknown_paths_and_methods_get_the_stable_404() {
+    let _sandbox = EnvSandbox::new();
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "http://127.0.0.1:1456".to_string(),
+        verify_bearer_token: Some(accept_all(Arc::new(AtomicUsize::new(0)))),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+    let client = reqwest::Client::new();
+
+    for (send_method, url) in [
+        (reqwest::Method::GET, format!("{}/v1/other", bridge.base_url)),
+        // Method mismatches fall through to the catch-all 404.
+        (reqwest::Method::POST, format!("{}/v1/models", bridge.base_url)),
+        (reqwest::Method::GET, format!("{}/v1/responses", bridge.base_url)),
+        (reqwest::Method::POST, format!("{}/health", bridge.base_url)),
+    ] {
+        let response = client
+            .request(send_method.clone(), &url)
+            .send()
+            .await
+            .expect("request");
+        assert_eq!(response.status().as_u16(), 404, "{send_method} {url}");
+        let body = body_json(response).await;
+        assert_eq!(body["error"]["code"], "local_bridge_not_found");
+        assert_eq!(
+            body["error"]["message"],
+            "Local bridge only accepts /health, /v1/models, and /v1/responses."
+        );
+    }
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn rejects_unauthenticated_requests_with_401() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: upstream.uri(),
+        verify_bearer_token: Some(reject_all()),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/v1/models", bridge.base_url))
+        .header("authorization", "Bearer nope")
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 401);
+    assert_eq!(
+        response.headers().get("content-type").unwrap(),
+        "application/json; charset=utf-8"
+    );
+    let body = body_json(response).await;
+    assert_eq!(body["error"]["code"], "local_bridge_unauthorized");
+    assert_eq!(
+        body["error"]["message"],
+        "Local bridge rejected an unauthenticated request."
+    );
+    // Nothing crossed the bridge.
+    assert!(upstream.received_requests().await.unwrap_or_default().is_empty());
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn forwards_with_the_runtime_client_key_and_scrubs_inbound_credentials() {
+    let sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/v1/models"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(json!({ "data": [] }))
+                .insert_header("x-upstream", "yes"),
+        )
+        .mount(&upstream)
+        .await;
+
+    let verified = Arc::new(AtomicUsize::new(0));
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: upstream.uri(),
+        verify_bearer_token: Some(accept_all(Arc::clone(&verified))),
+        runtime_client_api_key: Some("runtime-key".to_string()),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/v1/models", bridge.base_url))
+        .header("authorization", "Bearer cma_local_secret")
+        .header("x-api-key", "leak")
+        .header("cookie", "sid=1")
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    // content-encoding never reaches the client (the header-filter contract
+    // is pinned in the local_bridge unit tests; the HTTP client also decodes
+    // upstream bodies before the bridge re-streams them).
+    assert!(response.headers().get("content-encoding").is_none());
+    assert_eq!(response.headers().get("x-upstream").unwrap(), "yes");
+    assert_eq!(verified.load(Ordering::SeqCst), 1);
+
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 1);
+    let forwarded = &requests[0];
+    // The inbound (validated) token is REPLACED by the runtime client key.
+    assert_eq!(
+        forwarded.headers.get("authorization").unwrap(),
+        "Bearer runtime-key"
+    );
+    assert!(forwarded.headers.get("x-api-key").is_none());
+    assert!(forwarded.headers.get("cookie").is_none());
+
+    // Ledger row: source local-bridge, operation models, outcome success.
+    let rows = read_ledger_rows(&sandbox);
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0]["source"], "local-bridge");
+    assert_eq!(rows[0]["operation"], "models");
+    assert_eq!(rows[0]["outcome"], "success");
+    assert_eq!(rows[0]["statusCode"], 200);
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn drops_the_inbound_authorization_when_no_runtime_key_is_configured() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/v1/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("data: ok\n\n"))
+        .mount(&upstream)
+        .await;
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: upstream.uri(),
+        verify_bearer_token: Some(accept_all(Arc::new(AtomicUsize::new(0)))),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/v1/responses", bridge.base_url))
+        .header("authorization", "Bearer cma_local_secret")
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    assert_eq!(response.text().await.expect("body"), "data: ok\n\n");
+
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 1);
+    // Never leak the caller's bridge token upstream.
+    assert!(requests[0].headers.get("authorization").is_none());
+    assert_eq!(
+        requests[0].body,
+        serde_json::to_vec(&json!({ "model": "gpt-5-codex" })).unwrap()
+    );
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn maps_unreachable_upstreams_to_502_and_records_the_failure_row() {
+    let sandbox = EnvSandbox::new();
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        // Nothing listens on port 9 (discard) — the fetch fails fast.
+        runtime_base_url: "http://127.0.0.1:9".to_string(),
+        require_auth: Some(false),
+        ..Default::default()
+    })
+    .await
+    .expect("bridge starts");
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/v1/models", bridge.base_url))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 502);
+    let body = body_json(response).await;
+    assert_eq!(body["error"]["code"], "local_bridge_upstream_error");
+    assert_eq!(
+        body["error"]["message"],
+        "Local bridge failed to reach the runtime proxy."
+    );
+    let rows = read_ledger_rows(&sandbox);
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0]["source"], "local-bridge");
+    assert_eq!(rows[0]["outcome"], "failure");
+    assert_eq!(rows[0]["statusCode"], 502);
+    assert_eq!(rows[0]["errorCode"], "local_bridge_upstream_error");
+    bridge.close().await;
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn accepts_bracketed_ipv6_loopback_runtime_base_urls() {
+    let _sandbox = EnvSandbox::new();
+    // `new URL("http://[::1]:1456").hostname` yields "[::1]" — the bracketed
+    // form must count as loopback (TS regression).
+    let bridge = start_local_bridge(LocalBridgeOptions {
+        runtime_base_url: "http://[::1]:1456".to_string(),
+        verify_bearer_token: Some(reject_all()),
+        ..Default::default()
+    })
+    .await
+    .expect("bracketed IPv6 loopback accepted");
+    bridge.close().await;
+}
diff --git a/crates/proxy/tests/pipeline_test.rs b/crates/proxy/tests/pipeline_test.rs
new file mode 100644
index 000000000..f5cfd9d85
--- /dev/null
+++ b/crates/proxy/tests/pipeline_test.rs
@@ -0,0 +1,887 @@
+//! Integration tests for the merged rotation pipeline (`cma_proxy::pipeline`).
+//!
+//! Ports the highest-value assertions from the TS suites (P0 per spec 14
+//! §11): the `index.test.ts` "OpenAIOAuthPlugin fetch handler" rotation
+//! behaviors and the `index-retry.test.ts` budget/burst scenarios, driven
+//! against a wiremock upstream through the real pipeline.
+//!
+//! Every test is `#[serial]`: the pipeline touches process-global state
+//! (resilience cooldowns, rate-limit backoff, rotation trackers) and the
+//! `EnvSandbox` mutates env vars.
+
+use std::sync::Arc;
+
+use cma_accounts::manager::AccountManager;
+use cma_accounts::manager_persistence::SharedAccountManager;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_proxy::pipeline::{PipelineConfig, ProxyPipeline, load_pipeline_config};
+use cma_request::failure_policy::FailoverMode;
+use cma_request::model_map::get_model_family;
+use cma_request::rate_limit_backoff::clear_rate_limit_backoff_state;
+use cma_request::resilience::reset_request_resilience_state_for_tests;
+use cma_runtime::rotation::proxy_state::{
+    RotationProxyState, RotationProxyStateInit, create_rotation_proxy_state,
+};
+use cma_runtime::rotation::server_types::{RequestContext, RequestMethod, SchedulingStrategy};
+use cma_rotation::routing_mutex::RoutingMutexMode;
+use cma_testkit::sandbox::EnvSandbox;
+use serde_json::{Value, json};
+use serial_test::serial;
+use wiremock::matchers::{body_string_contains, header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+fn reset_globals() {
+    reset_request_resilience_state_for_tests();
+    clear_rate_limit_backoff_state();
+    AccountManager::reset_volatile_runtime_state();
+}
+
+/// Accounts with valid (far-future) access tokens so no refresh happens.
+fn storage_with_accounts(count: usize) -> AccountStorageV3 {
+    let now = cma_core::utils::now_ms();
+    let accounts: Vec<Value> = (0..count)
+        .map(|index| {
+            json!({
+                "refreshToken": format!("refresh-{}", index + 1),
+                "accessToken": format!("access-{}", index + 1),
+                "expiresAt": now + 3_600_000,
+                "accountId": format!("acc-{}", index + 1),
+                "email": format!("user{}@example.com", index + 1),
+                "addedAt": now,
+                "lastUsed": now,
+            })
+        })
+        .collect();
+    serde_json::from_value(json!({
+        "version": 3,
+        "accounts": accounts,
+        "activeIndex": 0,
+        "activeIndexByFamily": {},
+    }))
+    .expect("test storage parses")
+}
+
+fn test_state(upstream_base_url: &str, account_count: usize) -> RotationProxyState {
+    let manager = AccountManager::new(None, Some(&storage_with_accounts(account_count)));
+    let shared = SharedAccountManager::new(manager);
+    create_rotation_proxy_state(RotationProxyStateInit {
+        active_account_manager: shared,
+        routing_mutex_mode: RoutingMutexMode::Legacy,
+        scheduling_strategy: SchedulingStrategy::Hybrid,
+        fetch_client: reqwest::Client::new(),
+        upstream_base_url: upstream_base_url.to_string(),
+        client_api_key: "test-client-key".to_string(),
+        now: Arc::new(cma_core::utils::now_ms),
+        token_refresh_skew_ms: 60_000,
+        network_error_cooldown_ms: 6_000,
+        server_error_cooldown_ms: 4_000,
+        token_invalidation_cooldown_ms: 300_000,
+        min_rotation_interval_ms: 0,
+        pid_offset_enabled: false,
+        fetch_timeout_ms: 5_000,
+        stream_stall_timeout_ms: 45_000,
+        max_runtime_account_attempts: 4,
+        max_request_body_bytes: 64 * 1024 * 1024,
+        quota_remaining_percent_threshold: 10.0,
+        session_affinity_store: None,
+        last_observed_affinity_generation: 0,
+        forced_account_index: None,
+    })
+}
+
+/// Deterministic pipeline config: aggressive mode, no same-account retries,
+/// no stream failover, no wait-and-retry. `empty_response_max_retries: 2`
+/// keeps the outbound budget formula from starving short-429 retries and
+/// fallback restarts (TS default configs always leave budget slack).
+fn test_config() -> PipelineConfig {
+    PipelineConfig {
+        rate_limit_toast_debounce_ms: 0,
+        retry_all_accounts_rate_limited: false,
+        retry_all_accounts_max_wait_ms: 0,
+        retry_all_accounts_max_retries: 0,
+        fallback_on_unsupported_codex_model: false,
+        fallback_to_gpt52_on_unsupported_gpt53: true,
+        unsupported_codex_fallback_chain: None,
+        toast_duration_ms: 0,
+        failover_mode: FailoverMode::Aggressive,
+        stream_failover_max: 0,
+        stream_failover_soft_timeout_ms: 10_000,
+        stream_failover_hard_timeout_ms: 45_000,
+        max_same_account_retries: 0,
+        empty_response_max_retries: 2,
+        empty_response_retry_delay_ms: 0,
+        response_continuation_enabled: false,
+    }
+}
+
+fn responses_ctx(model: &str) -> RequestContext {
+    let body = json!({ "model": model, "stream": false });
+    RequestContext {
+        body: serde_json::to_vec(&body).unwrap(),
+        headers: reqwest::header::HeaderMap::new(),
+        method: RequestMethod::Post,
+        upstream_path: "/codex/responses".to_string(),
+        model: Some(model.to_string()),
+        family: get_model_family(model),
+        stream: false,
+        session_key: None,
+    }
+}
+
+fn ok_response_body() -> Value {
+    json!({
+        "id": "resp_ok",
+        "output": [{ "type": "message", "content": [{ "type": "output_text", "text": "hi" }] }],
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+/// index.test.ts: "returns success response for successful fetch" + the
+/// spec-04 outbound header contract (authorization / chatgpt-account-id /
+/// originator: codex_cli_rs — load-bearing, gotcha 24).
+#[tokio::test]
+#[serial]
+async fn success_forwards_upstream_with_rotation_headers() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("authorization", "Bearer access-1"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .and(header("originator", "codex_cli_rs"))
+        .and(header("openai-beta", "responses=experimental"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), Some("trace-1".to_string()))
+        .await;
+
+    assert_eq!(response.status, 200);
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains("resp_ok"), "body forwarded: {text}");
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.successful_requests, 1);
+    assert_eq!(metrics.total_requests, 1);
+    // Budget formula: accounts(1) + sameAccountRetries(0) + emptyRetries(2)
+    // + streamFailover(0) = 3, clamped to 1..=6 (spec 13 §5.4).
+    assert_eq!(metrics.outbound_request_attempt_budget, Some(3));
+}
+
+/// index.test.ts fetch-handler rotation: a 429 on the first account rotates
+/// to the second and succeeds (rate-limit mark persists on account 1).
+#[tokio::test]
+#[serial]
+async fn rotates_to_next_account_on_429() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    // Long Retry-After (120 s) > short-retry threshold (5 s default) ⇒
+    // full rotation, MARK-BEFORE-SLEEP not applicable.
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "120")
+                .set_body_json(json!({"error": {"message": "rate limited"}})),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-2"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 2), test_config());
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 200);
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.rate_limited_responses, 1);
+    assert!(metrics.account_rotations >= 1);
+    assert_eq!(metrics.successful_requests, 1);
+    // Account 1 carries the persisted rate-limit window.
+    let state = pipeline.state().await;
+    let mut manager = state.active_account_manager.lock().await;
+    let family = get_model_family("gpt-5.3-codex");
+    assert!(
+        !manager.is_account_available_for_family(0, family, Some("gpt-5.3-codex")),
+        "account 1 must be rate-limited after the 429"
+    );
+}
+
+/// index.test.ts: short 429 retries the SAME account after marking it
+/// rate-limited (mark-before-sleep, spec 13 gotcha 5).
+#[tokio::test]
+#[serial]
+async fn short_429_retries_same_account() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "1")
+                .set_body_json(json!({"error": {"message": "rate limited"}})),
+        )
+        .up_to_n_times(1)
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 200);
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.rate_limited_responses, 1);
+    assert_eq!(metrics.successful_requests, 1);
+    // Two outbound attempts, same account.
+    assert_eq!(metrics.total_requests, 2);
+}
+
+/// spec 04 gotcha 10: an upstream 401 carrying a token-invalidation phrase
+/// STOPS rotation (401 `token_invalidated`, second account untouched) and
+/// applies the 300 s monotonic cooldown.
+#[tokio::test]
+#[serial]
+async fn token_invalidation_401_stops_rotation() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .respond_with(
+            ResponseTemplate::new(401)
+                .insert_header("x-request-id", "req-diag-1")
+                .set_body_json(json!({
+                    "error": { "message": "Your authentication token has been invalidated. Please try signing in again." }
+                })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-2"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(0)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 2), test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 401);
+    // TS builds the reply from responseHeadersForClient(upstream.headers):
+    // scrubbed upstream diagnostics (x-request-id) survive and content-type
+    // is EXACTLY "application/json" (no charset).
+    assert_eq!(
+        response
+            .headers
+            .get("x-request-id")
+            .and_then(|v| v.to_str().ok()),
+        Some("req-diag-1"),
+        "upstream diagnostics forwarded on the token-invalidation reply"
+    );
+    assert_eq!(
+        response
+            .headers
+            .get("content-type")
+            .and_then(|v| v.to_str().ok()),
+        Some("application/json")
+    );
+    let body: Value =
+        serde_json::from_str(&response.collect_text().await.unwrap()).unwrap();
+    assert_eq!(body["error"]["code"], "token_invalidated");
+    // 300 s cooldown applied to account 1 (monotonic).
+    let state = pipeline.state().await;
+    let manager = state.active_account_manager.lock().await;
+    let cooling_until = manager
+        .get_account_by_index(0)
+        .and_then(|account| account.meta.cooling_down_until)
+        .unwrap_or(0);
+    assert!(
+        cooling_until >= cma_core::utils::now_ms() + 250_000,
+        "invalidation cooldown must be ~300s, got {cooling_until}"
+    );
+}
+
+/// spec 04 §14 + spec 13 §5.5.5: full exhaustion emits the stable
+/// `codex_runtime_rotation_pool_exhausted` body and arms the pool cooldown
+/// (the NEXT request fast-fails 429 with the frozen cooldown message).
+#[tokio::test]
+#[serial]
+async fn pool_exhaustion_emits_contract_body_and_arms_cooldown() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "600")
+                .set_body_json(json!({"error": {"message": "rate limited"}})),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 429, "rate-limit exhaustion maps to 429");
+    let body: Value =
+        serde_json::from_str(&response.collect_text().await.unwrap()).unwrap();
+    assert_eq!(
+        body["error"]["code"],
+        "codex_runtime_rotation_pool_exhausted"
+    );
+    assert_eq!(body["error"]["reason"], "rate-limit");
+    assert!(body["error"]["retry_after_ms"].as_i64().unwrap() > 0);
+    assert_eq!(
+        body["error"]["message"],
+        "All managed Codex accounts are temporarily unavailable for this runtime request."
+    );
+
+    // Second request: pool-exhaustion fast-fail (spec 13 §5.3).
+    let mut second = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+    assert_eq!(second.status, 429);
+    let text = second.collect_text().await.unwrap();
+    assert!(
+        text.contains("The account pool is cooling down after recent rate-limit exhaustion."),
+        "fast-fail message frozen: {text}"
+    );
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.pool_exhaustion_fast_fails, 1);
+}
+
+/// index.test.ts: "forces Spark fallback even when strict policy disables
+/// generic unsupported fallback" + "restarts account traversal after
+/// fallback model switch" (spec 13 gotchas 9–11).
+#[tokio::test]
+#[serial]
+async fn spark_unsupported_falls_back_and_restarts_traversal() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(body_string_contains("gpt-5.3-codex-spark"))
+        .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "The 'gpt-5.3-codex-spark' model is not supported when using Codex with a ChatGPT account.",
+            }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(body_string_contains("\"gpt-5.3-codex\""))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    // Strict policy: fallback_on_unsupported_codex_model = false — spark is
+    // force-fallback anyway.
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex-spark"), None)
+        .await;
+
+    assert_eq!(response.status, 200);
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.successful_requests, 1);
+    assert_eq!(metrics.total_requests, 2);
+}
+
+/// index-retry.test.ts: "stops after the bounded outbound request budget" —
+/// in the merged pipeline the spec-04 transient budget (min(count, 4)) caps
+/// a 5xx storm first; the terminal body reports reason "budget".
+#[tokio::test]
+#[serial]
+async fn server_error_storm_stops_at_transient_budget() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(500)
+                .set_body_json(json!({"error": {"message": "server exploded"}})),
+        )
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 8), test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 503);
+    let body: Value =
+        serde_json::from_str(&response.collect_text().await.unwrap()).unwrap();
+    assert_eq!(
+        body["error"]["code"],
+        "codex_runtime_rotation_pool_exhausted"
+    );
+    assert_eq!(body["error"]["reason"], "budget");
+    // Transient budget = min(accountCount=8, 4) ⇒ exactly 4 upstream hits.
+    let received = server.received_requests().await.unwrap();
+    assert_eq!(received.len(), 4, "transient budget caps upstream attempts");
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.server_errors, 4);
+}
+
+/// Pinned account unavailable ⇒ hard 503 `codex_pinned_account_unavailable`
+/// with a structured skip reason; NEVER falls through to rotation (#474).
+#[tokio::test]
+#[serial]
+async fn pinned_unavailable_hard_fails_without_rotation() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(0)
+        .mount(&server)
+        .await;
+
+    let mut state = test_state(&server.uri(), 2);
+    state.forced_account_index = Some(1);
+    // Disable the pinned account so it fails availability.
+    {
+        let mut manager = state.active_account_manager.manager().try_lock().unwrap();
+        manager.set_account_enabled(1, false);
+    }
+    let pipeline = ProxyPipeline::new(state, test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 503);
+    let body: Value =
+        serde_json::from_str(&response.collect_text().await.unwrap()).unwrap();
+    assert_eq!(body["error"]["code"], "codex_pinned_account_unavailable");
+}
+
+/// load_pipeline_config honors the env-driven failover settings, incl. the
+/// `capStreamFailoverMax` clamp to 1 (spec 13 gotcha 1).
+#[tokio::test]
+#[serial]
+async fn stream_failover_max_is_clamped_to_one() {
+    let mut sandbox = EnvSandbox::new();
+    sandbox.set_var("CODEX_AUTH_FAILOVER_MODE", "balanced");
+    sandbox.set_var("CODEX_AUTH_STREAM_FAILOVER_MAX", "5");
+    let config = load_pipeline_config(&cma_core::schemas::plugin_config::PluginConfig::default());
+    assert_eq!(
+        config.stream_failover_max, 1,
+        "mode default 2 and env 5 both clamp to 1"
+    );
+    assert_eq!(config.max_same_account_retries, 1, "balanced ⇒ 1");
+    sandbox.set_var("CODEX_AUTH_FAILOVER_MODE", "conservative");
+    let config = load_pipeline_config(&cma_core::schemas::plugin_config::PluginConfig::default());
+    assert_eq!(config.max_same_account_retries, 2, "conservative ⇒ 2");
+    sandbox.set_var("CODEX_AUTH_FAILOVER_MODE", "aggressive");
+    let config = load_pipeline_config(&cma_core::schemas::plugin_config::PluginConfig::default());
+    assert_eq!(config.max_same_account_retries, 0, "aggressive ⇒ 0");
+}
+
+// ---------------------------------------------------------------------------
+// Parity-fix pins (TS-vs-Rust divergence findings)
+// ---------------------------------------------------------------------------
+
+fn ledger_rows(sandbox: &EnvSandbox) -> Vec<Value> {
+    let path = sandbox
+        .codex_multi_auth_dir()
+        .join("usage")
+        .join("usage-ledger.jsonl");
+    let Ok(contents) = std::fs::read_to_string(path) else {
+        return Vec::new();
+    };
+    contents
+        .lines()
+        .filter(|line| !line.trim().is_empty())
+        .map(|line| serde_json::from_str(line).expect("ledger row parses"))
+        .collect()
+}
+
+/// Finding: the error ladder keys off the REMAPPED status. A structured 404
+/// usage-limit body (which upstream really uses for quota exhaustion on this
+/// endpoint) is remapped to 429 by handle_error_response and MUST take the
+/// rate-limit path -- mark the account rate-limited and rotate -- not the
+/// generic return (which would 429 the client while leaving the exhausted
+/// account eligible for immediate re-selection).
+#[tokio::test]
+#[serial]
+async fn mapped_404_usage_limit_marks_rate_limited_and_rotates() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-1"))
+        .respond_with(ResponseTemplate::new(404).set_body_json(json!({
+            "error": { "code": "usage_limit_reached", "message": "limit reached" }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-2"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 2), test_config());
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 200, "rotated to the healthy account");
+    let metrics = pipeline.metrics_snapshot();
+    assert_eq!(metrics.rate_limited_responses, 1, "took the 429 ladder branch");
+    assert!(metrics.account_rotations >= 1);
+    let state = pipeline.state().await;
+    let mut manager = state.active_account_manager.lock().await;
+    let family = get_model_family("gpt-5.3-codex");
+    assert!(
+        !manager.is_account_available_for_family(0, family, Some("gpt-5.3-codex")),
+        "the exhausted account must carry a rate-limit mark"
+    );
+}
+
+/// Finding: a 404 entitlement body (remapped to 403) must cache the
+/// plan-entitlement block exactly like a raw 403 -- the NEXT request for the
+/// same account fast-fails from the cache instead of re-hitting upstream.
+#[tokio::test]
+#[serial]
+async fn mapped_404_entitlement_caches_the_plan_block() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(404).set_body_json(json!({
+            "error": { "code": "usage_not_included", "message": "Usage not included in your plan" }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let first = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+    assert_eq!(first.status, 403, "remapped entitlement response");
+
+    // Second request: served from the entitlement cache (upstream expect(1)
+    // is verified on MockServer drop -- a second upstream hit panics).
+    let second = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+    assert_ne!(second.status, 200);
+    let requests = server.received_requests().await.expect("recorded");
+    assert_eq!(
+        requests.len(),
+        1,
+        "cached plan-entitlement block prevents the second upstream call"
+    );
+}
+
+/// Finding: a STREAMING upstream success must NOT eagerly record the ledger
+/// row -- the record is deferred to the client-forward stage (`forwarded ?
+/// success : failure/stream_forward_failed`), which also owns the
+/// network-failure account cleanup on a mid-stream stall.
+#[tokio::test]
+#[serial]
+async fn streaming_success_defers_the_ledger_row_to_the_forward_stage() {
+    let sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let mut ctx = responses_ctx("gpt-5.3-codex");
+    ctx.stream = true;
+    ctx.body = serde_json::to_vec(&json!({ "model": "gpt-5.3-codex", "stream": true })).unwrap();
+    ctx.session_key = Some("session-defer".to_string());
+
+    let outcome = pipeline.handle_responses_for_server(ctx, None).await;
+    assert_eq!(outcome.response.status, 200);
+    let deferred = outcome
+        .deferred
+        .expect("streaming success hands the record to the forward stage");
+    assert_eq!(deferred.account_index, 0);
+    assert_eq!(deferred.model.as_deref(), Some("gpt-5.3-codex"));
+    assert_eq!(deferred.session_key.as_deref(), Some("session-defer"));
+    assert!(
+        ledger_rows(&sandbox).is_empty(),
+        "no ledger row before the client forward resolves"
+    );
+
+    // Forward stage failure: the row becomes failure/stream_forward_failed
+    // (mirrors server.rs StreamUsage on_failure).
+    deferred
+        .recorder
+        .record(cma_quota::runtime_policy::RuntimeUsageRecordInput {
+            outcome: Some(cma_usage::types::UsageLedgerOutcome::Failure),
+            status_code: Some(200),
+            error_code: Some("stream_forward_failed".to_string()),
+            ..Default::default()
+        })
+        .await;
+    let rows = ledger_rows(&sandbox);
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0]["outcome"], "failure");
+    assert_eq!(rows[0]["errorCode"], "stream_forward_failed");
+
+    // The plain handle_responses entry point (in-process callers with no
+    // separate forward stage) records the deferred success itself.
+    let mut ctx = responses_ctx("gpt-5.3-codex");
+    ctx.stream = true;
+    ctx.body = serde_json::to_vec(&json!({ "model": "gpt-5.3-codex", "stream": true })).unwrap();
+    let response = pipeline.handle_responses(ctx, None).await;
+    assert_eq!(response.status, 200);
+    let rows = ledger_rows(&sandbox);
+    assert_eq!(rows.len(), 2);
+    assert_eq!(rows[1]["outcome"], "success");
+}
+
+/// Finding: a handled context-overflow returns TS's DEFAULT ledger row
+/// (failure / plugin_host_request_failed / statusCode null) -- TS never
+/// updates usageCompletion on that early return -- not a success row.
+#[tokio::test]
+#[serial]
+async fn context_overflow_handled_records_the_ts_default_failure_row() {
+    let sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+            "error": { "message": "This request exceeds the maximum context length (context_length_exceeded)." }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), test_config());
+    let mut response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+
+    assert_eq!(response.status, 200, "synthetic overflow SSE response");
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains("Context is too long"), "overflow notice: {text}");
+    let rows = ledger_rows(&sandbox);
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0]["outcome"], "failure", "TS default completion");
+    assert_eq!(rows[0]["errorCode"], "plugin_host_request_failed");
+    assert!(
+        rows[0].get("statusCode").is_none_or(Value::is_null),
+        "statusCode stays null like TS: {:?}",
+        rows[0]
+    );
+}
+
+/// Finding: the 429 short-retry toast is gated by the per-account
+/// shouldShowAccountToast debounce and records markToastShown -- a burst of
+/// 429s emits at most ONE rate-limit toast per debounce window per account.
+#[tokio::test]
+#[serial]
+async fn rate_limit_toasts_debounce_per_account() {
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "1")
+                .set_body_json(json!({"error": {"message": "rate limited"}})),
+        )
+        .up_to_n_times(2)
+        .expect(2)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response_body()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let mut config = test_config();
+    config.rate_limit_toast_debounce_ms = 30_000;
+    let pipeline = ProxyPipeline::new(test_state(&server.uri(), 1), config);
+    cma_runtime::toast::start_toast_capture_for_tests();
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+    let toasts = cma_runtime::toast::take_captured_toasts_for_tests();
+
+    assert_eq!(response.status, 200);
+    assert_eq!(pipeline.metrics_snapshot().rate_limited_responses, 2);
+    let rate_limit_toasts: Vec<&(String, String)> = toasts
+        .iter()
+        .filter(|(_, message)| message.contains("Rate limited"))
+        .collect();
+    assert_eq!(
+        rate_limit_toasts.len(),
+        1,
+        "one toast per account per debounce window, got {toasts:?}"
+    );
+    // markToastShown was recorded, so the debounce window is armed.
+    let state = pipeline.state().await;
+    let manager = state.active_account_manager.lock().await;
+    assert!(
+        !manager.should_show_account_toast(0, Some(30_000)),
+        "mark_toast_shown must be recorded on the 429 toast path"
+    );
+}
+
+/// Finding: the 429 backoff stable key reads the request-resolved accountId
+/// (written back onto the live account object in TS). An account stored
+/// WITHOUT accountId whose id resolves from the access token this request
+/// must key its backoff state under the resolved id, not slot/email.
+#[tokio::test]
+#[serial]
+async fn backoff_stable_key_uses_the_request_resolved_account_id() {
+    use base64::Engine as _;
+    let _sandbox = EnvSandbox::new();
+    reset_globals();
+
+    let b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD;
+    let jwt = format!(
+        "{}.{}.sig",
+        b64.encode(json!({ "alg": "none", "typ": "JWT" }).to_string()),
+        b64.encode(
+            json!({
+                "https://api.openai.com/auth": { "chatgpt_account_id": "acc-jwt-1" }
+            })
+            .to_string()
+        ),
+    );
+    let now = cma_core::utils::now_ms();
+    let storage: AccountStorageV3 = serde_json::from_value(json!({
+        "version": 3,
+        "accounts": [{
+            "refreshToken": "refresh-jwt",
+            "accessToken": jwt,
+            "expiresAt": now + 3_600_000,
+            "addedAt": now,
+            "lastUsed": now,
+        }],
+        "activeIndex": 0,
+        "activeIndexByFamily": {},
+    }))
+    .expect("storage parses");
+
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc-jwt-1"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "120")
+                .set_body_json(json!({"error": {"message": "rate limited"}})),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let manager = AccountManager::new(None, Some(&storage));
+    let shared = SharedAccountManager::new(manager);
+    let state = create_rotation_proxy_state(RotationProxyStateInit {
+        active_account_manager: shared,
+        routing_mutex_mode: RoutingMutexMode::Legacy,
+        scheduling_strategy: SchedulingStrategy::Hybrid,
+        fetch_client: reqwest::Client::new(),
+        upstream_base_url: server.uri(),
+        client_api_key: "test-client-key".to_string(),
+        now: Arc::new(cma_core::utils::now_ms),
+        token_refresh_skew_ms: 60_000,
+        network_error_cooldown_ms: 6_000,
+        server_error_cooldown_ms: 4_000,
+        token_invalidation_cooldown_ms: 300_000,
+        min_rotation_interval_ms: 0,
+        pid_offset_enabled: false,
+        fetch_timeout_ms: 5_000,
+        stream_stall_timeout_ms: 45_000,
+        max_runtime_account_attempts: 4,
+        max_request_body_bytes: 64 * 1024 * 1024,
+        quota_remaining_percent_threshold: 10.0,
+        session_affinity_store: None,
+        last_observed_affinity_generation: 0,
+        forced_account_index: None,
+    });
+    let pipeline = ProxyPipeline::new(state, test_config());
+    let response = pipeline
+        .handle_responses(responses_ctx("gpt-5.3-codex"), None)
+        .await;
+    assert_eq!(response.status, 429, "single exhausted account");
+
+    // The pipeline recorded the backoff under the RESOLVED id: probing the
+    // same key immediately lands in the dedup window (entry exists). Under
+    // the pre-fix slot/email key this probe would create a FRESH entry
+    // (is_duplicate == false, attempt 1).
+    let family = get_model_family("gpt-5.3-codex");
+    let quota_key = format!("{}:gpt-5.3-codex", family.as_str());
+    let probe = cma_request::rate_limit_backoff::get_rate_limit_backoff(
+        0,
+        &quota_key,
+        None,
+        Some("acc-jwt-1"),
+    );
+    assert!(
+        probe.is_duplicate,
+        "backoff state must live under the resolved accountId key: {probe:?}"
+    );
+}
diff --git a/crates/proxy/tests/server_test.rs b/crates/proxy/tests/server_test.rs
new file mode 100644
index 000000000..cf009e5bb
--- /dev/null
+++ b/crates/proxy/tests/server_test.rs
@@ -0,0 +1,623 @@
+//! P0 port of `test/runtime-rotation-proxy.test.ts` (HTTP-surface half) +
+//! `runtime-rotation-proxy-safe-equal.test.ts` behavior anchors.
+//!
+//! Every test pins the filesystem/env via `EnvSandbox` (`#[serial(env)]`) —
+//! the proxy loads config, policy state, and storage metadata from the
+//! sandboxed `~/.codex/multi-auth` tree, and its debounced saves write there.
+
+use cma_accounts::manager::AccountManager;
+use cma_accounts::manager_persistence::SharedAccountManager;
+use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+use cma_core::utils::now_ms;
+use cma_proxy::server::start_runtime_rotation_proxy;
+use cma_runtime::rotation::server_types::RuntimeRotationProxyOptions;
+use cma_testkit::sandbox::EnvSandbox;
+use serde_json::{Value, json};
+use serial_test::serial;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+const CLIENT_KEY: &str = "runtime-secret";
+
+fn account_meta(index: usize, now: i64) -> AccountMetadataV3 {
+    let mut meta =
+        AccountMetadataV3::new(format!("refresh-{}", index + 1), now - 60_000, now - 60_000);
+    meta.email = Some(format!("account-{}@example.com", index + 1));
+    meta.account_id = Some(format!("acc_{}", index + 1));
+    meta.access_token = Some(format!("access-{}", index + 1));
+    meta.expires_at = Some(now + 3_600_000);
+    meta.enabled = Some(true);
+    meta
+}
+
+fn storage_with(count: usize) -> AccountStorageV3 {
+    let now = now_ms();
+    let mut storage = AccountStorageV3::empty();
+    storage.accounts = (0..count).map(|index| account_meta(index, now)).collect();
+    storage
+}
+
+fn shared_manager(count: usize) -> SharedAccountManager {
+    // The pipeline consults process-wide singletons (health/token trackers,
+    // circuit breakers, pool-exhaustion/server-burst fast-fail cooldowns,
+    // rate-limit backoff). Vitest gave each TS test file a fresh module
+    // registry; these resets are the Rust equivalent so one test's pool
+    // exhaustion cannot fast-fail every later test with a synthetic 429.
+    AccountManager::reset_volatile_runtime_state();
+    cma_request::resilience::reset_request_resilience_state_for_tests();
+    cma_request::rate_limit_backoff::clear_rate_limit_backoff_state();
+    SharedAccountManager::new(AccountManager::new(None, Some(&storage_with(count))))
+}
+
+fn proxy_options(
+    manager: SharedAccountManager,
+    upstream_base_url: &str,
+) -> RuntimeRotationProxyOptions {
+    RuntimeRotationProxyOptions {
+        account_manager: Some(manager),
+        client_api_key: CLIENT_KEY.to_string(),
+        upstream_base_url: Some(upstream_base_url.to_string()),
+        ..Default::default()
+    }
+}
+
+async fn body_json(response: reqwest::Response) -> Value {
+    serde_json::from_str(&response.text().await.expect("body text")).expect("json body")
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn requires_a_client_api_key_at_startup() {
+    let _sandbox = EnvSandbox::new();
+    let error = start_runtime_rotation_proxy(RuntimeRotationProxyOptions {
+        account_manager: Some(shared_manager(1)),
+        client_api_key: "   ".to_string(),
+        ..Default::default()
+    })
+    .await
+    .expect_err("startup must fail");
+    assert_eq!(error.name(), "CodexValidationError");
+    assert_eq!(error.field(), Some("clientApiKey"));
+    assert_eq!(
+        error.to_string(),
+        "Runtime rotation proxy requires a clientApiKey."
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn refuses_to_bind_a_non_loopback_host_unconditionally() {
+    let _sandbox = EnvSandbox::new();
+    let error = start_runtime_rotation_proxy(RuntimeRotationProxyOptions {
+        account_manager: Some(shared_manager(1)),
+        client_api_key: CLIENT_KEY.to_string(),
+        host: Some("0.0.0.0".to_string()),
+        ..Default::default()
+    })
+    .await
+    .expect_err("startup must fail");
+    assert_eq!(error.name(), "CodexValidationError");
+    assert_eq!(error.field(), Some("host"));
+    assert_eq!(
+        error.to_string(),
+        "Runtime rotation proxy refuses to bind non-loopback host \"0.0.0.0\". It forwards managed OAuth tokens and is loopback-only."
+    );
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn rejects_unauthenticated_clients_with_401_never_404() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let client = reqwest::Client::new();
+
+    // Wrong bearer on a valid path -> 401.
+    let response = client
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", "Bearer wrong")
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 401);
+    let body = body_json(response).await;
+    assert_eq!(
+        body["error"]["code"],
+        "runtime_rotation_proxy_unauthorized"
+    );
+    assert_eq!(
+        body["error"]["message"],
+        "Runtime rotation proxy rejected an unauthenticated local request."
+    );
+
+    // Unknown path withOUT credentials -> STILL 401 (never a
+    // path-confirming 404 — endpoint enumeration defense).
+    let response = client
+        .post(format!("{}/definitely/not/a/route", proxy.base_url))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 401);
+
+    assert!(upstream.received_requests().await.unwrap_or_default().is_empty());
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_404_for_unsupported_paths_and_methods_when_authorized() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let client = reqwest::Client::new();
+
+    // Arbitrary local path that merely ends with "responses".
+    let response = client
+        .post(format!("{}/foo/responses", proxy.base_url))
+        .header("x-api-key", CLIENT_KEY)
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 404);
+    let body = body_json(response).await;
+    assert_eq!(body["error"]["code"], "runtime_rotation_proxy_not_found");
+    assert_eq!(
+        body["error"]["message"],
+        "Runtime rotation proxy only accepts Responses API, model discovery, and Codex thread goal requests."
+    );
+
+    // Wrong method on a supported path.
+    let response = client
+        .get(format!("{}/responses", proxy.base_url))
+        .header("x-api-key", CLIENT_KEY)
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 404);
+
+    assert!(upstream.received_requests().await.unwrap_or_default().is_empty());
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn rejects_oversized_request_bodies_before_selecting_an_account() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let mut options = proxy_options(shared_manager(1), &upstream.uri());
+    options.max_request_body_bytes = Some(64);
+    let proxy = start_runtime_rotation_proxy(options)
+        .await
+        .expect("proxy starts");
+
+    let big = "x".repeat(256);
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .body(format!("{{\"model\":\"gpt-5-codex\",\"pad\":\"{big}\"}}"))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 413);
+    let body = body_json(response).await;
+    assert_eq!(
+        body["error"]["code"],
+        "runtime_rotation_proxy_payload_too_large"
+    );
+    assert_eq!(
+        body["error"]["message"],
+        "Runtime rotation proxy request body is too large."
+    );
+    assert!(upstream.received_requests().await.unwrap_or_default().is_empty());
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn forwards_responses_replacing_caller_auth_and_scrubbing_credentials() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_string("data: ok\n\n")
+                .insert_header("content-type", "text/event-stream")
+                .insert_header("x-request-id", "req_1"),
+        )
+        .mount(&upstream)
+        .await;
+
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .header("cookie", "sid=1")
+        .header("x-custom", "kept")
+        .json(&json!({ "model": "gpt-5-codex", "stream": true }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    // Stale decoded content-encoding never reaches the client (the filter
+    // itself is pinned by the stream_failover_runtime unit tests).
+    assert!(response.headers().get("content-encoding").is_none());
+    assert_eq!(
+        response.headers().get("x-request-id").unwrap(),
+        "req_1"
+    );
+    assert_eq!(response.text().await.expect("body"), "data: ok\n\n");
+
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 1);
+    let forwarded = &requests[0];
+    assert_eq!(
+        forwarded.headers.get("authorization").unwrap(),
+        "Bearer access-1"
+    );
+    assert_eq!(forwarded.headers.get("chatgpt-account-id").unwrap(), "acc_1");
+    assert_eq!(
+        forwarded.headers.get("openai-beta").unwrap(),
+        "responses=experimental"
+    );
+    assert_eq!(forwarded.headers.get("originator").unwrap(), "codex_cli_rs");
+    assert!(forwarded.headers.get("cookie").is_none());
+    assert!(forwarded.headers.get("x-api-key").is_none());
+    assert_eq!(forwarded.headers.get("x-custom").unwrap(), "kept");
+    assert_eq!(
+        forwarded.body,
+        serde_json::to_vec(&json!({ "model": "gpt-5-codex", "stream": true })).unwrap()
+    );
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn forwards_model_discovery_through_managed_account_auth() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/models"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "data": [] })))
+        .mount(&upstream)
+        .await;
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .get(format!("{}/v1/models", proxy.base_url))
+        .header("x-api-key", CLIENT_KEY)
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 1);
+    assert_eq!(
+        requests[0].headers.get("authorization").unwrap(),
+        "Bearer access-1"
+    );
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn retries_a_429_on_another_account_before_returning_bytes() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    // Union deviation from the TS proxy test (which used `retry-after: 1`):
+    // the merged pipeline applies the spec-13 short-retry policy, so a
+    // retry-after at or below the 5 s short-retry threshold is retried on
+    // the SAME account (mark-before-sleep, up to 3 attempts) before
+    // rotating. A retry-after above the threshold pins the original
+    // TS-proxy behavior this test exists for: rotate to the next account
+    // before returning bytes, with exactly one attempt per account.
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc_1"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .set_body_json(json!({ "error": { "message": "quota" } }))
+                .insert_header("retry-after", "60"),
+        )
+        .mount(&upstream)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc_2"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("served-by-2"))
+        .mount(&upstream)
+        .await;
+
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(2), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    assert_eq!(response.text().await.expect("body"), "served-by-2");
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 2);
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_401_and_does_not_rotate_on_explicit_token_invalidation() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(401).set_body_json(json!({
+            "error": { "message": "Token has been invalidated." }
+        })))
+        .mount(&upstream)
+        .await;
+
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(2), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 401);
+    let body = body_json(response).await;
+    // Both invalidation vectors emit the same machine-readable shape.
+    assert_eq!(body["error"]["code"], "token_invalidated");
+    assert_eq!(body["error"]["message"], "Token has been invalidated.");
+    // No rotation: exactly one upstream attempt despite a second account.
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 1);
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn rotates_to_the_next_account_on_a_generic_401() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc_1"))
+        .respond_with(
+            ResponseTemplate::new(401)
+                .set_body_json(json!({ "error": { "message": "unauthorized" } })),
+        )
+        .mount(&upstream)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .and(header("chatgpt-account-id", "acc_2"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("served-by-2"))
+        .mount(&upstream)
+        .await;
+
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(2), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    assert_eq!(response.text().await.expect("body"), "served-by-2");
+    assert_eq!(upstream.received_requests().await.expect("recorded").len(), 2);
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn returns_a_structured_pool_exhaustion_response() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .set_body_json(json!({ "error": { "message": "quota" } }))
+                .insert_header("retry-after", "30"),
+        )
+        .mount(&upstream)
+        .await;
+
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 429);
+    let body = body_json(response).await;
+    assert_eq!(
+        body["error"]["code"],
+        "codex_runtime_rotation_pool_exhausted"
+    );
+    assert_eq!(
+        body["error"]["message"],
+        "All managed Codex accounts are temporarily unavailable for this runtime request."
+    );
+    assert_eq!(body["error"]["reason"], "rate-limit");
+    assert!(body["error"]["retry_after_ms"].as_i64().unwrap_or(0) > 0);
+    assert_eq!(
+        body["error"]["hint"],
+        "Run `codex-multi-auth rotation status` to inspect account state."
+    );
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn routes_every_request_to_the_ephemeral_forced_account(
+) {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("ok"))
+        .mount(&upstream)
+        .await;
+
+    let mut options = proxy_options(shared_manager(2), &upstream.uri());
+    options.forced_account_index = Some(1);
+    let proxy = start_runtime_rotation_proxy(options)
+        .await
+        .expect("proxy starts");
+    let client = reqwest::Client::new();
+    for _ in 0..2 {
+        let response = client
+            .post(format!("{}/responses", proxy.base_url))
+            .header("authorization", format!("Bearer {CLIENT_KEY}"))
+            .json(&json!({ "model": "gpt-5-codex" }))
+            .send()
+            .await
+            .expect("request");
+        assert_eq!(response.status().as_u16(), 200);
+    }
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(requests.len(), 2);
+    for request in &requests {
+        assert_eq!(request.headers.get("chatgpt-account-id").unwrap(), "acc_2");
+    }
+    proxy.close().await.expect("close");
+}
+
+/// A stray/inherited `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX` must NOT pin the
+/// proxy when the launcher explicitly resolved "no pin" (a run without
+/// `--account`): TS deletes the var from process.env in that case, so a
+/// nested wrapper run inside a forced session (or a leftover export) returns
+/// to normal rotation. Callers that never resolved the pin keep the env
+/// fallback.
+#[tokio::test]
+#[serial(env)]
+async fn suppresses_a_stray_env_pin_when_the_launcher_resolved_no_pin() {
+    let mut sandbox = EnvSandbox::new();
+    sandbox.set_var("CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX", "1");
+    let upstream = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("ok"))
+        .mount(&upstream)
+        .await;
+    let client = reqwest::Client::new();
+
+    // Launcher resolved "no pin": the ambient var is ignored — the request
+    // is served by normal selection (account 1), not the stray pin.
+    let mut options = proxy_options(shared_manager(2), &upstream.uri());
+    options.forced_account_index = None;
+    options.suppress_env_forced_account_index = true;
+    let proxy = start_runtime_rotation_proxy(options)
+        .await
+        .expect("proxy starts");
+    let response = client
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(
+        requests.last().unwrap().headers.get("chatgpt-account-id").unwrap(),
+        "acc_1",
+        "ambient pin ignored when the launcher resolved no pin"
+    );
+    proxy.close().await.expect("close");
+
+    // Without suppression (caller never resolved the pin), the env fallback
+    // still pins — preserving the pre-existing contract.
+    let mut options = proxy_options(shared_manager(2), &upstream.uri());
+    options.forced_account_index = None;
+    options.suppress_env_forced_account_index = false;
+    let proxy = start_runtime_rotation_proxy(options)
+        .await
+        .expect("proxy starts");
+    let response = client
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 200);
+    let requests = upstream.received_requests().await.expect("recorded");
+    assert_eq!(
+        requests.last().unwrap().headers.get("chatgpt-account-id").unwrap(),
+        "acc_2",
+        "env fallback preserved when not suppressed"
+    );
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn fails_hard_with_503_when_the_forced_account_is_missing() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let mut options = proxy_options(shared_manager(2), &upstream.uri());
+    options.forced_account_index = Some(5);
+    let proxy = start_runtime_rotation_proxy(options)
+        .await
+        .expect("proxy starts");
+    let response = reqwest::Client::new()
+        .post(format!("{}/responses", proxy.base_url))
+        .header("authorization", format!("Bearer {CLIENT_KEY}"))
+        .json(&json!({ "model": "gpt-5-codex" }))
+        .send()
+        .await
+        .expect("request");
+    assert_eq!(response.status().as_u16(), 503);
+    let body = body_json(response).await;
+    assert_eq!(body["error"]["code"], "codex_pinned_account_unavailable");
+    assert_eq!(body["error"]["pinnedAccountIndex"], 5);
+    // Structured reason (#486): the pinned index is out of the pool range.
+    assert_eq!(body["error"]["reason"], "missing");
+    assert_eq!(body["error"]["account_skip_reasons"]["5"], "missing");
+    assert!(
+        body["error"]["message"]
+            .as_str()
+            .unwrap()
+            .contains("Pinned account 6 is currently unavailable (missing)")
+    );
+    // Fail-hard: no upstream call was ever attempted.
+    assert!(upstream.received_requests().await.unwrap_or_default().is_empty());
+    proxy.close().await.expect("close");
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn get_status_masks_email_material_in_last_error() {
+    let _sandbox = EnvSandbox::new();
+    let upstream = MockServer::start().await;
+    let proxy = start_runtime_rotation_proxy(proxy_options(shared_manager(1), &upstream.uri()))
+        .await
+        .expect("proxy starts");
+    // Baseline status shape.
+    let status = proxy.get_status().await;
+    assert_eq!(status.total_requests, 0);
+    assert_eq!(status.last_error, None);
+    proxy.close().await.expect("close");
+}
diff --git a/crates/quota/Cargo.toml b/crates/quota/Cargo.toml
new file mode 100644
index 000000000..f2325f44d
--- /dev/null
+++ b/crates/quota/Cargo.toml
@@ -0,0 +1,35 @@
+[package]
+name = "cma-quota"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-storage = { path = "../storage" }
+cma-accounts = { path = "../accounts" }
+cma-request = { path = "../request" }
+cma-usage = { path = "../usage" }
+cma-rotation = { path = "../rotation" }
+serde.workspace = true
+serde_json.workspace = true
+reqwest.workspace = true
+notify.workspace = true
+tokio.workspace = true
+chrono.workspace = true
+sha2.workspace = true
+futures.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+wiremock.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/quota/src/audit.rs b/crates/quota/src/audit.rs
new file mode 100644
index 000000000..c0d38a31a
--- /dev/null
+++ b/crates/quota/src/audit.rs
@@ -0,0 +1,614 @@
+//! Port of `lib/audit.ts` — append-only JSONL audit log with size-based
+//! rotation (10 MiB / 5 files).
+//!
+//! Currently **dormant** in the TS repo: `auditLog`/`configureAudit` are not
+//! called anywhere and the module is not re-exported by `lib/index.ts`. It is
+//! ported for API parity; do not wire it into anything new.
+//!
+//! The TS module captures the default `logDir` at module load; here the
+//! default config is resolved lazily on FIRST access and then frozen (spec 05
+//! gotcha 24 explicitly allows either), defaulting to
+//! `<multi-auth-dir>/logs` (`getCodexLogDir()`).
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{get_correlation_id, mask_email};
+use cma_core::runtime_paths::get_codex_log_dir;
+use serde_json::{Map, Value};
+
+/// TS `enum AuditAction` — exact string values.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum AuditAction {
+    AccountAdd,
+    AccountRemove,
+    AccountSwitch,
+    AccountRefresh,
+    AccountExport,
+    AccountImport,
+    AuthLogin,
+    AuthLogout,
+    AuthRefresh,
+    AuthFailure,
+    ConfigLoad,
+    ConfigChange,
+    RequestStart,
+    RequestSuccess,
+    RequestFailure,
+    CircuitOpen,
+    CircuitClose,
+}
+
+impl AuditAction {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            AuditAction::AccountAdd => "account.add",
+            AuditAction::AccountRemove => "account.remove",
+            AuditAction::AccountSwitch => "account.switch",
+            AuditAction::AccountRefresh => "account.refresh",
+            AuditAction::AccountExport => "account.export",
+            AuditAction::AccountImport => "account.import",
+            AuditAction::AuthLogin => "auth.login",
+            AuditAction::AuthLogout => "auth.logout",
+            AuditAction::AuthRefresh => "auth.refresh",
+            AuditAction::AuthFailure => "auth.failure",
+            AuditAction::ConfigLoad => "config.load",
+            AuditAction::ConfigChange => "config.change",
+            AuditAction::RequestStart => "request.start",
+            AuditAction::RequestSuccess => "request.success",
+            AuditAction::RequestFailure => "request.failure",
+            AuditAction::CircuitOpen => "circuit.open",
+            AuditAction::CircuitClose => "circuit.close",
+        }
+    }
+}
+
+/// TS `enum AuditOutcome`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum AuditOutcome {
+    Success,
+    Failure,
+    Partial,
+}
+
+impl AuditOutcome {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            AuditOutcome::Success => "success",
+            AuditOutcome::Failure => "failure",
+            AuditOutcome::Partial => "partial",
+        }
+    }
+}
+
+/// TS `interface AuditConfig`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuditConfig {
+    pub enabled: bool,
+    pub log_dir: PathBuf,
+    pub max_file_size_bytes: u64,
+    pub max_files: u32,
+}
+
+/// TS `Partial<AuditConfig>` for [`configure_audit`] — shallow merge; only
+/// `Some` fields are applied.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AuditConfigUpdate {
+    pub enabled: Option<bool>,
+    pub log_dir: Option<PathBuf>,
+    pub max_file_size_bytes: Option<u64>,
+    pub max_files: Option<u32>,
+}
+
+static AUDIT_CONFIG: Mutex<Option<AuditConfig>> = Mutex::new(None);
+
+/// TS `DEFAULT_CONFIG` — `{ enabled: true, logDir: getCodexLogDir(),
+/// maxFileSizeBytes: 10 MiB, maxFiles: 5 }`.
+fn default_config() -> AuditConfig {
+    AuditConfig {
+        enabled: true,
+        log_dir: get_codex_log_dir(),
+        max_file_size_bytes: 10 * 1024 * 1024,
+        max_files: 5,
+    }
+}
+
+fn with_config<T>(f: impl FnOnce(&mut AuditConfig) -> T) -> T {
+    let mut guard = AUDIT_CONFIG
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    let config = guard.get_or_insert_with(default_config);
+    f(config)
+}
+
+/// TS `configureAudit(config)` — shallow merge into the module-level config.
+pub fn configure_audit(update: AuditConfigUpdate) {
+    with_config(|config| {
+        if let Some(enabled) = update.enabled {
+            config.enabled = enabled;
+        }
+        if let Some(log_dir) = update.log_dir {
+            config.log_dir = log_dir;
+        }
+        if let Some(max_file_size_bytes) = update.max_file_size_bytes {
+            config.max_file_size_bytes = max_file_size_bytes;
+        }
+        if let Some(max_files) = update.max_files {
+            config.max_files = max_files;
+        }
+    });
+}
+
+/// TS `getAuditConfig()` — returns a copy.
+pub fn get_audit_config() -> AuditConfig {
+    with_config(|config| config.clone())
+}
+
+/// Reset the module-level config so the next access re-resolves defaults.
+/// Test-only affordance: the TS module state resets per test-file process;
+/// Rust tests share one process.
+#[doc(hidden)]
+pub fn __reset_audit_config_for_tests() {
+    let mut guard = AUDIT_CONFIG
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    *guard = None;
+}
+
+/// TS `ensureLogDir()` — mkdir recursive, mode 0700 (mode is unix-only; a
+/// no-op on Windows, Node parity).
+fn ensure_log_dir(log_dir: &Path) -> std::io::Result<()> {
+    if !log_dir.exists() {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::DirBuilderExt;
+            std::fs::DirBuilder::new()
+                .recursive(true)
+                .mode(0o700)
+                .create(log_dir)?;
+        }
+        #[cfg(not(unix))]
+        {
+            std::fs::create_dir_all(log_dir)?;
+        }
+    }
+    Ok(())
+}
+
+fn log_file_path(log_dir: &Path) -> PathBuf {
+    log_dir.join("audit.log")
+}
+
+/// TS `rotateLogsIfNeeded()` — only when `size >= maxFileSizeBytes`. Loop `i`
+/// from `maxFiles - 1` down to `1`: delete the oldest slot on the first
+/// iteration, then shift `audit.log → audit.1.log → … → audit.{n-1}.log`.
+fn rotate_logs_if_needed(config: &AuditConfig) -> std::io::Result<()> {
+    let log_path = log_file_path(&config.log_dir);
+    let Ok(metadata) = std::fs::metadata(&log_path) else {
+        return Ok(());
+    };
+    if metadata.len() < config.max_file_size_bytes {
+        return Ok(());
+    }
+
+    let mut i = config.max_files.saturating_sub(1);
+    while i >= 1 {
+        let older = config.log_dir.join(format!("audit.{i}.log"));
+        let newer = if i == 1 {
+            log_path.clone()
+        } else {
+            config.log_dir.join(format!("audit.{}.log", i - 1))
+        };
+        if i == config.max_files.saturating_sub(1) && older.exists() {
+            std::fs::remove_file(&older)?;
+        }
+        if newer.exists() {
+            std::fs::rename(&newer, &older)?;
+        }
+        i -= 1;
+    }
+    Ok(())
+}
+
+/// TS `sanitizeActor` — actors containing `@` pass through the LOGGER
+/// `maskEmail` variant (not forecast's; spec 05 gotcha 15).
+fn sanitize_actor(actor: &str) -> String {
+    if actor.contains('@') {
+        mask_email(actor)
+    } else {
+        actor.to_string()
+    }
+}
+
+/// TS `sanitizeMetadata` (recursive):
+/// - key lowercased contains `token`/`secret`/`password` → `"***REDACTED***"`;
+/// - string value containing `@` → the WHOLE value through `maskEmail`;
+/// - any non-null object → recursed — **including arrays**, which come back
+///   as objects keyed `"0"`, `"1"`, … (deliberate TS `Object.entries` quirk;
+///   replicated, spec 05 gotcha 19);
+/// - everything else passes through (including `null`).
+fn sanitize_metadata(metadata: &Map<String, Value>) -> Map<String, Value> {
+    let mut sanitized = Map::new();
+    for (key, value) in metadata {
+        let lower_key = key.to_lowercase();
+        if lower_key.contains("token")
+            || lower_key.contains("secret")
+            || lower_key.contains("password")
+        {
+            sanitized.insert(key.clone(), Value::String("***REDACTED***".to_string()));
+        } else if let Some(text) = value.as_str().filter(|text| text.contains('@')) {
+            sanitized.insert(key.clone(), Value::String(mask_email(text)));
+        } else if let Some(object) = value.as_object() {
+            sanitized.insert(key.clone(), Value::Object(sanitize_metadata(object)));
+        } else if let Some(array) = value.as_array() {
+            // typeof [] === "object" in JS: arrays are recursed as records.
+            let mut as_object = Map::new();
+            for (index, item) in array.iter().enumerate() {
+                as_object.insert(index.to_string(), item.clone());
+            }
+            sanitized.insert(key.clone(), Value::Object(sanitize_metadata(&as_object)));
+        } else {
+            sanitized.insert(key.clone(), value.clone());
+        }
+    }
+    sanitized
+}
+
+/// TS `auditLog(action, actor, resource, outcome, metadata?)` — no-op when
+/// disabled; **never fails** (all I/O errors swallowed). Appends one compact
+/// JSON line (field order: `timestamp`, `correlationId`, `action`, `actor`,
+/// `resource`, `outcome`, `metadata?`) to `<logDir>/audit.log`.
+pub fn audit_log(
+    action: AuditAction,
+    actor: &str,
+    resource: &str,
+    outcome: AuditOutcome,
+    metadata: Option<&Map<String, Value>>,
+) {
+    let config = get_audit_config();
+    if !config.enabled {
+        return;
+    }
+
+    let result: std::io::Result<()> = (|| {
+        ensure_log_dir(&config.log_dir)?;
+        rotate_logs_if_needed(&config)?;
+
+        let mut entry = Map::new();
+        // `new Date().toISOString()` — millisecond precision, `Z` suffix.
+        let timestamp = chrono::Utc::now()
+            .format("%Y-%m-%dT%H:%M:%S%.3fZ")
+            .to_string();
+        entry.insert("timestamp".to_string(), Value::String(timestamp));
+        entry.insert(
+            "correlationId".to_string(),
+            match get_correlation_id() {
+                Some(id) => Value::String(id),
+                None => Value::Null,
+            },
+        );
+        entry.insert(
+            "action".to_string(),
+            Value::String(action.as_str().to_string()),
+        );
+        entry.insert("actor".to_string(), Value::String(sanitize_actor(actor)));
+        entry.insert("resource".to_string(), Value::String(resource.to_string()));
+        entry.insert(
+            "outcome".to_string(),
+            Value::String(outcome.as_str().to_string()),
+        );
+        if let Some(metadata) = metadata {
+            entry.insert(
+                "metadata".to_string(),
+                Value::Object(sanitize_metadata(metadata)),
+            );
+        }
+
+        let line = format!("{}\n", stringify_compact(&Value::Object(entry)));
+        let mut file = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(log_file_path(&config.log_dir))?;
+        file.write_all(line.as_bytes())?;
+        Ok(())
+    })();
+    // Audit logging should never break the application.
+    let _ = result;
+}
+
+/// TS `getAuditLogPath()`.
+pub fn get_audit_log_path() -> PathBuf {
+    with_config(|config| log_file_path(&config.log_dir))
+}
+
+/// TS `listAuditLogFiles()` — ensures the dir, keeps names matching
+/// `audit*.log`, maps to absolute paths, lexicographic sort. (TS propagates
+/// fs errors; here an unreadable dir yields an empty list — recorded
+/// deviation, the dormant callers never relied on the throw.)
+pub fn list_audit_log_files() -> Vec<PathBuf> {
+    let log_dir = with_config(|config| config.log_dir.clone());
+    let _ = ensure_log_dir(&log_dir);
+    let Ok(entries) = std::fs::read_dir(&log_dir) else {
+        return Vec::new();
+    };
+    let mut files: Vec<PathBuf> = entries
+        .filter_map(|entry| entry.ok())
+        .filter_map(|entry| entry.file_name().into_string().ok())
+        .filter(|name| name.starts_with("audit") && name.ends_with(".log"))
+        .map(|name| log_dir.join(name))
+        .collect();
+    files.sort_by(|a, b| a.to_string_lossy().cmp(&b.to_string_lossy()));
+    files
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use serial_test::serial;
+
+    fn setup(max_file_size_bytes: u64, max_files: u32) -> tempfile::TempDir {
+        __reset_audit_config_for_tests();
+        let dir = tempfile::Builder::new()
+            .prefix("cma-audit-test-")
+            .tempdir()
+            .unwrap();
+        configure_audit(AuditConfigUpdate {
+            enabled: Some(true),
+            log_dir: Some(dir.path().to_path_buf()),
+            max_file_size_bytes: Some(max_file_size_bytes),
+            max_files: Some(max_files),
+        });
+        dir
+    }
+
+    fn read_first_entry() -> Value {
+        let content = std::fs::read_to_string(get_audit_log_path()).unwrap();
+        serde_json::from_str(content.trim().lines().next().unwrap()).unwrap()
+    }
+
+    fn metadata(value: Value) -> Map<String, Value> {
+        value.as_object().unwrap().clone()
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn writes_audit_entry_to_log_file() {
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AccountAdd,
+            "test-actor",
+            "test-resource",
+            AuditOutcome::Success,
+            None,
+        );
+
+        let entry = read_first_entry();
+        assert_eq!(entry["action"], "account.add");
+        assert_eq!(entry["actor"], "test-actor");
+        assert_eq!(entry["resource"], "test-resource");
+        assert_eq!(entry["outcome"], "success");
+        assert!(entry["timestamp"].is_string());
+        assert!(entry.get("correlationId").is_some());
+        assert!(entry.get("metadata").is_none());
+        // Field order is frozen.
+        let keys: Vec<&String> = entry.as_object().unwrap().keys().collect();
+        assert_eq!(
+            keys,
+            ["timestamp", "correlationId", "action", "actor", "resource", "outcome"]
+        );
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn includes_metadata_when_provided() {
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AuthLogin,
+            "user",
+            "auth",
+            AuditOutcome::Success,
+            Some(&metadata(json!({ "method": "oauth" }))),
+        );
+        let entry = read_first_entry();
+        assert_eq!(entry["metadata"], json!({ "method": "oauth" }));
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn redacts_sensitive_metadata() {
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AuthRefresh,
+            "user",
+            "tokens",
+            AuditOutcome::Success,
+            Some(&metadata(json!({
+                "accessToken": "secret123",
+                "refreshToken": "secret456"
+            }))),
+        );
+        let entry = read_first_entry();
+        assert_eq!(entry["metadata"]["accessToken"], "***REDACTED***");
+        assert_eq!(entry["metadata"]["refreshToken"], "***REDACTED***");
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn masks_email_addresses_in_actor_and_metadata() {
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AccountAdd,
+            "user@example.com",
+            "account",
+            AuditOutcome::Success,
+            Some(&metadata(json!({ "userEmail": "test@example.org" }))),
+        );
+        let entry = read_first_entry();
+        let actor = entry["actor"].as_str().unwrap();
+        assert!(!actor.contains("user@example.com"));
+        assert!(actor.contains("***"));
+        // Logger maskEmail variant: <=2 local chars + "***@***." + tld.
+        assert_eq!(actor, "us***@***.com");
+        let email = entry["metadata"]["userEmail"].as_str().unwrap();
+        assert!(!email.contains("test@example.org"));
+        assert!(email.contains("***"));
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn recursively_sanitizes_nested_object_metadata() {
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AccountAdd,
+            "actor",
+            "account",
+            AuditOutcome::Success,
+            Some(&metadata(json!({
+                "nested": {
+                    "secretToken": "hidden-value",
+                    "email": "nested@example.com"
+                }
+            }))),
+        );
+        let entry = read_first_entry();
+        assert_eq!(entry["metadata"]["nested"]["secretToken"], "***REDACTED***");
+        assert!(entry["metadata"]["nested"]["email"]
+            .as_str()
+            .unwrap()
+            .contains("***"));
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn arrays_are_recursed_as_records() {
+        // TS Object.entries quirk: an array serializes as {"0":..., "1":...}.
+        let _dir = setup(1024, 3);
+        audit_log(
+            AuditAction::AccountAdd,
+            "actor",
+            "account",
+            AuditOutcome::Success,
+            Some(&metadata(json!({ "items": ["a@b.com", 7] }))),
+        );
+        let entry = read_first_entry();
+        assert!(entry["metadata"]["items"].is_object());
+        assert!(entry["metadata"]["items"]["0"]
+            .as_str()
+            .unwrap()
+            .contains("***"));
+        assert_eq!(entry["metadata"]["items"]["1"], 7);
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn does_not_write_when_disabled() {
+        let _dir = setup(1024, 3);
+        configure_audit(AuditConfigUpdate {
+            enabled: Some(false),
+            ..Default::default()
+        });
+        audit_log(
+            AuditAction::AccountAdd,
+            "actor",
+            "resource",
+            AuditOutcome::Success,
+            None,
+        );
+        assert!(!get_audit_log_path().exists());
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn configure_preserves_other_config_values() {
+        let dir = setup(1024, 3);
+        configure_audit(AuditConfigUpdate {
+            enabled: Some(false),
+            ..Default::default()
+        });
+        let config = get_audit_config();
+        assert!(!config.enabled);
+        assert_eq!(config.log_dir, dir.path());
+        assert_eq!(config.max_file_size_bytes, 1024);
+        assert_eq!(config.max_files, 3);
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn appends_multiple_entries() {
+        let _dir = setup(1024 * 1024, 3);
+        audit_log(AuditAction::AccountAdd, "a1", "r1", AuditOutcome::Success, None);
+        audit_log(
+            AuditAction::AccountRemove,
+            "a2",
+            "r2",
+            AuditOutcome::Failure,
+            None,
+        );
+        let content = std::fs::read_to_string(get_audit_log_path()).unwrap();
+        assert_eq!(content.trim().lines().count(), 2);
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn rotates_logs_when_max_size_exceeded_and_limits_file_count() {
+        let _dir = setup(1024, 3);
+        let large = "x".repeat(800);
+        for i in 0..10 {
+            audit_log(
+                AuditAction::RequestStart,
+                "actor",
+                &format!("resource-{i}"),
+                AuditOutcome::Success,
+                Some(&metadata(json!({ "data": large }))),
+            );
+        }
+        let files = list_audit_log_files();
+        assert!(!files.is_empty());
+        // maxFiles: 3 → audit.log + audit.1.log + audit.2.log at most.
+        assert!(files.len() <= 3);
+    }
+
+    #[test]
+    #[serial(audit)]
+    fn lists_audit_log_files_sorted() {
+        let _dir = setup(1024, 3);
+        assert!(list_audit_log_files().is_empty());
+        audit_log(
+            AuditAction::AccountAdd,
+            "actor",
+            "resource",
+            AuditOutcome::Success,
+            None,
+        );
+        let files = list_audit_log_files();
+        assert!(!files.is_empty());
+        assert!(files[0].to_string_lossy().contains("audit"));
+    }
+
+    #[test]
+    fn enum_string_values_are_frozen() {
+        assert_eq!(AuditAction::AccountAdd.as_str(), "account.add");
+        assert_eq!(AuditAction::AccountRemove.as_str(), "account.remove");
+        assert_eq!(AuditAction::AccountSwitch.as_str(), "account.switch");
+        assert_eq!(AuditAction::AccountRefresh.as_str(), "account.refresh");
+        assert_eq!(AuditAction::AccountExport.as_str(), "account.export");
+        assert_eq!(AuditAction::AccountImport.as_str(), "account.import");
+        assert_eq!(AuditAction::AuthLogin.as_str(), "auth.login");
+        assert_eq!(AuditAction::AuthLogout.as_str(), "auth.logout");
+        assert_eq!(AuditAction::AuthRefresh.as_str(), "auth.refresh");
+        assert_eq!(AuditAction::AuthFailure.as_str(), "auth.failure");
+        assert_eq!(AuditAction::ConfigLoad.as_str(), "config.load");
+        assert_eq!(AuditAction::ConfigChange.as_str(), "config.change");
+        assert_eq!(AuditAction::RequestStart.as_str(), "request.start");
+        assert_eq!(AuditAction::RequestSuccess.as_str(), "request.success");
+        assert_eq!(AuditAction::RequestFailure.as_str(), "request.failure");
+        assert_eq!(AuditAction::CircuitOpen.as_str(), "circuit.open");
+        assert_eq!(AuditAction::CircuitClose.as_str(), "circuit.close");
+        assert_eq!(AuditOutcome::Success.as_str(), "success");
+        assert_eq!(AuditOutcome::Failure.as_str(), "failure");
+        assert_eq!(AuditOutcome::Partial.as_str(), "partial");
+    }
+}
diff --git a/crates/quota/src/budget_guard.rs b/crates/quota/src/budget_guard.rs
new file mode 100644
index 000000000..e1f730f38
--- /dev/null
+++ b/crates/quota/src/budget_guard.rs
@@ -0,0 +1,756 @@
+//! Port of `lib/budget-guard.ts` — on-disk budget limits
+//! (`budget-guards.json`, version 1) + UTC window math + evaluation against
+//! usage-ledger summaries.
+//!
+//! Byte-compat notes (spec 05 §6 + gotchas 10/23):
+//! - Serialization is `JSON.stringify(payload, null, 2) + "\n"`, mode 0600,
+//!   dir 0700, atomic temp+rename with EBUSY/EPERM-only retry (5 attempts,
+//!   10·2^n ms) — the retry-code set is deliberately NARROWER than
+//!   quota-cache's; preserve the asymmetry.
+//! - `save_budget_guard_store` PROPAGATES errors (TS throws) — unlike
+//!   `saveQuotaCache` which swallows.
+//! - All window math is UTC; weeks start Monday.
+
+use std::io;
+use std::path::PathBuf;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::{
+    TrailingNewline, WriteJsonOptions, format_js_number, stringify_pretty2, write_json_atomic,
+};
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::is_record;
+use cma_usage::types::UsageSummary;
+use serde::ser::{Serialize, SerializeMap, Serializer};
+use serde_json::Value;
+
+/// TS `BUDGET_GUARD_FILE_NAME`.
+pub const BUDGET_GUARD_FILE_NAME: &str = "budget-guards.json";
+
+/// TS `RETRYABLE_FS_CODES` — EBUSY/EPERM ONLY (narrower than quota-cache).
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+
+/// In-process write serialization (TS module-level `writeQueue` promise
+/// chain; tokio's Mutex is FIFO-fair and a failed task never poisons the
+/// queue — matching the `.catch(() => undefined)` chain reset).
+static WRITE_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+/// TS `type BudgetWindow = "hour" | "day" | "week" | "month"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum BudgetWindow {
+    #[serde(rename = "hour")]
+    Hour,
+    #[serde(rename = "day")]
+    Day,
+    #[serde(rename = "week")]
+    Week,
+    #[serde(rename = "month")]
+    Month,
+}
+
+impl BudgetWindow {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            BudgetWindow::Hour => "hour",
+            BudgetWindow::Day => "day",
+            BudgetWindow::Week => "week",
+            BudgetWindow::Month => "month",
+        }
+    }
+
+    /// Strict membership test against `VALID_WINDOWS` (no fallback).
+    pub fn parse(value: &str) -> Option<Self> {
+        Some(match value {
+            "hour" => BudgetWindow::Hour,
+            "day" => BudgetWindow::Day,
+            "week" => BudgetWindow::Week,
+            "month" => BudgetWindow::Month,
+            _ => return None,
+        })
+    }
+}
+
+/// TS `interface BudgetLimit`. Field declaration order == on-disk emission
+/// order (byte compat); absent caps are omitted (`undefined` semantics).
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BudgetLimit {
+    /// Always the normalized map key.
+    pub key: String,
+    pub window: BudgetWindow,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_requests: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_cost_usd: Option<f64>,
+    /// Epoch ms; `0` when unknown.
+    pub updated_at: f64,
+}
+
+/// TS `Omit<BudgetLimit, "updatedAt">` — input for [`upsert_budget_limit`].
+#[derive(Debug, Clone, PartialEq)]
+pub struct BudgetLimitInput {
+    pub key: String,
+    pub window: BudgetWindow,
+    pub max_requests: Option<f64>,
+    pub max_tokens: Option<f64>,
+    pub max_cost_usd: Option<f64>,
+}
+
+/// TS `interface BudgetGuardStore` (`version` is always the literal `1`; the
+/// Rust type omits the field and the serializer emits it).
+///
+/// `limits` preserves JS-object insertion order: re-assigning an existing key
+/// keeps its position; new keys append.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct BudgetGuardStore {
+    entries: Vec<(String, BudgetLimit)>,
+}
+
+impl BudgetGuardStore {
+    /// TS `emptyStore()`.
+    pub fn empty() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn get(&self, key: &str) -> Option<&BudgetLimit> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, limit)| limit)
+    }
+
+    pub fn get_mut(&mut self, key: &str) -> Option<&mut BudgetLimit> {
+        self.entries
+            .iter_mut()
+            .find(|(k, _)| k == key)
+            .map(|(_, limit)| limit)
+    }
+
+    pub fn remove(&mut self, key: &str) -> Option<BudgetLimit> {
+        let position = self.entries.iter().position(|(k, _)| k == key)?;
+        Some(self.entries.remove(position).1)
+    }
+
+    /// JS `store.limits[key] = limit`: replaces in place (keeping position)
+    /// when the key exists, otherwise appends.
+    pub fn insert(&mut self, key: impl Into<String>, limit: BudgetLimit) {
+        let key = key.into();
+        if let Some(entry) = self.entries.iter_mut().find(|(k, _)| *k == key) {
+            entry.1 = limit;
+        } else {
+            self.entries.push((key, limit));
+        }
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, &BudgetLimit)> {
+        self.entries.iter().map(|(k, limit)| (k.as_str(), limit))
+    }
+}
+
+impl Serialize for BudgetGuardStore {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        struct Limits<'a>(&'a [(String, BudgetLimit)]);
+        impl Serialize for Limits<'_> {
+            fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+                let mut map = serializer.serialize_map(Some(self.0.len()))?;
+                for (key, limit) in self.0 {
+                    map.serialize_entry(key, limit)?;
+                }
+                map.end()
+            }
+        }
+        let mut map = serializer.serialize_map(Some(2))?;
+        map.serialize_entry("version", &1)?;
+        map.serialize_entry("limits", &Limits(&self.entries))?;
+        map.end()
+    }
+}
+
+/// TS `interface BudgetGuardEvaluation` — `usage` echo.
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BudgetGuardUsage {
+    pub requests: u64,
+    pub total_tokens: u64,
+    pub cost_usd: f64,
+}
+
+/// TS `interface BudgetGuardEvaluation` — `limits` echo (`null` when unset,
+/// hence NO skip_serializing_if).
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BudgetGuardLimits {
+    pub max_requests: Option<f64>,
+    pub max_tokens: Option<f64>,
+    pub max_cost_usd: Option<f64>,
+}
+
+/// TS `interface BudgetGuardEvaluation`.
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BudgetGuardEvaluation {
+    pub key: String,
+    pub window: BudgetWindow,
+    pub allowed: bool,
+    pub reasons: Vec<String>,
+    pub usage: BudgetGuardUsage,
+    pub limits: BudgetGuardLimits,
+}
+
+/// TS `getBudgetGuardPath()` — computed per call (NOT cached at module load,
+/// unlike quota-cache).
+pub fn get_budget_guard_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(BUDGET_GUARD_FILE_NAME)
+}
+
+/// TS `normalizeBudgetKey` / private `normalizeKey`: trim → lowercase →
+/// replace runs of `[^a-z0-9._:-]+` with `"-"` → `None` if empty → truncate
+/// to 100 chars. (The replacement leaves only ASCII, so char == UTF-16-unit
+/// truncation.)
+pub fn normalize_budget_key(value: &str) -> Option<String> {
+    let lowered = value.trim().to_lowercase();
+    let mut normalized = String::with_capacity(lowered.len());
+    let mut in_run = false;
+    for ch in lowered.chars() {
+        let allowed = matches!(ch, 'a'..='z' | '0'..='9' | '.' | '_' | ':' | '-');
+        if allowed {
+            normalized.push(ch);
+            in_run = false;
+        } else if !in_run {
+            normalized.push('-');
+            in_run = true;
+        }
+    }
+    if normalized.is_empty() {
+        return None;
+    }
+    Some(normalized.chars().take(100).collect())
+}
+
+/// TS `normalizePositiveNumber` — finite AND `> 0`, else `undefined`.
+fn normalize_positive_number(value: Option<f64>) -> Option<f64> {
+    value.filter(|v| v.is_finite() && *v > 0.0)
+}
+
+fn value_positive_number(value: Option<&Value>) -> Option<f64> {
+    normalize_positive_number(value.and_then(Value::as_f64))
+}
+
+/// TS `normalizeLimit(key, value)` over a raw JSON value — `None` when the
+/// value is not a record or the window is invalid.
+fn normalize_limit_value(key: &str, value: &Value) -> Option<BudgetLimit> {
+    if !is_record(value) {
+        return None;
+    }
+    let window = value
+        .get("window")
+        .and_then(Value::as_str)
+        .and_then(BudgetWindow::parse)?;
+    Some(BudgetLimit {
+        key: key.to_string(),
+        window,
+        max_requests: value_positive_number(value.get("maxRequests")),
+        max_tokens: value_positive_number(value.get("maxTokens")),
+        max_cost_usd: value_positive_number(value.get("maxCostUsd")),
+        updated_at: value
+            .get("updatedAt")
+            .and_then(Value::as_f64)
+            .filter(|v| v.is_finite())
+            .unwrap_or(0.0),
+    })
+}
+
+/// TS `normalizeStore(value)` over a raw JSON value — `version !== 1` (or a
+/// non-record) yields the empty store; keys are re-normalized (dropped when
+/// null); invalid limit entries are dropped.
+fn normalize_store_value(value: &Value) -> BudgetGuardStore {
+    if !is_record(value) || value.get("version").and_then(Value::as_f64) != Some(1.0) {
+        return BudgetGuardStore::empty();
+    }
+    let mut store = BudgetGuardStore::empty();
+    if let Some(limits) = value.get("limits").filter(|v| is_record(v)).and_then(Value::as_object) {
+        for (raw_key, raw) in limits {
+            let Some(key) = normalize_budget_key(raw_key) else {
+                continue;
+            };
+            if let Some(limit) = normalize_limit_value(&key, raw) {
+                store.insert(key, limit);
+            }
+        }
+    }
+    store
+}
+
+/// `normalizeStore` over an already-typed store (the save path): keys are
+/// re-normalized, caps re-filtered to finite-positive, `updatedAt`
+/// re-defaulted, and the entry `key` field forced to the normalized map key.
+fn normalize_store_typed(store: &BudgetGuardStore) -> BudgetGuardStore {
+    let mut normalized = BudgetGuardStore::empty();
+    for (raw_key, limit) in store.iter() {
+        let Some(key) = normalize_budget_key(raw_key) else {
+            continue;
+        };
+        let entry = BudgetLimit {
+            key: key.clone(),
+            window: limit.window,
+            max_requests: normalize_positive_number(limit.max_requests),
+            max_tokens: normalize_positive_number(limit.max_tokens),
+            max_cost_usd: normalize_positive_number(limit.max_cost_usd),
+            updated_at: if limit.updated_at.is_finite() {
+                limit.updated_at
+            } else {
+                0.0
+            },
+        };
+        normalized.insert(key, entry);
+    }
+    normalized
+}
+
+/// TS backoff `sleep(10 * 2 ** attempt)` with the 0-based failed-attempt
+/// counter → 10/20/40/80 ms for the core retry helper's 1-based index.
+fn budget_guard_backoff() -> Backoff {
+    Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1))))
+}
+
+/// TS `readFileWithRetry` — 5 attempts, EBUSY/EPERM only.
+async fn read_file_with_retry(path: &std::path::Path) -> io::Result<String> {
+    with_retry(
+        || async { tokio::fs::read_to_string(path).await },
+        RetryOptions::<io::Error>::new(5, budget_guard_backoff()).with_codes(RETRYABLE_FS_CODES),
+    )
+    .await
+}
+
+/// TS `loadBudgetGuardStore()` — NEVER fails: missing file → empty store;
+/// unreadable/malformed/wrong-version → warn + empty store (no migration).
+pub async fn load_budget_guard_store() -> BudgetGuardStore {
+    let path = get_budget_guard_path();
+    if !path.exists() {
+        return BudgetGuardStore::empty();
+    }
+    let parsed: Result<Value, String> = match read_file_with_retry(&path).await {
+        Ok(raw) => serde_json::from_str::<Value>(&raw).map_err(|error| error.to_string()),
+        Err(error) => Err(error.to_string()),
+    };
+    match parsed {
+        Ok(value) => normalize_store_value(&value),
+        Err(message) => {
+            let basename = path
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_default();
+            log_warn(
+                &format!("Failed to load budget guards from {basename}: {message}"),
+                None,
+            );
+            BudgetGuardStore::empty()
+        }
+    }
+}
+
+/// TS `saveBudgetGuardStore(store)` — normalize BEFORE write (unlike
+/// `saveQuotaCache`), then queue an atomic temp+rename write (dir 0700, file
+/// 0600, 2-space pretty + trailing `\n`, rename retried ×5 on EBUSY/EPERM,
+/// temp unlinked on failure). **Propagates errors** (TS throws).
+pub async fn save_budget_guard_store(store: &BudgetGuardStore) -> io::Result<()> {
+    let path = get_budget_guard_path();
+    let payload = normalize_store_typed(store);
+    let content = stringify_pretty2(&payload);
+    let _queue = WRITE_QUEUE.lock().await;
+    write_json_atomic(
+        &path,
+        &content,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::Lf,
+            ensure_parent_dir: true,
+            parent_dir_mode: Some(0o700),
+            rename_max_attempts: 5,
+            ..Default::default()
+        },
+    )
+    .await
+}
+
+/// TS `resetBudgetGuardWriteQueueForTests()` — the Rust queue is a static
+/// FIFO mutex with no persistent failure state, so this is a no-op kept for
+/// API parity.
+pub fn reset_budget_guard_write_queue_for_tests() {}
+
+/// TS `upsertBudgetLimit(store, limit, now = Date.now())` — normalizes the
+/// key/caps, stamps `updatedAt = now`, mutates the store, and returns the
+/// stored limit. Errors (frozen messages): `"Budget key is required"` when
+/// the key normalizes to nothing. (The TS `"Invalid budget limit"` branch is
+/// unreachable with a typed window; kept out by construction.)
+#[allow(clippy::result_large_err)] // CodexError is the crate-wide error vocabulary.
+pub fn upsert_budget_limit(
+    store: &mut BudgetGuardStore,
+    limit: &BudgetLimitInput,
+    now: i64,
+) -> Result<BudgetLimit, CodexError> {
+    let Some(key) = normalize_budget_key(&limit.key) else {
+        return Err(CodexError::new("Budget key is required"));
+    };
+    let next = BudgetLimit {
+        key: key.clone(),
+        window: limit.window,
+        max_requests: normalize_positive_number(limit.max_requests),
+        max_tokens: normalize_positive_number(limit.max_tokens),
+        max_cost_usd: normalize_positive_number(limit.max_cost_usd),
+        updated_at: now as f64,
+    };
+    store.insert(key, next.clone());
+    Ok(next)
+}
+
+/// TS `getBudgetWindowStart(window, now = Date.now())` — all UTC; weeks start
+/// **Monday** (`mondayOffset = day === 0 ? 6 : day - 1` over `getUTCDay()`).
+pub fn get_budget_window_start(window: BudgetWindow, now_ms: i64) -> i64 {
+    use chrono::{Datelike, Duration, TimeZone, Timelike, Utc};
+    let date = Utc
+        .timestamp_millis_opt(now_ms)
+        .single()
+        .unwrap_or_else(|| Utc.timestamp_millis_opt(0).unwrap());
+    match window {
+        BudgetWindow::Hour => date
+            .with_minute(0)
+            .and_then(|d| d.with_second(0))
+            .and_then(|d| d.with_nanosecond(0))
+            .map(|d| d.timestamp_millis())
+            .unwrap_or(now_ms),
+        BudgetWindow::Day => day_start(date).timestamp_millis(),
+        BudgetWindow::Week => {
+            let start = day_start(date);
+            let day = start.weekday().num_days_from_sunday() as i64;
+            let monday_offset = if day == 0 { 6 } else { day - 1 };
+            (start - Duration::days(monday_offset)).timestamp_millis()
+        }
+        BudgetWindow::Month => {
+            // TS order: setUTCDate(1) BEFORE setUTCHours (UTC, so order-safe).
+            let first = date.with_day(1).unwrap_or(date);
+            day_start(first).timestamp_millis()
+        }
+    }
+}
+
+fn day_start(date: chrono::DateTime<chrono::Utc>) -> chrono::DateTime<chrono::Utc> {
+    use chrono::Timelike;
+    date.with_hour(0)
+        .and_then(|d| d.with_minute(0))
+        .and_then(|d| d.with_second(0))
+        .and_then(|d| d.with_nanosecond(0))
+        .unwrap_or(date)
+}
+
+/// TS `evaluateBudgetGuard(limit, summary)` — each cap applies only when set;
+/// comparisons are `>=`. Reason strings are FROZEN (cost sides both
+/// `toFixed(6)`).
+pub fn evaluate_budget_guard(limit: &BudgetLimit, summary: &UsageSummary) -> BudgetGuardEvaluation {
+    let totals = &summary.totals;
+    let mut reasons: Vec<String> = Vec::new();
+    if let Some(max_requests) = limit.max_requests
+        && totals.requests as f64 >= max_requests
+    {
+        reasons.push(format!(
+            "request limit reached ({}/{})",
+            totals.requests,
+            format_js_number(max_requests)
+        ));
+    }
+    if let Some(max_tokens) = limit.max_tokens
+        && totals.total_tokens as f64 >= max_tokens
+    {
+        reasons.push(format!(
+            "token limit reached ({}/{})",
+            totals.total_tokens,
+            format_js_number(max_tokens)
+        ));
+    }
+    if let Some(max_cost_usd) = limit.max_cost_usd
+        && totals.cost_usd >= max_cost_usd
+    {
+        reasons.push(format!(
+            "cost limit reached ({:.6}/{:.6})",
+            totals.cost_usd, max_cost_usd
+        ));
+    }
+    BudgetGuardEvaluation {
+        key: limit.key.clone(),
+        window: limit.window,
+        allowed: reasons.is_empty(),
+        reasons,
+        usage: BudgetGuardUsage {
+            requests: totals.requests,
+            total_tokens: totals.total_tokens,
+            cost_usd: totals.cost_usd,
+        },
+        limits: BudgetGuardLimits {
+            max_requests: limit.max_requests,
+            max_tokens: limit.max_tokens,
+            max_cost_usd: limit.max_cost_usd,
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::goldens::read_golden_string;
+    use cma_testkit::sandbox::EnvSandbox;
+    use cma_usage::types::{UsageSummary, UsageSummaryBucket, UsageSummaryGroupBy};
+    use serial_test::serial;
+
+    fn make_summary(requests: u64, total_tokens: u64, cost_usd: f64) -> UsageSummary {
+        UsageSummary {
+            since: None,
+            until: None,
+            by: UsageSummaryGroupBy::default(),
+            totals: UsageSummaryBucket {
+                key: "total".to_string(),
+                requests,
+                successes: requests,
+                failures: 0,
+                blocked: 0,
+                cancelled: 0,
+                input_tokens: total_tokens,
+                output_tokens: 0,
+                cached_input_tokens: 0,
+                reasoning_tokens: 0,
+                total_tokens,
+                cost_usd,
+            },
+            buckets: Vec::new(),
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn saves_loads_and_evaluates_limits() {
+        let _sandbox = EnvSandbox::new();
+        let mut store = load_budget_guard_store().await;
+        let limit = upsert_budget_limit(
+            &mut store,
+            &BudgetLimitInput {
+                key: "Project A".to_string(),
+                window: BudgetWindow::Day,
+                max_requests: Some(2.0),
+                max_tokens: Some(100.0),
+                max_cost_usd: Some(1.0),
+            },
+            123,
+        )
+        .unwrap();
+        save_budget_guard_store(&store).await.unwrap();
+
+        let loaded = load_budget_guard_store().await;
+        assert_eq!(loaded.get("project-a"), Some(&limit));
+        assert!(evaluate_budget_guard(&limit, &make_summary(1, 99, 0.5)).allowed);
+        let blocked = evaluate_budget_guard(&limit, &make_summary(2, 101, 1.1));
+        assert!(!blocked.allowed);
+        assert_eq!(blocked.reasons.len(), 3);
+    }
+
+    #[test]
+    fn frozen_reason_strings() {
+        let limit = BudgetLimit {
+            key: "k".to_string(),
+            window: BudgetWindow::Day,
+            max_requests: Some(2.0),
+            max_tokens: Some(100.0),
+            max_cost_usd: Some(1.0),
+            updated_at: 0.0,
+        };
+        let evaluation = evaluate_budget_guard(&limit, &make_summary(2, 101, 1.1));
+        assert_eq!(
+            evaluation.reasons,
+            vec![
+                "request limit reached (2/2)".to_string(),
+                "token limit reached (101/100)".to_string(),
+                "cost limit reached (1.100000/1.000000)".to_string(),
+            ]
+        );
+    }
+
+    #[test]
+    fn computes_utc_budget_window_starts() {
+        use chrono::{TimeZone, Utc};
+        // Date.UTC(2026, 3, 29, 12, 34, 56) — month is 0-based in JS.
+        let now = Utc
+            .with_ymd_and_hms(2026, 4, 29, 12, 34, 56)
+            .unwrap()
+            .timestamp_millis();
+        let iso = |ms: i64| {
+            Utc.timestamp_millis_opt(ms)
+                .unwrap()
+                .format("%Y-%m-%dT%H:%M:%S%.3fZ")
+                .to_string()
+        };
+        assert_eq!(
+            iso(get_budget_window_start(BudgetWindow::Hour, now)),
+            "2026-04-29T12:00:00.000Z"
+        );
+        assert_eq!(
+            iso(get_budget_window_start(BudgetWindow::Day, now)),
+            "2026-04-29T00:00:00.000Z"
+        );
+        assert_eq!(
+            iso(get_budget_window_start(BudgetWindow::Month, now)),
+            "2026-04-01T00:00:00.000Z"
+        );
+        // 2026-04-29 is a Wednesday → Monday 2026-04-27 (Monday-start weeks).
+        assert_eq!(
+            iso(get_budget_window_start(BudgetWindow::Week, now)),
+            "2026-04-27T00:00:00.000Z"
+        );
+        // Sunday maps back 6 days to the previous Monday.
+        let sunday = Utc
+            .with_ymd_and_hms(2026, 4, 26, 8, 0, 0)
+            .unwrap()
+            .timestamp_millis();
+        assert_eq!(
+            iso(get_budget_window_start(BudgetWindow::Week, sunday)),
+            "2026-04-20T00:00:00.000Z"
+        );
+    }
+
+    #[test]
+    fn normalize_budget_key_rules() {
+        assert_eq!(normalize_budget_key("  Project A  "), Some("project-a".to_string()));
+        assert_eq!(normalize_budget_key("Team Alpha"), Some("team-alpha".to_string()));
+        assert_eq!(
+            normalize_budget_key("project:MyApp"),
+            Some("project:myapp".to_string())
+        );
+        // Runs of disallowed characters collapse into a single dash.
+        assert_eq!(normalize_budget_key("a!!b"), Some("a-b".to_string()));
+        assert_eq!(normalize_budget_key("!!!"), Some("-".to_string()));
+        assert_eq!(normalize_budget_key("   "), None);
+        assert_eq!(normalize_budget_key(""), None);
+        // Truncated to 100 chars.
+        let long = "x".repeat(150);
+        assert_eq!(normalize_budget_key(&long).unwrap().len(), 100);
+    }
+
+    #[test]
+    fn rejects_empty_budget_key_on_upsert() {
+        let mut store = BudgetGuardStore::empty();
+        let error = upsert_budget_limit(
+            &mut store,
+            &BudgetLimitInput {
+                key: "   ".to_string(),
+                window: BudgetWindow::Day,
+                max_requests: None,
+                max_tokens: None,
+                max_cost_usd: None,
+            },
+            1,
+        )
+        .unwrap_err();
+        assert_eq!(error.message(), "Budget key is required");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn version_mismatch_discards_store() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(
+            get_budget_guard_path(),
+            "{\"version\":2,\"limits\":{\"a\":{\"window\":\"day\"}}}",
+        )
+        .unwrap();
+        assert!(load_budget_guard_store().await.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn malformed_json_loads_as_empty_store() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_budget_guard_path(), "{oops").unwrap();
+        assert!(load_budget_guard_store().await.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn load_normalization_drops_invalid_entries_and_caps() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(
+            get_budget_guard_path(),
+            concat!(
+                "{\"version\":1,\"limits\":{",
+                "\"Team Alpha\":{\"window\":\"day\",\"maxRequests\":-5,\"maxTokens\":0,",
+                "\"maxCostUsd\":2.5,\"updatedAt\":\"bogus\"},",
+                "\"bad-window\":{\"window\":\"decade\"},",
+                "\"   \":{\"window\":\"day\"}",
+                "}}"
+            ),
+        )
+        .unwrap();
+        let store = load_budget_guard_store().await;
+        assert_eq!(store.len(), 1);
+        let limit = store.get("team-alpha").expect("normalized key");
+        assert_eq!(limit.key, "team-alpha");
+        assert_eq!(limit.window, BudgetWindow::Day);
+        assert_eq!(limit.max_requests, None);
+        assert_eq!(limit.max_tokens, None);
+        assert_eq!(limit.max_cost_usd, Some(2.5));
+        assert_eq!(limit.updated_at, 0.0);
+    }
+
+    /// Golden byte-compat: the exact fixture the TS implementation wrote for
+    /// the same two upserts (T0 = 1750000000000).
+    #[test]
+    fn golden_budget_guards_bytes() {
+        const T0: i64 = 1_750_000_000_000;
+        let mut store = BudgetGuardStore::empty();
+        upsert_budget_limit(
+            &mut store,
+            &BudgetLimitInput {
+                key: "team-alpha".to_string(),
+                window: BudgetWindow::Day,
+                max_requests: Some(500.0),
+                max_tokens: Some(2_000_000.0),
+                max_cost_usd: Some(25.0),
+            },
+            T0,
+        )
+        .unwrap();
+        upsert_budget_limit(
+            &mut store,
+            &BudgetLimitInput {
+                key: "personal".to_string(),
+                window: BudgetWindow::Month,
+                max_requests: None,
+                max_tokens: None,
+                max_cost_usd: Some(100.0),
+            },
+            T0,
+        )
+        .unwrap();
+        let payload = normalize_store_typed(&store);
+        let serialized = format!("{}\n", stringify_pretty2(&payload));
+        assert_eq!(serialized, read_golden_string("budget-guards.json"));
+
+        // Round-trip: loading the golden and re-serializing is byte-stable.
+        let parsed: Value =
+            serde_json::from_str(&read_golden_string("budget-guards.json")).unwrap();
+        let reloaded = normalize_store_value(&parsed);
+        let reserialized = format!("{}\n", stringify_pretty2(&normalize_store_typed(&reloaded)));
+        assert_eq!(reserialized, read_golden_string("budget-guards.json"));
+    }
+}
diff --git a/crates/quota/src/cache.rs b/crates/quota/src/cache.rs
new file mode 100644
index 000000000..f3f516c88
--- /dev/null
+++ b/crates/quota/src/cache.rs
@@ -0,0 +1,659 @@
+//! Port of `lib/quota-cache.ts` — the on-disk persisted quota cache
+//! (`quota-cache.json`): atomic write, tolerant read.
+//!
+//! On-disk format (byte-compatibility required — golden:
+//! `crates/testkit/goldens/quota-cache.json`):
+//!
+//! ```json
+//! {
+//!   "version": 1,
+//!   "byAccountId": { "<accountId>": { ...entry... } },
+//!   "byEmail": { "<lowercased-trimmed-email>": { ...entry... } }
+//! }
+//! ```
+//!
+//! Serialization is `JSON.stringify(payload, null, 2) + "\n"` (2-space
+//! indent, trailing newline), UTF-8, file mode 0600, dir 0700.
+//!
+//! Contracts (spec 05 §3 + gotchas 9/10):
+//! - `load_quota_cache` / `save_quota_cache` NEVER return errors — failures
+//!   are logged (`log_warn`) and yield empty maps / a skipped write.
+//! - `version != 1` → warn + empty maps (no migration; old versions are
+//!   discarded).
+//! - Writes are serialized in-process (promise chain in TS; a tokio `Mutex`
+//!   here); cross-process writers can race — last rename wins, atomic rename
+//!   prevents torn files.
+//! - The staged temp file keeps its `.tmp` suffix (`temp_path_for`) for
+//!   stale-sweepers; it is unlinked (best effort) when the rename fails.
+//!
+//! Rust-specific divergence (recorded in the port log): the TS module
+//! computed `QUOTA_CACHE_PATH` ONCE at module load; the Rust port resolves it
+//! per call so `CODEX_MULTI_AUTH_DIR` test sandboxes work. In production the
+//! env does not change mid-process, so behavior is identical.
+
+use std::path::PathBuf;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::{format_js_number, stringify_pretty2};
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::temp_path::temp_path_for;
+use cma_core::utils::is_record;
+use serde::ser::SerializeMap;
+use serde::{Serialize, Serializer};
+use serde_json::Value;
+use tokio::io::AsyncWriteExt;
+
+/// `basename(QUOTA_CACHE_PATH)` — used in the frozen warn texts.
+const QUOTA_CACHE_LABEL: &str = "quota-cache.json";
+
+/// TS `QuotaCacheWindow` — every field optional; only finite numbers survive
+/// the load-side normalization. Numbers are `f64` because the TS reader
+/// accepts (and round-trips) fractional values for every field.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize)]
+pub struct QuotaCacheWindow {
+    #[serde(rename = "usedPercent", skip_serializing_if = "Option::is_none")]
+    pub used_percent: Option<f64>,
+    #[serde(rename = "windowMinutes", skip_serializing_if = "Option::is_none")]
+    pub window_minutes: Option<f64>,
+    #[serde(rename = "resetAtMs", skip_serializing_if = "Option::is_none")]
+    pub reset_at_ms: Option<f64>,
+}
+
+/// TS `QuotaCacheEntry` — serde field order == TS/JSON key order.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct QuotaCacheEntry {
+    #[serde(rename = "updatedAt")]
+    pub updated_at: f64,
+    pub status: f64,
+    pub model: String,
+    #[serde(rename = "planType", skip_serializing_if = "Option::is_none")]
+    pub plan_type: Option<String>,
+    pub primary: QuotaCacheWindow,
+    pub secondary: QuotaCacheWindow,
+}
+
+/// Insertion-ordered `Record<string, QuotaCacheEntry>` (JS object key order:
+/// replacing an existing key keeps its position; new keys append).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct QuotaCacheEntryMap {
+    entries: Vec<(String, QuotaCacheEntry)>,
+}
+
+impl QuotaCacheEntryMap {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn contains_key(&self, key: &str) -> bool {
+        self.entries.iter().any(|(k, _)| k == key)
+    }
+
+    pub fn get(&self, key: &str) -> Option<&QuotaCacheEntry> {
+        self.entries
+            .iter()
+            .find(|(k, _)| k == key)
+            .map(|(_, entry)| entry)
+    }
+
+    pub fn get_mut(&mut self, key: &str) -> Option<&mut QuotaCacheEntry> {
+        self.entries
+            .iter_mut()
+            .find(|(k, _)| k == key)
+            .map(|(_, entry)| entry)
+    }
+
+    /// JS `map[key] = entry` — replaces in place (keeping key position) or
+    /// appends. Returns the previous entry when replaced.
+    pub fn insert(
+        &mut self,
+        key: impl Into<String>,
+        entry: QuotaCacheEntry,
+    ) -> Option<QuotaCacheEntry> {
+        let key = key.into();
+        if let Some(slot) = self
+            .entries
+            .iter_mut()
+            .find(|(existing, _)| *existing == key)
+        {
+            return Some(std::mem::replace(&mut slot.1, entry));
+        }
+        self.entries.push((key, entry));
+        None
+    }
+
+    /// JS `delete map[key]`.
+    pub fn remove(&mut self, key: &str) -> Option<QuotaCacheEntry> {
+        let index = self.entries.iter().position(|(k, _)| k == key)?;
+        Some(self.entries.remove(index).1)
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&str, &QuotaCacheEntry)> {
+        self.entries
+            .iter()
+            .map(|(key, entry)| (key.as_str(), entry))
+    }
+
+    pub fn keys(&self) -> impl Iterator<Item = &str> {
+        self.entries.iter().map(|(key, _)| key.as_str())
+    }
+}
+
+impl Serialize for QuotaCacheEntryMap {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let mut map = serializer.serialize_map(Some(self.entries.len()))?;
+        for (key, entry) in &self.entries {
+            map.serialize_entry(key, entry)?;
+        }
+        map.end()
+    }
+}
+
+impl FromIterator<(String, QuotaCacheEntry)> for QuotaCacheEntryMap {
+    fn from_iter<I: IntoIterator<Item = (String, QuotaCacheEntry)>>(iter: I) -> Self {
+        let mut map = QuotaCacheEntryMap::new();
+        for (key, entry) in iter {
+            map.insert(key, entry);
+        }
+        map
+    }
+}
+
+/// TS `QuotaCacheData` — the in-memory shape callers pass around (the
+/// on-disk file additionally carries `version: 1`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct QuotaCacheData {
+    pub by_account_id: QuotaCacheEntryMap,
+    pub by_email: QuotaCacheEntryMap,
+}
+
+/// On-disk payload shape (`QuotaCacheFile` in TS) — serialized verbatim from
+/// caller data (no normalization on save; callers pass normalized data).
+#[derive(Serialize)]
+struct QuotaCacheFilePayload<'a> {
+    version: u32,
+    #[serde(rename = "byAccountId")]
+    by_account_id: &'a QuotaCacheEntryMap,
+    #[serde(rename = "byEmail")]
+    by_email: &'a QuotaCacheEntryMap,
+}
+
+/// TS `getQuotaCachePath()` — `<multi-auth-dir>/quota-cache.json`.
+pub fn get_quota_cache_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(QUOTA_CACHE_LABEL)
+}
+
+/// `10 * 2^(attempt-1)` for the 1-based failed-attempt index → 10/20/40/80 ms.
+fn cache_retry_backoff() -> Backoff {
+    Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1))))
+}
+
+/// TS `normalizeNumber` — JSON number and finite, else `None`.
+fn normalize_number(value: Option<&Value>) -> Option<f64> {
+    value?.as_f64().filter(|n| n.is_finite())
+}
+
+/// TS `normalizeWindow` — non-record → empty window.
+fn normalize_window(value: Option<&Value>) -> QuotaCacheWindow {
+    let Some(value) = value else {
+        return QuotaCacheWindow::default();
+    };
+    if !is_record(value) {
+        return QuotaCacheWindow::default();
+    }
+    QuotaCacheWindow {
+        used_percent: normalize_number(value.get("usedPercent")),
+        window_minutes: normalize_number(value.get("windowMinutes")),
+        reset_at_ms: normalize_number(value.get("resetAtMs")),
+    }
+}
+
+/// TS `normalizeEntry` — requires finite `updatedAt`/`status` and a
+/// non-empty-after-trim `model` (stored trimmed); `planType` kept only when a
+/// string (as-is, untrimmed).
+fn normalize_entry(value: &Value) -> Option<QuotaCacheEntry> {
+    if !is_record(value) {
+        return None;
+    }
+    let updated_at = normalize_number(value.get("updatedAt"))?;
+    let status = normalize_number(value.get("status"))?;
+    let model = value.get("model").and_then(Value::as_str).unwrap_or("");
+    let model = model.trim();
+    if model.is_empty() {
+        return None;
+    }
+    Some(QuotaCacheEntry {
+        updated_at,
+        status,
+        model: model.to_string(),
+        plan_type: value
+            .get("planType")
+            .and_then(Value::as_str)
+            .map(str::to_string),
+        primary: normalize_window(value.get("primary")),
+        secondary: normalize_window(value.get("secondary")),
+    })
+}
+
+/// TS `normalizeEntryMap` — non-objects, blank keys, and invalid entries are
+/// dropped; valid entries keep their ORIGINAL (untrimmed) key.
+fn normalize_entry_map(value: Option<&Value>) -> QuotaCacheEntryMap {
+    let mut entries = QuotaCacheEntryMap::new();
+    let Some(Value::Object(map)) = value else {
+        return entries;
+    };
+    for (key, raw) in map {
+        if key.trim().is_empty() {
+            continue;
+        }
+        let Some(normalized) = normalize_entry(raw) else {
+            continue;
+        };
+        entries.insert(key.clone(), normalized);
+    }
+    entries
+}
+
+/// JS `String(value)` for the version-mismatch warn (`String(undefined)` →
+/// `"undefined"`).
+fn js_string_of(value: Option<&Value>) -> String {
+    match value {
+        None => "undefined".to_string(),
+        Some(Value::Null) => "null".to_string(),
+        Some(Value::Bool(b)) => b.to_string(),
+        Some(Value::Number(n)) => format_js_number(n.as_f64().unwrap_or(f64::NAN)),
+        Some(Value::String(s)) => s.clone(),
+        Some(Value::Array(items)) => items
+            .iter()
+            .map(|item| js_string_of(Some(item)))
+            .collect::<Vec<_>>()
+            .join(","),
+        Some(Value::Object(_)) => "[object Object]".to_string(),
+    }
+}
+
+/// JS strict `parsed.version !== 1` (number `1`/`1.0` only).
+fn version_is_one(value: Option<&Value>) -> bool {
+    matches!(value, Some(Value::Number(n)) if n.as_f64() == Some(1.0))
+}
+
+async fn read_cache_file_with_retry(path: &std::path::Path) -> std::io::Result<String> {
+    // Retries the shared FILE_RETRY_CODES taxonomy (EBUSY/EPERM/EAGAIN/
+    // ENOTEMPTY/EACCES) so a transient Windows lock (AV/indexer/concurrent
+    // reader) on the quota cache is retried consistently with every other fs
+    // path, not just EBUSY/EPERM.
+    with_retry(
+        || async { tokio::fs::read_to_string(path).await },
+        RetryOptions::new(5, cache_retry_backoff()),
+    )
+    .await
+}
+
+/// TS `loadQuotaCache()` — **never fails**. Missing file, parse failures,
+/// non-object payloads, version mismatches, and I/O errors all yield empty
+/// maps (warn-logged where the TS warns).
+pub async fn load_quota_cache() -> QuotaCacheData {
+    let path = get_quota_cache_path();
+    if !path.exists() {
+        return QuotaCacheData::default();
+    }
+
+    let content = match read_cache_file_with_retry(&path).await {
+        Ok(content) => content,
+        Err(error) => {
+            log_warn(
+                &format!("Failed to load quota cache from {QUOTA_CACHE_LABEL}: {error}"),
+                None,
+            );
+            return QuotaCacheData::default();
+        }
+    };
+    let parsed: Value = match serde_json::from_str(&content) {
+        Ok(parsed) => parsed,
+        Err(error) => {
+            log_warn(
+                &format!("Failed to load quota cache from {QUOTA_CACHE_LABEL}: {error}"),
+                None,
+            );
+            return QuotaCacheData::default();
+        }
+    };
+    if !is_record(&parsed) {
+        return QuotaCacheData::default();
+    }
+    if !version_is_one(parsed.get("version")) {
+        log_warn(
+            &format!(
+                "Quota cache rejected due to version mismatch: {}",
+                js_string_of(parsed.get("version"))
+            ),
+            None,
+        );
+        return QuotaCacheData::default();
+    }
+
+    QuotaCacheData {
+        by_account_id: normalize_entry_map(parsed.get("byAccountId")),
+        by_email: normalize_entry_map(parsed.get("byEmail")),
+    }
+}
+
+/// In-process write queue (module promise chain in TS; tokio's Mutex is
+/// FIFO-fair and a failed writer never poisons the chain because the guarded
+/// section catches everything).
+static QUOTA_CACHE_WRITE_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+/// TS `saveQuotaCache(data)` — **never fails** (errors logged:
+/// `"Failed to save quota cache to quota-cache.json: {msg}"`). Atomic
+/// temp-file (`.{pid}.{epochMs}.{8hex}.tmp` via `temp_path_for`) + rename
+/// with the shared 5-attempt/10·2^(n−1) retry; temp unlinked on rename
+/// failure. Serialized by the per-process write queue.
+pub async fn save_quota_cache(data: &QuotaCacheData) {
+    let _queue = QUOTA_CACHE_WRITE_QUEUE.lock().await;
+    if let Err(message) = save_quota_cache_inner(data).await {
+        log_warn(
+            &format!("Failed to save quota cache to {QUOTA_CACHE_LABEL}: {message}"),
+            None,
+        );
+    }
+}
+
+async fn save_quota_cache_inner(data: &QuotaCacheData) -> Result<(), String> {
+    let cache_dir = get_codex_multi_auth_dir();
+    let path = cache_dir.join(QUOTA_CACHE_LABEL);
+
+    // The quota cache lives alongside other at-rest secrets, so keep the
+    // directory owner-only on POSIX (mode is a no-op on win32 / ACL-based).
+    tokio::fs::create_dir_all(&cache_dir)
+        .await
+        .map_err(|error| error.to_string())?;
+    // mkdir's mode only applies to a freshly-created dir; an upgrade with a
+    // pre-existing multi-auth dir keeps its old (possibly world-listable)
+    // perms, so re-assert 0o700 on POSIX. Best-effort: a chmod failure must
+    // not break the cache write (the 0o600 file below still protects data).
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ =
+            tokio::fs::set_permissions(&cache_dir, std::fs::Permissions::from_mode(0o700)).await;
+    }
+
+    let payload = QuotaCacheFilePayload {
+        version: 1,
+        by_account_id: &data.by_account_id,
+        by_email: &data.by_email,
+    };
+    let content = format!("{}\n", stringify_pretty2(&payload));
+
+    let temp_path = temp_path_for(&path);
+    let mut open_options = tokio::fs::OpenOptions::new();
+    open_options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        open_options.mode(0o600);
+    }
+    let write_result = async {
+        let mut file = open_options.open(&temp_path).await?;
+        file.write_all(content.as_bytes()).await?;
+        file.flush().await?;
+        Ok::<(), std::io::Error>(())
+    }
+    .await;
+    write_result.map_err(|error| error.to_string())?;
+
+    let rename_result = with_retry(
+        || async { tokio::fs::rename(&temp_path, &path).await },
+        RetryOptions::new(5, cache_retry_backoff()),
+    )
+    .await;
+    if let Err(error) = rename_result {
+        // Best effort temp cleanup.
+        let _ = tokio::fs::remove_file(&temp_path).await;
+        return Err(error.to_string());
+    }
+    Ok(())
+}
+
+// ============================================================================
+// Tests — ported from test/quota-cache.test.ts (+ golden byte round-trip)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn sample_entry() -> QuotaCacheEntry {
+        QuotaCacheEntry {
+            updated_at: 1_753_500_000_000.0,
+            status: 200.0,
+            model: "gpt-5.6-sol".to_string(),
+            plan_type: Some("plus".to_string()),
+            primary: QuotaCacheWindow {
+                used_percent: Some(12.5),
+                window_minutes: Some(300.0),
+                reset_at_ms: Some(1_753_500_000_000.0),
+            },
+            secondary: QuotaCacheWindow {
+                used_percent: Some(3.1),
+                window_minutes: Some(10_080.0),
+                reset_at_ms: Some(1_753_900_000_000.0),
+            },
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_empty_cache_by_default() {
+        let _sandbox = EnvSandbox::new();
+        let cache = load_quota_cache().await;
+        assert!(cache.by_account_id.is_empty());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn saves_and_reloads_quota_entries() {
+        let _sandbox = EnvSandbox::new();
+        let mut data = QuotaCacheData::default();
+        data.by_account_id.insert("acc_quota", sample_entry());
+        data.by_email.insert("quota@example.com", sample_entry());
+        save_quota_cache(&data).await;
+
+        let reloaded = load_quota_cache().await;
+        assert_eq!(reloaded, data);
+        assert_eq!(
+            reloaded
+                .by_account_id
+                .get("acc_quota")
+                .map(|entry| entry.model.as_str()),
+            Some("gpt-5.6-sol")
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn stages_atomic_writes_through_temp_path_and_leaves_no_tmp_behind() {
+        let sandbox = EnvSandbox::new();
+        let mut data = QuotaCacheData::default();
+        data.by_account_id.insert("acc_quota", sample_entry());
+        save_quota_cache(&data).await;
+
+        assert!(get_quota_cache_path().exists());
+        let leftovers: Vec<_> = std::fs::read_dir(sandbox.codex_multi_auth_dir())
+            .unwrap()
+            .filter_map(|entry| entry.ok())
+            .map(|entry| entry.file_name().to_string_lossy().to_string())
+            .filter(|name| name.ends_with(".tmp"))
+            .collect();
+        assert!(leftovers.is_empty(), "stale temp files: {leftovers:?}");
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    #[serial(env)]
+    async fn keeps_the_cache_directory_owner_only_on_posix() {
+        use std::os::unix::fs::PermissionsExt;
+        let sandbox = EnvSandbox::new();
+        // Pre-create with loose perms so the save must re-assert 0o700.
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::set_permissions(
+            sandbox.codex_multi_auth_dir(),
+            std::fs::Permissions::from_mode(0o755),
+        )
+        .unwrap();
+        let mut data = QuotaCacheData::default();
+        data.by_account_id.insert("acc_quota", sample_entry());
+        save_quota_cache(&data).await;
+        let mode = std::fs::metadata(sandbox.codex_multi_auth_dir())
+            .unwrap()
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o777, 0o700);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn ignores_cache_files_with_unsupported_version() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(
+            get_quota_cache_path(),
+            "{\"version\":2,\"byAccountId\":{\"acc\":{\"updatedAt\":1,\"status\":200,\"model\":\"m\",\"primary\":{},\"secondary\":{}}},\"byEmail\":{}}",
+        )
+        .unwrap();
+        let cache = load_quota_cache().await;
+        assert!(cache.by_account_id.is_empty());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_empty_cache_when_parsed_payload_is_not_an_object() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_quota_cache_path(), "[1, 2, 3]").unwrap();
+        let cache = load_quota_cache().await;
+        assert!(cache.by_account_id.is_empty());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn returns_empty_cache_on_malformed_json() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_quota_cache_path(), "{oops").unwrap();
+        let cache = load_quota_cache().await;
+        assert!(cache.by_account_id.is_empty());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn normalizes_mixed_valid_and_invalid_cached_entries() {
+        let sandbox = EnvSandbox::new();
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        let raw = r#"{
+  "version": 1,
+  "byAccountId": {
+    "good": {
+      "updatedAt": 1753500000000,
+      "status": 200,
+      "model": "  gpt-5.6-sol  ",
+      "planType": "plus",
+      "primary": { "usedPercent": 12.5, "windowMinutes": "nope", "resetAtMs": 1753500000000 },
+      "secondary": "not-a-window"
+    },
+    "missing-model": {
+      "updatedAt": 1753500000000,
+      "status": 200,
+      "model": "   ",
+      "primary": {},
+      "secondary": {}
+    },
+    "bad-updated-at": {
+      "updatedAt": "soon",
+      "status": 200,
+      "model": "gpt-5.5",
+      "primary": {},
+      "secondary": {}
+    },
+    "   ": {
+      "updatedAt": 1753500000000,
+      "status": 200,
+      "model": "gpt-5.5",
+      "primary": {},
+      "secondary": {}
+    },
+    "not-a-record": 42
+  },
+  "byEmail": "not-an-object"
+}"#;
+        std::fs::write(get_quota_cache_path(), raw).unwrap();
+
+        let cache = load_quota_cache().await;
+        assert_eq!(cache.by_account_id.len(), 1);
+        let good = cache.by_account_id.get("good").expect("good entry kept");
+        // Model stored trimmed; non-finite / non-number window values dropped.
+        assert_eq!(good.model, "gpt-5.6-sol");
+        assert_eq!(good.plan_type.as_deref(), Some("plus"));
+        assert_eq!(good.primary.used_percent, Some(12.5));
+        assert_eq!(good.primary.window_minutes, None);
+        assert_eq!(good.primary.reset_at_ms, Some(1_753_500_000_000.0));
+        assert_eq!(good.secondary, QuotaCacheWindow::default());
+        assert!(cache.by_email.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn serializes_concurrent_saves_so_the_last_write_wins() {
+        let _sandbox = EnvSandbox::new();
+        let mut first = QuotaCacheData::default();
+        first.by_account_id.insert("first", sample_entry());
+        let mut second = QuotaCacheData::default();
+        second.by_account_id.insert("second", sample_entry());
+
+        let (first_done, second_done) =
+            tokio::join!(save_quota_cache(&first), save_quota_cache(&second));
+        let _ = (first_done, second_done);
+
+        // Whatever order the queue picked, the final file is a VALID cache
+        // (never torn) containing exactly one of the two payloads.
+        let reloaded = load_quota_cache().await;
+        assert_eq!(reloaded.by_account_id.len(), 1);
+        assert!(
+            reloaded.by_account_id.contains_key("first")
+                || reloaded.by_account_id.contains_key("second")
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn golden_byte_round_trip() {
+        let sandbox = EnvSandbox::new();
+        let golden_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("../testkit/goldens/quota-cache.json");
+        let golden = std::fs::read_to_string(&golden_path).expect("golden fixture");
+        std::fs::create_dir_all(sandbox.codex_multi_auth_dir()).unwrap();
+        std::fs::write(get_quota_cache_path(), &golden).unwrap();
+
+        let loaded = load_quota_cache().await;
+        assert_eq!(loaded.by_account_id.len(), 2);
+        assert_eq!(loaded.by_email.len(), 2);
+
+        save_quota_cache(&loaded).await;
+        let rewritten = std::fs::read_to_string(get_quota_cache_path()).unwrap();
+        assert_eq!(rewritten, golden, "quota-cache.json byte round-trip");
+    }
+}
diff --git a/crates/quota/src/forecast.rs b/crates/quota/src/forecast.rs
new file mode 100644
index 000000000..e63311292
--- /dev/null
+++ b/crates/quota/src/forecast.rs
@@ -0,0 +1,1723 @@
+//! Port of `lib/forecast.ts` — PURE account-availability forecasting, risk
+//! scoring, and recommendation. No I/O, no env.
+//!
+//! H5 rules (stress audit, spec 05 gotchas 2/4/5):
+//! - On a 200 probe under usage pressure, only actually-exhausted windows
+//!   (RAW `usedPercent >= 100`) contribute waits — a healthy weekly window's
+//!   ~7d reset must never inflate `waitMs`. On a 429 every future window
+//!   counts.
+//! - A live window at 100% used with NO `resetAtMs` ⇒ `exhausted = true`
+//!   (ready → delayed) even on a 200.
+//! - Quota-exhausted accounts are classified `"delayed"` for display/sorting
+//!   but carry `exhausted: true` and are EXCLUDED from the recommendation:
+//!   an all-exhausted pool returns the null recommendation, never a bogus
+//!   "pick shortest wait".
+
+use std::collections::HashMap;
+
+use cma_accounts::manager_persistence::{AccountLabelSource, format_account_label};
+use cma_accounts::rate_limits::format_wait_time;
+use cma_core::schemas::account_storage::AccountMetadataV3;
+use cma_core::schemas::token::TokenFailure;
+use serde::Serialize;
+
+use crate::cache::QuotaCacheData;
+use crate::probe::CodexQuotaSnapshot;
+use crate::readiness::{
+    find_quota_cache_entry_for_account, is_quota_cache_entry_exhausted,
+    quota_used_percent_is_exhausted,
+};
+
+/// TS `ForecastAvailability = "ready" | "delayed" | "unavailable"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ForecastAvailability {
+    Ready,
+    Delayed,
+    Unavailable,
+}
+
+impl ForecastAvailability {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ForecastAvailability::Ready => "ready",
+            ForecastAvailability::Delayed => "delayed",
+            ForecastAvailability::Unavailable => "unavailable",
+        }
+    }
+
+    /// Sort rank: ready=0, delayed=1, unavailable=2.
+    const fn rank(self) -> u8 {
+        match self {
+            ForecastAvailability::Ready => 0,
+            ForecastAvailability::Delayed => 1,
+            ForecastAvailability::Unavailable => 2,
+        }
+    }
+}
+
+impl std::fmt::Display for ForecastAvailability {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// TS `ForecastRiskLevel = "low" | "medium" | "high"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ForecastRiskLevel {
+    Low,
+    Medium,
+    High,
+}
+
+impl ForecastRiskLevel {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ForecastRiskLevel::Low => "low",
+            ForecastRiskLevel::Medium => "medium",
+            ForecastRiskLevel::High => "high",
+        }
+    }
+}
+
+impl std::fmt::Display for ForecastRiskLevel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// TS `RuntimeForecastOverlay` — persisted runtime-observability skip-reason
+/// maps keyed by `String(index)` plus the policy-blocked index list.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RuntimeForecastOverlay {
+    pub account_skip_reasons: HashMap<String, String>,
+    pub last_pool_exhaustion_skip_reasons: HashMap<String, String>,
+    pub policy_blocked_indexes: Vec<usize>,
+}
+
+/// TS `ForecastAccountInput`.
+#[derive(Clone, Copy, Debug)]
+pub struct ForecastAccountInput<'a> {
+    pub index: usize,
+    pub account: &'a AccountMetadataV3,
+    pub is_current: bool,
+    /// Caller-supplied clock (epoch ms).
+    pub now: i64,
+    pub refresh_failure: Option<&'a TokenFailure>,
+    pub live_quota: Option<&'a CodexQuotaSnapshot>,
+    pub quota_cache: Option<&'a QuotaCacheData>,
+    /// Defaults to `[account]` when absent.
+    pub all_accounts: Option<&'a [AccountMetadataV3]>,
+    pub runtime_overlay: Option<&'a RuntimeForecastOverlay>,
+}
+
+impl<'a> ForecastAccountInput<'a> {
+    /// Minimal input (everything optional unset) — mirrors the TS object
+    /// literal with only the required fields.
+    pub fn new(index: usize, account: &'a AccountMetadataV3, is_current: bool, now: i64) -> Self {
+        ForecastAccountInput {
+            index,
+            account,
+            is_current,
+            now,
+            refresh_failure: None,
+            live_quota: None,
+            quota_cache: None,
+            all_accounts: None,
+            runtime_overlay: None,
+        }
+    }
+}
+
+/// TS `ForecastAccountResult`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ForecastAccountResult {
+    pub index: usize,
+    /// `redactEmails(formatAccountLabel(account, index))`.
+    pub label: String,
+    pub is_current: bool,
+    pub availability: ForecastAvailability,
+    /// Clamped int 0..=100.
+    pub risk_score: i64,
+    pub risk_level: ForecastRiskLevel,
+    /// `Math.max(0, Math.floor(waitMs))`.
+    pub wait_ms: i64,
+    pub reasons: Vec<String>,
+    pub hard_failure: bool,
+    pub disabled: bool,
+    /// Blocked solely by quota exhaustion; classified "delayed" but never
+    /// recommendable.
+    pub exhausted: bool,
+}
+
+/// TS `ForecastRecommendation`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ForecastRecommendation {
+    pub recommended_index: Option<usize>,
+    pub reason: String,
+}
+
+/// One `considered` row of [`ForecastExplanation`].
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ForecastExplanationAccount {
+    pub index: usize,
+    pub label: String,
+    pub is_current: bool,
+    pub availability: ForecastAvailability,
+    pub risk_score: i64,
+    pub risk_level: ForecastRiskLevel,
+    pub wait_ms: i64,
+    pub reasons: Vec<String>,
+    pub selected: bool,
+}
+
+/// TS `ForecastExplanation`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ForecastExplanation {
+    pub recommended_index: Option<usize>,
+    pub recommendation_reason: String,
+    pub considered: Vec<ForecastExplanationAccount>,
+}
+
+/// TS `ForecastSummary`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ForecastSummary {
+    pub total: usize,
+    pub ready: usize,
+    pub delayed: usize,
+    pub unavailable: usize,
+    pub high_risk: usize,
+}
+
+// ---------------------------------------------------------------------------
+// Redaction helpers (private but behavior-critical for output strings)
+// ---------------------------------------------------------------------------
+
+/// forecast.ts's OWN `maskEmail` — `atIndex <= 0` masks fully and the tld
+/// fallback is `"***"`. Deliberately different from logger.ts's variant
+/// (`atIndex < 0`, empty tld fallback) — do not unify (spec 05 gotcha 15).
+fn mask_email(value: &str) -> String {
+    let Some(at_index) = value.find('@') else {
+        return "***@***".to_string();
+    };
+    if at_index == 0 {
+        return "***@***".to_string();
+    }
+    let local = &value[..at_index];
+    let domain = &value[at_index + 1..];
+    // JS `domain.split(".").pop()` — the last dot segment (the whole domain
+    // when it has no dot; `""` for an empty domain).
+    let tld = domain.rsplit('.').next().unwrap_or("");
+    let prefix: String = local.chars().take(2).collect();
+    let tld = if tld.is_empty() { "***" } else { tld };
+    format!("{prefix}***@***.{tld}")
+}
+
+fn is_email_local_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '%' | '+' | '-')
+}
+
+fn is_email_domain_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || matches!(c, '.' | '-')
+}
+
+/// Hand-rolled equivalent of the JS global regex
+/// `/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g` with each match
+/// replaced by [`mask_email`] (the `regex` crate is not a cma-quota
+/// dependency; the charset is ASCII-only so a scanner reproduces the
+/// leftmost-greedy semantics exactly).
+fn redact_emails(value: &str) -> String {
+    let chars: Vec<char> = value.chars().collect();
+    let mut out = String::with_capacity(value.len());
+    let mut scan_from = 0usize; // chars at < scan_from are already emitted
+    let mut i = 0usize;
+    while i < chars.len() {
+        if chars[i] != '@' {
+            i += 1;
+            continue;
+        }
+        // Local part: maximal run of local chars ending right before the '@'
+        // (must not reach into already-consumed output).
+        let mut local_start = i;
+        while local_start > scan_from && is_email_local_char(chars[local_start - 1]) {
+            local_start -= 1;
+        }
+        if local_start == i {
+            i += 1;
+            continue; // no local part → no match at this '@'
+        }
+        // Domain run after '@'.
+        let run_start = i + 1;
+        let mut run_end = run_start;
+        while run_end < chars.len() && is_email_domain_char(chars[run_end]) {
+            run_end += 1;
+        }
+        if run_end == run_start {
+            i += 1;
+            continue;
+        }
+        // Greedy domain with backtracking: the RIGHTMOST '.' inside the run
+        // that (a) leaves a non-empty domain part before it and (b) is
+        // followed by >= 2 ASCII letters. The tld is the maximal letter run
+        // after that dot (the match may end before run_end, e.g. "b.comx2").
+        let mut match_end: Option<usize> = None;
+        for d in (run_start + 1..run_end).rev() {
+            if chars[d] != '.' {
+                continue;
+            }
+            let mut t_end = d + 1;
+            while t_end < run_end && chars[t_end].is_ascii_alphabetic() {
+                t_end += 1;
+            }
+            if t_end - (d + 1) >= 2 {
+                match_end = Some(t_end);
+                break;
+            }
+        }
+        let Some(match_end) = match_end else {
+            i += 1;
+            continue;
+        };
+        // Emit the unmatched prefix, then the masked match.
+        out.extend(&chars[scan_from..local_start]);
+        let matched: String = chars[local_start..match_end].iter().collect();
+        out.push_str(&mask_email(&matched));
+        scan_from = match_end;
+        i = match_end;
+    }
+    out.extend(&chars[scan_from..]);
+    out
+}
+
+/// Hand-rolled `/Bearer\s+\S+/gi` → `"Bearer ***"`.
+fn redact_bearer_tokens(value: &str) -> String {
+    let chars: Vec<char> = value.chars().collect();
+    let mut out = String::with_capacity(value.len());
+    let mut i = 0usize;
+    while i < chars.len() {
+        let is_bearer = chars.len() - i >= 6
+            && chars[i..i + 6]
+                .iter()
+                .zip("bearer".chars())
+                .all(|(c, b)| c.to_ascii_lowercase() == b);
+        if is_bearer {
+            let mut j = i + 6;
+            let ws_start = j;
+            while j < chars.len() && chars[j].is_whitespace() {
+                j += 1;
+            }
+            if j > ws_start {
+                let token_start = j;
+                while j < chars.len() && !chars[j].is_whitespace() {
+                    j += 1;
+                }
+                if j > token_start {
+                    out.push_str("Bearer ***");
+                    i = j;
+                    continue;
+                }
+            }
+        }
+        out.push(chars[i]);
+        i += 1;
+    }
+    out
+}
+
+/// Hand-rolled `/\b(sk-[A-Za-z0-9]{10,})\b/g` → `"***"` (JS word chars are
+/// `[A-Za-z0-9_]`; a trailing `_` breaks the closing `\b`).
+fn redact_sk_tokens(value: &str) -> String {
+    let chars: Vec<char> = value.chars().collect();
+    let mut out = String::with_capacity(value.len());
+    let mut i = 0usize;
+    let is_word = |c: char| c.is_ascii_alphanumeric() || c == '_';
+    while i < chars.len() {
+        let starts_sk =
+            chars.len() - i >= 3 && chars[i] == 's' && chars[i + 1] == 'k' && chars[i + 2] == '-';
+        let boundary_before = i == 0 || !is_word(chars[i - 1]);
+        if starts_sk && boundary_before {
+            let mut j = i + 3;
+            while j < chars.len() && chars[j].is_ascii_alphanumeric() {
+                j += 1;
+            }
+            let run_len = j - (i + 3);
+            let boundary_after = j >= chars.len() || !is_word(chars[j]);
+            if run_len >= 10 && boundary_after {
+                out.push_str("***");
+                i = j;
+                continue;
+            }
+        }
+        out.push(chars[i]);
+        i += 1;
+    }
+    out
+}
+
+/// TS `redactSensitiveReason` — Bearer tokens, `sk-` keys, then emails.
+fn redact_sensitive_reason(value: &str) -> String {
+    redact_emails(&redact_sk_tokens(&redact_bearer_tokens(value)))
+}
+
+/// TS `summarizeRefreshFailure` — reason code (plus `" (status)"`) wins;
+/// otherwise the redacted message (or `"refresh failed"`) capped at 160.
+fn summarize_refresh_failure(failure: &TokenFailure) -> String {
+    if let Some(reason) = &failure.reason {
+        let status_code = match failure.status_code {
+            Some(status) => format!(" ({status})"),
+            None => String::new(),
+        };
+        return format!("{}{status_code}", reason.as_str());
+    }
+    let fallback = failure
+        .message
+        .as_deref()
+        .map(str::trim)
+        .filter(|message| !message.is_empty())
+        .unwrap_or("refresh failed");
+    redact_sensitive_reason(fallback)
+        .chars()
+        .take(160)
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Scoring helpers
+// ---------------------------------------------------------------------------
+
+/// TS `clampRisk` — `max(0, min(100, round(score)))` (i64 scores are always
+/// finite integers; the TS non-finite → 100 branch is unreachable here).
+fn clamp_risk(score: i64) -> i64 {
+    score.clamp(0, 100)
+}
+
+/// TS `getRiskLevel` — `>= 75` high, `>= 40` medium, else low.
+fn get_risk_level(score: i64) -> ForecastRiskLevel {
+    if score >= 75 {
+        ForecastRiskLevel::High
+    } else if score >= 40 {
+        ForecastRiskLevel::Medium
+    } else {
+        ForecastRiskLevel::Low
+    }
+}
+
+/// Local port of `getRateLimitResetTimeForFamily(account, now, "codex")`
+/// (TS `lib/runtime/account-status.ts` — that module lands in `cma-runtime`,
+/// which sits ABOVE this crate in the DAG, so forecast carries its own copy):
+/// minimum strictly-future value among `rateLimitResetTimes` entries whose
+/// key is exactly the family or starts with `"{family}:"`.
+fn rate_limit_reset_time_for_codex_family(account: &AccountMetadataV3, now: i64) -> Option<i64> {
+    let times = account.rate_limit_reset_times.as_ref()?;
+    let mut min_reset: Option<i64> = None;
+    for (key, value) in times.iter() {
+        if value <= now {
+            continue;
+        }
+        if key != "codex" && !key.starts_with("codex:") {
+            continue;
+        }
+        if min_reset.is_none_or(|current| value < current) {
+            min_reset = Some(value);
+        }
+    }
+    min_reset
+}
+
+/// TS `getLiveQuotaWaitMs(snapshot, now, onlyExhausted)`.
+///
+/// Under pure usage pressure (not a 429), only an actually-exhausted window
+/// (100% used, RAW) imposes a wait — a healthy weekly secondary normally
+/// resets ~7d out; folding that in would overstate the wait by orders of
+/// magnitude and invert the recommendation (stress audit H5). On a 429 every
+/// future window is honored.
+fn get_live_quota_wait_ms(snapshot: &CodexQuotaSnapshot, now: i64, only_exhausted: bool) -> i64 {
+    let mut max_wait: Option<i64> = None;
+    for window in [&snapshot.primary, &snapshot.secondary] {
+        if only_exhausted && !quota_used_percent_is_exhausted(window.used_percent) {
+            continue;
+        }
+        let Some(reset_at) = window.reset_at_ms else {
+            continue;
+        };
+        let remaining = reset_at - now;
+        if remaining > 0 && max_wait.is_none_or(|current| remaining > current) {
+            max_wait = Some(remaining);
+        }
+    }
+    max_wait.unwrap_or(0)
+}
+
+/// TS `describeQuotaUsage` — `"{label} quota {bounded}% used"` with the
+/// bounded ROUNDED percent (display only).
+fn describe_quota_usage(label: &str, used_percent: Option<f64>) -> Option<String> {
+    let used = used_percent?;
+    if !used.is_finite() {
+        return None;
+    }
+    let bounded = used.round().clamp(0.0, 100.0) as i64;
+    Some(format!("{label} quota {bounded}% used"))
+}
+
+/// TS `isHardRefreshFailure` — `missing_refresh`, 401, or a 400 whose
+/// message mentions an invalid/revoked grant.
+pub fn is_hard_refresh_failure(failure: &TokenFailure) -> bool {
+    use cma_core::schemas::token::TokenFailureReason;
+    if failure.reason == Some(TokenFailureReason::MissingRefresh) {
+        return true;
+    }
+    if failure.status_code == Some(401) {
+        return true;
+    }
+    if failure.status_code != Some(400) {
+        return false;
+    }
+    let message = failure.message.as_deref().unwrap_or("").to_lowercase();
+    message.contains("invalid_grant")
+        || message.contains("invalid refresh")
+        || message.contains("token has been revoked")
+}
+
+/// TS `appendWaitReason` — only appended when the wait is positive.
+fn append_wait_reason(reasons: &mut Vec<String>, prefix: &str, wait_ms: i64) {
+    if wait_ms <= 0 {
+        return;
+    }
+    reasons.push(format!("{prefix} {}", format_wait_time(wait_ms)));
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+
+/// TS `evaluateForecastAccount(input)` — order matters; risk deltas are
+/// additive. See the module docs for the H5 rules.
+pub fn evaluate_forecast_account(input: &ForecastAccountInput<'_>) -> ForecastAccountResult {
+    let account = input.account;
+    let index = input.index;
+    let now = input.now;
+    let mut reasons: Vec<String> = Vec::new();
+    let mut availability = ForecastAvailability::Ready;
+    let mut risk_score: i64 = if input.is_current { -5 } else { 0 };
+    let mut wait_ms: f64 = 0.0;
+    let mut hard_failure = false;
+    let mut exhausted = false;
+    // Only strict `false` disables; `undefined` is enabled.
+    let disabled = account.enabled == Some(false);
+
+    if disabled {
+        availability = ForecastAvailability::Unavailable;
+        risk_score += 95;
+        reasons.push("account is disabled".to_string());
+    }
+
+    if let Some(failure) = input.refresh_failure {
+        let hard = is_hard_refresh_failure(failure);
+        hard_failure = hard;
+        let detail = summarize_refresh_failure(failure);
+        if hard {
+            availability = ForecastAvailability::Unavailable;
+            risk_score += 90;
+            reasons.push(format!("hard auth failure: {detail}"));
+        } else {
+            risk_score += 25;
+            reasons.push(format!("refresh warning: {detail}"));
+        }
+    }
+
+    let cooling_down_active = matches!(account.cooling_down_until, Some(until) if until > now);
+    if let Some(cooling_down_until) = account.cooling_down_until
+        && cooling_down_until > now
+    {
+        let remaining = cooling_down_until - now;
+        wait_ms = wait_ms.max(remaining as f64);
+        if availability == ForecastAvailability::Ready {
+            availability = ForecastAvailability::Delayed;
+        }
+        risk_score += 45;
+        append_wait_reason(&mut reasons, "cooldown remaining", remaining);
+    }
+
+    let rate_limit_reset_at = rate_limit_reset_time_for_codex_family(account, now);
+    if let Some(reset_at) = rate_limit_reset_at {
+        let remaining = (reset_at - now).max(0);
+        wait_ms = wait_ms.max(remaining as f64);
+        if availability == ForecastAvailability::Ready {
+            availability = ForecastAvailability::Delayed;
+        }
+        risk_score += 35;
+        append_wait_reason(&mut reasons, "rate limit resets in", remaining);
+    }
+
+    let single_account = std::slice::from_ref(account);
+    let all_accounts = input.all_accounts.unwrap_or(single_account);
+    let quota_entry = find_quota_cache_entry_for_account(input.quota_cache, &account, all_accounts);
+    if is_quota_cache_entry_exhausted(quota_entry, now) {
+        // Only a window that is genuinely at/over 100% used contributes its
+        // reset time. Testing the ROUNDED left-percent instead would treat a
+        // 99.6%-used sibling as at-limit and fold its (possibly far-future)
+        // reset into the max below, overstating the wait for an account whose
+        // actually-exhausted window recovers much sooner.
+        let mut reset_ats: Vec<f64> = Vec::new();
+        if let Some(entry) = quota_entry {
+            for window in [&entry.primary, &entry.secondary] {
+                if quota_used_percent_is_exhausted(window.used_percent)
+                    && let Some(reset_at) = window.reset_at_ms
+                    && reset_at.is_finite()
+                    && reset_at > now as f64
+                {
+                    reset_ats.push(reset_at);
+                }
+            }
+        }
+        // Fallback to the CURRENT waitMs (not 0) when no window carries a
+        // usable future reset (spec 05 gotcha 22).
+        let quota_wait = if reset_ats.is_empty() {
+            wait_ms
+        } else {
+            reset_ats.iter().copied().fold(f64::MIN, f64::max) - now as f64
+        };
+        wait_ms = wait_ms.max(quota_wait);
+        if availability == ForecastAvailability::Ready {
+            availability = ForecastAvailability::Delayed;
+        }
+        exhausted = true;
+        risk_score += 60;
+        reasons.push("quota cache exhausted".to_string());
+        append_wait_reason(&mut reasons, "quota resets in", quota_wait.floor() as i64);
+    }
+
+    // Time-bounded overlay reasons ("rate-limited", "cooling-down:...") are
+    // persisted to runtime-observability.json on pool exhaustion and only
+    // ever cleared by an explicit runtime reset, never on a subsequent
+    // successful request. That leaves a stale reason on disk after the
+    // underlying window expires, so the forecast would keep marking a working
+    // account as unavailable. Cross-reference the time-aware disk state
+    // before applying: drop the overlay reason when the condition it
+    // describes is no longer active. Each reason validates only against its
+    // own backing disk state ("rate-limited" → rateLimitResetTimes,
+    // "cooling-down" → coolingDownUntil) so we never substitute a misleading
+    // reason string. Non-time-bounded reasons ("circuit-open",
+    // "token-exhausted", "policy-blocked") have no disk expiry to check and
+    // are always applied.
+    let overlay = input.runtime_overlay;
+    let index_key = index.to_string();
+    let overlay_reason: Option<&str> = overlay.and_then(|overlay| {
+        overlay
+            .account_skip_reasons
+            .get(&index_key)
+            .or_else(|| overlay.last_pool_exhaustion_skip_reasons.get(&index_key))
+            .map(String::as_str)
+    });
+    let is_stale_overlay_reason = match overlay_reason {
+        Some("rate-limited") => rate_limit_reset_at.is_none(),
+        Some(reason) if reason.starts_with("cooling-down") => !cooling_down_active,
+        _ => false,
+    };
+    if overlay.is_some_and(|overlay| overlay.policy_blocked_indexes.contains(&index)) {
+        availability = ForecastAvailability::Unavailable;
+        risk_score += 95;
+        reasons.push("runtime policy blocked account".to_string());
+    } else if let Some(reason) = overlay_reason
+        // JS truthiness gate (`overlayReason && ...`): an empty-string reason
+        // is falsy in TS and must leave the account Ready.
+        && !reason.is_empty()
+        && reason != "already-attempted"
+        && !is_stale_overlay_reason
+    {
+        availability = ForecastAvailability::Unavailable;
+        risk_score += match reason {
+            "circuit-open" => 90,
+            "token-exhausted" => 70,
+            _ => 50,
+        };
+        reasons.push(format!("runtime skip: {reason}"));
+    }
+
+    if let Some(quota) = input.live_quota {
+        let primary_used = quota.primary.used_percent.unwrap_or(0.0);
+        let secondary_used = quota.secondary.used_percent.unwrap_or(0.0);
+        let quota_pressure = quota.status == 429 || primary_used >= 90.0 || secondary_used >= 90.0;
+
+        if quota.status == 429 {
+            if availability != ForecastAvailability::Unavailable {
+                availability = ForecastAvailability::Delayed;
+            }
+            risk_score += 35;
+            reasons.push("live probe returned 429".to_string());
+        }
+        let live_wait = if quota_pressure {
+            get_live_quota_wait_ms(quota, now, quota.status != 429)
+        } else {
+            0
+        };
+        wait_ms = wait_ms.max(live_wait as f64);
+        if live_wait > 0 && availability == ForecastAvailability::Ready {
+            availability = ForecastAvailability::Delayed;
+        }
+
+        // A live window at 100% used with NO resetAtMs has no known recovery
+        // time — on a 200 probe getLiveQuotaWaitMs yields 0 and the 429
+        // branch never fires, so without this the account would stay "ready"
+        // and be recommended as a healthy pick. A window WITH a resetAtMs is
+        // only *delayed*, not exhausted. The raw-usedPercent test keeps 99.6%
+        // from being falsely benched.
+        let live_exhausted = (quota_used_percent_is_exhausted(quota.primary.used_percent)
+            && quota.primary.reset_at_ms.is_none())
+            || (quota_used_percent_is_exhausted(quota.secondary.used_percent)
+                && quota.secondary.reset_at_ms.is_none());
+        if live_exhausted {
+            exhausted = true;
+            if availability == ForecastAvailability::Ready {
+                availability = ForecastAvailability::Delayed;
+            }
+        }
+
+        if let Some(usage) = describe_quota_usage("primary", quota.primary.used_percent) {
+            reasons.push(usage);
+        }
+        if let Some(usage) = describe_quota_usage("secondary", quota.secondary.used_percent) {
+            reasons.push(usage);
+        }
+
+        if primary_used >= 98.0 || secondary_used >= 98.0 {
+            risk_score += 55;
+        } else if primary_used >= 90.0 || secondary_used >= 90.0 {
+            risk_score += 35;
+        } else if primary_used >= 80.0 || secondary_used >= 80.0 {
+            risk_score += 20;
+        } else if primary_used >= 70.0 || secondary_used >= 70.0 {
+            risk_score += 10;
+        }
+    }
+
+    // Staleness: `lastUsed` in the future (negative age) → +5; older than
+    // 7 days → +10. `lastUsed <= 0` means "never" — no penalty at all.
+    let has_last_used = account.last_used > 0;
+    if has_last_used {
+        let last_used_age = now - account.last_used;
+        if last_used_age < 0 {
+            risk_score += 5;
+        } else if last_used_age > 7 * 24 * 60 * 60 * 1000 {
+            risk_score += 10;
+        }
+    }
+
+    let final_risk = clamp_risk(risk_score);
+    ForecastAccountResult {
+        index,
+        label: redact_emails(&format_account_label(
+            Some(account as &dyn AccountLabelSource),
+            index,
+        )),
+        is_current: input.is_current,
+        availability,
+        risk_score: final_risk,
+        risk_level: get_risk_level(final_risk),
+        wait_ms: (wait_ms.floor() as i64).max(0),
+        reasons,
+        hard_failure,
+        disabled,
+        exhausted,
+    }
+}
+
+/// TS `evaluateForecastAccounts(inputs)` — simple map.
+pub fn evaluate_forecast_accounts(
+    inputs: &[ForecastAccountInput<'_>],
+) -> Vec<ForecastAccountResult> {
+    inputs.iter().map(evaluate_forecast_account).collect()
+}
+
+/// TS `compareForecastResults` — availability rank, then (both-delayed)
+/// ascending wait, then ascending risk, current-first, ascending index.
+fn compare_forecast_results(
+    a: &ForecastAccountResult,
+    b: &ForecastAccountResult,
+) -> std::cmp::Ordering {
+    use std::cmp::Ordering;
+    let rank = a.availability.rank().cmp(&b.availability.rank());
+    if rank != Ordering::Equal {
+        return rank;
+    }
+    if a.availability == ForecastAvailability::Delayed
+        && b.availability == ForecastAvailability::Delayed
+        && a.wait_ms != b.wait_ms
+    {
+        return a.wait_ms.cmp(&b.wait_ms);
+    }
+    if a.risk_score != b.risk_score {
+        return a.risk_score.cmp(&b.risk_score);
+    }
+    if a.is_current != b.is_current {
+        return if a.is_current {
+            Ordering::Less
+        } else {
+            Ordering::Greater
+        };
+    }
+    a.index.cmp(&b.index)
+}
+
+/// TS `recommendForecastAccount(results)`.
+///
+/// Excludes disabled, hard-failed, `exhausted`, and unavailable accounts —
+/// an all-exhausted pool returns the null recommendation, never a bogus
+/// "shortest wait" pick.
+pub fn recommend_forecast_account(results: &[ForecastAccountResult]) -> ForecastRecommendation {
+    let candidates: Vec<&ForecastAccountResult> = results
+        .iter()
+        .filter(|result| {
+            !result.disabled
+                && !result.hard_failure
+                && !result.exhausted
+                && result.availability != ForecastAvailability::Unavailable
+        })
+        .collect();
+    if candidates.is_empty() {
+        // Distinguish "blocked/exhausted" accounts (unavailable but neither
+        // disabled nor hard-failed, or quota-exhausted "delayed" ones) from
+        // disabled/hard-failed pools so the guidance matches the blocker.
+        let has_blocked_or_exhausted = results.iter().any(|result| {
+            !result.disabled
+                && !result.hard_failure
+                && (result.exhausted || result.availability == ForecastAvailability::Unavailable)
+        });
+        return ForecastRecommendation {
+            recommended_index: None,
+            reason: if has_blocked_or_exhausted {
+                "All accounts are blocked or exhausted. Wait for a reset, clear the block, or run `codex-multi-auth login` to add a fresh account.".to_string()
+            } else {
+                "No healthy accounts are available. Run `codex-multi-auth login` to add a fresh account.".to_string()
+            },
+        };
+    }
+
+    let mut sorted = candidates;
+    sorted.sort_by(|a, b| compare_forecast_results(a, b));
+    let Some(best) = sorted.first() else {
+        // Defensive branch (unreachable in practice — mirrors the TS).
+        return ForecastRecommendation {
+            recommended_index: None,
+            reason: "No recommendation available.".to_string(),
+        };
+    };
+
+    if best.availability == ForecastAvailability::Ready {
+        return ForecastRecommendation {
+            recommended_index: Some(best.index),
+            reason: format!(
+                "Lowest risk ready account ({}, score {}).",
+                best.risk_level, best.risk_score
+            ),
+        };
+    }
+
+    ForecastRecommendation {
+        recommended_index: Some(best.index),
+        reason: format!(
+            "No account is immediately ready; pick shortest wait ({}).",
+            format_wait_time(best.wait_ms)
+        ),
+    }
+}
+
+/// TS `summarizeForecast(results)`.
+pub fn summarize_forecast(results: &[ForecastAccountResult]) -> ForecastSummary {
+    ForecastSummary {
+        total: results.len(),
+        ready: results
+            .iter()
+            .filter(|result| result.availability == ForecastAvailability::Ready)
+            .count(),
+        delayed: results
+            .iter()
+            .filter(|result| result.availability == ForecastAvailability::Delayed)
+            .count(),
+        unavailable: results
+            .iter()
+            .filter(|result| result.availability == ForecastAvailability::Unavailable)
+            .count(),
+        high_risk: results
+            .iter()
+            .filter(|result| result.risk_level == ForecastRiskLevel::High)
+            .count(),
+    }
+}
+
+/// TS `buildForecastExplanation(results, recommendation)` —
+/// `selected = recommendation.recommendedIndex === result.index`.
+pub fn build_forecast_explanation(
+    results: &[ForecastAccountResult],
+    recommendation: &ForecastRecommendation,
+) -> ForecastExplanation {
+    ForecastExplanation {
+        recommended_index: recommendation.recommended_index,
+        recommendation_reason: recommendation.reason.clone(),
+        considered: results
+            .iter()
+            .map(|result| ForecastExplanationAccount {
+                index: result.index,
+                label: result.label.clone(),
+                is_current: result.is_current,
+                availability: result.availability,
+                risk_score: result.risk_score,
+                risk_level: result.risk_level,
+                wait_ms: result.wait_ms,
+                reasons: result.reasons.clone(),
+                selected: recommendation.recommended_index == Some(result.index),
+            })
+            .collect(),
+    }
+}
+
+// ============================================================================
+// Tests — ported from test/forecast.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cache::{QuotaCacheEntry, QuotaCacheWindow};
+    use crate::probe::CodexQuotaWindow;
+    use cma_core::schemas::account_storage::RateLimitStateV3;
+    use cma_core::schemas::token::TokenFailureReason;
+
+    const NOW: i64 = 1_700_000_000_000;
+
+    fn account(now: i64) -> AccountMetadataV3 {
+        AccountMetadataV3::new("refresh-1", now - 10_000, now - 10_000)
+    }
+
+    fn failure(
+        reason: Option<TokenFailureReason>,
+        status_code: Option<i64>,
+        message: Option<&str>,
+    ) -> TokenFailure {
+        TokenFailure {
+            reason,
+            status_code,
+            message: message.map(str::to_string),
+        }
+    }
+
+    fn live_quota(
+        status: u16,
+        primary: CodexQuotaWindow,
+        secondary: CodexQuotaWindow,
+    ) -> CodexQuotaSnapshot {
+        CodexQuotaSnapshot {
+            status,
+            plan_type: None,
+            active_limit: None,
+            primary,
+            secondary,
+            model: "gpt-5-codex".to_string(),
+        }
+    }
+
+    fn live_window(used_percent: Option<f64>, reset_at_ms: Option<i64>) -> CodexQuotaWindow {
+        CodexQuotaWindow {
+            used_percent,
+            window_minutes: None,
+            reset_at_ms,
+        }
+    }
+
+    fn exhausted_cache(account_id: &str, entry: QuotaCacheEntry) -> QuotaCacheData {
+        let mut cache = QuotaCacheData::default();
+        cache.by_account_id.insert(account_id, entry);
+        cache
+    }
+
+    fn cache_entry(primary: QuotaCacheWindow, secondary: QuotaCacheWindow) -> QuotaCacheEntry {
+        QuotaCacheEntry {
+            updated_at: NOW as f64,
+            status: 200.0,
+            model: "gpt-5.3-codex".to_string(),
+            plan_type: None,
+            primary,
+            secondary,
+        }
+    }
+
+    fn cache_window(used_percent: Option<f64>, reset_at_ms: Option<f64>) -> QuotaCacheWindow {
+        QuotaCacheWindow {
+            used_percent,
+            window_minutes: None,
+            reset_at_ms,
+        }
+    }
+
+    #[test]
+    fn marks_disabled_account_as_unavailable_high_risk() {
+        let mut meta = AccountMetadataV3::new("refresh-1", NOW - 1_000, NOW - 1_000);
+        meta.enabled = Some(false);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &meta, false, NOW));
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+        assert_eq!(result.risk_level, ForecastRiskLevel::High);
+        assert!(result.disabled);
+    }
+
+    #[test]
+    fn detects_hard_refresh_failures() {
+        assert!(is_hard_refresh_failure(&failure(
+            Some(TokenFailureReason::MissingRefresh),
+            None,
+            None
+        )));
+        assert!(is_hard_refresh_failure(&failure(
+            Some(TokenFailureReason::HttpError),
+            Some(400),
+            Some("invalid_grant: token revoked")
+        )));
+        assert!(!is_hard_refresh_failure(&failure(
+            Some(TokenFailureReason::NetworkError),
+            None,
+            Some("timeout")
+        )));
+    }
+
+    #[test]
+    fn raises_risk_when_live_quota_usage_is_very_high() {
+        let meta = account(NOW);
+        let quota = live_quota(
+            200,
+            live_window(Some(95.0), None),
+            live_window(Some(20.0), None),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, true, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert!(result.risk_score >= 30);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|reason| reason.contains("primary quota"))
+        );
+    }
+
+    #[test]
+    fn marks_quota_cache_exhausted_accounts_as_delayed_instead_of_ready() {
+        let mut meta = account(NOW);
+        meta.email = Some("quota@example.com".to_string());
+        meta.account_id = Some("acc_quota".to_string());
+        let cache = exhausted_cache(
+            "acc_quota",
+            cache_entry(
+                cache_window(Some(100.0), Some((NOW + 60_000) as f64)),
+                cache_window(Some(25.0), Some((NOW + 300_000) as f64)),
+            ),
+        );
+        let all = vec![meta.clone()];
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.quota_cache = Some(&cache);
+        input.all_accounts = Some(&all);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 60_000);
+        assert!(result.reasons.iter().any(|r| r == "quota cache exhausted"));
+        assert!(result.exhausted);
+    }
+
+    #[test]
+    fn waits_for_the_later_quota_reset_when_both_cached_windows_are_exhausted() {
+        let mut meta = account(NOW);
+        meta.email = Some("quota@example.com".to_string());
+        meta.account_id = Some("acc_quota".to_string());
+        let cache = exhausted_cache(
+            "acc_quota",
+            cache_entry(
+                cache_window(Some(100.0), Some((NOW + 60_000) as f64)),
+                cache_window(Some(100.0), Some((NOW + 300_000) as f64)),
+            ),
+        );
+        let all = vec![meta.clone()];
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.quota_cache = Some(&cache);
+        input.all_accounts = Some(&all);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 300_000);
+        assert!(result.reasons.iter().any(|r| r == "quota cache exhausted"));
+        assert!(result.reasons.iter().any(|r| r == "quota resets in 5m 0s"));
+    }
+
+    #[test]
+    fn ignores_a_99_6_used_sibling_window_when_computing_the_exhausted_wait() {
+        let mut meta = account(NOW);
+        meta.email = Some("quota@example.com".to_string());
+        meta.account_id = Some("acc_quota".to_string());
+        let cache = exhausted_cache(
+            "acc_quota",
+            cache_entry(
+                // Genuinely exhausted, recovers in a minute.
+                cache_window(Some(100.0), Some((NOW + 60_000) as f64)),
+                // 99.6% used ROUNDS to 0 left but still has quota; its
+                // 28-day monthly reset must not be folded in.
+                cache_window(Some(99.6), Some((NOW + 28 * 86_400_000) as f64)),
+            ),
+        );
+        let all = vec![meta.clone()];
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.quota_cache = Some(&cache);
+        input.all_accounts = Some(&all);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 60_000);
+    }
+
+    #[test]
+    fn applies_runtime_overlay_skip_reasons_to_forecast_availability() {
+        let meta = account(NOW);
+        let raw = evaluate_forecast_account(&ForecastAccountInput::new(0, &meta, false, NOW));
+        assert_eq!(raw.availability, ForecastAvailability::Ready);
+
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .last_pool_exhaustion_skip_reasons
+            .insert("0".to_string(), "circuit-open".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let overlaid = evaluate_forecast_account(&input);
+        assert_eq!(overlaid.availability, ForecastAvailability::Unavailable);
+        assert!(
+            overlaid
+                .reasons
+                .iter()
+                .any(|r| r == "runtime skip: circuit-open")
+        );
+    }
+
+    #[test]
+    fn marks_non_time_bounded_runtime_skip_reasons_as_unavailable() {
+        for reason in ["circuit-open", "token-exhausted", "workspace-disabled"] {
+            let meta = account(NOW);
+            let mut overlay = RuntimeForecastOverlay::default();
+            overlay
+                .last_pool_exhaustion_skip_reasons
+                .insert("0".to_string(), reason.to_string());
+            let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+            input.runtime_overlay = Some(&overlay);
+            let result = evaluate_forecast_account(&input);
+            assert_eq!(result.availability, ForecastAvailability::Unavailable);
+            assert!(
+                result
+                    .reasons
+                    .iter()
+                    .any(|r| r == &format!("runtime skip: {reason}"))
+            );
+        }
+    }
+
+    #[test]
+    fn ignores_an_empty_string_overlay_reason_like_js_truthiness() {
+        // TS gates on `overlayReason && ...`; "" is falsy, so a hand-edited
+        // (or buggy-writer) empty reason must leave the account Ready and
+        // never emit a bare "runtime skip: " reason.
+        let meta = account(NOW);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), String::new());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+        assert!(result.reasons.iter().all(|r| !r.starts_with("runtime skip:")));
+    }
+
+    #[test]
+    fn ignores_a_stale_rate_limited_overlay_when_no_rate_limit_is_active_on_disk() {
+        let mut meta = account(NOW);
+        // Expired entry: no longer an active rate limit.
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", NOW - 30_000);
+        meta.rate_limit_reset_times = Some(times);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .last_pool_exhaustion_skip_reasons
+            .insert("0".to_string(), "rate-limited".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+        assert!(result.reasons.is_empty());
+    }
+
+    #[test]
+    fn ignores_a_stale_rate_limited_overlay_when_rate_limit_reset_times_is_absent() {
+        let meta = account(NOW);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .last_pool_exhaustion_skip_reasons
+            .insert("0".to_string(), "rate-limited".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+    }
+
+    #[test]
+    fn applies_a_rate_limited_overlay_when_the_rate_limit_is_still_active_on_disk() {
+        let mut meta = account(NOW);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", NOW + 120_000);
+        meta.rate_limit_reset_times = Some(times);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), "rate-limited".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "runtime skip: rate-limited")
+        );
+    }
+
+    #[test]
+    fn applies_a_rate_limited_overlay_when_a_model_scoped_limit_is_active_on_disk() {
+        let mut meta = account(NOW);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex:gpt-5.3-codex", NOW + 120_000);
+        meta.rate_limit_reset_times = Some(times);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), "rate-limited".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+    }
+
+    #[test]
+    fn cooling_down_overlay_staleness_rules() {
+        // Elapsed cooldown → stale, ignored.
+        let mut meta = account(NOW);
+        meta.cooling_down_until = Some(NOW - 1_000);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), "cooling-down:server-error".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+
+        // Absent coolingDownUntil → stale, ignored.
+        let meta = account(NOW);
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+
+        // Active cooldown → applied.
+        let mut meta = account(NOW);
+        meta.cooling_down_until = Some(NOW + 60_000);
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "runtime skip: cooling-down:server-error")
+        );
+    }
+
+    #[test]
+    fn already_attempted_overlay_reason_is_always_ignored() {
+        let meta = account(NOW);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), "already-attempted".to_string());
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+    }
+
+    #[test]
+    fn policy_block_takes_precedence_over_skip_reasons() {
+        let meta = account(NOW);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay
+            .account_skip_reasons
+            .insert("0".to_string(), "circuit-open".to_string());
+        overlay.policy_blocked_indexes.push(0);
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "runtime policy blocked account")
+        );
+        assert!(!result.reasons.iter().any(|r| r.starts_with("runtime skip")));
+    }
+
+    #[test]
+    fn recommends_the_best_ready_account() {
+        let meta_a = account(NOW);
+        let meta_b = account(NOW);
+        let results = vec![
+            evaluate_forecast_account(&ForecastAccountInput::new(0, &meta_a, false, NOW)),
+            evaluate_forecast_account(&ForecastAccountInput::new(1, &meta_b, true, NOW)),
+        ];
+        let recommendation = recommend_forecast_account(&results);
+        // The current account starts at -5 risk (clamped to 0) and ties are
+        // broken current-first.
+        assert_eq!(recommendation.recommended_index, Some(1));
+        assert_eq!(
+            recommendation.reason,
+            "Lowest risk ready account (low, score 0)."
+        );
+    }
+
+    #[test]
+    fn redacts_sensitive_refresh_warning_details() {
+        let meta = account(NOW);
+        let refresh_failure = failure(
+            None,
+            None,
+            Some("Bearer abc.def.ghi rejected for user@example.com (key sk-abcdefghij12345)"),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.refresh_failure = Some(&refresh_failure);
+        let result = evaluate_forecast_account(&input);
+        let reason = result
+            .reasons
+            .iter()
+            .find(|r| r.starts_with("refresh warning:"))
+            .expect("refresh warning reason");
+        assert!(!reason.contains("abc.def.ghi"), "bearer leaked: {reason}");
+        assert!(
+            !reason.contains("user@example.com"),
+            "email leaked: {reason}"
+        );
+        assert!(
+            !reason.contains("sk-abcdefghij12345"),
+            "key leaked: {reason}"
+        );
+        assert_eq!(
+            reason,
+            "refresh warning: Bearer *** rejected for us***@***.com (key ***)"
+        );
+    }
+
+    #[test]
+    fn marks_hard_refresh_failure_as_unavailable() {
+        let meta = account(NOW);
+        let refresh_failure = failure(Some(TokenFailureReason::MissingRefresh), None, None);
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.refresh_failure = Some(&refresh_failure);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+        assert!(result.hard_failure);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "hard auth failure: missing_refresh")
+        );
+    }
+
+    #[test]
+    fn prefers_refresh_failure_reason_code_over_raw_message_text() {
+        let meta = account(NOW);
+        let refresh_failure = failure(
+            Some(TokenFailureReason::HttpError),
+            Some(429),
+            Some("something noisy"),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.refresh_failure = Some(&refresh_failure);
+        let result = evaluate_forecast_account(&input);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "refresh warning: http_error (429)")
+        );
+    }
+
+    #[test]
+    fn uses_redacted_fallback_refresh_messages_when_reason_code_is_blank() {
+        let meta = account(NOW);
+        let refresh_failure = failure(None, None, Some("   "));
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.refresh_failure = Some(&refresh_failure);
+        let result = evaluate_forecast_account(&input);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "refresh warning: refresh failed")
+        );
+    }
+
+    #[test]
+    fn uses_max_of_cooldown_and_rate_limit_wait_for_delayed_availability() {
+        let mut meta = account(NOW);
+        meta.cooling_down_until = Some(NOW + 30_000);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", NOW + 90_000);
+        meta.rate_limit_reset_times = Some(times);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &meta, false, NOW));
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 90_000);
+        assert!(result.reasons.iter().any(|r| r == "cooldown remaining 30s"));
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "rate limit resets in 1m 30s")
+        );
+    }
+
+    #[test]
+    fn marks_delayed_on_live_429_and_tracks_quota_reset_wait() {
+        let meta = account(NOW);
+        // 429 honors EVERY future window, including a healthy one.
+        let quota = live_quota(
+            429,
+            live_window(Some(50.0), Some(NOW + 45_000)),
+            live_window(Some(10.0), None),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 45_000);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "live probe returned 429")
+        );
+        assert!(!result.exhausted);
+    }
+
+    #[test]
+    fn does_not_delay_healthy_accounts_only_because_quota_reset_headers_exist() {
+        let meta = account(NOW);
+        let quota = live_quota(
+            200,
+            live_window(Some(12.0), Some(NOW + 3_600_000)),
+            live_window(Some(3.0), Some(NOW + 7 * 86_400_000)),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+        assert_eq!(result.wait_ms, 0);
+    }
+
+    #[test]
+    fn does_not_delay_a_99_6_used_live_window_whose_reset_is_still_in_the_future() {
+        let meta = account(NOW);
+        // 99.6% is usage pressure (>= 90) but NOT raw-exhausted; on a 200 the
+        // only-exhausted filter keeps its future reset out of the wait.
+        let quota = live_quota(
+            200,
+            live_window(Some(99.6), Some(NOW + 28 * 86_400_000)),
+            live_window(Some(10.0), None),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Ready);
+        assert_eq!(result.wait_ms, 0);
+        assert!(!result.exhausted);
+    }
+
+    #[test]
+    fn h5_live_quota_wait_reflects_only_the_exhausted_window_not_a_healthy_7d_secondary() {
+        let meta = account(NOW);
+        let quota = live_quota(
+            200,
+            live_window(Some(100.0), Some(NOW + 60_000)),
+            live_window(Some(50.0), Some(NOW + 7 * 86_400_000)),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 60_000);
+    }
+
+    #[test]
+    fn h5_recommends_the_account_that_actually_frees_first_under_live_quota_pressure() {
+        let meta_a = account(NOW);
+        let meta_b = account(NOW);
+        // A frees in 60 s; B frees in 10 min. Folding healthy secondaries in
+        // would have made both waits ~7 d and scrambled the order.
+        let quota_a = live_quota(
+            200,
+            live_window(Some(100.0), Some(NOW + 60_000)),
+            live_window(Some(40.0), Some(NOW + 7 * 86_400_000)),
+        );
+        let quota_b = live_quota(
+            200,
+            live_window(Some(100.0), Some(NOW + 600_000)),
+            live_window(Some(45.0), Some(NOW + 7 * 86_400_000)),
+        );
+        let mut input_a = ForecastAccountInput::new(0, &meta_a, false, NOW);
+        input_a.live_quota = Some(&quota_a);
+        let mut input_b = ForecastAccountInput::new(1, &meta_b, false, NOW);
+        input_b.live_quota = Some(&quota_b);
+        let results = vec![
+            evaluate_forecast_account(&input_a),
+            evaluate_forecast_account(&input_b),
+        ];
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, Some(0));
+        assert_eq!(
+            recommendation.reason,
+            "No account is immediately ready; pick shortest wait (1m 0s)."
+        );
+    }
+
+    #[test]
+    fn flags_a_live_200_probe_at_100_used_with_no_reset_at_as_exhausted_not_ready() {
+        let meta = account(NOW);
+        let quota = live_quota(
+            200,
+            live_window(Some(100.0), None),
+            live_window(Some(10.0), None),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert!(result.exhausted);
+    }
+
+    #[test]
+    fn applies_higher_risk_at_higher_quota_usage_thresholds() {
+        let meta = account(NOW);
+        let expectations = [(65.0, 0), (70.0, 10), (80.0, 20), (90.0, 35), (98.0, 55)];
+        for (used, expected_delta) in expectations {
+            let quota = live_quota(
+                200,
+                live_window(Some(used), None),
+                live_window(Some(0.0), None),
+            );
+            let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+            input.live_quota = Some(&quota);
+            let result = evaluate_forecast_account(&input);
+            assert_eq!(
+                result.risk_score, expected_delta,
+                "usedPercent {used} → +{expected_delta}"
+            );
+        }
+    }
+
+    #[test]
+    fn adds_stale_age_risk_penalties_for_invalid_and_old_usage_timestamps() {
+        // lastUsed in the future → negative age → +5.
+        let future = AccountMetadataV3::new("refresh-1", NOW - 1_000, NOW + 60_000);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &future, false, NOW));
+        assert_eq!(result.risk_score, 5);
+
+        // Older than 7 days → +10.
+        let old = AccountMetadataV3::new("refresh-1", NOW - 1_000, NOW - 8 * 86_400_000);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &old, false, NOW));
+        assert_eq!(result.risk_score, 10);
+
+        // lastUsed 0 (never) → no staleness penalty at all.
+        let never = AccountMetadataV3::new("refresh-1", NOW - 1_000, 0);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &never, false, NOW));
+        assert_eq!(result.risk_score, 0);
+    }
+
+    #[test]
+    fn returns_delayed_recommendation_when_no_account_is_immediately_ready() {
+        let mut meta = account(NOW);
+        meta.cooling_down_until = Some(NOW + 90_000);
+        let results = vec![evaluate_forecast_account(&ForecastAccountInput::new(
+            0, &meta, false, NOW,
+        ))];
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, Some(0));
+        assert_eq!(
+            recommendation.reason,
+            "No account is immediately ready; pick shortest wait (1m 30s)."
+        );
+    }
+
+    #[test]
+    fn uses_codex_family_reset_keys_and_ignores_stale_or_invalid_entries() {
+        let mut meta = account(NOW);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", NOW - 1_000); // stale — ignored
+        times.insert("codex:gpt-5.3-codex", NOW + 120_000);
+        times.insert("gpt-5.2", NOW + 60_000); // different family — ignored
+        meta.rate_limit_reset_times = Some(times);
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &meta, false, NOW));
+        assert_eq!(result.availability, ForecastAvailability::Delayed);
+        assert_eq!(result.wait_ms, 120_000);
+        assert!(
+            result
+                .reasons
+                .iter()
+                .any(|r| r == "rate limit resets in 2m 0s")
+        );
+    }
+
+    #[test]
+    fn keeps_unavailable_state_when_live_quota_returns_429_on_an_unavailable_account() {
+        let mut meta = account(NOW);
+        meta.enabled = Some(false);
+        let quota = live_quota(
+            429,
+            live_window(Some(100.0), Some(NOW + 60_000)),
+            live_window(None, None),
+        );
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.live_quota = Some(&quota);
+        let result = evaluate_forecast_account(&input);
+        assert_eq!(result.availability, ForecastAvailability::Unavailable);
+    }
+
+    #[test]
+    fn breaks_delayed_recommendation_ties_in_favor_of_the_current_account() {
+        let mut meta_a = account(NOW);
+        meta_a.cooling_down_until = Some(NOW + 60_000);
+        let mut meta_b = account(NOW);
+        meta_b.cooling_down_until = Some(NOW + 60_000);
+        let results = vec![
+            evaluate_forecast_account(&ForecastAccountInput::new(0, &meta_a, false, NOW)),
+            evaluate_forecast_account(&ForecastAccountInput::new(1, &meta_b, true, NOW)),
+        ];
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, Some(1));
+    }
+
+    #[test]
+    fn returns_null_recommendation_when_all_candidates_are_disabled_or_hard_failed() {
+        let mut disabled_meta = account(NOW);
+        disabled_meta.enabled = Some(false);
+        let hard_meta = account(NOW);
+        let hard = failure(Some(TokenFailureReason::MissingRefresh), None, None);
+        let mut hard_input = ForecastAccountInput::new(1, &hard_meta, false, NOW);
+        hard_input.refresh_failure = Some(&hard);
+        let results = vec![
+            evaluate_forecast_account(&ForecastAccountInput::new(0, &disabled_meta, false, NOW)),
+            evaluate_forecast_account(&hard_input),
+        ];
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, None);
+        assert_eq!(
+            recommendation.reason,
+            "No healthy accounts are available. Run `codex-multi-auth login` to add a fresh account."
+        );
+    }
+
+    #[test]
+    fn returns_null_recommendation_when_all_accounts_are_policy_blocked_or_exhausted() {
+        let meta = account(NOW);
+        let mut overlay = RuntimeForecastOverlay::default();
+        overlay.policy_blocked_indexes.push(0);
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.runtime_overlay = Some(&overlay);
+        let results = vec![evaluate_forecast_account(&input)];
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, None);
+        assert_eq!(
+            recommendation.reason,
+            "All accounts are blocked or exhausted. Wait for a reset, clear the block, or run `codex-multi-auth login` to add a fresh account."
+        );
+    }
+
+    #[test]
+    fn returns_null_recommendation_when_all_accounts_are_quota_exhausted() {
+        let mut meta = account(NOW);
+        meta.email = Some("quota@example.com".to_string());
+        meta.account_id = Some("acc_quota".to_string());
+        let cache = exhausted_cache(
+            "acc_quota",
+            cache_entry(
+                cache_window(Some(100.0), Some((NOW + 60_000) as f64)),
+                cache_window(Some(10.0), None),
+            ),
+        );
+        let all = vec![meta.clone()];
+        let mut input = ForecastAccountInput::new(0, &meta, false, NOW);
+        input.quota_cache = Some(&cache);
+        input.all_accounts = Some(&all);
+        let results = vec![evaluate_forecast_account(&input)];
+        // Exhausted accounts are "delayed" for display but never win a
+        // shortest-wait recommendation.
+        assert_eq!(results[0].availability, ForecastAvailability::Delayed);
+        assert!(results[0].exhausted);
+        let recommendation = recommend_forecast_account(&results);
+        assert_eq!(recommendation.recommended_index, None);
+        assert_eq!(
+            recommendation.reason,
+            "All accounts are blocked or exhausted. Wait for a reset, clear the block, or run `codex-multi-auth login` to add a fresh account."
+        );
+    }
+
+    #[test]
+    fn summarize_and_explanation_shapes() {
+        let ready_meta = account(NOW);
+        let mut delayed_meta = account(NOW);
+        delayed_meta.cooling_down_until = Some(NOW + 60_000);
+        let mut disabled_meta = account(NOW);
+        disabled_meta.enabled = Some(false);
+        let results = vec![
+            evaluate_forecast_account(&ForecastAccountInput::new(0, &ready_meta, false, NOW)),
+            evaluate_forecast_account(&ForecastAccountInput::new(1, &delayed_meta, false, NOW)),
+            evaluate_forecast_account(&ForecastAccountInput::new(2, &disabled_meta, false, NOW)),
+        ];
+        let summary = summarize_forecast(&results);
+        assert_eq!(
+            summary,
+            ForecastSummary {
+                total: 3,
+                ready: 1,
+                delayed: 1,
+                unavailable: 1,
+                high_risk: 1,
+            }
+        );
+
+        let recommendation = recommend_forecast_account(&results);
+        let explanation = build_forecast_explanation(&results, &recommendation);
+        assert_eq!(explanation.recommended_index, Some(0));
+        assert_eq!(explanation.considered.len(), 3);
+        assert!(explanation.considered[0].selected);
+        assert!(!explanation.considered[1].selected);
+    }
+
+    #[test]
+    fn redacts_email_in_the_account_label() {
+        let mut meta = account(NOW);
+        meta.email = Some("user.name@example.co.uk".to_string());
+        let result = evaluate_forecast_account(&ForecastAccountInput::new(0, &meta, false, NOW));
+        assert!(
+            !result.label.contains("user.name@example.co.uk"),
+            "label leaked email: {}",
+            result.label
+        );
+        assert!(result.label.contains("us***@***.uk"), "{}", result.label);
+    }
+}
diff --git a/crates/quota/src/health.rs b/crates/quota/src/health.rs
new file mode 100644
index 000000000..fff36a23e
--- /dev/null
+++ b/crates/quota/src/health.rs
@@ -0,0 +1,381 @@
+//! Port of `lib/health.ts` — a PURE shape-transformation utility producing
+//! the `PluginHealth` report (AUDIT-M08/D-04).
+//!
+//! Callers pass an already-flattened accounts array; the field-name mapping
+//! the caller must perform from `ManagedAccount` (kept in docs):
+//!
+//! | [`HealthAccountInput`] field | `ManagedAccount` source                          |
+//! |------------------------------|--------------------------------------------------|
+//! | `rate_limited_until`         | computed from `rateLimitResetTimes` per family   |
+//! | `cooldown_until`             | `coolingDownUntil`                               |
+//! | `last_used_at`               | `lastUsed`                                       |
+//! | `health`                     | computed from `getHealthTracker().getScore()`    |
+//!
+//! Side effect (spec 05 gotcha 18): fetching a circuit breaker CREATES one
+//! in the global registry when absent (registry FIFO-capped).
+
+use cma_core::json_io::format_js_number;
+use cma_rotation::circuit_breaker::{CircuitState, get_circuit_breaker};
+use cma_storage::identity::{AccountIdentityLike, get_account_identity_key};
+
+/// One flattened account row (the TS inline parameter shape).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct HealthAccountInput {
+    pub index: usize,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub refresh_token: Option<String>,
+    /// Health score 0..=100 (tracker-derived; may be fractional).
+    pub health: f64,
+    pub rate_limited_until: Option<i64>,
+    pub cooldown_until: Option<i64>,
+    pub cooldown_reason: Option<String>,
+    pub last_used_at: Option<i64>,
+}
+
+impl AccountIdentityLike for HealthAccountInput {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        self.refresh_token.as_deref()
+    }
+}
+
+/// TS `AccountHealth`. (No `Serialize`: `CircuitState` is rotation runtime
+/// state and stays compiler-enforced non-serializable — render via
+/// [`format_health_report`] or map manually.)
+#[derive(Clone, Debug, PartialEq)]
+pub struct AccountHealth {
+    pub index: usize,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub health: f64,
+    pub is_rate_limited: bool,
+    pub is_cooling_down: bool,
+    pub cooldown_reason: Option<String>,
+    pub last_used: Option<i64>,
+    pub circuit_state: CircuitState,
+}
+
+/// TS `PluginHealth["status"]`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PluginHealthStatus {
+    Healthy,
+    Degraded,
+    Unhealthy,
+}
+
+impl PluginHealthStatus {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            PluginHealthStatus::Healthy => "healthy",
+            PluginHealthStatus::Degraded => "degraded",
+            PluginHealthStatus::Unhealthy => "unhealthy",
+        }
+    }
+}
+
+impl std::fmt::Display for PluginHealthStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// TS `PluginHealth`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct PluginHealth {
+    pub status: PluginHealthStatus,
+    pub account_count: usize,
+    pub healthy_account_count: usize,
+    pub rate_limited_count: usize,
+    pub cooling_down_count: usize,
+    pub accounts: Vec<AccountHealth>,
+    pub timestamp: i64,
+}
+
+/// TS `getAccountHealth(accounts, now = Date.now())`.
+///
+/// A healthy account is not rate-limited, not cooling down, `health >= 50`,
+/// and has a CLOSED circuit. Status: no healthy among a non-empty pool →
+/// `unhealthy`; some unhealthy → `degraded`; else `healthy` (empty input is
+/// `healthy`).
+pub fn get_account_health(accounts: &[HealthAccountInput], now: Option<i64>) -> PluginHealth {
+    let now = now.unwrap_or_else(cma_core::utils::now_ms);
+    let account_healths: Vec<AccountHealth> = accounts
+        .iter()
+        .map(|acc| {
+            let circuit_key =
+                get_account_identity_key(acc).unwrap_or_else(|| format!("account:{}", acc.index));
+            // Side effect: creates the breaker in the global registry when
+            // absent (FIFO-capped).
+            let circuit = get_circuit_breaker(&circuit_key, None);
+            AccountHealth {
+                index: acc.index,
+                email: acc.email.clone(),
+                account_id: acc.account_id.clone(),
+                health: acc.health,
+                is_rate_limited: acc.rate_limited_until.unwrap_or(0) > now,
+                is_cooling_down: acc.cooldown_until.unwrap_or(0) > now,
+                cooldown_reason: acc.cooldown_reason.clone(),
+                last_used: acc.last_used_at,
+                circuit_state: circuit.get_state(),
+            }
+        })
+        .collect();
+
+    let healthy_count = account_healths
+        .iter()
+        .filter(|a| {
+            !a.is_rate_limited
+                && !a.is_cooling_down
+                && a.health >= 50.0
+                && a.circuit_state == CircuitState::Closed
+        })
+        .count();
+    let rate_limited_count = account_healths.iter().filter(|a| a.is_rate_limited).count();
+    let cooling_down_count = account_healths.iter().filter(|a| a.is_cooling_down).count();
+
+    let status = if healthy_count == 0 && !accounts.is_empty() {
+        PluginHealthStatus::Unhealthy
+    } else if healthy_count < accounts.len() {
+        PluginHealthStatus::Degraded
+    } else {
+        PluginHealthStatus::Healthy
+    };
+
+    PluginHealth {
+        status,
+        account_count: accounts.len(),
+        healthy_account_count: healthy_count,
+        rate_limited_count,
+        cooling_down_count,
+        accounts: account_healths,
+        timestamp: now,
+    }
+}
+
+/// TS `formatHealthReport(health)` — exact lines joined by `"\n"` (FROZEN
+/// user-visible strings).
+pub fn format_health_report(health: &PluginHealth) -> String {
+    let mut lines: Vec<String> = vec![
+        format!("Plugin Health: {}", health.status.as_str().to_uppercase()),
+        String::new(),
+        format!(
+            "Accounts: {}/{} healthy",
+            health.healthy_account_count, health.account_count
+        ),
+    ];
+
+    if health.rate_limited_count > 0 {
+        lines.push(format!("Rate Limited: {}", health.rate_limited_count));
+    }
+    if health.cooling_down_count > 0 {
+        lines.push(format!("Cooling Down: {}", health.cooling_down_count));
+    }
+
+    if !health.accounts.is_empty() {
+        lines.push(String::new());
+        lines.push("Account Details:".to_string());
+        for acc in &health.accounts {
+            let email = acc
+                .email
+                .clone()
+                .unwrap_or_else(|| format!("Account {}", acc.index + 1));
+            let mut flags: Vec<String> = Vec::new();
+            if acc.is_rate_limited {
+                flags.push("rate-limited".to_string());
+            }
+            if acc.is_cooling_down {
+                flags.push(format!(
+                    "cooling-{}",
+                    acc.cooldown_reason.as_deref().unwrap_or("down")
+                ));
+            }
+            if acc.circuit_state != CircuitState::Closed {
+                flags.push(format!("circuit-{}", acc.circuit_state.as_str()));
+            }
+            let flag_str = if flags.is_empty() {
+                String::new()
+            } else {
+                format!(" [{}]", flags.join(", "))
+            };
+            lines.push(format!(
+                "  [{}] {}: {}%{}",
+                acc.index + 1,
+                email,
+                format_js_number(acc.health),
+                flag_str
+            ));
+        }
+    }
+
+    lines.join("\n")
+}
+
+// ============================================================================
+// Tests — ported from test/health.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_rotation::circuit_breaker::reset_all_circuit_breakers;
+    use serial_test::serial;
+
+    const NOW: i64 = 1_700_000_000_000;
+
+    fn input(index: usize, health: f64) -> HealthAccountInput {
+        HealthAccountInput {
+            index,
+            email: Some(format!("user{index}@example.com")),
+            account_id: Some(format!("acc_{index}")),
+            health,
+            ..HealthAccountInput::default()
+        }
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn returns_healthy_status_when_all_accounts_are_good() {
+        reset_all_circuit_breakers();
+        let health = get_account_health(&[input(0, 100.0), input(1, 80.0)], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Healthy);
+        assert_eq!(health.account_count, 2);
+        assert_eq!(health.healthy_account_count, 2);
+        assert_eq!(health.timestamp, NOW);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn returns_degraded_status_when_some_accounts_are_rate_limited() {
+        reset_all_circuit_breakers();
+        let mut limited = input(1, 100.0);
+        limited.rate_limited_until = Some(NOW + 60_000);
+        let health = get_account_health(&[input(0, 100.0), limited], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Degraded);
+        assert_eq!(health.healthy_account_count, 1);
+        assert_eq!(health.rate_limited_count, 1);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn returns_unhealthy_status_when_all_accounts_are_unavailable() {
+        reset_all_circuit_breakers();
+        let mut a = input(0, 100.0);
+        a.rate_limited_until = Some(NOW + 60_000);
+        let mut b = input(1, 100.0);
+        b.cooldown_until = Some(NOW + 60_000);
+        let health = get_account_health(&[a, b], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Unhealthy);
+        assert_eq!(health.healthy_account_count, 0);
+        assert_eq!(health.cooling_down_count, 1);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn returns_healthy_for_empty_accounts() {
+        reset_all_circuit_breakers();
+        let health = get_account_health(&[], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Healthy);
+        assert_eq!(health.account_count, 0);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn marks_low_health_accounts_as_not_healthy() {
+        reset_all_circuit_breakers();
+        let health = get_account_health(&[input(0, 49.0)], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Unhealthy);
+        // Boundary: exactly 50 counts as healthy.
+        let health = get_account_health(&[input(0, 50.0)], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Healthy);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn includes_circuit_breaker_state_in_account_health() {
+        reset_all_circuit_breakers();
+        let health = get_account_health(&[input(0, 100.0)], Some(NOW));
+        assert_eq!(health.accounts[0].circuit_state, CircuitState::Closed);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn does_not_count_circuit_open_accounts_as_healthy() {
+        reset_all_circuit_breakers();
+        let acc = input(0, 100.0);
+        // Force the account's breaker open (3 failures in the window). The
+        // registry key must match what getAccountHealth derives.
+        let key = get_account_identity_key(&acc).expect("identity key");
+        let breaker = get_circuit_breaker(&key, None);
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.record_failure();
+
+        let health = get_account_health(&[acc], Some(NOW));
+        assert_eq!(health.accounts[0].circuit_state, CircuitState::Open);
+        assert_eq!(health.healthy_account_count, 0);
+        assert_eq!(health.status, PluginHealthStatus::Unhealthy);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn falls_back_to_an_index_scoped_circuit_key_without_identity() {
+        reset_all_circuit_breakers();
+        let anonymous = HealthAccountInput {
+            index: 3,
+            health: 100.0,
+            ..HealthAccountInput::default()
+        };
+        // No identity fields at all → "account:{index}" key; must not panic
+        // and must stay healthy with a fresh (closed) breaker.
+        let health = get_account_health(&[anonymous], Some(NOW));
+        assert_eq!(health.status, PluginHealthStatus::Healthy);
+        assert_eq!(health.accounts[0].circuit_state, CircuitState::Closed);
+    }
+
+    #[test]
+    #[serial(circuit)]
+    fn formats_health_report_correctly() {
+        reset_all_circuit_breakers();
+        let mut limited = HealthAccountInput {
+            index: 1,
+            health: 30.0,
+            ..HealthAccountInput::default()
+        };
+        limited.rate_limited_until = Some(NOW + 60_000);
+        let mut cooling = HealthAccountInput {
+            index: 2,
+            health: 75.5,
+            ..HealthAccountInput::default()
+        };
+        cooling.cooldown_until = Some(NOW + 60_000);
+        cooling.cooldown_reason = Some("auth".to_string());
+        let healthy = HealthAccountInput {
+            index: 0,
+            email: Some("a@b.com".to_string()),
+            health: 100.0,
+            ..HealthAccountInput::default()
+        };
+
+        let health = get_account_health(&[healthy, limited, cooling], Some(NOW));
+        let report = format_health_report(&health);
+        assert_eq!(
+            report,
+            "Plugin Health: DEGRADED\n\
+             \n\
+             Accounts: 1/3 healthy\n\
+             Rate Limited: 1\n\
+             Cooling Down: 1\n\
+             \n\
+             Account Details:\n\
+             \x20 [1] a@b.com: 100%\n\
+             \x20 [2] Account 2: 30% [rate-limited]\n\
+             \x20 [3] Account 3: 75.5% [cooling-auth]"
+        );
+    }
+}
diff --git a/crates/quota/src/lib.rs b/crates/quota/src/lib.rs
new file mode 100644
index 000000000..cb9e1f5b5
--- /dev/null
+++ b/crates/quota/src/lib.rs
@@ -0,0 +1,12 @@
+//! cma-quota - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod audit;
+pub mod budget_guard;
+pub mod cache;
+pub mod forecast;
+pub mod health;
+pub mod live_account_sync;
+pub mod parallel_probe;
+pub mod preemptive_scheduler;
+pub mod probe;
+pub mod readiness;
+pub mod runtime_policy;
diff --git a/crates/quota/src/live_account_sync.rs b/crates/quota/src/live_account_sync.rs
new file mode 100644
index 000000000..8977ef3b9
--- /dev/null
+++ b/crates/quota/src/live_account_sync.rs
@@ -0,0 +1,684 @@
+//! Port of `lib/live-account-sync.ts` — watches the account storage file and
+//! triggers a reload callback when its content changes. Uses a directory
+//! watcher (`notify`, the `fs.watch` analogue) plus a polling fallback for
+//! Windows reliability.
+//!
+//! Behavior contract (spec 05 §11 + gotcha 21):
+//! - The WATCHER observes the parent DIRECTORY (survives atomic
+//!   rename-replace); events match the target name or `"{target}."`-prefixed
+//!   temp-staging names.
+//! - Poll compares mtime with `!=` (NOT `>`) so coarse Windows timestamps and
+//!   file-deletion→missing transitions both trigger.
+//! - Reloads are debounced (trailing edge) and single-flight WITHOUT
+//!   re-queue: a change landing mid-reload is picked up by the next poll
+//!   tick, not immediately.
+//! - `readMtimeMs` maps ENOENT/EBUSY/EACCES to "missing" but propagates any
+//!   other error.
+//! - After a successful reload the mtime is re-read.
+
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::{Arc, Mutex, Weak};
+
+use cma_core::fs_retry::code_of;
+use cma_core::logger::create_logger;
+use cma_core::utils::now_ms;
+use notify::Watcher;
+use serde_json::json;
+use tokio::task::JoinHandle;
+
+/// Reason a reload was scheduled (TS `"watch" | "poll"` union).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LiveSyncReason {
+    Watch,
+    Poll,
+}
+
+impl LiveSyncReason {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            LiveSyncReason::Watch => "watch",
+            LiveSyncReason::Poll => "poll",
+        }
+    }
+}
+
+/// Boxed reload future (TS `() => Promise<void>`; rejections are counted).
+pub type LiveReloadFuture = Pin<
+    Box<dyn std::future::Future<Output = Result<(), Box<dyn std::error::Error + Send + Sync>>> + Send>,
+>;
+/// Shared reload callback.
+pub type LiveReloadFn = Arc<dyn Fn() -> LiveReloadFuture + Send + Sync>;
+
+/// TS `interface LiveAccountSyncOptions`.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct LiveAccountSyncOptions {
+    /// Default 250, floor 50.
+    pub debounce_ms: Option<u64>,
+    /// Default 2000, floor 500.
+    pub poll_interval_ms: Option<u64>,
+}
+
+/// TS `interface LiveAccountSyncSnapshot`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LiveAccountSyncSnapshot {
+    pub path: Option<PathBuf>,
+    pub running: bool,
+    pub last_known_mtime_ms: Option<f64>,
+    pub last_sync_at: Option<i64>,
+    pub reload_count: u64,
+    pub error_count: u64,
+}
+
+/// TS private `readMtimeMs(path)` — `Ok(None)` for missing/locked
+/// (ENOENT/EBUSY/EACCES), `Err` for anything else, otherwise the finite
+/// mtime in milliseconds (sub-millisecond precision preserved, Node
+/// `stats.mtimeMs` parity).
+async fn read_mtime_ms(path: &Path) -> std::io::Result<Option<f64>> {
+    match tokio::fs::metadata(path).await {
+        Ok(metadata) => {
+            let Ok(modified) = metadata.modified() else {
+                return Ok(None);
+            };
+            let mtime_ms = match modified.duration_since(std::time::UNIX_EPOCH) {
+                Ok(duration) => duration.as_secs_f64() * 1000.0,
+                // Pre-epoch mtimes are representable in Node as negative ms.
+                Err(before_epoch) => -(before_epoch.duration().as_secs_f64() * 1000.0),
+            };
+            Ok(mtime_ms.is_finite().then_some(mtime_ms))
+        }
+        Err(error) => {
+            if error.kind() == std::io::ErrorKind::NotFound
+                || matches!(code_of(&error), Some("ENOENT" | "EBUSY" | "EACCES"))
+            {
+                Ok(None)
+            } else {
+                Err(error)
+            }
+        }
+    }
+}
+
+/// TS `summarizeWatchPath` — basename only (never log the full path).
+fn summarize_watch_path(path: Option<&Path>) -> String {
+    match path.and_then(|p| p.file_name()) {
+        Some(name) => name.to_string_lossy().into_owned(),
+        None => "<unknown>".to_string(),
+    }
+}
+
+struct State {
+    watcher: Option<notify::RecommendedWatcher>,
+    poll_task: Option<JoinHandle<()>>,
+    debounce_task: Option<JoinHandle<()>>,
+    current_path: Option<PathBuf>,
+    running: bool,
+    last_known_mtime_ms: Option<f64>,
+    last_sync_at: Option<i64>,
+    reload_count: u64,
+    error_count: u64,
+}
+
+struct Inner {
+    reload: LiveReloadFn,
+    debounce_ms: u64,
+    poll_interval_ms: u64,
+    state: Mutex<State>,
+    /// Single-flight gate (TS `reloadInFlight`): held for the duration of a
+    /// reload; a concurrent attempt awaits the holder and returns WITHOUT
+    /// re-running.
+    reload_gate: tokio::sync::Mutex<()>,
+}
+
+/// TS `class LiveAccountSync`.
+pub struct LiveAccountSync {
+    inner: Arc<Inner>,
+}
+
+impl std::fmt::Debug for LiveAccountSync {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LiveAccountSync")
+            .field("snapshot", &self.get_snapshot())
+            .finish()
+    }
+}
+
+impl LiveAccountSync {
+    /// TS constructor — `debounceMs = max(50, floor(?? 250))`,
+    /// `pollIntervalMs = max(500, floor(?? 2000))`.
+    pub fn new(reload: LiveReloadFn, options: LiveAccountSyncOptions) -> Self {
+        Self {
+            inner: Arc::new(Inner {
+                reload,
+                debounce_ms: options.debounce_ms.unwrap_or(250).max(50),
+                poll_interval_ms: options.poll_interval_ms.unwrap_or(2_000).max(500),
+                state: Mutex::new(State {
+                    watcher: None,
+                    poll_task: None,
+                    debounce_task: None,
+                    current_path: None,
+                    running: false,
+                    last_known_mtime_ms: None,
+                    last_sync_at: None,
+                    reload_count: 0,
+                    error_count: 0,
+                }),
+                reload_gate: tokio::sync::Mutex::const_new(()),
+            }),
+        }
+    }
+
+    /// TS `syncToPath(path)` — empty path or already-running-on-same-path is
+    /// a no-op; otherwise stops any previous watch and starts the dir watcher
+    /// plus the poll loop. Propagates unexpected initial-stat errors (TS
+    /// parity: `readMtimeMs` rethrows non-mapped codes).
+    ///
+    /// Must run inside a tokio runtime (the poll/debounce tasks are spawned
+    /// on the ambient runtime; the TS timers were `unref()`'d, which tokio
+    /// tasks match — they never keep a process alive on their own).
+    pub async fn sync_to_path(&self, path: &Path) -> std::io::Result<()> {
+        if path.as_os_str().is_empty() {
+            return Ok(());
+        }
+        {
+            let state = self.lock_state();
+            if state.running && state.current_path.as_deref() == Some(path) {
+                return Ok(());
+            }
+        }
+        self.stop();
+
+        {
+            let mut state = self.lock_state();
+            state.current_path = Some(path.to_path_buf());
+        }
+        let initial_mtime = read_mtime_ms(path).await?;
+        let runtime = tokio::runtime::Handle::current();
+
+        // fs.watch analogue: watch the parent DIRECTORY (not the file) so
+        // atomic rename-replace keeps being observed.
+        let target_name = path
+            .file_name()
+            .map(|name| name.to_string_lossy().into_owned())
+            .unwrap_or_default();
+        let target_prefix = format!("{target_name}.");
+        let weak: Weak<Inner> = Arc::downgrade(&self.inner);
+        let watcher_runtime = runtime.clone();
+        let watcher_result =
+            notify::recommended_watcher(move |event: Result<notify::Event, notify::Error>| {
+                let Some(inner) = weak.upgrade() else {
+                    return;
+                };
+                let Ok(event) = event else {
+                    // Watcher-level errors have no TS analogue (fs.watch never
+                    // delivered them to the listener); polling covers the gap.
+                    return;
+                };
+                // A missing filename in TS scheduled unconditionally; notify
+                // events with no paths behave the same.
+                let matches = event.paths.is_empty()
+                    || event.paths.iter().any(|event_path| {
+                        event_path
+                            .file_name()
+                            .map(|name| name.to_string_lossy())
+                            .is_some_and(|name| {
+                                name == target_name.as_str() || name.starts_with(&target_prefix)
+                            })
+                    });
+                if matches {
+                    Inner::schedule_reload(&inner, &watcher_runtime, LiveSyncReason::Watch);
+                }
+            });
+        let parent = match path.parent() {
+            Some(parent) if !parent.as_os_str().is_empty() => parent.to_path_buf(),
+            _ => PathBuf::from("."),
+        };
+        let watcher = match watcher_result {
+            Ok(mut watcher) => match watcher.watch(&parent, notify::RecursiveMode::NonRecursive) {
+                Ok(()) => Some(watcher),
+                Err(error) => {
+                    self.record_watch_start_failure(path, &error);
+                    None
+                }
+            },
+            Err(error) => {
+                self.record_watch_start_failure(path, &error);
+                None
+            }
+        };
+
+        // Poll fallback (TS `setInterval(pollOnce, pollIntervalMs).unref()`).
+        let poll_inner = Arc::clone(&self.inner);
+        let poll_interval = self.inner.poll_interval_ms;
+        let poll_runtime = runtime.clone();
+        let poll_task = runtime.spawn(async move {
+            loop {
+                tokio::time::sleep(std::time::Duration::from_millis(poll_interval)).await;
+                Inner::poll_once(&poll_inner, &poll_runtime).await;
+            }
+        });
+
+        let mut state = self.lock_state();
+        state.last_known_mtime_ms = initial_mtime;
+        state.watcher = watcher;
+        state.poll_task = Some(poll_task);
+        state.running = true;
+        Ok(())
+    }
+
+    fn record_watch_start_failure(&self, path: &Path, error: &notify::Error) {
+        {
+            let mut state = self.lock_state();
+            state.error_count += 1;
+        }
+        create_logger("live-account-sync").warn(
+            "Failed to start fs.watch for account storage",
+            Some(&json!({
+                "path": summarize_watch_path(Some(path)),
+                "error": error.to_string(),
+            })),
+        );
+    }
+
+    /// TS `stop()` — flips `running`, closes the watcher, clears the poll
+    /// interval and any pending debounce timer.
+    pub fn stop(&self) {
+        let mut state = self.lock_state();
+        state.running = false;
+        state.watcher = None;
+        if let Some(poll_task) = state.poll_task.take() {
+            poll_task.abort();
+        }
+        if let Some(debounce_task) = state.debounce_task.take() {
+            debounce_task.abort();
+        }
+    }
+
+    /// TS `getSnapshot()`.
+    pub fn get_snapshot(&self) -> LiveAccountSyncSnapshot {
+        let state = self.lock_state();
+        LiveAccountSyncSnapshot {
+            path: state.current_path.clone(),
+            running: state.running,
+            last_known_mtime_ms: state.last_known_mtime_ms,
+            last_sync_at: state.last_sync_at,
+            reload_count: state.reload_count,
+            error_count: state.error_count,
+        }
+    }
+
+    fn lock_state(&self) -> std::sync::MutexGuard<'_, State> {
+        self.inner
+            .state
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    /// Direct access to the private `runReload` path (the TS suite reaches it
+    /// reflectively to prove single-flight coalescing).
+    #[doc(hidden)]
+    pub async fn __run_reload_for_tests(&self, reason: LiveSyncReason) {
+        Inner::run_reload(Arc::clone(&self.inner), reason).await;
+    }
+}
+
+impl Drop for LiveAccountSync {
+    fn drop(&mut self) {
+        // Rust-side hygiene: dropping the handle tears the watcher/tasks down
+        // (the TS object simply became unreachable; nothing observable
+        // differs because nothing can call a dropped handle).
+        self.stop();
+    }
+}
+
+impl Inner {
+    /// TS `scheduleReload(reason)` — trailing-edge debounce: any pending
+    /// timer is cancelled and a fresh one armed.
+    fn schedule_reload(
+        inner: &Arc<Inner>,
+        runtime: &tokio::runtime::Handle,
+        reason: LiveSyncReason,
+    ) {
+        let mut state = inner
+            .state
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        if !state.running {
+            return;
+        }
+        if let Some(previous) = state.debounce_task.take() {
+            previous.abort();
+        }
+        let debounce_ms = inner.debounce_ms;
+        let task_inner = Arc::clone(inner);
+        state.debounce_task = Some(runtime.spawn(async move {
+            tokio::time::sleep(std::time::Duration::from_millis(debounce_ms)).await;
+            Inner::run_reload(task_inner, reason).await;
+        }));
+    }
+
+    /// TS `pollOnce()` — any mtime inequality (`!=`, including
+    /// present→missing) schedules a reload; stat errors are counted.
+    async fn poll_once(inner: &Arc<Inner>, runtime: &tokio::runtime::Handle) {
+        let path = {
+            let state = inner
+                .state
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if !state.running {
+                return;
+            }
+            let Some(path) = state.current_path.clone() else {
+                return;
+            };
+            path
+        };
+        match read_mtime_ms(&path).await {
+            Ok(current_mtime) => {
+                let changed = {
+                    let mut state = inner
+                        .state
+                        .lock()
+                        .unwrap_or_else(|poisoned| poisoned.into_inner());
+                    if state.last_known_mtime_ms != current_mtime {
+                        state.last_known_mtime_ms = current_mtime;
+                        true
+                    } else {
+                        false
+                    }
+                };
+                if changed {
+                    Inner::schedule_reload(inner, runtime, LiveSyncReason::Poll);
+                }
+            }
+            Err(error) => {
+                {
+                    let mut state = inner
+                        .state
+                        .lock()
+                        .unwrap_or_else(|poisoned| poisoned.into_inner());
+                    state.error_count += 1;
+                }
+                create_logger("live-account-sync").debug(
+                    "Live account sync poll failed",
+                    Some(&json!({
+                        "path": summarize_watch_path(Some(&path)),
+                        "error": error.to_string(),
+                    })),
+                );
+            }
+        }
+    }
+
+    /// TS `runReload(reason)` — single-flight WITHOUT re-queue: when a reload
+    /// is already in flight, await its completion and return (a change
+    /// landing mid-reload is caught by the next poll tick). On success the
+    /// mtime is re-read AFTER the reload.
+    async fn run_reload(inner: Arc<Inner>, reason: LiveSyncReason) {
+        let target_path = {
+            let state = inner
+                .state
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if !state.running {
+                return;
+            }
+            let Some(path) = state.current_path.clone() else {
+                return;
+            };
+            path
+        };
+
+        let _gate = match inner.reload_gate.try_lock() {
+            Ok(gate) => gate,
+            Err(_) => {
+                // In flight: wait for it to finish, then return without
+                // running a second reload.
+                let _wait = inner.reload_gate.lock().await;
+                return;
+            }
+        };
+
+        let log = create_logger("live-account-sync");
+        let outcome: Result<(), String> = async {
+            (inner.reload)().await.map_err(|error| error.to_string())?;
+            {
+                let mut state = inner
+                    .state
+                    .lock()
+                    .unwrap_or_else(|poisoned| poisoned.into_inner());
+                state.last_sync_at = Some(now_ms());
+                state.reload_count += 1;
+            }
+            let refreshed = read_mtime_ms(&target_path)
+                .await
+                .map_err(|error| error.to_string())?;
+            {
+                let mut state = inner
+                    .state
+                    .lock()
+                    .unwrap_or_else(|poisoned| poisoned.into_inner());
+                state.last_known_mtime_ms = refreshed;
+            }
+            log.debug(
+                "Reloaded account manager from live storage update",
+                Some(&json!({
+                    "reason": reason.as_str(),
+                    "path": summarize_watch_path(Some(&target_path)),
+                })),
+            );
+            Ok(())
+        }
+        .await;
+
+        if let Err(error) = outcome {
+            {
+                let mut state = inner
+                    .state
+                    .lock()
+                    .unwrap_or_else(|poisoned| poisoned.into_inner());
+                state.error_count += 1;
+            }
+            log.warn(
+                "Live account sync reload failed",
+                Some(&json!({
+                    "reason": reason.as_str(),
+                    "path": summarize_watch_path(Some(&target_path)),
+                    "error": error,
+                })),
+            );
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use std::time::Duration;
+
+    fn counting_reload(counter: Arc<AtomicU64>, fail: bool) -> LiveReloadFn {
+        Arc::new(move || {
+            let counter = Arc::clone(&counter);
+            Box::pin(async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                if fail {
+                    Err("reload failed".into())
+                } else {
+                    Ok(())
+                }
+            })
+        })
+    }
+
+    fn temp_storage() -> (tempfile::TempDir, PathBuf) {
+        let dir = tempfile::Builder::new()
+            .prefix("cma-live-sync-")
+            .tempdir()
+            .unwrap();
+        let path = dir.path().join("openai-codex-accounts.json");
+        std::fs::write(&path, "{\"version\":3,\"activeIndex\":0,\"accounts\":[]}").unwrap();
+        (dir, path)
+    }
+
+    #[tokio::test]
+    async fn reloads_when_file_changes_are_detected() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let sync = LiveAccountSync::new(
+            counting_reload(Arc::clone(&calls), false),
+            LiveAccountSyncOptions {
+                debounce_ms: Some(50),
+                poll_interval_ms: Some(500),
+            },
+        );
+
+        sync.sync_to_path(&path).await.unwrap();
+        // Change content (watch event + mtime change for the poll fallback).
+        std::fs::write(
+            &path,
+            "{\"version\":3,\"activeIndex\":0,\"accounts\":[{\"refreshToken\":\"a\"}]}",
+        )
+        .unwrap();
+
+        tokio::time::sleep(Duration::from_millis(900)).await;
+
+        assert!(calls.load(Ordering::SeqCst) > 0);
+        let snapshot = sync.get_snapshot();
+        assert!(snapshot.reload_count > 0);
+        assert!(snapshot.last_sync_at.is_some());
+        sync.stop();
+    }
+
+    #[tokio::test]
+    async fn records_errors_when_reload_fails() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let sync = LiveAccountSync::new(
+            counting_reload(Arc::clone(&calls), true),
+            LiveAccountSyncOptions {
+                debounce_ms: Some(50),
+                poll_interval_ms: Some(500),
+            },
+        );
+
+        sync.sync_to_path(&path).await.unwrap();
+        std::fs::write(
+            &path,
+            "{\"version\":3,\"activeIndex\":0,\"accounts\":[{\"refreshToken\":\"b\"}]}",
+        )
+        .unwrap();
+
+        tokio::time::sleep(Duration::from_millis(900)).await;
+
+        let snapshot = sync.get_snapshot();
+        assert!(snapshot.error_count > 0);
+        assert_eq!(snapshot.reload_count, 0);
+        sync.stop();
+    }
+
+    #[tokio::test]
+    async fn stops_watching_cleanly_and_prevents_further_reloads() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let sync = LiveAccountSync::new(
+            counting_reload(Arc::clone(&calls), false),
+            LiveAccountSyncOptions {
+                debounce_ms: Some(50),
+                poll_interval_ms: Some(500),
+            },
+        );
+
+        sync.sync_to_path(&path).await.unwrap();
+        sync.stop();
+        std::fs::write(
+            &path,
+            "{\"version\":3,\"activeIndex\":0,\"accounts\":[{\"refreshToken\":\"c\"}]}",
+        )
+        .unwrap();
+
+        tokio::time::sleep(Duration::from_millis(1_200)).await;
+
+        assert_eq!(calls.load(Ordering::SeqCst), 0);
+        assert!(!sync.get_snapshot().running);
+    }
+
+    #[tokio::test]
+    async fn syncing_same_path_while_running_is_a_no_op() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let sync = LiveAccountSync::new(
+            counting_reload(Arc::clone(&calls), false),
+            LiveAccountSyncOptions::default(),
+        );
+        sync.sync_to_path(&path).await.unwrap();
+        let before = sync.get_snapshot();
+        sync.sync_to_path(&path).await.unwrap();
+        let after = sync.get_snapshot();
+        assert!(after.running);
+        assert_eq!(before.path, after.path);
+        sync.stop();
+    }
+
+    #[tokio::test]
+    async fn missing_file_yields_none_mtime_and_deletion_triggers_poll_reload() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let sync = LiveAccountSync::new(
+            counting_reload(Arc::clone(&calls), false),
+            LiveAccountSyncOptions {
+                debounce_ms: Some(50),
+                poll_interval_ms: Some(500),
+            },
+        );
+        sync.sync_to_path(&path).await.unwrap();
+        assert!(sync.get_snapshot().last_known_mtime_ms.is_some());
+
+        // Deleting the file flips the poll-observed mtime to None (`!=`
+        // comparison, not `>`), scheduling a reload.
+        std::fs::remove_file(&path).unwrap();
+        tokio::time::sleep(Duration::from_millis(900)).await;
+
+        assert!(calls.load(Ordering::SeqCst) > 0);
+        assert_eq!(sync.get_snapshot().last_known_mtime_ms, None);
+        sync.stop();
+    }
+
+    #[tokio::test]
+    async fn coalesces_overlapping_reload_attempts_into_single_in_flight_reload() {
+        let (_dir, path) = temp_storage();
+        let calls = Arc::new(AtomicU64::new(0));
+        let gate = Arc::new(tokio::sync::Semaphore::new(0));
+        let reload_calls = Arc::clone(&calls);
+        let reload_gate = Arc::clone(&gate);
+        let reload: LiveReloadFn = Arc::new(move || {
+            let calls = Arc::clone(&reload_calls);
+            let gate = Arc::clone(&reload_gate);
+            Box::pin(async move {
+                calls.fetch_add(1, Ordering::SeqCst);
+                // Block until the test releases the gate.
+                let _permit = gate.acquire().await.unwrap();
+                Ok(())
+            })
+        });
+        let sync = LiveAccountSync::new(
+            reload,
+            LiveAccountSyncOptions {
+                debounce_ms: Some(50),
+                poll_interval_ms: Some(500),
+            },
+        );
+        sync.sync_to_path(&path).await.unwrap();
+
+        let first = sync.__run_reload_for_tests(LiveSyncReason::Poll);
+        let second = sync.__run_reload_for_tests(LiveSyncReason::Watch);
+        let release = async {
+            tokio::time::sleep(Duration::from_millis(100)).await;
+            gate.add_permits(1);
+        };
+        tokio::join!(first, second, release);
+
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+        sync.stop();
+    }
+}
diff --git a/crates/quota/src/parallel_probe.rs b/crates/quota/src/parallel_probe.rs
new file mode 100644
index 000000000..12a512e55
--- /dev/null
+++ b/crates/quota/src/parallel_probe.rs
@@ -0,0 +1,576 @@
+//! Port of `lib/parallel-probe.ts` — candidate ranking by hybrid score plus
+//! a first-success-wins parallel probe race.
+//!
+//! Contracts (spec 05 §7 + gotchas 16/17):
+//! - Ranking score = `health * 2 + tokens * 5 + hoursSinceUsed * 2.0` over
+//!   the singleton trackers (untracked accounts score at the tracker maxima).
+//! - `get_top_candidates` MUTATES its snapshot accounts:
+//!   `clear_expired_rate_limits` prunes expired windows before availability
+//!   checks. (In TS the snapshot shared `rateLimitResetTimes` with the live
+//!   pool so the pruning leaked back; the Rust snapshot is a deep clone, so
+//!   the pruning stays local — behavior-neutral, the live pool lazily prunes
+//!   on its own reads.)
+//! - `probe_accounts_in_parallel` IGNORES its options parameter (declared
+//!   for API compatibility). Single-candidate failures return a `Failure`
+//!   result; multi-candidate all-fail returns `None` — asymmetric by design.
+//! - On a win every OTHER candidate's controller is aborted (compared by
+//!   `account.index`) and late results are ignored.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use cma_accounts::manager::{AccountManager, ManagedAccount, get_runtime_tracker_key};
+use cma_accounts::rate_limits::{
+    clear_expired_rate_limits, get_quota_key, is_rate_limited_for_family,
+};
+use cma_core::logger::create_logger;
+use cma_core::model_family::ModelFamily;
+use cma_core::utils::now_ms;
+use cma_request::headers::ArgError;
+use cma_rotation::trackers::{get_health_tracker, get_token_tracker};
+use futures::StreamExt;
+use futures::stream::FuturesUnordered;
+
+/// AbortController analogue for probe candidates (`tokio`-native; no
+/// `tokio-util` dependency in this crate).
+#[derive(Clone, Debug, Default)]
+pub struct ProbeAbortController {
+    inner: Arc<AbortInner>,
+}
+
+#[derive(Debug, Default)]
+struct AbortInner {
+    aborted: AtomicBool,
+    notify: tokio::sync::Notify,
+}
+
+impl ProbeAbortController {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Signal abort to every clone/signal of this controller.
+    pub fn abort(&self) {
+        self.inner.aborted.store(true, Ordering::SeqCst);
+        self.inner.notify.notify_waiters();
+    }
+
+    pub fn is_aborted(&self) -> bool {
+        self.inner.aborted.load(Ordering::SeqCst)
+    }
+
+    /// The `AbortSignal` half handed to probe functions.
+    pub fn signal(&self) -> ProbeAbortSignal {
+        ProbeAbortSignal {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+/// AbortSignal analogue — poll [`Self::is_aborted`] or await
+/// [`Self::cancelled`].
+#[derive(Clone, Debug)]
+pub struct ProbeAbortSignal {
+    inner: Arc<AbortInner>,
+}
+
+impl ProbeAbortSignal {
+    pub fn is_aborted(&self) -> bool {
+        self.inner.aborted.load(Ordering::SeqCst)
+    }
+
+    /// Resolves once the owning controller aborts (immediately when already
+    /// aborted).
+    pub async fn cancelled(&self) {
+        loop {
+            if self.is_aborted() {
+                return;
+            }
+            let notified = self.inner.notify.notified();
+            if self.is_aborted() {
+                return;
+            }
+            notified.await;
+        }
+    }
+}
+
+/// TS `ProbeCandidate` — one account with a fresh abort controller.
+#[derive(Clone, Debug)]
+pub struct ProbeCandidate {
+    pub account: ManagedAccount,
+    pub controller: ProbeAbortController,
+}
+
+/// TS `ProbeResult<T>` — the `type: "success" | "failure"` union as an enum.
+#[derive(Debug)]
+pub enum ProbeResult<T, E> {
+    Success {
+        account: ManagedAccount,
+        response: T,
+    },
+    Failure {
+        account: ManagedAccount,
+        error: E,
+    },
+}
+
+impl<T, E> ProbeResult<T, E> {
+    pub fn account(&self) -> &ManagedAccount {
+        match self {
+            ProbeResult::Success { account, .. } | ProbeResult::Failure { account, .. } => account,
+        }
+    }
+
+    pub fn is_success(&self) -> bool {
+        matches!(self, ProbeResult::Success { .. })
+    }
+}
+
+/// TS `ParallelProbeOptions` — **declared but unused**:
+/// `probe_accounts_in_parallel` ignores it (no concurrency cap, no timeout).
+/// Kept for API compatibility.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct ParallelProbeOptions {
+    pub max_concurrency: usize,
+    pub timeout_ms: u64,
+}
+
+/// TS `getTopCandidates` — top-N candidates ranked by hybrid score WITHOUT
+/// mutating AccountManager state (beyond the snapshot materialization).
+///
+/// The TS dual-call overload collapses into one typed signature; the
+/// `accountManager`/`modelFamily` TypeErrors are unrepresentable in Rust,
+/// while the `maxCandidates` validation survives as an [`ArgError`] with the
+/// frozen TS message.
+pub fn get_top_candidates(
+    account_manager: &mut AccountManager,
+    model_family: ModelFamily,
+    model: Option<&str>,
+    max_candidates: usize,
+) -> Result<Vec<ManagedAccount>, ArgError> {
+    if max_candidates == 0 {
+        return Err(ArgError::new(
+            "getTopCandidates requires maxCandidates to be a positive integer",
+        ));
+    }
+
+    let accounts = account_manager.get_accounts_snapshot();
+    if accounts.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let quota_key = get_quota_key(model_family, model);
+    let health_tracker = get_health_tracker(None);
+    let token_tracker = get_token_tracker(None);
+
+    struct Metrics {
+        account: ManagedAccount,
+        tracker_key: cma_rotation::trackers::TrackerKey,
+        is_available: bool,
+    }
+
+    let mut accounts_with_metrics: Vec<Metrics> = Vec::with_capacity(accounts.len());
+    for mut account in accounts {
+        clear_expired_rate_limits(&mut account);
+        let is_rate_limited = is_rate_limited_for_family(&mut account, model_family, model);
+        // Fresh clock per account (TS `Date.now()` inside the loop).
+        let is_cooling_down = matches!(account.cooling_down_until, Some(until) if until > now_ms());
+        let is_available = !is_rate_limited && !is_cooling_down;
+        let tracker_key = get_runtime_tracker_key(&mut account);
+        accounts_with_metrics.push(Metrics {
+            account,
+            tracker_key,
+            is_available,
+        });
+    }
+
+    let available: Vec<Metrics> = accounts_with_metrics
+        .into_iter()
+        .filter(|metrics| metrics.is_available)
+        .collect();
+    if available.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let now = now_ms();
+    let mut scored: Vec<(ManagedAccount, f64)> = available
+        .into_iter()
+        .map(|metrics| {
+            let health = health_tracker.get_score(metrics.tracker_key.clone(), Some(&quota_key));
+            let tokens = token_tracker.get_tokens(metrics.tracker_key.clone(), Some(&quota_key));
+            let hours_since_used =
+                (now - metrics.account.last_used) as f64 / (1000.0 * 60.0 * 60.0);
+            let score = health * 2.0 + tokens * 5.0 + hours_since_used * 2.0;
+            (metrics.account, score)
+        })
+        .collect();
+
+    // Descending by score; Rust `sort_by` is stable, so ties keep input
+    // order (Node's sort is stable too).
+    scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+    scored.truncate(max_candidates);
+    Ok(scored.into_iter().map(|(account, _)| account).collect())
+}
+
+/// TS `probeAccountsInParallel(candidates, probeFn, _options)` — probe with
+/// first-success-wins racing; losing candidates are aborted immediately when
+/// a winner is found. `_options` is ignored (TS parity — see
+/// [`ParallelProbeOptions`]).
+pub async fn probe_accounts_in_parallel<T, E, F, Fut>(
+    candidates: &[ProbeCandidate],
+    probe_fn: F,
+    _options: Option<&ParallelProbeOptions>,
+) -> Option<ProbeResult<T, E>>
+where
+    F: Fn(ManagedAccount, ProbeAbortSignal) -> Fut,
+    Fut: std::future::Future<Output = Result<T, E>>,
+{
+    let log = create_logger("parallel-probe");
+
+    if candidates.is_empty() {
+        return None;
+    }
+
+    if candidates.len() == 1 {
+        let candidate = &candidates[0];
+        let account = candidate.account.clone();
+        return match probe_fn(account.clone(), candidate.controller.signal()).await {
+            Ok(response) => Some(ProbeResult::Success { account, response }),
+            Err(error) => Some(ProbeResult::Failure { account, error }),
+        };
+    }
+
+    log.debug(
+        &format!("Probing {} accounts in parallel", candidates.len()),
+        None,
+    );
+
+    let mut in_flight = FuturesUnordered::new();
+    for (position, candidate) in candidates.iter().enumerate() {
+        let future = probe_fn(candidate.account.clone(), candidate.controller.signal());
+        in_flight.push(async move { (position, future.await) });
+    }
+
+    while let Some((position, result)) = in_flight.next().await {
+        match result {
+            Ok(response) => {
+                let account = candidates[position].account.clone();
+                log.debug(
+                    &format!(
+                        "Parallel probe succeeded with account {}",
+                        account.index + 1
+                    ),
+                    None,
+                );
+                for candidate in candidates {
+                    if candidate.account.index != account.index {
+                        candidate.controller.abort();
+                    }
+                }
+                // Dropping `in_flight` cancels the losing futures; their
+                // late results are ignored (TS: `then` sees the winner set).
+                return Some(ProbeResult::Success { account, response });
+            }
+            Err(_error) => {
+                // Losing rejections are swallowed; all-fail resolves None
+                // when the stream drains.
+            }
+        }
+    }
+
+    None
+}
+
+/// TS `createProbeCandidates(accounts)` — one fresh controller per account.
+pub fn create_probe_candidates(accounts: Vec<ManagedAccount>) -> Vec<ProbeCandidate> {
+    accounts
+        .into_iter()
+        .map(|account| ProbeCandidate {
+            account,
+            controller: ProbeAbortController::new(),
+        })
+        .collect()
+}
+
+// ============================================================================
+// Tests — ported from test/parallel-probe.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{
+        AccountMetadataV3, AccountStorageV3, RateLimitStateV3,
+    };
+
+    fn stored_account(refresh: &str, last_used: i64) -> AccountMetadataV3 {
+        AccountMetadataV3::new(refresh, now_ms() - 1_000, last_used)
+    }
+
+    fn manager_of(accounts: Vec<AccountMetadataV3>) -> AccountManager {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage.active_index = 0;
+        AccountManager::new(None, Some(&storage))
+    }
+
+    fn candidates_of(manager: &mut AccountManager) -> Vec<ProbeCandidate> {
+        create_probe_candidates(manager.get_accounts_snapshot())
+    }
+
+    // -- createProbeCandidates ----------------------------------------------
+
+    #[test]
+    fn creates_candidates_with_abort_controllers() {
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now_ms()),
+            stored_account("token-2", now_ms()),
+        ]);
+        let candidates = candidates_of(&mut manager);
+        assert_eq!(candidates.len(), 2);
+        for candidate in &candidates {
+            assert!(!candidate.controller.is_aborted());
+        }
+    }
+
+    // -- probeAccountsInParallel --------------------------------------------
+
+    #[tokio::test]
+    async fn returns_none_for_empty_candidates() {
+        let result: Option<ProbeResult<&str, String>> =
+            probe_accounts_in_parallel(&[], |_, _| async { Ok("unused") }, None).await;
+        assert!(result.is_none());
+    }
+
+    #[tokio::test]
+    async fn returns_success_for_single_candidate() {
+        let mut manager = manager_of(vec![stored_account("token-1", now_ms())]);
+        let candidates = candidates_of(&mut manager);
+        let result: Option<ProbeResult<&str, String>> =
+            probe_accounts_in_parallel(&candidates, |_, _| async { Ok("ok") }, None).await;
+        match result.expect("result") {
+            ProbeResult::Success { account, response } => {
+                assert_eq!(account.index, 0);
+                assert_eq!(response, "ok");
+            }
+            ProbeResult::Failure { .. } => panic!("expected success"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_failure_for_single_failing_candidate() {
+        let mut manager = manager_of(vec![stored_account("token-1", now_ms())]);
+        let candidates = candidates_of(&mut manager);
+        let result: Option<ProbeResult<&str, String>> = probe_accounts_in_parallel(
+            &candidates,
+            |_, _| async { Err("probe failed".to_string()) },
+            None,
+        )
+        .await;
+        match result.expect("result") {
+            ProbeResult::Failure { account, error } => {
+                assert_eq!(account.index, 0);
+                assert_eq!(error, "probe failed");
+            }
+            ProbeResult::Success { .. } => panic!("expected failure"),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_first_success_in_parallel_probing() {
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now_ms()),
+            stored_account("token-2", now_ms()),
+            stored_account("token-3", now_ms()),
+        ]);
+        let candidates = candidates_of(&mut manager);
+        // Account 1 (index 1) resolves fastest; 0 is slow; 2 fails fast.
+        let result: Option<ProbeResult<usize, String>> = probe_accounts_in_parallel(
+            &candidates,
+            |account, _signal| async move {
+                match account.index {
+                    0 => {
+                        tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+                        Ok(0)
+                    }
+                    1 => {
+                        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+                        Ok(1)
+                    }
+                    _ => Err("fast failure".to_string()),
+                }
+            },
+            None,
+        )
+        .await;
+        match result.expect("result") {
+            ProbeResult::Success { account, response } => {
+                assert_eq!(account.index, 1);
+                assert_eq!(response, 1);
+            }
+            ProbeResult::Failure { .. } => panic!("expected success"),
+        }
+    }
+
+    #[tokio::test]
+    async fn aborts_losing_candidates_after_winner_found() {
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now_ms()),
+            stored_account("token-2", now_ms()),
+        ]);
+        let candidates = candidates_of(&mut manager);
+        let result: Option<ProbeResult<usize, String>> = probe_accounts_in_parallel(
+            &candidates,
+            |account, signal| async move {
+                if account.index == 0 {
+                    Ok(0)
+                } else {
+                    // The loser waits on its abort signal.
+                    signal.cancelled().await;
+                    Err("aborted".to_string())
+                }
+            },
+            None,
+        )
+        .await;
+        assert!(result.expect("result").is_success());
+        assert!(!candidates[0].controller.is_aborted(), "winner not aborted");
+        assert!(candidates[1].controller.is_aborted(), "loser aborted");
+    }
+
+    #[tokio::test]
+    async fn returns_none_when_all_candidates_fail() {
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now_ms()),
+            stored_account("token-2", now_ms()),
+        ]);
+        let candidates = candidates_of(&mut manager);
+        let result: Option<ProbeResult<usize, String>> = probe_accounts_in_parallel(
+            &candidates,
+            |account, _| async move { Err(format!("failure {}", account.index)) },
+            None,
+        )
+        .await;
+        assert!(result.is_none(), "multi-candidate all-fail must be None");
+    }
+
+    #[tokio::test]
+    async fn options_parameter_is_accepted_and_ignored() {
+        let mut manager = manager_of(vec![stored_account("token-1", now_ms())]);
+        let candidates = candidates_of(&mut manager);
+        let options = ParallelProbeOptions {
+            max_concurrency: 1,
+            timeout_ms: 1,
+        };
+        let result: Option<ProbeResult<&str, String>> =
+            probe_accounts_in_parallel(&candidates, |_, _| async { Ok("ok") }, Some(&options))
+                .await;
+        assert!(result.expect("result").is_success());
+    }
+
+    // -- getTopCandidates ---------------------------------------------------
+
+    #[test]
+    fn returns_empty_array_when_no_accounts_available() {
+        let mut manager = manager_of(Vec::new());
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 3).expect("ok");
+        assert!(top.is_empty());
+    }
+
+    #[test]
+    fn returns_up_to_max_candidates_accounts() {
+        let now = now_ms();
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now),
+            stored_account("token-2", now),
+            stored_account("token-3", now),
+        ]);
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 2).expect("ok");
+        assert_eq!(top.len(), 2);
+    }
+
+    #[test]
+    fn filters_out_rate_limited_accounts() {
+        let now = now_ms();
+        let mut limited = stored_account("token-1", now);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", now + 60_000);
+        limited.rate_limit_reset_times = Some(times);
+        let mut manager = manager_of(vec![limited, stored_account("token-2", now)]);
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 5).expect("ok");
+        assert_eq!(top.len(), 1);
+        assert_eq!(top[0].meta.refresh_token, "token-2");
+    }
+
+    #[test]
+    fn expired_rate_limits_are_cleared_before_the_availability_check() {
+        let now = now_ms();
+        let mut expired = stored_account("token-1", now);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex", now - 60_000);
+        expired.rate_limit_reset_times = Some(times);
+        let mut manager = manager_of(vec![expired]);
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 5).expect("ok");
+        assert_eq!(top.len(), 1, "expired window must not exclude the account");
+    }
+
+    #[test]
+    fn filters_out_cooling_down_accounts() {
+        let now = now_ms();
+        let mut cooling = stored_account("token-1", now);
+        cooling.cooling_down_until = Some(now + 60_000);
+        let mut manager = manager_of(vec![cooling, stored_account("token-2", now)]);
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 5).expect("ok");
+        assert_eq!(top.len(), 1);
+        assert_eq!(top[0].meta.refresh_token, "token-2");
+    }
+
+    #[test]
+    fn returns_accounts_sorted_by_hybrid_score() {
+        let now = now_ms();
+        // Untracked accounts share the tracker maxima; only idle hours
+        // differentiate: older lastUsed → higher score.
+        let mut manager = manager_of(vec![
+            stored_account("token-1", now - 3_600_000),
+            stored_account("token-2", now - 10 * 3_600_000),
+            stored_account("token-3", now - 5 * 3_600_000),
+        ]);
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 3).expect("ok");
+        let order: Vec<&str> = top
+            .iter()
+            .map(|account| account.meta.refresh_token.as_str())
+            .collect();
+        assert_eq!(order, vec!["token-2", "token-3", "token-1"]);
+    }
+
+    #[test]
+    fn model_scoped_rate_limits_exclude_candidates_for_that_model() {
+        let now = now_ms();
+        let mut limited = stored_account("token-1", now);
+        let mut times = RateLimitStateV3::new();
+        times.insert("codex:gpt-5.3-codex", now + 60_000);
+        limited.rate_limit_reset_times = Some(times);
+        let mut manager = manager_of(vec![limited, stored_account("token-2", now)]);
+
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, Some("gpt-5.3-codex"), 5)
+            .expect("ok");
+        assert_eq!(top.len(), 1);
+        assert_eq!(top[0].meta.refresh_token, "token-2");
+
+        // Without the model scope only the base family key applies.
+        let top = get_top_candidates(&mut manager, ModelFamily::Codex, None, 5).expect("ok");
+        assert_eq!(top.len(), 2);
+    }
+
+    #[test]
+    fn rejects_non_positive_max_candidates_with_the_frozen_message() {
+        let mut manager = manager_of(vec![stored_account("token-1", now_ms())]);
+        let error =
+            get_top_candidates(&mut manager, ModelFamily::Codex, None, 0).expect_err("error");
+        assert_eq!(
+            error.message(),
+            "getTopCandidates requires maxCandidates to be a positive integer"
+        );
+    }
+}
diff --git a/crates/quota/src/preemptive_scheduler.rs b/crates/quota/src/preemptive_scheduler.rs
new file mode 100644
index 000000000..4eab9f27d
--- /dev/null
+++ b/crates/quota/src/preemptive_scheduler.rs
@@ -0,0 +1,913 @@
+//! Port of `lib/preemptive-quota-scheduler.ts` — in-memory per-key
+//! (`"{entitlementAccountKey}:{model ?? modelFamily}"`) request deferrals fed
+//! by upstream `x-codex-*` response headers.
+//!
+//! CRITICAL INVARIANTS (spec 05 §5 + gotchas 1/3/11):
+//! - State is **per-process, in-memory only**. It must NEVER be persisted
+//!   (same bug class as the 6.4.0 persisted-token-bucket regression), which is
+//!   why no type in this module implements `serde::Serialize`.
+//! - H4: `mark_rate_limited` only preserves a prior PRIMARY reset when that
+//!   prior primary was itself a rate-limit/exhausted window, and
+//!   `get_deferral`'s 429 branch filters windows through
+//!   [`is_rate_limit_window`] so a benign weekly secondary (~7d reset) never
+//!   benches an account for the full deferral cap on a transient 429.
+//! - The "rounded left-percent == 0" test (`quotaLeftPercentFromUsed(...) ===
+//!   0`) is used HERE ONLY. Everywhere else in the quota cluster exhaustion is
+//!   the RAW `usedPercent >= 100` predicate. Do NOT unify the two.
+
+use std::collections::HashMap;
+
+use cma_core::utils::now_ms;
+use reqwest::header::HeaderMap;
+
+use crate::readiness::quota_left_percent_from_used;
+
+/// TS `DEFAULT_REMAINING_PERCENT_THRESHOLD` (%).
+const DEFAULT_REMAINING_PERCENT_THRESHOLD: f64 = 5.0;
+/// TS `DEFAULT_MAX_DEFERRAL_MS` (2 h).
+const DEFAULT_MAX_DEFERRAL_MS: i64 = 2 * 60 * 60_000;
+/// Prune throttle: at most one prune per minute (TS `maybePrune`).
+const PRUNE_THROTTLE_MS: i64 = 60_000;
+
+/// TS `interface QuotaSchedulerWindow`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct QuotaSchedulerWindow {
+    pub used_percent: Option<f64>,
+    pub reset_at_ms: Option<i64>,
+}
+
+/// TS `interface QuotaSchedulerSnapshot`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaSchedulerSnapshot {
+    pub status: u16,
+    pub primary: QuotaSchedulerWindow,
+    pub secondary: QuotaSchedulerWindow,
+    pub updated_at: i64,
+}
+
+/// TS deferral `reason` union `"rate-limit" | "quota-near-exhaustion"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QuotaDeferralReason {
+    RateLimit,
+    QuotaNearExhaustion,
+}
+
+impl QuotaDeferralReason {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            QuotaDeferralReason::RateLimit => "rate-limit",
+            QuotaDeferralReason::QuotaNearExhaustion => "quota-near-exhaustion",
+        }
+    }
+}
+
+/// TS `interface QuotaDeferralDecision`.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct QuotaDeferralDecision {
+    pub defer: bool,
+    pub wait_ms: i64,
+    pub reason: Option<QuotaDeferralReason>,
+}
+
+impl QuotaDeferralDecision {
+    const fn no_defer() -> Self {
+        Self {
+            defer: false,
+            wait_ms: 0,
+            reason: None,
+        }
+    }
+}
+
+/// TS `interface QuotaSchedulerOptions` — every field optional; non-finite
+/// numbers are ignored exactly like the TS `Number.isFinite` guards.
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+pub struct QuotaSchedulerOptions {
+    pub enabled: Option<bool>,
+    pub remaining_percent_threshold_primary: Option<f64>,
+    pub remaining_percent_threshold_secondary: Option<f64>,
+    /// Legacy knob: `remaining = 100 - usedPercentThreshold` applied to BOTH
+    /// thresholds (then the specific fields override individually).
+    pub used_percent_threshold: Option<f64>,
+    pub max_deferral_ms: Option<f64>,
+}
+
+/// TS `clampInt(value, min, max)` = `max(min, min(max, floor(value)))`.
+fn clamp_int(value: f64, min: f64, max: f64) -> f64 {
+    value.floor().min(max).max(min)
+}
+
+/// TS `parseFiniteNumberHeader` — `Number(raw)` accepted when finite.
+/// (JS `Number` trims whitespace; empty/absent values are rejected first.)
+fn parse_finite_number_header(headers: &HeaderMap, name: &str) -> Option<f64> {
+    let raw = headers.get(name)?.to_str().ok()?;
+    if raw.is_empty() {
+        return None;
+    }
+    let parsed: f64 = raw.trim().parse().ok()?;
+    parsed.is_finite().then_some(parsed)
+}
+
+/// JS `Number.parseInt(raw, 10)` — leading whitespace + optional sign, then
+/// the longest ASCII-digit prefix; NaN when no digits.
+fn js_parse_int(raw: &str) -> Option<f64> {
+    let s = raw.trim_start();
+    let (negative, rest) = match s.as_bytes().first() {
+        Some(b'+') => (false, &s[1..]),
+        Some(b'-') => (true, &s[1..]),
+        _ => (false, s),
+    };
+    let digits: &str = {
+        let end = rest
+            .as_bytes()
+            .iter()
+            .position(|b| !b.is_ascii_digit())
+            .unwrap_or(rest.len());
+        &rest[..end]
+    };
+    if digits.is_empty() {
+        return None;
+    }
+    // Parse via f64 to mirror JS number semantics for huge values.
+    let value: f64 = digits.parse().ok()?;
+    Some(if negative { -value } else { value })
+}
+
+/// TS `parseFiniteIntHeader`.
+fn parse_finite_int_header(headers: &HeaderMap, name: &str) -> Option<f64> {
+    let raw = headers.get(name)?.to_str().ok()?;
+    if raw.is_empty() {
+        return None;
+    }
+    let parsed = js_parse_int(raw)?;
+    parsed.is_finite().then_some(parsed)
+}
+
+/// `Date.parse` subset for header values: RFC 2822 (HTTP date), RFC 3339 /
+/// ISO 8601 with offset, and bare `YYYY-MM-DD` (UTC midnight per ES2015+).
+fn js_date_parse_ms(trimmed: &str) -> Option<i64> {
+    if let Ok(dt) = chrono::DateTime::parse_from_rfc2822(trimmed) {
+        return Some(dt.timestamp_millis());
+    }
+    if let Ok(dt) = chrono::DateTime::parse_from_rfc3339(trimmed) {
+        return Some(dt.timestamp_millis());
+    }
+    if let Ok(date) = chrono::NaiveDate::parse_from_str(trimmed, "%Y-%m-%d") {
+        let dt = date.and_hms_opt(0, 0, 0)?.and_utc();
+        return Some(dt.timestamp_millis());
+    }
+    None
+}
+
+/// TS `parseResetAtMs(headers, prefix, now)` — `{prefix}-reset-after-seconds`
+/// (relative, from the CALLER-SUPPLIED `now`, not the wall clock) wins when
+/// `> 0`; otherwise `{prefix}-reset-at` as all-digits epoch (values
+/// `< 10_000_000_000` are seconds) or a parseable date string.
+fn parse_reset_at_ms(headers: &HeaderMap, prefix: &str, now: i64) -> Option<i64> {
+    if let Some(reset_after_seconds) = parse_finite_int_header(headers, &format!("{prefix}-reset-after-seconds"))
+        && reset_after_seconds > 0.0
+    {
+        return Some(now.saturating_add((reset_after_seconds * 1000.0) as i64));
+    }
+    let raw = headers.get(format!("{prefix}-reset-at"))?.to_str().ok()?;
+    if raw.is_empty() {
+        return None;
+    }
+    let trimmed = raw.trim();
+    if !trimmed.is_empty()
+        && trimmed.bytes().all(|b| b.is_ascii_digit())
+        && let Ok(parsed) = trimmed.parse::<f64>()
+        && parsed.is_finite()
+        && parsed > 0.0
+    {
+        return Some(if parsed < 10_000_000_000.0 {
+            (parsed * 1000.0) as i64
+        } else {
+            parsed as i64
+        });
+    }
+    js_date_parse_ms(trimmed)
+}
+
+/// TS `readQuotaSchedulerSnapshot(headers, status, now = Date.now())` — parses
+/// ONLY the used-percent/reset signals for both windows; `None` unless at
+/// least one of the four values parsed. `updated_at = now`.
+pub fn read_quota_scheduler_snapshot(
+    headers: &HeaderMap,
+    status: u16,
+    now: i64,
+) -> Option<QuotaSchedulerSnapshot> {
+    const PRIMARY_PREFIX: &str = "x-codex-primary";
+    const SECONDARY_PREFIX: &str = "x-codex-secondary";
+    let primary_used = parse_finite_number_header(headers, &format!("{PRIMARY_PREFIX}-used-percent"));
+    let secondary_used =
+        parse_finite_number_header(headers, &format!("{SECONDARY_PREFIX}-used-percent"));
+    let primary_reset_at = parse_reset_at_ms(headers, PRIMARY_PREFIX, now);
+    let secondary_reset_at = parse_reset_at_ms(headers, SECONDARY_PREFIX, now);
+
+    let has_signal = primary_used.is_some()
+        || secondary_used.is_some()
+        || primary_reset_at.is_some()
+        || secondary_reset_at.is_some();
+    if !has_signal {
+        return None;
+    }
+
+    Some(QuotaSchedulerSnapshot {
+        status,
+        primary: QuotaSchedulerWindow {
+            used_percent: primary_used,
+            reset_at_ms: primary_reset_at,
+        },
+        secondary: QuotaSchedulerWindow {
+            used_percent: secondary_used,
+            reset_at_ms: secondary_reset_at,
+        },
+        updated_at: now,
+    })
+}
+
+/// H4 helper: a window counts toward a 429 deferral only when it is genuinely
+/// a rate-limit / exhaustion window — no finite `usedPercent` at all, or a
+/// ROUNDED left percent of 0 (this is the one place the rounded helper is the
+/// correct predicate; see module docs).
+fn is_rate_limit_window(window: &QuotaSchedulerWindow) -> bool {
+    match window.used_percent {
+        Some(used) if used.is_finite() => quota_left_percent_from_used(Some(used)) == Some(0),
+        _ => true,
+    }
+}
+
+/// TS `class PreemptiveQuotaScheduler` — in-memory, never persisted.
+#[derive(Debug)]
+pub struct PreemptiveQuotaScheduler {
+    snapshots: HashMap<String, QuotaSchedulerSnapshot>,
+    enabled: bool,
+    primary_remaining_percent_threshold: f64,
+    secondary_remaining_percent_threshold: f64,
+    max_deferral_ms: i64,
+    last_prune_at: i64,
+}
+
+impl Default for PreemptiveQuotaScheduler {
+    fn default() -> Self {
+        Self::new(QuotaSchedulerOptions::default())
+    }
+}
+
+impl PreemptiveQuotaScheduler {
+    /// TS constructor — defaults, then `configure(options)`.
+    pub fn new(options: QuotaSchedulerOptions) -> Self {
+        let mut scheduler = Self {
+            snapshots: HashMap::new(),
+            enabled: true,
+            primary_remaining_percent_threshold: DEFAULT_REMAINING_PERCENT_THRESHOLD,
+            secondary_remaining_percent_threshold: DEFAULT_REMAINING_PERCENT_THRESHOLD,
+            max_deferral_ms: DEFAULT_MAX_DEFERRAL_MS,
+            last_prune_at: 0,
+        };
+        scheduler.configure(options);
+        scheduler
+    }
+
+    /// TS `configure(options)` — legacy `usedPercentThreshold` derives BOTH
+    /// remaining thresholds first, then the specific primary/secondary values
+    /// override individually. `maxDeferralMs` is floored with a 1s floor.
+    pub fn configure(&mut self, options: QuotaSchedulerOptions) {
+        if let Some(enabled) = options.enabled {
+            self.enabled = enabled;
+        }
+
+        if let Some(legacy) = options.used_percent_threshold
+            && legacy.is_finite()
+        {
+            let clamped_used = clamp_int(legacy, 0.0, 100.0);
+            let derived_remaining = clamp_int(100.0 - clamped_used, 0.0, 100.0);
+            self.primary_remaining_percent_threshold = derived_remaining;
+            self.secondary_remaining_percent_threshold = derived_remaining;
+        }
+
+        if let Some(primary) = options.remaining_percent_threshold_primary
+            && primary.is_finite()
+        {
+            self.primary_remaining_percent_threshold = clamp_int(primary, 0.0, 100.0);
+        }
+
+        if let Some(secondary) = options.remaining_percent_threshold_secondary
+            && secondary.is_finite()
+        {
+            self.secondary_remaining_percent_threshold = clamp_int(secondary, 0.0, 100.0);
+        }
+
+        if let Some(max_deferral_ms) = options.max_deferral_ms
+            && max_deferral_ms.is_finite()
+        {
+            self.max_deferral_ms = (max_deferral_ms.floor() as i64).max(1_000);
+        }
+    }
+
+    /// TS `maybePrune(now)` — throttled to once per 60 s.
+    fn maybe_prune(&mut self, now: i64) {
+        if now - self.last_prune_at < PRUNE_THROTTLE_MS {
+            return;
+        }
+        self.prune(now);
+        self.last_prune_at = now;
+    }
+
+    /// TS `update(key, snapshot)` — whole-snapshot replace; no-op on empty
+    /// key. The prune probe uses `snapshot.updatedAt || Date.now()` (falsy
+    /// zero falls back to the wall clock).
+    pub fn update(&mut self, key: &str, snapshot: QuotaSchedulerSnapshot) {
+        if key.is_empty() {
+            return;
+        }
+        let prune_now = if snapshot.updated_at != 0 {
+            snapshot.updated_at
+        } else {
+            now_ms()
+        };
+        self.maybe_prune(prune_now);
+        self.snapshots.insert(key.to_string(), snapshot);
+    }
+
+    /// TS `markRateLimited(key, retryAfterMs, now = Date.now())`.
+    ///
+    /// Stress-audit H4 fix — do not regress: a 429 retry-after defines the
+    /// PRIMARY rate-limit window only. A prior primary reset is preserved
+    /// ONLY when that prior primary was itself a rate-limit/exhausted window
+    /// (no finite usedPercent, or rounded left == 0); a healthy primary from
+    /// an earlier 200 snapshot must NOT extend the bench. The secondary
+    /// window is carried as-is (it is filtered at read time).
+    pub fn mark_rate_limited(&mut self, key: &str, retry_after_ms: f64, now: i64) {
+        if key.is_empty() {
+            return;
+        }
+        let wait_ms = if retry_after_ms.is_finite() {
+            (retry_after_ms.floor() as i64).max(0)
+        } else {
+            0
+        };
+        let existing = self.snapshots.get(key);
+        let existing_primary = existing.map(|snapshot| &snapshot.primary);
+        let existing_primary_is_rate_limit =
+            existing_primary.is_some_and(is_rate_limit_window);
+        let existing_primary_reset_at_ms = if existing_primary_is_rate_limit {
+            existing_primary.and_then(|window| window.reset_at_ms).unwrap_or(0)
+        } else {
+            0
+        };
+        let next_reset_at_ms = existing_primary_reset_at_ms.max(now.saturating_add(wait_ms));
+        let secondary = existing
+            .map(|snapshot| snapshot.secondary.clone())
+            .unwrap_or_default();
+        let updated_at = existing.map(|snapshot| snapshot.updated_at).unwrap_or(0).max(now);
+        self.snapshots.insert(
+            key.to_string(),
+            QuotaSchedulerSnapshot {
+                status: 429,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(100.0),
+                    reset_at_ms: Some(next_reset_at_ms),
+                },
+                secondary,
+                updated_at,
+            },
+        );
+    }
+
+    /// TS `getDeferral(key, now = Date.now())`.
+    pub fn get_deferral(&mut self, key: &str, now: i64) -> QuotaDeferralDecision {
+        self.maybe_prune(now);
+        if !self.enabled {
+            return QuotaDeferralDecision::no_defer();
+        }
+
+        let Some(snapshot) = self.snapshots.get(key) else {
+            return QuotaDeferralDecision::no_defer();
+        };
+
+        let window_wait = |window: &QuotaSchedulerWindow| -> i64 {
+            match window.reset_at_ms {
+                Some(reset_at) if reset_at > now => reset_at - now,
+                _ => 0,
+            }
+        };
+        let primary_wait = window_wait(&snapshot.primary);
+        let secondary_wait = window_wait(&snapshot.secondary);
+
+        // 429 branch (H4): only windows that are genuinely rate-limit /
+        // exhaustion windows contribute; a benign secondary at e.g. 30% used
+        // from a prior 200 snapshot is excluded so a transient 429 never
+        // benches the account for the full deferral cap.
+        let longest_wait = [&snapshot.primary, &snapshot.secondary]
+            .into_iter()
+            .filter(|window| is_rate_limit_window(window))
+            .filter_map(|window| window.reset_at_ms)
+            .filter(|reset_at| *reset_at > now)
+            .map(|reset_at| reset_at - now)
+            .filter(|wait| *wait > 0)
+            .max()
+            .unwrap_or(0);
+
+        if snapshot.status == 429 && longest_wait > 0 {
+            let bounded = longest_wait.min(self.max_deferral_ms);
+            if bounded > 0 {
+                return QuotaDeferralDecision {
+                    defer: true,
+                    wait_ms: bounded,
+                    reason: Some(QuotaDeferralReason::RateLimit),
+                };
+            }
+        }
+
+        // Near-exhaustion branch (any status): a window is near-exhausted iff
+        // its finite usedPercent >= 100 - threshold (per-window thresholds).
+        let near_exhausted = |window: &QuotaSchedulerWindow, threshold: f64| -> bool {
+            window
+                .used_percent
+                .is_some_and(|used| used.is_finite() && used >= 100.0 - threshold)
+        };
+        let primary_near = near_exhausted(&snapshot.primary, self.primary_remaining_percent_threshold);
+        let secondary_near =
+            near_exhausted(&snapshot.secondary, self.secondary_remaining_percent_threshold);
+        let near_exhausted_wait = i64::max(
+            if primary_near { primary_wait } else { 0 },
+            if secondary_near { secondary_wait } else { 0 },
+        );
+        if near_exhausted_wait > 0 {
+            let bounded = near_exhausted_wait.min(self.max_deferral_ms);
+            if bounded > 0 {
+                return QuotaDeferralDecision {
+                    defer: true,
+                    wait_ms: bounded,
+                    reason: Some(QuotaDeferralReason::QuotaNearExhaustion),
+                };
+            }
+        }
+
+        QuotaDeferralDecision::no_defer()
+    }
+
+    /// TS `prune(now = Date.now())` — removes entries whose latest reset
+    /// (`max(primary, secondary)`, absent = 0) is `> 0 && <= now`. Entries
+    /// with NO reset timestamps are kept forever (accepted bounded leak).
+    pub fn prune(&mut self, now: i64) -> usize {
+        let before = self.snapshots.len();
+        self.snapshots.retain(|_, snapshot| {
+            let latest_reset = i64::max(
+                snapshot.primary.reset_at_ms.unwrap_or(0),
+                snapshot.secondary.reset_at_ms.unwrap_or(0),
+            );
+            !(latest_reset > 0 && latest_reset <= now)
+        });
+        before - self.snapshots.len()
+    }
+
+    /// Test/diagnostic access to a stored snapshot (mirrors the TS tests'
+    /// reflective `snapshots` map access; read-only).
+    #[doc(hidden)]
+    pub fn snapshot_for_key(&self, key: &str) -> Option<&QuotaSchedulerSnapshot> {
+        self.snapshots.get(key)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.insert(
+                name.parse::<HeaderName>().unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn reads_quota_snapshot_from_codex_headers() {
+        let headers = headers(&[
+            ("x-codex-primary-used-percent", "99"),
+            ("x-codex-primary-reset-after-seconds", "120"),
+            ("x-codex-secondary-used-percent", "10"),
+        ]);
+        let snapshot = read_quota_scheduler_snapshot(&headers, 200, 1_000).expect("snapshot");
+        assert_eq!(snapshot.status, 200);
+        assert_eq!(snapshot.primary.used_percent, Some(99.0));
+        assert!(snapshot.primary.reset_at_ms.unwrap() > 1_000);
+    }
+
+    #[test]
+    fn uses_provided_now_when_parsing_reset_after_seconds() {
+        let headers = headers(&[("x-codex-primary-reset-after-seconds", "120")]);
+        let snapshot = read_quota_scheduler_snapshot(&headers, 200, 5_000).expect("snapshot");
+        assert_eq!(snapshot.primary.reset_at_ms, Some(125_000));
+    }
+
+    #[test]
+    fn returns_none_when_quota_headers_present_but_invalid() {
+        let headers = headers(&[
+            ("x-codex-primary-used-percent", "not-a-number"),
+            ("x-codex-primary-reset-after-seconds", "oops"),
+            ("x-codex-primary-reset-at", "not-a-date"),
+            ("x-codex-secondary-reset-at", "still-not-a-date"),
+        ]);
+        assert!(read_quota_scheduler_snapshot(&headers, 200, 5_000).is_none());
+    }
+
+    #[test]
+    fn parses_reset_at_as_epoch_seconds_milliseconds_and_http_date() {
+        let snapshot = read_quota_scheduler_snapshot(
+            &headers(&[
+                ("x-codex-primary-reset-at", "1700000000"),
+                ("x-codex-secondary-reset-at", "1700000000000"),
+            ]),
+            200,
+            0,
+        )
+        .expect("snapshot");
+        assert_eq!(snapshot.primary.reset_at_ms, Some(1_700_000_000_000));
+        assert_eq!(snapshot.secondary.reset_at_ms, Some(1_700_000_000_000));
+
+        // Date.parse("Tue, 14 Nov 2023 22:13:20 GMT") === 1_700_000_000_000.
+        let date_snapshot = read_quota_scheduler_snapshot(
+            &headers(&[("x-codex-primary-reset-at", "Tue, 14 Nov 2023 22:13:20 GMT")]),
+            200,
+            0,
+        )
+        .expect("snapshot");
+        assert_eq!(date_snapshot.primary.reset_at_ms, Some(1_700_000_000_000));
+    }
+
+    #[test]
+    fn defers_requests_for_known_429_window() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.mark_rate_limited("acc:model", 30_000.0, 1_000);
+
+        let decision = scheduler.get_deferral("acc:model", 2_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::RateLimit));
+        assert!(decision.wait_ms > 0);
+    }
+
+    #[test]
+    fn preserves_longest_known_rate_limit_reset_across_overlapping_updates() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.mark_rate_limited("acc:model", 30_000.0, 1_000);
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 429,
+                primary: QuotaSchedulerWindow::default(),
+                secondary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(31_000),
+                },
+                updated_at: 1_000,
+            },
+        );
+        scheduler.mark_rate_limited("acc:model", 10_000.0, 5_000);
+
+        let decision = scheduler.get_deferral("acc:model", 6_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::RateLimit));
+        assert_eq!(decision.wait_ms, 25_000);
+    }
+
+    #[test]
+    fn uses_longest_active_reset_window_for_429_deferrals() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 429,
+                primary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(31_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(61_000),
+                },
+                updated_at: 1_000,
+            },
+        );
+
+        let decision = scheduler.get_deferral("acc:model", 6_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::RateLimit));
+        assert_eq!(decision.wait_ms, 55_000);
+    }
+
+    #[test]
+    fn preserves_secondary_near_exhaustion_state_when_marking_rate_limited() {
+        let mut scheduler = PreemptiveQuotaScheduler::new(QuotaSchedulerOptions {
+            remaining_percent_threshold_secondary: Some(5.0),
+            ..Default::default()
+        });
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(10.0),
+                    reset_at_ms: Some(0),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: Some(97.0),
+                    reset_at_ms: Some(61_000),
+                },
+                updated_at: 1_000,
+            },
+        );
+        scheduler.mark_rate_limited("acc:model", 30_000.0, 1_000);
+        let stored = scheduler.snapshot_for_key("acc:model").expect("snapshot");
+        assert_eq!(stored.secondary.used_percent, Some(97.0));
+        assert_eq!(stored.secondary.reset_at_ms, Some(61_000));
+    }
+
+    #[test]
+    fn sanitizes_non_finite_retry_after_values() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.mark_rate_limited("acc:model", f64::NAN, 1_000);
+        assert!(!scheduler.get_deferral("acc:model", 1_000).defer);
+
+        scheduler.mark_rate_limited("acc:model", f64::INFINITY, 2_000);
+        assert!(!scheduler.get_deferral("acc:model", 2_000).defer);
+
+        scheduler.mark_rate_limited("acc:model", -1234.0, 3_000);
+        assert!(!scheduler.get_deferral("acc:model", 3_000).defer);
+    }
+
+    #[test]
+    fn defers_when_usage_near_exhaustion_and_reset_pending() {
+        let mut scheduler = PreemptiveQuotaScheduler::new(QuotaSchedulerOptions {
+            used_percent_threshold: Some(95.0),
+            ..Default::default()
+        });
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(97.0),
+                    reset_at_ms: Some(70_000),
+                },
+                secondary: QuotaSchedulerWindow::default(),
+                updated_at: 10_000,
+            },
+        );
+
+        let decision = scheduler.get_deferral("acc:model", 20_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::QuotaNearExhaustion));
+    }
+
+    #[test]
+    fn uses_longest_near_exhausted_reset_window_for_quota_deferrals() {
+        let mut scheduler = PreemptiveQuotaScheduler::new(QuotaSchedulerOptions {
+            remaining_percent_threshold_primary: Some(5.0),
+            remaining_percent_threshold_secondary: Some(5.0),
+            ..Default::default()
+        });
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(96.0),
+                    reset_at_ms: Some(70_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: Some(97.0),
+                    reset_at_ms: Some(120_000),
+                },
+                updated_at: 10_000,
+            },
+        );
+
+        let decision = scheduler.get_deferral("acc:model", 20_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::QuotaNearExhaustion));
+        assert_eq!(decision.wait_ms, 100_000);
+    }
+
+    #[test]
+    fn prunes_expired_snapshots() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.update(
+            "a",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(1_500),
+                },
+                secondary: QuotaSchedulerWindow::default(),
+                updated_at: 1_000,
+            },
+        );
+        scheduler.update(
+            "b",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(20_000),
+                },
+                secondary: QuotaSchedulerWindow::default(),
+                updated_at: 1_000,
+            },
+        );
+
+        assert_eq!(scheduler.prune(2_000), 1);
+        assert!(!scheduler.get_deferral("a", 2_100).defer);
+        assert!(!scheduler.get_deferral("b", 2_100).defer);
+    }
+
+    #[test]
+    fn uses_separate_primary_and_secondary_remaining_thresholds() {
+        let mut scheduler = PreemptiveQuotaScheduler::new(QuotaSchedulerOptions {
+            remaining_percent_threshold_primary: Some(10.0),
+            remaining_percent_threshold_secondary: Some(2.0),
+            ..Default::default()
+        });
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(91.0),
+                    reset_at_ms: Some(65_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: Some(97.0),
+                    reset_at_ms: Some(66_000),
+                },
+                updated_at: 1_000,
+            },
+        );
+
+        let decision = scheduler.get_deferral("acc:model", 5_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::QuotaNearExhaustion));
+    }
+
+    #[test]
+    fn can_disable_preemptive_deferral_without_clearing_snapshots() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.mark_rate_limited("acc:model", 30_000.0, 1_000);
+        assert!(scheduler.get_deferral("acc:model", 2_000).defer);
+
+        scheduler.configure(QuotaSchedulerOptions {
+            enabled: Some(false),
+            ..Default::default()
+        });
+        assert!(!scheduler.get_deferral("acc:model", 2_000).defer);
+
+        scheduler.configure(QuotaSchedulerOptions {
+            enabled: Some(true),
+            ..Default::default()
+        });
+        assert!(scheduler.get_deferral("acc:model", 2_000).defer);
+    }
+
+    #[test]
+    fn ignores_empty_keys_and_falls_back_when_updated_at_is_falsy() {
+        let now = now_ms();
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+
+        scheduler.update(
+            "",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(99.0),
+                    reset_at_ms: Some(now + 60_000),
+                },
+                secondary: QuotaSchedulerWindow::default(),
+                updated_at: now,
+            },
+        );
+        scheduler.mark_rate_limited("", 30_000.0, now);
+        assert_eq!(
+            scheduler.get_deferral("", now + 1_000),
+            QuotaDeferralDecision::no_defer()
+        );
+
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 429,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(100.0),
+                    reset_at_ms: Some(now + 45_000),
+                },
+                secondary: QuotaSchedulerWindow::default(),
+                updated_at: 0,
+            },
+        );
+        let decision = scheduler.get_deferral("acc:model", now + 5_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::RateLimit));
+    }
+
+    #[test]
+    fn prunes_using_latest_reset_from_primary_or_secondary() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        scheduler.update(
+            "keep",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(1_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(7_000),
+                },
+                updated_at: 0,
+            },
+        );
+        scheduler.update(
+            "drop",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(1_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: None,
+                    reset_at_ms: Some(1_500),
+                },
+                updated_at: 0,
+            },
+        );
+
+        assert_eq!(scheduler.prune(2_000), 1);
+        assert_eq!(scheduler.prune(8_000), 1);
+    }
+
+    #[test]
+    fn h4_transient_429_does_not_bench_account_on_benign_weekly_window() {
+        let mut scheduler = PreemptiveQuotaScheduler::default();
+        let now: i64 = 1_000_000;
+        let week_ms: i64 = 7 * 24 * 60 * 60 * 1000;
+        // Healthy 200 snapshot: primary fine, weekly secondary resets ~7d out.
+        scheduler.update(
+            "acc:model",
+            QuotaSchedulerSnapshot {
+                status: 200,
+                primary: QuotaSchedulerWindow {
+                    used_percent: Some(20.0),
+                    reset_at_ms: Some(now + 5 * 60_000),
+                },
+                secondary: QuotaSchedulerWindow {
+                    used_percent: Some(30.0),
+                    reset_at_ms: Some(now + week_ms),
+                },
+                updated_at: now,
+            },
+        );
+        // Transient 60s 429.
+        scheduler.mark_rate_limited("acc:model", 60_000.0, now);
+        let decision = scheduler.get_deferral("acc:model", now + 1_000);
+        assert!(decision.defer);
+        assert_eq!(decision.reason, Some(QuotaDeferralReason::RateLimit));
+        // Must reflect the ~60s retry window, NOT the 7d weekly reset (which
+        // would clamp to the 2h deferral cap). Allow the remaining ~59s.
+        assert!(decision.wait_ms <= 60_000);
+        assert!(decision.wait_ms > 50_000);
+        // After the 429 window passes, no longer rate-limit-deferred.
+        let after = scheduler.get_deferral("acc:model", now + 61_000);
+        assert_ne!(after.reason, Some(QuotaDeferralReason::RateLimit));
+    }
+
+    #[test]
+    fn rate_limit_window_uses_rounded_left_percent_boundary() {
+        // The scheduler is the ONE place the rounded left-percent (readiness
+        // `quotaLeftPercentFromUsed`) decides rate-limit-window membership.
+        let window = |used: Option<f64>| QuotaSchedulerWindow {
+            used_percent: used,
+            reset_at_ms: None,
+        };
+        // 99.6 used -> 0.4 left -> rounds to 0 -> rate-limit window.
+        assert!(is_rate_limit_window(&window(Some(99.6))));
+        // 99.5 used -> 0.5 left -> JS Math.round(0.5) === 1 -> NOT zero.
+        assert!(!is_rate_limit_window(&window(Some(99.5))));
+        // Over-100 usage clamps to 0 left.
+        assert!(is_rate_limit_window(&window(Some(100.4))));
+        assert!(is_rate_limit_window(&window(Some(250.0))));
+        // Absent / non-finite usedPercent always counts.
+        assert!(is_rate_limit_window(&window(None)));
+        assert!(is_rate_limit_window(&window(Some(f64::NAN))));
+        // Healthy usage never counts.
+        assert!(!is_rate_limit_window(&window(Some(30.0))));
+    }
+}
diff --git a/crates/quota/src/probe.rs b/crates/quota/src/probe.rs
new file mode 100644
index 000000000..0c18d5104
--- /dev/null
+++ b/crates/quota/src/probe.rs
@@ -0,0 +1,1141 @@
+//! Port of `lib/quota-probe.ts` — a live (cheap) streaming POST against the
+//! Codex backend that parses `x-codex-*` response headers into a
+//! [`CodexQuotaSnapshot`].
+//!
+//! Contracts (spec 05 §2 + gotchas 12/13/14):
+//! - Models are probed SEQUENTIALLY over the 6-model chain (Sol first).
+//! - A response with quota headers produces a snapshot on ANY status —
+//!   a 429 with headers still parses (status recorded verbatim).
+//! - Unsupported-model errors continue down the chain; when EVERY attempted
+//!   model was unsupported (and nothing else failed) the probe fails with a
+//!   `CodexUnavailableError` rendered as
+//!   `"Codex not available for this account"` (issue #501).
+//! - Reasoning effort is model-dependent (`low` for 5.6/codex tiers, `none`
+//!   for pre-5.6 general models — issue #627).
+//! - Every model attempt increments the diagnostic-probe observability
+//!   counters (both snapshot top-level and `runtimeMetrics`); the TS calls
+//!   `mutateRuntimeObservabilitySnapshot` directly, but that module lives in
+//!   `cma-runtime` ABOVE this crate, so the Rust port exposes a hook seam
+//!   ([`set_probe_observability_hook`]) that `cma-runtime` registers.
+
+use std::sync::{Arc, RwLock};
+
+use chrono::TimeZone;
+use cma_core::constants::CODEX_BASE_URL;
+use cma_core::errors::CodexError;
+use cma_core::json_io::stringify_compact;
+use cma_core::utils::{is_record, now_ms};
+use cma_request::error_classification::get_unsupported_codex_model_info;
+use cma_request::fetch_helpers::shared_client;
+use cma_request::headers::{CreateCodexHeadersOptions, create_codex_headers_positional};
+use cma_request::model_map::{QUOTA_PROBE_MODEL_CHAIN, resolve_probe_reasoning_effort};
+use cma_request::prompts::codex::get_codex_instructions;
+use reqwest::header::{HeaderMap, HeaderValue};
+use serde::Serialize;
+use serde_json::{Value, json};
+
+/// Human-readable note shown when a live probe fails solely because the
+/// account lacks Codex entitlement (see `CodexUnavailableError`). Centralized
+/// so every check/forecast/repair surface renders the same wording instead of
+/// leaking the raw upstream "model is not supported..." message (issue #501).
+pub const CODEX_UNAVAILABLE_PROBE_NOTE: &str = "Codex not available for this account";
+
+/// TS `describeCodexProbeFailure(error, normalize?)` — the friendly note for
+/// `CodexUnavailableError` (matched by CODE, cross-realm safe); otherwise the
+/// (optionally normalized) raw message.
+pub fn describe_codex_probe_failure(
+    error: &CodexError,
+    normalize: Option<&dyn Fn(&str) -> String>,
+) -> String {
+    if error.is_codex_unavailable() {
+        return CODEX_UNAVAILABLE_PROBE_NOTE.to_string();
+    }
+    let raw = error.message();
+    match normalize {
+        Some(normalize) => normalize(raw),
+        None => raw.to_string(),
+    }
+}
+
+/// TS `CodexQuotaWindow` — parsed from response headers: `usedPercent` is a
+/// float (fractional percentages are expected and significant),
+/// `windowMinutes` a `parseInt` integer, `resetAtMs` an absolute epoch-ms
+/// timestamp.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize)]
+pub struct CodexQuotaWindow {
+    #[serde(rename = "usedPercent", skip_serializing_if = "Option::is_none")]
+    pub used_percent: Option<f64>,
+    #[serde(rename = "windowMinutes", skip_serializing_if = "Option::is_none")]
+    pub window_minutes: Option<i64>,
+    #[serde(rename = "resetAtMs", skip_serializing_if = "Option::is_none")]
+    pub reset_at_ms: Option<i64>,
+}
+
+/// TS `CodexQuotaSnapshot`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct CodexQuotaSnapshot {
+    pub status: u16,
+    #[serde(rename = "planType", skip_serializing_if = "Option::is_none")]
+    pub plan_type: Option<String>,
+    #[serde(rename = "activeLimit", skip_serializing_if = "Option::is_none")]
+    pub active_limit: Option<i64>,
+    pub primary: CodexQuotaWindow,
+    pub secondary: CodexQuotaWindow,
+    pub model: String,
+}
+
+/// TS `ProbeCodexQuotaOptions`.
+#[derive(Clone, Debug, Default)]
+pub struct ProbeCodexQuotaOptions {
+    pub account_id: String,
+    pub access_token: String,
+    /// Preferred model to try first (prepended to the fallback chain).
+    pub model: Option<String>,
+    /// Fallback models; `None` = [`QUOTA_PROBE_MODEL_CHAIN`].
+    pub fallback_models: Option<Vec<String>>,
+    /// Per-model timeout, clamped to `[1_000, 60_000]`; default `15_000`.
+    pub timeout_ms: Option<u64>,
+    /// Rust-only test seam: overrides `CODEX_BASE_URL` (the TS module
+    /// hardcodes it and tests stub global `fetch`; Rust tests point this at
+    /// a wiremock server instead). `None` in production.
+    pub base_url: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Observability hook (see module docs)
+// ---------------------------------------------------------------------------
+
+type ProbeObservabilityHook = Arc<dyn Fn() + Send + Sync>;
+
+static PROBE_OBSERVABILITY_HOOK: RwLock<Option<ProbeObservabilityHook>> = RwLock::new(None);
+
+/// Register (or clear) the per-attempt observability hook. `cma-runtime`
+/// installs a closure that increments `diagnosticProbeRequests` on BOTH the
+/// snapshot top level and `runtimeMetrics` (spec 05 gotcha 14). Invoked once
+/// per MODEL attempt, not per `fetch_codex_quota_snapshot` call.
+pub fn set_probe_observability_hook(hook: Option<ProbeObservabilityHook>) {
+    *PROBE_OBSERVABILITY_HOOK
+        .write()
+        .unwrap_or_else(|poisoned| poisoned.into_inner()) = hook;
+}
+
+fn note_probe_attempt() {
+    let hook = PROBE_OBSERVABILITY_HOOK
+        .read()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .clone();
+    if let Some(hook) = hook {
+        hook();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Header parsing (must be replicated exactly)
+// ---------------------------------------------------------------------------
+
+fn header_str<'h>(headers: &'h HeaderMap, name: &str) -> Option<&'h str> {
+    headers.get(name).and_then(|value| value.to_str().ok())
+}
+
+/// JS `Number(raw)` restricted to what quota headers realistically carry:
+/// trims whitespace, accepts decimal/exponent floats; empty-after-trim is `0`
+/// (JS `Number("")`/`Number(" ")` are `0`, but the callers gate on a
+/// non-empty RAW value first). Non-finite results are rejected by callers.
+fn js_number(raw: &str) -> Option<f64> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return Some(0.0);
+    }
+    match trimmed {
+        "Infinity" | "+Infinity" => return Some(f64::INFINITY),
+        "-Infinity" => return Some(f64::NEG_INFINITY),
+        _ => {}
+    }
+    trimmed.parse::<f64>().ok()
+}
+
+/// JS `Number.parseInt(raw, 10)` — leading whitespace skipped, optional
+/// sign, maximal leading digit run, trailing garbage ignored; no digits →
+/// `None` (NaN).
+fn js_parse_int(raw: &str) -> Option<i64> {
+    let trimmed = raw.trim_start();
+    let (negative, digits_part) = match trimmed.strip_prefix('-') {
+        Some(rest) => (true, rest),
+        None => (false, trimmed.strip_prefix('+').unwrap_or(trimmed)),
+    };
+    let digit_run: String = digits_part
+        .chars()
+        .take_while(|c| c.is_ascii_digit())
+        .collect();
+    if digit_run.is_empty() {
+        return None;
+    }
+    // Saturate on overflow (JS would keep float precision; quota headers
+    // never approach i64::MAX).
+    let value = digit_run.parse::<i64>().unwrap_or(i64::MAX);
+    Some(if negative { -value } else { value })
+}
+
+/// TS `parseFiniteNumberHeader` — missing/empty header → `None`;
+/// `Number(raw)` accepted only when finite (floats allowed).
+fn parse_finite_number_header(headers: &HeaderMap, name: &str) -> Option<f64> {
+    let raw = header_str(headers, name)?;
+    if raw.is_empty() {
+        return None;
+    }
+    js_number(raw).filter(|parsed| parsed.is_finite())
+}
+
+/// TS `parseFiniteIntHeader` — missing/empty header → `None`;
+/// `parseInt(raw, 10)` accepted when finite.
+fn parse_finite_int_header(headers: &HeaderMap, name: &str) -> Option<i64> {
+    let raw = header_str(headers, name)?;
+    if raw.is_empty() {
+        return None;
+    }
+    js_parse_int(raw)
+}
+
+/// The subset of JS `Date.parse` the quota `-reset-at` header can carry once
+/// the all-digits fast path has been tried: RFC 3339 / ISO 8601 (with zone),
+/// RFC 2822 (HTTP dates), date-only ISO (UTC midnight per ECMA-262), and
+/// zone-less date-times (LOCAL time per ECMA-262).
+fn js_date_parse_ms(trimmed: &str) -> Option<i64> {
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc2822(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(date) = chrono::NaiveDate::parse_from_str(trimmed, "%Y-%m-%d") {
+        let midnight = date.and_hms_opt(0, 0, 0)?;
+        return Some(chrono::Utc.from_utc_datetime(&midnight).timestamp_millis());
+    }
+    for format in ["%Y-%m-%dT%H:%M:%S%.f", "%Y-%m-%d %H:%M:%S%.f"] {
+        if let Ok(naive) = chrono::NaiveDateTime::parse_from_str(trimmed, format) {
+            return chrono::Local
+                .from_local_datetime(&naive)
+                .earliest()
+                .map(|local| local.timestamp_millis());
+        }
+    }
+    None
+}
+
+/// TS `parseResetAtMs(headers, prefix)` — `-reset-after-seconds` (relative,
+/// from the CURRENT wall clock) wins; else `-reset-at` with the digit
+/// heuristics: all-digit values `< 10_000_000_000` are epoch-SECONDS
+/// (× 1000), larger are already ms; anything else goes through the
+/// `Date.parse` ladder.
+fn parse_reset_at_ms(headers: &HeaderMap, prefix: &str) -> Option<i64> {
+    let reset_after_seconds =
+        parse_finite_int_header(headers, &format!("{prefix}-reset-after-seconds"));
+    if let Some(seconds) = reset_after_seconds
+        && seconds > 0
+    {
+        // f64 multiply mirrors JS semantics; the `as i64` cast saturates on
+        // overflow, so a hostile huge header yields a far-future resetAtMs
+        // (blocked window) exactly like TS — never a wrapped negative value.
+        return Some(now_ms().saturating_add((seconds as f64 * 1000.0) as i64));
+    }
+
+    let reset_at_raw = header_str(headers, &format!("{prefix}-reset-at"))?;
+    if reset_at_raw.is_empty() {
+        return None;
+    }
+    let trimmed = reset_at_raw.trim();
+    if !trimmed.is_empty()
+        && trimmed.chars().all(|c| c.is_ascii_digit())
+        && let Some(parsed) = js_parse_int(trimmed)
+        && parsed > 0
+    {
+        return Some(if parsed < 10_000_000_000 {
+            parsed * 1000
+        } else {
+            parsed
+        });
+    }
+    js_date_parse_ms(trimmed)
+}
+
+/// TS `hasCodexQuotaHeaders` — presence gate: any of the 8 quota headers
+/// present (value content irrelevant, even empty).
+fn has_codex_quota_headers(headers: &HeaderMap) -> bool {
+    const KEYS: [&str; 8] = [
+        "x-codex-primary-used-percent",
+        "x-codex-primary-window-minutes",
+        "x-codex-primary-reset-at",
+        "x-codex-primary-reset-after-seconds",
+        "x-codex-secondary-used-percent",
+        "x-codex-secondary-window-minutes",
+        "x-codex-secondary-reset-at",
+        "x-codex-secondary-reset-after-seconds",
+    ];
+    KEYS.iter().any(|key| headers.contains_key(*key))
+}
+
+/// TS `parseQuotaSnapshotBase(headers, status)` — `None` when the presence
+/// gate fails; the status is included verbatim (a 429 with quota headers
+/// still parses). The returned snapshot's `model` is empty — the caller
+/// fills it.
+fn parse_quota_snapshot_base(headers: &HeaderMap, status: u16) -> Option<CodexQuotaSnapshot> {
+    if !has_codex_quota_headers(headers) {
+        return None;
+    }
+
+    let primary_prefix = "x-codex-primary";
+    let secondary_prefix = "x-codex-secondary";
+    let primary = CodexQuotaWindow {
+        used_percent: parse_finite_number_header(
+            headers,
+            &format!("{primary_prefix}-used-percent"),
+        ),
+        window_minutes: parse_finite_int_header(
+            headers,
+            &format!("{primary_prefix}-window-minutes"),
+        ),
+        reset_at_ms: parse_reset_at_ms(headers, primary_prefix),
+    };
+    let secondary = CodexQuotaWindow {
+        used_percent: parse_finite_number_header(
+            headers,
+            &format!("{secondary_prefix}-used-percent"),
+        ),
+        window_minutes: parse_finite_int_header(
+            headers,
+            &format!("{secondary_prefix}-window-minutes"),
+        ),
+        reset_at_ms: parse_reset_at_ms(headers, secondary_prefix),
+    };
+
+    let plan_type = header_str(headers, "x-codex-plan-type")
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string);
+    let active_limit = parse_finite_int_header(headers, "x-codex-active-limit");
+
+    Some(CodexQuotaSnapshot {
+        status,
+        plan_type,
+        active_limit,
+        primary,
+        secondary,
+        model: String::new(),
+    })
+}
+
+/// TS `normalizeProbeModels` — `[trim(primary), ...(fallbacks ??
+/// QUOTA_PROBE_MODEL_CHAIN)]`, blanks dropped, deduped preserving first
+/// occurrence.
+fn normalize_probe_models(
+    primary_model: Option<&str>,
+    fallback_models: Option<&[String]>,
+) -> Vec<String> {
+    let mut merged: Vec<&str> = Vec::new();
+    if let Some(primary) = primary_model {
+        merged.push(primary);
+    }
+    match fallback_models {
+        Some(fallbacks) => merged.extend(fallbacks.iter().map(String::as_str)),
+        None => merged.extend(QUOTA_PROBE_MODEL_CHAIN.iter().copied()),
+    }
+    let mut models: Vec<String> = Vec::new();
+    for model in merged {
+        let trimmed = model.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        if !models.iter().any(|existing| existing == trimmed) {
+            models.push(trimmed.to_string());
+        }
+    }
+    models
+}
+
+/// TS `extractErrorMessage(bodyText, status)` — empty body → `"HTTP
+/// {status}"`; JSON `error.message` string → that; top-level `message`
+/// string → that; else the trimmed raw body.
+fn extract_error_message(body_text: &str, status: u16) -> String {
+    let trimmed = body_text.trim();
+    if trimmed.is_empty() {
+        return format!("HTTP {status}");
+    }
+    if let Ok(parsed) = serde_json::from_str::<Value>(trimmed)
+        && is_record(&parsed)
+    {
+        if let Some(message) = parsed
+            .get("error")
+            .filter(|error| is_record(error))
+            .and_then(|error| error.get("message"))
+            .and_then(Value::as_str)
+        {
+            return message.to_string();
+        }
+        if let Some(message) = parsed.get("message").and_then(Value::as_str) {
+            return message.to_string();
+        }
+    }
+    trimmed.to_string()
+}
+
+// ---------------------------------------------------------------------------
+// Display formatting
+// ---------------------------------------------------------------------------
+
+/// TS `formatQuotaWindowLabel` — falsy/non-finite/<=0 → `"quota"`; whole
+/// days → `"{d}d"`; whole hours → `"{h}h"`; else `"{m}m"`.
+fn format_quota_window_label(window_minutes: Option<i64>) -> String {
+    let Some(minutes) = window_minutes else {
+        return "quota".to_string();
+    };
+    if minutes <= 0 {
+        return "quota".to_string();
+    }
+    if minutes % 1440 == 0 {
+        format!("{}d", minutes / 1440)
+    } else if minutes % 60 == 0 {
+        format!("{}h", minutes / 60)
+    } else {
+        format!("{minutes}m")
+    }
+}
+
+/// TS `formatQuotaResetAt(resetAtMs, nowMs = Date.now())` — same LOCAL
+/// calendar day: `"HH:MM"` (24-hour); else `"HH:MM on {Mon DD}"`. Invalid /
+/// non-positive input → `None`. (The TS output is locale-dependent via
+/// `toLocaleTimeString`; the Rust port pins the equivalent en-dash-free
+/// `%H:%M` / `%b %d` local-time formatting per the spec note.)
+pub fn format_quota_reset_at(
+    reset_at_ms: Option<i64>,
+    now_ms_override: Option<i64>,
+) -> Option<String> {
+    let reset_at = reset_at_ms?;
+    if reset_at <= 0 {
+        return None;
+    }
+    let date = chrono::Local.timestamp_millis_opt(reset_at).single()?;
+    let now = chrono::Local
+        .timestamp_millis_opt(now_ms_override.unwrap_or_else(now_ms))
+        .single()?;
+
+    let time = date.format("%H:%M").to_string();
+    if now.date_naive() == date.date_naive() {
+        return Some(time);
+    }
+    Some(format!("{time} on {}", date.format("%b %d")))
+}
+
+/// TS private `formatWindowSummary` — `"{label}[ {left}% left][ (resets
+/// {fmt})]"`.
+fn format_window_summary(label: &str, window: &CodexQuotaWindow) -> String {
+    let mut summary = label.to_string();
+    if let Some(used) = window.used_percent
+        && used.is_finite()
+    {
+        let left = (100.0 - used).round().clamp(0.0, 100.0) as i64;
+        summary = format!("{summary} {left}% left");
+    }
+    if let Some(reset) = format_quota_reset_at(window.reset_at_ms, None) {
+        summary = format!("{summary} (resets {reset})");
+    }
+    summary
+}
+
+/// TS `formatQuotaSnapshotLine(snapshot)` — comma-joined window summaries,
+/// optional `plan:{planType}` / `active:{n}`, and `"rate-limited"` iff the
+/// status is 429.
+pub fn format_quota_snapshot_line(snapshot: &CodexQuotaSnapshot) -> String {
+    let primary_label = format_quota_window_label(snapshot.primary.window_minutes);
+    let secondary_label = format_quota_window_label(snapshot.secondary.window_minutes);
+    let mut parts = vec![
+        format_window_summary(&primary_label, &snapshot.primary),
+        format_window_summary(&secondary_label, &snapshot.secondary),
+    ];
+    if let Some(plan_type) = &snapshot.plan_type
+        && !plan_type.is_empty()
+    {
+        parts.push(format!("plan:{plan_type}"));
+    }
+    if let Some(active_limit) = snapshot.active_limit {
+        parts.push(format!("active:{active_limit}"));
+    }
+    if snapshot.status == 429 {
+        parts.push("rate-limited".to_string());
+    }
+    parts.join(", ")
+}
+
+// ---------------------------------------------------------------------------
+// The probe
+// ---------------------------------------------------------------------------
+
+/// Outcome of a single model attempt (internal).
+enum ProbeAttempt {
+    Snapshot(CodexQuotaSnapshot),
+    /// Unsupported-model rejection — continue down the chain.
+    Unsupported(String),
+    /// Any other failure — continue, but the run can no longer end in
+    /// `CodexUnavailableError`.
+    Failure(String),
+}
+
+async fn probe_one_model(
+    base_url: &str,
+    account_id: &str,
+    access_token: &str,
+    model: &str,
+    timeout_ms: u64,
+) -> ProbeAttempt {
+    let instructions = get_codex_instructions(Some(model)).await;
+    // Send the cheapest effort each probe model actually declares (the
+    // GPT-5.6 tiers and codex models do not list `none`), keeping the probe
+    // consistent with normal request routing (issue #627).
+    let effort = resolve_probe_reasoning_effort(Some(model));
+    let probe_body = json!({
+        "model": model,
+        "stream": true,
+        "store": false,
+        "include": ["reasoning.encrypted_content"],
+        "instructions": instructions,
+        "input": [
+            {
+                "type": "message",
+                "role": "user",
+                "content": [{ "type": "input_text", "text": "quota ping" }],
+            }
+        ],
+        "reasoning": { "effort": effort.as_str(), "summary": "auto" },
+        "text": { "verbosity": "low" },
+    });
+
+    let mut headers = match create_codex_headers_positional(
+        None,
+        account_id,
+        access_token,
+        Some(&CreateCodexHeadersOptions {
+            model: Some(model.to_string()),
+            prompt_cache_key: None,
+        }),
+    ) {
+        Ok(headers) => headers,
+        Err(error) => return ProbeAttempt::Failure(error.message().to_string()),
+    };
+    headers.insert(
+        reqwest::header::CONTENT_TYPE,
+        HeaderValue::from_static("application/json"),
+    );
+
+    note_probe_attempt();
+    let send = shared_client()
+        .post(format!("{base_url}/codex/responses"))
+        .headers(headers)
+        .body(stringify_compact(&probe_body))
+        .send();
+    let response = match tokio::time::timeout(std::time::Duration::from_millis(timeout_ms), send)
+        .await
+    {
+        // Node fetch abort surfaces DOMException "This operation was
+        // aborted" — frozen for parity with the TS timeout path.
+        Err(_elapsed) => return ProbeAttempt::Failure("This operation was aborted".to_string()),
+        Ok(Err(error)) => return ProbeAttempt::Failure(error.to_string()),
+        Ok(Ok(response)) => response,
+    };
+
+    let status = response.status().as_u16();
+    if let Some(mut snapshot) = parse_quota_snapshot_base(response.headers(), status) {
+        // Dropping the response cancels the streamed body (TS
+        // `response.body?.cancel()` best effort).
+        snapshot.model = model.to_string();
+        return ProbeAttempt::Snapshot(snapshot);
+    }
+
+    if !response.status().is_success() {
+        let body_text = response.text().await.unwrap_or_default();
+        let error_body: Value = if body_text.is_empty() {
+            Value::Null
+        } else {
+            serde_json::from_str(&body_text)
+                .unwrap_or_else(|_| json!({ "error": { "message": body_text } }))
+        };
+        let unsupported_info = get_unsupported_codex_model_info(&error_body);
+        if unsupported_info.is_unsupported {
+            return ProbeAttempt::Unsupported(
+                unsupported_info
+                    .message
+                    .unwrap_or_else(|| format!("Model '{model}' unsupported for this account")),
+            );
+        }
+        return ProbeAttempt::Failure(extract_error_message(&body_text, status));
+    }
+
+    // OK but no quota headers.
+    ProbeAttempt::Failure("Codex response did not include quota headers".to_string())
+}
+
+/// TS `fetchCodexQuotaSnapshot(options)` — probe Codex models sequentially
+/// to obtain a quota snapshot for the account. See the module docs for the
+/// chain/unsupported/`CodexUnavailableError` contracts.
+pub async fn fetch_codex_quota_snapshot(
+    options: &ProbeCodexQuotaOptions,
+) -> Result<CodexQuotaSnapshot, CodexError> {
+    let models =
+        normalize_probe_models(options.model.as_deref(), options.fallback_models.as_deref());
+    let timeout_ms = options.timeout_ms.unwrap_or(15_000).clamp(1_000, 60_000);
+    let base_url = options.base_url.as_deref().unwrap_or(CODEX_BASE_URL);
+
+    let mut last_error: Option<String> = None;
+    let mut attempted_any_model = false;
+    let mut saw_unsupported_model = false;
+    let mut saw_other_failure = false;
+
+    for model in &models {
+        attempted_any_model = true;
+        match probe_one_model(
+            base_url,
+            &options.account_id,
+            &options.access_token,
+            model,
+            timeout_ms,
+        )
+        .await
+        {
+            ProbeAttempt::Snapshot(snapshot) => return Ok(snapshot),
+            ProbeAttempt::Unsupported(message) => {
+                saw_unsupported_model = true;
+                last_error = Some(message);
+            }
+            ProbeAttempt::Failure(message) => {
+                saw_other_failure = true;
+                last_error = Some(message);
+            }
+        }
+    }
+
+    if attempted_any_model && saw_unsupported_model && !saw_other_failure {
+        return Err(CodexError::unavailable(last_error.unwrap_or_else(|| {
+            "Codex is not available for this account".to_string()
+        })));
+    }
+
+    Err(CodexError::new(
+        last_error.unwrap_or_else(|| "Failed to fetch quotas".to_string()),
+    ))
+}
+
+// ============================================================================
+// Tests — ported from test/quota-probe.test.ts (wiremock replaces the TS
+// global-fetch stubs; the `base_url` seam points the probe at the mock)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use wiremock::matchers::{body_partial_json, header, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn options(server: &MockServer) -> ProbeCodexQuotaOptions {
+        ProbeCodexQuotaOptions {
+            account_id: "acct_probe".to_string(),
+            access_token: "token-123".to_string(),
+            model: None,
+            fallback_models: None,
+            timeout_ms: None,
+            base_url: Some(server.uri()),
+        }
+    }
+
+    /// Options pinned to a single explicit model (empty fallback list) so a
+    /// test exercises exactly one attempt.
+    fn single_model_options(server: &MockServer, model: &str) -> ProbeCodexQuotaOptions {
+        ProbeCodexQuotaOptions {
+            model: Some(model.to_string()),
+            fallback_models: Some(Vec::new()),
+            ..options(server)
+        }
+    }
+
+    fn quota_headers_response(status: u16) -> ResponseTemplate {
+        ResponseTemplate::new(status)
+            .insert_header("x-codex-primary-used-percent", "12.5")
+            .insert_header("x-codex-primary-window-minutes", "300")
+            .insert_header("x-codex-primary-reset-after-seconds", "60")
+            .insert_header("x-codex-secondary-used-percent", "3")
+            .insert_header("x-codex-secondary-window-minutes", "10080")
+            .insert_header("x-codex-plan-type", "plus")
+            .insert_header("x-codex-active-limit", "5")
+    }
+
+    #[tokio::test]
+    async fn returns_parsed_quota_snapshot_from_response_headers() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .and(header("authorization", "Bearer token-123"))
+            .and(header("content-type", "application/json"))
+            .respond_with(quota_headers_response(200))
+            .mount(&server)
+            .await;
+
+        let before = now_ms();
+        let snapshot = fetch_codex_quota_snapshot(&options(&server))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.status, 200);
+        assert_eq!(snapshot.plan_type.as_deref(), Some("plus"));
+        assert_eq!(snapshot.active_limit, Some(5));
+        assert_eq!(snapshot.primary.used_percent, Some(12.5));
+        assert_eq!(snapshot.primary.window_minutes, Some(300));
+        let reset = snapshot.primary.reset_at_ms.expect("primary reset");
+        assert!(
+            reset >= before + 60_000 && reset <= now_ms() + 60_000,
+            "reset-after-seconds must be now + 60s (got {reset})"
+        );
+        assert_eq!(snapshot.secondary.used_percent, Some(3.0));
+        assert_eq!(snapshot.secondary.window_minutes, Some(10_080));
+        assert_eq!(snapshot.secondary.reset_at_ms, None);
+        // Default probe model: Sol first (DEFAULT_PROBE_MODEL).
+        assert_eq!(snapshot.model, "gpt-5.6-sol");
+    }
+
+    #[tokio::test]
+    async fn uses_gpt_5_6_sol_as_the_default_quota_probe_model() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .and(body_partial_json(
+                json!({ "model": "gpt-5.6-sol", "stream": true, "store": false }),
+            ))
+            .respond_with(quota_headers_response(200))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let snapshot = fetch_codex_quota_snapshot(&options(&server))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.model, "gpt-5.6-sol");
+    }
+
+    #[tokio::test]
+    async fn falls_back_from_the_gpt_5_6_probe_model_to_gpt_5_5_when_it_is_unsupported() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .and(body_partial_json(json!({ "model": "gpt-5.6-sol" })))
+            .respond_with(ResponseTemplate::new(400).set_body_string(
+                "{\"error\":{\"code\":\"model_not_supported_with_chatgpt_account\",\"message\":\"The 'gpt-5.6-sol' model is not supported\"}}",
+            ))
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .and(body_partial_json(json!({ "model": "gpt-5.5" })))
+            .respond_with(quota_headers_response(200))
+            .mount(&server)
+            .await;
+
+        let snapshot = fetch_codex_quota_snapshot(&options(&server))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.model, "gpt-5.5");
+    }
+
+    #[tokio::test]
+    async fn accepts_429_responses_when_quota_headers_are_present() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                ResponseTemplate::new(429)
+                    .insert_header("x-codex-primary-used-percent", "100")
+                    .insert_header("x-codex-primary-reset-after-seconds", "120"),
+            )
+            .mount(&server)
+            .await;
+
+        let snapshot = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.status, 429);
+        assert_eq!(snapshot.primary.used_percent, Some(100.0));
+        assert_eq!(snapshot.model, "gpt-5.5");
+    }
+
+    #[tokio::test]
+    async fn times_out_a_stalled_probe_and_surfaces_abort_failure() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                quota_headers_response(200).set_delay(std::time::Duration::from_millis(3_000)),
+            )
+            .mount(&server)
+            .await;
+
+        let probe_options = ProbeCodexQuotaOptions {
+            timeout_ms: Some(1_000),
+            ..single_model_options(&server, "gpt-5.5")
+        };
+        let error = fetch_codex_quota_snapshot(&probe_options)
+            .await
+            .expect_err("timeout");
+        assert_eq!(error.message(), "This operation was aborted");
+        assert!(!error.is_codex_unavailable());
+    }
+
+    #[tokio::test]
+    async fn parses_reset_at_values_expressed_as_epoch_seconds_and_epoch_milliseconds() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    // < 10_000_000_000 → epoch-seconds → × 1000
+                    .insert_header("x-codex-primary-reset-at", "1750001000")
+                    // >= 10_000_000_000 → already epoch-ms
+                    .insert_header("x-codex-secondary-reset-at", "1750001000000"),
+            )
+            .mount(&server)
+            .await;
+
+        let snapshot = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.primary.reset_at_ms, Some(1_750_001_000_000));
+        assert_eq!(snapshot.secondary.reset_at_ms, Some(1_750_001_000_000));
+    }
+
+    #[tokio::test]
+    async fn keeps_reset_at_undefined_for_invalid_reset_at_values() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .insert_header("x-codex-primary-reset-at", "soon")
+                    .insert_header("x-codex-secondary-reset-at", "0"),
+            )
+            .mount(&server)
+            .await;
+
+        let snapshot = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect("snapshot");
+        assert_eq!(snapshot.primary.reset_at_ms, None);
+        assert_eq!(snapshot.secondary.reset_at_ms, None);
+    }
+
+    #[tokio::test]
+    async fn throws_parsed_nested_error_message_for_non_ok_response_without_quota_headers() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                ResponseTemplate::new(500)
+                    .set_body_string("{\"error\":{\"message\":\"upstream exploded\"}}"),
+            )
+            .mount(&server)
+            .await;
+
+        let error = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect_err("error");
+        assert_eq!(error.message(), "upstream exploded");
+    }
+
+    #[tokio::test]
+    async fn throws_top_level_message_plain_text_and_http_fallback_for_non_ok_response() {
+        for (body, expected) in [
+            ("{\"message\":\"top level\"}", "top level"),
+            ("plain text failure", "plain text failure"),
+            ("", "HTTP 500"),
+        ] {
+            let server = MockServer::start().await;
+            Mock::given(method("POST"))
+                .and(path("/codex/responses"))
+                .respond_with(ResponseTemplate::new(500).set_body_string(body))
+                .mount(&server)
+                .await;
+            let error = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+                .await
+                .expect_err("error");
+            assert_eq!(error.message(), expected, "body {body:?}");
+        }
+    }
+
+    #[tokio::test]
+    async fn uses_default_unsupported_model_message_when_helper_does_not_provide_one() {
+        let server = MockServer::start().await;
+        // `code` marks it unsupported but carries no message string.
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(ResponseTemplate::new(400).set_body_string(
+                "{\"error\":{\"code\":\"model_not_supported_with_chatgpt_account\"}}",
+            ))
+            .mount(&server)
+            .await;
+
+        let error = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect_err("error");
+        assert!(error.is_codex_unavailable());
+        assert_eq!(
+            error.message(),
+            "Model 'gpt-5.5' unsupported for this account"
+        );
+    }
+
+    #[tokio::test]
+    async fn throws_codex_unavailable_error_when_every_model_is_unsupported() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(ResponseTemplate::new(400).set_body_string(
+                "{\"error\":{\"code\":\"model_not_supported_with_chatgpt_account\",\"message\":\"model is not supported\"}}",
+            ))
+            .mount(&server)
+            .await;
+
+        let error = fetch_codex_quota_snapshot(&options(&server))
+            .await
+            .expect_err("error");
+        assert!(error.is_codex_unavailable());
+        assert_eq!(
+            describe_codex_probe_failure(&error, None),
+            CODEX_UNAVAILABLE_PROBE_NOTE
+        );
+    }
+
+    #[tokio::test]
+    async fn does_not_throw_codex_unavailable_error_when_a_non_unsupported_failure_is_mixed_in() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .and(body_partial_json(json!({ "model": "gpt-5.6-sol" })))
+            .respond_with(ResponseTemplate::new(400).set_body_string(
+                "{\"error\":{\"code\":\"model_not_supported_with_chatgpt_account\",\"message\":\"model is not supported\"}}",
+            ))
+            .mount(&server)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(
+                ResponseTemplate::new(500)
+                    .set_body_string("{\"error\":{\"message\":\"server broke\"}}"),
+            )
+            .mount(&server)
+            .await;
+
+        let probe_options = ProbeCodexQuotaOptions {
+            model: Some("gpt-5.6-sol".to_string()),
+            fallback_models: Some(vec!["gpt-5.5".to_string()]),
+            ..options(&server)
+        };
+        let error = fetch_codex_quota_snapshot(&probe_options)
+            .await
+            .expect_err("error");
+        assert!(!error.is_codex_unavailable());
+        assert_eq!(error.message(), "server broke");
+    }
+
+    #[tokio::test]
+    async fn throws_missing_quota_header_error_when_response_succeeds_without_quota_headers() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("data: {}\n\n"))
+            .mount(&server)
+            .await;
+
+        let error = fetch_codex_quota_snapshot(&single_model_options(&server, "gpt-5.5"))
+            .await
+            .expect_err("error");
+        assert!(!error.is_codex_unavailable());
+        assert_eq!(
+            error.message(),
+            "Codex response did not include quota headers"
+        );
+    }
+
+    #[tokio::test]
+    async fn throws_generic_failure_when_no_normalized_probe_models_are_available() {
+        let server = MockServer::start().await;
+        let probe_options = ProbeCodexQuotaOptions {
+            model: Some("   ".to_string()),
+            fallback_models: Some(vec!["  ".to_string(), String::new()]),
+            ..options(&server)
+        };
+        let error = fetch_codex_quota_snapshot(&probe_options)
+            .await
+            .expect_err("error");
+        assert_eq!(error.message(), "Failed to fetch quotas");
+    }
+
+    #[tokio::test]
+    async fn increments_the_observability_hook_once_per_model_attempt() {
+        static COUNTER: AtomicUsize = AtomicUsize::new(0);
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/codex/responses"))
+            .respond_with(ResponseTemplate::new(400).set_body_string(
+                "{\"error\":{\"code\":\"model_not_supported_with_chatgpt_account\",\"message\":\"model is not supported\"}}",
+            ))
+            .mount(&server)
+            .await;
+
+        COUNTER.store(0, Ordering::SeqCst);
+        // The hook is process-global; other probe tests may fire attempts
+        // concurrently. `#[tokio::test]` uses a current-thread runtime, so
+        // attempts from THIS test always run on this thread — count only
+        // those.
+        let test_thread = std::thread::current().id();
+        set_probe_observability_hook(Some(Arc::new(move || {
+            if std::thread::current().id() == test_thread {
+                COUNTER.fetch_add(1, Ordering::SeqCst);
+            }
+        })));
+        let probe_options = ProbeCodexQuotaOptions {
+            model: Some("gpt-5.6-sol".to_string()),
+            fallback_models: Some(vec!["gpt-5.5".to_string()]),
+            ..options(&server)
+        };
+        let _ = fetch_codex_quota_snapshot(&probe_options).await;
+        set_probe_observability_hook(None);
+        // One increment per MODEL attempt, not per call.
+        assert_eq!(COUNTER.load(Ordering::SeqCst), 2);
+    }
+
+    // -- pure formatting -----------------------------------------------------
+
+    #[test]
+    fn formats_quota_lines_with_day_hour_labels_reset_text_plan_and_active_limits() {
+        let reset_at = now_ms() + 60_000;
+        let snapshot = CodexQuotaSnapshot {
+            status: 429,
+            plan_type: Some("plus".to_string()),
+            active_limit: Some(3),
+            primary: CodexQuotaWindow {
+                used_percent: Some(25.0),
+                window_minutes: Some(300),
+                reset_at_ms: Some(reset_at),
+            },
+            secondary: CodexQuotaWindow {
+                used_percent: Some(99.6),
+                window_minutes: Some(10_080),
+                reset_at_ms: None,
+            },
+            model: "gpt-5.6-sol".to_string(),
+        };
+        let line = format_quota_snapshot_line(&snapshot);
+        let reset_text = format_quota_reset_at(Some(reset_at), None).expect("reset text");
+        assert_eq!(
+            line,
+            format!(
+                "5h 75% left (resets {reset_text}), 7d 0% left, plan:plus, active:3, rate-limited"
+            )
+        );
+    }
+
+    #[test]
+    fn formats_fallback_quota_labels_and_suppresses_invalid_reset_time() {
+        let snapshot = CodexQuotaSnapshot {
+            status: 200,
+            plan_type: None,
+            active_limit: None,
+            primary: CodexQuotaWindow {
+                used_percent: None,
+                window_minutes: None,
+                reset_at_ms: Some(-5),
+            },
+            secondary: CodexQuotaWindow {
+                used_percent: Some(30.0),
+                window_minutes: Some(90),
+                reset_at_ms: None,
+            },
+            model: "gpt-5.5".to_string(),
+        };
+        assert_eq!(format_quota_snapshot_line(&snapshot), "quota, 90m 70% left");
+        assert_eq!(format_quota_reset_at(Some(0), None), None);
+        assert_eq!(format_quota_reset_at(None, None), None);
+    }
+
+    #[test]
+    fn format_quota_reset_at_uses_day_suffix_for_other_days() {
+        let now = 1_700_000_000_000; // fixed reference
+        let same_day = format_quota_reset_at(Some(now + 60_000), Some(now)).expect("same day");
+        assert!(
+            !same_day.contains(" on "),
+            "same-day format must be bare HH:MM: {same_day}"
+        );
+        let other_day =
+            format_quota_reset_at(Some(now + 3 * 86_400_000), Some(now)).expect("other day");
+        assert!(
+            other_day.contains(" on "),
+            "cross-day format must carry ' on Mon DD': {other_day}"
+        );
+    }
+
+    #[test]
+    fn describe_codex_probe_failure_variants() {
+        let unavailable = CodexError::unavailable("model is not supported for this account");
+        assert_eq!(
+            describe_codex_probe_failure(&unavailable, None),
+            CODEX_UNAVAILABLE_PROBE_NOTE
+        );
+
+        let other = CodexError::new("boom");
+        assert_eq!(describe_codex_probe_failure(&other, None), "boom");
+
+        let normalizer = |message: &str| format!("normalized: {message}");
+        assert_eq!(
+            describe_codex_probe_failure(&other, Some(&normalizer)),
+            "normalized: boom"
+        );
+        // The normalizer never applies to unavailable errors.
+        assert_eq!(
+            describe_codex_probe_failure(&unavailable, Some(&normalizer)),
+            CODEX_UNAVAILABLE_PROBE_NOTE
+        );
+    }
+
+    #[test]
+    fn hostile_huge_reset_after_seconds_saturates_to_a_far_future_reset() {
+        // TS float math yields a huge finite resetAtMs (blocked window); the
+        // i64 port must saturate positive instead of wrapping negative
+        // (which would read as already-reset → account looks healthy) or
+        // panicking under overflow checks.
+        let before = now_ms();
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            "x-codex-primary-reset-after-seconds",
+            HeaderValue::from_static("9300000000000000"),
+        );
+        let parsed = parse_reset_at_ms(&headers, "x-codex-primary").expect("resetAtMs");
+        assert!(parsed > before, "far-future, never wrapped: {parsed}");
+
+        // 20-digit runs saturate the parse itself, then the ms conversion.
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            "x-codex-primary-reset-after-seconds",
+            HeaderValue::from_static("99999999999999999999"),
+        );
+        let parsed = parse_reset_at_ms(&headers, "x-codex-primary").expect("resetAtMs");
+        assert!(parsed > before, "saturated parse stays far-future: {parsed}");
+    }
+
+    #[test]
+    fn js_parse_int_and_number_semantics() {
+        assert_eq!(js_parse_int("300"), Some(300));
+        assert_eq!(js_parse_int("  42abc"), Some(42));
+        assert_eq!(js_parse_int("12.9"), Some(12));
+        assert_eq!(js_parse_int("-7"), Some(-7));
+        assert_eq!(js_parse_int("abc"), None);
+        assert_eq!(js_parse_int(""), None);
+        assert_eq!(js_number("12.5"), Some(12.5));
+        assert_eq!(js_number(" 42 "), Some(42.0));
+        assert_eq!(js_number("1e3"), Some(1000.0));
+        assert_eq!(js_number("nope"), None);
+        assert!(js_number("Infinity").is_some_and(|n| n.is_infinite()));
+    }
+}
diff --git a/crates/quota/src/readiness.rs b/crates/quota/src/readiness.rs
new file mode 100644
index 000000000..cacc328ae
--- /dev/null
+++ b/crates/quota/src/readiness.rs
@@ -0,0 +1,532 @@
+//! Port of `lib/quota-readiness.ts` — pure helpers for quota-cache entry
+//! lookup keying rules and the "is exhausted" logic.
+//!
+//! Behavior contracts (spec 05 §4 + gotchas 1/7/8):
+//! - Exhaustion is decided on the RAW `usedPercent >= 100` float —
+//!   [`quota_left_percent_from_used`] (rounded) is DISPLAY ONLY. Rounding
+//!   `100 - 99.6 = 0.4` down to `0` left would falsely bench a window that
+//!   still has quota.
+//! - Cache keying safety: `byAccountId` only when the id is unique among the
+//!   accounts; `byEmail` only when exactly one account carries that email and
+//!   at most one distinct accountId. Ambiguity deliberately yields NO entry
+//!   (prevents cross-account quota bleed).
+//! - Staleness escape ("quota-forecast-02"): a 100%-used window with no
+//!   `resetAtMs` stops being "exhausted" once `windowMinutes` have elapsed
+//!   since the snapshot's `updatedAt`.
+
+use std::collections::{HashMap, HashSet};
+
+use cma_accounts::manager::ManagedAccount;
+use cma_core::schemas::account_storage::AccountMetadataV3;
+
+use crate::cache::{QuotaCacheData, QuotaCacheEntry, QuotaCacheWindow};
+
+/// TS `QuotaCacheAccountRef = Pick<AccountMetadataV3, "accountId" | "email">`.
+///
+/// A structural trait so cache lookups accept `AccountMetadataV3`,
+/// `ManagedAccount`, or the owned [`QuotaAccountRef`] pair alike.
+pub trait QuotaCacheAccountRef {
+    fn quota_account_id(&self) -> Option<&str>;
+    fn quota_email(&self) -> Option<&str>;
+}
+
+impl QuotaCacheAccountRef for AccountMetadataV3 {
+    fn quota_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn quota_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+}
+
+impl QuotaCacheAccountRef for ManagedAccount {
+    fn quota_account_id(&self) -> Option<&str> {
+        self.meta.account_id.as_deref()
+    }
+    fn quota_email(&self) -> Option<&str> {
+        self.meta.email.as_deref()
+    }
+}
+
+/// Owned `{ accountId?, email? }` pair for callers without a full account.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct QuotaAccountRef {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+}
+
+impl QuotaCacheAccountRef for QuotaAccountRef {
+    fn quota_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn quota_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+}
+
+impl<T: QuotaCacheAccountRef + ?Sized> QuotaCacheAccountRef for &T {
+    fn quota_account_id(&self) -> Option<&str> {
+        (**self).quota_account_id()
+    }
+    fn quota_email(&self) -> Option<&str> {
+        (**self).quota_email()
+    }
+}
+
+/// TS `normalizeQuotaAccountId(value)` — trim; `None` when empty/absent.
+pub fn normalize_quota_account_id(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `normalizeQuotaEmail(value)` — trim + lowercase; `None` when empty.
+pub fn normalize_quota_email(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim().to_lowercase();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+/// TS `hasUniqueQuotaAccountId(accounts, account)` — the account's normalized
+/// id is non-null AND exactly ONE entry in `accounts` shares it.
+pub fn has_unique_quota_account_id<T: QuotaCacheAccountRef>(
+    accounts: &[T],
+    account: &impl QuotaCacheAccountRef,
+) -> bool {
+    let Some(account_id) = normalize_quota_account_id(account.quota_account_id()) else {
+        return false;
+    };
+    let mut count = 0usize;
+    for candidate in accounts {
+        if normalize_quota_account_id(candidate.quota_account_id()).as_deref()
+            == Some(account_id.as_str())
+        {
+            count += 1;
+        }
+    }
+    count == 1
+}
+
+/// TS `QuotaEmailFallbackState`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct QuotaEmailFallbackState {
+    pub matching_count: usize,
+    pub distinct_account_ids: HashSet<String>,
+}
+
+/// TS `buildQuotaEmailFallbackState(accounts)` — per normalized email: count
+/// of accounts carrying it plus the set of their normalized accountIds.
+pub fn build_quota_email_fallback_state<T: QuotaCacheAccountRef>(
+    accounts: &[T],
+) -> HashMap<String, QuotaEmailFallbackState> {
+    let mut state_by_email: HashMap<String, QuotaEmailFallbackState> = HashMap::new();
+    for account in accounts {
+        let Some(email) = normalize_quota_email(account.quota_email()) else {
+            continue;
+        };
+        let account_id = normalize_quota_account_id(account.quota_account_id());
+        let state = state_by_email.entry(email).or_default();
+        state.matching_count += 1;
+        if let Some(account_id) = account_id {
+            state.distinct_account_ids.insert(account_id);
+        }
+    }
+    state_by_email
+}
+
+/// TS `hasSafeQuotaEmailFallback(state, account)` — email present in the
+/// state with `matchingCount === 1 && distinctAccountIds.size <= 1`.
+pub fn has_safe_quota_email_fallback(
+    email_fallback_state: &HashMap<String, QuotaEmailFallbackState>,
+    account: &impl QuotaCacheAccountRef,
+) -> bool {
+    let Some(email) = normalize_quota_email(account.quota_email()) else {
+        return false;
+    };
+    let Some(state) = email_fallback_state.get(&email) else {
+        return false;
+    };
+    state.matching_count == 1 && state.distinct_account_ids.len() <= 1
+}
+
+/// TS `quotaLeftPercentFromUsed(used)` — `max(0, min(100, round(100 - used)))`.
+///
+/// DISPLAY ONLY — never use for exhaustion decisions (see module docs).
+pub fn quota_left_percent_from_used(used_percent: Option<f64>) -> Option<i64> {
+    let used = used_percent?;
+    if !used.is_finite() {
+        return None;
+    }
+    let left = (100.0 - used).round();
+    Some(left.clamp(0.0, 100.0) as i64)
+}
+
+/// TS `quotaUsedPercentIsExhausted(used)` — finite AND `>= 100` (RAW float).
+///
+/// THE exhaustion predicate: any `usedPercent` in `(99.5, 100)` rounds to `0`
+/// left-percent, so testing the rounded value would falsely bench windows
+/// that still have quota.
+pub fn quota_used_percent_is_exhausted(used_percent: Option<f64>) -> bool {
+    matches!(used_percent, Some(used) if used.is_finite() && used >= 100.0)
+}
+
+/// TS private `quotaWindowIsExhausted(window, now, updatedAt)`.
+fn quota_window_is_exhausted(window: &QuotaCacheWindow, now: i64, updated_at: Option<f64>) -> bool {
+    if let Some(reset_at_ms) = window.reset_at_ms
+        && now as f64 >= reset_at_ms
+    {
+        return false;
+    }
+    // quota-forecast-02: a window can be 100% used with NO resetAtMs. Without
+    // a staleness escape that reads as "exhausted forever". When we know when
+    // the snapshot was taken (updatedAt) and the window length
+    // (windowMinutes), synthesize a conservative expiry: once a full window
+    // has elapsed since the snapshot, the window must have rolled over, so
+    // stop treating it as exhausted.
+    if window.reset_at_ms.is_none()
+        && let Some(updated_at) = updated_at
+        && let Some(window_minutes) = window.window_minutes
+        && window_minutes > 0.0
+        && now as f64 >= updated_at + window_minutes * 60_000.0
+    {
+        return false;
+    }
+    quota_used_percent_is_exhausted(window.used_percent)
+}
+
+/// TS `isQuotaCacheEntryExhausted(entry, now)` — true when EITHER window is
+/// exhausted. Codex quota windows are cumulative gates: a 0%-remaining active
+/// window blocks use even if the other window still has quota left.
+pub fn is_quota_cache_entry_exhausted(entry: Option<&QuotaCacheEntry>, now: i64) -> bool {
+    let Some(entry) = entry else {
+        return false;
+    };
+    let updated_at = Some(entry.updated_at);
+    quota_window_is_exhausted(&entry.primary, now, updated_at)
+        || quota_window_is_exhausted(&entry.secondary, now, updated_at)
+}
+
+/// TS `findQuotaCacheEntryForAccount(cache, account, accounts)` (the default
+/// `emailFallbackState` overload) — builds the fallback state internally.
+pub fn find_quota_cache_entry_for_account<'c, T: QuotaCacheAccountRef>(
+    cache: Option<&'c QuotaCacheData>,
+    account: &impl QuotaCacheAccountRef,
+    accounts: &[T],
+) -> Option<&'c QuotaCacheEntry> {
+    let email_fallback_state = build_quota_email_fallback_state(accounts);
+    find_quota_cache_entry_for_account_with_state(cache, account, accounts, &email_fallback_state)
+}
+
+/// TS `findQuotaCacheEntryForAccount(cache, account, accounts, state)` with a
+/// caller-precomputed email fallback state.
+///
+/// `byAccountId` is consulted only when the accountId normalizes AND is
+/// unique among `accounts`; `byEmail` only when the email fallback is safe.
+/// Duplicate accountIds or ambiguous emails deliberately get NO cache entry.
+pub fn find_quota_cache_entry_for_account_with_state<'c, T: QuotaCacheAccountRef>(
+    cache: Option<&'c QuotaCacheData>,
+    account: &impl QuotaCacheAccountRef,
+    accounts: &[T],
+    email_fallback_state: &HashMap<String, QuotaEmailFallbackState>,
+) -> Option<&'c QuotaCacheEntry> {
+    let cache = cache?;
+    if let Some(account_id) = normalize_quota_account_id(account.quota_account_id())
+        && has_unique_quota_account_id(accounts, account)
+        && let Some(entry) = cache.by_account_id.get(&account_id)
+    {
+        return Some(entry);
+    }
+    if let Some(email) = normalize_quota_email(account.quota_email())
+        && has_safe_quota_email_fallback(email_fallback_state, account)
+        && let Some(entry) = cache.by_email.get(&email)
+    {
+        return Some(entry);
+    }
+    None
+}
+
+// ============================================================================
+// Tests — ported from test/quota-readiness.test.ts
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn window(
+        used_percent: Option<f64>,
+        window_minutes: Option<f64>,
+        reset_at_ms: Option<f64>,
+    ) -> QuotaCacheWindow {
+        QuotaCacheWindow {
+            used_percent,
+            window_minutes,
+            reset_at_ms,
+        }
+    }
+
+    fn entry(
+        updated_at: f64,
+        primary: QuotaCacheWindow,
+        secondary: QuotaCacheWindow,
+    ) -> QuotaCacheEntry {
+        QuotaCacheEntry {
+            updated_at,
+            status: 200.0,
+            model: "gpt-5.3-codex".to_string(),
+            plan_type: None,
+            primary,
+            secondary,
+        }
+    }
+
+    const NOW: i64 = 1_700_000_000_000;
+
+    // -- isQuotaCacheEntryExhausted ------------------------------------------
+
+    #[test]
+    fn treats_either_exhausted_quota_window_as_unavailable() {
+        let primary_exhausted = entry(
+            NOW as f64,
+            window(Some(100.0), None, Some((NOW + 60_000) as f64)),
+            window(Some(20.0), None, None),
+        );
+        assert!(is_quota_cache_entry_exhausted(
+            Some(&primary_exhausted),
+            NOW
+        ));
+
+        let secondary_exhausted = entry(
+            NOW as f64,
+            window(Some(20.0), None, None),
+            window(Some(100.0), None, Some((NOW + 60_000) as f64)),
+        );
+        assert!(is_quota_cache_entry_exhausted(
+            Some(&secondary_exhausted),
+            NOW
+        ));
+    }
+
+    #[test]
+    fn keeps_accounts_available_when_both_known_windows_have_quota_left() {
+        let healthy = entry(
+            NOW as f64,
+            window(Some(42.0), None, Some((NOW + 60_000) as f64)),
+            window(Some(63.0), None, Some((NOW + 600_000) as f64)),
+        );
+        assert!(!is_quota_cache_entry_exhausted(Some(&healthy), NOW));
+        assert!(!is_quota_cache_entry_exhausted(None, NOW));
+    }
+
+    #[test]
+    fn does_not_bench_a_window_with_fractional_quota_just_above_99_5_used() {
+        // 99.6% used rounds to 0% left, but the raw value is < 100: still quota.
+        let fractional = entry(
+            NOW as f64,
+            window(Some(99.6), None, Some((NOW + 60_000) as f64)),
+            window(Some(10.0), None, None),
+        );
+        assert_eq!(quota_left_percent_from_used(Some(99.6)), Some(0));
+        assert!(!quota_used_percent_is_exhausted(Some(99.6)));
+        assert!(!is_quota_cache_entry_exhausted(Some(&fractional), NOW));
+    }
+
+    #[test]
+    fn does_not_treat_expired_quota_windows_as_exhausted() {
+        let expired = entry(
+            (NOW - 600_000) as f64,
+            window(Some(100.0), None, Some((NOW - 1) as f64)),
+            window(Some(100.0), None, Some((NOW - 60_000) as f64)),
+        );
+        assert!(!is_quota_cache_entry_exhausted(Some(&expired), NOW));
+    }
+
+    #[test]
+    fn expires_an_exhausted_window_with_no_reset_at_after_window_minutes_elapse() {
+        // 300-minute window, snapshot taken 301 minutes ago, no resetAtMs.
+        let stale = entry(
+            (NOW - 301 * 60_000) as f64,
+            window(Some(100.0), Some(300.0), None),
+            window(Some(10.0), None, None),
+        );
+        assert!(!is_quota_cache_entry_exhausted(Some(&stale), NOW));
+    }
+
+    #[test]
+    fn still_reports_exhausted_with_no_reset_at_before_the_window_elapses() {
+        let fresh = entry(
+            (NOW - 60_000) as f64,
+            window(Some(100.0), Some(300.0), None),
+            window(Some(10.0), None, None),
+        );
+        assert!(is_quota_cache_entry_exhausted(Some(&fresh), NOW));
+    }
+
+    #[test]
+    fn expires_an_exhausted_secondary_window_with_no_reset_at_after_its_window_elapses() {
+        let stale_secondary = entry(
+            (NOW - 10_081 * 60_000) as f64,
+            window(Some(10.0), Some(300.0), None),
+            window(Some(100.0), Some(10_080.0), None),
+        );
+        assert!(!is_quota_cache_entry_exhausted(Some(&stale_secondary), NOW));
+    }
+
+    #[test]
+    fn treats_the_exact_window_boundary_as_expired_inclusive() {
+        // now == updatedAt + windowMinutes * 60_000 exactly.
+        let boundary = entry(
+            (NOW - 300 * 60_000) as f64,
+            window(Some(100.0), Some(300.0), None),
+            window(Some(10.0), None, None),
+        );
+        assert!(!is_quota_cache_entry_exhausted(Some(&boundary), NOW));
+    }
+
+    #[test]
+    fn stays_exhausted_when_window_minutes_is_missing() {
+        let no_window = entry(
+            (NOW - 100 * 86_400_000) as f64,
+            window(Some(100.0), None, None),
+            window(Some(10.0), None, None),
+        );
+        assert!(is_quota_cache_entry_exhausted(Some(&no_window), NOW));
+    }
+
+    #[test]
+    fn stays_exhausted_when_window_minutes_is_zero_or_negative() {
+        for minutes in [0.0, -300.0] {
+            let bad_minutes = entry(
+                (NOW - 100 * 86_400_000) as f64,
+                window(Some(100.0), Some(minutes), None),
+                window(Some(10.0), None, None),
+            );
+            assert!(
+                is_quota_cache_entry_exhausted(Some(&bad_minutes), NOW),
+                "windowMinutes {minutes} must not enable the staleness escape"
+            );
+        }
+    }
+
+    #[test]
+    fn does_not_prematurely_expire_when_updated_at_is_in_the_future_clock_skew() {
+        let future_snapshot = entry(
+            (NOW + 60_000) as f64,
+            window(Some(100.0), Some(300.0), None),
+            window(Some(10.0), None, None),
+        );
+        assert!(is_quota_cache_entry_exhausted(Some(&future_snapshot), NOW));
+    }
+
+    // -- keying rules --------------------------------------------------------
+
+    fn account(account_id: Option<&str>, email: Option<&str>) -> QuotaAccountRef {
+        QuotaAccountRef {
+            account_id: account_id.map(str::to_string),
+            email: email.map(str::to_string),
+        }
+    }
+
+    #[test]
+    fn normalizers_trim_and_lowercase() {
+        assert_eq!(
+            normalize_quota_account_id(Some("  acc_1  ")),
+            Some("acc_1".to_string())
+        );
+        assert_eq!(normalize_quota_account_id(Some("   ")), None);
+        assert_eq!(normalize_quota_account_id(None), None);
+        assert_eq!(
+            normalize_quota_email(Some("  User@Example.COM ")),
+            Some("user@example.com".to_string())
+        );
+        assert_eq!(normalize_quota_email(Some("")), None);
+        assert_eq!(normalize_quota_email(None), None);
+    }
+
+    #[test]
+    fn unique_account_id_requires_exactly_one_match() {
+        let a = account(Some("acc_1"), Some("a@example.com"));
+        let b = account(Some("acc_2"), Some("b@example.com"));
+        let dup = account(Some("acc_1"), Some("c@example.com"));
+
+        assert!(has_unique_quota_account_id(
+            &[a.clone(), b.clone()],
+            &a.clone()
+        ));
+        assert!(!has_unique_quota_account_id(
+            &[a.clone(), b.clone(), dup.clone()],
+            &a.clone()
+        ));
+        let no_id = account(None, Some("x@example.com"));
+        assert!(!has_unique_quota_account_id(
+            std::slice::from_ref(&no_id),
+            &no_id
+        ));
+    }
+
+    #[test]
+    fn email_fallback_is_safe_only_for_a_single_unambiguous_account() {
+        let solo = account(None, Some("solo@example.com"));
+        let dup_a = account(Some("acc_1"), Some("dup@example.com"));
+        let dup_b = account(Some("acc_2"), Some("dup@example.com"));
+        let accounts = vec![solo.clone(), dup_a.clone(), dup_b.clone()];
+        let state = build_quota_email_fallback_state(&accounts);
+
+        assert!(has_safe_quota_email_fallback(&state, &solo));
+        assert!(!has_safe_quota_email_fallback(&state, &dup_a));
+        assert!(!has_safe_quota_email_fallback(&state, &dup_b));
+        assert!(!has_safe_quota_email_fallback(&state, &account(None, None)));
+    }
+
+    #[test]
+    fn find_entry_prefers_unique_account_id_then_safe_email() {
+        let mut cache = QuotaCacheData::default();
+        cache.by_account_id.insert(
+            "acc_1",
+            entry(
+                NOW as f64,
+                window(Some(1.0), None, None),
+                window(None, None, None),
+            ),
+        );
+        cache.by_email.insert(
+            "mail@example.com",
+            entry(
+                NOW as f64,
+                window(Some(2.0), None, None),
+                window(None, None, None),
+            ),
+        );
+
+        let by_id = account(Some("acc_1"), Some("mail@example.com"));
+        let accounts = vec![by_id.clone()];
+        let found = find_quota_cache_entry_for_account(Some(&cache), &by_id, &accounts)
+            .expect("entry by accountId");
+        assert_eq!(found.primary.used_percent, Some(1.0));
+
+        // Email fallback fires only when the account did not resolve by id.
+        let by_email = account(None, Some("Mail@Example.com"));
+        let accounts = vec![by_email.clone()];
+        let found = find_quota_cache_entry_for_account(Some(&cache), &by_email, &accounts)
+            .expect("entry by email");
+        assert_eq!(found.primary.used_percent, Some(2.0));
+
+        // Ambiguous email → no entry at all.
+        let dup_a = account(Some("acc_a"), Some("mail@example.com"));
+        let dup_b = account(Some("acc_b"), Some("mail@example.com"));
+        let accounts = vec![dup_a.clone(), dup_b];
+        assert!(find_quota_cache_entry_for_account(Some(&cache), &dup_a, &accounts).is_none());
+
+        // Null cache → null.
+        assert!(
+            find_quota_cache_entry_for_account(None, &by_id, std::slice::from_ref(&by_id))
+                .is_none()
+        );
+    }
+}
diff --git a/crates/quota/src/runtime_policy.rs b/crates/quota/src/runtime_policy.rs
new file mode 100644
index 000000000..4ad3b3d20
--- /dev/null
+++ b/crates/quota/src/runtime_policy.rs
@@ -0,0 +1,862 @@
+//! Port of `lib/policy/runtime-policy.ts` — the pre-request policy gate the
+//! proxy pipeline consults before any account work, plus the once-only usage
+//! recorder factory.
+//!
+//! Gate order (spec 13 §5.2 + ARCHITECTURE 6.11): model allow/deny substring
+//! match → soft budget evaluation (vs the usage ledger with
+//! `include_archives: true` — quota-forecast-03) → pause/drain blocks →
+//! tag/weight score boosts → capability suppression, which is keyed by the
+//! ENTITLEMENT account key (`resolveEntitlementAccountKey`), NOT the policy
+//! key — quota-forecast-01: the capability store is written under the
+//! entitlement key at the `recordUnsupported` sites, so the read must use the
+//! same key or suppression is dead.
+//!
+//! Budget enforcement is soft / eventually-consistent under concurrency
+//! (audit L10): evaluations read a pre-request ledger snapshot while
+//! consumption is only recorded at completion, so racing requests can
+//! transiently overshoot. Intentional — budgets are a best-effort guard.
+
+use std::collections::{HashMap, HashSet};
+use std::io;
+use std::path::Path;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use cma_accounts::account_policy::{
+    AccountPolicyStore, get_account_policy_key_from_parts, load_account_policy_store,
+};
+use cma_accounts::capability_policy::CapabilityPolicyStore;
+use cma_accounts::entitlement_cache::{EntitlementAccountRef, resolve_entitlement_account_key};
+use cma_accounts::routing_profiles::{
+    ProjectRoutingProfileContext, resolve_project_routing_profile,
+};
+use cma_core::utils::now_ms;
+use cma_usage::ledger::{append_usage_ledger_row, summarize_usage_ledger};
+use cma_usage::types::{
+    UsageLedgerAppendInput, UsageLedgerOperation, UsageLedgerOutcome, UsageLedgerRow,
+    UsageLedgerSource, UsageSummaryQuery,
+};
+
+use crate::budget_guard::{
+    BudgetGuardEvaluation, BudgetGuardStore, evaluate_budget_guard, get_budget_window_start,
+    load_budget_guard_store, normalize_budget_key,
+};
+
+/// TS `interface RuntimePolicyAccount`.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RuntimePolicyAccount {
+    pub index: i64,
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+}
+
+/// TS `interface RuntimePolicyDecision`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct RuntimePolicyDecision {
+    pub allowed: bool,
+    /// 429 when blocked by a budget, 403 otherwise (only meaningful when
+    /// `allowed == false`).
+    pub status_code: u16,
+    /// `None` when allowed; `"budget_blocked"` / `"policy_blocked"`.
+    pub error_code: Option<String>,
+    pub reasons: Vec<String>,
+    pub project_key: Option<String>,
+    pub blocked_account_indexes: HashSet<i64>,
+    pub score_boost_by_account: HashMap<i64, f64>,
+    pub budget_evaluations: Vec<BudgetGuardEvaluation>,
+}
+
+/// TS `interface RuntimePolicyState`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct RuntimePolicyState {
+    pub account_policies: AccountPolicyStore,
+    pub budgets: BudgetGuardStore,
+    pub project: ProjectRoutingProfileContext,
+}
+
+/// TS `loadRuntimePolicyState(startDir = process.cwd())` — the three loads
+/// run concurrently (`Promise.all`); each is individually never-failing.
+pub async fn load_runtime_policy_state(start_dir: &Path) -> RuntimePolicyState {
+    let (account_policies, budgets, project) = tokio::join!(
+        load_account_policy_store(),
+        load_budget_guard_store(),
+        resolve_project_routing_profile(start_dir),
+    );
+    RuntimePolicyState {
+        account_policies,
+        budgets,
+        project,
+    }
+}
+
+/// TS `normalizeToken` — trim + lowercase, `None` when empty.
+fn normalize_token(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim().to_lowercase();
+    if trimmed.is_empty() { None } else { Some(trimmed) }
+}
+
+/// TS `matchesModel(patterns, model)` — exact OR substring match over
+/// normalized tokens; an un-normalizable model never matches.
+fn matches_model(patterns: &[String], model: Option<&str>) -> bool {
+    let Some(normalized_model) = normalize_token(model) else {
+        return false;
+    };
+    patterns
+        .iter()
+        .any(|pattern| match normalize_token(Some(pattern)) {
+            Some(normalized_pattern) => {
+                normalized_model == normalized_pattern
+                    || normalized_model.contains(&normalized_pattern)
+            }
+            None => false,
+        })
+}
+
+/// TS `intersects(left, right)`.
+fn intersects(left: &[String], right: &[String]) -> bool {
+    let right_set: HashSet<&str> = right.iter().map(String::as_str).collect();
+    left.iter().any(|entry| right_set.contains(entry.as_str()))
+}
+
+/// TS `evaluateBudgets` — checks `global`, the normalized
+/// `project:{projectKey}` and the normalized profile `budgetKey` (dedupe,
+/// insertion order). Keys are looked up through [`normalize_budget_key`]
+/// because the store only ever holds normalized keys — an un-normalized
+/// runtime key (`project:MyApp`) must still hit its stored `project:myapp`
+/// limit or the budget is silently unenforced.
+async fn evaluate_budgets(
+    state: &RuntimePolicyState,
+    now: i64,
+) -> io::Result<Vec<BudgetGuardEvaluation>> {
+    let mut keys: Vec<String> = vec!["global".to_string()];
+    if let Some(project_key) = &state.project.project_key
+        && let Some(key) = normalize_budget_key(&format!("project:{project_key}"))
+        && !keys.contains(&key)
+    {
+        keys.push(key);
+    }
+    if let Some(profile) = &state.project.profile
+        && let Some(budget_key) = &profile.budget_key
+        && let Some(key) = normalize_budget_key(budget_key)
+        && !keys.contains(&key)
+    {
+        keys.push(key);
+    }
+    let mut evaluations = Vec::new();
+    for key in keys {
+        let Some(limit) = state.budgets.get(&key) else {
+            continue;
+        };
+        let summary = summarize_usage_ledger(&UsageSummaryQuery {
+            since: Some(get_budget_window_start(limit.window, now) as f64),
+            until: Some(now as f64),
+            // Budget windows (e.g. monthly) can span a ledger rotation.
+            // Without archives, rotated-out rows are dropped from the sum,
+            // under-counting spend (quota-forecast-03).
+            include_archives: true,
+            by: None,
+        })
+        .await?;
+        evaluations.push(evaluate_budget_guard(limit, &summary));
+    }
+    Ok(evaluations)
+}
+
+/// Input for [`evaluate_runtime_policy`].
+#[derive(Clone, Copy)]
+pub struct EvaluateRuntimePolicyInput<'a> {
+    pub state: &'a RuntimePolicyState,
+    pub accounts: &'a [RuntimePolicyAccount],
+    pub model: Option<&'a str>,
+    pub capability_policy: Option<&'a CapabilityPolicyStore>,
+    /// `None` → wall clock (TS `now ?? Date.now()`).
+    pub now: Option<i64>,
+}
+
+/// TS `evaluateRuntimePolicy(input)`.
+///
+/// Errors bubble up from the usage-ledger read (the TS promise rejected the
+/// same way); the pipeline caller treats any error as FAIL-OPEN.
+pub async fn evaluate_runtime_policy(
+    input: EvaluateRuntimePolicyInput<'_>,
+) -> io::Result<RuntimePolicyDecision> {
+    let now = input.now.unwrap_or_else(now_ms);
+    let mut reasons: Vec<String> = Vec::new();
+    let mut blocked_account_indexes: HashSet<i64> = HashSet::new();
+    let mut score_boost_by_account: HashMap<i64, f64> = HashMap::new();
+    let profile = input.state.project.profile.as_ref();
+
+    if let Some(profile) = profile
+        && !profile.model_denylist.is_empty()
+        && matches_model(&profile.model_denylist, input.model)
+    {
+        reasons.push("routing profile denies requested model".to_string());
+    }
+    if let Some(profile) = profile
+        && !profile.model_allowlist.is_empty()
+        && !matches_model(&profile.model_allowlist, input.model)
+    {
+        reasons.push("routing profile does not allow requested model".to_string());
+    }
+
+    let budget_evaluations = evaluate_budgets(input.state, now).await?;
+    for evaluation in &budget_evaluations {
+        if !evaluation.allowed {
+            reasons.push(format!(
+                "budget {} blocked request: {}",
+                evaluation.key,
+                evaluation.reasons.join("; ")
+            ));
+        }
+    }
+
+    for account in input.accounts {
+        let account_key = get_account_policy_key_from_parts(
+            account.account_id.as_deref(),
+            account.email.as_deref(),
+        );
+        let account_policy = input.state.account_policies.get(&account_key);
+        let mut boost = 0.0_f64;
+        if let Some(policy) = account_policy {
+            if policy.paused {
+                blocked_account_indexes.insert(account.index);
+            }
+            if policy.drained {
+                blocked_account_indexes.insert(account.index);
+            }
+            boost += (policy.weight - 1.0) * 2.0;
+            if let Some(profile) = profile {
+                if !profile.preferred_tags.is_empty()
+                    && intersects(&policy.tags, &profile.preferred_tags)
+                {
+                    boost += 8.0;
+                }
+                if !profile.avoid_tags.is_empty() && intersects(&policy.tags, &profile.avoid_tags) {
+                    boost -= 8.0;
+                }
+            }
+        }
+        if let Some(profile) = profile
+            && let Some(weight) = profile.account_weight_by_key.get(&account_key)
+        {
+            boost += weight * 2.0;
+        }
+        // quota-forecast-01: read the capability store under the SAME key the
+        // recordUnsupported sites write (the entitlement key), never the
+        // policy key.
+        let capability_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: account.account_id.clone(),
+            email: account.email.clone(),
+            refresh_token: None,
+            index: Some(account.index),
+        });
+        if let Some(capability_policy) = input.capability_policy
+            && let Some(snapshot) =
+                capability_policy.get_snapshot(&capability_key, input.model.unwrap_or("unknown"))
+            && snapshot.unsupported > 0
+        {
+            blocked_account_indexes.insert(account.index);
+        }
+        score_boost_by_account.insert(account.index, boost);
+    }
+
+    let blocked_by_budget = budget_evaluations
+        .iter()
+        .any(|evaluation| !evaluation.allowed);
+    let allowed = reasons.is_empty() && !blocked_by_budget;
+    Ok(RuntimePolicyDecision {
+        allowed,
+        status_code: if blocked_by_budget { 429 } else { 403 },
+        error_code: if allowed {
+            None
+        } else if blocked_by_budget {
+            Some("budget_blocked".to_string())
+        } else {
+            Some("policy_blocked".to_string())
+        },
+        reasons,
+        project_key: input.state.project.project_key.clone(),
+        blocked_account_indexes,
+        score_boost_by_account,
+        budget_evaluations,
+    })
+}
+
+/// Boxed append future (test seam for the TS injectable `append`).
+pub type UsageAppendFuture =
+    Pin<Box<dyn std::future::Future<Output = io::Result<UsageLedgerRow>> + Send>>;
+/// Injectable append function (defaults to `appendUsageLedgerRow`).
+pub type UsageAppendFn = Arc<dyn Fn(UsageLedgerAppendInput) -> UsageAppendFuture + Send + Sync>;
+
+/// TS `createRuntimeUsageRecorder` options.
+#[derive(Clone)]
+pub struct RuntimeUsageRecorderOptions {
+    pub source: UsageLedgerSource,
+    pub operation: UsageLedgerOperation,
+    pub model: Option<String>,
+    pub project_key: Option<String>,
+    pub request_id: Option<String>,
+    /// `None` → wall clock at creation.
+    pub started_at: Option<i64>,
+    /// Test seam; `None` uses [`append_usage_ledger_row`].
+    pub append: Option<UsageAppendFn>,
+}
+
+/// TS `interface RuntimeUsageRecordInput`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct RuntimeUsageRecordInput {
+    /// Required in TS; `Default` falls back to `Failure` (an unclassifiable
+    /// outcome must never count as a success) — always set it explicitly.
+    pub outcome: Option<UsageLedgerOutcome>,
+    pub status_code: Option<i64>,
+    pub error_code: Option<String>,
+    pub duration_ms: Option<i64>,
+    pub account: Option<RuntimePolicyAccount>,
+    pub input_tokens: Option<f64>,
+    pub output_tokens: Option<f64>,
+    pub cached_input_tokens: Option<f64>,
+    pub reasoning_tokens: Option<f64>,
+    pub total_tokens: Option<f64>,
+}
+
+/// TS `interface RuntimeUsageRecorder` — records AT MOST once per request
+/// lifecycle; later calls are silent no-ops. Append failures are swallowed
+/// (`.catch(() => undefined)`).
+pub struct RuntimeUsageRecorder {
+    recorded: AtomicBool,
+    source: UsageLedgerSource,
+    operation: UsageLedgerOperation,
+    model: Option<String>,
+    project_key: Option<String>,
+    request_id: Option<String>,
+    started_at: i64,
+    append: Option<UsageAppendFn>,
+}
+
+impl std::fmt::Debug for RuntimeUsageRecorder {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RuntimeUsageRecorder")
+            .field("recorded", &self.has_recorded())
+            .field("source", &self.source)
+            .field("operation", &self.operation)
+            .finish()
+    }
+}
+
+/// TS `createRuntimeUsageRecorder(input)`.
+pub fn create_runtime_usage_recorder(options: RuntimeUsageRecorderOptions) -> RuntimeUsageRecorder {
+    RuntimeUsageRecorder {
+        recorded: AtomicBool::new(false),
+        source: options.source,
+        operation: options.operation,
+        model: options.model,
+        project_key: options.project_key,
+        request_id: options.request_id,
+        started_at: options.started_at.unwrap_or_else(now_ms),
+        append: options.append,
+    }
+}
+
+impl RuntimeUsageRecorder {
+    /// TS `hasRecorded()`.
+    pub fn has_recorded(&self) -> bool {
+        self.recorded.load(Ordering::SeqCst)
+    }
+
+    /// TS `record(input)` — first call wins; builds the append row
+    /// (`durationMs ?? Date.now() - startedAt`) and swallows append errors.
+    pub async fn record(&self, input: RuntimeUsageRecordInput) {
+        if self.recorded.swap(true, Ordering::SeqCst) {
+            return;
+        }
+        let account = input.account.as_ref();
+        let row = UsageLedgerAppendInput {
+            id: None,
+            created_at: None,
+            source: Some(self.source.as_str().to_string()),
+            operation: Some(self.operation.as_str().to_string()),
+            outcome: Some(
+                input
+                    .outcome
+                    .unwrap_or(UsageLedgerOutcome::Failure)
+                    .as_str()
+                    .to_string(),
+            ),
+            model: self.model.clone(),
+            project_key: self.project_key.clone(),
+            account_id: account.and_then(|a| a.account_id.clone()),
+            email: account.and_then(|a| a.email.clone()),
+            account_index: account.map(|a| a.index as f64),
+            request_id: self.request_id.clone(),
+            status_code: input.status_code.map(|code| code as f64),
+            error_code: input.error_code.clone(),
+            duration_ms: Some(
+                input
+                    .duration_ms
+                    .unwrap_or_else(|| now_ms() - self.started_at) as f64,
+            ),
+            input_tokens: input.input_tokens,
+            output_tokens: input.output_tokens,
+            cached_input_tokens: input.cached_input_tokens,
+            reasoning_tokens: input.reasoning_tokens,
+            total_tokens: input.total_tokens,
+            cost_usd: None,
+        };
+        match &self.append {
+            Some(append) => {
+                let _ = append(row).await;
+            }
+            None => {
+                let _ = append_usage_ledger_row(&row).await;
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::budget_guard::{BudgetLimit, BudgetWindow};
+    use cma_accounts::account_policy::AccountPolicy;
+    use cma_accounts::routing_profiles::{AccountWeightMap, RoutingProfile};
+    use cma_testkit::sandbox::EnvSandbox;
+    use cma_usage::ledger::rotate_usage_ledger;
+    use cma_usage::ledger::RotateUsageLedgerOptions;
+    use serial_test::serial;
+    use std::path::PathBuf;
+    use std::sync::Mutex;
+
+    fn utc_ms(year: i32, month: u32, day: u32, hour: u32) -> i64 {
+        use chrono::TimeZone;
+        chrono::Utc
+            .with_ymd_and_hms(year, month, day, hour, 0, 0)
+            .unwrap()
+            .timestamp_millis()
+    }
+
+    fn state() -> RuntimePolicyState {
+        RuntimePolicyState {
+            account_policies: AccountPolicyStore::empty(),
+            budgets: BudgetGuardStore::empty(),
+            project: ProjectRoutingProfileContext {
+                start_dir: PathBuf::from("/repo"),
+                project_root: Some(PathBuf::from("/repo")),
+                identity_root: Some(PathBuf::from("/repo")),
+                project_key: Some("project-a".to_string()),
+                profile: None,
+            },
+        }
+    }
+
+    fn profile() -> RoutingProfile {
+        RoutingProfile {
+            project_key: "project-a".to_string(),
+            project_name: "Project A".to_string(),
+            identity_root: "/repo".to_string(),
+            preferred_tags: Vec::new(),
+            avoid_tags: Vec::new(),
+            model_allowlist: Vec::new(),
+            model_denylist: Vec::new(),
+            account_weight_by_key: AccountWeightMap::new(),
+            budget_key: None,
+            updated_at: 1.0,
+        }
+    }
+
+    fn day_limit(key: &str, max_requests: f64) -> BudgetLimit {
+        BudgetLimit {
+            key: key.to_string(),
+            window: BudgetWindow::Day,
+            max_requests: Some(max_requests),
+            max_tokens: None,
+            max_cost_usd: None,
+            updated_at: 1.0,
+        }
+    }
+
+    async fn append_success_row(id: Option<&str>, created_at: i64) {
+        append_usage_ledger_row(&UsageLedgerAppendInput {
+            id: id.map(str::to_string),
+            created_at: Some(created_at as f64),
+            source: Some("runtime-proxy".to_string()),
+            operation: Some("responses".to_string()),
+            outcome: Some("success".to_string()),
+            model: Some("gpt-5.3-codex".to_string()),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+    }
+
+    fn append_stub_row() -> io::Result<UsageLedgerRow> {
+        // Minimal well-formed row for the injected-append seam.
+        Ok(UsageLedgerRow {
+            version: 1,
+            id: "row-1".to_string(),
+            created_at: 100.0,
+            source: UsageLedgerSource::PluginHost,
+            operation: UsageLedgerOperation::Responses,
+            outcome: UsageLedgerOutcome::Success,
+            model: None,
+            project_key: None,
+            account: None,
+            request_id: None,
+            status_code: None,
+            error_code: None,
+            duration_ms: Some(0),
+            tokens: Default::default(),
+            cost_usd: None,
+        })
+    }
+
+    #[tokio::test]
+    async fn blocks_paused_accounts_and_adds_profile_score_boosts() {
+        let mut policy_state = state();
+        let account_key = get_account_policy_key_from_parts(Some("acct_1"), None);
+        policy_state.account_policies.insert(
+            account_key.clone(),
+            AccountPolicy {
+                account_key: account_key.clone(),
+                tags: vec!["fast".to_string()],
+                weight: 3.0,
+                paused: true,
+                drained: false,
+                note: None,
+                updated_at: 1.0,
+            },
+        );
+        let mut project_profile = profile();
+        project_profile.preferred_tags = vec!["fast".to_string()];
+        project_profile.model_allowlist = vec!["gpt-5.3-codex".to_string()];
+        project_profile
+            .account_weight_by_key
+            .insert(account_key.clone(), 2.0);
+        policy_state.project.profile = Some(project_profile);
+
+        let accounts = [RuntimePolicyAccount {
+            index: 0,
+            account_id: Some("acct_1".to_string()),
+            email: Some("owner@example.com".to_string()),
+        }];
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &accounts,
+            model: Some("gpt-5.3-codex"),
+            capability_policy: None,
+            now: Some(100),
+        })
+        .await
+        .unwrap();
+
+        assert!(decision.allowed);
+        assert!(decision.blocked_account_indexes.contains(&0));
+        // (weight 3 - 1) * 2 + preferred-tag 8 + account-weight 2 * 2 = 16.
+        assert_eq!(decision.score_boost_by_account.get(&0), Some(&16.0));
+    }
+
+    #[tokio::test]
+    async fn denylist_and_allowlist_reasons_are_frozen() {
+        let mut policy_state = state();
+        let mut project_profile = profile();
+        project_profile.model_denylist = vec!["sol".to_string()];
+        project_profile.model_allowlist = vec!["gpt-5.3-codex".to_string()];
+        policy_state.project.profile = Some(project_profile);
+
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &[],
+            model: Some("gpt-5.6-sol"),
+            capability_policy: None,
+            now: Some(100),
+        })
+        .await
+        .unwrap();
+
+        assert!(!decision.allowed);
+        assert_eq!(decision.status_code, 403);
+        assert_eq!(decision.error_code.as_deref(), Some("policy_blocked"));
+        assert_eq!(
+            decision.reasons,
+            vec![
+                "routing profile denies requested model".to_string(),
+                "routing profile does not allow requested model".to_string(),
+            ]
+        );
+    }
+
+    // quota-forecast-01: capability suppression reads the store under the
+    // SAME key the recordUnsupported sites write (entitlement key). A record
+    // written under that key must block the account here.
+    #[tokio::test]
+    async fn blocks_account_whose_model_was_recorded_unsupported() {
+        let mut capability_policy = CapabilityPolicyStore::new();
+        let account = RuntimePolicyAccount {
+            index: 0,
+            account_id: Some("acct_cap".to_string()),
+            email: Some("cap@example.com".to_string()),
+        };
+        let model = "gpt-5.3-codex";
+        let entitlement_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: account.account_id.clone(),
+            email: account.email.clone(),
+            refresh_token: None,
+            index: Some(account.index),
+        });
+        capability_policy.record_unsupported(&entitlement_key, model, 100);
+
+        let policy_state = state();
+        let accounts = [account];
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &accounts,
+            model: Some(model),
+            capability_policy: Some(&capability_policy),
+            now: Some(100),
+        })
+        .await
+        .unwrap();
+
+        assert!(decision.blocked_account_indexes.contains(&0));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn blocks_requests_when_matching_budget_is_exhausted() {
+        let _sandbox = EnvSandbox::new();
+        let mut policy_state = state();
+        policy_state
+            .budgets
+            .insert("global", day_limit("global", 1.0));
+        append_success_row(None, utc_ms(2026, 4, 29, 1)).await;
+
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &[],
+            model: Some("gpt-5.3-codex"),
+            capability_policy: None,
+            now: Some(utc_ms(2026, 4, 29, 2)),
+        })
+        .await
+        .unwrap();
+
+        assert!(!decision.allowed);
+        assert_eq!(decision.status_code, 429);
+        assert_eq!(decision.error_code.as_deref(), Some("budget_blocked"));
+    }
+
+    // budget-guard stores limits ONLY under normalizeBudgetKey; a runtime
+    // projectKey carrying uppercase must be normalized before lookup or the
+    // budget is silently unenforced.
+    #[tokio::test]
+    #[serial(env)]
+    async fn enforces_project_budget_stored_under_normalized_key() {
+        let _sandbox = EnvSandbox::new();
+        let mut policy_state = state();
+        policy_state.project.project_key = Some("MyApp".to_string());
+        policy_state
+            .budgets
+            .insert("project:myapp", day_limit("project:myapp", 1.0));
+        append_success_row(None, utc_ms(2026, 4, 29, 1)).await;
+
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &[],
+            model: Some("gpt-5.3-codex"),
+            capability_policy: None,
+            now: Some(utc_ms(2026, 4, 29, 2)),
+        })
+        .await
+        .unwrap();
+
+        assert!(!decision.allowed);
+        assert_eq!(decision.status_code, 429);
+        assert_eq!(decision.error_code.as_deref(), Some("budget_blocked"));
+        assert!(
+            decision
+                .budget_evaluations
+                .iter()
+                .any(|evaluation| evaluation.key == "project:myapp" && !evaluation.allowed)
+        );
+    }
+
+    // Same normalization gap on the routing profile's budgetKey: stored as
+    // `team-alpha`, carried at runtime as `Team Alpha`.
+    #[tokio::test]
+    #[serial(env)]
+    async fn enforces_profile_budget_stored_under_normalized_key() {
+        let _sandbox = EnvSandbox::new();
+        let mut policy_state = state();
+        let mut project_profile = profile();
+        project_profile.budget_key = Some("Team Alpha".to_string());
+        policy_state.project.profile = Some(project_profile);
+        policy_state
+            .budgets
+            .insert("team-alpha", day_limit("team-alpha", 1.0));
+        append_success_row(None, utc_ms(2026, 4, 29, 1)).await;
+
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &[],
+            model: Some("gpt-5.3-codex"),
+            capability_policy: None,
+            now: Some(utc_ms(2026, 4, 29, 2)),
+        })
+        .await
+        .unwrap();
+
+        assert!(!decision.allowed);
+        assert_eq!(decision.error_code.as_deref(), Some("budget_blocked"));
+        assert!(
+            decision
+                .budget_evaluations
+                .iter()
+                .any(|evaluation| evaluation.key == "team-alpha" && !evaluation.allowed)
+        );
+    }
+
+    #[tokio::test]
+    async fn records_usage_at_most_once() {
+        let seen: Arc<Mutex<Vec<UsageLedgerAppendInput>>> = Arc::new(Mutex::new(Vec::new()));
+        let sink = Arc::clone(&seen);
+        let append: UsageAppendFn = Arc::new(move |row| {
+            let sink = Arc::clone(&sink);
+            Box::pin(async move {
+                sink.lock().unwrap().push(row);
+                append_stub_row()
+            })
+        });
+        let recorder = create_runtime_usage_recorder(RuntimeUsageRecorderOptions {
+            source: UsageLedgerSource::PluginHost,
+            operation: UsageLedgerOperation::Responses,
+            model: Some("gpt-5.3-codex".to_string()),
+            project_key: Some("project-a".to_string()),
+            request_id: Some("req-1".to_string()),
+            started_at: Some(100),
+            append: Some(append),
+        });
+
+        recorder
+            .record(RuntimeUsageRecordInput {
+                outcome: Some(UsageLedgerOutcome::Success),
+                status_code: Some(200),
+                account: Some(RuntimePolicyAccount {
+                    index: 0,
+                    account_id: Some("acct_1".to_string()),
+                    email: Some("owner@example.com".to_string()),
+                }),
+                ..Default::default()
+            })
+            .await;
+        recorder
+            .record(RuntimeUsageRecordInput {
+                outcome: Some(UsageLedgerOutcome::Failure),
+                status_code: Some(500),
+                ..Default::default()
+            })
+            .await;
+
+        let calls = seen.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        let row = &calls[0];
+        assert_eq!(row.source.as_deref(), Some("plugin-host"));
+        assert_eq!(row.operation.as_deref(), Some("responses"));
+        assert_eq!(row.outcome.as_deref(), Some("success"));
+        assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(row.project_key.as_deref(), Some("project-a"));
+        assert_eq!(row.request_id.as_deref(), Some("req-1"));
+        assert_eq!(row.status_code, Some(200.0));
+        assert_eq!(row.account_id.as_deref(), Some("acct_1"));
+        assert_eq!(row.email.as_deref(), Some("owner@example.com"));
+        assert_eq!(row.account_index, Some(0.0));
+        assert!(recorder.has_recorded());
+    }
+
+    #[tokio::test]
+    async fn records_thread_goal_usage_as_distinct_operation() {
+        let seen: Arc<Mutex<Vec<UsageLedgerAppendInput>>> = Arc::new(Mutex::new(Vec::new()));
+        let sink = Arc::clone(&seen);
+        let append: UsageAppendFn = Arc::new(move |row| {
+            let sink = Arc::clone(&sink);
+            Box::pin(async move {
+                sink.lock().unwrap().push(row);
+                append_stub_row()
+            })
+        });
+        let recorder = create_runtime_usage_recorder(RuntimeUsageRecorderOptions {
+            source: UsageLedgerSource::RuntimeProxy,
+            operation: UsageLedgerOperation::ThreadGoal,
+            model: None,
+            project_key: Some("project-a".to_string()),
+            request_id: Some("thread-1".to_string()),
+            started_at: Some(100),
+            append: Some(append),
+        });
+
+        recorder
+            .record(RuntimeUsageRecordInput {
+                outcome: Some(UsageLedgerOutcome::Failure),
+                status_code: Some(403),
+                error_code: Some("thread_goal_upstream_blocked".to_string()),
+                ..Default::default()
+            })
+            .await;
+
+        let calls = seen.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        let row = &calls[0];
+        assert_eq!(row.source.as_deref(), Some("runtime-proxy"));
+        assert_eq!(row.operation.as_deref(), Some("thread-goal"));
+        assert_eq!(row.outcome.as_deref(), Some("failure"));
+        assert_eq!(row.request_id.as_deref(), Some("thread-1"));
+        assert_eq!(row.status_code, Some(403.0));
+        assert_eq!(
+            row.error_code.as_deref(),
+            Some("thread_goal_upstream_blocked")
+        );
+    }
+
+    // quota-forecast-03: a budget window can span a usage-ledger rotation.
+    // A pre-rotation row lives only in the archives; blocking proves the
+    // archived row is counted (includeArchives: true).
+    #[tokio::test]
+    #[serial(env)]
+    async fn counts_archived_spend_when_budget_window_spans_ledger_rotation() {
+        let _sandbox = EnvSandbox::new();
+        let mut policy_state = state();
+        policy_state
+            .budgets
+            .insert("global", day_limit("global", 2.0));
+
+        append_success_row(Some("before-rotate"), utc_ms(2026, 4, 29, 1)).await;
+        let rotated = rotate_usage_ledger(&RotateUsageLedgerOptions {
+            now: Some(utc_ms(2026, 4, 29, 2) as f64),
+            if_larger_than_bytes: None,
+        })
+        .await
+        .unwrap();
+        assert!(rotated.is_some());
+        append_success_row(Some("after-rotate"), utc_ms(2026, 4, 29, 3)).await;
+
+        let decision = evaluate_runtime_policy(EvaluateRuntimePolicyInput {
+            state: &policy_state,
+            accounts: &[],
+            model: Some("gpt-5.3-codex"),
+            capability_policy: None,
+            now: Some(utc_ms(2026, 4, 29, 4)),
+        })
+        .await
+        .unwrap();
+
+        // 2 requests in-window (1 archived + 1 current) >= maxRequests:2.
+        assert!(!decision.allowed);
+        assert_eq!(decision.status_code, 429);
+        assert_eq!(decision.error_code.as_deref(), Some("budget_blocked"));
+        let global_eval = decision
+            .budget_evaluations
+            .iter()
+            .find(|evaluation| evaluation.key == "global")
+            .expect("global evaluation");
+        assert_eq!(global_eval.usage.requests, 2);
+    }
+}
diff --git a/crates/request/Cargo.toml b/crates/request/Cargo.toml
new file mode 100644
index 000000000..9403b9b71
--- /dev/null
+++ b/crates/request/Cargo.toml
@@ -0,0 +1,38 @@
+[package]
+name = "cma-request"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-auth = { path = "../auth" }
+cma-accounts = { path = "../accounts" }
+cma-storage = { path = "../storage" }
+serde.workspace = true
+serde_json.workspace = true
+reqwest.workspace = true
+url.workspace = true
+http.workspace = true
+bytes.workspace = true
+futures.workspace = true
+tokio.workspace = true
+tokio-util.workspace = true
+regex.workspace = true
+sha2.workspace = true
+base64.workspace = true
+chrono.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+wiremock.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/request/assets/codex-host-bridge.txt b/crates/request/assets/codex-host-bridge.txt
new file mode 100644
index 000000000..17d95d428
--- /dev/null
+++ b/crates/request/assets/codex-host-bridge.txt
@@ -0,0 +1,139 @@
+# Codex Host Bridge
+
+You are running Codex through a host terminal coding runtime. The host provides specific tools to help you work efficiently.
+
+## CRITICAL: Tool Usage
+
+<critical_rule priority="0">
+apply_patch/applyPatch are Codex names, but host tool names vary by version.
+- Inspect the actual tool list before editing.
+- If `edit` exists: use `edit` for precise in-place string replacements and hashline edits.
+- If `edit` is absent and `apply_patch` exists: use `apply_patch` for those precise/hashline edits in this plugin.
+- For diff-style or multi-line structural edits: use `patch` if available, otherwise use `apply_patch`.
+- In this plugin, `edit` / `apply_patch` also support hashline refs (`lineRef`, `endLineRef`, `operation`, `content`)
+</critical_rule>
+
+<critical_rule priority="0">
+UPDATE_PLAN DOES NOT EXIST -> USE "todowrite" INSTEAD
+- NEVER use: update_plan, updatePlan, read_plan, readPlan
+- ALWAYS use: todowrite for task/plan updates, todoread to read plans
+- Before plan operations: Verify you're using "todowrite", NOT "update_plan"
+</critical_rule>
+
+## Available Host Tools
+
+**File Operations:**
+- `write`  - Create new files
+  - Overwriting existing files requires a prior Read in this session; default to ASCII unless the file already uses Unicode.
+- `edit`   - Modify existing files with string replacement (version-dependent)
+  - Requires a prior Read in this session; preserve exact indentation; ensure `oldString` uniquely matches or use `replaceAll`; edit fails if ambiguous or missing.
+  - Never pass unresolved template placeholders in `oldString` (e.g. `${TARGET_SNIPPET}`); `oldString` must be literal text copied from the current file.
+  - For complex multi-line changes: break into multiple sequential edit calls, each with unique oldString context.
+- `apply_patch` - May be the edit/patch tool name in newer host builds (version-dependent)
+  - In this plugin, `apply_patch` also accepts hashline edit args (`path`, `lineRef`, `endLineRef`, `operation`, `content`) when `edit` is not available.
+- `hashline_read` - Read file with hashline refs (`L<line>#<hash>`) for deterministic edits
+- `patch`  - Apply diff-style patches for multi-line updates (version-dependent)
+- `read`   - Read file contents
+
+Note: Tool naming is version-dependent. If `edit` is unavailable but `apply_patch` exists, use `apply_patch`.
+
+When available, prefer hashline workflow for reliability:
+1. Call `hashline_read` for target file and capture refs.
+2. Call `edit` or `apply_patch` with `lineRef` (and optional `endLineRef`) plus `operation` and `content`.
+3. Use legacy `oldString` / `newString` only when hashline refs are unavailable, and only with literal file text (no template placeholders).
+
+**Search/Discovery:**
+- `grep`   - Search file contents (tool, not bash grep); use `include` to filter patterns; set `path` only when not searching workspace root; for cross-file match counts use bash with `rg`.
+- `glob`   - Find files by pattern; defaults to workspace cwd unless `path` is set.
+- `list`   - List directories (requires absolute paths)
+
+**Execution:**
+- `bash`   - Run shell commands
+  - No workdir parameter; do not include it in tool calls.
+  - Always include a short description for the command.
+  - Do not use cd; use absolute paths in commands.
+  - Quote paths containing spaces with double quotes.
+  - Chain multiple commands with ';' or '&&'; avoid newlines.
+  - Use Grep/Glob tools for searches; only use bash with `rg` when you need counts or advanced features.
+  - Do not use `ls`/`cat` in bash; use `list`/`read` tools instead.
+  - For deletions (rm), verify by listing parent dir with `list`.
+
+**Network:**
+- `webfetch` - Fetch web content
+  - Use fully-formed URLs (http/https; http auto-upgrades to https).
+  - Always set `format` to one of: text | markdown | html; prefer markdown unless otherwise required.
+  - Read-only; short cache window.
+
+**Task Management:**
+- `todowrite` - Manage tasks/plans (REPLACES update_plan)
+- `todoread`  - Read current plan
+
+## Substitution Rules
+
+Base instruction says:    You MUST use instead:
+apply_patch           ->   patch (preferred if available), otherwise edit/apply_patch based on actual tool list
+update_plan           ->   todowrite
+read_plan             ->   todoread
+
+**Path Usage:** Use per-tool conventions to avoid conflicts:
+- Tool calls: `read`, `edit`, `write`, `list` require absolute paths.
+- Searches: `grep`/`glob` default to the workspace cwd; prefer relative include patterns; set `path` only when a different root is needed.
+- Presentation: In assistant messages, show workspace-relative paths; use absolute paths only inside tool calls.
+- Tool schema overrides general path preferences-do not convert required absolute paths to relative.
+
+## Verification Checklist
+
+Before file/plan modifications:
+1. Am I using the actual available edit tool name (`edit`, `patch`, or `apply_patch`)?
+2. Am I using "todowrite" NOT "update_plan"?
+3. Is this tool in the approved list above?
+4. Am I following each tool's path requirements?
+
+If ANY answer is NO -> STOP and correct before proceeding.
+
+## Host Working Style
+
+**Communication:**
+- Send brief preambles (8-12 words) before tool calls, building on prior context
+- Provide progress updates during longer tasks
+
+**Execution:**
+- Keep working autonomously until query is fully resolved before yielding
+- Don't return to user with partial solutions
+
+**Code Approach:**
+- New projects: Be ambitious and creative
+- Existing codebases: Surgical precision - modify only what's requested unless explicitly instructed to do otherwise
+
+**Testing:**
+- If tests exist: Start specific to your changes, then broader validation
+
+## Advanced Tools
+
+**Task Tool (Sub-Agents):**
+- Use the Task tool (functions.task) to launch sub-agents
+- Check the Task tool description for current agent types and their capabilities
+- Useful for complex analysis, specialized workflows, or tasks requiring isolated context
+- The agent list is dynamically generated - refer to tool schema for available agents
+
+**Parallelization:**
+- When multiple independent tool calls are needed, use multi_tool_use.parallel to run them concurrently.
+- Reserve sequential calls for ordered or data-dependent steps.
+
+**MCP Tools:**
+- Model Context Protocol servers provide additional capabilities
+- MCP tools are prefixed: `mcp__<server-name>__<tool-name>`
+- Check your available tools for MCP integrations
+- Use when the tool's functionality matches your task needs
+
+## What Remains from Codex
+ 
+Sandbox policies, approval mechanisms, final answer formatting, git commit protocols, and file reference formats all follow Codex instructions. In approval policy "never", never request escalations.
+
+## Approvals & Safety
+- Assume workspace-write filesystem, network enabled, approval on-failure unless explicitly stated otherwise.
+- When a command fails due to sandboxing or permissions, retry with escalated permissions if allowed by policy, including a one-line justification.
+- Treat destructive commands (e.g., `rm`, `git reset --hard`) as requiring explicit user request or approval.
+- Never run `git reset --hard`, `git checkout --`, or force deletes unless the user explicitly asked for that exact action.
+- `request_user_input` is Plan-mode only; do not call it in Default mode.
+- When uncertain, prefer non-destructive verification first (e.g., confirm file existence with `list`, then delete with `bash`).
\ No newline at end of file
diff --git a/crates/request/assets/codex-instructions.md b/crates/request/assets/codex-instructions.md
new file mode 100644
index 000000000..88a569fa7
--- /dev/null
+++ b/crates/request/assets/codex-instructions.md
@@ -0,0 +1,68 @@
+You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.
+
+## General
+
+- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
+
+## Editing constraints
+
+- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
+- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
+- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
+- You may be in a dirty git worktree.
+    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
+    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
+    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
+    * If the changes are in unrelated files, just ignore them and don't revert them.
+- Do not amend a commit unless explicitly requested to do so.
+- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
+- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.
+
+## Plan tool
+
+When using the planning tool:
+- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
+- Do not make single-step plans.
+- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
+
+## Special user requests
+
+- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.
+- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.
+
+## Presenting your work and final message
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+- Default: be very concise; friendly coding teammate tone.
+- Ask only when needed; suggest ideas; mirror the user's style.
+- For substantial work, summarize clearly; follow final‑answer formatting.
+- Skip heavy formatting for simple confirmations.
+- Don't dump large files you've written; reference paths only.
+- No "save/copy this file" - User is on the same machine.
+- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
+- For code changes:
+  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
+  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
+  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
+- The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result.
+
+### Final answer structure and style guidelines
+
+- Plain text; CLI handles styling. Use structure only when it helps scanability.
+- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
+- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
+- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
+- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
+- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
+- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
+- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
+- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
+- File References: When referencing files in your response, make sure to include the relevant start line and always follow the below rules:
+  * Use inline code to make file paths clickable.
+  * Each reference should have a stand alone path. Even if it's the same file.
+  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
+  * Line/column (1‑based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
+  * Do not use URIs like file://, vscode://, or https://.
+  * Do not provide range of lines
+  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5
diff --git a/crates/request/assets/tool-remap-message.txt b/crates/request/assets/tool-remap-message.txt
new file mode 100644
index 000000000..1b86f301a
--- /dev/null
+++ b/crates/request/assets/tool-remap-message.txt
@@ -0,0 +1,80 @@
+<user_instructions priority="0">
+<environment_override priority="0">
+YOU ARE IN A DIFFERENT ENVIRONMENT. These instructions override ALL previous tool references.
+</environment_override>
+
+<tool_replacements priority="0">
+<critical_rule priority="0">
+apply_patch/applyPatch are Codex names, but host tool names vary by version.
+- Inspect the actual tool list before editing.
+- If edit exists: use edit for precise in-place string replacements and hashline edits.
+- If edit is absent and apply_patch exists: use apply_patch for those precise/hashline edits in this plugin.
+- For diff-style or multi-line structural edits: use patch if available, otherwise use apply_patch.
+- In this plugin, edit/apply_patch support hashline refs (lineRef, endLineRef, operation, content)
+</critical_rule>
+
+<critical_rule priority="0">
+UPDATE_PLAN DOES NOT EXIST -> USE "todowrite" INSTEAD
+- NEVER use: update_plan, updatePlan
+- ALWAYS use: todowrite for ALL task/plan operations
+- Use todoread to read current plan
+- Before plan operations: Verify you're using "todowrite", NOT "update_plan"
+</critical_rule>
+</tool_replacements>
+
+<available_tools priority="0">
+File Operations:
+  - write  - Create new files (if available)
+  - edit   - Modify existing files with string replacement (version-dependent)
+  - oldString must be literal text from the current file; never pass unresolved placeholders like ${TARGET_SNIPPET}
+  - apply_patch - May be the edit/patch tool name in newer host builds (version-dependent)
+  - hashline_read - Read lines with hashline refs (L<line>#<hash>) for deterministic edits
+  - patch  - Apply diff patches (version-dependent)
+  - read   - Read file contents
+
+Search/Discovery:
+  - grep   - Search file contents
+  - glob   - Find files by pattern
+  - list   - List directories (if available)
+
+Execution:
+  - bash   - Run shell commands
+
+Network:
+  - webfetch - Fetch web content
+
+Task Management:
+  - todowrite - Manage tasks/plans (REPLACES update_plan)
+  - todoread  - Read current plan
+</available_tools>
+
+<substitution_rules priority="0">
+Base instruction says:    You MUST use instead:
+apply_patch           ->   patch (preferred if available), otherwise edit/apply_patch based on actual tool list
+update_plan           ->   todowrite
+read_plan             ->   todoread
+absolute paths        ->   relative paths
+</substitution_rules>
+
+<verification_checklist priority="0">
+Before file/plan modifications:
+1. Am I using the actual available edit tool name (edit, patch, or apply_patch)?
+2. Am I using "todowrite" NOT "update_plan"?
+3. Is this tool in the approved list above?
+4. Am I using relative paths?
+
+If ANY answer is NO -> STOP and correct before proceeding.
+</verification_checklist>
+
+<hashline_workflow priority="0">
+When hashline_read is available:
+1. call hashline_read on the file
+2. edit/apply_patch using lineRef/endLineRef + operation + content
+3. use oldString/newString only as fallback, and only with literal file text (no template placeholders)
+</hashline_workflow>
+
+<safety_rules priority="0">
+- Never run destructive git commands (`git reset --hard`, `git checkout --`) unless explicitly requested by the user.
+- Never call `request_user_input` unless collaboration mode is explicitly Plan mode.
+</safety_rules>
+</user_instructions>
\ No newline at end of file
diff --git a/crates/request/src/attempt_budget.rs b/crates/request/src/attempt_budget.rs
new file mode 100644
index 000000000..d078e284f
--- /dev/null
+++ b/crates/request/src/attempt_budget.rs
@@ -0,0 +1,137 @@
+//! Port of `lib/request/request-attempt-budget.ts` — the finite per-request
+//! outbound attempt budget and the stream-failover candidate order
+//! (spec 06 §15).
+
+const MAX_TOTAL_OUTBOUND_REQUEST_ATTEMPTS: u32 = 6;
+const MAX_STREAM_FAILOVERS: u32 = 1;
+const MAX_STREAM_FAILOVER_CANDIDATES: usize = 2;
+
+/// TS `capStreamFailoverMax(value)` — clamp configured stream failover
+/// retries to the conservative runtime cap. **CLAMPS TO 1** (never more than
+/// a single failover). Non-finite input coerces to 0.
+pub fn cap_stream_failover_max(value: f64) -> u32 {
+    let floored = if value.is_finite() { value.floor() } else { 0.0 };
+    floored.clamp(0.0, MAX_STREAM_FAILOVERS as f64) as u32
+}
+
+/// Params for [`compute_outbound_request_attempt_budget`]. Values are `f64`
+/// because the TS callers feed raw config numbers (possibly NaN/Infinity);
+/// each is sanitized exactly like the TS.
+#[derive(Clone, Copy, Debug)]
+pub struct OutboundRequestAttemptBudgetParams {
+    pub account_count: f64,
+    pub max_same_account_retries: f64,
+    pub empty_response_max_retries: f64,
+    pub stream_failover_max: f64,
+}
+
+/// `Math.max(lo, Math.floor(Number.isFinite(v) ? v : dflt))`.
+fn sanitize(value: f64, default: f64, lo: f64) -> f64 {
+    let v = if value.is_finite() { value } else { default };
+    v.floor().max(lo)
+}
+
+/// TS `computeOutboundRequestAttemptBudget(params)` — bounds all outbound
+/// Responses API fetches across account rotation, same-account retries,
+/// empty-response retries, and stream failover. Result is in `1..=6`.
+pub fn compute_outbound_request_attempt_budget(
+    params: OutboundRequestAttemptBudgetParams,
+) -> u32 {
+    let account_count = sanitize(params.account_count, 1.0, 1.0);
+    let max_same_account_retries = sanitize(params.max_same_account_retries, 0.0, 0.0);
+    let empty_response_max_retries = sanitize(params.empty_response_max_retries, 0.0, 0.0);
+    let stream_failover_max = cap_stream_failover_max(params.stream_failover_max) as f64;
+
+    let total = account_count
+        + max_same_account_retries
+        + empty_response_max_retries
+        + stream_failover_max;
+    total
+        .min(MAX_TOTAL_OUTBOUND_REQUEST_ATTEMPTS as f64)
+        .max(1.0) as u32
+}
+
+/// TS `buildStreamFailoverCandidateOrder(primaryIndex, accountIndices)` —
+/// the primary first plus at most ONE alternate (2 candidates total),
+/// skipping duplicates. (The TS `Number.isFinite` filter is statically
+/// guaranteed by `usize`.)
+pub fn build_stream_failover_candidate_order(
+    primary_index: usize,
+    account_indices: &[usize],
+) -> Vec<usize> {
+    let mut order = vec![primary_index];
+    for &index in account_indices {
+        if index == primary_index || order.contains(&index) {
+            continue;
+        }
+        order.push(index);
+        if order.len() >= MAX_STREAM_FAILOVER_CANDIDATES {
+            break;
+        }
+    }
+    order
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn caps_stream_failover_to_a_single_retry() {
+        assert_eq!(cap_stream_failover_max(0.0), 0);
+        assert_eq!(cap_stream_failover_max(1.0), 1);
+        assert_eq!(cap_stream_failover_max(3.0), 1);
+        assert_eq!(cap_stream_failover_max(f64::NAN), 0);
+        assert_eq!(cap_stream_failover_max(-2.0), 0);
+        assert_eq!(cap_stream_failover_max(f64::INFINITY), 0);
+    }
+
+    #[test]
+    fn caps_outbound_request_budgets_for_large_account_pools() {
+        assert_eq!(
+            compute_outbound_request_attempt_budget(OutboundRequestAttemptBudgetParams {
+                account_count: 12.0,
+                max_same_account_retries: 2.0,
+                empty_response_max_retries: 2.0,
+                stream_failover_max: 3.0,
+            }),
+            6
+        );
+    }
+
+    #[test]
+    fn sanitizes_non_finite_retry_inputs_to_deterministic_defaults() {
+        assert_eq!(
+            compute_outbound_request_attempt_budget(OutboundRequestAttemptBudgetParams {
+                account_count: f64::NAN,
+                max_same_account_retries: f64::INFINITY,
+                empty_response_max_retries: f64::NEG_INFINITY,
+                stream_failover_max: f64::NAN,
+            }),
+            1
+        );
+    }
+
+    #[test]
+    fn small_pools_get_small_budgets() {
+        assert_eq!(
+            compute_outbound_request_attempt_budget(OutboundRequestAttemptBudgetParams {
+                account_count: 1.0,
+                max_same_account_retries: 1.0,
+                empty_response_max_retries: 1.0,
+                stream_failover_max: 1.0,
+            }),
+            4
+        );
+    }
+
+    #[test]
+    fn keeps_primary_plus_at_most_one_alternate() {
+        assert_eq!(
+            build_stream_failover_candidate_order(2, &[2, 5, 2, 7, 9]),
+            vec![2, 5]
+        );
+        assert_eq!(build_stream_failover_candidate_order(0, &[]), vec![0]);
+        assert_eq!(build_stream_failover_candidate_order(1, &[1, 1]), vec![1]);
+    }
+}
diff --git a/crates/request/src/context_overflow.rs b/crates/request/src/context_overflow.rs
new file mode 100644
index 000000000..7afb54eae
--- /dev/null
+++ b/crates/request/src/context_overflow.rs
@@ -0,0 +1,312 @@
+//! Port of `lib/context-overflow.ts` — context overflow handler
+//! (ARCHITECTURE §6.10: 400 prompt-too-long → synthetic 200 SSE).
+//!
+//! Handles "Prompt too long" / context length exceeded errors by returning a
+//! synthetic SSE response that advises the user to use /compact or /clear.
+//! This prevents the host session from getting locked on 400 errors.
+//!
+//! The synthetic stream speaks the OpenAI **Responses API** SSE dialect
+//! (`response.*` events) — the dialect the Codex CLI client and this crate's
+//! own `convert_sse_to_json` parser speak (recovery-01: the old Anthropic
+//! Messages envelope was unparseable, so the notice never reached the user).
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use http::HeaderMap;
+use http::header::HeaderValue;
+use serde_json::Value;
+
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::log_debug;
+use cma_core::utils::now_ms;
+
+use crate::response_handler::StreamResponse;
+
+/// Error patterns that indicate context overflow (TS
+/// `CONTEXT_OVERFLOW_PATTERNS` — frozen, matched case-insensitively).
+const CONTEXT_OVERFLOW_PATTERNS: [&str; 7] = [
+    "prompt is too long",
+    "prompt_too_long",
+    "context length exceeded",
+    "context_length_exceeded",
+    "maximum context length",
+    "token limit exceeded",
+    "too many tokens",
+];
+
+/// Check if an error body indicates context overflow (TS
+/// `isContextOverflowError`). Only 400 responses with a non-empty body match.
+pub fn is_context_overflow_error(status: u16, body_text: &str) -> bool {
+    if status != 400 {
+        return false;
+    }
+    if body_text.is_empty() {
+        return false;
+    }
+    let lower_body = body_text.to_lowercase();
+    CONTEXT_OVERFLOW_PATTERNS
+        .iter()
+        .any(|pattern| lower_body.contains(pattern))
+}
+
+/// The message shown to users when context overflow occurs (frozen text — TS
+/// `CONTEXT_OVERFLOW_MESSAGE`).
+const CONTEXT_OVERFLOW_MESSAGE: &str = "[Plugin Notice] Context is too long for this model.\n\nPlease use one of these commands to reduce context size:\n\n\u{2022} **/compact** - Compress conversation history (recommended)\n\u{2022} **/clear** - Start fresh with empty context\n\u{2022} **/undo** - Remove recent messages\n\nThen retry your request.\n\nAlternatively, you can switch to a model with a larger context window.";
+
+/// Monotonic tie-breaker mixed into the synthetic id suffix (the TS
+/// `Math.random().toString(36).slice(2, 8)` analogue — 6 base-36 chars).
+static SYNTHETIC_ID_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+fn random_base36_suffix() -> String {
+    const DIGITS: &[u8; 36] = b"0123456789abcdefghijklmnopqrstuvwxyz";
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.subsec_nanos() as u64)
+        .unwrap_or(0);
+    let counter = SYNTHETIC_ID_COUNTER.fetch_add(1, Ordering::Relaxed);
+    // Cheap splitmix-style scramble so consecutive calls do not share a prefix.
+    let mut x = nanos
+        .wrapping_mul(0x9E37_79B9_7F4A_7C15)
+        .wrapping_add(counter.wrapping_mul(0xBF58_476D_1CE4_E5B9));
+    x ^= x >> 31;
+    let mut out = String::with_capacity(6);
+    for _ in 0..6 {
+        out.push(DIGITS[(x % 36) as usize] as char);
+        x /= 36;
+    }
+    out
+}
+
+fn push_event(events: &mut String, event_type: &str, payload: &Value) {
+    // TS: `event: ${type}\ndata: ${JSON.stringify({ type, ...payload })}\n\n`
+    // with `type` serialized FIRST. Callers build the payload with `type` as
+    // the first key so serde's preserve_order emits identical bytes.
+    events.push_str("event: ");
+    events.push_str(event_type);
+    events.push_str("\ndata: ");
+    events.push_str(&stringify_compact(payload));
+    events.push_str("\n\n");
+}
+
+/// Creates a synthetic SSE response for context overflow errors (TS
+/// `createContextOverflowResponse`). Returns 200 OK so the host session does
+/// not lock on the 400.
+pub fn create_context_overflow_response(model: Option<&str>) -> StreamResponse {
+    let model = model.unwrap_or("unknown");
+    let now = now_ms();
+    let message_id = format!("msg_synthetic_overflow_{now}_{}", random_base36_suffix());
+    let response_id = format!("resp_synthetic_overflow_{now}_{}", random_base36_suffix());
+
+    let mut events = String::new();
+
+    // response.created
+    push_event(
+        &mut events,
+        "response.created",
+        &serde_json::json!({
+            "type": "response.created",
+            "response": {
+                "id": response_id,
+                "object": "response",
+                "model": model,
+                "status": "in_progress"
+            }
+        }),
+    );
+
+    // output item (assistant message) added
+    push_event(
+        &mut events,
+        "response.output_item.added",
+        &serde_json::json!({
+            "type": "response.output_item.added",
+            "output_index": 0,
+            "item": {
+                "id": message_id,
+                "type": "message",
+                "role": "assistant",
+                "content": []
+            }
+        }),
+    );
+
+    // streamed text + its terminal "done" carrying the final canonical text
+    push_event(
+        &mut events,
+        "response.output_text.delta",
+        &serde_json::json!({
+            "type": "response.output_text.delta",
+            "output_index": 0,
+            "content_index": 0,
+            "delta": CONTEXT_OVERFLOW_MESSAGE
+        }),
+    );
+    push_event(
+        &mut events,
+        "response.output_text.done",
+        &serde_json::json!({
+            "type": "response.output_text.done",
+            "output_index": 0,
+            "content_index": 0,
+            "text": CONTEXT_OVERFLOW_MESSAGE
+        }),
+    );
+
+    // terminal response.completed with the full output array
+    push_event(
+        &mut events,
+        "response.completed",
+        &serde_json::json!({
+            "type": "response.completed",
+            "response": {
+                "id": response_id,
+                "object": "response",
+                "model": model,
+                "status": "completed",
+                "output": [
+                    {
+                        "id": message_id,
+                        "type": "message",
+                        "role": "assistant",
+                        "content": [{ "type": "output_text", "text": CONTEXT_OVERFLOW_MESSAGE }]
+                    }
+                ],
+                "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 }
+            }
+        }),
+    );
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        http::header::CONTENT_TYPE,
+        HeaderValue::from_static("text/event-stream"),
+    );
+    headers.insert(
+        http::HeaderName::from_static("x-codex-plugin-synthetic"),
+        HeaderValue::from_static("true"),
+    );
+    headers.insert(
+        http::HeaderName::from_static("x-codex-plugin-error-type"),
+        HeaderValue::from_static("context_overflow"),
+    );
+
+    // TS `new Response(..., { status: 200 })` leaves statusText empty.
+    StreamResponse::from_text(200, "", headers, events)
+}
+
+/// Result of [`handle_context_overflow`].
+///
+/// The TS version clones the `Response` before reading so the caller keeps a
+/// readable original on the `handled: false` path. Rust bodies are one-shot
+/// streams, so the non-handled variant returns the original response with its
+/// body re-buffered from the bytes read during inspection (the "clone before
+/// return" contract).
+#[derive(Debug)]
+pub enum ContextOverflowOutcome {
+    /// Overflow detected: `response` is the synthetic 200 SSE notice.
+    Handled { response: StreamResponse },
+    /// Not an overflow: `response` is the original response (body preserved).
+    NotHandled { response: StreamResponse },
+}
+
+impl ContextOverflowOutcome {
+    /// TS `result.handled`.
+    pub fn handled(&self) -> bool {
+        matches!(self, ContextOverflowOutcome::Handled { .. })
+    }
+
+    /// Unwrap to the response either way (both variants carry one).
+    pub fn into_response(self) -> StreamResponse {
+        match self {
+            ContextOverflowOutcome::Handled { response }
+            | ContextOverflowOutcome::NotHandled { response } => response,
+        }
+    }
+}
+
+/// Check a response for context overflow and return a synthetic response if
+/// needed (TS `handleContextOverflow`).
+///
+/// Read errors are swallowed (TS `catch {}`): the outcome degrades to
+/// `NotHandled` with whatever bytes were collected before the failure.
+pub async fn handle_context_overflow(
+    mut response: StreamResponse,
+    model: Option<&str>,
+) -> ContextOverflowOutcome {
+    if response.status != 400 {
+        return ContextOverflowOutcome::NotHandled { response };
+    }
+
+    let Some(mut body) = response.body.take() else {
+        // No body: nothing to match on (TS reads "" and finds no pattern).
+        return ContextOverflowOutcome::NotHandled { response };
+    };
+
+    // Buffer the body so it can be handed back on the NotHandled path.
+    let mut collected: Vec<u8> = Vec::new();
+    let mut read_failed = false;
+    {
+        use futures::StreamExt;
+        while let Some(item) = body.next().await {
+            match item {
+                Ok(chunk) => collected.extend_from_slice(&chunk),
+                Err(_) => {
+                    // Ignore read errors (TS `catch { /* Ignore */ }`).
+                    read_failed = true;
+                    break;
+                }
+            }
+        }
+    }
+
+    if !read_failed {
+        let body_text = String::from_utf8_lossy(&collected);
+        if is_context_overflow_error(response.status, &body_text) {
+            log_debug("Context overflow detected, returning synthetic response", None);
+            return ContextOverflowOutcome::Handled {
+                response: create_context_overflow_response(model),
+            };
+        }
+    }
+
+    response.body = Some(crate::response_handler::body_stream_from_bytes(
+        bytes::Bytes::from(collected),
+    ));
+    ContextOverflowOutcome::NotHandled { response }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn overflow_message_is_frozen() {
+        assert!(CONTEXT_OVERFLOW_MESSAGE.starts_with("[Plugin Notice] Context is too long"));
+        assert!(CONTEXT_OVERFLOW_MESSAGE.contains("\u{2022} **/compact** - Compress conversation history (recommended)"));
+        assert!(CONTEXT_OVERFLOW_MESSAGE.ends_with("switch to a model with a larger context window."));
+    }
+
+    #[test]
+    fn random_base36_suffix_shape() {
+        let a = random_base36_suffix();
+        let b = random_base36_suffix();
+        assert_eq!(a.len(), 6);
+        assert!(a.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit()));
+        // Consecutive calls must differ (counter mixing).
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn push_event_serializes_type_first() {
+        let mut events = String::new();
+        push_event(
+            &mut events,
+            "response.created",
+            &serde_json::json!({ "type": "response.created", "response": { "id": "r" } }),
+        );
+        assert_eq!(
+            events,
+            "event: response.created\ndata: {\"type\":\"response.created\",\"response\":{\"id\":\"r\"}}\n\n"
+        );
+    }
+}
diff --git a/crates/request/src/error_classification.rs b/crates/request/src/error_classification.rs
new file mode 100644
index 000000000..a9c773c94
--- /dev/null
+++ b/crates/request/src/error_classification.rs
@@ -0,0 +1,953 @@
+//! Port of `lib/request/error-classification.ts` — upstream error
+//! classification.
+//!
+//! Behavior source: spec 06 §7 + the TS source (authority). `fetch_helpers`
+//! re-exports this module's public surface, mirroring the TS re-export
+//! contract.
+//!
+//! CRITICAL (spec 06 gotcha 5): [`canonicalize_model_name`] strips ONLY the
+//! `-(none|minimal|low|medium|high|xhigh)` suffixes. It deliberately does NOT
+//! strip `-max`/`-ultra` — unlike the transformer's `VARIANT_SUFFIX_PATTERN`.
+
+use std::sync::OnceLock;
+
+use cma_core::schemas::plugin_config::FallbackChain;
+use cma_core::utils::is_record;
+use regex::Regex;
+use serde_json::Value;
+
+use crate::fetch_helpers::SyntheticResponse;
+
+/// `@internal` in TS — exported for sibling request modules.
+pub const CHATGPT_CODEX_UNSUPPORTED_MODEL_CODE: &str = "model_not_supported_with_chatgpt_account";
+
+fn chatgpt_codex_unsupported_model_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r"(?i)model is not supported when using codex with a chatgpt account").unwrap()
+    })
+}
+
+fn normalized_unsupported_model_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r#"(?i)the model ['"]([^'"]+)['"] is not currently available for this chatgpt account"#)
+            .unwrap()
+    })
+}
+
+fn model_access_denied_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r#"(?i)the model [`'"]([^`'"]+)[`'"] does not exist or you do not have access to it"#)
+            .unwrap()
+    })
+}
+
+fn direct_unsupported_model_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(
+            r#"(?i)['"]([^'"]+)['"]\s+model is not supported when using codex with a chatgpt account"#,
+        )
+        .unwrap()
+    })
+}
+
+fn entitlement_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r"(?i)usage_not_included|not.included.in.your.plan|subscription.does.not.include")
+            .unwrap()
+    })
+}
+
+/// `DEFAULT_UNSUPPORTED_CODEX_FALLBACK_CHAIN` — exact table & order.
+pub static DEFAULT_UNSUPPORTED_CODEX_FALLBACK_CHAIN: &[(&str, &[&str])] = &[
+    ("gpt-5", &["gpt-5.5"]),
+    ("gpt-5-pro", &["gpt-5.5-pro"]),
+    ("gpt-5-chat-latest", &["gpt-5.5"]),
+    ("gpt-5.5", &["gpt-5.4"]),
+    ("gpt-5.5-pro", &["gpt-5.4"]),
+    ("gpt-5.5-2026-04-23", &["gpt-5.4"]),
+    ("gpt-5.5-pro-2026-04-23", &["gpt-5.4"]),
+    ("gpt-5.5-20260423", &["gpt-5.4"]),
+    ("gpt-5.5-pro-20260423", &["gpt-5.4"]),
+    ("gpt-5.3-codex-spark", &["gpt-5.3-codex", "gpt-5.2-codex"]),
+    ("gpt-5.3-codex", &["gpt-5.2-codex"]),
+    ("codex-max", &["gpt-5.3-codex"]),
+    ("gpt-5.1-codex-max", &["gpt-5.3-codex"]),
+    ("codex-mini-latest", &["gpt-5.3-codex"]),
+    ("gpt-5-codex-mini", &["gpt-5.3-codex"]),
+    ("gpt-5.1-codex-mini", &["gpt-5.3-codex"]),
+    ("gpt-5-codex", &["gpt-5.3-codex", "gpt-5.2-codex"]),
+    ("gpt-5.2-codex", &["gpt-5.3-codex"]),
+    ("gpt-5.1-codex", &["gpt-5.3-codex"]),
+];
+
+/// TS `UnsupportedCodexModelInfo`.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct UnsupportedCodexModelInfo {
+    pub is_unsupported: bool,
+    pub code: Option<String>,
+    pub message: Option<String>,
+    pub unsupported_model: Option<String>,
+}
+
+/// TS `ResolveUnsupportedCodexFallbackOptions`.
+#[derive(Debug, Clone)]
+pub struct ResolveUnsupportedCodexFallbackOptions<'a> {
+    pub requested_model: Option<&'a str>,
+    pub error_body: &'a Value,
+    pub attempted_models: &'a [String],
+    pub fallback_on_unsupported_codex_model: bool,
+    pub fallback_to_gpt52_on_unsupported_gpt53: bool,
+    /// Custom chain overrides (config getter output shape).
+    pub custom_chain: Option<&'a FallbackChain>,
+}
+
+/// TS `canonicalizeModelName` (private there, behavior-critical here).
+///
+/// trim → lowercase → strip provider prefix (`split("/").pop()`) → strip
+/// suffix `-(none|minimal|low|medium|high|xhigh)` ONLY (no `-max`/`-ultra`).
+/// Empty → `None`.
+pub(crate) fn canonicalize_model_name(model: Option<&str>) -> Option<String> {
+    let trimmed = model?.trim().to_lowercase();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let stripped = if trimmed.contains('/') {
+        trimmed.rsplit('/').next().unwrap_or(&trimmed)
+    } else {
+        &trimmed
+    };
+    for suffix in ["-none", "-minimal", "-low", "-medium", "-high", "-xhigh"] {
+        if let Some(base) = stripped.strip_suffix(suffix) {
+            return Some(base.to_string());
+        }
+    }
+    Some(stripped.to_string())
+}
+
+/// Ordered `Record<string, string[]>` analogue used by chain normalization.
+fn chain_get<'a>(chain: &'a [(String, Vec<String>)], key: &str) -> Option<&'a [String]> {
+    chain
+        .iter()
+        .find(|(k, _)| k == key)
+        .map(|(_, targets)| targets.as_slice())
+}
+
+fn chain_set(chain: &mut Vec<(String, Vec<String>)>, key: String, values: Vec<String>) {
+    if let Some(entry) = chain.iter_mut().find(|(k, _)| *k == key) {
+        entry.1 = values;
+    } else {
+        chain.push((key, values));
+    }
+}
+
+fn normalize_fallback_chain(custom_chain: Option<&FallbackChain>) -> Vec<(String, Vec<String>)> {
+    let mut normalized: Vec<(String, Vec<String>)> = Vec::new();
+    for (key, values) in DEFAULT_UNSUPPORTED_CODEX_FALLBACK_CHAIN {
+        let Some(normalized_key) = canonicalize_model_name(Some(key)) else {
+            continue;
+        };
+        let normalized_values = values
+            .iter()
+            .filter_map(|value| canonicalize_model_name(Some(value)))
+            .collect();
+        chain_set(&mut normalized, normalized_key, normalized_values);
+    }
+
+    let Some(custom_chain) = custom_chain else {
+        return normalized;
+    };
+
+    for (key, values) in custom_chain.0.iter() {
+        let Some(normalized_key) = canonicalize_model_name(Some(key)) else {
+            continue;
+        };
+        let normalized_values: Vec<String> = values
+            .iter()
+            .filter_map(|value| canonicalize_model_name(Some(value)))
+            .collect();
+        if !normalized_values.is_empty() {
+            chain_set(&mut normalized, normalized_key, normalized_values);
+        }
+    }
+
+    normalized
+}
+
+/// TS `extractUnsupportedCodexModelFromText(bodyText)`.
+pub fn extract_unsupported_codex_model_from_text(body_text: &str) -> Option<String> {
+    if let Some(captures) = direct_unsupported_model_pattern().captures(body_text)
+        && let Some(model) = captures.get(1)
+    {
+        return canonicalize_model_name(Some(model.as_str()));
+    }
+    if let Some(captures) = normalized_unsupported_model_pattern().captures(body_text)
+        && let Some(model) = captures.get(1)
+    {
+        return canonicalize_model_name(Some(model.as_str()));
+    }
+    if let Some(captures) = model_access_denied_pattern().captures(body_text)
+        && let Some(model) = captures.get(1)
+    {
+        return canonicalize_model_name(Some(model.as_str()));
+    }
+    None
+}
+
+/// `@internal` in TS. Status must be 400 and the body non-empty, matching any
+/// of the three unsupported-model patterns.
+pub fn is_unsupported_codex_model_for_chatgpt(status: u16, body_text: &str) -> bool {
+    if status != cma_core::constants::HTTP_STATUS.bad_request {
+        return false;
+    }
+    if body_text.is_empty() {
+        return false;
+    }
+    chatgpt_codex_unsupported_model_pattern().is_match(body_text)
+        || normalized_unsupported_model_pattern().is_match(body_text)
+        || model_access_denied_pattern().is_match(body_text)
+}
+
+fn matches_any_unsupported_pattern(text: &str) -> bool {
+    chatgpt_codex_unsupported_model_pattern().is_match(text)
+        || normalized_unsupported_model_pattern().is_match(text)
+        || model_access_denied_pattern().is_match(text)
+}
+
+/// TS `getUnsupportedCodexModelInfo(errorBody)`.
+pub fn get_unsupported_codex_model_info(error_body: &Value) -> UnsupportedCodexModelInfo {
+    if !is_record(error_body) {
+        return UnsupportedCodexModelInfo::default();
+    }
+
+    let maybe_error = error_body.get("error");
+    let maybe_error_record = maybe_error.filter(|value| is_record(value));
+    let Some(maybe_error) = maybe_error_record else {
+        // Flat `{ "detail": "..." }` shape (Codex quota endpoint).
+        let Some(detail) = error_body.get("detail").and_then(Value::as_str) else {
+            return UnsupportedCodexModelInfo::default();
+        };
+        if !matches_any_unsupported_pattern(detail) {
+            return UnsupportedCodexModelInfo::default();
+        }
+        return UnsupportedCodexModelInfo {
+            is_unsupported: true,
+            code: None,
+            message: Some(detail.to_string()),
+            unsupported_model: extract_unsupported_codex_model_from_text(detail),
+        };
+    };
+
+    let code = maybe_error
+        .get("code")
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    let message = maybe_error
+        .get("message")
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    let unsupported_model_from_payload = maybe_error
+        .get("unsupported_model")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty());
+    let unsupported_model = match unsupported_model_from_payload {
+        Some(payload_model) => canonicalize_model_name(Some(payload_model)),
+        None => extract_unsupported_codex_model_from_text(message.as_deref().unwrap_or("")),
+    };
+    let is_unsupported = code.as_deref() == Some(CHATGPT_CODEX_UNSUPPORTED_MODEL_CODE)
+        || message
+            .as_deref()
+            .map(matches_any_unsupported_pattern)
+            .unwrap_or(false);
+
+    UnsupportedCodexModelInfo {
+        is_unsupported,
+        code,
+        message,
+        unsupported_model,
+    }
+}
+
+/// TS `resolveUnsupportedCodexFallbackModel(options)`.
+pub fn resolve_unsupported_codex_fallback_model(
+    options: &ResolveUnsupportedCodexFallbackOptions<'_>,
+) -> Option<String> {
+    if !options.fallback_on_unsupported_codex_model {
+        return None;
+    }
+
+    let unsupported = get_unsupported_codex_model_info(options.error_body);
+    if !unsupported.is_unsupported {
+        return None;
+    }
+
+    let requested_model = canonicalize_model_name(options.requested_model);
+    let current_model = requested_model.or(unsupported.unsupported_model)?;
+
+    let mut attempted: Vec<String> = Vec::new();
+    for model in options.attempted_models {
+        if let Some(normalized) = canonicalize_model_name(Some(model))
+            && !attempted.contains(&normalized)
+        {
+            attempted.push(normalized);
+        }
+    }
+
+    let chain = normalize_fallback_chain(options.custom_chain);
+    let targets = chain_get(&chain, &current_model)?;
+    if targets.is_empty() {
+        return None;
+    }
+
+    for target in targets {
+        if !options.fallback_to_gpt52_on_unsupported_gpt53
+            && current_model == "gpt-5.3-codex"
+            && target == "gpt-5.2-codex"
+        {
+            continue;
+        }
+        if *target == current_model {
+            continue;
+        }
+        if attempted.iter().any(|attempted| attempted == target) {
+            continue;
+        }
+        return Some(target.clone());
+    }
+
+    None
+}
+
+/// TS `shouldFallbackToGpt52OnUnsupportedGpt53(requestedModel, errorBody)` —
+/// true when the legacy `gpt-5.3-codex → gpt-5.2-codex` edge is available.
+pub fn should_fallback_to_gpt52_on_unsupported_gpt53(
+    requested_model: Option<&str>,
+    error_body: &Value,
+) -> bool {
+    if canonicalize_model_name(requested_model).as_deref() != Some("gpt-5.3-codex") {
+        return false;
+    }
+
+    resolve_unsupported_codex_fallback_model(&ResolveUnsupportedCodexFallbackOptions {
+        requested_model,
+        error_body,
+        attempted_models: &[],
+        fallback_on_unsupported_codex_model: true,
+        fallback_to_gpt52_on_unsupported_gpt53: true,
+        custom_chain: None,
+    })
+    .as_deref()
+        == Some("gpt-5.2-codex")
+}
+
+/// TS `isEntitlementError(code, bodyText)` — subscription doesn't include the
+/// feature ("usage_not_included"), which is NOT a temporary rate limit.
+pub fn is_entitlement_error(code: &str, body_text: &str) -> bool {
+    let haystack = format!("{code} {body_text}").to_lowercase();
+    entitlement_pattern().is_match(&haystack)
+}
+
+fn workspace_disabled_patterns() -> &'static [Regex; 6] {
+    static RES: OnceLock<[Regex; 6]> = OnceLock::new();
+    RES.get_or_init(|| {
+        [
+            Regex::new(r"(?i)workspace.*(?:disabled|expired|deactivated|terminated)").unwrap(),
+            Regex::new(
+                r"(?i)account\s+(?:has\s+been|is)\s+(?:disabled|expired|deactivated|terminated|closed)",
+            )
+            .unwrap(),
+            Regex::new(r"(?i)(?:workspace|org(?:anization)?).*no longer.*(?:active|available|valid)")
+                .unwrap(),
+            Regex::new(r"(?i)(?:workspace|org(?:anization)?).*has been.*(?:disabled|expired|closed)")
+                .unwrap(),
+            Regex::new(r"(?i)workspace.*(?:access|subscription).*expired").unwrap(),
+            Regex::new(r"(?i)org(?:anization)?.*(?:disabled|expired|inactive)").unwrap(),
+        ]
+    })
+}
+
+fn deactivated_workspace_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| Regex::new(r"(?i)\bdeactivated_workspace\b").unwrap())
+}
+
+const WORKSPACE_ERROR_CODES: &[&str] = &[
+    "workspace_disabled",
+    "workspace_expired",
+    "workspace_terminated",
+    "account_disabled",
+    "account_expired",
+    "organization_disabled",
+];
+
+fn split_code_tokens(normalized_code: &str) -> Vec<&str> {
+    normalized_code
+        .split(|c: char| !(c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_'))
+        .map(str::trim)
+        .filter(|token| !token.is_empty())
+        .collect()
+}
+
+/// TS `isWorkspaceDisabledError(status, code, bodyText)`.
+///
+/// `code` is `unknown` in TS (strings, numbers, null all occur) — pass any
+/// JSON value; only strings contribute a normalized code.
+pub fn is_workspace_disabled_error(status: u16, code: &Value, body_text: &str) -> bool {
+    let normalized_code = code
+        .as_str()
+        .map(|value| value.trim().to_lowercase())
+        .unwrap_or_default();
+
+    if status == 402 {
+        let tokens = split_code_tokens(&normalized_code);
+        return tokens.contains(&"deactivated_workspace")
+            || deactivated_workspace_pattern().is_match(body_text);
+    }
+
+    if status != 403 {
+        return false;
+    }
+
+    let haystack = format!("{normalized_code} {body_text}").to_lowercase();
+    let tokens = split_code_tokens(&normalized_code);
+
+    for pattern in workspace_disabled_patterns() {
+        if pattern.is_match(&haystack) {
+            return true;
+        }
+    }
+
+    if WORKSPACE_ERROR_CODES.contains(&normalized_code.as_str()) {
+        return true;
+    }
+
+    tokens
+        .iter()
+        .any(|token| WORKSPACE_ERROR_CODES.contains(token))
+}
+
+/// TS `createEntitlementErrorResponse(_bodyText)` — the bodyText argument is
+/// ignored; the payload is fixed (spec 06 §26 error contract).
+pub fn create_entitlement_error_response() -> SyntheticResponse {
+    let message = "This model is not included in your ChatGPT subscription. \
+Please check that your account or workspace has access to Codex models (Plus/Pro/Business/Enterprise). \
+If you recently subscribed or switched workspaces, try logging out and back in with `codex-multi-auth login`.";
+
+    let mut error = serde_json::Map::new();
+    error.insert("message".into(), Value::String(message.to_string()));
+    error.insert("type".into(), Value::String("entitlement_error".into()));
+    error.insert("code".into(), Value::String("usage_not_included".into()));
+    let mut payload = serde_json::Map::new();
+    payload.insert("error".into(), Value::Object(error));
+
+    let mut headers = http::HeaderMap::new();
+    headers.insert(
+        "content-type",
+        "application/json; charset=utf-8".parse().unwrap(),
+    );
+
+    SyntheticResponse {
+        status: 403,
+        status_text: "Forbidden".into(),
+        headers,
+        body: serde_json::to_string(&Value::Object(payload)).unwrap_or_default(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn resolve(
+        requested_model: Option<&str>,
+        error_body: &Value,
+        attempted: &[&str],
+        enabled: bool,
+        legacy_edge: bool,
+        custom_chain: Option<&FallbackChain>,
+    ) -> Option<String> {
+        let attempted: Vec<String> = attempted.iter().map(|s| s.to_string()).collect();
+        resolve_unsupported_codex_fallback_model(&ResolveUnsupportedCodexFallbackOptions {
+            requested_model,
+            error_body,
+            attempted_models: &attempted,
+            fallback_on_unsupported_codex_model: enabled,
+            fallback_to_gpt52_on_unsupported_gpt53: legacy_edge,
+            custom_chain,
+        })
+    }
+
+    #[test]
+    fn is_entitlement_error_matches_codes_and_body_phrases() {
+        assert!(is_entitlement_error("usage_not_included", ""));
+        assert!(is_entitlement_error("", "Usage not included in your plan"));
+        assert!(!is_entitlement_error("usage_limit_reached", ""));
+        assert!(!is_entitlement_error("rate_limit_exceeded", ""));
+        assert!(!is_entitlement_error("not_found", "Resource not found"));
+    }
+
+    #[test]
+    fn workspace_disabled_403_messages_and_codes() {
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "Your workspace has been disabled"
+        ));
+        assert!(is_workspace_disabled_error(403, &json!(""), "Workspace expired"));
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "Account has been deactivated"
+        ));
+        assert!(is_workspace_disabled_error(403, &json!("workspace_disabled"), ""));
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!("workspace_expired"),
+            "Some message"
+        ));
+        assert!(is_workspace_disabled_error(403, &json!("account_disabled"), ""));
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!("organization_disabled"),
+            ""
+        ));
+    }
+
+    #[test]
+    fn workspace_disabled_matches_wrapped_tokens_not_partial_text() {
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!("error.workspace_disabled"),
+            ""
+        ));
+        assert!(is_workspace_disabled_error(
+            403,
+            &json!("workspace_expired:error"),
+            ""
+        ));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!("error.usage_not_included"),
+            ""
+        ));
+    }
+
+    #[test]
+    fn workspace_disabled_402_deactivated_workspace_signals() {
+        assert!(is_workspace_disabled_error(402, &json!("deactivated_workspace"), ""));
+        assert!(is_workspace_disabled_error(
+            402,
+            &json!("error.deactivated_workspace"),
+            ""
+        ));
+        assert!(is_workspace_disabled_error(
+            402,
+            &json!(""),
+            r#"{"error":{"code":"deactivated_workspace"}}"#
+        ));
+    }
+
+    #[test]
+    fn workspace_disabled_rejects_unsupported_statuses() {
+        for status in [400u16, 401, 500] {
+            assert!(!is_workspace_disabled_error(
+                status,
+                &json!(""),
+                "Your workspace has been disabled"
+            ));
+        }
+        assert!(!is_workspace_disabled_error(400, &json!("workspace_disabled"), ""));
+        assert!(!is_workspace_disabled_error(402, &json!("payment_required"), ""));
+        assert!(!is_workspace_disabled_error(
+            402,
+            &json!(""),
+            "Your workspace has been disabled"
+        ));
+    }
+
+    #[test]
+    fn workspace_disabled_rejects_unrelated_403s() {
+        assert!(!is_workspace_disabled_error(403, &json!(""), "Permission denied"));
+        assert!(!is_workspace_disabled_error(403, &json!(""), "Not authorized"));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!("usage_not_included"),
+            "Not in your plan"
+        ));
+    }
+
+    #[test]
+    fn workspace_disabled_classifies_numeric_codes_via_body_text() {
+        assert!(is_workspace_disabled_error(403, &json!(402), "Workspace disabled"));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!(402),
+            "Billing failed for your subscription"
+        ));
+        assert!(!is_workspace_disabled_error(403, &json!(0), ""));
+    }
+
+    #[test]
+    fn workspace_disabled_rejects_billing_style_403s() {
+        assert!(!is_workspace_disabled_error(403, &json!("billing_failed"), ""));
+        assert!(!is_workspace_disabled_error(403, &json!("payment_required"), ""));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "Payment required to continue"
+        ));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "Billing failed for your plan"
+        ));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "Your billing account has expired"
+        ));
+        assert!(!is_workspace_disabled_error(
+            403,
+            &json!(""),
+            "service account terminated"
+        ));
+        assert!(!is_workspace_disabled_error(403, &json!(""), "team plan inactive"));
+    }
+
+    #[test]
+    fn entitlement_error_response_has_fixed_shape() {
+        let response = create_entitlement_error_response();
+        assert_eq!(response.status, 403);
+        assert_eq!(response.status_text, "Forbidden");
+        let json: Value = serde_json::from_str(&response.body).unwrap();
+        assert_eq!(json["error"]["type"], "entitlement_error");
+        assert_eq!(json["error"]["code"], "usage_not_included");
+        assert!(
+            json["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("ChatGPT subscription")
+        );
+    }
+
+    #[test]
+    fn canonicalize_strips_only_none_through_xhigh_suffixes() {
+        // Spec 06 gotcha 5: -max/-ultra are NOT effort suffixes here.
+        assert_eq!(
+            canonicalize_model_name(Some("org/GPT-5.3-Codex-High")).as_deref(),
+            Some("gpt-5.3-codex")
+        );
+        assert_eq!(
+            canonicalize_model_name(Some("gpt-5.1-codex-max")).as_deref(),
+            Some("gpt-5.1-codex-max")
+        );
+        assert_eq!(
+            canonicalize_model_name(Some("gpt-5.6-sol-ultra")).as_deref(),
+            Some("gpt-5.6-sol-ultra")
+        );
+        assert_eq!(canonicalize_model_name(Some("   ")), None);
+        assert_eq!(canonicalize_model_name(None), None);
+    }
+
+    #[test]
+    fn extracts_unsupported_model_from_all_wordings() {
+        assert_eq!(
+            extract_unsupported_codex_model_from_text(
+                "The 'gpt-5.3-codex-spark' model is not supported when using Codex with a ChatGPT account.",
+            )
+            .as_deref(),
+            Some("gpt-5.3-codex-spark")
+        );
+        assert_eq!(
+            extract_unsupported_codex_model_from_text(
+                "The model 'gpt-5.3-codex' is not currently available for this ChatGPT account when using Codex OAuth.",
+            )
+            .as_deref(),
+            Some("gpt-5.3-codex")
+        );
+        assert_eq!(
+            extract_unsupported_codex_model_from_text(
+                "The model `gpt-5.5` does not exist or you do not have access to it.",
+            )
+            .as_deref(),
+            Some("gpt-5.5")
+        );
+    }
+
+    #[test]
+    fn unsupported_info_from_normalized_error_payload() {
+        let info = get_unsupported_codex_model_info(&json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "The model 'gpt-5.3-codex-spark' is not currently available for this ChatGPT account when using Codex OAuth.",
+                "unsupported_model": "gpt-5.3-codex-spark",
+            }
+        }));
+        assert!(info.is_unsupported);
+        assert_eq!(info.unsupported_model.as_deref(), Some("gpt-5.3-codex-spark"));
+    }
+
+    #[test]
+    fn unsupported_info_from_normalized_wording_without_code() {
+        let info = get_unsupported_codex_model_info(&json!({
+            "error": {
+                "message": "The model 'gpt-5.3-codex' is not currently available for this chatgpt account.",
+            }
+        }));
+        assert!(info.is_unsupported);
+        assert_eq!(info.unsupported_model.as_deref(), Some("gpt-5.3-codex"));
+    }
+
+    #[test]
+    fn unsupported_info_from_flat_detail_branch() {
+        let info = get_unsupported_codex_model_info(&json!({
+            "detail": "The model 'gpt-5.3-codex' is not currently available for this chatgpt account.",
+        }));
+        assert!(info.is_unsupported);
+        assert_eq!(info.unsupported_model.as_deref(), Some("gpt-5.3-codex"));
+
+        let info = get_unsupported_codex_model_info(&json!({
+            "detail": "The 'gpt-5-codex' model is not supported when using Codex with a ChatGPT account.",
+        }));
+        assert!(info.is_unsupported);
+        assert!(info.message.as_deref().unwrap().contains("gpt-5-codex"));
+        assert_eq!(info.unsupported_model.as_deref(), Some("gpt-5-codex"));
+    }
+
+    #[test]
+    fn unsupported_info_detail_with_null_error_and_placeholder_model() {
+        let info = get_unsupported_codex_model_info(&json!({
+            "error": null,
+            "detail": "The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account.",
+        }));
+        assert!(info.is_unsupported);
+        assert_eq!(info.unsupported_model.as_deref(), Some("gpt-5.3-codex"));
+
+        let info = get_unsupported_codex_model_info(&json!({
+            "detail": "model is not supported when using Codex with a ChatGPT account",
+        }));
+        assert!(info.is_unsupported);
+        assert_eq!(info.unsupported_model, None);
+    }
+
+    #[test]
+    fn unsupported_info_ignores_malformed_payloads() {
+        assert!(!get_unsupported_codex_model_info(&Value::Null).is_unsupported);
+        assert!(
+            !get_unsupported_codex_model_info(&json!({ "error": "not-an-object" })).is_unsupported
+        );
+        let info = get_unsupported_codex_model_info(&json!({ "error": { "code": 123 } }));
+        assert_eq!(info.code, None);
+        assert_eq!(info.message, None);
+        assert!(!info.is_unsupported);
+        assert!(
+            !get_unsupported_codex_model_info(&json!({ "detail": "you are not authorized" }))
+                .is_unsupported
+        );
+        assert!(!get_unsupported_codex_model_info(&json!({ "detail": 42 })).is_unsupported);
+    }
+
+    #[test]
+    fn resolves_spark_fallback_chain_to_current_codex_first() {
+        let error_body = json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "The 'gpt-5.3-codex-spark' model is not supported when using Codex with a ChatGPT account.",
+            }
+        });
+        assert_eq!(
+            resolve(
+                Some("gpt-5.3-codex-spark"),
+                &error_body,
+                &["gpt-5.3-codex-spark"],
+                true,
+                true,
+                None,
+            )
+            .as_deref(),
+            Some("gpt-5.3-codex")
+        );
+
+        let error_body = json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account.",
+            }
+        });
+        assert_eq!(
+            resolve(
+                Some("gpt-5.3-codex"),
+                &error_body,
+                &["gpt-5.3-codex-spark", "gpt-5.3-codex", "gpt-5-codex"],
+                true,
+                true,
+                None,
+            )
+            .as_deref(),
+            Some("gpt-5.2-codex")
+        );
+    }
+
+    #[test]
+    fn respects_legacy_gpt52_toggle_when_disabled() {
+        let error_body = json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account.",
+            }
+        });
+        assert_eq!(
+            resolve(Some("gpt-5.3-codex"), &error_body, &["gpt-5.3-codex"], true, false, None),
+            None
+        );
+        assert_eq!(
+            resolve(
+                Some("gpt-5.3-codex"),
+                &error_body,
+                &["gpt-5.3-codex", "gpt-5-codex"],
+                true,
+                false,
+                None,
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn resolves_gpt55_fallback_to_gpt54() {
+        let unsupported = |model: &str| {
+            json!({
+                "error": {
+                    "code": "model_not_supported_with_chatgpt_account",
+                    "message": format!("The '{model}' model is not supported when using Codex with a ChatGPT account."),
+                }
+            })
+        };
+        assert_eq!(
+            resolve(Some("gpt-5.5"), &unsupported("gpt-5.5"), &["gpt-5.5"], true, true, None)
+                .as_deref(),
+            Some("gpt-5.4")
+        );
+        assert_eq!(
+            resolve(
+                Some("gpt-5.5-pro-2026-04-23"),
+                &unsupported("gpt-5.5-pro-2026-04-23"),
+                &["gpt-5.5-pro-2026-04-23"],
+                true,
+                true,
+                None,
+            )
+            .as_deref(),
+            Some("gpt-5.4")
+        );
+        let access_denied = json!({
+            "error": {
+                "message": "The model `gpt-5.5` does not exist or you do not have access to it.",
+            }
+        });
+        assert_eq!(
+            resolve(Some("gpt-5.5"), &access_denied, &["gpt-5.5"], true, true, None).as_deref(),
+            Some("gpt-5.4")
+        );
+    }
+
+    #[test]
+    fn resolves_stale_aliases_to_current_models() {
+        let unsupported = |model: &str| {
+            json!({
+                "error": {
+                    "code": "model_not_supported_with_chatgpt_account",
+                    "message": format!("The '{model}' model is not supported when using Codex with a ChatGPT account."),
+                }
+            })
+        };
+        assert_eq!(
+            resolve(Some("gpt-5"), &unsupported("gpt-5"), &["gpt-5"], true, true, None).as_deref(),
+            Some("gpt-5.5")
+        );
+        assert_eq!(
+            resolve(
+                Some("gpt-5.1-codex-mini"),
+                &unsupported("gpt-5.1-codex-mini"),
+                &["gpt-5.1-codex-mini"],
+                true,
+                true,
+                None,
+            )
+            .as_deref(),
+            Some("gpt-5.3-codex")
+        );
+    }
+
+    #[test]
+    fn resolves_custom_chains_with_canonicalization() {
+        let custom = FallbackChain(vec![
+            (String::new(), vec!["gpt-5-codex".into()]),
+            (
+                "gpt-5.3-codex".into(),
+                vec!["gpt-5.3-codex".into(), "gpt-5-codex-low".into()],
+            ),
+        ]);
+        let error_body = json!({
+            "error": {
+                "code": "model_not_supported_with_chatgpt_account",
+                "message": "not supported when using Codex with a ChatGPT account",
+            }
+        });
+        let attempted = ["", "   ", "gpt-5.3-codex"];
+        assert_eq!(
+            resolve(
+                Some("org/gpt-5.3-codex-high"),
+                &error_body,
+                &attempted,
+                true,
+                true,
+                Some(&custom),
+            )
+            .as_deref(),
+            Some("gpt-5-codex")
+        );
+    }
+
+    #[test]
+    fn returns_none_when_disabled_or_unresolvable() {
+        let unsupported_error = json!({
+            "error": { "code": "model_not_supported_with_chatgpt_account" }
+        });
+        assert_eq!(
+            resolve(Some("gpt-5.3-codex"), &unsupported_error, &[], false, true, None),
+            None
+        );
+        assert_eq!(resolve(None, &unsupported_error, &[], true, true, None), None);
+        assert_eq!(
+            resolve(Some("unknown-codex-model"), &unsupported_error, &[], true, true, None),
+            None
+        );
+    }
+
+    #[test]
+    fn flags_gpt52_fallback_only_for_current_codex_unsupported_errors() {
+        assert!(should_fallback_to_gpt52_on_unsupported_gpt53(
+            Some("gpt-5.3-codex"),
+            &json!({
+                "error": {
+                    "code": "model_not_supported_with_chatgpt_account",
+                    "message": "not supported when using Codex with a ChatGPT account",
+                }
+            }),
+        ));
+        assert!(!should_fallback_to_gpt52_on_unsupported_gpt53(
+            Some("gpt-5.2-codex"),
+            &json!({ "error": { "code": "model_not_supported_with_chatgpt_account" } }),
+        ));
+        assert!(!should_fallback_to_gpt52_on_unsupported_gpt53(
+            Some("gpt-5.3-codex"),
+            &json!({ "error": { "code": "usage_not_included" } }),
+        ));
+    }
+}
diff --git a/crates/request/src/failover_config.rs b/crates/request/src/failover_config.rs
new file mode 100644
index 000000000..b2f831796
--- /dev/null
+++ b/crates/request/src/failover_config.rs
@@ -0,0 +1,70 @@
+//! Port of `lib/request/failover-config.ts` — env parsing helpers for the
+//! failover mode + numeric tunables (spec 06 §12).
+//!
+//! Gotcha (spec 06 §27 item 12): [`parse_failover_mode`] defaults every
+//! unknown/absent string to `Balanced`, while the failure-policy INPUT default
+//! is `Aggressive`. Both are deliberate.
+
+use crate::failure_policy::FailoverMode;
+
+/// TS `parseFailoverMode(value)` — trim + lowercase; only `"aggressive"` and
+/// `"conservative"` pass through, everything else (including `None`) is
+/// `Balanced`.
+pub fn parse_failover_mode(value: Option<&str>) -> FailoverMode {
+    let normalized = value.unwrap_or("").trim().to_lowercase();
+    match normalized.as_str() {
+        "aggressive" => FailoverMode::Aggressive,
+        "conservative" => FailoverMode::Conservative,
+        _ => FailoverMode::Balanced,
+    }
+}
+
+/// TS `parseEnvInt(value)` — `Number.parseInt(v, 10)` semantics: skip leading
+/// whitespace, optional sign, then base-10 digits (trailing garbage ignored).
+/// No digits => `None`. Negative/zero values pass through as-is.
+pub fn parse_env_int(value: Option<&str>) -> Option<i64> {
+    let value = value?;
+    let trimmed = value.trim_start();
+    let (negative, rest) = match trimmed.strip_prefix('-') {
+        Some(rest) => (true, rest),
+        None => (false, trimmed.strip_prefix('+').unwrap_or(trimmed)),
+    };
+    let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
+    if digits.is_empty() {
+        return None;
+    }
+    // parseInt keeps consuming digits and JS numbers lose precision beyond
+    // 2^53; saturate rather than error for absurd inputs.
+    let magnitude = digits.parse::<i64>().unwrap_or(i64::MAX);
+    Some(if negative { -magnitude } else { magnitude })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_failover_mode_with_balanced_fallback() {
+        assert_eq!(parse_failover_mode(Some("aggressive")), FailoverMode::Aggressive);
+        assert_eq!(
+            parse_failover_mode(Some(" conservative ")),
+            FailoverMode::Conservative
+        );
+        assert_eq!(parse_failover_mode(Some("weird")), FailoverMode::Balanced);
+        assert_eq!(parse_failover_mode(None), FailoverMode::Balanced);
+        assert_eq!(parse_failover_mode(Some("AGGRESSIVE")), FailoverMode::Aggressive);
+    }
+
+    #[test]
+    fn parses_finite_integers_from_env_values() {
+        assert_eq!(parse_env_int(Some("42")), Some(42));
+        assert_eq!(parse_env_int(Some("08")), Some(8));
+        assert_eq!(parse_env_int(None), None);
+        assert_eq!(parse_env_int(Some("abc")), None);
+        // parseInt semantics: trailing garbage ignored, sign honored.
+        assert_eq!(parse_env_int(Some(" 42abc")), Some(42));
+        assert_eq!(parse_env_int(Some("-7")), Some(-7));
+        assert_eq!(parse_env_int(Some("+9")), Some(9));
+        assert_eq!(parse_env_int(Some("")), None);
+    }
+}
diff --git a/crates/request/src/failure_policy.rs b/crates/request/src/failure_policy.rs
new file mode 100644
index 000000000..508fa7aa4
--- /dev/null
+++ b/crates/request/src/failure_policy.rs
@@ -0,0 +1,496 @@
+//! Port of `lib/request/failure-policy.ts` — the per-failure-kind decision
+//! table consumed by the runtime rotation loop (spec 06 §11).
+//!
+//! Pure and concurrency-safe: no filesystem access, no logging, no token
+//! exposure. Gotcha (spec 06 §27 item 12): a missing `failover_mode` on the
+//! INPUT defaults to `Aggressive` here, whereas
+//! [`crate::failover_config::parse_failover_mode`] defaults unknown strings to
+//! `Balanced`. Both are deliberate.
+
+use cma_core::constants::ACCOUNT_LIMITS;
+use cma_core::schemas::account_storage::CooldownReason;
+
+/// TS `FailureKind`. The extra [`FailureKind::Unknown`] variant models the
+/// TS `switch` default arm (reachable there only via unsound casts, but its
+/// decision row is contractual and test-pinned).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum FailureKind {
+    AuthRefresh,
+    Network,
+    Server,
+    RateLimit,
+    EmptyResponse,
+    /// Defensive default row (TS `default:` arm).
+    Unknown,
+}
+
+/// TS `FailoverMode = "aggressive" | "balanced" | "conservative"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum FailoverMode {
+    Aggressive,
+    Balanced,
+    Conservative,
+}
+
+impl FailoverMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Aggressive => "aggressive",
+            Self::Balanced => "balanced",
+            Self::Conservative => "conservative",
+        }
+    }
+}
+
+/// TS `handoffStrategy: "soft" | "hard"`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum HandoffStrategy {
+    Soft,
+    Hard,
+}
+
+impl HandoffStrategy {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Soft => "soft",
+            Self::Hard => "hard",
+        }
+    }
+}
+
+/// TS `FailurePolicyInput`. Numeric hints are `f64` because the TS callers
+/// may pass arbitrary numbers; the policy floors/clamps exactly like the TS.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct FailurePolicyInput {
+    pub kind: Option<FailureKind>,
+    pub consecutive_auth_failures: Option<f64>,
+    pub max_auth_failures_before_removal: Option<f64>,
+    pub server_retry_after_ms: Option<f64>,
+    pub failover_mode: Option<FailoverMode>,
+}
+
+impl FailurePolicyInput {
+    pub fn for_kind(kind: FailureKind) -> Self {
+        Self {
+            kind: Some(kind),
+            ..Self::default()
+        }
+    }
+}
+
+/// TS `FailurePolicyDecision`.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct FailurePolicyDecision {
+    pub rotate_account: bool,
+    pub refund_token: bool,
+    pub record_failure: bool,
+    pub mark_rate_limited: bool,
+    pub remove_account: bool,
+    pub cooldown_ms: Option<i64>,
+    pub cooldown_reason: Option<CooldownReason>,
+    pub retry_same_account: bool,
+    pub retry_delay_ms: Option<i64>,
+    pub handoff_strategy: HandoffStrategy,
+}
+
+/// TS optional second argument to `evaluateFailurePolicy`.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct FailurePolicyOverrides {
+    pub network_cooldown_ms: Option<f64>,
+    pub server_cooldown_ms: Option<f64>,
+}
+
+const DEFAULT_NETWORK_COOLDOWN_MS: f64 = 6_000.0;
+const DEFAULT_SERVER_COOLDOWN_MS: f64 = 4_000.0;
+
+fn network_retry_delay_ms(mode: FailoverMode) -> i64 {
+    match mode {
+        FailoverMode::Aggressive => 0,
+        FailoverMode::Balanced => 250,
+        FailoverMode::Conservative => 900,
+    }
+}
+
+fn empty_response_retry_delay_ms(mode: FailoverMode) -> i64 {
+    match mode {
+        FailoverMode::Aggressive => 0,
+        FailoverMode::Balanced => 200,
+        FailoverMode::Conservative => 600,
+    }
+}
+
+/// TS `getFailoverMode` — input mode or `aggressive` when unset.
+fn get_failover_mode(input: &FailurePolicyInput) -> FailoverMode {
+    input.failover_mode.unwrap_or(FailoverMode::Aggressive)
+}
+
+/// `Math.max(lo, Math.floor(v ?? fallback))`.
+fn floored_at_least(value: Option<f64>, fallback: f64, lo: i64) -> i64 {
+    let candidate = value.unwrap_or(fallback);
+    let floored = if candidate.is_finite() {
+        candidate.floor() as i64
+    } else if candidate.is_infinite() && candidate > 0.0 {
+        i64::MAX
+    } else {
+        // NaN / -Infinity floor below any finite -> clamps to `lo`.
+        i64::MIN
+    };
+    floored.max(lo)
+}
+
+/// Port of TS `evaluateFailurePolicy(input, overrides?)`.
+pub fn evaluate_failure_policy(
+    input: &FailurePolicyInput,
+    overrides: Option<&FailurePolicyOverrides>,
+) -> FailurePolicyDecision {
+    let overrides = overrides.copied().unwrap_or_default();
+    match input.kind {
+        Some(FailureKind::AuthRefresh) => {
+            let failures = floored_at_least(input.consecutive_auth_failures, 0.0, 0);
+            let max_failures = floored_at_least(
+                input.max_auth_failures_before_removal,
+                ACCOUNT_LIMITS.max_auth_failures_before_removal as f64,
+                1,
+            );
+            FailurePolicyDecision {
+                rotate_account: true,
+                refund_token: false,
+                record_failure: false,
+                mark_rate_limited: false,
+                remove_account: failures >= max_failures,
+                cooldown_ms: Some(ACCOUNT_LIMITS.auth_failure_cooldown_ms),
+                cooldown_reason: Some(CooldownReason::AuthFailure),
+                retry_same_account: false,
+                retry_delay_ms: None,
+                handoff_strategy: HandoffStrategy::Hard,
+            }
+        }
+        Some(FailureKind::Network) => {
+            let mode = get_failover_mode(input);
+            let cooldown_ms = floored_at_least(
+                overrides.network_cooldown_ms,
+                DEFAULT_NETWORK_COOLDOWN_MS,
+                0,
+            );
+            let retry_delay_ms = network_retry_delay_ms(mode);
+            let retry_same_account = retry_delay_ms > 0;
+            FailurePolicyDecision {
+                rotate_account: !retry_same_account,
+                refund_token: true,
+                record_failure: true,
+                mark_rate_limited: false,
+                remove_account: false,
+                cooldown_ms: Some(cooldown_ms),
+                cooldown_reason: (cooldown_ms > 0).then_some(CooldownReason::NetworkError),
+                retry_same_account,
+                retry_delay_ms: retry_same_account.then_some(retry_delay_ms),
+                handoff_strategy: HandoffStrategy::Soft,
+            }
+        }
+        Some(FailureKind::Server) => {
+            let mode = get_failover_mode(input);
+            let retry_after_ms = floored_at_least(input.server_retry_after_ms, 0.0, 0);
+            let fallback_cooldown =
+                floored_at_least(overrides.server_cooldown_ms, DEFAULT_SERVER_COOLDOWN_MS, 0);
+            let cooldown_ms = if retry_after_ms > 0 {
+                retry_after_ms
+            } else {
+                fallback_cooldown
+            };
+            let retry_same_account = mode == FailoverMode::Conservative && retry_after_ms <= 0;
+            FailurePolicyDecision {
+                rotate_account: !retry_same_account,
+                refund_token: true,
+                record_failure: true,
+                mark_rate_limited: false,
+                remove_account: false,
+                cooldown_ms: Some(cooldown_ms),
+                cooldown_reason: (cooldown_ms > 0).then_some(CooldownReason::ServerError),
+                retry_same_account,
+                retry_delay_ms: retry_same_account.then_some(500),
+                handoff_strategy: HandoffStrategy::Hard,
+            }
+        }
+        Some(FailureKind::RateLimit) => FailurePolicyDecision {
+            rotate_account: true,
+            refund_token: false,
+            record_failure: false,
+            mark_rate_limited: true,
+            remove_account: false,
+            cooldown_ms: None,
+            cooldown_reason: None,
+            retry_same_account: false,
+            retry_delay_ms: None,
+            handoff_strategy: HandoffStrategy::Hard,
+        },
+        Some(FailureKind::EmptyResponse) => {
+            let mode = get_failover_mode(input);
+            let retry_delay_ms = empty_response_retry_delay_ms(mode);
+            let retry_same_account = retry_delay_ms > 0;
+            FailurePolicyDecision {
+                rotate_account: !retry_same_account,
+                refund_token: true,
+                record_failure: true,
+                mark_rate_limited: false,
+                remove_account: false,
+                cooldown_ms: None,
+                cooldown_reason: None,
+                retry_same_account,
+                retry_delay_ms: retry_same_account.then_some(retry_delay_ms),
+                handoff_strategy: HandoffStrategy::Soft,
+            }
+        }
+        Some(FailureKind::Unknown) | None => FailurePolicyDecision {
+            rotate_account: true,
+            refund_token: true,
+            record_failure: true,
+            mark_rate_limited: false,
+            remove_account: false,
+            cooldown_ms: None,
+            cooldown_reason: None,
+            retry_same_account: false,
+            retry_delay_ms: None,
+            handoff_strategy: HandoffStrategy::Hard,
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn input(kind: FailureKind) -> FailurePolicyInput {
+        FailurePolicyInput::for_kind(kind)
+    }
+
+    #[test]
+    fn auth_refresh_removal_boundary() {
+        for (failures, remove) in [(0.0, false), (2.0, false), (3.0, true)] {
+            let decision = evaluate_failure_policy(
+                &FailurePolicyInput {
+                    kind: Some(FailureKind::AuthRefresh),
+                    consecutive_auth_failures: Some(failures),
+                    max_auth_failures_before_removal: Some(3.0),
+                    ..Default::default()
+                },
+                None,
+            );
+            assert_eq!(decision.remove_account, remove, "failures={failures}");
+            assert!(decision.rotate_account);
+            assert_eq!(decision.handoff_strategy, HandoffStrategy::Hard);
+        }
+    }
+
+    #[test]
+    fn auth_refresh_removal_sets_cooldown_reason() {
+        let decision = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::AuthRefresh),
+                consecutive_auth_failures: Some(3.0),
+                max_auth_failures_before_removal: Some(3.0),
+                ..Default::default()
+            },
+            None,
+        );
+        assert!(decision.remove_account);
+        assert_eq!(decision.cooldown_reason, Some(CooldownReason::AuthFailure));
+        assert_eq!(decision.cooldown_ms, Some(30_000));
+    }
+
+    #[test]
+    fn network_configured_cooldown_rotates() {
+        let decision = evaluate_failure_policy(
+            &input(FailureKind::Network),
+            Some(&FailurePolicyOverrides {
+                network_cooldown_ms: Some(9_000.0),
+                ..Default::default()
+            }),
+        );
+        assert!(decision.rotate_account);
+        assert!(decision.refund_token);
+        assert_eq!(decision.cooldown_ms, Some(9_000));
+        assert_eq!(decision.cooldown_reason, Some(CooldownReason::NetworkError));
+    }
+
+    #[test]
+    fn network_balanced_retries_same_account() {
+        let decision = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Network),
+                failover_mode: Some(FailoverMode::Balanced),
+                ..Default::default()
+            },
+            Some(&FailurePolicyOverrides {
+                network_cooldown_ms: Some(9_000.0),
+                ..Default::default()
+            }),
+        );
+        assert!(decision.retry_same_account);
+        assert_eq!(decision.retry_delay_ms, Some(250));
+        assert!(!decision.rotate_account);
+        assert_eq!(decision.handoff_strategy, HandoffStrategy::Soft);
+    }
+
+    #[test]
+    fn network_mode_matrix() {
+        for (mode, retry_same, delay) in [
+            (FailoverMode::Aggressive, false, None),
+            (FailoverMode::Balanced, true, Some(250)),
+            (FailoverMode::Conservative, true, Some(900)),
+        ] {
+            let decision = evaluate_failure_policy(
+                &FailurePolicyInput {
+                    kind: Some(FailureKind::Network),
+                    failover_mode: Some(mode),
+                    ..Default::default()
+                },
+                None,
+            );
+            assert_eq!(decision.retry_same_account, retry_same);
+            assert_eq!(decision.retry_delay_ms, delay);
+            assert_eq!(decision.rotate_account, !retry_same);
+            assert_eq!(decision.handoff_strategy, HandoffStrategy::Soft);
+        }
+    }
+
+    #[test]
+    fn server_mode_matrix_zero_retry_after() {
+        for (mode, retry_same, delay, rotate) in [
+            (FailoverMode::Aggressive, false, None, true),
+            (FailoverMode::Balanced, false, None, true),
+            (FailoverMode::Conservative, true, Some(500), false),
+        ] {
+            let decision = evaluate_failure_policy(
+                &FailurePolicyInput {
+                    kind: Some(FailureKind::Server),
+                    failover_mode: Some(mode),
+                    server_retry_after_ms: Some(0.0),
+                    ..Default::default()
+                },
+                None,
+            );
+            assert_eq!(decision.retry_same_account, retry_same);
+            assert_eq!(decision.retry_delay_ms, delay);
+            assert_eq!(decision.rotate_account, rotate);
+            assert_eq!(decision.handoff_strategy, HandoffStrategy::Hard);
+        }
+    }
+
+    #[test]
+    fn server_conservative_without_retry_after_retries_same() {
+        let decision = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Server),
+                failover_mode: Some(FailoverMode::Conservative),
+                ..Default::default()
+            },
+            Some(&FailurePolicyOverrides {
+                server_cooldown_ms: Some(4_000.0),
+                ..Default::default()
+            }),
+        );
+        assert!(decision.retry_same_account);
+        assert_eq!(decision.retry_delay_ms, Some(500));
+        assert!(!decision.rotate_account);
+        assert_eq!(decision.cooldown_reason, Some(CooldownReason::ServerError));
+    }
+
+    #[test]
+    fn server_rotates_when_retry_after_provided() {
+        let decision = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Server),
+                failover_mode: Some(FailoverMode::Conservative),
+                server_retry_after_ms: Some(3_000.0),
+                ..Default::default()
+            },
+            None,
+        );
+        assert!(!decision.retry_same_account);
+        assert!(decision.rotate_account);
+        assert_eq!(decision.cooldown_ms, Some(3_000));
+        assert_eq!(decision.cooldown_reason, Some(CooldownReason::ServerError));
+    }
+
+    #[test]
+    fn rate_limit_marks_without_cooldown() {
+        let decision = evaluate_failure_policy(&input(FailureKind::RateLimit), None);
+        assert!(decision.mark_rate_limited);
+        assert!(!decision.refund_token);
+        assert_eq!(decision.cooldown_ms, None);
+    }
+
+    #[test]
+    fn empty_response_mode_matrix() {
+        for (mode, retry_same, delay) in [
+            (FailoverMode::Aggressive, false, None),
+            (FailoverMode::Balanced, true, Some(200)),
+            (FailoverMode::Conservative, true, Some(600)),
+        ] {
+            let decision = evaluate_failure_policy(
+                &FailurePolicyInput {
+                    kind: Some(FailureKind::EmptyResponse),
+                    failover_mode: Some(mode),
+                    ..Default::default()
+                },
+                None,
+            );
+            assert_eq!(decision.retry_same_account, retry_same);
+            assert_eq!(decision.retry_delay_ms, delay);
+            assert_eq!(decision.rotate_account, !retry_same);
+            assert_eq!(decision.handoff_strategy, HandoffStrategy::Soft);
+        }
+    }
+
+    #[test]
+    fn zero_override_cooldowns_clear_reason() {
+        let network = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Network),
+                failover_mode: Some(FailoverMode::Aggressive),
+                ..Default::default()
+            },
+            Some(&FailurePolicyOverrides {
+                network_cooldown_ms: Some(0.0),
+                ..Default::default()
+            }),
+        );
+        let server = evaluate_failure_policy(
+            &FailurePolicyInput {
+                kind: Some(FailureKind::Server),
+                failover_mode: Some(FailoverMode::Aggressive),
+                server_retry_after_ms: Some(0.0),
+                ..Default::default()
+            },
+            Some(&FailurePolicyOverrides {
+                server_cooldown_ms: Some(0.0),
+                ..Default::default()
+            }),
+        );
+        assert_eq!(network.cooldown_ms, Some(0));
+        assert_eq!(network.cooldown_reason, None);
+        assert_eq!(server.cooldown_ms, Some(0));
+        assert_eq!(server.cooldown_reason, None);
+    }
+
+    #[test]
+    fn unknown_kind_falls_back_to_hard_default() {
+        for probe in [input(FailureKind::Unknown), FailurePolicyInput::default()] {
+            let decision = evaluate_failure_policy(&probe, None);
+            assert!(decision.rotate_account);
+            assert!(decision.refund_token);
+            assert!(decision.record_failure);
+            assert!(!decision.remove_account);
+            assert!(!decision.retry_same_account);
+            assert_eq!(decision.handoff_strategy, HandoffStrategy::Hard);
+        }
+    }
+
+    #[test]
+    fn missing_failover_mode_defaults_to_aggressive() {
+        // Gotcha 12: input default is aggressive (0-delay -> immediate rotate).
+        let decision = evaluate_failure_policy(&input(FailureKind::Network), None);
+        assert!(!decision.retry_same_account);
+        assert!(decision.rotate_account);
+    }
+}
diff --git a/crates/request/src/fetch_helpers.rs b/crates/request/src/fetch_helpers.rs
new file mode 100644
index 000000000..c18637aa1
--- /dev/null
+++ b/crates/request/src/fetch_helpers.rs
@@ -0,0 +1,2233 @@
+//! Port of `lib/request/fetch-helpers.ts` — orchestration helpers for the
+//! custom fetch implementation.
+//!
+//! Behavior source: spec 06 §6 + the TS source (authority).
+//!
+//! Like the TS module, this file re-exports the public surfaces of
+//! `error_classification`, `url_rewriting`, `headers`, and `token_refresh`
+//! so importers can keep using one canonical entry point.
+//!
+//! Shared HTTP client (ARCHITECTURE §5.1): ONE `reqwest::Client` per process,
+//! built here ([`shared_client`]). The 60 s fetch timeout is enforced
+//! per-request by callers via `tokio::time::timeout` (driven by
+//! `cma_config::getters::get_fetch_timeout_ms`), mirroring the TS
+//! AbortController pattern — NEVER as a client-wide timeout (that would also
+//! kill healthy long-lived SSE streams).
+//!
+//! Sibling seam: the TS `transformRequestForCodex` calls
+//! `request-transformer.transformRequestBody` and
+//! `prompts/codex.getCodexInstructions` directly. Those live in sibling
+//! agents' files (`transformer.rs`, `prompts/codex.rs`), so they are injected
+//! through [`TransformRequestForCodexDeps`]; the pipeline wires the real
+//! functions once they land. Everything already implemented (`model_map`,
+//! `response_handler`, `error_classification`, `headers`, `url_rewriting`) is
+//! called directly.
+
+use std::sync::OnceLock;
+
+use cma_core::constants::{ERROR_MESSAGES, HTTP_STATUS, LOG_STAGES, MAX_RATE_LIMIT_DELAY_MS};
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{log_error, log_request, log_warn};
+use cma_core::types::UserConfig;
+use cma_core::utils::{now_ms, to_string_value};
+use futures::future::BoxFuture;
+use http::header::{HeaderMap, HeaderValue};
+use regex::Regex;
+use serde_json::{Map, Value};
+
+use crate::error_classification::{
+    CHATGPT_CODEX_UNSUPPORTED_MODEL_CODE, is_unsupported_codex_model_for_chatgpt,
+};
+use crate::headers::log_deprecation_headers;
+use crate::model_map::{get_model_family, resolve_normalized_model};
+use crate::request_init::{BodyInit, RequestInit};
+use crate::response_handler::{
+    BoxError, ConvertSseOptions, StreamResponse, attach_response_id_capture, convert_sse_to_json,
+    ensure_content_type,
+};
+use crate::response_metadata::js_date_parse_ms;
+
+// ---------------------------------------------------------------------------
+// Re-export surface (TS `export ... from` block in fetch-helpers.ts)
+// ---------------------------------------------------------------------------
+
+pub use crate::error_classification::{
+    DEFAULT_UNSUPPORTED_CODEX_FALLBACK_CHAIN, ResolveUnsupportedCodexFallbackOptions,
+    UnsupportedCodexModelInfo, create_entitlement_error_response,
+    extract_unsupported_codex_model_from_text, get_unsupported_codex_model_info,
+    is_entitlement_error, is_workspace_disabled_error, resolve_unsupported_codex_fallback_model,
+    should_fallback_to_gpt52_on_unsupported_gpt53,
+};
+pub use crate::headers::{
+    ArgError, CreateCodexHeadersOptions, CreateCodexHeadersParams, create_codex_headers,
+    create_codex_headers_positional,
+};
+pub use crate::token_refresh::{
+    Auth, AuthPersistPayload, AuthSetterFn, refresh_and_update_token,
+    refresh_and_update_token_with, should_refresh_token, should_refresh_token_at,
+};
+pub use crate::url_rewriting::{
+    close_shared_proxy_dispatchers, extract_request_url, resolve_client_for_request,
+    resolve_proxy_url_for_request, rewrite_url_for_codex,
+};
+
+// ---------------------------------------------------------------------------
+// Shared response/client primitives
+// ---------------------------------------------------------------------------
+
+/// A fully-buffered synthetic `Response` (the web `new Response(text, ...)`
+/// analogue used by the error-normalization paths, where bodies are always
+/// small JSON strings).
+#[derive(Debug, Clone)]
+pub struct SyntheticResponse {
+    pub status: u16,
+    pub status_text: String,
+    pub headers: HeaderMap,
+    pub body: String,
+}
+
+impl SyntheticResponse {
+    /// Parse the buffered body as JSON (test/consumer convenience — the TS
+    /// `await response.json()`).
+    pub fn json(&self) -> Option<Value> {
+        serde_json::from_str(&self.body).ok()
+    }
+
+    /// Convert into a streaming response (single-chunk body).
+    pub fn into_stream_response(self) -> StreamResponse {
+        StreamResponse::from_text(self.status, self.status_text, self.headers, self.body)
+    }
+}
+
+/// The ONE process-wide direct `reqwest::Client` (ARCHITECTURE §5.1).
+///
+/// Deliberately built WITHOUT a client-wide timeout: per-request deadlines are
+/// the caller's `tokio::time::timeout` (60 s default via config), and the
+/// 45 s stream-stall timeout applies between chunks in `response_handler`.
+pub fn shared_client() -> &'static reqwest::Client {
+    static CLIENT: OnceLock<reqwest::Client> = OnceLock::new();
+    CLIENT.get_or_init(|| {
+        reqwest::Client::builder()
+            .build()
+            .expect("failed to build the shared HTTP client")
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Types (TS interfaces)
+// ---------------------------------------------------------------------------
+
+/// TS `RateLimitInfo`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RateLimitInfo {
+    pub retry_after_ms: i64,
+    /// The parsed `error.code`/`error.type` string; `Some("")` when the body
+    /// parsed but carried no code (TS keeps the empty string).
+    pub code: Option<String>,
+}
+
+/// TS `FastSessionInputTrimPlan["trim"]` — the deferred-trim directive handed
+/// from the transform step to `response_compaction`.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct DeferredFastSessionInputTrim {
+    pub max_items: f64,
+    pub prefer_latest_user_only: bool,
+}
+
+/// TS `"hybrid" | "always"` fast-session strategy union.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum FastSessionStrategy {
+    #[default]
+    Hybrid,
+    Always,
+}
+
+impl FastSessionStrategy {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            FastSessionStrategy::Hybrid => "hybrid",
+            FastSessionStrategy::Always => "always",
+        }
+    }
+}
+
+/// TS `TransformRequestForCodexResult`.
+#[derive(Debug, Clone)]
+pub struct TransformRequestForCodexResult {
+    pub body: Map<String, Value>,
+    pub updated_init: RequestInit,
+    pub deferred_fast_session_input_trim: Option<DeferredFastSessionInputTrim>,
+}
+
+/// The TS optional `options` bag of `transformRequestForCodex`.
+#[derive(Debug, Clone, Copy)]
+pub struct TransformRequestForCodexOptions {
+    pub fast_session: bool,
+    pub fast_session_strategy: FastSessionStrategy,
+    pub fast_session_max_input_items: f64,
+    pub defer_fast_session_input_trimming: bool,
+    pub allow_background_responses: bool,
+}
+
+impl Default for TransformRequestForCodexOptions {
+    fn default() -> Self {
+        TransformRequestForCodexOptions {
+            fast_session: false,
+            fast_session_strategy: FastSessionStrategy::Hybrid,
+            fast_session_max_input_items: 30.0,
+            defer_fast_session_input_trimming: false,
+            allow_background_responses: false,
+        }
+    }
+}
+
+/// Arguments forwarded to the injected `transformRequestBody` (the TS
+/// positional call in `transformRequestForCodex`).
+#[derive(Debug, Clone)]
+pub struct TransformRequestBodyArgs {
+    pub body: Map<String, Value>,
+    pub codex_instructions: String,
+    pub user_config: UserConfig,
+    pub codex_mode: bool,
+    pub fast_session: bool,
+    pub fast_session_strategy: FastSessionStrategy,
+    pub fast_session_max_input_items: f64,
+    pub defer_fast_session_input_trimming: bool,
+    pub allow_background_responses: bool,
+}
+
+/// `transformer::resolve_fast_session_input_trim_plan(...).trim` seam:
+/// `(body, fastSession, strategy, maxItems)` → the deferred-trim directive
+/// (`None` when the plan does not apply).
+pub type ResolveFastSessionInputTrimFn<'a> = &'a (dyn Fn(
+    &Map<String, Value>,
+    bool,
+    FastSessionStrategy,
+    f64,
+) -> Option<DeferredFastSessionInputTrim>
+              + Send
+              + Sync);
+
+/// `prompts::codex::get_codex_instructions(normalizedModel)` seam.
+pub type GetCodexInstructionsFn<'a> =
+    &'a (dyn Fn(&str) -> BoxFuture<'static, Result<String, BoxError>> + Send + Sync);
+
+/// `transformer::transform_request_body(...)` seam. Errors whose message
+/// starts with `"Responses background mode"` MUST surface as errors — they
+/// are rethrown; everything else degrades to `None`.
+pub type TransformRequestBodyFn<'a> = &'a (dyn Fn(
+    TransformRequestBodyArgs,
+)
+    -> BoxFuture<'static, Result<Map<String, Value>, BoxError>>
+              + Send
+              + Sync);
+
+/// Sibling seam for `transformRequestForCodex` (see module docs). The
+/// pipeline wires the three closures to the real `transformer`/`prompts`
+/// functions once those sibling modules land.
+pub struct TransformRequestForCodexDeps<'a> {
+    pub resolve_fast_session_input_trim: ResolveFastSessionInputTrimFn<'a>,
+    pub get_codex_instructions: GetCodexInstructionsFn<'a>,
+    pub transform_request_body: TransformRequestBodyFn<'a>,
+}
+
+/// TS `ErrorHandlingResult`. `error_body` is the NORMALIZED payload (spec 06
+/// gotcha 27), not the raw upstream JSON.
+#[derive(Debug, Clone)]
+pub struct ErrorHandlingResult {
+    pub response: SyntheticResponse,
+    pub rate_limit: Option<RateLimitInfo>,
+    pub error_body: Option<Value>,
+}
+
+/// TS `ErrorHandlingOptions`.
+#[derive(Debug, Clone, Default)]
+pub struct ErrorHandlingOptions {
+    pub request_correlation_id: Option<String>,
+    pub thread_id: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// transformRequestForCodex
+// ---------------------------------------------------------------------------
+
+/// JS truthiness for logging fields (`!!value`).
+fn js_truthy(value: Option<&Value>) -> bool {
+    match value {
+        None | Some(Value::Null) => false,
+        Some(Value::Bool(b)) => *b,
+        Some(Value::Number(n)) => n.as_f64().map(|f| f != 0.0 && !f.is_nan()).unwrap_or(true),
+        Some(Value::String(s)) => !s.is_empty(),
+        Some(Value::Array(_)) | Some(Value::Object(_)) => true,
+    }
+}
+
+/// TS `body.input?.length` — array length, or UTF-16 length for string input.
+fn js_input_length(value: Option<&Value>) -> Option<u64> {
+    match value {
+        Some(Value::Array(items)) => Some(items.len() as u64),
+        Some(Value::String(s)) => Some(s.encode_utf16().count() as u64),
+        _ => None,
+    }
+}
+
+fn transform_log_common(map: &mut Map<String, Value>, body: &Map<String, Value>) {
+    map.insert(
+        "hasTools".to_string(),
+        Value::Bool(js_truthy(body.get("tools"))),
+    );
+    map.insert(
+        "hasInput".to_string(),
+        Value::Bool(js_truthy(body.get("input"))),
+    );
+    if let Some(length) = js_input_length(body.get("input")) {
+        map.insert("inputLength".to_string(), Value::from(length));
+    }
+}
+
+/// TS `transformRequestForCodex(init, url, userConfig, codexMode, parsedBody,
+/// options)`.
+///
+/// Returns:
+/// - `Ok(None)` for the TS `undefined` outcomes (no body, non-string body,
+///   parse failure — logged as `"Error parsing request"`);
+/// - `Err(_)` ONLY for rethrown background-mode violations (message starts
+///   with `"Responses background mode"`).
+pub async fn transform_request_for_codex(
+    init: Option<&RequestInit>,
+    url: &str,
+    user_config: &UserConfig,
+    codex_mode: bool,
+    parsed_body: Option<&Map<String, Value>>,
+    options: TransformRequestForCodexOptions,
+    deps: &TransformRequestForCodexDeps<'_>,
+) -> Result<Option<TransformRequestForCodexResult>, BoxError> {
+    let has_parsed_body = parsed_body.map(|map| !map.is_empty()).unwrap_or(false);
+    // TS truthiness on init.body: an empty string is falsy; byte bodies (the
+    // Blob/Uint8Array arms) are truthy but fail the string check below.
+    let init_body = init.and_then(|i| i.body.as_ref()).filter(|body| match body {
+        BodyInit::Text(text) => !text.is_empty(),
+        BodyInit::Bytes(_) => true,
+    });
+    if init_body.is_none() && !has_parsed_body {
+        return Ok(None);
+    }
+
+    let body: Map<String, Value> = if has_parsed_body {
+        parsed_body.expect("has_parsed_body").clone()
+    } else {
+        match init_body {
+            Some(BodyInit::Text(text)) => match serde_json::from_str::<Value>(text) {
+                Ok(Value::Object(map)) => map,
+                // Non-object JSON dies inside the TS transform with a caught
+                // TypeError; parse failures die at JSON.parse. Both land in
+                // the same logError + undefined outcome.
+                Ok(_) | Err(_) => {
+                    log_error(ERROR_MESSAGES.request_parse_error, None);
+                    return Ok(None);
+                }
+            },
+            _ => return Ok(None),
+        }
+    };
+
+    let original_model = body.get("model").and_then(Value::as_str).map(str::to_string);
+    let trim_directive = (deps.resolve_fast_session_input_trim)(
+        &body,
+        options.fast_session,
+        options.fast_session_strategy,
+        options.fast_session_max_input_items,
+    );
+
+    // Normalize first so the correct model-specific prompt is fetched.
+    let normalized_model = resolve_normalized_model(original_model.as_deref());
+    let model_family = get_model_family(normalized_model);
+
+    // Log original request.
+    let mut before = Map::new();
+    before.insert("url".to_string(), Value::String(url.to_string()));
+    before.insert(
+        "originalModel".to_string(),
+        original_model
+            .clone()
+            .map(Value::String)
+            .unwrap_or(Value::Null),
+    );
+    before.insert(
+        "model".to_string(),
+        body.get("model").cloned().unwrap_or(Value::Null),
+    );
+    transform_log_common(&mut before, &body);
+    before.insert("codexMode".to_string(), Value::Bool(codex_mode));
+    before.insert("body".to_string(), Value::Object(body.clone()));
+    log_request(LOG_STAGES.before_transform, &before);
+
+    // Fetch model-specific Codex instructions (cached per model family).
+    let codex_instructions = match (deps.get_codex_instructions)(normalized_model).await {
+        Ok(instructions) => instructions,
+        Err(error) => {
+            log_error(
+                ERROR_MESSAGES.request_parse_error,
+                Some(&Value::String(error.to_string())),
+            );
+            return Ok(None);
+        }
+    };
+
+    // Transform request body.
+    let transformed_body = match (deps.transform_request_body)(TransformRequestBodyArgs {
+        body,
+        codex_instructions,
+        user_config: user_config.clone(),
+        codex_mode,
+        fast_session: options.fast_session,
+        fast_session_strategy: options.fast_session_strategy,
+        fast_session_max_input_items: options.fast_session_max_input_items,
+        defer_fast_session_input_trimming: options.defer_fast_session_input_trimming,
+        allow_background_responses: options.allow_background_responses,
+    })
+    .await
+    {
+        Ok(transformed) => transformed,
+        Err(error) => {
+            // Background-mode violations are RETHROWN (TS
+            // `e.message.startsWith("Responses background mode")`).
+            if error.to_string().starts_with("Responses background mode") {
+                return Err(error);
+            }
+            log_error(
+                ERROR_MESSAGES.request_parse_error,
+                Some(&Value::String(error.to_string())),
+            );
+            return Ok(None);
+        }
+    };
+
+    // Log transformed request. (TS logs `transformedBody.model` under the
+    // `normalizedModel` key — the transformer never rewrites `body.model`.)
+    let mut after = Map::new();
+    after.insert("url".to_string(), Value::String(url.to_string()));
+    after.insert(
+        "originalModel".to_string(),
+        original_model.map(Value::String).unwrap_or(Value::Null),
+    );
+    after.insert(
+        "normalizedModel".to_string(),
+        transformed_body.get("model").cloned().unwrap_or(Value::Null),
+    );
+    after.insert(
+        "modelFamily".to_string(),
+        Value::String(model_family.as_str().to_string()),
+    );
+    transform_log_common(&mut after, &transformed_body);
+    if let Some(reasoning) = transformed_body.get("reasoning") {
+        after.insert("reasoning".to_string(), reasoning.clone());
+    }
+    if let Some(verbosity) = transformed_body
+        .get("text")
+        .and_then(|text| text.get("verbosity"))
+    {
+        after.insert("textVerbosity".to_string(), verbosity.clone());
+    }
+    if let Some(include) = transformed_body.get("include") {
+        after.insert("include".to_string(), include.clone());
+    }
+    after.insert("body".to_string(), Value::Object(transformed_body.clone()));
+    log_request(LOG_STAGES.after_transform, &after);
+
+    let mut updated_init = init.cloned().unwrap_or_default();
+    updated_init.body = Some(BodyInit::Text(stringify_compact(&Value::Object(
+        transformed_body.clone(),
+    ))));
+
+    let background = transformed_body.get("background") == Some(&Value::Bool(true));
+    Ok(Some(TransformRequestForCodexResult {
+        body: transformed_body,
+        updated_init,
+        deferred_fast_session_input_trim: if options.defer_fast_session_input_trimming
+            && !background
+        {
+            trim_directive
+        } else {
+            None
+        },
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// handleErrorResponse
+// ---------------------------------------------------------------------------
+
+fn header_str<'a>(headers: &'a HeaderMap, name: &str) -> Option<std::borrow::Cow<'a, str>> {
+    headers
+        .get(name)
+        .map(|value| String::from_utf8_lossy(value.as_bytes()))
+}
+
+/// JS `Number.parseInt(value, 10)`: leading whitespace + optional sign +
+/// leading digit run; anything else → NaN (`None`).
+fn js_parse_int(value: &str) -> Option<f64> {
+    let trimmed = value.trim_start();
+    let (sign, rest) = match trimmed.as_bytes().first() {
+        Some(b'-') => (-1.0, &trimmed[1..]),
+        Some(b'+') => (1.0, &trimmed[1..]),
+        _ => (1.0, trimmed),
+    };
+    let digits: &str = {
+        let end = rest
+            .as_bytes()
+            .iter()
+            .position(|byte| !byte.is_ascii_digit())
+            .unwrap_or(rest.len());
+        &rest[..end]
+    };
+    if digits.is_empty() {
+        return None;
+    }
+    digits.parse::<f64>().ok().map(|parsed| sign * parsed)
+}
+
+/// TS `toNumber(value)`: `null`/absent → `None`; `Number(value)` with the
+/// non-finite results filtered.
+fn js_to_number(value: Option<&Value>) -> Option<f64> {
+    match value? {
+        Value::Null => None,
+        Value::Number(number) => number.as_f64().filter(|f| f.is_finite()),
+        Value::String(text) => {
+            let trimmed = text.trim();
+            if trimmed.is_empty() {
+                return Some(0.0);
+            }
+            trimmed.parse::<f64>().ok().filter(|f| f.is_finite())
+        }
+        Value::Bool(b) => Some(if *b { 1.0 } else { 0.0 }),
+        Value::Array(_) | Value::Object(_) => None,
+    }
+}
+
+/// TS `clampRateLimitDelayMs`: non-finite → None; floor; ≤ 0 → None;
+/// `min(value, MAX_RATE_LIMIT_DELAY_MS)` (7-day clamp).
+fn clamp_rate_limit_delay_ms(value: f64) -> Option<i64> {
+    if !value.is_finite() {
+        return None;
+    }
+    let normalized = value.floor();
+    if normalized <= 0.0 {
+        return None;
+    }
+    Some((normalized as i64).min(MAX_RATE_LIMIT_DELAY_MS))
+}
+
+fn normalize_retry_after_ms(value: f64) -> Option<i64> {
+    clamp_rate_limit_delay_ms(value)
+}
+
+fn normalize_retry_after_seconds(value: f64) -> Option<i64> {
+    clamp_rate_limit_delay_ms(value * 1000.0)
+}
+
+/// TS `parseResetTimestampMs`: all-digits → epoch seconds when
+/// `< 10_000_000_000`, else epoch ms; otherwise `Date.parse`.
+fn parse_reset_timestamp_ms(raw_value: &str) -> Option<f64> {
+    let trimmed = raw_value.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    if !trimmed.is_empty() && trimmed.bytes().all(|byte| byte.is_ascii_digit())
+        && let Ok(parsed) = trimmed.parse::<f64>()
+            && parsed.is_finite() && parsed > 0.0 {
+                return Some(if parsed < 10_000_000_000.0 {
+                    parsed * 1000.0
+                } else {
+                    parsed
+                });
+            }
+
+    js_date_parse_ms(trimmed).map(|ms| ms as f64)
+}
+
+/// Parsed `parseRateLimitBody` output.
+#[derive(Debug, Clone, PartialEq)]
+struct ParsedRateLimitBody {
+    code: String,
+    resets_at: Option<f64>,
+    retry_after_ms: Option<f64>,
+    retry_after_seconds: Option<f64>,
+}
+
+/// TS `parseRateLimitBody(body)`.
+fn parse_rate_limit_body(body: &str) -> Option<ParsedRateLimitBody> {
+    if body.is_empty() {
+        return None;
+    }
+    let parsed: Value = serde_json::from_str(body).ok()?;
+    let empty = Map::new();
+    let error = parsed.get("error").and_then(Value::as_object).unwrap_or(&empty);
+
+    // `(error.code ?? error.type ?? "").toString()` — null coalesces onward.
+    let code = error
+        .get("code")
+        .filter(|value| !value.is_null())
+        .or_else(|| error.get("type").filter(|value| !value.is_null()))
+        .map(to_string_value)
+        .unwrap_or_default();
+    let resets_at = js_to_number(
+        error
+            .get("resets_at")
+            .filter(|value| !value.is_null())
+            .or_else(|| error.get("reset_at").filter(|value| !value.is_null())),
+    );
+    let retry_after_ms = js_to_number(error.get("retry_after_ms"));
+    let retry_after_seconds = js_to_number(error.get("retry_after"));
+    Some(ParsedRateLimitBody {
+        code,
+        resets_at,
+        retry_after_ms,
+        retry_after_seconds,
+    })
+}
+
+fn retry_after_duration_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r"(?i)\b(?:try|retry)\s+again\s+in\s+(\d+)\s*(second|minute|hour|day)s?\b")
+            .unwrap()
+    })
+}
+
+fn retry_after_clock_time_pattern() -> &'static Regex {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    RE.get_or_init(|| {
+        Regex::new(r"(?i)\b(?:try|retry)\s+again\s+at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\b")
+            .unwrap()
+    })
+}
+
+/// TS `parseRetryAfterTextMs(bodyText, now)` — natural-language retry hints.
+pub(crate) fn parse_retry_after_text_ms_at(body_text: &str, now_ms: i64) -> Option<i64> {
+    if body_text.is_empty() {
+        return None;
+    }
+
+    if let Some(captures) = retry_after_duration_pattern().captures(body_text) {
+        let amount = captures
+            .get(1)
+            .and_then(|amount| js_parse_int(amount.as_str()));
+        let unit = captures
+            .get(2)
+            .map(|unit| unit.as_str().to_lowercase())
+            .unwrap_or_default();
+        if let Some(amount) = amount.filter(|amount| *amount > 0.0) {
+            let multiplier: f64 = match unit.as_str() {
+                "second" => 1000.0,
+                "minute" => 60_000.0,
+                "hour" => 3_600_000.0,
+                "day" => 86_400_000.0,
+                _ => 0.0,
+            };
+            if multiplier > 0.0 {
+                return clamp_rate_limit_delay_ms(amount * multiplier);
+            }
+        }
+    }
+
+    let captures = retry_after_clock_time_pattern().captures(body_text)?;
+    let hour12 = captures.get(1).and_then(|h| js_parse_int(h.as_str()))?;
+    let minute = captures
+        .get(2)
+        .map(|m| js_parse_int(m.as_str()))
+        .unwrap_or(Some(0.0))?;
+    let meridiem = captures
+        .get(3)
+        .map(|m| m.as_str().to_lowercase())
+        .unwrap_or_default();
+    if !(1.0..=12.0).contains(&hour12)
+        || !(0.0..=59.0).contains(&minute)
+        || (meridiem != "am" && meridiem != "pm")
+    {
+        return None;
+    }
+
+    // Next LOCAL occurrence of that clock time (TS `target.setHours(...)`).
+    use chrono::TimeZone;
+    let mut hour24 = (hour12 as u32) % 12;
+    if meridiem == "pm" {
+        hour24 += 12;
+    }
+    let now_local = chrono::Local.timestamp_millis_opt(now_ms).single()?;
+    let today = now_local.date_naive();
+    let resolve = |date: chrono::NaiveDate| -> Option<i64> {
+        let naive = date.and_hms_opt(hour24, minute as u32, 0)?;
+        let local = chrono::Local
+            .from_local_datetime(&naive)
+            .earliest()?;
+        Some(local.timestamp_millis())
+    };
+    let mut target_ms = resolve(today)?;
+    if target_ms <= now_ms {
+        target_ms = resolve(today.succ_opt()?)?;
+    }
+    clamp_rate_limit_delay_ms((target_ms - now_ms) as f64)
+}
+
+/// TS `parseRetryAfterMs(response, bodyText, parsedBody)` — full precedence
+/// order (spec 06 §6), everything clamped to the 7-day cap.
+fn parse_retry_after_ms_at(
+    headers: &HeaderMap,
+    body_text: &str,
+    parsed_body: Option<&ParsedRateLimitBody>,
+    now_ms: i64,
+) -> Option<i64> {
+    if let Some(retry_after_ms) = parsed_body.and_then(|parsed| parsed.retry_after_ms)
+        && let Some(normalized) = normalize_retry_after_ms(retry_after_ms) {
+            return Some(normalized);
+        }
+    if let Some(retry_after_seconds) = parsed_body.and_then(|parsed| parsed.retry_after_seconds)
+        && let Some(normalized) = normalize_retry_after_seconds(retry_after_seconds) {
+            return Some(normalized);
+        }
+
+    if let Some(header) = header_str(headers, "retry-after-ms").filter(|value| !value.is_empty())
+        && let Some(parsed) = js_parse_int(&header)
+            && let Some(normalized) = normalize_retry_after_ms(parsed) {
+                return Some(normalized);
+            }
+
+    if let Some(header) = header_str(headers, "retry-after").filter(|value| !value.is_empty()) {
+        if let Some(parsed) = js_parse_int(&header)
+            && let Some(normalized) = normalize_retry_after_seconds(parsed) {
+                return Some(normalized);
+            }
+        if let Some(parsed_date_ms) = js_date_parse_ms(header.trim())
+            && let Some(normalized) = normalize_retry_after_ms((parsed_date_ms - now_ms) as f64) {
+                return Some(normalized);
+            }
+    }
+
+    let mut reset_candidates: Vec<i64> = Vec::new();
+    for header in [
+        "x-codex-primary-reset-after-seconds",
+        "x-codex-secondary-reset-after-seconds",
+    ] {
+        let Some(value) = header_str(headers, header).filter(|value| !value.is_empty()) else {
+            continue;
+        };
+        if let Some(parsed) = js_parse_int(&value)
+            && let Some(normalized) = normalize_retry_after_seconds(parsed) {
+                reset_candidates.push(normalized);
+            }
+    }
+
+    for header in [
+        "x-codex-primary-reset-at",
+        "x-codex-secondary-reset-at",
+        "x-ratelimit-reset",
+    ] {
+        let Some(value) = header_str(headers, header).filter(|value| !value.is_empty()) else {
+            continue;
+        };
+        let Some(timestamp) = parse_reset_timestamp_ms(&value) else {
+            continue;
+        };
+        if let Some(delta) = normalize_retry_after_ms(timestamp - now_ms as f64) {
+            reset_candidates.push(delta);
+        }
+    }
+
+    // `if (parsedBody?.resetsAt)` — TS truthiness: 0 is falsy.
+    if let Some(resets_at) = parsed_body
+        .and_then(|parsed| parsed.resets_at)
+        .filter(|value| *value != 0.0)
+    {
+        let timestamp = if resets_at < 10_000_000_000.0 {
+            resets_at * 1000.0
+        } else {
+            resets_at
+        };
+        if let Some(delta) = normalize_retry_after_ms(timestamp - now_ms as f64) {
+            reset_candidates.push(delta);
+        }
+    }
+
+    if let Some(max) = reset_candidates.into_iter().max() {
+        return Some(max);
+    }
+
+    parse_retry_after_text_ms_at(body_text, now_ms)
+}
+
+/// Outcome of the TS `mapUsageLimit404WithBody`.
+enum Usage404Mapping {
+    Untouched,
+    /// Entitlement 404 → the fixed 403 response.
+    Entitlement(SyntheticResponse),
+    /// Structured quota-limit 404 → remap to 429 "Too Many Requests".
+    RateLimited,
+}
+
+fn map_usage_limit_404_with_body(status: u16, body_text: &str) -> Usage404Mapping {
+    if status != HTTP_STATUS.not_found || body_text.is_empty() {
+        return Usage404Mapping::Untouched;
+    }
+
+    let (code, error_type) = match serde_json::from_str::<Value>(body_text) {
+        Ok(parsed) => {
+            let error = parsed.get("error").cloned().unwrap_or(Value::Null);
+            let code = error
+                .get("code")
+                .filter(|value| !value.is_null())
+                .map(to_string_value)
+                .unwrap_or_default();
+            let error_type = error
+                .get("type")
+                .filter(|value| !value.is_null())
+                .map(to_string_value)
+                .unwrap_or_default();
+            (code, error_type)
+        }
+        Err(_) => (String::new(), String::new()),
+    };
+
+    let normalized_signals: Vec<String> = [code, error_type]
+        .into_iter()
+        .map(|value| value.to_lowercase())
+        .filter(|value| !value.is_empty())
+        .collect();
+
+    // Entitlement errors first — these are NOT rate limits.
+    if is_entitlement_error(&normalized_signals.join(" "), body_text) {
+        return Usage404Mapping::Entitlement(create_entitlement_error_response());
+    }
+
+    // Only structured quota-limit codes remap 404 → 429; free-text 404 bodies
+    // stay untouched (spec 06 gotcha 28).
+    if !normalized_signals
+        .iter()
+        .any(|value| value.contains("usage_limit") || value.contains("rate_limit_exceeded"))
+    {
+        return Usage404Mapping::Untouched;
+    }
+
+    Usage404Mapping::RateLimited
+}
+
+fn extract_rate_limit_info(
+    status: u16,
+    headers: &HeaderMap,
+    body_text: &str,
+) -> Option<RateLimitInfo> {
+    let parsed = parse_rate_limit_body(body_text);
+
+    // Entitlement errors should not be treated as rate limits.
+    let code_for_entitlement = parsed
+        .as_ref()
+        .map(|parsed| parsed.code.as_str())
+        .unwrap_or("");
+    if is_entitlement_error(code_for_entitlement, body_text) {
+        return None;
+    }
+
+    if status != HTTP_STATUS.too_many_requests {
+        return None;
+    }
+
+    let retry_after_ms = parse_retry_after_ms_at(headers, body_text, parsed.as_ref(), now_ms())
+        .unwrap_or(60_000);
+    Some(RateLimitInfo {
+        retry_after_ms,
+        code: parsed.map(|parsed| parsed.code),
+    })
+}
+
+/// TS `extractErrorDiagnostics` — ordered `{httpStatus, requestId, cfRay,
+/// correlationId, threadId}` with empty/absent fields removed.
+fn extract_error_diagnostics(
+    headers: &HeaderMap,
+    status: u16,
+    options: Option<&ErrorHandlingOptions>,
+) -> Option<Map<String, Value>> {
+    // First PRESENT header wins even when empty (the TS `??` chain stops at
+    // `""`); empty strings are then dropped by the cleanup pass.
+    let request_id = [
+        "x-request-id",
+        "request-id",
+        "openai-request-id",
+        "x-openai-request-id",
+    ]
+    .iter()
+    .find_map(|name| header_str(headers, name).map(|value| value.into_owned()));
+    let cf_ray = header_str(headers, "cf-ray").map(|value| value.into_owned());
+
+    let mut diagnostics = Map::new();
+    diagnostics.insert("httpStatus".to_string(), Value::from(status));
+    if let Some(request_id) = request_id.filter(|value| !value.is_empty()) {
+        diagnostics.insert("requestId".to_string(), Value::String(request_id));
+    }
+    if let Some(cf_ray) = cf_ray.filter(|value| !value.is_empty()) {
+        diagnostics.insert("cfRay".to_string(), Value::String(cf_ray));
+    }
+    if let Some(correlation_id) = options
+        .and_then(|options| options.request_correlation_id.clone())
+        .filter(|value| !value.is_empty())
+    {
+        diagnostics.insert("correlationId".to_string(), Value::String(correlation_id));
+    }
+    if let Some(thread_id) = options
+        .and_then(|options| options.thread_id.clone())
+        .filter(|value| !value.is_empty())
+    {
+        diagnostics.insert("threadId".to_string(), Value::String(thread_id));
+    }
+
+    if diagnostics.is_empty() {
+        None
+    } else {
+        Some(diagnostics)
+    }
+}
+
+const LOGIN_HINT_SUFFIX: &str = " (run `codex-multi-auth login` if this persists)";
+
+/// TS `normalizeErrorPayload` → `{ error: { message, type?, code?,
+/// unsupported_model?, diagnostics? } }`.
+fn normalize_error_payload(
+    error_body: Option<&Value>,
+    body_text: &str,
+    status_text: &str,
+    status: u16,
+    diagnostics: Option<&Map<String, Value>>,
+) -> Value {
+    let attach_diagnostics = |error: &mut Map<String, Value>| {
+        if let Some(diagnostics) = diagnostics
+            && !diagnostics.is_empty() {
+                error.insert(
+                    "diagnostics".to_string(),
+                    Value::Object(diagnostics.clone()),
+                );
+            }
+    };
+    let append_login_hint = |error: &mut Map<String, Value>| {
+        if status == HTTP_STATUS.unauthorized
+            && let Some(Value::String(message)) = error.get_mut("message") {
+                message.push_str(LOGIN_HINT_SUFFIX);
+            }
+    };
+    let wrap = |error: Map<String, Value>| -> Value {
+        let mut payload = Map::new();
+        payload.insert("error".to_string(), Value::Object(error));
+        Value::Object(payload)
+    };
+
+    if is_unsupported_codex_model_for_chatgpt(status, body_text) {
+        let unsupported_model = extract_unsupported_codex_model_from_text(body_text)
+            .unwrap_or_else(|| "requested model".to_string());
+        let message = format!(
+            "The model '{unsupported_model}' is not currently available for this ChatGPT account when using Codex OAuth. \
+This is an account/workspace entitlement gate, not a temporary rate limit. \
+Try 'gpt-5.3-codex' (current), or legacy aliases like 'gpt-5-codex'/'gpt-5.2-codex', or enable automatic fallback via \
+unsupportedCodexPolicy: \"fallback\" (or CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback). \
+(Legacy: CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1 or fallbackOnUnsupportedCodexModel)."
+        );
+        let mut error = Map::new();
+        error.insert("message".to_string(), Value::String(message));
+        error.insert(
+            "type".to_string(),
+            Value::String("entitlement_error".to_string()),
+        );
+        error.insert(
+            "code".to_string(),
+            Value::String(CHATGPT_CODEX_UNSUPPORTED_MODEL_CODE.to_string()),
+        );
+        error.insert(
+            "unsupported_model".to_string(),
+            Value::String(unsupported_model),
+        );
+        attach_diagnostics(&mut error);
+        return wrap(error);
+    }
+
+    if let Some(Value::Object(body)) = error_body {
+        if let Some(Value::Object(maybe_error)) = body.get("error")
+            && let Some(Value::String(message)) = maybe_error.get("message") {
+                let mut error = Map::new();
+                error.insert("message".to_string(), Value::String(message.clone()));
+                if let Some(Value::String(error_type)) = maybe_error.get("type") {
+                    error.insert("type".to_string(), Value::String(error_type.clone()));
+                }
+                match maybe_error.get("code") {
+                    Some(code @ Value::String(_)) | Some(code @ Value::Number(_)) => {
+                        error.insert("code".to_string(), code.clone());
+                    }
+                    _ => {}
+                }
+                attach_diagnostics(&mut error);
+                append_login_hint(&mut error);
+                return wrap(error);
+            }
+
+        if let Some(Value::String(message)) = body.get("message") {
+            let mut error = Map::new();
+            error.insert("message".to_string(), Value::String(message.clone()));
+            attach_diagnostics(&mut error);
+            append_login_hint(&mut error);
+            return wrap(error);
+        }
+    }
+
+    let trimmed = body_text.trim();
+    let message = if !trimmed.is_empty() {
+        trimmed.to_string()
+    } else if !status_text.is_empty() {
+        status_text.to_string()
+    } else {
+        "Request failed".to_string()
+    };
+    let mut error = Map::new();
+    error.insert("message".to_string(), Value::String(message));
+    attach_diagnostics(&mut error);
+    append_login_hint(&mut error);
+    wrap(error)
+}
+
+/// TS `ensureJsonErrorResponse` — JSON body with the original status/statusText
+/// and `content-type: application/json; charset=utf-8`.
+fn ensure_json_error_response(
+    status: u16,
+    status_text: &str,
+    headers: &HeaderMap,
+    payload: &Value,
+) -> SyntheticResponse {
+    let mut response_headers = headers.clone();
+    response_headers.insert(
+        "content-type",
+        HeaderValue::from_static("application/json; charset=utf-8"),
+    );
+    SyntheticResponse {
+        status,
+        status_text: status_text.to_string(),
+        headers: response_headers,
+        body: stringify_compact(payload),
+    }
+}
+
+/// TS `handleErrorResponse(response, options?)`.
+pub async fn handle_error_response(
+    mut response: StreamResponse,
+    options: Option<&ErrorHandlingOptions>,
+) -> ErrorHandlingResult {
+    // request-01: deprecation/sunset headers are logged on the error path too.
+    log_deprecation_headers(&response.headers);
+
+    // TS safeReadBody: read failures degrade to "".
+    let body_text = response.collect_text().await.unwrap_or_default();
+    let status = response.status;
+    let status_text = response.status_text.clone();
+    let headers = response.headers.clone();
+
+    let (final_status, final_status_text) = match map_usage_limit_404_with_body(status, &body_text)
+    {
+        Usage404Mapping::Entitlement(entitlement_response) => {
+            // Entitlement errors return the ready-to-use 403 immediately.
+            return ErrorHandlingResult {
+                response: entitlement_response,
+                rate_limit: None,
+                error_body: None,
+            };
+        }
+        Usage404Mapping::RateLimited => (
+            HTTP_STATUS.too_many_requests,
+            "Too Many Requests".to_string(),
+        ),
+        Usage404Mapping::Untouched => (status, status_text),
+    };
+
+    let rate_limit = extract_rate_limit_info(final_status, &headers, &body_text);
+
+    let error_body_raw: Option<Value> = if body_text.is_empty() {
+        None
+    } else {
+        match serde_json::from_str::<Value>(&body_text) {
+            Ok(parsed) => Some(parsed),
+            Err(_) => {
+                let mut fallback = Map::new();
+                fallback.insert("message".to_string(), Value::String(body_text.clone()));
+                Some(Value::Object(fallback))
+            }
+        }
+    };
+
+    let diagnostics = extract_error_diagnostics(&headers, final_status, options);
+    let normalized_error = normalize_error_payload(
+        error_body_raw.as_ref(),
+        &body_text,
+        &final_status_text,
+        final_status,
+        diagnostics.as_ref(),
+    );
+    let error_response = ensure_json_error_response(
+        final_status,
+        &final_status_text,
+        &headers,
+        &normalized_error,
+    );
+
+    if final_status == HTTP_STATUS.unauthorized {
+        log_warn(
+            "Codex upstream returned 401 Unauthorized",
+            diagnostics
+                .as_ref()
+                .map(|diagnostics| Value::Object(diagnostics.clone()))
+                .as_ref(),
+        );
+    }
+
+    let mut log_data = Map::new();
+    log_data.insert("status".to_string(), Value::from(final_status));
+    log_data.insert(
+        "statusText".to_string(),
+        Value::String(final_status_text.clone()),
+    );
+    if let Some(diagnostics) = diagnostics {
+        log_data.insert("diagnostics".to_string(), Value::Object(diagnostics));
+    }
+    log_request(LOG_STAGES.error_response, &log_data);
+
+    ErrorHandlingResult {
+        response: error_response,
+        rate_limit,
+        error_body: Some(normalized_error),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// handleSuccessResponse
+// ---------------------------------------------------------------------------
+
+/// TS `handleSuccessResponse(response, isStreaming, options?)`.
+///
+/// Non-streaming callers get the SSE stream converted to a single JSON body;
+/// streaming callers get the stream as-is with response-id sniffing attached.
+pub async fn handle_success_response(
+    response: StreamResponse,
+    is_streaming: bool,
+    options: ConvertSseOptions,
+) -> Result<StreamResponse, BoxError> {
+    // Check for deprecation headers (RFC 8594).
+    log_deprecation_headers(&response.headers);
+
+    let response_headers = ensure_content_type(&response.headers);
+
+    if !is_streaming {
+        return convert_sse_to_json(response, &response_headers, options).await;
+    }
+
+    Ok(attach_response_id_capture(
+        response,
+        response_headers,
+        options.on_response_id,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use futures::StreamExt;
+    use http::header::HeaderName;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.append(
+                HeaderName::try_from(*name).unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    fn resp(status: u16, status_text: &str, header_pairs: &[(&str, &str)], body: &str) -> StreamResponse {
+        StreamResponse::from_text(status, status_text, headers(header_pairs), body)
+    }
+
+    fn json_resp(status: u16, body: Value) -> StreamResponse {
+        resp(status, "", &[], &stringify_compact(&body))
+    }
+
+    // -- 404 usage-limit / entitlement mapping ------------------------------
+
+    #[tokio::test]
+    async fn maps_usage_limit_404_errors_to_429() {
+        let body = serde_json::json!({
+            "error": { "code": "usage_limit_reached", "message": "limit reached" }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 429);
+        assert_eq!(result.response.status_text, "Too Many Requests");
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["code"], "usage_limit_reached");
+        assert!(result.rate_limit.unwrap().retry_after_ms > 0);
+    }
+
+    #[tokio::test]
+    async fn maps_usage_limit_404_errors_to_429_when_signal_comes_from_error_type() {
+        let body = serde_json::json!({
+            "error": { "type": "usage_limit_reached", "message": "limit reached" }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 429);
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["type"], "usage_limit_reached");
+        assert!(result.rate_limit.unwrap().retry_after_ms > 0);
+    }
+
+    #[tokio::test]
+    async fn maps_usage_limit_404_errors_to_429_when_code_and_type_disagree() {
+        let body = serde_json::json!({
+            "error": {
+                "code": "rate_limit_exceeded",
+                "type": "usage_limit_reached",
+                "message": "limit reached"
+            }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 429);
+        assert!(result.rate_limit.unwrap().retry_after_ms > 0);
+    }
+
+    #[tokio::test]
+    async fn maps_entitlement_style_404_errors_to_403_when_only_type_carries_the_signal() {
+        let body = serde_json::json!({
+            "error": {
+                "code": "not_found",
+                "type": "usage_not_included",
+                "message": "Not included in your plan"
+            }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 403);
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["code"], "usage_not_included");
+        assert!(json["error"]["message"].as_str().unwrap().contains("not included"));
+        assert!(result.rate_limit.is_none());
+        assert!(result.error_body.is_none());
+    }
+
+    #[tokio::test]
+    async fn prioritizes_entitlement_over_rate_limit_when_signals_conflict() {
+        let body = serde_json::json!({
+            "error": {
+                "code": "usage_not_included",
+                "type": "usage_limit_reached",
+                "message": "mixed signals"
+            }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 403);
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn leaves_non_usage_404_errors_unchanged() {
+        let body = serde_json::json!({ "error": { "code": "not_found", "message": "nope" } });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 404);
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["code"], "not_found");
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn maps_usage_not_included_404_to_403_entitlement_error_not_rate_limit() {
+        let body = serde_json::json!({
+            "error": { "code": "usage_not_included", "message": "Usage not included in your plan" }
+        });
+        let result = handle_error_response(json_resp(404, body), None).await;
+        assert_eq!(result.response.status, 403);
+        assert!(result.rate_limit.is_none());
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["type"], "entitlement_error");
+        assert!(
+            json["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("not included in your ChatGPT subscription")
+        );
+    }
+
+    #[tokio::test]
+    async fn does_not_remap_404s_with_free_text_usage_limit_messages() {
+        let result = handle_error_response(
+            resp(404, "", &[], "usage limit exceeded - please try again"),
+            None,
+        )
+        .await;
+        assert_eq!(result.response.status, 404);
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn does_not_remap_404s_with_malformed_json_bodies() {
+        let result = handle_error_response(resp(404, "", &[], "{ invalid json"), None).await;
+        assert_eq!(result.response.status, 404);
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn does_not_remap_empty_404_bodies_to_rate_limits() {
+        let result = handle_error_response(resp(404, "", &[], ""), None).await;
+        assert_eq!(result.response.status, 404);
+        assert!(result.rate_limit.is_none());
+    }
+
+    // -- error normalization -------------------------------------------------
+
+    #[tokio::test]
+    async fn extracts_nested_error_message() {
+        let body = serde_json::json!({
+            "error": { "message": "nested error message", "type": "test_type", "code": "test_code" }
+        });
+        let result = handle_error_response(json_resp(500, body), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "nested error message");
+        assert_eq!(json["error"]["type"], "test_type");
+        assert_eq!(json["error"]["code"], "test_code");
+        // errorBody is the NORMALIZED payload (gotcha 27).
+        assert_eq!(result.error_body.unwrap(), json);
+    }
+
+    #[tokio::test]
+    async fn extracts_top_level_message() {
+        let body = serde_json::json!({ "message": "top-level message" });
+        let result = handle_error_response(json_resp(500, body), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "top-level message");
+    }
+
+    #[tokio::test]
+    async fn uses_trimmed_body_text_when_json_parses_to_non_record() {
+        let result = handle_error_response(resp(500, "", &[], "\"just a string\""), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "\"just a string\"");
+    }
+
+    #[tokio::test]
+    async fn uses_body_text_when_no_structured_error() {
+        let result = handle_error_response(resp(500, "", &[], "plain text error"), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "plain text error");
+    }
+
+    #[tokio::test]
+    async fn uses_status_text_when_body_is_empty() {
+        let result =
+            handle_error_response(resp(500, "Internal Server Error", &[], ""), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "Internal Server Error");
+    }
+
+    #[tokio::test]
+    async fn uses_fallback_message_when_everything_is_empty() {
+        let result = handle_error_response(resp(500, "", &[], ""), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "Request failed");
+    }
+
+    #[tokio::test]
+    async fn handles_numeric_error_codes() {
+        let body = serde_json::json!({ "error": { "message": "error", "code": 12345 } });
+        let result = handle_error_response(json_resp(500, body), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["code"], 12345);
+    }
+
+    #[tokio::test]
+    async fn error_response_forces_json_content_type() {
+        let result = handle_error_response(
+            resp(500, "", &[("content-type", "text/plain")], "boom"),
+            None,
+        )
+        .await;
+        assert_eq!(
+            result.response.headers.get("content-type").unwrap(),
+            "application/json; charset=utf-8"
+        );
+    }
+
+    #[tokio::test]
+    async fn includes_401_diagnostics_from_response_headers() {
+        let body = serde_json::json!({ "error": { "message": "Unauthorized" } });
+        let result = handle_error_response(
+            resp(
+                401,
+                "",
+                &[("cf-ray", "abc123-def"), ("x-request-id", "req_123")],
+                &stringify_compact(&body),
+            ),
+            Some(&ErrorHandlingOptions {
+                request_correlation_id: Some("corr-1".into()),
+                thread_id: Some("thread-1".into()),
+            }),
+        )
+        .await;
+        let json = result.response.json().unwrap();
+        assert!(
+            json["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("codex-multi-auth login")
+        );
+        let diagnostics = &json["error"]["diagnostics"];
+        assert_eq!(diagnostics["cfRay"], "abc123-def");
+        assert_eq!(diagnostics["requestId"], "req_123");
+        assert_eq!(diagnostics["correlationId"], "corr-1");
+        assert_eq!(diagnostics["threadId"], "thread-1");
+        assert_eq!(diagnostics["httpStatus"], 401);
+    }
+
+    #[tokio::test]
+    async fn adds_login_hint_for_all_401_message_branches() {
+        // top-level message
+        let top_level = handle_error_response(
+            resp(
+                401,
+                "Unauthorized",
+                &[],
+                &stringify_compact(&serde_json::json!({ "message": "token invalid" })),
+            ),
+            None,
+        )
+        .await;
+        assert!(
+            top_level.response.json().unwrap()["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("codex-multi-auth login")
+        );
+        // trimmed body text
+        let trimmed =
+            handle_error_response(resp(401, "Unauthorized", &[], "plain auth failure"), None).await;
+        assert!(
+            trimmed.response.json().unwrap()["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("codex-multi-auth login")
+        );
+        // statusText
+        let status_text = handle_error_response(resp(401, "Unauthorized", &[], ""), None).await;
+        assert!(
+            status_text.response.json().unwrap()["error"]["message"]
+                .as_str()
+                .unwrap()
+                .contains("codex-multi-auth login")
+        );
+        // fallback
+        let fallback = handle_error_response(resp(401, "", &[], ""), None).await;
+        assert_eq!(
+            fallback.response.json().unwrap()["error"]["message"],
+            format!("Request failed{LOGIN_HINT_SUFFIX}")
+        );
+    }
+
+    // -- unsupported-model 400 handling --------------------------------------
+
+    #[tokio::test]
+    async fn normalizes_chatgpt_model_not_supported_400_to_actionable_entitlement_error() {
+        let body = serde_json::json!({
+            "detail": "The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account."
+        });
+        let result = handle_error_response(json_resp(400, body), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["type"], "entitlement_error");
+        assert_eq!(
+            json["error"]["code"],
+            "model_not_supported_with_chatgpt_account"
+        );
+        let message = json["error"]["message"].as_str().unwrap();
+        assert!(message.contains("'gpt-5.3-codex'"));
+        assert!(message.contains("CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL"));
+        assert_eq!(json["error"]["unsupported_model"], "gpt-5.3-codex");
+    }
+
+    #[tokio::test]
+    async fn rewrites_normalized_not_currently_available_400_wording_as_entitlement_error() {
+        let result = handle_error_response(
+            resp(
+                400,
+                "",
+                &[],
+                "The model 'gpt-5.3-codex' is not currently available for this chatgpt account.",
+            ),
+            None,
+        )
+        .await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["type"], "entitlement_error");
+        assert_eq!(
+            json["error"]["code"],
+            "model_not_supported_with_chatgpt_account"
+        );
+        assert_eq!(json["error"]["unsupported_model"], "gpt-5.3-codex");
+        assert!(json["error"]["message"].as_str().unwrap().contains("entitlement gate"));
+    }
+
+    #[tokio::test]
+    async fn uses_generic_unsupported_model_placeholder_when_body_has_no_quoted_model() {
+        let body = serde_json::json!({
+            "detail": "model is not supported when using Codex with a ChatGPT account"
+        });
+        let result = handle_error_response(json_resp(400, body), None).await;
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["unsupported_model"], "requested model");
+    }
+
+    // -- rate limit extraction ------------------------------------------------
+
+    #[tokio::test]
+    async fn parses_retry_after_ms_from_body() {
+        let body = serde_json::json!({ "error": { "message": "rate limited", "retry_after_ms": 5000 } });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 5000);
+    }
+
+    #[tokio::test]
+    async fn keeps_retry_after_ms_values_in_milliseconds() {
+        let body = serde_json::json!({ "error": { "message": "rate limited", "retry_after_ms": 5 } });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 5);
+    }
+
+    #[tokio::test]
+    async fn interprets_retry_after_values_as_seconds() {
+        let body = serde_json::json!({ "error": { "message": "rate limited", "retry_after": 5 } });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 5000);
+    }
+
+    #[tokio::test]
+    async fn parses_retry_after_ms_header() {
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("retry-after-ms", "3000")],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 3000);
+    }
+
+    #[tokio::test]
+    async fn parses_retry_after_header_seconds() {
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("retry-after", "10")],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 10_000);
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_retry_after_headers_when_body_retry_values_are_invalid() {
+        let body = serde_json::json!({ "error": { "message": "rate limited", "retry_after_ms": -1 } });
+        let result = handle_error_response(
+            resp(429, "", &[("retry-after-ms", "2500")], &stringify_compact(&body)),
+            None,
+        )
+        .await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 2500);
+    }
+
+    #[tokio::test]
+    async fn handles_invalid_retry_after_header_with_default_fallback() {
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("retry-after", "invalid")],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 60_000);
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_default_retry_window_when_retry_metadata_is_invalid() {
+        let past_unix_seconds = now_ms() / 1000 - 60;
+        let body = serde_json::json!({
+            "error": {
+                "message": "rate limited",
+                "retry_after_ms": "not-a-number",
+                "retry_after": 0,
+                "resets_at": "also-bad",
+            }
+        });
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[
+                    ("retry-after-ms", "NaN"),
+                    ("retry-after", "0"),
+                    ("x-ratelimit-reset", &past_unix_seconds.to_string()),
+                ],
+                &stringify_compact(&body),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 60_000);
+    }
+
+    #[tokio::test]
+    async fn handles_resets_at_in_the_past_with_default_fallback() {
+        let past_timestamp = now_ms() / 1000 - 60;
+        let body = serde_json::json!({
+            "error": { "message": "rate limited", "resets_at": past_timestamp }
+        });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        assert_eq!(result.rate_limit.unwrap().retry_after_ms, 60_000);
+    }
+
+    #[tokio::test]
+    async fn parses_x_ratelimit_reset_unix_seconds_header() {
+        let future_timestamp = now_ms() / 1000 + 60;
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("x-ratelimit-reset", &future_timestamp.to_string())],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        let retry_after_ms = result.rate_limit.unwrap().retry_after_ms;
+        assert!(retry_after_ms > 0);
+        assert!(retry_after_ms <= 60_000);
+    }
+
+    #[tokio::test]
+    async fn parses_resets_at_in_milliseconds_format_from_body() {
+        let future_timestamp_ms = now_ms() + 30_000;
+        let body = serde_json::json!({
+            "error": { "message": "rate limited", "resets_at": future_timestamp_ms }
+        });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        let retry_after_ms = result.rate_limit.unwrap().retry_after_ms;
+        assert!(retry_after_ms > 0);
+        assert!(retry_after_ms <= 30_000);
+    }
+
+    #[tokio::test]
+    async fn caps_retry_after_ms_body_values_at_7_days() {
+        let body = serde_json::json!({
+            "error": { "message": "rate limited", "retry_after_ms": 10 * 24 * 60 * 60 * 1000 }
+        });
+        let result = handle_error_response(json_resp(429, body), None).await;
+        assert_eq!(
+            result.rate_limit.unwrap().retry_after_ms,
+            7 * 24 * 60 * 60 * 1000
+        );
+    }
+
+    #[tokio::test]
+    async fn caps_retry_after_ms_header_values_at_7_days() {
+        let ten_days_ms = (10 * 24 * 60 * 60 * 1000i64).to_string();
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("retry-after-ms", &ten_days_ms)],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(
+            result.rate_limit.unwrap().retry_after_ms,
+            7 * 24 * 60 * 60 * 1000
+        );
+    }
+
+    #[tokio::test]
+    async fn caps_reset_timestamp_hints_at_7_days() {
+        let reset_at_seconds = now_ms() / 1000 + 10 * 24 * 60 * 60;
+        let result = handle_error_response(
+            resp(
+                429,
+                "",
+                &[("x-ratelimit-reset", &reset_at_seconds.to_string())],
+                &stringify_compact(&serde_json::json!({ "error": { "message": "rate limited" } })),
+            ),
+            None,
+        )
+        .await;
+        assert_eq!(
+            result.rate_limit.unwrap().retry_after_ms,
+            7 * 24 * 60 * 60 * 1000
+        );
+    }
+
+    #[tokio::test]
+    async fn handles_429_with_entitlement_code_or_text_as_non_rate_limit() {
+        let by_code =
+            serde_json::json!({ "error": { "code": "usage_not_included", "message": "Not included" } });
+        let result = handle_error_response(json_resp(429, by_code), None).await;
+        assert_eq!(result.response.status, 429);
+        assert!(result.rate_limit.is_none());
+
+        let by_text =
+            serde_json::json!({ "error": { "message": "Usage not included in your plan" } });
+        let result = handle_error_response(json_resp(429, by_text), None).await;
+        assert_eq!(result.response.status, 429);
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn does_not_treat_non_429_rate_limit_text_as_a_cooldown_signal() {
+        let result = handle_error_response(
+            resp(500, "", &[], "rate_limit_exceeded - upstream overloaded"),
+            None,
+        )
+        .await;
+        assert_eq!(result.response.status, 500);
+        assert!(result.rate_limit.is_none());
+    }
+
+    #[tokio::test]
+    async fn body_read_failures_degrade_to_the_request_failed_payload() {
+        // safeReadBody catch: an erroring body stream reads as "".
+        let failing_body: crate::response_handler::BodyStream =
+            futures::stream::once(async { Err::<bytes::Bytes, BoxError>("boom".into()) }).boxed();
+        let response = StreamResponse::new(500, "", HeaderMap::new(), Some(failing_body));
+        let result = handle_error_response(response, None).await;
+        assert_eq!(result.response.status, 500);
+        let json = result.response.json().unwrap();
+        assert_eq!(json["error"]["message"], "Request failed");
+    }
+
+    // -- deterministic parseRetryAfterMs internals ---------------------------
+
+    /// Fixed "now": 2026-04-05T00:00:00.000Z.
+    const NOW_MS: i64 = 1_775_347_200_000;
+
+    #[test]
+    fn now_constant_matches_the_ts_fake_clock() {
+        let expected = chrono::DateTime::parse_from_rfc3339("2026-04-05T00:00:00.000Z")
+            .unwrap()
+            .timestamp_millis();
+        assert_eq!(NOW_MS, expected);
+    }
+
+    #[test]
+    fn parses_retry_after_header_http_date() {
+        let headers = headers(&[("retry-after", "Sun, 05 Apr 2026 00:01:30 GMT")]);
+        assert_eq!(
+            parse_retry_after_ms_at(&headers, "", None, NOW_MS),
+            Some(90_000)
+        );
+    }
+
+    #[test]
+    fn prefers_the_longest_reset_hint_across_headers() {
+        let headers = headers(&[
+            ("x-codex-primary-reset-after-seconds", "60"),
+            ("x-codex-secondary-reset-at", "Sun, 05 Apr 2026 01:30:00 GMT"),
+        ]);
+        assert_eq!(
+            parse_retry_after_ms_at(&headers, "", None, NOW_MS),
+            Some(90 * 60 * 1000)
+        );
+    }
+
+    #[test]
+    fn millisecond_epoch_reset_headers_skip_the_seconds_multiplier() {
+        let reset_ms = NOW_MS + 45_000;
+        let headers = headers(&[("x-ratelimit-reset", &reset_ms.to_string())]);
+        assert_eq!(
+            parse_retry_after_ms_at(&headers, "", None, NOW_MS),
+            Some(45_000)
+        );
+    }
+
+    #[test]
+    fn parses_natural_language_retry_durations() {
+        assert_eq!(
+            parse_retry_after_text_ms_at(
+                "You've hit your usage limit. Please try again in 2 hours.",
+                NOW_MS
+            ),
+            Some(2 * 60 * 60 * 1000)
+        );
+        assert_eq!(
+            parse_retry_after_text_ms_at("retry again in 45 seconds", NOW_MS),
+            Some(45_000)
+        );
+        assert_eq!(
+            parse_retry_after_text_ms_at("try again in 1 day", NOW_MS),
+            Some(24 * 60 * 60 * 1000)
+        );
+        assert_eq!(parse_retry_after_text_ms_at("no hints here", NOW_MS), None);
+    }
+
+    #[test]
+    fn parses_natural_language_clock_times_in_local_time() {
+        use chrono::TimeZone;
+        // "today" at 04:00 LOCAL (DST transitions happen before 04:00, so the
+        // 04:00 → 06:26 window is transition-free).
+        let date = chrono::Local::now().date_naive();
+        let four_am = chrono::Local
+            .from_local_datetime(&date.and_hms_opt(4, 0, 0).unwrap())
+            .earliest()
+            .unwrap();
+        let now = four_am.timestamp_millis();
+
+        let parsed = parse_retry_after_text_ms_at(
+            "You've hit your usage limit. To get more access now, send a request to your admin or try again at 6:26 AM.",
+            now,
+        );
+        assert_eq!(parsed, Some((2 * 60 + 26) * 60 * 1000));
+
+        // A clock time already past rolls to the next day.
+        let rolled = parse_retry_after_text_ms_at("try again at 3:00 AM", now).unwrap();
+        assert!(rolled > 0);
+        assert!(rolled <= 24 * 60 * 60 * 1000);
+    }
+
+    #[test]
+    fn seven_day_clamp_applies_to_every_source() {
+        assert_eq!(
+            clamp_rate_limit_delay_ms(10.0 * 24.0 * 60.0 * 60.0 * 1000.0),
+            Some(MAX_RATE_LIMIT_DELAY_MS)
+        );
+        assert_eq!(clamp_rate_limit_delay_ms(0.0), None);
+        assert_eq!(clamp_rate_limit_delay_ms(-5.0), None);
+        assert_eq!(clamp_rate_limit_delay_ms(f64::NAN), None);
+        assert_eq!(
+            parse_retry_after_text_ms_at("try again in 30 days", NOW_MS),
+            Some(MAX_RATE_LIMIT_DELAY_MS)
+        );
+    }
+
+    // -- handleSuccessResponse -----------------------------------------------
+
+    #[tokio::test]
+    async fn returns_stream_as_is_for_streaming_requests() {
+        let response = resp(200, "", &[], "stream body");
+        let mut result = handle_success_response(response, true, ConvertSseOptions::default())
+            .await
+            .unwrap();
+        assert_eq!(result.status, 200);
+        assert_eq!(result.collect_text().await.unwrap(), "stream body");
+    }
+
+    #[tokio::test]
+    async fn captures_response_ids_from_streaming_sse_without_rewriting_the_stream() {
+        let sse = "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_stream_123\"}}\n\n\
+data: {\"type\":\"response.done\",\"response\":{\"id\":\"resp_stream_123\"}}\n\n";
+        let response = resp(
+            200,
+            "",
+            &[("content-type", "text/event-stream")],
+            sse,
+        );
+        let seen: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
+        let seen_in_callback = Arc::clone(&seen);
+        let mut result = handle_success_response(
+            response,
+            true,
+            ConvertSseOptions {
+                on_response_id: Some(Arc::new(move |id| {
+                    assert_eq!(id, "resp_stream_123");
+                    seen_in_callback.fetch_add(1, Ordering::SeqCst);
+                })),
+                stream_stall_timeout_ms: None,
+            },
+        )
+        .await
+        .unwrap();
+
+        let text = result.collect_text().await.unwrap();
+        assert!(text.contains("\"resp_stream_123\""));
+        assert_eq!(seen.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn converts_sse_to_json_for_non_streaming_requests() {
+        let sse = "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_1\",\"output\":[]}}\n\n";
+        let response = resp(200, "OK", &[("content-type", "text/event-stream")], sse);
+        let mut result = handle_success_response(response, false, ConvertSseOptions::default())
+            .await
+            .unwrap();
+        assert_eq!(
+            result.headers.get("content-type").unwrap(),
+            "application/json; charset=utf-8"
+        );
+        let text = result.collect_text().await.unwrap();
+        let json: Value = serde_json::from_str(&text).unwrap();
+        assert_eq!(json["id"], "resp_1");
+    }
+
+    // -- transformRequestForCodex (sibling seam injected) ---------------------
+
+    struct DepsFixture {
+        instruction_calls: Arc<AtomicUsize>,
+    }
+
+    impl DepsFixture {
+        fn new() -> Self {
+            DepsFixture {
+                instruction_calls: Arc::new(AtomicUsize::new(0)),
+            }
+        }
+    }
+
+    fn passthrough_transform(
+        args: TransformRequestBodyArgs,
+    ) -> BoxFuture<'static, Result<Map<String, Value>, BoxError>> {
+        Box::pin(async move {
+            let mut body = args.body;
+            body.insert(
+                "instructions".to_string(),
+                Value::String(args.codex_instructions),
+            );
+            body.insert("stream".to_string(), Value::Bool(true));
+            Ok(body)
+        })
+    }
+
+    fn trim_when_fast(
+        _body: &Map<String, Value>,
+        fast_session: bool,
+        _strategy: FastSessionStrategy,
+        max_items: f64,
+    ) -> Option<DeferredFastSessionInputTrim> {
+        fast_session.then_some(DeferredFastSessionInputTrim {
+            max_items,
+            prefer_latest_user_only: false,
+        })
+    }
+
+    async fn run_transform(
+        init: Option<&RequestInit>,
+        parsed_body: Option<&Map<String, Value>>,
+        options: TransformRequestForCodexOptions,
+        transform: TransformRequestBodyFn<'_>,
+        fixture: &DepsFixture,
+    ) -> Result<Option<TransformRequestForCodexResult>, BoxError> {
+        let calls = Arc::clone(&fixture.instruction_calls);
+        let get_instructions = move |_model: &str| -> BoxFuture<'static, Result<String, BoxError>> {
+            calls.fetch_add(1, Ordering::SeqCst);
+            Box::pin(async { Ok("TEST INSTRUCTIONS".to_string()) })
+        };
+        let deps = TransformRequestForCodexDeps {
+            resolve_fast_session_input_trim: &trim_when_fast,
+            get_codex_instructions: &get_instructions,
+            transform_request_body: transform,
+        };
+        transform_request_for_codex(
+            init,
+            "https://example.com",
+            &UserConfig::default(),
+            true,
+            parsed_body,
+            options,
+            &deps,
+        )
+        .await
+    }
+
+    fn text_init(body: &str) -> RequestInit {
+        RequestInit {
+            method: Some("POST".into()),
+            headers: None,
+            body: Some(BodyInit::Text(body.to_string())),
+        }
+    }
+
+    #[tokio::test]
+    async fn returns_none_when_init_and_parsed_body_are_missing() {
+        let fixture = DepsFixture::new();
+        let result = run_transform(
+            None,
+            None,
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+
+        // init without a body
+        let init = RequestInit::default();
+        let result = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+        assert_eq!(fixture.instruction_calls.load(Ordering::SeqCst), 0);
+    }
+
+    #[tokio::test]
+    async fn returns_none_when_init_body_is_not_a_string() {
+        let fixture = DepsFixture::new();
+        let init = RequestInit {
+            body: Some(BodyInit::Bytes(b"test".to_vec())),
+            ..Default::default()
+        };
+        let result = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[tokio::test]
+    async fn returns_none_when_parsed_body_is_empty_and_init_body_is_unavailable() {
+        let fixture = DepsFixture::new();
+        let init = RequestInit {
+            body: Some(BodyInit::Bytes(b"ignored".to_vec())),
+            ..Default::default()
+        };
+        let empty = Map::new();
+        let result = run_transform(
+            Some(&init),
+            Some(&empty),
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[tokio::test]
+    async fn returns_none_and_logs_when_json_parsing_fails() {
+        let fixture = DepsFixture::new();
+        let init = text_init("not valid json {{{");
+        let result = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+        assert_eq!(fixture.instruction_calls.load(Ordering::SeqCst), 0);
+    }
+
+    #[tokio::test]
+    async fn transforms_request_body_successfully() {
+        let fixture = DepsFixture::new();
+        let init = text_init(&stringify_compact(
+            &serde_json::json!({ "model": "gpt-5.1", "input": "Hello" }),
+        ));
+        let result = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap()
+        .unwrap();
+
+        assert_eq!(result.body.get("model"), Some(&Value::String("gpt-5.1".into())));
+        assert_eq!(
+            result.body.get("instructions"),
+            Some(&Value::String("TEST INSTRUCTIONS".into()))
+        );
+        let updated_body = result.updated_init.body.unwrap();
+        let text = updated_body.as_text().unwrap();
+        let round_trip: Value = serde_json::from_str(text).unwrap();
+        assert_eq!(round_trip["model"], "gpt-5.1");
+        assert_eq!(fixture.instruction_calls.load(Ordering::SeqCst), 1);
+        assert!(result.deferred_fast_session_input_trim.is_none());
+    }
+
+    #[tokio::test]
+    async fn transforms_parsed_body_when_init_is_missing_or_binary() {
+        let fixture = DepsFixture::new();
+        let parsed: Map<String, Value> = serde_json::from_value(serde_json::json!({
+            "model": "gpt-5.3-codex",
+            "input": [{ "type": "message", "role": "user", "content": "hi" }],
+        }))
+        .unwrap();
+
+        let result = run_transform(
+            None,
+            Some(&parsed),
+            TransformRequestForCodexOptions {
+                fast_session: true,
+                fast_session_strategy: FastSessionStrategy::Always,
+                fast_session_max_input_items: 12.0,
+                ..Default::default()
+            },
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap()
+        .unwrap();
+        assert_eq!(
+            result.body.get("model"),
+            Some(&Value::String("gpt-5.3-codex".into()))
+        );
+        assert!(result.updated_init.body.unwrap().as_text().is_some());
+    }
+
+    #[tokio::test]
+    async fn rethrows_background_mode_compatibility_errors() {
+        let fixture = DepsFixture::new();
+        let background_rejecting = |_args: TransformRequestBodyArgs| -> BoxFuture<
+            'static,
+            Result<Map<String, Value>, BoxError>,
+        > {
+            Box::pin(async {
+                Err::<Map<String, Value>, BoxError>(
+                    "Responses background mode is disabled. Enable pluginConfig.backgroundResponses or CODEX_AUTH_BACKGROUND_RESPONSES=1 to opt in."
+                        .into(),
+                )
+            })
+        };
+        let init = text_init(&stringify_compact(&serde_json::json!({
+            "model": "gpt-5.4",
+            "background": true,
+            "input": [{ "type": "message", "role": "user", "content": "hello" }],
+        })));
+        let error = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &background_rejecting,
+            &fixture,
+        )
+        .await
+        .unwrap_err();
+        assert!(error.to_string().starts_with("Responses background mode"));
+    }
+
+    #[tokio::test]
+    async fn other_transform_errors_degrade_to_none() {
+        let fixture = DepsFixture::new();
+        let failing = |_args: TransformRequestBodyArgs| -> BoxFuture<
+            'static,
+            Result<Map<String, Value>, BoxError>,
+        > { Box::pin(async { Err::<Map<String, Value>, BoxError>("kaboom".into()) }) };
+        let init = text_init(&stringify_compact(&serde_json::json!({ "model": "gpt-5.1" })));
+        let result = run_transform(
+            Some(&init),
+            None,
+            TransformRequestForCodexOptions::default(),
+            &failing,
+            &fixture,
+        )
+        .await
+        .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[tokio::test]
+    async fn defers_fast_session_trim_only_for_non_background_requests() {
+        let fixture = DepsFixture::new();
+        let options = TransformRequestForCodexOptions {
+            fast_session: true,
+            fast_session_strategy: FastSessionStrategy::Always,
+            fast_session_max_input_items: 1.0,
+            defer_fast_session_input_trimming: true,
+            ..Default::default()
+        };
+
+        // Non-background: the deferred directive is handed back.
+        let init = text_init(&stringify_compact(&serde_json::json!({
+            "model": "gpt-5.4",
+            "input": [{ "type": "message", "role": "user", "content": "hello" }],
+        })));
+        let result = run_transform(
+            Some(&init),
+            None,
+            options,
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap()
+        .unwrap();
+        assert_eq!(
+            result.deferred_fast_session_input_trim,
+            Some(DeferredFastSessionInputTrim {
+                max_items: 1.0,
+                prefer_latest_user_only: false,
+            })
+        );
+
+        // Background=true suppresses the deferred trim.
+        let init = text_init(&stringify_compact(&serde_json::json!({
+            "model": "gpt-5.4",
+            "background": true,
+            "input": [
+                { "id": "msg_1", "type": "message", "role": "user", "content": "hello" },
+                { "id": "msg_2", "type": "message", "role": "assistant", "content": "hi" },
+            ],
+        })));
+        let result = run_transform(
+            Some(&init),
+            None,
+            options,
+            &passthrough_transform,
+            &fixture,
+        )
+        .await
+        .unwrap()
+        .unwrap();
+        assert_eq!(result.body.get("background"), Some(&Value::Bool(true)));
+        assert!(result.deferred_fast_session_input_trim.is_none());
+    }
+
+    // -- misc helpers ---------------------------------------------------------
+
+    #[test]
+    fn js_parse_int_matches_parse_int_semantics() {
+        assert_eq!(js_parse_int("2500"), Some(2500.0));
+        assert_eq!(js_parse_int("  42abc"), Some(42.0));
+        assert_eq!(js_parse_int("-7"), Some(-7.0));
+        assert_eq!(js_parse_int("+8"), Some(8.0));
+        assert_eq!(js_parse_int("abc"), None);
+        assert_eq!(js_parse_int(""), None);
+        assert_eq!(js_parse_int("Sun, 05 Apr 2026 00:01:30 GMT"), None);
+    }
+
+    #[test]
+    fn shared_client_is_a_singleton() {
+        let first = shared_client() as *const reqwest::Client;
+        let second = shared_client() as *const reqwest::Client;
+        assert_eq!(first, second);
+    }
+}
diff --git a/crates/request/src/headers.rs b/crates/request/src/headers.rs
new file mode 100644
index 000000000..662c0f46a
--- /dev/null
+++ b/crates/request/src/headers.rs
@@ -0,0 +1,350 @@
+//! Port of `lib/request/headers.ts` — Codex request-header construction.
+//!
+//! Behavior source: spec 06 §8 + the TS source (authority). `fetch_helpers`
+//! re-exports this module's public surface, mirroring the TS re-export
+//! contract.
+//!
+//! Dual-call contract: the TS `createCodexHeaders` is overloaded
+//! (named-params object OR positional args) and throws
+//! `TypeError("createCodexHeaders requires accountId and accessToken")` when
+//! either credential is missing/empty. Rust has no runtime overloading, so
+//! both entry points exist as separate functions sharing one validation path
+//! that surfaces the frozen message as an [`ArgError`] (the workspace-wide
+//! `TypeError` analogue, ARCHITECTURE §8.2).
+
+use cma_core::constants::{OPENAI_HEADERS, OPENAI_HEADER_VALUES};
+use cma_core::logger::log_warn;
+use http::header::{HeaderMap, HeaderName, HeaderValue};
+use serde_json::{Value, json};
+
+/// Plain argument error carrying a frozen TS `TypeError` message
+/// (deliberately NOT a `CodexError` — ARCHITECTURE §8.2).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ArgError {
+    message: String,
+}
+
+impl ArgError {
+    /// Create an [`ArgError`] with the given frozen message.
+    pub fn new(message: impl Into<String>) -> Self {
+        ArgError {
+            message: message.into(),
+        }
+    }
+
+    /// The frozen message text.
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl std::fmt::Display for ArgError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ArgError {}
+
+/// TS `CreateCodexHeadersOptions`.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct CreateCodexHeadersOptions {
+    pub model: Option<String>,
+    pub prompt_cache_key: Option<String>,
+}
+
+/// TS `CreateCodexHeadersParams` (named-parameter call form).
+#[derive(Debug, Clone, Default)]
+pub struct CreateCodexHeadersParams {
+    pub init_headers: Option<HeaderMap>,
+    pub account_id: String,
+    pub access_token: String,
+    pub opts: Option<CreateCodexHeadersOptions>,
+}
+
+/// Named-parameter form of `createCodexHeaders`.
+pub fn create_codex_headers(params: &CreateCodexHeadersParams) -> Result<HeaderMap, ArgError> {
+    create_codex_headers_positional(
+        params.init_headers.as_ref(),
+        &params.account_id,
+        &params.access_token,
+        params.opts.as_ref(),
+    )
+}
+
+/// Positional form of `createCodexHeaders`.
+///
+/// Construction order (exact TS parity):
+/// 1. delete `x-api-key`;
+/// 2. `Authorization: Bearer {accessToken}`;
+/// 3. `chatgpt-account-id: {accountId}`;
+/// 4. `OpenAI-Beta: responses=experimental`;
+/// 5. `originator: codex_cli_rs`;
+/// 6. if `opts.promptCacheKey` (truthy — empty string counts as absent): set
+///    BOTH `conversation_id` and `session_id` to it; else DELETE both;
+/// 7. `accept: text/event-stream`.
+pub fn create_codex_headers_positional(
+    init_headers: Option<&HeaderMap>,
+    account_id: &str,
+    access_token: &str,
+    opts: Option<&CreateCodexHeadersOptions>,
+) -> Result<HeaderMap, ArgError> {
+    if account_id.is_empty() || access_token.is_empty() {
+        return Err(ArgError::new(
+            "createCodexHeaders requires accountId and accessToken",
+        ));
+    }
+
+    let mut headers = init_headers.cloned().unwrap_or_default();
+    headers.remove("x-api-key");
+    set_header(
+        &mut headers,
+        "authorization",
+        &format!("Bearer {access_token}"),
+    )?;
+    set_header(&mut headers, OPENAI_HEADERS.account_id, account_id)?;
+    set_header(
+        &mut headers,
+        OPENAI_HEADERS.beta,
+        OPENAI_HEADER_VALUES.beta_responses,
+    )?;
+    set_header(
+        &mut headers,
+        OPENAI_HEADERS.originator,
+        OPENAI_HEADER_VALUES.originator_codex,
+    )?;
+
+    let cache_key = opts
+        .and_then(|o| o.prompt_cache_key.as_deref())
+        .filter(|key| !key.is_empty());
+    match cache_key {
+        Some(key) => {
+            set_header(&mut headers, OPENAI_HEADERS.conversation_id, key)?;
+            set_header(&mut headers, OPENAI_HEADERS.session_id, key)?;
+        }
+        None => {
+            headers.remove(OPENAI_HEADERS.conversation_id);
+            headers.remove(OPENAI_HEADERS.session_id);
+        }
+    }
+    set_header(&mut headers, "accept", "text/event-stream")?;
+    Ok(headers)
+}
+
+/// `headers.set(...)` analogue: replaces every existing value for the name.
+/// Invalid header material maps to the closest `TypeError` analogue (the TS
+/// `Headers.set` would throw a `TypeError` for invalid bytes as well).
+fn set_header(headers: &mut HeaderMap, name: &str, value: &str) -> Result<(), ArgError> {
+    let name = HeaderName::try_from(name).map_err(|_| ArgError::new("Invalid header name"))?;
+    let value = HeaderValue::from_str(value).map_err(|_| ArgError::new("Invalid header value"))?;
+    headers.insert(name, value);
+    Ok(())
+}
+
+/// Log RFC 8594 `Deprecation`/`Sunset` headers if present. Shared by the
+/// success and error response handlers so a sunset notice is surfaced
+/// regardless of status (request-01).
+pub fn log_deprecation_headers(headers: &HeaderMap) {
+    let deprecation = header_value_or_null(headers, "deprecation");
+    let sunset = header_value_or_null(headers, "sunset");
+    if deprecation != Value::Null || sunset != Value::Null {
+        log_warn(
+            "API deprecation notice",
+            Some(&json!({ "deprecation": deprecation, "sunset": sunset })),
+        );
+    }
+}
+
+fn header_value_or_null(headers: &HeaderMap, name: &str) -> Value {
+    match headers.get(name) {
+        Some(value) => Value::String(String::from_utf8_lossy(value.as_bytes()).into_owned()),
+        None => Value::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const ACCOUNT_ID: &str = "test-account-123";
+    const ACCESS_TOKEN: &str = "test-access-token";
+
+    fn get<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+        headers.get(name).and_then(|v| v.to_str().ok())
+    }
+
+    #[test]
+    fn creates_headers_with_all_required_fields_when_cache_key_provided() {
+        let headers = create_codex_headers_positional(
+            None,
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: Some("gpt-5-codex".into()),
+                prompt_cache_key: Some("session-1".into()),
+            }),
+        )
+        .unwrap();
+
+        assert_eq!(
+            get(&headers, "authorization"),
+            Some(format!("Bearer {ACCESS_TOKEN}").as_str())
+        );
+        assert_eq!(get(&headers, OPENAI_HEADERS.account_id), Some(ACCOUNT_ID));
+        assert_eq!(
+            get(&headers, OPENAI_HEADERS.beta),
+            Some(OPENAI_HEADER_VALUES.beta_responses)
+        );
+        assert_eq!(
+            get(&headers, OPENAI_HEADERS.originator),
+            Some(OPENAI_HEADER_VALUES.originator_codex)
+        );
+        assert_eq!(get(&headers, OPENAI_HEADERS.session_id), Some("session-1"));
+        assert_eq!(
+            get(&headers, OPENAI_HEADERS.conversation_id),
+            Some("session-1")
+        );
+        assert_eq!(get(&headers, "accept"), Some("text/event-stream"));
+    }
+
+    #[test]
+    fn removes_x_api_key_header() {
+        let mut init = HeaderMap::new();
+        init.insert("x-api-key", "should-be-removed".parse().unwrap());
+        let headers = create_codex_headers_positional(
+            Some(&init),
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: Some("gpt-5".into()),
+                prompt_cache_key: Some("session-2".into()),
+            }),
+        )
+        .unwrap();
+        assert!(!headers.contains_key("x-api-key"));
+    }
+
+    #[test]
+    fn preserves_other_existing_headers() {
+        let mut init = HeaderMap::new();
+        init.insert("content-type", "application/json".parse().unwrap());
+        let headers = create_codex_headers_positional(
+            Some(&init),
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: Some("gpt-5".into()),
+                prompt_cache_key: Some("session-3".into()),
+            }),
+        )
+        .unwrap();
+        assert_eq!(get(&headers, "content-type"), Some("application/json"));
+    }
+
+    #[test]
+    fn uses_prompt_cache_key_for_both_conversation_and_session_ids() {
+        let key = "ses_abc123";
+        let headers = create_codex_headers_positional(
+            None,
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: None,
+                prompt_cache_key: Some(key.into()),
+            }),
+        )
+        .unwrap();
+        assert_eq!(get(&headers, OPENAI_HEADERS.conversation_id), Some(key));
+        assert_eq!(get(&headers, OPENAI_HEADERS.session_id), Some(key));
+    }
+
+    #[test]
+    fn does_not_set_conversation_or_session_headers_without_cache_key() {
+        let headers = create_codex_headers_positional(
+            None,
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: Some("gpt-5".into()),
+                prompt_cache_key: None,
+            }),
+        )
+        .unwrap();
+        assert!(headers.get(OPENAI_HEADERS.conversation_id).is_none());
+        assert!(headers.get(OPENAI_HEADERS.session_id).is_none());
+    }
+
+    #[test]
+    fn deletes_stale_conversation_and_session_headers_without_cache_key() {
+        // Spec 06 gotcha 18: don't leave stale values from the incoming init.
+        let mut init = HeaderMap::new();
+        init.insert(OPENAI_HEADERS.conversation_id, "stale".parse().unwrap());
+        init.insert(OPENAI_HEADERS.session_id, "stale".parse().unwrap());
+        let headers =
+            create_codex_headers_positional(Some(&init), ACCOUNT_ID, ACCESS_TOKEN, None).unwrap();
+        assert!(headers.get(OPENAI_HEADERS.conversation_id).is_none());
+        assert!(headers.get(OPENAI_HEADERS.session_id).is_none());
+    }
+
+    #[test]
+    fn empty_prompt_cache_key_is_treated_as_absent() {
+        // TS truthiness: `if (cacheKey)` — "" falls to the delete branch.
+        let headers = create_codex_headers_positional(
+            None,
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: None,
+                prompt_cache_key: Some(String::new()),
+            }),
+        )
+        .unwrap();
+        assert!(headers.get(OPENAI_HEADERS.conversation_id).is_none());
+        assert!(headers.get(OPENAI_HEADERS.session_id).is_none());
+    }
+
+    #[test]
+    fn named_parameter_form_matches_positional_form() {
+        let positional = create_codex_headers_positional(
+            None,
+            ACCOUNT_ID,
+            ACCESS_TOKEN,
+            Some(&CreateCodexHeadersOptions {
+                model: Some("gpt-5".into()),
+                prompt_cache_key: Some("session-named".into()),
+            }),
+        )
+        .unwrap();
+        let named = create_codex_headers(&CreateCodexHeadersParams {
+            init_headers: None,
+            account_id: ACCOUNT_ID.into(),
+            access_token: ACCESS_TOKEN.into(),
+            opts: Some(CreateCodexHeadersOptions {
+                model: Some("gpt-5".into()),
+                prompt_cache_key: Some("session-named".into()),
+            }),
+        })
+        .unwrap();
+        assert_eq!(positional, named);
+        assert!(!named.contains_key("x-api-key"));
+    }
+
+    #[test]
+    fn missing_credentials_yield_frozen_type_error_message() {
+        let err = create_codex_headers_positional(None, "", ACCESS_TOKEN, None).unwrap_err();
+        assert_eq!(
+            err.message(),
+            "createCodexHeaders requires accountId and accessToken"
+        );
+        let err = create_codex_headers_positional(None, ACCOUNT_ID, "", None).unwrap_err();
+        assert_eq!(
+            err.message(),
+            "createCodexHeaders requires accountId and accessToken"
+        );
+        let err = create_codex_headers(&CreateCodexHeadersParams::default()).unwrap_err();
+        assert_eq!(
+            err.message(),
+            "createCodexHeaders requires accountId and accessToken"
+        );
+    }
+}
diff --git a/crates/request/src/input_utils.rs b/crates/request/src/input_utils.rs
new file mode 100644
index 000000000..0c3b40f46
--- /dev/null
+++ b/crates/request/src/input_utils.rs
@@ -0,0 +1,912 @@
+//! Port of `lib/request/helpers/input-utils.ts` — input-list surgery
+//! (spec 06 §3): host-prompt stripping, orphaned tool-output conversion, and
+//! missing-tool-output injection.
+//!
+//! All functions are pure; items are the permissive
+//! [`cma_core::types::InputItem`] model (unknown keys ride in `extra`).
+
+use cma_core::types::InputItem;
+use serde_json::{Map, Value, json};
+
+/// TS `HOST_PROMPT_SIGNATURES` — already lowercased (the TS module lowercases
+/// them at init).
+const HOST_PROMPT_SIGNATURES: [&str; 5] = [
+    "you are a coding agent running in the codex",
+    "you are codex, an agent",
+    "you are codex, an interactive cli agent",
+    "you are codex, an interactive cli tool",
+    "you are codex, the best coding agent on the planet",
+];
+
+/// TS `HOST_CONTEXT_MARKERS` — already lowercased.
+const HOST_CONTEXT_MARKERS: [&str; 4] = [
+    "here is some useful information about the environment you are running in:",
+    "<env>",
+    "instructions from:",
+    "<instructions>",
+];
+
+/// TS `getContentText` — string content as-is; array content joins the `text`
+/// of parts with `type === "input_text"` and a truthy (non-empty string)
+/// `text` with `"\n"`; anything else → `""`.
+pub fn get_content_text(item: &InputItem) -> String {
+    match &item.content {
+        Some(Value::String(text)) => text.clone(),
+        Some(Value::Array(parts)) => parts
+            .iter()
+            .filter_map(|part| {
+                let obj = part.as_object()?;
+                if obj.get("type").and_then(Value::as_str) != Some("input_text") {
+                    return None;
+                }
+                match obj.get("text") {
+                    Some(Value::String(text)) if !text.is_empty() => Some(text.clone()),
+                    _ => None,
+                }
+            })
+            .collect::<Vec<_>>()
+            .join("\n"),
+        _ => String::new(),
+    }
+}
+
+/// TS `replaceContentText` — string content stays a string; array content
+/// becomes `[{type:"input_text", text}]`; the (unreachable in practice)
+/// fallback also writes a plain string.
+fn replace_content_text(mut item: InputItem, content_text: &str) -> InputItem {
+    item.content = match &item.content {
+        Some(Value::Array(_)) => Some(json!([{ "type": "input_text", "text": content_text }])),
+        _ => Some(Value::String(content_text.to_string())),
+    };
+    item
+}
+
+/// ASCII case-insensitive substring search returning the byte index in
+/// `haystack`. All host-context markers are pure ASCII, so the returned index
+/// is always a valid char boundary of the ORIGINAL string (the TS code
+/// lowercases the whole content and indexes into that instead; for ASCII
+/// markers the two are equivalent).
+fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option<usize> {
+    let haystack_bytes = haystack.as_bytes();
+    let needle_bytes = needle.as_bytes();
+    if needle_bytes.is_empty() || needle_bytes.len() > haystack_bytes.len() {
+        return None;
+    }
+    (0..=haystack_bytes.len() - needle_bytes.len()).find(|&index| {
+        haystack_bytes[index..index + needle_bytes.len()].eq_ignore_ascii_case(needle_bytes)
+    })
+}
+
+/// TS `extractHostContext` — the slice from the EARLIEST context marker,
+/// `trimStart`ed; `None` when no marker is present.
+fn extract_host_context(content_text: &str) -> Option<String> {
+    let earliest = HOST_CONTEXT_MARKERS
+        .iter()
+        .filter_map(|marker| find_ascii_case_insensitive(content_text, marker))
+        .min()?;
+    Some(content_text[earliest..].trim_start().to_string())
+}
+
+/// TS `isHostSystemPrompt`.
+///
+/// Role must be exactly `"developer"` or `"system"` (case-sensitive, TS
+/// parity). With a non-empty `cached_prompt`: exact trimmed match, OR content
+/// starts with the cached prompt, OR first-200-chars equality — any hit wins.
+/// Regardless of the cached prompt, the lowercased/trim-started content
+/// starting with one of the known host-prompt signatures also matches.
+pub fn is_host_system_prompt(item: &InputItem, cached_prompt: Option<&str>) -> bool {
+    let is_system_role = matches!(item.role.as_deref(), Some("developer") | Some("system"));
+    if !is_system_role {
+        return false;
+    }
+
+    let content_text = get_content_text(item);
+    if content_text.is_empty() {
+        return false;
+    }
+
+    if let Some(cached) = cached_prompt.filter(|cached| !cached.is_empty()) {
+        let content_trimmed = content_text.trim();
+        let cached_trimmed = cached.trim();
+        if content_trimmed == cached_trimmed {
+            return true;
+        }
+        if content_trimmed.starts_with(cached_trimmed) {
+            return true;
+        }
+        // TS `substring(0, 200)` — first 200 chars of each side compared.
+        let content_prefix: String = content_trimmed.chars().take(200).collect();
+        let cached_prefix: String = cached_trimmed.chars().take(200).collect();
+        if content_prefix == cached_prefix {
+            return true;
+        }
+    }
+
+    let normalized = content_text.trim_start().to_lowercase();
+    HOST_PROMPT_SIGNATURES
+        .iter()
+        .any(|signature| normalized.starts_with(signature))
+}
+
+/// TS `filterHostSystemPromptsWithCachedPrompt` — user-role items always kept;
+/// detected host prompts either keep only their host-context slice or are
+/// dropped entirely. `None` input passes through (TS non-array passthrough).
+pub fn filter_host_system_prompts_with_cached_prompt(
+    input: Option<Vec<InputItem>>,
+    cached_prompt: Option<&str>,
+) -> Option<Vec<InputItem>> {
+    let input = input?;
+    Some(
+        input
+            .into_iter()
+            .flat_map(|item| {
+                if item.role.as_deref() == Some("user") {
+                    return vec![item];
+                }
+                if !is_host_system_prompt(&item, cached_prompt) {
+                    return vec![item];
+                }
+                let content_text = get_content_text(&item);
+                match extract_host_context(&content_text) {
+                    Some(preserved) if !preserved.is_empty() => {
+                        vec![replace_content_text(item, &preserved)]
+                    }
+                    _ => vec![],
+                }
+            })
+            .collect(),
+    )
+}
+
+/// TS `getCallId` — trimmed non-empty string `call_id`, else `None`.
+fn get_call_id(item: &InputItem) -> Option<String> {
+    let raw = item.extra.get("call_id")?.as_str()?;
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS orphan-conversion truncation limit.
+const MAX_ORPHAN_OUTPUT_CHARS: usize = 16_000;
+
+/// TS `convertOrphanedOutputToMessage` — the orphaned `*_output` item becomes
+/// an assistant message
+/// `"[Previous {toolName} result; call_id={id|unknown}]: {text}"` where text
+/// is the string output, or `JSON.stringify` of a non-string output, truncated
+/// at 16000 chars with a `"\n...[truncated]"` suffix.
+fn convert_orphaned_output_to_message(item: &InputItem, call_id: Option<&str>) -> InputItem {
+    let tool_name = item
+        .extra
+        .get("name")
+        .and_then(Value::as_str)
+        .unwrap_or("tool");
+    let label_call_id = call_id.unwrap_or("unknown");
+    let mut text = match item.extra.get("output") {
+        Some(Value::String(output)) => output.clone(),
+        // JSON.stringify(out); serde_json cannot fail on a Value (no circular
+        // refs / bigints exist), so the TS catch-path `String(output ?? "")`
+        // is unreachable here.
+        Some(other) => serde_json::to_string(other).unwrap_or_default(),
+        // TS: JSON.stringify(undefined) → undefined; Rust treats a missing
+        // output as the empty string.
+        None => String::new(),
+    };
+    if text.chars().count() > MAX_ORPHAN_OUTPUT_CHARS {
+        let truncated: String = text.chars().take(MAX_ORPHAN_OUTPUT_CHARS).collect();
+        text = format!("{truncated}\n...[truncated]");
+    }
+    InputItem {
+        id: None,
+        kind: Some("message".to_string()),
+        role: Some("assistant".to_string()),
+        content: Some(Value::String(format!(
+            "[Previous {tool_name} result; call_id={label_call_id}]: {text}"
+        ))),
+        extra: Map::new(),
+    }
+}
+
+/// TS `collectCallIds` — call ids of `function_call` / `local_shell_call` /
+/// `custom_tool_call` items.
+struct CallIds {
+    function_call_ids: Vec<String>,
+    local_shell_call_ids: Vec<String>,
+    custom_tool_call_ids: Vec<String>,
+}
+
+fn collect_call_ids(input: &[InputItem]) -> CallIds {
+    let mut ids = CallIds {
+        function_call_ids: Vec::new(),
+        local_shell_call_ids: Vec::new(),
+        custom_tool_call_ids: Vec::new(),
+    };
+    for item in input {
+        let Some(call_id) = get_call_id(item) else {
+            continue;
+        };
+        match item.kind.as_deref() {
+            Some("function_call") => ids.function_call_ids.push(call_id),
+            Some("local_shell_call") => ids.local_shell_call_ids.push(call_id),
+            Some("custom_tool_call") => ids.custom_tool_call_ids.push(call_id),
+            _ => {}
+        }
+    }
+    ids
+}
+
+/// TS `normalizeOrphanedToolOutputs` — outputs with no matching call anywhere
+/// in the list are converted to assistant messages (never dropped, so the
+/// model keeps the tool-result context). Matching rules:
+/// - `function_call_output` matches a `function_call` OR `local_shell_call` id;
+/// - `custom_tool_call_output` matches a `custom_tool_call` id;
+/// - `local_shell_call_output` matches a `local_shell_call` id.
+pub fn normalize_orphaned_tool_outputs(input: Vec<InputItem>) -> Vec<InputItem> {
+    let ids = collect_call_ids(&input);
+    input
+        .into_iter()
+        .map(|item| {
+            let call_id = get_call_id(&item);
+            let has_match = |haystack: &[String]| {
+                call_id
+                    .as_deref()
+                    .map(|id| haystack.iter().any(|known| known == id))
+                    .unwrap_or(false)
+            };
+            match item.kind.as_deref() {
+                Some("function_call_output") => {
+                    if has_match(&ids.function_call_ids) || has_match(&ids.local_shell_call_ids) {
+                        item
+                    } else {
+                        convert_orphaned_output_to_message(&item, call_id.as_deref())
+                    }
+                }
+                Some("custom_tool_call_output") => {
+                    if has_match(&ids.custom_tool_call_ids) {
+                        item
+                    } else {
+                        convert_orphaned_output_to_message(&item, call_id.as_deref())
+                    }
+                }
+                Some("local_shell_call_output") => {
+                    if has_match(&ids.local_shell_call_ids) {
+                        item
+                    } else {
+                        convert_orphaned_output_to_message(&item, call_id.as_deref())
+                    }
+                }
+                _ => item,
+            }
+        })
+        .collect()
+}
+
+/// TS `CANCELLED_TOOL_OUTPUT` — frozen user-visible string.
+const CANCELLED_TOOL_OUTPUT: &str = "Operation cancelled by user";
+
+/// TS `collectOutputCallIds`.
+fn collect_output_call_ids(input: &[InputItem]) -> Vec<String> {
+    input
+        .iter()
+        .filter(|item| {
+            matches!(
+                item.kind.as_deref(),
+                Some("function_call_output")
+                    | Some("local_shell_call_output")
+                    | Some("custom_tool_call_output")
+            )
+        })
+        .filter_map(get_call_id)
+        .collect()
+}
+
+/// TS `injectMissingToolOutputs` — for every call item whose call_id has no
+/// corresponding `*_output` anywhere in the input, insert
+/// `{ type: <matching output type>, call_id, output: "Operation cancelled by user" }`
+/// immediately after it.
+pub fn inject_missing_tool_outputs(input: Vec<InputItem>) -> Vec<InputItem> {
+    let output_call_ids = collect_output_call_ids(&input);
+    let mut result: Vec<InputItem> = Vec::with_capacity(input.len());
+
+    for item in input {
+        let kind = item.kind.clone();
+        let call_id = get_call_id(&item);
+        result.push(item);
+
+        let output_type = match kind.as_deref() {
+            Some("function_call") => "function_call_output",
+            Some("local_shell_call") => "local_shell_call_output",
+            Some("custom_tool_call") => "custom_tool_call_output",
+            _ => continue,
+        };
+        let Some(call_id) = call_id else { continue };
+        if output_call_ids.iter().any(|known| known == &call_id) {
+            continue;
+        }
+        let mut extra = Map::new();
+        extra.insert("call_id".to_string(), Value::String(call_id));
+        extra.insert(
+            "output".to_string(),
+            Value::String(CANCELLED_TOOL_OUTPUT.to_string()),
+        );
+        result.push(InputItem {
+            id: None,
+            kind: Some(output_type.to_string()),
+            role: None,
+            content: None,
+            extra,
+        });
+    }
+
+    result
+}
+
+// ===========================================================================
+// Tests — ported from test/input-utils.test.ts
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn item(value: Value) -> InputItem {
+        serde_json::from_value(value).expect("test item must parse")
+    }
+
+    fn items(value: Value) -> Vec<InputItem> {
+        serde_json::from_value(value).expect("test items must parse")
+    }
+
+    // --- injectMissingToolOutputs -----------------------------------------
+
+    #[test]
+    fn inject_returns_empty_for_empty_input() {
+        assert!(inject_missing_tool_outputs(Vec::new()).is_empty());
+    }
+
+    #[test]
+    fn inject_passes_through_input_with_no_function_calls() {
+        let input = items(json!([
+            { "type": "message", "role": "user", "content": "Hello" },
+            { "type": "message", "role": "assistant", "content": "Hi there" },
+        ]));
+        assert_eq!(inject_missing_tool_outputs(input.clone()), input);
+    }
+
+    #[test]
+    fn inject_passes_through_function_call_with_matching_output() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "call_id": "call_1", "name": "test" },
+            { "type": "function_call_output", "role": "tool", "call_id": "call_1", "output": "result" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[0].kind.as_deref(), Some("function_call"));
+        assert_eq!(result[1].kind.as_deref(), Some("function_call_output"));
+    }
+
+    #[test]
+    fn inject_injects_output_for_orphaned_function_call() {
+        let input = items(json!([
+            { "type": "message", "role": "user", "content": "run the tool" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_orphan", "name": "read_file" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[2].kind.as_deref(), Some("function_call_output"));
+        assert_eq!(
+            result[2].extra.get("call_id"),
+            Some(&Value::String("call_orphan".to_string()))
+        );
+        assert_eq!(
+            result[2].extra.get("output"),
+            Some(&Value::String("Operation cancelled by user".to_string()))
+        );
+    }
+
+    #[test]
+    fn inject_injects_output_for_orphaned_local_shell_call() {
+        let input = items(json!([
+            { "type": "local_shell_call", "role": "assistant", "call_id": "shell_1", "command": "ls" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[1].kind.as_deref(), Some("local_shell_call_output"));
+        assert_eq!(
+            result[1].extra.get("call_id"),
+            Some(&Value::String("shell_1".to_string()))
+        );
+    }
+
+    #[test]
+    fn inject_injects_output_for_orphaned_custom_tool_call() {
+        let input = items(json!([
+            { "type": "custom_tool_call", "role": "assistant", "call_id": "custom_1", "name": "my_tool" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[1].kind.as_deref(), Some("custom_tool_call_output"));
+    }
+
+    #[test]
+    fn inject_handles_multiple_orphaned_calls() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "call_id": "call_1", "name": "tool1" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_2", "name": "tool2" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_3", "name": "tool3" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 6);
+        assert_eq!(
+            result
+                .iter()
+                .filter(|i| i.kind.as_deref() == Some("function_call_output"))
+                .count(),
+            3
+        );
+    }
+
+    #[test]
+    fn inject_only_injects_for_calls_without_outputs() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "call_id": "call_with_output", "name": "tool1" },
+            { "type": "function_call_output", "role": "tool", "call_id": "call_with_output", "output": "done" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_without_output", "name": "tool2" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 4);
+        assert_eq!(
+            result
+                .iter()
+                .filter(|i| i.kind.as_deref() == Some("function_call_output"))
+                .count(),
+            2
+        );
+    }
+
+    #[test]
+    fn inject_skips_calls_without_call_id() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "name": "no_id_tool" },
+        ]));
+        assert_eq!(inject_missing_tool_outputs(input).len(), 1);
+    }
+
+    #[test]
+    fn inject_places_output_immediately_after_the_call() {
+        let input = items(json!([
+            { "type": "message", "role": "user", "content": "start" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_A", "name": "toolA" },
+            { "type": "message", "role": "user", "content": "middle" },
+            { "type": "function_call", "role": "assistant", "call_id": "call_B", "name": "toolB" },
+            { "type": "message", "role": "user", "content": "end" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        assert_eq!(result.len(), 7);
+        let kinds: Vec<_> = result.iter().map(|i| i.kind.as_deref().unwrap()).collect();
+        assert_eq!(
+            kinds,
+            vec![
+                "message",
+                "function_call",
+                "function_call_output",
+                "message",
+                "function_call",
+                "function_call_output",
+                "message",
+            ]
+        );
+        assert_eq!(
+            result[2].extra.get("call_id"),
+            Some(&Value::String("call_A".to_string()))
+        );
+        assert_eq!(
+            result[5].extra.get("call_id"),
+            Some(&Value::String("call_B".to_string()))
+        );
+    }
+
+    #[test]
+    fn injected_output_serializes_with_ts_key_order() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "call_id": "c1", "name": "t" },
+        ]));
+        let result = inject_missing_tool_outputs(input);
+        let serialized = serde_json::to_string(&result[1]).unwrap();
+        assert_eq!(
+            serialized,
+            r#"{"type":"function_call_output","call_id":"c1","output":"Operation cancelled by user"}"#
+        );
+    }
+
+    // --- normalizeOrphanedToolOutputs -------------------------------------
+
+    #[test]
+    fn normalize_converts_orphaned_function_call_output_to_message() {
+        let input = items(json!([
+            { "type": "function_call_output", "role": "tool", "call_id": "orphan_call", "output": "some result" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].kind.as_deref(), Some("message"));
+        assert_eq!(result[0].role.as_deref(), Some("assistant"));
+    }
+
+    #[test]
+    fn normalize_preserves_function_call_output_with_matching_call() {
+        let input = items(json!([
+            { "type": "function_call", "role": "assistant", "call_id": "matched_call", "name": "test" },
+            { "type": "function_call_output", "role": "tool", "call_id": "matched_call", "output": "result" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[1].kind.as_deref(), Some("function_call_output"));
+    }
+
+    #[test]
+    fn normalize_converts_orphaned_local_shell_call_output_to_message() {
+        let input = items(json!([
+            { "type": "local_shell_call_output", "role": "tool", "call_id": "orphan_shell", "output": "shell result" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].kind.as_deref(), Some("message"));
+        assert_eq!(result[0].role.as_deref(), Some("assistant"));
+    }
+
+    #[test]
+    fn normalize_preserves_local_shell_call_output_with_matching_call() {
+        let input = items(json!([
+            { "type": "local_shell_call", "role": "assistant", "call_id": "shell_matched", "command": "ls" },
+            { "type": "local_shell_call_output", "role": "tool", "call_id": "shell_matched", "output": "files" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[1].kind.as_deref(), Some("local_shell_call_output"));
+    }
+
+    #[test]
+    fn normalize_function_call_output_matches_local_shell_call_ids_too() {
+        let input = items(json!([
+            { "type": "local_shell_call", "call_id": "shell_call", "action": {"type": "exec"} },
+            { "type": "function_call_output", "call_id": "shell_call", "output": "ok" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result[1].kind.as_deref(), Some("function_call_output"));
+    }
+
+    #[test]
+    fn normalize_truncates_very_long_output_content() {
+        let long_output = "x".repeat(20_000);
+        let input = items(json!([
+            { "type": "function_call_output", "role": "tool", "call_id": "orphan_long", "output": long_output },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].kind.as_deref(), Some("message"));
+        let content = result[0]
+            .content
+            .as_ref()
+            .and_then(Value::as_str)
+            .unwrap_or("");
+        assert!(content.len() < 20_000);
+        assert!(content.contains("[truncated]"));
+    }
+
+    #[test]
+    fn normalize_converts_non_string_output_to_json() {
+        let input = items(json!([
+            { "type": "function_call_output", "role": "tool", "call_id": "orphan_obj", "output": { "key": "value" } },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].kind.as_deref(), Some("message"));
+        let content = result[0]
+            .content
+            .as_ref()
+            .and_then(Value::as_str)
+            .unwrap_or("");
+        assert!(content.contains("key"));
+        assert!(content.contains("value"));
+    }
+
+    #[test]
+    fn normalize_message_label_uses_name_and_call_id() {
+        let input = items(json!([
+            { "type": "function_call_output", "call_id": "orphan_call", "name": "read", "output": "{}" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        let content = result[0].content.as_ref().and_then(Value::as_str).unwrap();
+        assert_eq!(content, "[Previous read result; call_id=orphan_call]: {}");
+    }
+
+    #[test]
+    fn normalize_message_label_falls_back_to_tool_and_unknown() {
+        // No name → "tool"; blank call_id → "unknown".
+        let input = items(json!([
+            { "type": "custom_tool_call_output", "call_id": "   ", "output": "oops" },
+        ]));
+        let result = normalize_orphaned_tool_outputs(input);
+        let content = result[0].content.as_ref().and_then(Value::as_str).unwrap();
+        assert_eq!(content, "[Previous tool result; call_id=unknown]: oops");
+    }
+
+    // --- combined flow -----------------------------------------------------
+
+    #[test]
+    fn combined_flow_handles_both_orphaned_calls_and_outputs() {
+        let input = items(json!([
+            { "type": "function_call_output", "role": "tool", "call_id": "orphan_output", "output": "lost result" },
+            { "type": "function_call", "role": "assistant", "call_id": "orphan_call", "name": "new_tool" },
+        ]));
+        let normalized = normalize_orphaned_tool_outputs(input);
+        let injected = inject_missing_tool_outputs(normalized);
+        assert_eq!(
+            injected
+                .iter()
+                .filter(|i| i.kind.as_deref() == Some("message"))
+                .count(),
+            1
+        );
+        assert_eq!(
+            injected
+                .iter()
+                .filter(|i| i.kind.as_deref() == Some("function_call"))
+                .count(),
+            1
+        );
+        assert_eq!(
+            injected
+                .iter()
+                .filter(|i| i.kind.as_deref() == Some("function_call_output"))
+                .count(),
+            1
+        );
+    }
+
+    // --- getContentText edge cases -----------------------------------------
+
+    #[test]
+    fn get_content_text_returns_empty_for_non_string_non_array_content() {
+        assert_eq!(
+            get_content_text(&item(json!({ "type": "message", "role": "user" }))),
+            ""
+        );
+        assert_eq!(
+            get_content_text(&item(
+                json!({ "type": "message", "role": "user", "content": null })
+            )),
+            ""
+        );
+        assert_eq!(
+            get_content_text(&item(
+                json!({ "type": "message", "role": "user", "content": 123 })
+            )),
+            ""
+        );
+    }
+
+    #[test]
+    fn get_content_text_joins_input_text_parts_and_skips_empty_or_foreign_parts() {
+        let value = item(json!({
+            "type": "message",
+            "role": "user",
+            "content": [
+                { "type": "input_text", "text": "one" },
+                { "type": "input_image", "url": "x" },
+                { "type": "input_text", "text": "" },
+                { "type": "input_text", "text": "two" },
+            ]
+        }));
+        assert_eq!(get_content_text(&value), "one\ntwo");
+    }
+
+    // --- isHostSystemPrompt -------------------------------------------------
+
+    #[test]
+    fn host_prompt_true_when_content_starts_with_cached_prompt() {
+        let cached = "You are Codex, an agent";
+        let value = item(json!({
+            "type": "message",
+            "role": "system",
+            "content": "You are Codex, an agent with additional context appended here",
+        }));
+        assert!(is_host_system_prompt(&value, Some(cached)));
+    }
+
+    #[test]
+    fn host_prompt_true_when_first_200_chars_match_cached_prefix() {
+        let long_text = "A".repeat(250);
+        let content = format!("{}{}", &long_text[..200], "B".repeat(100));
+        let value = item(json!({
+            "type": "message",
+            "role": "system",
+            "content": content,
+        }));
+        assert!(is_host_system_prompt(&value, Some(&long_text)));
+    }
+
+    #[test]
+    fn host_prompt_false_for_non_system_roles_even_with_matching_content() {
+        let value = item(json!({
+            "type": "message",
+            "role": "user",
+            "content": "You are Codex, an agent",
+        }));
+        assert!(!is_host_system_prompt(
+            &value,
+            Some("You are Codex, an agent")
+        ));
+    }
+
+    #[test]
+    fn host_prompt_false_when_content_is_empty() {
+        let value = item(json!({
+            "type": "message",
+            "role": "system",
+            "content": "",
+        }));
+        assert!(!is_host_system_prompt(
+            &value,
+            Some("You are Codex, an agent")
+        ));
+    }
+
+    #[test]
+    fn host_prompt_true_for_developer_role_with_matching_signature() {
+        let value = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": "You are Codex, an interactive CLI agent that does stuff",
+        }));
+        assert!(is_host_system_prompt(&value, None));
+    }
+
+    #[test]
+    fn host_prompt_detects_string_and_array_content_signatures() {
+        let string_item = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": "You are a coding agent running in the Codex, a terminal-based coding assistant.",
+        }));
+        assert!(is_host_system_prompt(&string_item, None));
+
+        let array_item = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": [{
+                "type": "input_text",
+                "text": "You are a coding agent running in the Codex, a terminal-based coding assistant.",
+            }],
+        }));
+        assert!(is_host_system_prompt(&array_item, None));
+    }
+
+    #[test]
+    fn host_prompt_does_not_detect_agents_md_or_env_content() {
+        let agents_md = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": "# Project Guidelines\n\nThis is custom AGENTS.md content for the project.",
+        }));
+        assert!(!is_host_system_prompt(&agents_md, None));
+
+        let env_plus_agents = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": "Environment: /path/to/project\nDate: 2025-01-01\n\n# AGENTS.md\n\nCustom instructions here.",
+        }));
+        assert!(!is_host_system_prompt(&env_plus_agents, None));
+    }
+
+    #[test]
+    fn host_prompt_does_not_detect_signature_in_the_middle() {
+        let cached = "You are a coding agent running in the Codex.";
+        let value = item(json!({
+            "type": "message",
+            "role": "developer",
+            "content": "Environment info here\n\nYou are a coding agent running in the Codex.",
+        }));
+        assert!(!is_host_system_prompt(&value, Some(cached)));
+    }
+
+    // --- filterHostSystemPromptsWithCachedPrompt ---------------------------
+
+    #[test]
+    fn filter_returns_none_for_none_input() {
+        assert!(filter_host_system_prompts_with_cached_prompt(None, None).is_none());
+    }
+
+    #[test]
+    fn filter_preserves_user_messages_unchanged() {
+        let input = items(json!([
+            { "type": "message", "role": "user", "content": "Hello" },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input.clone()), None);
+        assert_eq!(result, Some(input));
+    }
+
+    #[test]
+    fn filter_drops_host_system_prompt_without_context() {
+        let input = items(json!([
+            { "type": "message", "role": "system", "content": "You are Codex, an agent doing things" },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input), None).unwrap();
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn filter_preserves_context_when_filtering_host_prompt() {
+        let input = items(json!([
+            {
+                "type": "message",
+                "role": "system",
+                "content": "You are Codex, an agent\n\nHere is some useful information about the environment you are running in:\n<env>test</env>",
+            },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input), None).unwrap();
+        assert_eq!(result.len(), 1);
+        let content = result[0].content.as_ref().and_then(Value::as_str).unwrap();
+        assert!(content.contains("Here is some useful information"));
+        assert!(!content.contains("You are Codex, an agent\n"));
+    }
+
+    #[test]
+    fn filter_replaces_array_content_with_extracted_context() {
+        let input = items(json!([
+            {
+                "type": "message",
+                "role": "system",
+                "content": [
+                    { "type": "input_text", "text": "You are Codex, an agent\n\n<instructions>\nDo things</instructions>" },
+                ],
+            },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input), None).unwrap();
+        assert_eq!(result.len(), 1);
+        let content = result[0].content.as_ref().unwrap();
+        let parts = content.as_array().expect("array content stays an array");
+        let text = parts[0].get("text").and_then(Value::as_str).unwrap();
+        assert!(text.contains("<instructions>"));
+    }
+
+    #[test]
+    fn filter_keeps_agents_md_and_env_messages() {
+        let input = items(json!([
+            { "type": "message", "role": "developer", "content": "You are a coding agent running in the Codex" },
+            { "type": "message", "role": "developer", "content": "# Project Guidelines\n\nThis is AGENTS.md content." },
+            { "type": "message", "role": "user", "content": "hello" },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input), None).unwrap();
+        assert_eq!(result.len(), 2);
+        let first = result[0].content.as_ref().and_then(Value::as_str).unwrap();
+        assert!(first.contains("AGENTS.md"));
+        assert_eq!(result[1].role.as_deref(), Some("user"));
+    }
+
+    #[test]
+    fn filter_strips_codex_prompt_but_keeps_concatenated_env_instructions() {
+        let content = [
+            "You are a coding agent running in the Codex, a terminal-based coding assistant.",
+            "Here is some useful information about the environment you are running in:",
+            "<env>",
+            "  Working directory: /path/to/project",
+            "</env>",
+            "Instructions from: /path/to/AGENTS.md",
+            "# Project Guidelines",
+        ]
+        .join("\n");
+        let input = items(json!([
+            { "type": "message", "role": "developer", "content": content },
+            { "type": "message", "role": "user", "content": "hello" },
+        ]));
+        let result = filter_host_system_prompts_with_cached_prompt(Some(input), None).unwrap();
+        assert_eq!(result.len(), 2);
+        let preserved = result[0].content.as_ref().and_then(Value::as_str).unwrap();
+        assert!(preserved.contains("Here is some useful information about the environment"));
+        assert!(preserved.contains("Instructions from: /path/to/AGENTS.md"));
+        assert!(!preserved.contains("You are a coding agent running in the Codex"));
+    }
+}
diff --git a/crates/request/src/lib.rs b/crates/request/src/lib.rs
new file mode 100644
index 000000000..463731546
--- /dev/null
+++ b/crates/request/src/lib.rs
@@ -0,0 +1,25 @@
+//! cma-request - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod attempt_budget;
+pub mod context_overflow;
+pub mod error_classification;
+pub mod failover_config;
+pub mod failure_policy;
+pub mod fetch_helpers;
+pub mod headers;
+pub mod input_utils;
+pub mod model_map;
+pub mod prompts;
+pub mod rate_limit_backoff;
+pub mod rate_limit_decision;
+pub mod request_init;
+pub mod resilience;
+pub mod response_compaction;
+pub mod response_handler;
+pub mod response_metadata;
+pub mod stream_failover;
+pub mod stream_failover_runtime;
+pub mod token_refresh;
+pub mod tool_utils;
+pub mod transformer;
+pub mod url_rewriting;
+pub mod wait_utils;
diff --git a/crates/request/src/model_map.rs b/crates/request/src/model_map.rs
new file mode 100644
index 000000000..fd9da0cfa
--- /dev/null
+++ b/crates/request/src/model_map.rs
@@ -0,0 +1,1122 @@
+//! Port of `lib/request/helpers/model-map.ts` — the model catalog: alias map,
+//! model-id resolution with GPT-5 family fallback, per-model profiles, and
+//! tool-surface capability metadata (spec 06 §1).
+//!
+//! `ModelFamily`, `MODEL_FAMILIES`, `DEFAULT_MODEL` and `DEFAULT_PROBE_MODEL`
+//! live in `cma_core::model_family` (de-cycling move #1, ARCHITECTURE §4);
+//! this module owns the resolution TABLES and re-exports those names so the
+//! TS module surface stays intact for callers.
+//!
+//! Layering seam: `cma-accounts` (L2) cannot see this crate (L3), so it
+//! defined the traits [`cma_accounts::capability_policy::ModelCatalog`] and
+//! [`cma_accounts::capability_matrix::ModelProfileProvider`]. The production
+//! implementations for both live here on [`RequestModelCatalog`].
+//!
+//! Resolution contract (spec 06 §1 + gotcha 6):
+//! - exact/case-insensitive alias lookup first;
+//! - ANY id containing `codex` → [`CURRENT_CODEX_MODEL`];
+//! - unknown GPT-5.6 tiers → Sol;
+//! - anything else GPT-5-ish → per-minor catalog, defaulting to `gpt-5.5`;
+//! - fully unknown ids → [`DEFAULT_MODEL`] (`"gpt-5.5"`).
+
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use cma_core::constants::{ModelReasoningEffort, WireReasoningEffort};
+
+// TS re-exports: `export { MODEL_FAMILIES, DEFAULT_MODEL, ... }` — the enum
+// and default-model constants live in core; the catalog re-exports them.
+pub use cma_core::constants::{
+    ModelReasoningEffort as ReasoningEffort, WireReasoningEffort as WireEffort,
+};
+pub use cma_core::model_family::{
+    DEFAULT_MODEL, DEFAULT_PROBE_MODEL, MODEL_FAMILIES, ModelFamily, PromptModelFamily,
+};
+
+/// TS `ModelCapabilities` — identical shape to the accounts-crate seam type,
+/// so the seam type IS the canonical type here (no conversion layer).
+pub use cma_accounts::capability_matrix::ModelCapabilitiesInfo as ModelCapabilities;
+
+use cma_accounts::capability_matrix::{MatrixModelProfile, ModelProfileProvider};
+use cma_accounts::capability_policy::ModelCatalog;
+
+/// TS `CURRENT_CODEX_MODEL`.
+pub const CURRENT_CODEX_MODEL: &str = "gpt-5.3-codex";
+
+const LEGACY_CODEX_MODEL: &str = "gpt-5-codex";
+
+const GPT_5_6_SOL_MODEL: &str = "gpt-5.6-sol";
+const GPT_5_6_TERRA_MODEL: &str = "gpt-5.6-terra";
+const GPT_5_6_LUNA_MODEL: &str = "gpt-5.6-luna";
+/// Bare `gpt-5.6` is OpenAI's documented alias for the flagship (Sol) tier.
+const GPT_5_6_FLAGSHIP_ALIAS: &str = "gpt-5.6";
+
+const GPT_5_5_CANONICAL_MODEL: &str = "gpt-5.5";
+const GPT_5_5_PRO_CANONICAL_MODEL: &str = "gpt-5.5-pro";
+const GPT_5_5_RELEASE_MODEL: &str = "gpt-5.5-2026-04-23";
+const GPT_5_5_PRO_RELEASE_MODEL: &str = "gpt-5.5-pro-2026-04-23";
+const GPT_5_5_RELEASE_COMPAT_MODEL: &str = "gpt-5.5-20260423";
+const GPT_5_5_PRO_RELEASE_COMPAT_MODEL: &str = "gpt-5.5-pro-20260423";
+
+/// Single source of truth for the live/quota probe fallback chain (TS
+/// `QUOTA_PROBE_MODEL_CHAIN`). Leads with GPT-5.6 and steps down so accounts
+/// without 5.6 entitlement still resolve a working probe model.
+pub const QUOTA_PROBE_MODEL_CHAIN: [&str; 6] = [
+    DEFAULT_PROBE_MODEL,
+    DEFAULT_MODEL,
+    "gpt-5.4",
+    CURRENT_CODEX_MODEL,
+    "gpt-5.2-codex",
+    LEGACY_CODEX_MODEL,
+];
+
+// ---------------------------------------------------------------------------
+// Capability presets (TS `TOOL_CAPABILITIES`)
+// ---------------------------------------------------------------------------
+
+const CAPS_FULL: ModelCapabilities = ModelCapabilities {
+    tool_search: true,
+    computer_use: true,
+    compaction: true,
+};
+/// Defined-but-unused in TS too; kept for table parity.
+#[allow(dead_code)]
+const CAPS_COMPUTER_ONLY: ModelCapabilities = ModelCapabilities {
+    tool_search: false,
+    computer_use: true,
+    compaction: false,
+};
+const CAPS_COMPUTER_AND_COMPACT: ModelCapabilities = ModelCapabilities {
+    tool_search: false,
+    computer_use: true,
+    compaction: true,
+};
+const CAPS_COMPACT_ONLY: ModelCapabilities = ModelCapabilities {
+    tool_search: false,
+    computer_use: false,
+    compaction: true,
+};
+const CAPS_BASIC: ModelCapabilities = ModelCapabilities {
+    tool_search: false,
+    computer_use: false,
+    compaction: false,
+};
+
+// ---------------------------------------------------------------------------
+// Model profiles (TS `MODEL_PROFILES`)
+// ---------------------------------------------------------------------------
+
+/// TS `ModelProfile`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModelProfile {
+    pub normalized_model: &'static str,
+    pub prompt_family: PromptModelFamily,
+    pub default_reasoning_effort: ModelReasoningEffort,
+    pub supported_reasoning_efforts: &'static [ModelReasoningEffort],
+    pub capabilities: ModelCapabilities,
+}
+
+use ModelReasoningEffort as E;
+
+const EFFORTS_CODEX: &[E] = &[E::Low, E::Medium, E::High, E::Xhigh];
+const EFFORTS_GENERAL: &[E] = &[E::None, E::Low, E::Medium, E::High, E::Xhigh];
+const EFFORTS_PRO: &[E] = &[E::Medium, E::High, E::Xhigh];
+const EFFORTS_MEDIUM_ONLY: &[E] = &[E::Medium];
+const EFFORTS_GPT_5_1: &[E] = &[E::None, E::Low, E::Medium, E::High];
+/// Sol and Terra expose `ultra`; Luna stops at `max`. No 5.6 tier accepts
+/// `none`/`minimal`, so those aliases are deliberately never generated.
+const GPT_5_6_SOL_TERRA_EFFORTS: &[E] = &[E::Low, E::Medium, E::High, E::Xhigh, E::Max, E::Ultra];
+const GPT_5_6_LUNA_EFFORTS: &[E] = &[E::Low, E::Medium, E::High, E::Xhigh, E::Max];
+
+/// Effective model profiles keyed by canonical model name (key ==
+/// `normalized_model`), in the exact TS table order — the order is the
+/// `ModelProfileProvider::default_models` contract.
+pub const MODEL_PROFILES: [ModelProfile; 15] = [
+    ModelProfile {
+        normalized_model: CURRENT_CODEX_MODEL,
+        prompt_family: ModelFamily::Gpt5Codex,
+        default_reasoning_effort: E::High,
+        supported_reasoning_efforts: EFFORTS_CODEX,
+        capabilities: CAPS_BASIC,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.4",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::None,
+        supported_reasoning_efforts: EFFORTS_GENERAL,
+        capabilities: CAPS_FULL,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.4-pro",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::High,
+        supported_reasoning_efforts: EFFORTS_PRO,
+        capabilities: CAPS_COMPUTER_AND_COMPACT,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.4-mini",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: EFFORTS_MEDIUM_ONLY,
+        capabilities: CAPS_COMPACT_ONLY,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.4-nano",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: EFFORTS_MEDIUM_ONLY,
+        capabilities: CAPS_COMPACT_ONLY,
+    },
+    // GPT-5.6 ships its base instructions inline in the upstream model catalog
+    // rather than as a `gpt_5_6_prompt.md`, so these stay on the GPT-5.2
+    // prompt family alongside the other post-5.2 general models.
+    ModelProfile {
+        normalized_model: GPT_5_6_SOL_MODEL,
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Low,
+        supported_reasoning_efforts: GPT_5_6_SOL_TERRA_EFFORTS,
+        capabilities: CAPS_FULL,
+    },
+    ModelProfile {
+        normalized_model: GPT_5_6_TERRA_MODEL,
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: GPT_5_6_SOL_TERRA_EFFORTS,
+        capabilities: CAPS_FULL,
+    },
+    ModelProfile {
+        normalized_model: GPT_5_6_LUNA_MODEL,
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: GPT_5_6_LUNA_EFFORTS,
+        capabilities: CAPS_FULL,
+    },
+    ModelProfile {
+        normalized_model: GPT_5_5_CANONICAL_MODEL,
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::None,
+        supported_reasoning_efforts: EFFORTS_GENERAL,
+        capabilities: CAPS_FULL,
+    },
+    ModelProfile {
+        normalized_model: GPT_5_5_PRO_CANONICAL_MODEL,
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::High,
+        supported_reasoning_efforts: EFFORTS_PRO,
+        capabilities: CAPS_COMPUTER_AND_COMPACT,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.2-pro",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::High,
+        supported_reasoning_efforts: EFFORTS_PRO,
+        capabilities: CAPS_BASIC,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.2",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::None,
+        supported_reasoning_efforts: EFFORTS_GENERAL,
+        capabilities: CAPS_BASIC,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5.1",
+        prompt_family: ModelFamily::Gpt5_1,
+        default_reasoning_effort: E::None,
+        supported_reasoning_efforts: EFFORTS_GPT_5_1,
+        capabilities: CAPS_BASIC,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5-mini",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: EFFORTS_MEDIUM_ONLY,
+        capabilities: CAPS_COMPACT_ONLY,
+    },
+    ModelProfile {
+        normalized_model: "gpt-5-nano",
+        prompt_family: ModelFamily::Gpt5_2,
+        default_reasoning_effort: E::Medium,
+        supported_reasoning_efforts: EFFORTS_MEDIUM_ONLY,
+        capabilities: CAPS_COMPACT_ONLY,
+    },
+];
+
+/// `MODEL_PROFILES[model]` — exact-key lookup (key == `normalized_model`).
+pub fn get_model_profile_exact(model: &str) -> Option<&'static ModelProfile> {
+    MODEL_PROFILES
+        .iter()
+        .find(|profile| profile.normalized_model == model)
+}
+
+// ---------------------------------------------------------------------------
+// Alias map (TS `MODEL_MAP`)
+// ---------------------------------------------------------------------------
+
+/// Insertion-ordered alias → canonical-model map reproducing JS object
+/// property-order semantics: re-inserting an existing key updates its value
+/// but keeps its original position (matters for the case-insensitive
+/// first-match scan in [`ModelMap::get_case_insensitive`]).
+#[derive(Debug, Default)]
+pub struct ModelMap {
+    entries: Vec<(String, &'static str)>,
+    index: HashMap<String, usize>,
+}
+
+impl ModelMap {
+    fn insert(&mut self, alias: &str, canonical: &'static str) {
+        if let Some(&position) = self.index.get(alias) {
+            self.entries[position].1 = canonical;
+        } else {
+            self.index.insert(alias.to_string(), self.entries.len());
+            self.entries.push((alias.to_string(), canonical));
+        }
+    }
+
+    /// Exact-key lookup (TS `Object.hasOwn(MODEL_MAP, id)` + read).
+    pub fn get(&self, alias: &str) -> Option<&'static str> {
+        self.index.get(alias).map(|&position| self.entries[position].1)
+    }
+
+    /// First key (in insertion order) whose lowercase form equals the
+    /// lowercased id (TS `Object.keys(MODEL_MAP).find(...)`).
+    pub fn get_case_insensitive(&self, alias: &str) -> Option<&'static str> {
+        let lower = alias.to_lowercase();
+        self.entries
+            .iter()
+            .find(|(key, _)| key.to_lowercase() == lower)
+            .map(|&(_, canonical)| canonical)
+    }
+
+    /// Aliases in insertion order.
+    pub fn keys(&self) -> impl Iterator<Item = &str> {
+        self.entries.iter().map(|(key, _)| key.as_str())
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+}
+
+/// The alias map (TS `MODEL_MAP`), built once at first use in the exact TS
+/// registration order.
+pub fn model_map() -> &'static ModelMap {
+    &MODEL_MAP
+}
+
+static MODEL_MAP: LazyLock<ModelMap> = LazyLock::new(build_model_map);
+
+/// TS `REASONING_VARIANTS` — the alias-suffix set (NOT max/ultra).
+const REASONING_VARIANTS: [&str; 6] = ["none", "minimal", "low", "medium", "high", "xhigh"];
+
+fn add_alias(map: &mut ModelMap, alias: &str, normalized_model: &'static str) {
+    map.insert(alias, normalized_model);
+}
+
+fn add_reasoning_aliases(map: &mut ModelMap, alias: &str, normalized_model: &'static str) {
+    add_alias(map, alias, normalized_model);
+    for variant in REASONING_VARIANTS {
+        add_alias(map, &format!("{alias}-{variant}"), normalized_model);
+    }
+}
+
+/// Register a model plus one alias per effort it actually supports.
+///
+/// Unlike [`add_reasoning_aliases`], this does not assume the global variant
+/// list: GPT-5.6 rejects `none`/`minimal` and only Sol/Terra accept `ultra`.
+fn add_effort_aliases(
+    map: &mut ModelMap,
+    alias: &str,
+    normalized_model: &'static str,
+    efforts: &[ModelReasoningEffort],
+) {
+    add_alias(map, alias, normalized_model);
+    for effort in efforts {
+        add_alias(map, &format!("{alias}-{}", effort.as_str()), normalized_model);
+    }
+}
+
+fn add_codex_aliases(map: &mut ModelMap) {
+    add_reasoning_aliases(map, CURRENT_CODEX_MODEL, CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5.3-codex-spark", CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, LEGACY_CODEX_MODEL, CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5.2-codex", CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5.1-codex", CURRENT_CODEX_MODEL);
+    add_alias(map, "gpt_5_codex", CURRENT_CODEX_MODEL);
+
+    add_reasoning_aliases(map, "codex-max", CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5.1-codex-max", CURRENT_CODEX_MODEL);
+    // TS registers the bare `codex-max` alias a second time (harmless
+    // overwrite; position preserved).
+    add_alias(map, "codex-max", CURRENT_CODEX_MODEL);
+
+    add_alias(map, "codex-mini-latest", CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5-codex-mini", CURRENT_CODEX_MODEL);
+    add_reasoning_aliases(map, "gpt-5.1-codex-mini", CURRENT_CODEX_MODEL);
+}
+
+fn add_general_aliases(map: &mut ModelMap) {
+    add_reasoning_aliases(map, GPT_5_5_CANONICAL_MODEL, GPT_5_5_CANONICAL_MODEL);
+    add_reasoning_aliases(map, GPT_5_5_RELEASE_MODEL, GPT_5_5_CANONICAL_MODEL);
+    add_reasoning_aliases(map, GPT_5_5_RELEASE_COMPAT_MODEL, GPT_5_5_CANONICAL_MODEL);
+    add_reasoning_aliases(map, GPT_5_5_PRO_CANONICAL_MODEL, GPT_5_5_PRO_CANONICAL_MODEL);
+    add_reasoning_aliases(map, GPT_5_5_PRO_RELEASE_MODEL, GPT_5_5_PRO_CANONICAL_MODEL);
+    add_reasoning_aliases(map, GPT_5_5_PRO_RELEASE_COMPAT_MODEL, GPT_5_5_PRO_CANONICAL_MODEL);
+    add_reasoning_aliases(map, "gpt-5.4", "gpt-5.4");
+    add_reasoning_aliases(map, "gpt-5.4-pro", "gpt-5.4-pro");
+    add_reasoning_aliases(map, "gpt-5.4-mini", "gpt-5.4-mini");
+    add_reasoning_aliases(map, "gpt-5.4-nano", "gpt-5.4-nano");
+    add_reasoning_aliases(map, "gpt-5.2-pro", "gpt-5.2-pro");
+    add_reasoning_aliases(map, "gpt-5-pro", GPT_5_5_PRO_CANONICAL_MODEL);
+    add_reasoning_aliases(map, "gpt-5.2", "gpt-5.2");
+    add_reasoning_aliases(map, "gpt-5.1", "gpt-5.1");
+    add_reasoning_aliases(map, "gpt-5", DEFAULT_MODEL);
+    add_reasoning_aliases(map, "gpt-5-mini", "gpt-5-mini");
+    add_reasoning_aliases(map, "gpt-5-nano", "gpt-5-nano");
+
+    add_reasoning_aliases(map, "gpt-5.1-chat-latest", "gpt-5.1");
+    add_reasoning_aliases(map, "gpt-5-chat-latest", DEFAULT_MODEL);
+}
+
+fn add_gpt56_aliases(map: &mut ModelMap) {
+    add_effort_aliases(map, GPT_5_6_SOL_MODEL, GPT_5_6_SOL_MODEL, GPT_5_6_SOL_TERRA_EFFORTS);
+    add_effort_aliases(
+        map,
+        GPT_5_6_TERRA_MODEL,
+        GPT_5_6_TERRA_MODEL,
+        GPT_5_6_SOL_TERRA_EFFORTS,
+    );
+    add_effort_aliases(map, GPT_5_6_LUNA_MODEL, GPT_5_6_LUNA_MODEL, GPT_5_6_LUNA_EFFORTS);
+    add_effort_aliases(
+        map,
+        GPT_5_6_FLAGSHIP_ALIAS,
+        GPT_5_6_SOL_MODEL,
+        GPT_5_6_SOL_TERRA_EFFORTS,
+    );
+}
+
+fn build_model_map() -> ModelMap {
+    let mut map = ModelMap::default();
+    add_codex_aliases(&mut map);
+    add_general_aliases(&mut map);
+    add_gpt56_aliases(&mut map);
+    map
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/// TS `stripProviderPrefix` — everything after the last `/` (a trailing `/`
+/// therefore strips to the empty string, exactly like `split("/").pop()`).
+pub(crate) fn strip_provider_prefix(model_id: &str) -> &str {
+    if model_id.contains('/') {
+        model_id.rsplit('/').next().unwrap_or(model_id)
+    } else {
+        model_id
+    }
+}
+
+/// TS `tokenizeModelId` — lowercase, split on runs of `[^a-z0-9]`.
+fn tokenize_model_id(model_id: &str) -> Vec<String> {
+    model_id
+        .to_lowercase()
+        .split(|c: char| !c.is_ascii_alphanumeric())
+        .filter(|token| !token.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+/// TS `lookupMappedModel` — exact, then first case-insensitive key match in
+/// insertion order.
+fn lookup_mapped_model(model_id: &str) -> Option<&'static str> {
+    let map = model_map();
+    if let Some(canonical) = map.get(model_id) {
+        return Some(canonical);
+    }
+    map.get_case_insensitive(model_id)
+}
+
+/// TS `resolveCodexCatalogModel`.
+///
+/// The TS body is a chain of lowercase substring checks
+/// (`gpt-5.3-codex[-spark]`, `gpt 5.3 codex`, `gpt-5.2-codex`, …,
+/// plain `codex`) that ALL return [`CURRENT_CODEX_MODEL`]; since every needle
+/// contains `codex` and the final check is plain `codex`, the chain reduces to
+/// "anything containing `codex`" (spec 06 §1 step 4 states this explicitly).
+fn resolve_codex_catalog_model(model_id: &str) -> Option<&'static str> {
+    if model_id.to_lowercase().contains("codex") {
+        Some(CURRENT_CODEX_MODEL)
+    } else {
+        None
+    }
+}
+
+/// TS `resolveGpt56CatalogModel` — resolves GPT-5.6 identifiers that are not
+/// exact aliases (for example a future `gpt-5.6-terra-fast`). Unrecognised
+/// tiers resolve to Sol, matching OpenAI's bare `gpt-5.6` alias. Without this,
+/// the general resolver would silently fall back to 5.5.
+fn resolve_gpt56_catalog_model(model_id: &str) -> Option<&'static str> {
+    let tokens = tokenize_model_id(model_id);
+    let gpt_index = tokens.iter().position(|token| token == "gpt")?;
+    let is_gpt56 = tokens.get(gpt_index + 1).map(String::as_str) == Some("5")
+        && tokens.get(gpt_index + 2).map(String::as_str) == Some("6");
+    if !is_gpt56 || tokens.iter().any(|token| token == "codex") {
+        return None;
+    }
+
+    if tokens.iter().any(|token| token == "terra") {
+        return Some(GPT_5_6_TERRA_MODEL);
+    }
+    if tokens.iter().any(|token| token == "luna") {
+        return Some(GPT_5_6_LUNA_MODEL);
+    }
+    Some(GPT_5_6_SOL_MODEL)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum GeneralGpt5Variant {
+    Base,
+    Pro,
+    Mini,
+    Nano,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct GeneralGpt5VariantCatalog {
+    base: &'static str,
+    pro: Option<&'static str>,
+    mini: Option<&'static str>,
+    nano: Option<&'static str>,
+}
+
+impl GeneralGpt5VariantCatalog {
+    /// TS `resolveGeneralGpt5CatalogVariant` — `catalog[variant] ?? catalog.base`.
+    fn resolve(self, variant: GeneralGpt5Variant) -> &'static str {
+        match variant {
+            GeneralGpt5Variant::Base => self.base,
+            GeneralGpt5Variant::Pro => self.pro.unwrap_or(self.base),
+            GeneralGpt5Variant::Mini => self.mini.unwrap_or(self.base),
+            GeneralGpt5Variant::Nano => self.nano.unwrap_or(self.base),
+        }
+    }
+}
+
+/// TS `GENERAL_GPT5_VERSION_CATALOG` — per-minor variant tables. Note the
+/// deliberate `4.base = DEFAULT_MODEL` ("gpt-5.5", not "gpt-5.4"): `gpt-5.4`
+/// itself resolves through the exact alias map; this entry only matters for
+/// odd spellings like `gpt 5 4` that miss the alias map.
+fn general_gpt5_catalog_for_minor(minor: u64) -> Option<GeneralGpt5VariantCatalog> {
+    match minor {
+        1 => Some(GeneralGpt5VariantCatalog {
+            base: "gpt-5.1",
+            pro: None,
+            mini: None,
+            nano: None,
+        }),
+        2 => Some(GeneralGpt5VariantCatalog {
+            base: "gpt-5.2",
+            pro: Some("gpt-5.2-pro"),
+            mini: None,
+            nano: None,
+        }),
+        4 => Some(GeneralGpt5VariantCatalog {
+            base: DEFAULT_MODEL,
+            pro: Some("gpt-5.4-pro"),
+            mini: Some("gpt-5.4-mini"),
+            nano: Some("gpt-5.4-nano"),
+        }),
+        5 => Some(GENERAL_GPT5_STABLE_VARIANTS),
+        _ => None,
+    }
+}
+
+/// TS `GENERAL_GPT5_STABLE_VARIANTS` (`GENERAL_GPT5_VERSION_CATALOG[5]`).
+const GENERAL_GPT5_STABLE_VARIANTS: GeneralGpt5VariantCatalog = GeneralGpt5VariantCatalog {
+    base: GPT_5_5_CANONICAL_MODEL,
+    pro: Some(GPT_5_5_PRO_CANONICAL_MODEL),
+    mini: Some("gpt-5-mini"),
+    nano: Some("gpt-5-nano"),
+};
+
+/// TS `GENERAL_GPT5_GENERIC_VARIANTS` (no minor version present).
+const GENERAL_GPT5_GENERIC_VARIANTS: GeneralGpt5VariantCatalog = GeneralGpt5VariantCatalog {
+    base: DEFAULT_MODEL,
+    pro: Some(GPT_5_5_PRO_CANONICAL_MODEL),
+    mini: Some("gpt-5-mini"),
+    nano: Some("gpt-5-nano"),
+};
+
+/// TS `resolveGeneralGpt5CatalogModel`.
+fn resolve_general_gpt5_catalog_model(model_id: &str) -> Option<&'static str> {
+    let tokens = tokenize_model_id(model_id);
+    let gpt_index = tokens.iter().position(|token| token == "gpt")?;
+    if tokens.get(gpt_index + 1).map(String::as_str) != Some("5") {
+        return None;
+    }
+    if tokens.iter().any(|token| token == "codex") {
+        return None;
+    }
+
+    // `/^\d+$/` on the token after `5`; unparseable-but-numeric (overflow)
+    // behaves like an unknown minor, which resolves through the stable
+    // catalog exactly as a huge JS Number would.
+    let raw_minor = tokens.get(gpt_index + 2);
+    let is_numeric_minor = raw_minor
+        .map(|token| !token.is_empty() && token.bytes().all(|b| b.is_ascii_digit()))
+        .unwrap_or(false);
+
+    let variant = if tokens.iter().any(|token| token == "mini") {
+        GeneralGpt5Variant::Mini
+    } else if tokens.iter().any(|token| token == "nano") {
+        GeneralGpt5Variant::Nano
+    } else if tokens.iter().any(|token| token == "pro") {
+        GeneralGpt5Variant::Pro
+    } else {
+        GeneralGpt5Variant::Base
+    };
+
+    if !is_numeric_minor {
+        return Some(GENERAL_GPT5_GENERIC_VARIANTS.resolve(variant));
+    }
+
+    let known_catalog = raw_minor
+        .and_then(|token| token.parse::<u64>().ok())
+        .and_then(general_gpt5_catalog_for_minor);
+    match known_catalog {
+        Some(catalog) => Some(catalog.resolve(variant)),
+        // Unknown minor → stable (v5) catalog for the variant.
+        None => Some(GENERAL_GPT5_STABLE_VARIANTS.resolve(variant)),
+    }
+}
+
+/// TS `getNormalizedModel` — exact/case-insensitive alias lookup ONLY
+/// (strips provider prefix, trims); `None` for unknown ids; never panics.
+pub fn get_normalized_model(model_id: &str) -> Option<&'static str> {
+    let stripped = strip_provider_prefix(model_id.trim());
+    if stripped.is_empty() {
+        return None;
+    }
+    lookup_mapped_model(stripped)
+}
+
+/// TS `resolveNormalizedModel` — alias lookup expanded with the GPT-5 family
+/// fallback rules; empty/`None` → [`DEFAULT_MODEL`].
+pub fn resolve_normalized_model(model: Option<&str>) -> &'static str {
+    let Some(model) = model else {
+        return DEFAULT_MODEL;
+    };
+    if model.is_empty() {
+        return DEFAULT_MODEL;
+    }
+
+    let model_id = strip_provider_prefix(model).trim();
+    if model_id.is_empty() {
+        return DEFAULT_MODEL;
+    }
+
+    if let Some(mapped) = lookup_mapped_model(model_id) {
+        return mapped;
+    }
+    if let Some(codex) = resolve_codex_catalog_model(model_id) {
+        return codex;
+    }
+    if let Some(gpt56) = resolve_gpt56_catalog_model(model_id) {
+        return gpt56;
+    }
+    if let Some(general) = resolve_general_gpt5_catalog_model(model_id) {
+        return general;
+    }
+
+    DEFAULT_MODEL
+}
+
+/// TS `getModelProfile` — profile of the resolved model, falling back to the
+/// [`DEFAULT_MODEL`] profile (which the static table guarantees exists).
+pub fn get_model_profile(model: Option<&str>) -> &'static ModelProfile {
+    let normalized = resolve_normalized_model(model);
+    get_model_profile_exact(normalized)
+        .or_else(|| get_model_profile_exact(DEFAULT_MODEL))
+        .unwrap_or_else(|| panic!("Default model profile is missing for {DEFAULT_MODEL}"))
+}
+
+/// TS `getModelCapabilities`.
+pub fn get_model_capabilities(model: Option<&str>) -> ModelCapabilities {
+    get_model_profile(model).capabilities
+}
+
+/// TS `getModelFamily` (source: `lib/prompts/codex.ts`; the table row for
+/// this module assigns it here) — the prompt family of the resolved model.
+pub fn get_model_family(model: &str) -> PromptModelFamily {
+    get_model_profile(Some(model)).prompt_family
+}
+
+/// Cheapest-first ordering used to pick a quota-probe reasoning effort.
+/// `ultra` is intentionally absent: it never reaches the wire (upstream
+/// rewrites it to `max`) and would only ever be a more expensive choice.
+const PROBE_REASONING_EFFORT_PREFERENCE: [WireReasoningEffort; 7] = [
+    WireReasoningEffort::None,
+    WireReasoningEffort::Minimal,
+    WireReasoningEffort::Low,
+    WireReasoningEffort::Medium,
+    WireReasoningEffort::High,
+    WireReasoningEffort::Xhigh,
+    WireReasoningEffort::Max,
+];
+
+/// TS `resolveProbeReasoningEffort` — the cheapest effort the probe model
+/// declares support for; fallback is the profile default with `ultra` → `max`.
+/// Never returns `ultra` (the type makes that structural).
+pub fn resolve_probe_reasoning_effort(model: Option<&str>) -> WireReasoningEffort {
+    let profile = get_model_profile(model);
+    for wire in PROBE_REASONING_EFFORT_PREFERENCE {
+        if profile
+            .supported_reasoning_efforts
+            .contains(&ModelReasoningEffort::from(wire))
+        {
+            return wire;
+        }
+    }
+    profile.default_reasoning_effort.to_wire()
+}
+
+/// TS `isKnownModel` — `true` only for exact known aliases (no fallback).
+pub fn is_known_model(model_id: &str) -> bool {
+    get_normalized_model(model_id).is_some()
+}
+
+// ---------------------------------------------------------------------------
+// L2 seam implementations (cma-accounts traits)
+// ---------------------------------------------------------------------------
+
+/// Production implementation of the accounts-crate catalog seams, backed by
+/// this module's tables. Wire it into
+/// `cma_accounts::capability_policy::CapabilityPolicyStore::with_catalog` and
+/// `cma_accounts::capability_matrix::build_model_capability_matrix`.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RequestModelCatalog;
+
+impl ModelCatalog for RequestModelCatalog {
+    fn get_normalized_model(&self, model: &str) -> Option<String> {
+        get_normalized_model(model).map(str::to_string)
+    }
+
+    fn resolve_normalized_model(&self, model: &str) -> String {
+        resolve_normalized_model(Some(model)).to_string()
+    }
+}
+
+impl ModelProfileProvider for RequestModelCatalog {
+    fn default_models(&self) -> Vec<String> {
+        MODEL_PROFILES
+            .iter()
+            .map(|profile| profile.normalized_model.to_string())
+            .collect()
+    }
+
+    fn resolve_normalized_model(&self, model: &str) -> String {
+        resolve_normalized_model(Some(model)).to_string()
+    }
+
+    fn profile(&self, model: &str) -> Option<MatrixModelProfile> {
+        get_model_profile_exact(model).map(|profile| MatrixModelProfile {
+            normalized_model: profile.normalized_model.to_string(),
+            prompt_family: profile.prompt_family,
+            default_reasoning_effort: profile.default_reasoning_effort,
+            supported_reasoning_efforts: profile.supported_reasoning_efforts.to_vec(),
+            capabilities: profile.capabilities,
+        })
+    }
+}
+
+/// Shared handle for call sites that take `Arc<dyn ModelCatalog>`.
+pub fn shared_model_catalog() -> std::sync::Arc<dyn ModelCatalog> {
+    std::sync::Arc::new(RequestModelCatalog)
+}
+
+// ===========================================================================
+// Tests — ported from test/model-map.test.ts (+ Rust-only table/seam checks)
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // --- MODEL_MAP -------------------------------------------------------
+
+    #[test]
+    fn routes_codex_aliases_to_the_current_documented_codex_model() {
+        let map = model_map();
+        assert_eq!(map.get("gpt-5-codex"), Some("gpt-5.3-codex"));
+        assert_eq!(map.get("gpt-5.3-codex-spark-high"), Some("gpt-5.3-codex"));
+        assert_eq!(map.get("gpt-5.1-codex-max-xhigh"), Some("gpt-5.3-codex"));
+        assert_eq!(map.get("codex-mini-latest"), Some("gpt-5.3-codex"));
+        assert_eq!(map.get("gpt_5_codex"), Some("gpt-5.3-codex"));
+        assert_eq!(map.get("codex-max"), Some("gpt-5.3-codex"));
+    }
+
+    #[test]
+    fn keeps_gpt_5_5_aliases_canonical_while_preserving_existing_general_models() {
+        let map = model_map();
+        assert_eq!(map.get("gpt-5.5"), Some("gpt-5.5"));
+        assert_eq!(map.get("gpt-5.5-pro-high"), Some("gpt-5.5-pro"));
+        assert_eq!(map.get("gpt-5.4"), Some("gpt-5.4"));
+        assert_eq!(map.get("gpt-5"), Some("gpt-5.5"));
+    }
+
+    #[test]
+    fn keeps_mini_and_nano_on_current_non_5_1_model_ids() {
+        let map = model_map();
+        assert_eq!(map.get("gpt-5-mini"), Some("gpt-5-mini"));
+        assert_eq!(map.get("gpt-5-nano"), Some("gpt-5-nano"));
+        assert_eq!(map.get("gpt-5.4-mini"), Some("gpt-5.4-mini"));
+        assert_eq!(map.get("gpt-5.4-nano"), Some("gpt-5.4-nano"));
+    }
+
+    #[test]
+    fn adds_reasoning_variants_for_legacy_chat_latest_aliases() {
+        let map = model_map();
+        assert_eq!(map.get("gpt-5-chat-latest-high"), Some("gpt-5.5"));
+        assert_eq!(map.get("gpt-5.1-chat-latest-minimal"), Some("gpt-5.1"));
+    }
+
+    #[test]
+    fn gpt56_aliases_use_per_tier_effort_lists_not_the_global_variant_list() {
+        let map = model_map();
+        // Sol/Terra list ultra; Luna stops at max.
+        assert_eq!(map.get("gpt-5.6-sol-ultra"), Some("gpt-5.6-sol"));
+        assert_eq!(map.get("gpt-5.6-terra-ultra"), Some("gpt-5.6-terra"));
+        assert_eq!(map.get("gpt-5.6-luna-max"), Some("gpt-5.6-luna"));
+        assert_eq!(map.get("gpt-5.6-luna-ultra"), None);
+        // No 5.6 tier registers none/minimal aliases.
+        assert_eq!(map.get("gpt-5.6-sol-none"), None);
+        assert_eq!(map.get("gpt-5.6-terra-minimal"), None);
+        // Bare flagship alias (+ effort variants) lands on Sol.
+        assert_eq!(map.get("gpt-5.6"), Some("gpt-5.6-sol"));
+        assert_eq!(map.get("gpt-5.6-max"), Some("gpt-5.6-sol"));
+    }
+
+    #[test]
+    fn reinserting_an_alias_keeps_its_original_position() {
+        let mut map = ModelMap::default();
+        map.insert("a", "one");
+        map.insert("b", "two");
+        map.insert("a", "three");
+        let keys: Vec<&str> = map.keys().collect();
+        assert_eq!(keys, vec!["a", "b"]);
+        assert_eq!(map.get("a"), Some("three"));
+        assert_eq!(map.len(), 2);
+        assert!(!map.is_empty());
+    }
+
+    // --- getNormalizedModel ----------------------------------------------
+
+    #[test]
+    fn returns_exact_aliases_case_insensitively() {
+        assert_eq!(get_normalized_model("GPT-5.5"), Some("gpt-5.5"));
+        assert_eq!(get_normalized_model("GPT-5.5-PRO-HIGH"), Some("gpt-5.5-pro"));
+        assert_eq!(get_normalized_model("GPT-5.4"), Some("gpt-5.4"));
+        assert_eq!(get_normalized_model("GPT-5.4-PRO-HIGH"), Some("gpt-5.4-pro"));
+        assert_eq!(get_normalized_model("gpt-5.4-mini"), Some("gpt-5.4-mini"));
+        assert_eq!(get_normalized_model("gpt-5.3-codex-high"), Some("gpt-5.3-codex"));
+        assert_eq!(get_normalized_model("gpt-5-chat-latest-high"), Some("gpt-5.5"));
+        assert_eq!(get_normalized_model("codex-max"), Some("gpt-5.3-codex"));
+    }
+
+    #[test]
+    fn returns_none_for_unknown_exact_identifiers() {
+        assert_eq!(get_normalized_model("unknown-model"), None);
+        assert_eq!(get_normalized_model("gpt-6"), None);
+        assert_eq!(get_normalized_model("gpt-5.7"), None);
+        assert_eq!(get_normalized_model(""), None);
+        // Trailing provider slash strips to empty → None.
+        assert_eq!(get_normalized_model("openai/"), None);
+    }
+
+    // --- resolveNormalizedModel ------------------------------------------
+
+    #[test]
+    fn resolves_provider_prefixed_and_verbose_gpt5_variants() {
+        assert_eq!(
+            resolve_normalized_model(Some("openai/gpt-5.5-2026-04-23")),
+            "gpt-5.5"
+        );
+        assert_eq!(
+            resolve_normalized_model(Some("openai/gpt-5.5-20260423")),
+            "gpt-5.5"
+        );
+        assert_eq!(resolve_normalized_model(Some("GPT 5.5 Pro High")), "gpt-5.5-pro");
+        assert_eq!(resolve_normalized_model(Some("openai/gpt-5.4")), "gpt-5.4");
+        assert_eq!(
+            resolve_normalized_model(Some("openai/gpt-5.4-mini-high")),
+            "gpt-5.4-mini"
+        );
+        assert_eq!(resolve_normalized_model(Some("GPT 5.4 Pro High")), "gpt-5.4-pro");
+        assert_eq!(
+            resolve_normalized_model(Some("GPT 5 Codex Low (ChatGPT Subscription)")),
+            "gpt-5.3-codex"
+        );
+    }
+
+    #[test]
+    fn defaults_unknown_gpt5ish_requests_to_gpt_5_5_instead_of_gpt_5_1() {
+        assert_eq!(resolve_normalized_model(Some("gpt-5-unknown-preview")), "gpt-5.5");
+        assert_eq!(
+            resolve_normalized_model(Some("gpt 5 experimental build")),
+            "gpt-5.5"
+        );
+    }
+
+    #[test]
+    fn keeps_gpt_5_5_aliases_first_class_with_fallback_routing_for_unknown_names() {
+        assert_eq!(resolve_normalized_model(Some("gpt-5.5")), "gpt-5.5");
+        assert_eq!(resolve_normalized_model(Some("gpt-5.5-high")), "gpt-5.5");
+        assert_eq!(
+            resolve_normalized_model(Some("openai/gpt-5.5-pro-high")),
+            "gpt-5.5-pro"
+        );
+    }
+
+    #[test]
+    fn uses_the_current_default_model_when_the_request_is_missing_or_unrelated() {
+        assert_eq!(resolve_normalized_model(None), DEFAULT_MODEL);
+        assert_eq!(resolve_normalized_model(Some("")), DEFAULT_MODEL);
+        assert_eq!(resolve_normalized_model(Some("gpt-4")), DEFAULT_MODEL);
+        assert_eq!(resolve_normalized_model(Some("unknown-model")), DEFAULT_MODEL);
+    }
+
+    #[test]
+    fn anything_containing_codex_normalizes_to_the_current_codex_model() {
+        assert_eq!(resolve_normalized_model(Some("my-gpt-5-codex-model")), "gpt-5.3-codex");
+        assert_eq!(resolve_normalized_model(Some("mycodex")), "gpt-5.3-codex");
+        assert_eq!(resolve_normalized_model(Some("gpt 5.2 codex")), "gpt-5.3-codex");
+        assert_eq!(
+            resolve_normalized_model(Some("gpt 5.1 codex max")),
+            "gpt-5.3-codex"
+        );
+    }
+
+    #[test]
+    fn unknown_gpt56_tiers_land_on_sol_and_named_tiers_resolve() {
+        // Not exact aliases → the 5.6 token resolver.
+        assert_eq!(
+            resolve_normalized_model(Some("gpt-5.6-terra-fast")),
+            "gpt-5.6-terra"
+        );
+        assert_eq!(
+            resolve_normalized_model(Some("gpt 5.6 luna preview")),
+            "gpt-5.6-luna"
+        );
+        assert_eq!(resolve_normalized_model(Some("gpt-5.6-pro")), "gpt-5.6-sol");
+        assert_eq!(resolve_normalized_model(Some("GPT 5 6")), "gpt-5.6-sol");
+        // 5.6 + codex → the codex resolver wins first.
+        assert_eq!(
+            resolve_normalized_model(Some("gpt-5.6-codex")),
+            "gpt-5.3-codex"
+        );
+    }
+
+    #[test]
+    fn general_gpt5_catalog_resolves_minor_and_variant_tokens() {
+        // Minor-version catalogs.
+        assert_eq!(resolve_normalized_model(Some("gpt 5 1")), "gpt-5.1");
+        assert_eq!(resolve_normalized_model(Some("gpt 5 2 pro")), "gpt-5.2-pro");
+        // Minor-1 catalog has base only → pro falls back to base.
+        assert_eq!(resolve_normalized_model(Some("gpt 5 1 pro")), "gpt-5.1");
+        // Minor-4 base is literally DEFAULT_MODEL (gpt-5.5) — deliberate.
+        assert_eq!(resolve_normalized_model(Some("gpt 5 4")), "gpt-5.5");
+        assert_eq!(resolve_normalized_model(Some("gpt 5 4 mini")), "gpt-5.4-mini");
+        // Unknown minor → stable (v5) catalog.
+        assert_eq!(resolve_normalized_model(Some("gpt 5 7 pro")), "gpt-5.5-pro");
+        assert_eq!(resolve_normalized_model(Some("gpt-5.7")), "gpt-5.5");
+        // Variant precedence: mini beats nano beats pro.
+        assert_eq!(
+            resolve_normalized_model(Some("gpt 5 pro mini nano")),
+            "gpt-5-mini"
+        );
+    }
+
+    // --- model profiles ---------------------------------------------------
+
+    #[test]
+    fn routes_gpt_5_4_era_general_models_through_the_latest_general_prompt_family() {
+        assert_eq!(
+            get_model_profile(Some("gpt-5.4")).prompt_family,
+            ModelFamily::Gpt5_2
+        );
+        assert_eq!(
+            get_model_profile(Some("gpt-5.4-pro")).prompt_family,
+            ModelFamily::Gpt5_2
+        );
+        assert_eq!(
+            get_model_profile(Some("gpt-5-mini")).prompt_family,
+            ModelFamily::Gpt5_2
+        );
+    }
+
+    #[test]
+    fn keeps_gpt_5_1_on_its_own_prompt_family() {
+        assert_eq!(
+            get_model_profile(Some("gpt-5.1")).prompt_family,
+            ModelFamily::Gpt5_1
+        );
+        assert_eq!(get_model_family("gpt-5.1"), ModelFamily::Gpt5_1);
+        assert_eq!(get_model_family("gpt-5-codex"), ModelFamily::Gpt5Codex);
+    }
+
+    #[test]
+    fn exposes_tool_search_and_computer_use_capabilities() {
+        let full = ModelCapabilities {
+            tool_search: true,
+            computer_use: true,
+            compaction: true,
+        };
+        let computer_and_compact = ModelCapabilities {
+            tool_search: false,
+            computer_use: true,
+            compaction: true,
+        };
+        let compact_only = ModelCapabilities {
+            tool_search: false,
+            computer_use: false,
+            compaction: true,
+        };
+        assert_eq!(get_model_capabilities(Some("gpt-5.5")), full);
+        assert_eq!(get_model_capabilities(Some("gpt-5.5-pro")), computer_and_compact);
+        assert_eq!(get_model_capabilities(Some("gpt-5.4")), full);
+        assert_eq!(get_model_capabilities(Some("gpt-5.4-pro")), computer_and_compact);
+        assert_eq!(get_model_capabilities(Some("gpt-5.4-mini")), compact_only);
+        assert_eq!(get_model_capabilities(Some("gpt-5-mini")), compact_only);
+        assert_eq!(get_model_capabilities(Some("gpt-5-nano")), compact_only);
+    }
+
+    #[test]
+    fn unknown_models_fall_back_to_the_default_profile() {
+        let profile = get_model_profile(Some("claude-3"));
+        assert_eq!(profile.normalized_model, DEFAULT_MODEL);
+        assert_eq!(get_model_profile(None).normalized_model, DEFAULT_MODEL);
+    }
+
+    // --- isKnownModel -----------------------------------------------------
+
+    #[test]
+    fn is_known_model_returns_true_for_explicit_aliases_only() {
+        assert!(is_known_model("gpt-5.5"));
+        assert!(is_known_model("gpt-5.5-pro-2026-04-23"));
+        assert!(is_known_model("gpt-5.5-pro-20260423"));
+        assert!(is_known_model("gpt-5.4"));
+        assert!(is_known_model("gpt-5.4-mini"));
+        assert!(is_known_model("GPT-5.3-CODEX-HIGH"));
+
+        assert!(!is_known_model("gpt-5-unknown-preview"));
+        assert!(!is_known_model("gpt-5.6-pro"));
+        assert!(!is_known_model("claude-3"));
+        assert!(!is_known_model(""));
+    }
+
+    // --- probe helpers ----------------------------------------------------
+
+    #[test]
+    fn quota_probe_model_chain_matches_ts() {
+        assert_eq!(
+            QUOTA_PROBE_MODEL_CHAIN,
+            [
+                "gpt-5.6-sol",
+                "gpt-5.5",
+                "gpt-5.4",
+                "gpt-5.3-codex",
+                "gpt-5.2-codex",
+                "gpt-5-codex",
+            ]
+        );
+    }
+
+    #[test]
+    fn resolve_probe_reasoning_effort_picks_the_cheapest_supported_wire_effort() {
+        // Pre-5.6 general models that list `none` send `none`.
+        assert_eq!(
+            resolve_probe_reasoning_effort(Some("gpt-5.5")),
+            WireReasoningEffort::None
+        );
+        // Codex and GPT-5.6 tiers do not list none/minimal → `low`.
+        assert_eq!(
+            resolve_probe_reasoning_effort(Some("gpt-5.3-codex")),
+            WireReasoningEffort::Low
+        );
+        assert_eq!(
+            resolve_probe_reasoning_effort(Some("gpt-5.6-sol")),
+            WireReasoningEffort::Low
+        );
+        // Medium-only smalls send medium; pro tiers send medium.
+        assert_eq!(
+            resolve_probe_reasoning_effort(Some("gpt-5-nano")),
+            WireReasoningEffort::Medium
+        );
+        assert_eq!(
+            resolve_probe_reasoning_effort(Some("gpt-5.5-pro")),
+            WireReasoningEffort::Medium
+        );
+    }
+
+    // --- L2 seam impls ----------------------------------------------------
+
+    #[test]
+    fn model_catalog_seam_matches_the_free_functions() {
+        let catalog = RequestModelCatalog;
+        assert_eq!(
+            ModelCatalog::get_normalized_model(&catalog, "GPT-5.5-PRO-HIGH"),
+            Some("gpt-5.5-pro".to_string())
+        );
+        assert_eq!(ModelCatalog::get_normalized_model(&catalog, "unknown-model"), None);
+        assert_eq!(
+            ModelCatalog::resolve_normalized_model(&catalog, "my-codex"),
+            "gpt-5.3-codex"
+        );
+        // Arc<dyn ModelCatalog> wiring compiles and dispatches.
+        let shared = shared_model_catalog();
+        assert_eq!(shared.resolve_normalized_model("gpt-5"), "gpt-5.5");
+    }
+
+    #[test]
+    fn model_profile_provider_seam_exposes_table_order_and_exact_profiles() {
+        let provider = RequestModelCatalog;
+        let defaults = ModelProfileProvider::default_models(&provider);
+        assert_eq!(defaults.len(), 15);
+        assert_eq!(defaults[0], "gpt-5.3-codex");
+        assert_eq!(defaults[1], "gpt-5.4");
+        assert_eq!(defaults[14], "gpt-5-nano");
+
+        // Exact-key lookup only — aliases do NOT hit (the matrix re-resolves).
+        assert!(ModelProfileProvider::profile(&provider, "gpt-5-codex").is_none());
+        let profile = ModelProfileProvider::profile(&provider, "gpt-5.3-codex")
+            .expect("canonical key resolves");
+        assert_eq!(profile.normalized_model, "gpt-5.3-codex");
+        assert_eq!(profile.prompt_family, ModelFamily::Gpt5Codex);
+        assert_eq!(profile.default_reasoning_effort, ModelReasoningEffort::High);
+        assert_eq!(
+            profile.supported_reasoning_efforts,
+            vec![
+                ModelReasoningEffort::Low,
+                ModelReasoningEffort::Medium,
+                ModelReasoningEffort::High,
+                ModelReasoningEffort::Xhigh,
+            ]
+        );
+        assert!(!profile.capabilities.tool_search);
+    }
+
+    #[test]
+    fn capability_policy_store_shares_buckets_through_this_catalog() {
+        use cma_accounts::capability_policy::CapabilityPolicyStore;
+        let mut store = CapabilityPolicyStore::with_catalog(std::sync::Arc::new(RequestModelCatalog));
+        store.record_success("id:acct", "openai/gpt-5-codex-high", 1_000);
+        let snapshot = store
+            .get_snapshot("id:acct", "gpt-5.3-codex")
+            .expect("alias and canonical id share one bucket");
+        assert_eq!(snapshot.successes, 1);
+    }
+}
diff --git a/crates/request/src/prompts/codex.rs b/crates/request/src/prompts/codex.rs
new file mode 100644
index 000000000..d31a65a0b
--- /dev/null
+++ b/crates/request/src/prompts/codex.rs
@@ -0,0 +1,992 @@
+//! Port of `lib/prompts/codex.ts` — the per-family Codex instructions cache
+//! (spec 06 / ARCHITECTURE §6.10).
+//!
+//! Fetches Codex system prompts from the latest `openai/codex` GitHub release
+//! with ETag-based conditional requests, a 15-minute TTL,
+//! stale-while-revalidate background refresh, sha256 cache integrity
+//! (prompts-03), atomic two-rename cache writes (prompts-06), and a bundled
+//! offline fallback embedded via `include_str!`.
+//!
+//! Divergence note (recorded in the port log): the TS bundled fallback read a
+//! `codex-instructions.md` sibling of the compiled module, which is absent
+//! from the published package — so the final fallback could itself fail. The
+//! Rust port embeds the fallback at compile time, making
+//! [`get_codex_instructions`] infallible.
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use cma_core::fs_retry::with_file_operation_retry;
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{log_debug, log_error, log_warn};
+use cma_core::model_family::{DEFAULT_MODEL, ModelFamily};
+use cma_core::runtime_paths::get_codex_cache_dir;
+use cma_core::temp_path::temp_file_nonce;
+use cma_core::types::{CacheMetadata, GitHubRelease};
+use cma_core::utils::now_ms;
+use serde_json::json;
+use sha2::{Digest, Sha256};
+
+use super::fetch_utils::{
+    PromptFetchOptions, fetch_with_timeout, read_body_text_guarded, with_body_timeout,
+};
+
+/// Bundled offline fallback (`assets/codex-instructions.md`): the upstream
+/// `codex-rs/core/gpt_5_codex_prompt.md` snapshot vendored into this crate.
+const BUNDLED_INSTRUCTIONS: &str = include_str!("../../assets/codex-instructions.md");
+
+const DEFAULT_GITHUB_API_RELEASES: &str =
+    "https://api.github.com/repos/openai/codex/releases/latest";
+const DEFAULT_GITHUB_HTML_RELEASES: &str = "https://github.com/openai/codex/releases/latest";
+/// `{raw_base}/{tag}/codex-rs/core/{prompt_file}`.
+const DEFAULT_RAW_BASE: &str = "https://raw.githubusercontent.com/openai/codex";
+
+const CACHE_TTL_MS: i64 = 15 * 60 * 1000;
+const RELEASE_TAG_TTL_MS: i64 = 5 * 60 * 1000;
+/// TS `MAX_CACHE_SIZE` — insertion-order eviction cap on the memory cache.
+/// (With only 5 model families the cap is unreachable; kept for parity.)
+const MAX_CACHE_SIZE: usize = 50;
+
+/// SHA-256 of cache content for integrity verification (prompts-03).
+fn sha256_hex(content: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(content.as_bytes());
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+#[derive(Clone, Debug)]
+struct MemoryEntry {
+    content: String,
+    timestamp: i64,
+}
+
+#[derive(Clone, Debug)]
+struct ReleaseTagCache {
+    tag: String,
+    checked_at: i64,
+}
+
+#[derive(Clone, Debug)]
+struct PromptSourceUrls {
+    api_releases: String,
+    html_releases: String,
+    raw_base: String,
+}
+
+impl PromptSourceUrls {
+    fn defaults() -> Self {
+        Self {
+            api_releases: DEFAULT_GITHUB_API_RELEASES.to_string(),
+            html_releases: DEFAULT_GITHUB_HTML_RELEASES.to_string(),
+            raw_base: DEFAULT_RAW_BASE.to_string(),
+        }
+    }
+}
+
+// Insertion-ordered memory cache (JS Map semantics for the eviction rule).
+static MEMORY_CACHE: Mutex<Vec<(ModelFamily, MemoryEntry)>> = Mutex::new(Vec::new());
+static REFRESHING_FAMILIES: Mutex<Option<HashSet<ModelFamily>>> = Mutex::new(None);
+static LATEST_RELEASE_TAG_CACHE: Mutex<Option<ReleaseTagCache>> = Mutex::new(None);
+static SOURCE_URL_OVERRIDES: Mutex<Option<PromptSourceUrls>> = Mutex::new(None);
+
+fn source_urls() -> PromptSourceUrls {
+    SOURCE_URL_OVERRIDES
+        .lock()
+        .expect("prompt source urls poisoned")
+        .clone()
+        .unwrap_or_else(PromptSourceUrls::defaults)
+}
+
+#[cfg(test)]
+fn set_source_urls_for_testing(api: &str, html: &str, raw_base: &str) {
+    *SOURCE_URL_OVERRIDES
+        .lock()
+        .expect("prompt source urls poisoned") = Some(PromptSourceUrls {
+        api_releases: api.to_string(),
+        html_releases: html.to_string(),
+        raw_base: raw_base.to_string(),
+    });
+}
+
+#[cfg(test)]
+fn clear_source_urls_for_testing() {
+    *SOURCE_URL_OVERRIDES
+        .lock()
+        .expect("prompt source urls poisoned") = None;
+}
+
+/// TS `__clearCacheForTesting` — clear the memory cache, in-flight refresh
+/// registry, and the release-tag cache.
+pub fn clear_cache_for_testing() {
+    MEMORY_CACHE.lock().expect("memory cache poisoned").clear();
+    if let Some(set) = REFRESHING_FAMILIES
+        .lock()
+        .expect("refresh registry poisoned")
+        .as_mut()
+    {
+        set.clear();
+    }
+    *LATEST_RELEASE_TAG_CACHE
+        .lock()
+        .expect("release tag cache poisoned") = None;
+}
+
+fn memory_get(family: ModelFamily) -> Option<MemoryEntry> {
+    MEMORY_CACHE
+        .lock()
+        .expect("memory cache poisoned")
+        .iter()
+        .find(|(key, _)| *key == family)
+        .map(|(_, entry)| entry.clone())
+}
+
+/// TS `setCacheEntry` — evict the OLDEST insertion when at capacity and the
+/// key is new (JS `Map.keys().next()`).
+fn memory_set(family: ModelFamily, content: String, timestamp: i64) {
+    let mut cache = MEMORY_CACHE.lock().expect("memory cache poisoned");
+    let existing = cache.iter().position(|(key, _)| *key == family);
+    if existing.is_none() && cache.len() >= MAX_CACHE_SIZE {
+        cache.remove(0);
+    }
+    match existing {
+        Some(index) => cache[index].1 = MemoryEntry { content, timestamp },
+        None => cache.push((family, MemoryEntry { content, timestamp })),
+    }
+}
+
+/// TS `PROMPT_FILES` — prompt file for each model family (based on
+/// `codex-rs/core/src/model_family.rs` logic).
+fn prompt_file(family: ModelFamily) -> &'static str {
+    match family {
+        ModelFamily::Gpt5Codex => "gpt_5_codex_prompt.md",
+        ModelFamily::CodexMax => "gpt-5.1-codex-max_prompt.md",
+        ModelFamily::Codex => "gpt_5_codex_prompt.md",
+        ModelFamily::Gpt5_2 => "gpt_5_2_prompt.md",
+        ModelFamily::Gpt5_1 => "gpt_5_1_prompt.md",
+    }
+}
+
+/// TS `CACHE_FILES` — cache file for each model family.
+fn cache_file_name(family: ModelFamily) -> &'static str {
+    match family {
+        ModelFamily::Gpt5Codex => "gpt-5-codex-instructions.md",
+        ModelFamily::CodexMax => "codex-max-instructions.md",
+        ModelFamily::Codex => "codex-instructions.md",
+        ModelFamily::Gpt5_2 => "gpt-5.2-instructions.md",
+        ModelFamily::Gpt5_1 => "gpt-5.1-instructions.md",
+    }
+}
+
+/// TS `CACHE_FILES[family].replace(".md", "-meta.json")`.
+fn cache_meta_file_name(family: ModelFamily) -> String {
+    cache_file_name(family).replacen(".md", "-meta.json", 1)
+}
+
+/// TS `getModelFamily(normalizedModel)` — the prompt family of the effective
+/// model. GPT-5.4/5.5-era general-purpose models intentionally stay on the
+/// GPT-5.2 prompt family until upstream releases a newer general prompt file.
+pub fn get_model_family(normalized_model: &str) -> ModelFamily {
+    crate::model_map::get_model_profile(Some(normalized_model)).prompt_family
+}
+
+async fn read_file_or_null(path: &Path) -> Option<String> {
+    tokio::fs::read_to_string(path).await.ok()
+}
+
+async fn retry_fs<T, F, Fut>(op: F) -> Result<T, String>
+where
+    F: FnMut() -> Fut,
+    Fut: std::future::Future<Output = std::io::Result<T>>,
+{
+    with_file_operation_retry(op)
+        .await
+        .map_err(|error: std::io::Error| error.to_string())
+}
+
+/// TS `writeCacheAtomically` (prompts-06): write content + meta each to a
+/// temp sibling then rename — content BEFORE meta so the meta's sha always
+/// describes a content file already on disk. A crash between the renames
+/// self-heals on the next read via the sha256 integrity check. Every fs step
+/// retries transient Windows EBUSY/EPERM/ENOTEMPTY/EACCES; temp cleanup is
+/// best-effort and never masks a successful write.
+async fn write_cache_atomically(
+    cache_file: &Path,
+    cache_meta_file: &Path,
+    content: &str,
+    meta: &CacheMetadata,
+) -> Result<(), String> {
+    let cache_dir = get_codex_cache_dir();
+    retry_fs(|| tokio::fs::create_dir_all(&cache_dir)).await?;
+    let nonce = temp_file_nonce();
+    let content_tmp = PathBuf::from(format!("{}.{nonce}.tmp", cache_file.display()));
+    let meta_tmp = PathBuf::from(format!("{}.{nonce}.tmp", cache_meta_file.display()));
+    let meta_json = stringify_compact(meta);
+
+    let result: Result<(), String> = async {
+        retry_fs(|| tokio::fs::write(&content_tmp, content.as_bytes())).await?;
+        retry_fs(|| tokio::fs::write(&meta_tmp, meta_json.as_bytes())).await?;
+        retry_fs(|| tokio::fs::rename(&content_tmp, cache_file)).await?;
+        retry_fs(|| tokio::fs::rename(&meta_tmp, cache_meta_file)).await?;
+        Ok(())
+    }
+    .await;
+
+    // `finally`: remove temp siblings; missing files are a no-op and a
+    // persistent failure is swallowed so cleanup never masks the write result.
+    let _ = retry_fs(|| async {
+        match tokio::fs::remove_file(&content_tmp).await {
+            Err(error) if error.kind() != std::io::ErrorKind::NotFound => Err(error),
+            _ => Ok(()),
+        }
+    })
+    .await;
+    let _ = retry_fs(|| async {
+        match tokio::fs::remove_file(&meta_tmp).await {
+            Err(error) if error.kind() != std::io::ErrorKind::NotFound => Err(error),
+            _ => Ok(()),
+        }
+    })
+    .await;
+
+    result
+}
+
+/// TS `getLatestReleaseTag()` — 5-minute-cached release tag, resolved via the
+/// GitHub API with an HTML redirect/scrape fallback.
+async fn get_latest_release_tag() -> Result<String, String> {
+    if let Some(cache) = LATEST_RELEASE_TAG_CACHE
+        .lock()
+        .expect("release tag cache poisoned")
+        .clone()
+        && now_ms() - cache.checked_at < RELEASE_TAG_TTL_MS
+    {
+        return Ok(cache.tag);
+    }
+    let urls = source_urls();
+
+    // API path — every failure falls through to the HTML fallback.
+    let api_attempt: Result<Option<String>, ()> = async {
+        let response = fetch_with_timeout(
+            &urls.api_releases,
+            &PromptFetchOptions {
+                json: true,
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|_| ())?;
+        if !response.status().is_success() {
+            return Ok(None);
+        }
+        // Guard the body read: the fetch timeout only covers connect+headers,
+        // so a release API response that stalls mid-body must not hang this
+        // request-blocking path (prompts-02).
+        let data: GitHubRelease = with_body_timeout(response.json::<GitHubRelease>(), None)
+            .await
+            .map_err(|_| ())?
+            .map_err(|_| ())?;
+        Ok((!data.tag_name.is_empty()).then_some(data.tag_name))
+    }
+    .await;
+    if let Ok(Some(tag)) = api_attempt {
+        *LATEST_RELEASE_TAG_CACHE
+            .lock()
+            .expect("release tag cache poisoned") = Some(ReleaseTagCache {
+            tag: tag.clone(),
+            checked_at: now_ms(),
+        });
+        return Ok(tag);
+    }
+
+    let html_response = fetch_with_timeout(&urls.html_releases, &PromptFetchOptions::default())
+        .await
+        .map_err(|error| error.to_string())?;
+    if !html_response.status().is_success() {
+        return Err(format!(
+            "Failed to fetch latest release: {}",
+            html_response.status().as_u16()
+        ));
+    }
+
+    // Redirect-following resolves the final /releases/tag/<tag> URL.
+    let final_url = html_response.url().to_string();
+    if !final_url.is_empty() {
+        let last = final_url.split("/tag/").last().unwrap_or("");
+        if last != final_url && !last.is_empty() && !last.contains('/') {
+            let tag = last.to_string();
+            *LATEST_RELEASE_TAG_CACHE
+                .lock()
+                .expect("release tag cache poisoned") = Some(ReleaseTagCache {
+                tag: tag.clone(),
+                checked_at: now_ms(),
+            });
+            return Ok(tag);
+        }
+    }
+
+    // Same mid-body-stall guard as the JSON path for the HTML fallback.
+    let html = with_body_timeout(html_response.text(), None)
+        .await
+        .map_err(|error| error.to_string())?
+        .map_err(|error| error.to_string())?;
+    let pattern = regex::Regex::new(r#"/openai/codex/releases/tag/([^"]+)"#).expect("static regex");
+    if let Some(captures) = pattern.captures(&html)
+        && let Some(tag) = captures.get(1).map(|m| m.as_str().to_string())
+        && !tag.is_empty()
+    {
+        *LATEST_RELEASE_TAG_CACHE
+            .lock()
+            .expect("release tag cache poisoned") = Some(ReleaseTagCache {
+            tag: tag.clone(),
+            checked_at: now_ms(),
+        });
+        return Ok(tag);
+    }
+
+    Err("Failed to determine latest release tag from GitHub".to_string())
+}
+
+/// TS `fetchAndPersistInstructions` — conditional fetch from the latest
+/// release tag, sha256-verified 304 revalidation, guarded body read, atomic
+/// content+meta persist.
+async fn fetch_and_persist_instructions(
+    family: ModelFamily,
+    prompt_file_name: &str,
+    cache_file: &Path,
+    cache_meta_file: &Path,
+    cached_metadata: Option<&CacheMetadata>,
+) -> Result<String, String> {
+    let mut cached_etag: Option<String> = cached_metadata.and_then(|meta| meta.etag.clone());
+    let cached_tag: Option<&str> = cached_metadata.map(|meta| meta.tag.as_str());
+    let latest_tag = get_latest_release_tag().await?;
+    let instructions_url = format!(
+        "{}/{latest_tag}/codex-rs/core/{prompt_file_name}",
+        source_urls().raw_base
+    );
+
+    if cached_tag != Some(latest_tag.as_str()) {
+        cached_etag = None;
+    }
+
+    let mut headers: Vec<(String, String)> = Vec::new();
+    if let Some(etag) = &cached_etag {
+        headers.push(("If-None-Match".to_string(), etag.clone()));
+    }
+
+    let response = fetch_with_timeout(
+        &instructions_url,
+        &PromptFetchOptions {
+            headers,
+            ..Default::default()
+        },
+    )
+    .await
+    .map_err(|error| error.to_string())?;
+
+    // A 304 is only meaningful if we actually sent a conditional request.
+    // When the caller cleared the metadata (e.g. an sha256 mismatch forced a
+    // full refetch), no If-None-Match was sent, so a 304 cannot be trusted to
+    // describe our disk content.
+    if response.status() == reqwest::StatusCode::NOT_MODIFIED && cached_etag.is_some() {
+        let disk_content = read_file_or_null(cache_file).await;
+        // Require a prior sha to trust a 304: without one the on-disk bytes
+        // are unverified, and re-serving them while minting a fresh digest
+        // would launder un-vetted content.
+        let prior_sha = cached_metadata.and_then(|meta| meta.sha256.as_deref());
+        let disk_integrity_ok = matches!(
+            (&disk_content, prior_sha),
+            (Some(content), Some(sha)) if sha == sha256_hex(content)
+        );
+        if let Some(content) = disk_content
+            && disk_integrity_ok
+        {
+            memory_set(family, content.clone(), now_ms());
+            // Refresh the meta (lastChecked) atomically and re-affirm the
+            // content sha so the integrity record stays in sync.
+            write_cache_atomically(
+                cache_file,
+                cache_meta_file,
+                &content,
+                &CacheMetadata {
+                    etag: cached_etag,
+                    tag: latest_tag,
+                    last_checked: now_ms(),
+                    url: instructions_url,
+                    sha256: Some(sha256_hex(&content)),
+                },
+            )
+            .await?;
+            return Ok(content);
+        }
+        return Err("304 revalidation failed integrity check".to_string());
+    }
+
+    if !response.status().is_success() {
+        return Err(format!("HTTP {}", response.status().as_u16()));
+    }
+
+    // Size-cap + reject empty bodies (prompts-04/05) before caching/serving.
+    let new_etag = response
+        .headers()
+        .get("etag")
+        .and_then(|v| v.to_str().ok())
+        .map(str::to_string);
+    let instructions = read_body_text_guarded(response, None, None)
+        .await
+        .map_err(|error| error.to_string())?;
+    // prompts-03/06: write content + meta atomically with a content sha256 so
+    // the cache cannot tear and can be integrity-checked on the next read.
+    write_cache_atomically(
+        cache_file,
+        cache_meta_file,
+        &instructions,
+        &CacheMetadata {
+            etag: new_etag,
+            tag: latest_tag,
+            last_checked: now_ms(),
+            url: instructions_url,
+            sha256: Some(sha256_hex(&instructions)),
+        },
+    )
+    .await?;
+    memory_set(family, instructions.clone(), now_ms());
+    Ok(instructions)
+}
+
+/// TS `refreshInstructionsInBackground` — deduped background refresh per
+/// family; failures are debug-logged and never surface.
+fn refresh_instructions_in_background(
+    family: ModelFamily,
+    prompt_file_name: &'static str,
+    cache_file: PathBuf,
+    cache_meta_file: PathBuf,
+    cached_metadata: Option<CacheMetadata>,
+) {
+    {
+        let mut guard = REFRESHING_FAMILIES
+            .lock()
+            .expect("refresh registry poisoned");
+        let set = guard.get_or_insert_with(HashSet::new);
+        if !set.insert(family) {
+            return;
+        }
+    }
+    tokio::spawn(async move {
+        let result = fetch_and_persist_instructions(
+            family,
+            prompt_file_name,
+            &cache_file,
+            &cache_meta_file,
+            cached_metadata.as_ref(),
+        )
+        .await;
+        if let Err(error) = result {
+            log_debug(
+                &format!(
+                    "Background prompt refresh failed for {}",
+                    family.as_str()
+                ),
+                Some(&json!({ "error": error })),
+            );
+        }
+        if let Some(set) = REFRESHING_FAMILIES
+            .lock()
+            .expect("refresh registry poisoned")
+            .as_mut()
+        {
+            set.remove(&family);
+        }
+    });
+}
+
+/// TS `getCodexInstructions(normalizedModel = DEFAULT_MODEL)`.
+///
+/// Per-family cache ladder: fresh memory → disk (sha256-verified; fresh
+/// serve / stale-while-revalidate) → stale memory (SWR) → network fetch →
+/// usable disk fallback → bundled fallback. Rate-limit protection: GitHub is
+/// only consulted when the cache is older than 15 minutes.
+///
+/// Infallible in Rust: the bundled fallback is embedded via `include_str!`
+/// (see the module-level divergence note).
+pub async fn get_codex_instructions(normalized_model: Option<&str>) -> String {
+    let model = match normalized_model {
+        Some(value) if !value.is_empty() => value,
+        _ => DEFAULT_MODEL,
+    };
+    let model_family = get_model_family(model);
+    let now = now_ms();
+    if let Some(cached) = memory_get(model_family)
+        && now - cached.timestamp < CACHE_TTL_MS
+    {
+        return cached.content;
+    }
+
+    let prompt_file_name = prompt_file(model_family);
+    let cache_dir = get_codex_cache_dir();
+    let cache_file = cache_dir.join(cache_file_name(model_family));
+    let cache_meta_file = cache_dir.join(cache_meta_file_name(model_family));
+
+    let meta_content = read_file_or_null(&cache_meta_file).await;
+    let disk_content = read_file_or_null(&cache_file).await;
+    let mut cached_metadata: Option<CacheMetadata> =
+        meta_content.and_then(|raw| serde_json::from_str(&raw).ok());
+
+    // prompts-03: once disk content fails its sha256 it must not be trusted
+    // anywhere downstream — not served, not the 304 revalidation body, and
+    // not the offline fallback. Track a "usable" view separately.
+    let mut usable_disk_content = disk_content.clone();
+
+    if let Some(disk) = &disk_content
+        && cached_metadata
+            .as_ref()
+            .is_some_and(|meta| meta.last_checked != 0)
+    {
+        let meta = cached_metadata.as_ref().expect("checked above").clone();
+        match meta.sha256.as_deref() {
+            None => {
+                // Unverified legacy entry: clear meta so no If-None-Match is
+                // sent and the cache isn't fast-path served; retain the bytes
+                // as an offline fallback for a failed full fetch.
+                cached_metadata = None;
+            }
+            Some(prior_sha) if prior_sha != sha256_hex(disk) => {
+                log_warn(
+                    &format!(
+                        "Discarding corrupt prompt cache for {} (sha256 mismatch)",
+                        model_family.as_str()
+                    ),
+                    None,
+                );
+                // Force a full refetch: the corrupt body must not be served,
+                // used as the catch fallback, or re-blessed via a 304.
+                usable_disk_content = None;
+                cached_metadata = None;
+            }
+            Some(_) if now - meta.last_checked < CACHE_TTL_MS => {
+                memory_set(model_family, disk.clone(), now);
+                return disk.clone();
+            }
+            Some(_) => {
+                // Stale-while-revalidate: serve stale immediately, refresh in
+                // the background.
+                memory_set(model_family, disk.clone(), now);
+                refresh_instructions_in_background(
+                    model_family,
+                    prompt_file_name,
+                    cache_file,
+                    cache_meta_file,
+                    Some(meta),
+                );
+                return disk.clone();
+            }
+        }
+    }
+
+    if let Some(cached) = memory_get(model_family)
+        && now - cached.timestamp >= CACHE_TTL_MS
+    {
+        // Keep session latency stable by serving stale memory cache while
+        // refreshing.
+        memory_set(model_family, cached.content.clone(), now);
+        refresh_instructions_in_background(
+            model_family,
+            prompt_file_name,
+            cache_file,
+            cache_meta_file,
+            cached_metadata,
+        );
+        return cached.content;
+    }
+
+    match fetch_and_persist_instructions(
+        model_family,
+        prompt_file_name,
+        &cache_file,
+        &cache_meta_file,
+        cached_metadata.as_ref(),
+    )
+    .await
+    {
+        Ok(content) => content,
+        Err(error) => {
+            log_error(
+                &format!(
+                    "Failed to fetch {} instructions from GitHub: {error}",
+                    model_family.as_str()
+                ),
+                None,
+            );
+            if let Some(disk) = usable_disk_content {
+                log_warn(
+                    &format!("Using cached {} instructions", model_family.as_str()),
+                    None,
+                );
+                memory_set(model_family, disk.clone(), now);
+                return disk;
+            }
+            log_warn(
+                &format!(
+                    "Falling back to bundled instructions for {}",
+                    model_family.as_str()
+                ),
+                None,
+            );
+            memory_set(model_family, BUNDLED_INSTRUCTIONS.to_string(), now);
+            BUNDLED_INSTRUCTIONS.to_string()
+        }
+    }
+}
+
+/// TS `prewarmCodexInstructions(models = [])` — prewarm instruction caches
+/// for the provided models (default `[DEFAULT_MODEL, "gpt-5.3-codex",
+/// "gpt-5.1"]`), deduped per prompt family (first model wins). Must be called
+/// from within a tokio runtime; failures cannot occur (the fetch ladder ends
+/// in the bundled fallback), so the TS prewarm catch has no analogue.
+pub fn prewarm_codex_instructions(models: &[&str]) {
+    let candidates: Vec<String> = if models.is_empty() {
+        vec![
+            DEFAULT_MODEL.to_string(),
+            "gpt-5.3-codex".to_string(),
+            "gpt-5.1".to_string(),
+        ]
+    } else {
+        models.iter().map(|model| model.to_string()).collect()
+    };
+    let mut prewarm_targets: Vec<(ModelFamily, String)> = Vec::new();
+    for model in candidates {
+        let prompt_family = get_model_family(&model);
+        if !prewarm_targets
+            .iter()
+            .any(|(family, _)| *family == prompt_family)
+        {
+            prewarm_targets.push((prompt_family, model));
+        }
+    }
+    for (_, model) in prewarm_targets {
+        tokio::spawn(async move {
+            let _ = get_codex_instructions(Some(&model)).await;
+        });
+    }
+}
+
+/// TS `TOOL_REMAP_MESSAGE` — tool remapping instructions for host runtime
+/// tools. Byte-identical to the TS export (extracted from the template
+/// literal into `assets/tool-remap-message.txt`).
+pub const TOOL_REMAP_MESSAGE: &str = include_str!("../../assets/tool-remap-message.txt");
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use wiremock::matchers::{header, header_exists, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn reset() {
+        clear_cache_for_testing();
+        clear_source_urls_for_testing();
+    }
+
+    /// Route the module at a wiremock server hosting both the release API and
+    /// the raw prompt files.
+    async fn mount_release_api(server: &MockServer, tag: &str) {
+        Mock::given(method("GET"))
+            .and(path("/releases/latest"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(serde_json::json!({ "tag_name": tag })),
+            )
+            .mount(server)
+            .await;
+    }
+
+    fn point_at(server: &MockServer) {
+        let base = server.uri();
+        set_source_urls_for_testing(
+            &format!("{base}/releases/latest"),
+            &format!("{base}/releases/html-latest"),
+            &format!("{base}/raw"),
+        );
+    }
+
+    #[test]
+    fn tool_remap_message_matches_frozen_shape() {
+        assert!(TOOL_REMAP_MESSAGE.starts_with("<user_instructions priority=\"0\">"));
+        assert!(TOOL_REMAP_MESSAGE.contains("UPDATE_PLAN DOES NOT EXIST -> USE \"todowrite\" INSTEAD"));
+        // The TS `\${TARGET_SNIPPET}` escape resolves to a literal `${…}`.
+        assert!(TOOL_REMAP_MESSAGE.contains("${TARGET_SNIPPET}"));
+        assert!(TOOL_REMAP_MESSAGE.ends_with("</user_instructions>"));
+        assert_eq!(TOOL_REMAP_MESSAGE.len(), 3266);
+    }
+
+    #[test]
+    fn bundled_fallback_is_nonempty_instructions_text() {
+        assert!(BUNDLED_INSTRUCTIONS.starts_with("You are Codex"));
+        assert!(BUNDLED_INSTRUCTIONS.len() > 1_000);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn family_file_mappings_match_ts_tables() {
+        assert_eq!(prompt_file(ModelFamily::Gpt5Codex), "gpt_5_codex_prompt.md");
+        assert_eq!(prompt_file(ModelFamily::CodexMax), "gpt-5.1-codex-max_prompt.md");
+        assert_eq!(prompt_file(ModelFamily::Codex), "gpt_5_codex_prompt.md");
+        assert_eq!(prompt_file(ModelFamily::Gpt5_2), "gpt_5_2_prompt.md");
+        assert_eq!(prompt_file(ModelFamily::Gpt5_1), "gpt_5_1_prompt.md");
+        assert_eq!(cache_file_name(ModelFamily::Codex), "codex-instructions.md");
+        assert_eq!(
+            cache_meta_file_name(ModelFamily::Codex),
+            "codex-instructions-meta.json"
+        );
+        assert_eq!(
+            cache_meta_file_name(ModelFamily::Gpt5_2),
+            "gpt-5.2-instructions-meta.json"
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn fetches_persists_and_serves_from_memory_within_ttl() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        mount_release_api(&server, "rust-v9.9.9").await;
+        Mock::given(method("GET"))
+            .and(path("/raw/rust-v9.9.9/codex-rs/core/gpt_5_2_prompt.md"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_string("prompt body v1")
+                    .insert_header("etag", "\"etag-1\""),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        let first = get_codex_instructions(Some("gpt-5.5")).await;
+        assert_eq!(first, "prompt body v1");
+
+        // Disk cache written atomically with sha256 meta.
+        let cache_dir = get_codex_cache_dir();
+        let disk = tokio::fs::read_to_string(cache_dir.join("gpt-5.2-instructions.md"))
+            .await
+            .expect("cache file");
+        assert_eq!(disk, "prompt body v1");
+        let meta: CacheMetadata = serde_json::from_str(
+            &tokio::fs::read_to_string(cache_dir.join("gpt-5.2-instructions-meta.json"))
+                .await
+                .expect("meta file"),
+        )
+        .expect("meta parses");
+        assert_eq!(meta.etag.as_deref(), Some("\"etag-1\""));
+        assert_eq!(meta.tag, "rust-v9.9.9");
+        assert_eq!(meta.sha256.as_deref(), Some(sha256_hex("prompt body v1").as_str()));
+
+        // Second call inside the TTL is served from memory (expect(1) above
+        // fails the test if another raw fetch happens).
+        let second = get_codex_instructions(Some("gpt-5.5")).await;
+        assert_eq!(second, "prompt body v1");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn corrupt_disk_cache_is_discarded_and_refetched() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        mount_release_api(&server, "rust-v1.0.0").await;
+        Mock::given(method("GET"))
+            .and(path("/raw/rust-v1.0.0/codex-rs/core/gpt_5_2_prompt.md"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("fresh body"))
+            .expect(1)
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        // Seed a tampered cache: content no longer matches the recorded sha.
+        let cache_dir = get_codex_cache_dir();
+        tokio::fs::create_dir_all(&cache_dir).await.expect("mkdir");
+        tokio::fs::write(cache_dir.join("gpt-5.2-instructions.md"), "tampered")
+            .await
+            .expect("seed content");
+        let meta = CacheMetadata {
+            etag: Some("\"old\"".to_string()),
+            tag: "rust-v1.0.0".to_string(),
+            last_checked: now_ms(),
+            url: "u".to_string(),
+            sha256: Some(sha256_hex("original body")),
+        };
+        tokio::fs::write(
+            cache_dir.join("gpt-5.2-instructions-meta.json"),
+            stringify_compact(&meta),
+        )
+        .await
+        .expect("seed meta");
+
+        // Despite a FRESH lastChecked, the sha mismatch forces a refetch and
+        // the tampered bytes are never served.
+        let served = get_codex_instructions(Some("gpt-5.5")).await;
+        assert_eq!(served, "fresh body");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn stale_cache_revalidates_with_304_and_reserves_disk_content() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        mount_release_api(&server, "rust-v2.0.0").await;
+        Mock::given(method("GET"))
+            .and(path("/raw/rust-v2.0.0/codex-rs/core/gpt_5_2_prompt.md"))
+            .and(header("if-none-match", "\"etag-cached\""))
+            .respond_with(ResponseTemplate::new(304))
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        let cache_dir = get_codex_cache_dir();
+        tokio::fs::create_dir_all(&cache_dir).await.expect("mkdir");
+        tokio::fs::write(cache_dir.join("gpt-5.2-instructions.md"), "cached body")
+            .await
+            .expect("seed content");
+        let stale_checked = now_ms() - CACHE_TTL_MS - 1_000;
+        let meta = CacheMetadata {
+            etag: Some("\"etag-cached\"".to_string()),
+            tag: "rust-v2.0.0".to_string(),
+            last_checked: stale_checked,
+            url: "u".to_string(),
+            sha256: Some(sha256_hex("cached body")),
+        };
+        tokio::fs::write(
+            cache_dir.join("gpt-5.2-instructions-meta.json"),
+            stringify_compact(&meta),
+        )
+        .await
+        .expect("seed meta");
+
+        // Stale disk cache: served immediately (SWR) while the background
+        // refresh 304-revalidates.
+        let served = get_codex_instructions(Some("gpt-5.5")).await;
+        assert_eq!(served, "cached body");
+
+        // Drive the revalidation deterministically (the background task from
+        // the SWR path may or may not have completed; the direct call
+        // exercises the 304 + sha-verified re-serve path).
+        let revalidated = fetch_and_persist_instructions(
+            ModelFamily::Gpt5_2,
+            "gpt_5_2_prompt.md",
+            &cache_dir.join("gpt-5.2-instructions.md"),
+            &cache_dir.join("gpt-5.2-instructions-meta.json"),
+            Some(&meta),
+        )
+        .await
+        .expect("304 revalidation");
+        assert_eq!(revalidated, "cached body");
+        // lastChecked refreshed on disk.
+        let refreshed: CacheMetadata = serde_json::from_str(
+            &tokio::fs::read_to_string(cache_dir.join("gpt-5.2-instructions-meta.json"))
+                .await
+                .expect("meta"),
+        )
+        .expect("parses");
+        assert!(refreshed.last_checked > stale_checked);
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn falls_back_to_bundled_instructions_when_offline_with_no_cache() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        // Point at a server that always errors.
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .respond_with(ResponseTemplate::new(500))
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        let served = get_codex_instructions(Some("gpt-5.3-codex")).await;
+        assert_eq!(served, BUNDLED_INSTRUCTIONS);
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn legacy_meta_without_sha_forces_full_fetch_but_keeps_offline_fallback() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        mount_release_api(&server, "rust-v3.0.0").await;
+        // The full fetch fails; the legacy (unverified) disk bytes remain the
+        // offline fallback.
+        Mock::given(method("GET"))
+            .and(path("/raw/rust-v3.0.0/codex-rs/core/gpt_5_2_prompt.md"))
+            .respond_with(ResponseTemplate::new(500))
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        let cache_dir = get_codex_cache_dir();
+        tokio::fs::create_dir_all(&cache_dir).await.expect("mkdir");
+        tokio::fs::write(cache_dir.join("gpt-5.2-instructions.md"), "legacy body")
+            .await
+            .expect("seed content");
+        // Pre-upgrade meta: fresh lastChecked but NO sha256 field.
+        tokio::fs::write(
+            cache_dir.join("gpt-5.2-instructions-meta.json"),
+            format!(
+                r#"{{"etag":"\"legacy\"","tag":"rust-v3.0.0","lastChecked":{},"url":"u"}}"#,
+                now_ms()
+            ),
+        )
+        .await
+        .expect("seed meta");
+
+        let served = get_codex_instructions(Some("gpt-5.5")).await;
+        assert_eq!(served, "legacy body");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn release_tag_falls_back_to_html_scrape() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        // API broken.
+        Mock::given(method("GET"))
+            .and(path("/releases/latest"))
+            .respond_with(ResponseTemplate::new(500))
+            .mount(&server)
+            .await;
+        // HTML page (no /tag/ redirect) with the scrapeable link. The prompt
+        // fetch also carries the mandatory User-Agent (prompts-08).
+        Mock::given(method("GET"))
+            .and(path("/releases/html-latest"))
+            .and(header_exists("user-agent"))
+            .respond_with(ResponseTemplate::new(200).set_body_string(
+                r#"<a href="/openai/codex/releases/tag/rust-v7.7.7">latest</a>"#,
+            ))
+            .mount(&server)
+            .await;
+        Mock::given(method("GET"))
+            .and(path("/raw/rust-v7.7.7/codex-rs/core/gpt_5_1_prompt.md"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("g51 prompt"))
+            .mount(&server)
+            .await;
+        point_at(&server);
+
+        let served = get_codex_instructions(Some("gpt-5.1")).await;
+        assert_eq!(served, "g51 prompt");
+        reset();
+    }
+}
diff --git a/crates/request/src/prompts/fetch_utils.rs b/crates/request/src/prompts/fetch_utils.rs
new file mode 100644
index 000000000..e9dd17a4d
--- /dev/null
+++ b/crates/request/src/prompts/fetch_utils.rs
@@ -0,0 +1,354 @@
+//! Port of `lib/prompts/fetch-utils.ts` — shared, hardened fetch helpers for
+//! the GitHub-backed prompt fetchers (spec 06 / ARCHITECTURE §6.10).
+//!
+//! Both prompt sources (`prompts::codex` and `prompts::host_prompt`) pull
+//! text over the network on a request-blocking path. These helpers add the
+//! guards from the TS hardening pass (prompts-02/04/05/08):
+//! - a bounded fetch timeout so a hung GitHub connection cannot stall the
+//!   request pipeline indefinitely (prompts-02);
+//! - a maximum response size, checked against `Content-Length` and enforced
+//!   while reading, so a pathological body cannot exhaust memory (prompts-04);
+//! - rejection of empty / whitespace-only 200 bodies so a bad response is not
+//!   cached and served as "instructions" (prompts-05);
+//! - a `User-Agent` (api.github.com rejects requests without one) plus a
+//!   sensible `Accept`, applied to every request (prompts-08).
+//!
+//! Like the TS `fetchWithTimeout` AbortSignal, the fetch timeout here covers
+//! connect+headers only (the send future); body reads are guarded separately
+//! by per-chunk idle timeouts in [`read_body_text_guarded`] /
+//! [`with_body_timeout`].
+
+use std::fmt;
+use std::future::Future;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use futures::StreamExt;
+
+pub(crate) const PROMPT_FETCH_TIMEOUT_MS: u64 = 10_000;
+/// 1 MB ceiling for a prompt body.
+pub const PROMPT_FETCH_MAX_BYTES: usize = 1_000_000;
+const PROMPT_FETCH_USER_AGENT: &str = "codex-multi-auth";
+
+/// Message-carrying error for the prompt fetch helpers. The TS threw plain
+/// `Error`s; the message strings are frozen where noted.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PromptFetchError(pub String);
+
+impl PromptFetchError {
+    pub fn message(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for PromptFetchError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for PromptFetchError {}
+
+/// TS `PromptFetchOptions`. `max_bytes` exists for interface parity but (as
+/// in TS) is not consumed by [`fetch_with_timeout`] — pass it to
+/// [`read_body_text_guarded`] instead.
+#[derive(Clone, Debug, Default)]
+pub struct PromptFetchOptions {
+    pub headers: Vec<(String, String)>,
+    pub timeout_ms: Option<u64>,
+    pub max_bytes: Option<usize>,
+    /// When true, also request GitHub's JSON API content type.
+    pub json: bool,
+}
+
+fn shared_client() -> &'static reqwest::Client {
+    static CLIENT: OnceLock<reqwest::Client> = OnceLock::new();
+    CLIENT.get_or_init(|| {
+        reqwest::Client::builder()
+            .build()
+            .expect("prompt fetch client")
+    })
+}
+
+/// TS `withPromptFetchHeaders(headers, json)`.
+///
+/// Merges caller headers with the mandatory `User-Agent` / `Accept` defaults.
+/// The mandatory headers are applied AFTER the caller's so they always win: a
+/// caller must not be able to blank or replace them and bypass the hardening
+/// (api.github.com rejects requests without a User-Agent). Caller headers are
+/// still honored for everything else (e.g. `If-None-Match`).
+pub fn with_prompt_fetch_headers(
+    headers: &[(String, String)],
+    json: bool,
+) -> Vec<(String, String)> {
+    let mut merged: Vec<(String, String)> = headers
+        .iter()
+        .filter(|(name, _)| {
+            !name.eq_ignore_ascii_case("user-agent") && !name.eq_ignore_ascii_case("accept")
+        })
+        .cloned()
+        .collect();
+    merged.push(("User-Agent".to_string(), PROMPT_FETCH_USER_AGENT.to_string()));
+    merged.push((
+        "Accept".to_string(),
+        if json {
+            "application/vnd.github+json".to_string()
+        } else {
+            "text/plain, */*".to_string()
+        },
+    ));
+    merged
+}
+
+/// TS `fetchWithTimeout(url, options)` — GET with a bounded timeout covering
+/// connect+headers. Returns the `Response` (caller inspects status). Throws
+/// on timeout/network error, matching native fetch rejection semantics.
+/// Redirects are followed (the final URL is available via `response.url()`).
+pub async fn fetch_with_timeout(
+    url: &str,
+    options: &PromptFetchOptions,
+) -> Result<reqwest::Response, PromptFetchError> {
+    let timeout_ms = options.timeout_ms.unwrap_or(PROMPT_FETCH_TIMEOUT_MS);
+    let mut request = shared_client().get(url);
+    for (name, value) in with_prompt_fetch_headers(&options.headers, options.json) {
+        request = request.header(name, value);
+    }
+    match tokio::time::timeout(Duration::from_millis(timeout_ms), request.send()).await {
+        Ok(Ok(response)) => Ok(response),
+        Ok(Err(error)) => Err(PromptFetchError(error.to_string())),
+        Err(_elapsed) => Err(PromptFetchError(format!(
+            "fetch timed out after {timeout_ms}ms"
+        ))),
+    }
+}
+
+/// TS `withBodyTimeout(response, read, timeoutMs?)` — race a response-body
+/// read against a bounded timeout. `fetch_with_timeout`'s deadline only
+/// covers connect+headers, so a server that sends headers then stalls
+/// mid-body would otherwise hang a request-blocking path forever. Dropping
+/// the losing read future tears down the underlying stream (the Rust
+/// analogue of the TS `body.cancel()`).
+pub async fn with_body_timeout<T, Fut>(
+    read: Fut,
+    timeout_ms: Option<u64>,
+) -> Result<T, PromptFetchError>
+where
+    Fut: Future<Output = T>,
+{
+    let timeout_ms = timeout_ms.unwrap_or(PROMPT_FETCH_TIMEOUT_MS);
+    match tokio::time::timeout(Duration::from_millis(timeout_ms), read).await {
+        Ok(value) => Ok(value),
+        Err(_elapsed) => Err(PromptFetchError(format!(
+            "response body read timed out after {timeout_ms}ms"
+        ))),
+    }
+}
+
+/// TS `readBodyTextGuarded(response, maxBytes?, timeoutMs?)`.
+///
+/// Reads a response body as text with a size ceiling, rejecting empty bodies.
+/// Checks `Content-Length` first (fast reject), then enforces the cap while
+/// streaming so a server that omits/understates the header still cannot
+/// exceed the limit. Each chunk read is raced against a per-chunk idle
+/// timeout (prompts-02) — a chunk resets the budget; a quiet gap longer than
+/// `timeout_ms` aborts. Frozen error messages:
+/// - `"prompt body too large: Content-Length {n} exceeds {max}"`
+/// - `"prompt body too large: exceeded {max} bytes"`
+/// - `"prompt body read timed out after {ms}ms"`
+/// - `"prompt body was empty"`
+pub async fn read_body_text_guarded(
+    response: reqwest::Response,
+    max_bytes: Option<usize>,
+    timeout_ms: Option<u64>,
+) -> Result<String, PromptFetchError> {
+    let max_bytes = max_bytes.unwrap_or(PROMPT_FETCH_MAX_BYTES);
+    let timeout_ms = timeout_ms.unwrap_or(PROMPT_FETCH_TIMEOUT_MS);
+
+    if let Some(declared) = response
+        .headers()
+        .get(http::header::CONTENT_LENGTH)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.trim().parse::<u64>().ok())
+        && declared > max_bytes as u64
+    {
+        return Err(PromptFetchError(format!(
+            "prompt body too large: Content-Length {declared} exceeds {max_bytes}"
+        )));
+    }
+
+    let mut stream = response.bytes_stream();
+    let mut chunks: Vec<u8> = Vec::new();
+    loop {
+        let next =
+            match tokio::time::timeout(Duration::from_millis(timeout_ms), stream.next()).await {
+                Ok(item) => item,
+                Err(_elapsed) => {
+                    return Err(PromptFetchError(format!(
+                        "prompt body read timed out after {timeout_ms}ms"
+                    )));
+                }
+            };
+        match next {
+            None => break,
+            Some(Err(error)) => return Err(PromptFetchError(error.to_string())),
+            Some(Ok(chunk)) => {
+                if chunks.len() + chunk.len() > max_bytes {
+                    return Err(PromptFetchError(format!(
+                        "prompt body too large: exceeded {max_bytes} bytes"
+                    )));
+                }
+                chunks.extend_from_slice(&chunk);
+            }
+        }
+    }
+
+    let text = String::from_utf8_lossy(&chunks).into_owned();
+    if text.trim().is_empty() {
+        return Err(PromptFetchError("prompt body was empty".to_string()));
+    }
+    Ok(text)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wiremock::matchers::{header, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    #[test]
+    fn mandatory_headers_always_win() {
+        let merged = with_prompt_fetch_headers(
+            &[
+                ("User-Agent".to_string(), "evil".to_string()),
+                ("accept".to_string(), "nope".to_string()),
+                ("If-None-Match".to_string(), "\"etag\"".to_string()),
+            ],
+            false,
+        );
+        let ua: Vec<_> = merged
+            .iter()
+            .filter(|(n, _)| n.eq_ignore_ascii_case("user-agent"))
+            .collect();
+        assert_eq!(ua, vec![&("User-Agent".to_string(), "codex-multi-auth".to_string())]);
+        let accept: Vec<_> = merged
+            .iter()
+            .filter(|(n, _)| n.eq_ignore_ascii_case("accept"))
+            .collect();
+        assert_eq!(accept.len(), 1);
+        assert_eq!(accept[0].1, "text/plain, */*");
+        assert!(merged
+            .iter()
+            .any(|(n, v)| n == "If-None-Match" && v == "\"etag\""));
+    }
+
+    #[test]
+    fn json_mode_requests_the_github_api_content_type() {
+        let merged = with_prompt_fetch_headers(&[], true);
+        assert!(merged
+            .iter()
+            .any(|(n, v)| n == "Accept" && v == "application/vnd.github+json"));
+    }
+
+    #[tokio::test]
+    async fn fetch_sends_user_agent_and_reads_bodies() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/prompt.txt"))
+            .and(header("user-agent", "codex-multi-auth"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("hello prompt"))
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let response = fetch_with_timeout(
+            &format!("{}/prompt.txt", server.uri()),
+            &PromptFetchOptions::default(),
+        )
+        .await
+        .expect("fetch ok");
+        assert_eq!(response.status(), 200);
+        let text = read_body_text_guarded(response, None, None)
+            .await
+            .expect("body ok");
+        assert_eq!(text, "hello prompt");
+    }
+
+    #[tokio::test]
+    async fn rejects_oversize_bodies_while_streaming() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/big"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("x".repeat(64)))
+            .mount(&server)
+            .await;
+
+        let response = fetch_with_timeout(
+            &format!("{}/big", server.uri()),
+            &PromptFetchOptions::default(),
+        )
+        .await
+        .expect("fetch ok");
+        let err = read_body_text_guarded(response, Some(16), None)
+            .await
+            .expect_err("oversize");
+        // Content-Length fast-reject fires first when the header is present.
+        assert!(
+            err.message() == "prompt body too large: Content-Length 64 exceeds 16"
+                || err.message() == "prompt body too large: exceeded 16 bytes",
+            "unexpected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn rejects_empty_and_whitespace_only_bodies() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/empty"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("   \n  "))
+            .mount(&server)
+            .await;
+
+        let response = fetch_with_timeout(
+            &format!("{}/empty", server.uri()),
+            &PromptFetchOptions::default(),
+        )
+        .await
+        .expect("fetch ok");
+        let err = read_body_text_guarded(response, None, None)
+            .await
+            .expect_err("empty body");
+        assert_eq!(err.message(), "prompt body was empty");
+    }
+
+    #[tokio::test]
+    async fn fetch_times_out_against_unresponsive_servers() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/slow"))
+            .respond_with(ResponseTemplate::new(200).set_delay(Duration::from_secs(10)))
+            .mount(&server)
+            .await;
+
+        let err = fetch_with_timeout(
+            &format!("{}/slow", server.uri()),
+            &PromptFetchOptions {
+                timeout_ms: Some(50),
+                ..Default::default()
+            },
+        )
+        .await
+        .expect_err("timeout");
+        assert_eq!(err.message(), "fetch timed out after 50ms");
+    }
+
+    #[tokio::test]
+    async fn with_body_timeout_rejects_stalled_reads() {
+        let err = with_body_timeout(std::future::pending::<String>(), Some(20))
+            .await
+            .expect_err("stalled");
+        assert_eq!(err.message(), "response body read timed out after 20ms");
+
+        let ok = with_body_timeout(async { 7usize }, Some(1_000)).await;
+        assert_eq!(ok, Ok(7));
+    }
+}
diff --git a/crates/request/src/prompts/host_bridge.rs b/crates/request/src/prompts/host_bridge.rs
new file mode 100644
index 000000000..ebf74a450
--- /dev/null
+++ b/crates/request/src/prompts/host_bridge.rs
@@ -0,0 +1,36 @@
+//! Port of `lib/prompts/codex-host-bridge.ts` — the static Codex host-bridge
+//! prompt (spec 06 §0 cross-module imports; consumed by the request
+//! transformer's `add_codex_bridge_message`).
+//!
+//! The text bridges Codex CLI instructions to the host runtime environment:
+//! tool mappings, available-tools list, substitution rules, and the
+//! verification checklist (~450 tokens, ~90% smaller than the full host
+//! prompt).
+//!
+//! The bytes are FROZEN: `assets/codex-host-bridge.txt` was extracted verbatim
+//! from the TS template literal (escape sequences resolved). Do not edit the
+//! asset by hand — regenerate it from the TS source if upstream changes.
+
+/// TS `CODEX_HOST_BRIDGE` — byte-identical to the TS export.
+pub const CODEX_HOST_BRIDGE: &str = include_str!("../../assets/codex-host-bridge.txt");
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bridge_prompt_matches_frozen_shape() {
+        assert!(CODEX_HOST_BRIDGE.starts_with("# Codex Host Bridge\n"));
+        // Resolved escapes from the TS template literal must be present.
+        assert!(CODEX_HOST_BRIDGE.contains("(e.g. `${TARGET_SNIPPET}`)"));
+        assert!(
+            CODEX_HOST_BRIDGE.contains("UPDATE_PLAN DOES NOT EXIST -> USE \"todowrite\" INSTEAD")
+        );
+        assert!(CODEX_HOST_BRIDGE
+            .contains("`request_user_input` is Plan-mode only; do not call it in Default mode."));
+        // No trailing newline: the TS literal ends right after the final ")."
+        assert!(CODEX_HOST_BRIDGE.ends_with("then delete with `bash`)."));
+        // Byte budget sanity (extraction produced 7418 UTF-8 bytes).
+        assert_eq!(CODEX_HOST_BRIDGE.len(), 7418);
+    }
+}
diff --git a/crates/request/src/prompts/host_prompt.rs b/crates/request/src/prompts/host_prompt.rs
new file mode 100644
index 000000000..5b045d59a
--- /dev/null
+++ b/crates/request/src/prompts/host_prompt.rs
@@ -0,0 +1,836 @@
+//! Port of `lib/prompts/host-codex-prompt.ts` — the sst/opencode `codex.txt`
+//! host-prompt cache (spec 06 / ARCHITECTURE §6.10).
+//!
+//! Fetches and caches the `codex.txt` system prompt from upstream GitHub
+//! sources with ETag-based conditional requests, a 15-minute TTL,
+//! stale-while-revalidate, an env-var source override, and a one-time
+//! migration of the two legacy cache file pairs.
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use chrono::SecondsFormat;
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::logger::log_debug;
+use cma_core::runtime_paths::get_codex_cache_dir;
+use cma_core::temp_path::temp_file_nonce;
+use cma_core::utils::now_ms;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+
+use super::fetch_utils::{PromptFetchOptions, fetch_with_timeout, read_body_text_guarded};
+
+/// Canonical upstream is sst/opencode; only the `dev` branch `codex.txt` is
+/// known-good (verified 2026-05-31) — `main` is kept as a cheap self-healing
+/// fallback in case the branch layout changes upstream.
+const DEFAULT_HOST_CODEX_PROMPT_URLS: [&str; 2] = [
+    "https://raw.githubusercontent.com/sst/opencode/dev/packages/opencode/src/session/prompt/codex.txt",
+    "https://raw.githubusercontent.com/sst/opencode/main/packages/opencode/src/session/prompt/codex.txt",
+];
+const CODEX_PROMPT_URL_OVERRIDE_ENV: &str = "CODEX_PROMPT_SOURCE_URL";
+const LEGACY_HOST_CODEX_URL_OVERRIDE_ENV: &str = "CODEX_CODEX_PROMPT_URL";
+const CACHE_FILE_NAME: &str = "host-codex-prompt.txt";
+const CACHE_META_FILE_NAME: &str = "host-codex-prompt-meta.json";
+/// Legacy cache file pairs, migrated to the current names on first read.
+const LEGACY_CACHE_FILES: [(&str, &str); 2] = [
+    ("opencode-codex-prompt.txt", "opencode-codex-prompt-meta.json"),
+    ("codex-prompt.txt", "codex-prompt-meta.json"),
+];
+const CACHE_TTL_MS: i64 = 15 * 60 * 1000;
+const RETRYABLE_FS_ERROR_CODES: [&str; 2] = ["EBUSY", "EPERM"];
+const WRITE_RETRY_ATTEMPTS: u32 = 5;
+const WRITE_RETRY_BASE_DELAY_MS: u64 = 10;
+
+/// TS `CacheMeta` — the on-disk meta shape (2-space pretty JSON, no trailing
+/// newline). `lastFetch` / `sourceUrl` are legacy fields kept for
+/// compatibility reads; serde field order = TS write order.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HostPromptCacheMeta {
+    /// Tolerant read: a legacy meta without `etag` becomes `""` (falsy in the
+    /// TS conditional-request gate).
+    #[serde(default)]
+    pub etag: String,
+    /// Legacy field for backwards compatibility.
+    #[serde(rename = "lastFetch", default, skip_serializing_if = "Option::is_none")]
+    pub last_fetch: Option<String>,
+    /// Timestamp for rate-limit protection; `0` (or absent) invalidates the
+    /// snapshot on read, matching the TS truthiness check.
+    #[serde(rename = "lastChecked", default)]
+    pub last_checked: i64,
+    #[serde(rename = "sourceKey", default, skip_serializing_if = "Option::is_none")]
+    pub source_key: Option<String>,
+    /// Legacy field kept for compatibility reads.
+    #[serde(rename = "sourceUrl", default, skip_serializing_if = "Option::is_none")]
+    pub source_url: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+struct CacheSnapshot {
+    content: String,
+    meta: HostPromptCacheMeta,
+}
+
+static MEMORY_CACHE: Mutex<Option<CacheSnapshot>> = Mutex::new(None);
+static REFRESH_IN_FLIGHT: Mutex<bool> = Mutex::new(false);
+#[cfg(test)]
+static DEFAULT_SOURCES_OVERRIDE: Mutex<Option<Vec<String>>> = Mutex::new(None);
+
+/// Reset the in-process caches (memory snapshot + refresh flag) for tests.
+pub fn reset_host_prompt_cache_for_testing() {
+    *MEMORY_CACHE.lock().expect("host prompt cache poisoned") = None;
+    *REFRESH_IN_FLIGHT.lock().expect("refresh flag poisoned") = false;
+    #[cfg(test)]
+    {
+        *DEFAULT_SOURCES_OVERRIDE
+            .lock()
+            .expect("default sources poisoned") = None;
+    }
+}
+
+#[cfg(test)]
+fn set_default_sources_for_testing(sources: Vec<String>) {
+    *DEFAULT_SOURCES_OVERRIDE
+        .lock()
+        .expect("default sources poisoned") = Some(sources);
+}
+
+fn default_sources() -> Vec<String> {
+    #[cfg(test)]
+    if let Some(overridden) = DEFAULT_SOURCES_OVERRIDE
+        .lock()
+        .expect("default sources poisoned")
+        .clone()
+    {
+        return overridden;
+    }
+    DEFAULT_HOST_CODEX_PROMPT_URLS
+        .iter()
+        .map(|url| url.to_string())
+        .collect()
+}
+
+fn cache_file_path() -> PathBuf {
+    get_codex_cache_dir().join(CACHE_FILE_NAME)
+}
+
+fn cache_meta_file_path() -> PathBuf {
+    get_codex_cache_dir().join(CACHE_META_FILE_NAME)
+}
+
+fn is_fresh(last_checked: i64) -> bool {
+    now_ms() - last_checked < CACHE_TTL_MS
+}
+
+/// TS `redactSourceForLog` — origin + pathname (no query/credentials);
+/// invalid URLs become `"<invalid-url>"`.
+fn redact_source_for_log(source: &str) -> String {
+    match url::Url::parse(source) {
+        Ok(parsed) => format!("{}{}", parsed.origin().ascii_serialization(), parsed.path()),
+        Err(_) => "<invalid-url>".to_string(),
+    }
+}
+
+/// TS `parseSourceUrl` — trimmed, must parse as an http(s) URL; anything else
+/// is ignored with a debug log.
+fn parse_source_url(source: Option<&str>) -> Option<String> {
+    let trimmed = source?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    match url::Url::parse(trimmed) {
+        Ok(parsed) => {
+            if parsed.scheme() != "http" && parsed.scheme() != "https" {
+                log_debug(
+                    "Ignoring codex prompt source override due to protocol",
+                    Some(&json!({ "source": redact_source_for_log(trimmed) })),
+                );
+                return None;
+            }
+            Some(trimmed.to_string())
+        }
+        Err(_) => {
+            log_debug(
+                "Ignoring invalid codex prompt source override",
+                Some(&json!({ "source": redact_source_for_log(trimmed) })),
+            );
+            None
+        }
+    }
+}
+
+/// TS `sourceCacheKey` — origin + pathname; unparseable sources fall back to
+/// the trimmed raw string.
+fn source_cache_key(source: &str) -> String {
+    match url::Url::parse(source) {
+        Ok(parsed) => format!("{}{}", parsed.origin().ascii_serialization(), parsed.path()),
+        Err(_) => source.trim().to_string(),
+    }
+}
+
+/// TS `resolvePromptSources` — env override first (current then legacy env
+/// name), then the defaults, deduped.
+fn resolve_prompt_sources() -> Vec<String> {
+    let mut sources: Vec<String> = Vec::new();
+    let mut add = |candidate: Option<String>| {
+        if let Some(parsed) = parse_source_url(candidate.as_deref())
+            && !sources.contains(&parsed)
+        {
+            sources.push(parsed);
+        }
+    };
+    add(std::env::var(CODEX_PROMPT_URL_OVERRIDE_ENV).ok());
+    add(std::env::var(LEGACY_HOST_CODEX_URL_OVERRIDE_ENV).ok());
+    for source in default_sources() {
+        add(Some(source));
+    }
+    sources
+}
+
+fn write_retry_options() -> RetryOptions<std::io::Error> {
+    RetryOptions::new(
+        WRITE_RETRY_ATTEMPTS,
+        Backoff::from_fn(|failed_attempt| {
+            WRITE_RETRY_BASE_DELAY_MS
+                .saturating_mul(2u64.saturating_pow(failed_attempt.saturating_sub(1)))
+        }),
+    )
+    .with_codes(&RETRYABLE_FS_ERROR_CODES)
+}
+
+/// TS `writeFileWithRetry` — EBUSY/EPERM x5, 10 ms doubling backoff.
+async fn write_file_with_retry(file_path: &Path, content: &str) -> Result<(), std::io::Error> {
+    with_retry(
+        || tokio::fs::write(file_path, content.as_bytes()),
+        write_retry_options(),
+    )
+    .await
+}
+
+/// TS `renameWithRetry` — same retry policy as writes.
+async fn rename_with_retry(from_path: &Path, to_path: &Path) -> Result<(), std::io::Error> {
+    with_retry(
+        || tokio::fs::rename(from_path, to_path),
+        write_retry_options(),
+    )
+    .await
+}
+
+/// TS `removeFileQuietly` — best-effort cleanup only.
+async fn remove_file_quietly(path: &Path) {
+    let _ = tokio::fs::remove_file(path).await;
+}
+
+/// TS `writeCacheFilesAtomically` — temp-sibling writes, content rename
+/// before meta rename, partial-rename recovery by rewriting the content file,
+/// temp cleanup on failure.
+async fn write_cache_files_atomically(
+    content: &str,
+    meta: &HostPromptCacheMeta,
+) -> Result<(), std::io::Error> {
+    let cache_dir = get_codex_cache_dir();
+    tokio::fs::create_dir_all(&cache_dir).await?;
+
+    let cache_file = cache_file_path();
+    let cache_meta_file = cache_meta_file_path();
+    let nonce = temp_file_nonce();
+    let content_tmp = PathBuf::from(format!("{}.{nonce}.tmp", cache_file.display()));
+    let meta_tmp = PathBuf::from(format!("{}.{nonce}.tmp", cache_meta_file.display()));
+    let meta_json = stringify_pretty2(meta);
+
+    write_file_with_retry(&content_tmp, content).await?;
+    if let Err(error) = write_file_with_retry(&meta_tmp, &meta_json).await {
+        remove_file_quietly(&content_tmp).await;
+        return Err(error);
+    }
+
+    let mut renamed_content = false;
+    let rename_result: Result<(), std::io::Error> = async {
+        rename_with_retry(&content_tmp, &cache_file).await?;
+        renamed_content = true;
+        rename_with_retry(&meta_tmp, &cache_meta_file).await?;
+        Ok(())
+    }
+    .await;
+    if let Err(error) = rename_result {
+        if renamed_content {
+            // Only one rename succeeded: restore consistency by rewriting the
+            // content file so it matches whatever meta remains on disk.
+            if let Err(recovery_error) = write_file_with_retry(&cache_file, content).await {
+                log_debug(
+                    "Failed to restore host-codex prompt content after partial rename failure",
+                    Some(&json!({ "error": recovery_error.to_string() })),
+                );
+            }
+        }
+        remove_file_quietly(&content_tmp).await;
+        remove_file_quietly(&meta_tmp).await;
+        return Err(error);
+    }
+    Ok(())
+}
+
+async fn try_read_pair(content_path: &Path, meta_path: &Path) -> Option<CacheSnapshot> {
+    let content = tokio::fs::read_to_string(content_path).await.ok()?;
+    let meta_content = tokio::fs::read_to_string(meta_path).await.ok()?;
+    let meta: HostPromptCacheMeta = serde_json::from_str(&meta_content).ok()?;
+    if meta.last_checked == 0 {
+        return None;
+    }
+    Some(CacheSnapshot { content, meta })
+}
+
+/// TS `readDiskCache` — current pair first, then the legacy pairs (migrating
+/// a legacy hit to the current file names; migration failure only debug-logs
+/// and the legacy snapshot is still used in memory).
+async fn read_disk_cache() -> Option<CacheSnapshot> {
+    if let Some(current) = try_read_pair(&cache_file_path(), &cache_meta_file_path()).await {
+        return Some(current);
+    }
+    let cache_dir = get_codex_cache_dir();
+    for (legacy_content, legacy_meta) in LEGACY_CACHE_FILES {
+        let Some(legacy_cache) =
+            try_read_pair(&cache_dir.join(legacy_content), &cache_dir.join(legacy_meta)).await
+        else {
+            continue;
+        };
+        if let Err(error) =
+            write_cache_files_atomically(&legacy_cache.content, &legacy_cache.meta).await
+        {
+            log_debug(
+                "Failed to migrate legacy host-codex prompt cache; using legacy cache in memory",
+                Some(&json!({ "error": error.to_string() })),
+            );
+        }
+        return Some(legacy_cache);
+    }
+    None
+}
+
+fn now_iso() -> String {
+    chrono::Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true)
+}
+
+/// TS `saveDiskCache`.
+async fn save_disk_cache(
+    content: &str,
+    etag: &str,
+    source_url: &str,
+) -> Result<HostPromptCacheMeta, std::io::Error> {
+    let meta = HostPromptCacheMeta {
+        etag: etag.to_string(),
+        last_fetch: Some(now_iso()),
+        last_checked: now_ms(),
+        source_key: Some(source_cache_key(source_url)),
+        source_url: None,
+    };
+    write_cache_files_atomically(content, &meta).await?;
+    Ok(meta)
+}
+
+/// TS `refreshPrompt(cachedMeta, cachedContent)` — walk the source list;
+/// conditional requests only against the source that produced the cached
+/// etag; 304 re-serves the cached content and refreshes only the meta file;
+/// a guarded 200 body persists atomically. All sources failing yields
+/// `"Failed to fetch codex prompt from all sources (...)"`.
+async fn refresh_prompt(
+    cached_meta: Option<&HostPromptCacheMeta>,
+    cached_content: Option<&str>,
+) -> Result<String, String> {
+    let sources = resolve_prompt_sources();
+    let mut last_failure: Option<String> = None;
+
+    for source_url in sources {
+        let current_source_key = source_cache_key(&source_url);
+        let cached_source_key: Option<String> = cached_meta.and_then(|meta| {
+            meta.source_key.clone().or_else(|| {
+                meta.source_url
+                    .as_deref()
+                    .map(source_cache_key)
+            })
+        });
+        let cached_etag = cached_meta
+            .map(|meta| meta.etag.as_str())
+            .filter(|etag| !etag.is_empty());
+        let can_use_conditional_request = cached_etag.is_some()
+            && cached_source_key
+                .as_deref()
+                .is_none_or(|key| key == current_source_key);
+        let mut headers: Vec<(String, String)> = Vec::new();
+        if can_use_conditional_request
+            && let Some(etag) = cached_etag
+        {
+            headers.push(("If-None-Match".to_string(), etag.to_string()));
+        }
+
+        let response = match fetch_with_timeout(
+            &source_url,
+            &PromptFetchOptions {
+                headers,
+                ..Default::default()
+            },
+        )
+        .await
+        {
+            Ok(response) => response,
+            Err(error) => {
+                last_failure = Some(format!("{}: {error}", redact_source_for_log(&source_url)));
+                log_debug(
+                    "Codex prompt source fetch failed",
+                    Some(&json!({
+                        "sourceUrl": redact_source_for_log(&source_url),
+                        "error": error.to_string(),
+                    })),
+                );
+                continue;
+            }
+        };
+
+        if response.status() == reqwest::StatusCode::NOT_MODIFIED
+            && let Some(content) = cached_content
+        {
+            let refreshed_meta = HostPromptCacheMeta {
+                etag: cached_meta.map(|meta| meta.etag.clone()).unwrap_or_default(),
+                last_fetch: cached_meta
+                    .and_then(|meta| meta.last_fetch.clone())
+                    .or_else(|| Some(now_iso())),
+                last_checked: now_ms(),
+                source_key: Some(current_source_key),
+                source_url: None,
+            };
+            *MEMORY_CACHE.lock().expect("host prompt cache poisoned") = Some(CacheSnapshot {
+                content: content.to_string(),
+                meta: refreshed_meta.clone(),
+            });
+            // 304 refreshes only the meta file (lastChecked), like the TS.
+            let _ = tokio::fs::create_dir_all(get_codex_cache_dir()).await;
+            write_file_with_retry(&cache_meta_file_path(), &stringify_pretty2(&refreshed_meta))
+                .await
+                .map_err(|error| error.to_string())?;
+            return Ok(content.to_string());
+        }
+
+        if !response.status().is_success() {
+            let status = response.status().as_u16();
+            last_failure = Some(format!(
+                "{}: HTTP {status}",
+                redact_source_for_log(&source_url)
+            ));
+            log_debug(
+                "Codex prompt source returned non-OK response",
+                Some(&json!({
+                    "sourceUrl": redact_source_for_log(&source_url),
+                    "status": status,
+                })),
+            );
+            continue;
+        }
+
+        let etag = response
+            .headers()
+            .get("etag")
+            .and_then(|value| value.to_str().ok())
+            .unwrap_or("")
+            .to_string();
+        // Size-cap + reject empty bodies (prompts-04/05): a truncated or
+        // empty 200 must not be cached and served as instructions.
+        let content = match read_body_text_guarded(response, None, None).await {
+            Ok(content) => content,
+            Err(error) => {
+                last_failure = Some(format!("{}: {error}", redact_source_for_log(&source_url)));
+                log_debug(
+                    "Codex prompt source body rejected",
+                    Some(&json!({
+                        "sourceUrl": redact_source_for_log(&source_url),
+                        "error": error.to_string(),
+                    })),
+                );
+                continue;
+            }
+        };
+        let meta = save_disk_cache(&content, &etag, &source_url)
+            .await
+            .map_err(|error| error.to_string())?;
+        *MEMORY_CACHE.lock().expect("host prompt cache poisoned") = Some(CacheSnapshot {
+            content: content.clone(),
+            meta,
+        });
+        return Ok(content);
+    }
+
+    Err(match last_failure {
+        Some(failure) => format!("Failed to fetch codex prompt from all sources ({failure})"),
+        None => "Failed to fetch codex prompt from all sources".to_string(),
+    })
+}
+
+/// TS `scheduleRefresh` — single-flight background refresh; failures only
+/// debug-log.
+fn schedule_refresh(cached_meta: Option<HostPromptCacheMeta>, cached_content: Option<String>) {
+    {
+        let mut in_flight = REFRESH_IN_FLIGHT.lock().expect("refresh flag poisoned");
+        if *in_flight {
+            return;
+        }
+        *in_flight = true;
+    }
+    tokio::spawn(async move {
+        if let Err(error) = refresh_prompt(cached_meta.as_ref(), cached_content.as_deref()).await {
+            log_debug(
+                "Codex prompt background refresh failed",
+                Some(&json!({ "error": error })),
+            );
+        }
+        *REFRESH_IN_FLIGHT.lock().expect("refresh flag poisoned") = false;
+    });
+}
+
+/// TS `getHostCodexPrompt()` — cache ladder: fresh memory → disk (fresh
+/// serve / stale-while-revalidate with a bumped in-memory `lastChecked`) →
+/// foreground refresh → stale memory → error
+/// `"Failed to fetch codex.txt and no cache available: {error}"`.
+pub async fn get_host_codex_prompt() -> Result<String, String> {
+    {
+        let memory = MEMORY_CACHE.lock().expect("host prompt cache poisoned");
+        if let Some(snapshot) = memory.as_ref()
+            && is_fresh(snapshot.meta.last_checked)
+        {
+            return Ok(snapshot.content.clone());
+        }
+    }
+
+    if let Some(disk_cache) = read_disk_cache().await {
+        if is_fresh(disk_cache.meta.last_checked) {
+            *MEMORY_CACHE.lock().expect("host prompt cache poisoned") = Some(disk_cache.clone());
+            return Ok(disk_cache.content);
+        }
+        // Serve stale content immediately and refresh in the background.
+        *MEMORY_CACHE.lock().expect("host prompt cache poisoned") = Some(CacheSnapshot {
+            content: disk_cache.content.clone(),
+            meta: HostPromptCacheMeta {
+                last_checked: now_ms(),
+                ..disk_cache.meta.clone()
+            },
+        });
+        schedule_refresh(Some(disk_cache.meta.clone()), Some(disk_cache.content.clone()));
+        return Ok(disk_cache.content);
+    }
+
+    let (memory_meta, memory_content) = {
+        let memory = MEMORY_CACHE.lock().expect("host prompt cache poisoned");
+        (
+            memory.as_ref().map(|snapshot| snapshot.meta.clone()),
+            memory.as_ref().map(|snapshot| snapshot.content.clone()),
+        )
+    };
+    match refresh_prompt(memory_meta.as_ref(), memory_content.as_deref()).await {
+        Ok(content) => Ok(content),
+        Err(error) => {
+            let stale_content = MEMORY_CACHE
+                .lock()
+                .expect("host prompt cache poisoned")
+                .as_ref()
+                .map(|snapshot| snapshot.content.clone());
+            if let Some(stale) = stale_content {
+                return Ok(stale);
+            }
+            Err(format!(
+                "Failed to fetch codex.txt and no cache available: {error}"
+            ))
+        }
+    }
+}
+
+/// TS `getCachedPromptPrefix(chars = 50)` — first N characters of the cached
+/// prompt for verification, `None` when not cached.
+pub async fn get_cached_prompt_prefix(chars: usize) -> Option<String> {
+    let content = tokio::fs::read_to_string(cache_file_path()).await.ok()?;
+    Some(content.chars().take(chars).collect())
+}
+
+/// TS `prewarmHostCodexPrompt()` — prewarm the cache without blocking
+/// startup. Must be called from within a tokio runtime.
+pub fn prewarm_host_codex_prompt() {
+    tokio::spawn(async {
+        if let Err(error) = get_host_codex_prompt().await {
+            log_debug(
+                "Codex prompt prewarm failed",
+                Some(&json!({ "error": error })),
+            );
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use wiremock::matchers::{header, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    fn reset() {
+        reset_host_prompt_cache_for_testing();
+    }
+
+    #[test]
+    #[serial(env)]
+    fn parses_and_redacts_source_overrides() {
+        let _sandbox = EnvSandbox::new();
+        assert_eq!(
+            parse_source_url(Some("  https://example.com/a.txt?x=1  ")),
+            Some("https://example.com/a.txt?x=1".to_string())
+        );
+        assert_eq!(parse_source_url(Some("ftp://example.com/a.txt")), None);
+        assert_eq!(parse_source_url(Some("not a url")), None);
+        assert_eq!(parse_source_url(Some("   ")), None);
+        assert_eq!(parse_source_url(None), None);
+        assert_eq!(
+            redact_source_for_log("https://user:pw@example.com/a.txt?secret=1"),
+            "https://example.com/a.txt"
+        );
+        assert_eq!(redact_source_for_log("nope"), "<invalid-url>");
+        assert_eq!(
+            source_cache_key("https://example.com/a.txt?x=1"),
+            "https://example.com/a.txt"
+        );
+        assert_eq!(source_cache_key(" raw-key "), "raw-key");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn env_override_wins_and_dedupes() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var(CODEX_PROMPT_URL_OVERRIDE_ENV, "https://override.example/codex.txt");
+        sandbox.set_var(
+            LEGACY_HOST_CODEX_URL_OVERRIDE_ENV,
+            "https://override.example/codex.txt",
+        );
+        let sources = resolve_prompt_sources();
+        assert_eq!(sources[0], "https://override.example/codex.txt");
+        // Deduped: the legacy env duplicate is dropped; defaults follow.
+        assert_eq!(
+            sources.len(),
+            1 + DEFAULT_HOST_CODEX_PROMPT_URLS.len(),
+            "sources: {sources:?}"
+        );
+        assert_eq!(sources[1], DEFAULT_HOST_CODEX_PROMPT_URLS[0]);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn fetches_persists_and_serves_within_ttl() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/codex.txt"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_string("host prompt body")
+                    .insert_header("etag", "\"h-1\""),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        set_default_sources_for_testing(vec![format!("{}/codex.txt", server.uri())]);
+
+        let first = get_host_codex_prompt().await.expect("fetch ok");
+        assert_eq!(first, "host prompt body");
+
+        // Disk cache written (content + pretty-2 meta, no trailing newline).
+        let disk = tokio::fs::read_to_string(cache_file_path())
+            .await
+            .expect("content file");
+        assert_eq!(disk, "host prompt body");
+        let meta_raw = tokio::fs::read_to_string(cache_meta_file_path())
+            .await
+            .expect("meta file");
+        assert!(!meta_raw.ends_with('\n'));
+        let meta: HostPromptCacheMeta = serde_json::from_str(&meta_raw).expect("meta parses");
+        assert_eq!(meta.etag, "\"h-1\"");
+        assert!(meta.source_key.as_deref().unwrap().ends_with("/codex.txt"));
+        assert!(meta.last_checked > 0);
+
+        // Second call is memory-served (expect(1) enforces no refetch).
+        let second = get_host_codex_prompt().await.expect("memory hit");
+        assert_eq!(second, "host prompt body");
+
+        // Prefix helper reads the cache file.
+        assert_eq!(
+            get_cached_prompt_prefix(4).await.as_deref(),
+            Some("host")
+        );
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn revalidates_stale_cache_with_304_and_keeps_content() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/codex.txt"))
+            .and(header("if-none-match", "\"h-cached\""))
+            .respond_with(ResponseTemplate::new(304))
+            .mount(&server)
+            .await;
+        let source = format!("{}/codex.txt", server.uri());
+        set_default_sources_for_testing(vec![source.clone()]);
+
+        let stale_meta = HostPromptCacheMeta {
+            etag: "\"h-cached\"".to_string(),
+            last_fetch: Some("2026-01-01T00:00:00.000Z".to_string()),
+            last_checked: now_ms() - CACHE_TTL_MS - 1_000,
+            source_key: Some(source_cache_key(&source)),
+            source_url: None,
+        };
+        write_cache_files_atomically("cached host prompt", &stale_meta)
+            .await
+            .expect("seed cache");
+
+        // Foreground refresh path (no memory): 304 re-serves the cached body.
+        let refreshed = refresh_prompt(Some(&stale_meta), Some("cached host prompt"))
+            .await
+            .expect("304 revalidation");
+        assert_eq!(refreshed, "cached host prompt");
+        let meta: HostPromptCacheMeta = serde_json::from_str(
+            &tokio::fs::read_to_string(cache_meta_file_path())
+                .await
+                .expect("meta"),
+        )
+        .expect("parses");
+        assert!(meta.last_checked > stale_meta.last_checked);
+        assert_eq!(meta.etag, "\"h-cached\"");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn cross_source_etag_is_not_sent_conditionally() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        // A conditional request would 304 here; the full fetch must happen
+        // because the cached etag belongs to a DIFFERENT source.
+        Mock::given(method("GET"))
+            .and(path("/other.txt"))
+            .and(header("if-none-match", "\"h-cached\""))
+            .respond_with(ResponseTemplate::new(304))
+            .mount(&server)
+            .await;
+        Mock::given(method("GET"))
+            .and(path("/other.txt"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("fresh other"))
+            .mount(&server)
+            .await;
+        let source = format!("{}/other.txt", server.uri());
+        set_default_sources_for_testing(vec![source]);
+
+        let cached_meta = HostPromptCacheMeta {
+            etag: "\"h-cached\"".to_string(),
+            last_fetch: None,
+            last_checked: 1,
+            source_key: Some("https://elsewhere.example/codex.txt".to_string()),
+            source_url: None,
+        };
+        let content = refresh_prompt(Some(&cached_meta), Some("old body"))
+            .await
+            .expect("full fetch");
+        assert_eq!(content, "fresh other");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn empty_bodies_are_rejected_and_fall_through_sources() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/empty.txt"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("   "))
+            .mount(&server)
+            .await;
+        Mock::given(method("GET"))
+            .and(path("/good.txt"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("good body"))
+            .mount(&server)
+            .await;
+        set_default_sources_for_testing(vec![
+            format!("{}/empty.txt", server.uri()),
+            format!("{}/good.txt", server.uri()),
+        ]);
+
+        let content = get_host_codex_prompt().await.expect("second source wins");
+        assert_eq!(content, "good body");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn all_sources_failing_without_cache_is_an_error() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .respond_with(ResponseTemplate::new(500))
+            .mount(&server)
+            .await;
+        set_default_sources_for_testing(vec![format!("{}/codex.txt", server.uri())]);
+
+        let error = get_host_codex_prompt().await.expect_err("no cache");
+        assert!(
+            error.starts_with("Failed to fetch codex.txt and no cache available:"),
+            "unexpected: {error}"
+        );
+        assert!(error.contains("HTTP 500"), "unexpected: {error}");
+        reset();
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn migrates_legacy_cache_pairs() {
+        let _sandbox = EnvSandbox::new();
+        reset();
+        // No network needed: the legacy disk cache is fresh.
+        set_default_sources_for_testing(vec![]);
+        let cache_dir = get_codex_cache_dir();
+        tokio::fs::create_dir_all(&cache_dir).await.expect("mkdir");
+        tokio::fs::write(cache_dir.join("opencode-codex-prompt.txt"), "legacy prompt")
+            .await
+            .expect("legacy content");
+        tokio::fs::write(
+            cache_dir.join("opencode-codex-prompt-meta.json"),
+            format!(
+                r#"{{"etag":"\"legacy\"","lastChecked":{},"sourceUrl":"https://old.example/codex.txt"}}"#,
+                now_ms()
+            ),
+        )
+        .await
+        .expect("legacy meta");
+
+        let content = get_host_codex_prompt().await.expect("legacy served");
+        assert_eq!(content, "legacy prompt");
+        // Migrated to the current file names.
+        assert_eq!(
+            tokio::fs::read_to_string(cache_file_path())
+                .await
+                .expect("migrated content"),
+            "legacy prompt"
+        );
+        let migrated: HostPromptCacheMeta = serde_json::from_str(
+            &tokio::fs::read_to_string(cache_meta_file_path())
+                .await
+                .expect("migrated meta"),
+        )
+        .expect("parses");
+        assert_eq!(migrated.etag, "\"legacy\"");
+        assert_eq!(
+            migrated.source_url.as_deref(),
+            Some("https://old.example/codex.txt")
+        );
+        reset();
+    }
+}
diff --git a/crates/request/src/prompts/mod.rs b/crates/request/src/prompts/mod.rs
new file mode 100644
index 000000000..c1ac27bf1
--- /dev/null
+++ b/crates/request/src/prompts/mod.rs
@@ -0,0 +1,5 @@
+//! cma-request - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod codex;
+pub mod fetch_utils;
+pub mod host_bridge;
+pub mod host_prompt;
diff --git a/crates/request/src/rate_limit_backoff.rs b/crates/request/src/rate_limit_backoff.rs
new file mode 100644
index 000000000..720ff9aec
--- /dev/null
+++ b/crates/request/src/rate_limit_backoff.rs
@@ -0,0 +1,749 @@
+//! Port of `lib/request/rate-limit-backoff.ts` — per-process 429 backoff
+//! with time-window deduplication (spec 06 §13).
+//!
+//! **CRITICAL anti-requirement (spec 06 §23 / 6.4.0 regression):** this state
+//! is per-process, in-memory ONLY. It must NEVER be serialized into the
+//! persisted account/rate-limit files. No type here implements `Serialize`.
+//!
+//! Behavior pins:
+//! - Deduplicate concurrent 429s inside `dedup_window_ms` (returns the
+//!   PREVIOUS attempt/delay without touching state).
+//! - Reset backoff after a quiet period (`state_reset_ms`).
+//! - Server retry-after acts as a FLOOR on the jittered exponential delay.
+//! - Reason multiplier is applied WITHOUT re-applying `2^(attempt-1)`
+//!   (audit REQ-HIGH-01); the first fresh attempt applies it to the
+//!   UN-jittered normalized base.
+
+use std::collections::HashMap;
+use std::sync::Mutex;
+
+use cma_core::schemas::account_storage::RateLimitReason;
+use cma_core::utils::now_ms;
+
+/// Defaults mirror `DEFAULT_PLUGIN_CONFIG` (`lib/config.ts`):
+/// `rateLimitDedupWindowMs ?? 2_000`, `rateLimitStateResetMs ?? 120_000`,
+/// `rateLimitMaxBackoffMs ?? 60_000`, `rateLimitShortRetryThresholdMs ?? 5_000`.
+const DEFAULT_RATE_LIMIT_DEDUP_WINDOW_MS: i64 = 2_000;
+const DEFAULT_RATE_LIMIT_STATE_RESET_MS: i64 = 120_000;
+const DEFAULT_MAX_BACKOFF_MS: i64 = 60_000;
+const DEFAULT_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS: i64 = 5_000;
+const RATE_LIMIT_BACKOFF_JITTER_FACTOR: f64 = 0.2;
+
+/// Maximum number of consecutive short-cooldown 429 retries before falling
+/// through to the long-cooldown rotation path. Without this bound, an
+/// upstream that perpetually returns short Retry-After values (at or below
+/// the short-retry threshold) would keep the request loop spinning on the
+/// same account indefinitely.
+pub const MAX_SHORT_RETRY_ATTEMPTS: u32 = 3;
+
+/// TS `RateLimitBackoffResult`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct RateLimitBackoffResult {
+    pub attempt: u32,
+    pub delay_ms: i64,
+    pub is_duplicate: bool,
+    pub reason: Option<RateLimitReason>,
+}
+
+#[derive(Clone, Copy, Debug)]
+struct RateLimitBackoffConfig {
+    dedup_window_ms: i64,
+    state_reset_ms: i64,
+    max_backoff_ms: i64,
+    short_retry_threshold_ms: i64,
+}
+
+impl RateLimitBackoffConfig {
+    const fn defaults() -> Self {
+        Self {
+            dedup_window_ms: DEFAULT_RATE_LIMIT_DEDUP_WINDOW_MS,
+            state_reset_ms: DEFAULT_RATE_LIMIT_STATE_RESET_MS,
+            max_backoff_ms: DEFAULT_MAX_BACKOFF_MS,
+            short_retry_threshold_ms: DEFAULT_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS,
+        }
+    }
+}
+
+/// TS `Partial<RateLimitBackoffConfig>` overrides for
+/// [`configure_rate_limit_backoff`]. Non-finite values are ignored, exactly
+/// like the TS `typeof === "number" && Number.isFinite` guards.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct RateLimitBackoffOverrides {
+    pub dedup_window_ms: Option<f64>,
+    pub state_reset_ms: Option<f64>,
+    pub max_backoff_ms: Option<f64>,
+    pub short_retry_threshold_ms: Option<f64>,
+}
+
+#[derive(Clone, Debug)]
+struct RateLimitState {
+    consecutive_429: u32,
+    last_at: i64,
+    #[allow(dead_code)] // parity with the TS state shape; useful in debugging
+    quota_key: String,
+    last_delay_ms: i64,
+}
+
+static CONFIG: Mutex<RateLimitBackoffConfig> = Mutex::new(RateLimitBackoffConfig::defaults());
+static STATE: Mutex<Option<HashMap<String, RateLimitState>>> = Mutex::new(None);
+
+fn config() -> RateLimitBackoffConfig {
+    *CONFIG.lock().expect("rate-limit backoff config poisoned")
+}
+
+fn with_state<T>(f: impl FnOnce(&mut HashMap<String, RateLimitState>) -> T) -> T {
+    let mut guard = STATE.lock().expect("rate-limit backoff state poisoned");
+    f(guard.get_or_insert_with(HashMap::new))
+}
+
+/// TS `configureRateLimitBackoff(overrides)` — each provided finite value is
+/// floored and clamped to its minimum (dedup >= 0, stateReset >= 1000,
+/// maxBackoff >= 1000, shortRetryThreshold >= 0); invalid values are ignored.
+pub fn configure_rate_limit_backoff(overrides: RateLimitBackoffOverrides) {
+    let mut cfg = CONFIG.lock().expect("rate-limit backoff config poisoned");
+    if let Some(v) = overrides.dedup_window_ms
+        && v.is_finite()
+    {
+        cfg.dedup_window_ms = (v.floor() as i64).max(0);
+    }
+    if let Some(v) = overrides.state_reset_ms
+        && v.is_finite()
+    {
+        cfg.state_reset_ms = (v.floor() as i64).max(1_000);
+    }
+    if let Some(v) = overrides.max_backoff_ms
+        && v.is_finite()
+    {
+        cfg.max_backoff_ms = (v.floor() as i64).max(1_000);
+    }
+    if let Some(v) = overrides.short_retry_threshold_ms
+        && v.is_finite()
+    {
+        cfg.short_retry_threshold_ms = (v.floor() as i64).max(0);
+    }
+}
+
+/// TS `resetRateLimitBackoffConfig()`.
+pub fn reset_rate_limit_backoff_config() {
+    *CONFIG.lock().expect("rate-limit backoff config poisoned") =
+        RateLimitBackoffConfig::defaults();
+}
+
+/// TS `getRateLimitShortRetryThresholdMs()` — the module-local getter.
+pub fn get_rate_limit_short_retry_threshold_ms() -> i64 {
+    config().short_retry_threshold_ms
+}
+
+/// The `lib/index.ts` barrel RENAME `getConfiguredRateLimitShortRetryThresholdMs`
+/// (spec 01 §2.13 / ARCHITECTURE §6.1 note): same value as
+/// [`get_rate_limit_short_retry_threshold_ms`], distinct from cma-config's
+/// `get_rate_limit_short_retry_threshold_ms` env/config getter. Both exist.
+pub fn configured_rate_limit_short_retry_threshold_ms() -> i64 {
+    get_rate_limit_short_retry_threshold_ms()
+}
+
+fn resolve_rate_limit_state_key(
+    account_index: usize,
+    quota_key: &str,
+    stable_account_key: Option<&str>,
+) -> String {
+    let normalized = stable_account_key.map(str::trim).unwrap_or("");
+    if normalized.is_empty() {
+        format!("slot:{account_index}:{quota_key}")
+    } else {
+        format!("{normalized}:{quota_key}")
+    }
+}
+
+/// TS `normalizeDelayMs` — non-finite/absent -> fallback, then
+/// `max(0, floor(v))`.
+fn normalize_delay_ms(value: Option<f64>, fallback: i64) -> i64 {
+    match value {
+        Some(v) if v.is_finite() => (v.floor() as i64).max(0),
+        // NaN / ±Infinity fail the TS `Number.isFinite` guard -> fallback.
+        _ => fallback.max(0),
+    }
+}
+
+/// `Math.random()` analogue — a uniform `[0,1)` draw for the ±20% jitter.
+///
+/// The foundation Cargo.toml for this crate does not include `rand`, and the
+/// jitter needs no cryptographic strength, so this derives the sample from
+/// `std::hash::RandomState` (per-instance random keys seeded from OS
+/// entropy). 53 bits of the hash map onto the JS double-precision unit
+/// interval.
+fn random_unit() -> f64 {
+    use std::hash::{BuildHasher, Hasher, RandomState};
+    let mut hasher = RandomState::new().build_hasher();
+    hasher.write_u64(0x9e37_79b9_7f4a_7c15);
+    ((hasher.finish() >> 11) as f64) / ((1u64 << 53) as f64)
+}
+
+/// TS `addBackoffJitter` with the `Math.random()` draw injected:
+/// `jitter_unit` is the uniform `[0,1)` sample.
+fn add_backoff_jitter(base_ms: f64, jitter_unit: f64) -> i64 {
+    let jitter = base_ms * RATE_LIMIT_BACKOFF_JITTER_FACTOR * (jitter_unit * 2.0 - 1.0);
+    ((base_ms + jitter).floor() as i64).max(0)
+}
+
+fn prune_stale_rate_limit_state(now: i64, state_reset_ms: i64) {
+    with_state(|state| {
+        state.retain(|_, entry| now - entry.last_at <= state_reset_ms);
+    });
+}
+
+fn get_rate_limit_backoff_at(
+    account_index: usize,
+    quota_key: &str,
+    server_retry_after_ms: Option<f64>,
+    stable_account_key: Option<&str>,
+    now: i64,
+    jitter_unit: f64,
+) -> RateLimitBackoffResult {
+    let cfg = config();
+    prune_stale_rate_limit_state(now, cfg.state_reset_ms);
+    let state_key = resolve_rate_limit_state_key(account_index, quota_key, stable_account_key);
+    let base_delay = normalize_delay_ms(server_retry_after_ms, 1_000);
+
+    with_state(|state| {
+        if let Some(previous) = state.get(&state_key)
+            && now - previous.last_at < cfg.dedup_window_ms
+        {
+            // Concurrent 429s within the dedup window must not over-increment:
+            // return the previous verdict WITHOUT updating state.
+            return RateLimitBackoffResult {
+                attempt: previous.consecutive_429,
+                delay_ms: previous.last_delay_ms,
+                is_duplicate: true,
+                reason: None,
+            };
+        }
+
+        let attempt = match state.get(&state_key) {
+            Some(previous) if now - previous.last_at < cfg.state_reset_ms => {
+                previous.consecutive_429 + 1
+            }
+            _ => 1,
+        };
+
+        let backoff_delay = ((base_delay as f64) * 2f64.powi(attempt as i32 - 1))
+            .min(cfg.max_backoff_ms as f64);
+        let jittered_delay = add_backoff_jitter(backoff_delay, jitter_unit).min(cfg.max_backoff_ms);
+        // The server hint is a FLOOR on the jittered delay.
+        let delay_ms = base_delay.max(jittered_delay);
+        state.insert(
+            state_key,
+            RateLimitState {
+                consecutive_429: attempt,
+                last_at: now,
+                quota_key: quota_key.to_string(),
+                last_delay_ms: delay_ms,
+            },
+        );
+        RateLimitBackoffResult {
+            attempt,
+            delay_ms,
+            is_duplicate: false,
+            reason: None,
+        }
+    })
+}
+
+/// TS `getRateLimitBackoff(accountIndex, quotaKey, serverRetryAfterMs,
+/// stableAccountKey?)` — compute rate-limit backoff for an account+quota key.
+pub fn get_rate_limit_backoff(
+    account_index: usize,
+    quota_key: &str,
+    server_retry_after_ms: Option<f64>,
+    stable_account_key: Option<&str>,
+) -> RateLimitBackoffResult {
+    get_rate_limit_backoff_at(
+        account_index,
+        quota_key,
+        server_retry_after_ms,
+        stable_account_key,
+        now_ms(),
+        random_unit(),
+    )
+}
+
+/// TS `resetRateLimitBackoff` — delete one state entry.
+pub fn reset_rate_limit_backoff(
+    account_index: usize,
+    quota_key: &str,
+    stable_account_key: Option<&str>,
+) {
+    let key = resolve_rate_limit_state_key(account_index, quota_key, stable_account_key);
+    with_state(|state| {
+        state.remove(&key);
+    });
+}
+
+/// TS `clearRateLimitBackoffState()` — clear the whole map.
+pub fn clear_rate_limit_backoff_state() {
+    with_state(|state| state.clear());
+}
+
+fn backoff_multiplier(reason: RateLimitReason) -> f64 {
+    match reason {
+        RateLimitReason::Quota => 3.0,
+        RateLimitReason::Tokens => 1.5,
+        RateLimitReason::Concurrent => 0.5,
+        RateLimitReason::Unknown => 1.0,
+    }
+}
+
+/// TS `calculateBackoffMs(baseDelayMs, _attempt, reason = "unknown")`.
+///
+/// Applies ONLY the reason multiplier to `base_delay_ms` (which is expected
+/// to already incorporate the exponential progression + jitter from
+/// [`get_rate_limit_backoff`]) and clamps to the configured max backoff.
+/// It deliberately does NOT re-apply `2^(attempt-1)` — doing so double-applied
+/// the exponential and saturated `max_backoff_ms` after two consecutive 429s
+/// (audit finding REQ-HIGH-01). `_attempt` is retained for API compatibility.
+pub fn calculate_backoff_ms(base_delay_ms: f64, _attempt: u32, reason: RateLimitReason) -> i64 {
+    let multiplier = backoff_multiplier(reason);
+    let scaled = (base_delay_ms * multiplier).floor().max(0.0);
+    let max = config().max_backoff_ms;
+    if scaled >= max as f64 { max } else { scaled as i64 }
+}
+
+/// TS `RateLimitBackoffWithReasonParams` (named-parameter form; the
+/// positional TS overload maps to the same struct).
+#[derive(Clone, Debug)]
+pub struct RateLimitBackoffWithReasonParams<'a> {
+    pub account_index: usize,
+    pub quota_key: &'a str,
+    pub server_retry_after_ms: Option<f64>,
+    /// Defaults to [`RateLimitReason::Unknown`] when `None`.
+    pub reason: Option<RateLimitReason>,
+    pub stable_account_key: Option<&'a str>,
+}
+
+/// Argument-validation error for [`get_rate_limit_backoff_with_reason`]
+/// (TS threw `TypeError`; message text frozen).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RateLimitBackoffArgError(pub String);
+
+impl std::fmt::Display for RateLimitBackoffArgError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for RateLimitBackoffArgError {}
+
+/// TS `getRateLimitBackoffWithReason(...)`.
+///
+/// Validates the quota key (frozen message
+/// `"getRateLimitBackoffWithReason requires a non-empty quotaKey"`; the TS
+/// non-negative-integer accountIndex check is statically guaranteed by
+/// `usize`), trims it, chains [`get_rate_limit_backoff`], then applies the
+/// reason multiplier: the first fresh attempt uses the UN-jittered normalized
+/// base (deterministic), later/duplicate attempts use the already-jittered
+/// exponential delay (REQ-HIGH-01: the exponential is never double-applied).
+pub fn get_rate_limit_backoff_with_reason(
+    params: RateLimitBackoffWithReasonParams<'_>,
+) -> Result<RateLimitBackoffResult, RateLimitBackoffArgError> {
+    get_rate_limit_backoff_with_reason_at(params, now_ms(), random_unit())
+}
+
+fn get_rate_limit_backoff_with_reason_at(
+    params: RateLimitBackoffWithReasonParams<'_>,
+    now: i64,
+    jitter_unit: f64,
+) -> Result<RateLimitBackoffResult, RateLimitBackoffArgError> {
+    if params.quota_key.trim().is_empty() {
+        return Err(RateLimitBackoffArgError(
+            "getRateLimitBackoffWithReason requires a non-empty quotaKey".to_string(),
+        ));
+    }
+    let normalized_quota_key = params.quota_key.trim();
+    let resolved_reason = params.reason.unwrap_or(RateLimitReason::Unknown);
+    let result = get_rate_limit_backoff_at(
+        params.account_index,
+        normalized_quota_key,
+        params.server_retry_after_ms,
+        params.stable_account_key,
+        now,
+        jitter_unit,
+    );
+    let normalized_base_delay = normalize_delay_ms(params.server_retry_after_ms, 1_000);
+    let multiplier_input = if result.attempt == 1 && !result.is_duplicate {
+        normalized_base_delay as f64
+    } else {
+        result.delay_ms as f64
+    };
+    let adjusted_delay = calculate_backoff_ms(multiplier_input, result.attempt, resolved_reason);
+    Ok(RateLimitBackoffResult {
+        delay_ms: adjusted_delay,
+        reason: Some(resolved_reason),
+        ..result
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    /// Every test resets the shared per-process state (config + map) and uses
+    /// injected `now`/jitter, so they serialize on the module state.
+    fn reset_all() {
+        clear_rate_limit_backoff_state();
+        reset_rate_limit_backoff_config();
+    }
+
+    /// `Math.random() == 0.5` -> zero jitter (the TS suite's baseline mock).
+    const MID: f64 = 0.5;
+
+    fn backoff_at(
+        index: usize,
+        key: &str,
+        retry_after: Option<f64>,
+        stable: Option<&str>,
+        now: i64,
+        jitter: f64,
+    ) -> RateLimitBackoffResult {
+        get_rate_limit_backoff_at(index, key, retry_after, stable, now, jitter)
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn deduplicates_concurrent_429s_within_the_window() {
+        reset_all();
+        let first = backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        assert_eq!(
+            first,
+            RateLimitBackoffResult {
+                attempt: 1,
+                delay_ms: 1000,
+                is_duplicate: false,
+                reason: None
+            }
+        );
+
+        let second = backoff_at(0, "codex", Some(1000.0), None, 1000, MID);
+        assert_eq!(second.attempt, 1);
+        assert_eq!(second.delay_ms, 1000);
+        assert!(second.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn increments_after_dedup_window() {
+        reset_all();
+        backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        let second = backoff_at(0, "codex", Some(1000.0), None, 2500, MID);
+        assert_eq!(second.attempt, 2);
+        assert_eq!(second.delay_ms, 2000);
+        assert!(!second.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn applies_jitter_to_new_windows_but_keeps_duplicates_stable() {
+        reset_all();
+        // Math.random() == 1 -> +20% jitter.
+        let first = backoff_at(4, "jitter-test", Some(1000.0), None, 0, 1.0);
+        assert_eq!(first.delay_ms, 1200);
+
+        // Duplicate window: previous delay returned regardless of jitter draw.
+        let duplicate = backoff_at(4, "jitter-test", Some(1000.0), None, 1000, 0.0);
+        assert_eq!(duplicate.delay_ms, 1200);
+        assert!(duplicate.is_duplicate);
+
+        // Math.random() == 0 -> -20% jitter, but server hint floors at 1000...
+        // exponential base is 2000 so -20% -> 1600.
+        let second = backoff_at(4, "jitter-test", Some(1000.0), None, 2500, 0.0);
+        assert_eq!(second.delay_ms, 1600);
+        assert!(!second.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn resets_after_quiet_period() {
+        reset_all();
+        backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        let next = backoff_at(0, "codex", Some(1000.0), None, 121_000, MID);
+        assert_eq!(next.attempt, 1);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn reset_rate_limit_backoff_clears_state() {
+        reset_all();
+        backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        reset_rate_limit_backoff(0, "codex", None);
+        let next = backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        assert_eq!(next.attempt, 1);
+        assert!(!next.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn uses_configurable_dedup_and_state_reset_windows() {
+        reset_all();
+        configure_rate_limit_backoff(RateLimitBackoffOverrides {
+            dedup_window_ms: Some(5_000.0),
+            state_reset_ms: Some(10_000.0),
+            ..Default::default()
+        });
+        backoff_at(0, "codex", Some(1000.0), None, 0, MID);
+        assert!(backoff_at(0, "codex", Some(1000.0), None, 3_000, MID).is_duplicate);
+        assert_eq!(backoff_at(0, "codex", Some(1000.0), None, 11_000, MID).attempt, 1);
+        reset_all();
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn does_not_carry_state_across_slot_reuse_when_stable_key_changes() {
+        reset_all();
+        backoff_at(0, "codex", Some(1000.0), Some("acc-1"), 0, MID);
+        let next_account = backoff_at(0, "codex", Some(1000.0), Some("acc-2"), 2_500, MID);
+        assert_eq!(next_account.attempt, 1);
+        assert!(!next_account.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn blank_stable_key_falls_back_to_slot_key() {
+        reset_all();
+        backoff_at(3, "codex", Some(1000.0), Some("   "), 0, MID);
+        // Same slot, no stable key -> same state entry (duplicate window).
+        let dup = backoff_at(3, "codex", Some(1000.0), None, 500, MID);
+        assert!(dup.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn calculate_backoff_applies_reason_multipliers() {
+        reset_all();
+        assert_eq!(calculate_backoff_ms(1000.0, 1, RateLimitReason::Quota), 3000);
+        assert_eq!(calculate_backoff_ms(1000.0, 1, RateLimitReason::Tokens), 1500);
+        assert_eq!(calculate_backoff_ms(1000.0, 1, RateLimitReason::Concurrent), 500);
+        assert_eq!(calculate_backoff_ms(1000.0, 1, RateLimitReason::Unknown), 1000);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn calculate_backoff_does_not_reapply_exponential() {
+        reset_all();
+        // REQ-HIGH-01: attempt number must not change the result.
+        assert_eq!(calculate_backoff_ms(1000.0, 1, RateLimitReason::Unknown), 1000);
+        assert_eq!(calculate_backoff_ms(1000.0, 2, RateLimitReason::Unknown), 1000);
+        assert_eq!(calculate_backoff_ms(1000.0, 3, RateLimitReason::Unknown), 1000);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn calculate_backoff_caps_at_max_backoff() {
+        reset_all();
+        let huge = 10.0 * 60.0 * 1000.0;
+        assert!(calculate_backoff_ms(huge, 20, RateLimitReason::Quota) <= 5 * 60 * 1000);
+        assert_eq!(
+            calculate_backoff_ms(huge, 20, RateLimitReason::Quota),
+            DEFAULT_MAX_BACKOFF_MS
+        );
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn calculate_backoff_uses_configurable_cap() {
+        reset_all();
+        configure_rate_limit_backoff(RateLimitBackoffOverrides {
+            max_backoff_ms: Some(12_000.0),
+            ..Default::default()
+        });
+        assert_eq!(calculate_backoff_ms(10_000.0, 20, RateLimitReason::Quota), 12_000);
+        reset_all();
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn exposes_configurable_short_retry_threshold() {
+        reset_all();
+        assert_eq!(get_rate_limit_short_retry_threshold_ms(), 5_000);
+        assert_eq!(configured_rate_limit_short_retry_threshold_ms(), 5_000);
+        configure_rate_limit_backoff(RateLimitBackoffOverrides {
+            short_retry_threshold_ms: Some(9_000.0),
+            ..Default::default()
+        });
+        assert_eq!(get_rate_limit_short_retry_threshold_ms(), 9_000);
+        assert_eq!(configured_rate_limit_short_retry_threshold_ms(), 9_000);
+        reset_all();
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn config_defaults_match_default_plugin_config() {
+        // TS pulls these defaults from DEFAULT_PLUGIN_CONFIG with ?? fallbacks;
+        // keep the consts pinned against the resolved config defaults.
+        let resolved = cma_core::schemas::plugin_config::PluginConfig::default_resolved();
+        assert_eq!(
+            resolved.rate_limit_dedup_window_ms,
+            Some(DEFAULT_RATE_LIMIT_DEDUP_WINDOW_MS as f64)
+        );
+        assert_eq!(
+            resolved.rate_limit_state_reset_ms,
+            Some(DEFAULT_RATE_LIMIT_STATE_RESET_MS as f64)
+        );
+        assert_eq!(
+            resolved.rate_limit_max_backoff_ms,
+            Some(DEFAULT_MAX_BACKOFF_MS as f64)
+        );
+        assert_eq!(
+            resolved.rate_limit_short_retry_threshold_ms,
+            Some(DEFAULT_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS as f64)
+        );
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn normalize_delay_edge_cases_fall_back_to_1000() {
+        reset_all();
+        for (i, retry) in [
+            (10usize, None),
+            (12, Some(f64::NAN)),
+            (13, Some(f64::INFINITY)),
+            (14, Some(f64::NEG_INFINITY)),
+        ] {
+            let result = backoff_at(i, "edge-test", retry, None, 0, MID);
+            assert_eq!(result.delay_ms, 1000, "case {i}");
+        }
+        // Negative floors to 0 -> exponential base 0, delay 0.
+        let neg = backoff_at(15, "edge-neg", Some(-50.0), None, 0, MID);
+        assert_eq!(neg.delay_ms, 0);
+    }
+
+    fn with_reason_at(
+        index: usize,
+        key: &str,
+        retry: Option<f64>,
+        reason: Option<RateLimitReason>,
+        now: i64,
+    ) -> RateLimitBackoffResult {
+        get_rate_limit_backoff_with_reason_at(
+            RateLimitBackoffWithReasonParams {
+                account_index: index,
+                quota_key: key,
+                server_retry_after_ms: retry,
+                reason,
+                stable_account_key: None,
+            },
+            now,
+            MID,
+        )
+        .expect("valid args")
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn with_reason_returns_adjusted_delay() {
+        reset_all();
+        let quota = with_reason_at(0, "test-quota", Some(1000.0), Some(RateLimitReason::Quota), 0);
+        assert_eq!(quota.reason, Some(RateLimitReason::Quota));
+        assert_eq!(quota.delay_ms, 3000);
+        assert_eq!(quota.attempt, 1);
+
+        let tokens =
+            with_reason_at(1, "test-tokens", Some(2000.0), Some(RateLimitReason::Tokens), 0);
+        assert_eq!(tokens.reason, Some(RateLimitReason::Tokens));
+        assert_eq!(tokens.delay_ms, 3000);
+
+        let default = with_reason_at(2, "test-default", Some(1000.0), None, 0);
+        assert_eq!(default.reason, Some(RateLimitReason::Unknown));
+        assert_eq!(default.delay_ms, 1000);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn with_reason_increments_attempt_on_subsequent_calls() {
+        reset_all();
+        with_reason_at(3, "test-increment", Some(1000.0), Some(RateLimitReason::Quota), 0);
+        let second =
+            with_reason_at(3, "test-increment", Some(1000.0), Some(RateLimitReason::Quota), 2500);
+        assert_eq!(second.attempt, 2);
+        // 1000 * 2^1 = 2000 (zero jitter), * quota(3.0) = 6000 — NOT 12000
+        // (REQ-HIGH-01 double-exponential regression).
+        assert_eq!(second.delay_ms, 6000);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn with_reason_rejects_blank_quota_key_without_mutating_state() {
+        reset_all();
+        let err = get_rate_limit_backoff_with_reason_at(
+            RateLimitBackoffWithReasonParams {
+                account_index: 0,
+                quota_key: "   ",
+                server_retry_after_ms: Some(1000.0),
+                reason: None,
+                stable_account_key: None,
+            },
+            0,
+            MID,
+        )
+        .unwrap_err();
+        assert_eq!(
+            err.to_string(),
+            "getRateLimitBackoffWithReason requires a non-empty quotaKey"
+        );
+
+        let first_valid =
+            with_reason_at(7, "state-safe", Some(1000.0), Some(RateLimitReason::Unknown), 0);
+        assert_eq!(first_valid.attempt, 1);
+        assert!(!first_valid.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn with_reason_trims_quota_key() {
+        reset_all();
+        with_reason_at(9, "trim-key", Some(1000.0), None, 0);
+        let dup = get_rate_limit_backoff_with_reason_at(
+            RateLimitBackoffWithReasonParams {
+                account_index: 9,
+                quota_key: "  trim-key  ",
+                server_retry_after_ms: Some(1000.0),
+                reason: None,
+                stable_account_key: None,
+            },
+            500,
+            MID,
+        )
+        .expect("valid");
+        assert!(dup.is_duplicate);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn does_not_double_apply_exponential_across_chained_attempts() {
+        reset_all();
+        let base = Some(1000.0);
+        let tokens = Some(RateLimitReason::Tokens);
+        let first = with_reason_at(42, "req-high-01-regression", base, tokens, 0);
+        assert_eq!(first.attempt, 1);
+        assert_eq!(first.delay_ms, 1500); // 1000 * 2^0 * 1.5
+
+        let second = with_reason_at(42, "req-high-01-regression", base, tokens, 2_500);
+        assert_eq!(second.attempt, 2);
+        assert_eq!(second.delay_ms, 3000); // 1000 * 2^1 * 1.5
+
+        let third = with_reason_at(42, "req-high-01-regression", base, tokens, 5_000);
+        assert_eq!(third.attempt, 3);
+        assert_eq!(third.delay_ms, 6000); // 1000 * 2^2 * 1.5
+        assert!(third.delay_ms < 60_000);
+
+        // Ratio attempt=1 -> attempt=3 reflects a SINGLE exponential (4x).
+        let ratio = third.delay_ms as f64 / first.delay_ms as f64;
+        assert!((ratio - 4.0).abs() < 0.1);
+        assert!(ratio < 8.0);
+    }
+
+    #[test]
+    #[serial(rate_limit_backoff)]
+    fn max_short_retry_attempts_is_three() {
+        assert_eq!(MAX_SHORT_RETRY_ATTEMPTS, 3);
+    }
+}
diff --git a/crates/request/src/rate_limit_decision.rs b/crates/request/src/rate_limit_decision.rs
new file mode 100644
index 000000000..62b2d5a28
--- /dev/null
+++ b/crates/request/src/rate_limit_decision.rs
@@ -0,0 +1,829 @@
+//! Port of `lib/request/rate-limit-decision.ts` — retry-after parsing
+//! (header + body), token-invalidation detection, quota near-exhaustion
+//! waits, and the standard machine-readable error bodies used by the runtime
+//! rotation proxy (spec 06 §14, spec 04 §req-loop).
+
+use std::fmt::Write as _;
+
+use cma_core::constants::{HTTP_STATUS, MAX_RATE_LIMIT_DELAY_MS};
+use cma_core::json_io::stringify_compact;
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason};
+use http::HeaderMap;
+use serde::Serialize;
+use serde_json::{Map, Value};
+
+use crate::failover_config::parse_env_int;
+
+/// Phrases observed in upstream 401 response bodies when OpenAI/Microsoft has
+/// explicitly revoked an OAuth token (as opposed to a generic expired-token
+/// 401 that can be retried after a refresh). Matching is case-insensitive
+/// substring. See issue #495.
+pub const TOKEN_INVALIDATION_PHRASES: [&str; 4] = [
+    "invalidated oauth token",
+    "authentication token has been invalidated",
+    "oauth token has been invalidated",
+    "token has been invalidated",
+];
+
+/// TS `isTokenInvalidationError(bodyText)`.
+pub fn is_token_invalidation_error(body_text: &str) -> bool {
+    let lower = body_text.to_lowercase();
+    TOKEN_INVALIDATION_PHRASES
+        .iter()
+        .any(|phrase| lower.contains(phrase))
+}
+
+/// TS `isTokenRefreshRetryable(result)` — near-duplicate of the private
+/// helper in token-refresh.ts, except `missing_refresh` falls to the generic
+/// `false` here. An absent reason is non-retryable.
+pub fn is_token_refresh_retryable(result: &TokenFailure) -> bool {
+    match result.reason {
+        Some(
+            TokenFailureReason::NetworkError
+            | TokenFailureReason::Unknown
+            | TokenFailureReason::InvalidResponse,
+        ) => true,
+        Some(TokenFailureReason::HttpError) => !matches!(
+            result.status_code,
+            Some(code)
+                if code == HTTP_STATUS.bad_request as i64
+                    || code == HTTP_STATUS.unauthorized as i64
+                    || code == HTTP_STATUS.forbidden as i64
+        ),
+        _ => false,
+    }
+}
+
+fn header_str<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+    headers.get(name).and_then(|v| v.to_str().ok())
+}
+
+/// `Date.parse` analogue for the formats that actually reach these parsers:
+/// RFC 1123/2822 HTTP dates and ISO-8601/RFC 3339 strings.
+fn parse_date_ms(value: &str) -> Option<i64> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc2822(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    None
+}
+
+/// TS `parseRetryAfterHeaderMs(headers, now)` — `retry-after-ms` int > 0
+/// as-is; `retry-after` int > 0 seconds x1000; else HTTP-date in the future.
+/// **No clamping here** (callers clamp).
+pub fn parse_retry_after_header_ms(headers: &HeaderMap, now: i64) -> Option<i64> {
+    if let Some(raw) = header_str(headers, "retry-after-ms")
+        && !raw.is_empty()
+        && let Some(parsed) = parse_env_int(Some(raw))
+        && parsed > 0
+    {
+        return Some(parsed);
+    }
+    let retry_after = header_str(headers, "retry-after")?;
+    if retry_after.is_empty() {
+        return None;
+    }
+    if let Some(as_seconds) = parse_env_int(Some(retry_after))
+        && as_seconds > 0
+    {
+        // Saturate like the sibling sites in get_quota_window_wait_ms: TS
+        // float math keeps a huge finite value that downstream clamps to the
+        // 7-day cap; a plain i64 multiply would wrap negative in release
+        // builds (account never benched) or panic with overflow-checks.
+        return Some(as_seconds.saturating_mul(1000));
+    }
+    if let Some(as_date) = parse_date_ms(retry_after)
+        && as_date > now
+    {
+        return Some(as_date - now);
+    }
+    None
+}
+
+/// JS `Number(value)` over a JSON value (the coercions these parsers hit).
+fn js_number_of(value: &Value) -> f64 {
+    match value {
+        Value::Number(n) => n.as_f64().unwrap_or(f64::NAN),
+        Value::String(s) => {
+            let trimmed = s.trim();
+            if trimmed.is_empty() {
+                0.0
+            } else {
+                trimmed.parse::<f64>().unwrap_or(f64::NAN)
+            }
+        }
+        Value::Bool(b) => {
+            if *b {
+                1.0
+            } else {
+                0.0
+            }
+        }
+        Value::Null => 0.0,
+        _ => f64::NAN,
+    }
+}
+
+/// TS `parseRetryAfterBodyMs(bodyText, now)` — JSON `{error:{...}}`:
+/// `retry_after_ms` > 0; else `retry_after` (seconds) x1000; else
+/// `resets_at ?? reset_at` with the `< 10_000_000_000 => seconds` heuristic,
+/// delta from `now` when in the future. Parse failure => `None`.
+pub fn parse_retry_after_body_ms(body_text: &str, now: i64) -> Option<i64> {
+    if body_text.trim().is_empty() {
+        return None;
+    }
+    let parsed: Value = serde_json::from_str(body_text).ok()?;
+    let error = parsed.as_object()?.get("error")?.as_object()?;
+
+    let retry_after_ms = error.get("retry_after_ms").map(js_number_of);
+    if let Some(v) = retry_after_ms
+        && v.is_finite()
+        && v > 0.0
+    {
+        return Some(v as i64);
+    }
+    let retry_after_seconds = error.get("retry_after").map(js_number_of);
+    if let Some(v) = retry_after_seconds
+        && v.is_finite()
+        && v > 0.0
+    {
+        return Some((v * 1000.0) as i64);
+    }
+    // `resets_at ?? reset_at` — JS `??` also coalesces an explicit null.
+    let reset_at_raw = error
+        .get("resets_at")
+        .filter(|v| !v.is_null())
+        .or_else(|| error.get("reset_at").filter(|v| !v.is_null()))
+        .map(js_number_of)?;
+    if reset_at_raw.is_finite() && reset_at_raw > 0.0 {
+        // Epoch heuristic: all values below 1e10 are seconds (spec gotcha 13).
+        let reset_at_ms = if reset_at_raw < 10_000_000_000.0 {
+            reset_at_raw * 1000.0
+        } else {
+            reset_at_raw
+        };
+        if reset_at_ms > now as f64 {
+            return Some((reset_at_ms - now as f64) as i64);
+        }
+    }
+    None
+}
+
+const TOKEN_INVALIDATED_CODE: &str = "token_invalidated";
+const TOKEN_INVALIDATED_FALLBACK_MESSAGE: &str =
+    "OAuth token has been invalidated. Please re-login.";
+
+/// TS `buildTokenInvalidationBody(upstreamBodyText)`.
+///
+/// Both invalidation exit paths (refresh-failure and upstream-401) must hand
+/// the client the same machine-readable shape —
+/// `{ "error": { "message", "code": "token_invalidated" } }` — so a consumer
+/// keying off `error.code` behaves identically regardless of which vector
+/// fired. A JSON upstream body's `message` (top-level, else `error.message`)
+/// is preserved when it is a non-blank string; non-JSON bodies (e.g. HTML)
+/// keep the stable fallback message rather than echoing markup.
+pub fn build_token_invalidation_body(upstream_body_text: &str) -> String {
+    let mut message = TOKEN_INVALIDATED_FALLBACK_MESSAGE.to_string();
+    let trimmed = upstream_body_text.trim();
+    if !trimmed.is_empty()
+        && let Ok(parsed) = serde_json::from_str::<Value>(trimmed)
+        && let Some(obj) = parsed.as_object()
+    {
+        if let Some(direct) = obj.get("message").and_then(Value::as_str)
+            && !direct.trim().is_empty()
+        {
+            message = direct.trim().to_string();
+        } else if let Some(error) = obj.get("error").and_then(Value::as_object)
+            && let Some(nested) = error.get("message").and_then(Value::as_str)
+            && !nested.trim().is_empty()
+        {
+            message = nested.trim().to_string();
+        }
+    }
+    stringify_compact(&serde_json::json!({
+        "error": { "message": message, "code": TOKEN_INVALIDATED_CODE }
+    }))
+}
+
+/// TS `extractErrorCodeFromBody(bodyText)` — top-level `code` string
+/// (trimmed) first, else `error.code`.
+pub fn extract_error_code_from_body(body_text: &str) -> Option<String> {
+    if body_text.trim().is_empty() {
+        return None;
+    }
+    let parsed: Value = serde_json::from_str(body_text).ok()?;
+    let obj = parsed.as_object()?;
+    if let Some(direct) = obj.get("code").and_then(Value::as_str) {
+        let trimmed = direct.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+    }
+    let nested = obj.get("error")?.as_object()?.get("code")?.as_str()?;
+    let trimmed = nested.trim();
+    (!trimmed.is_empty()).then(|| trimmed.to_string())
+}
+
+/// TS private `getQuotaWindowWaitMs(headers, prefix, now)`.
+fn get_quota_window_wait_ms(headers: &HeaderMap, prefix: &str, now: i64) -> i64 {
+    let reset_after_header = format!("{prefix}-reset-after-seconds");
+    if let Some(raw) = header_str(headers, &reset_after_header)
+        && let Some(reset_after_seconds) = parse_env_int(Some(raw))
+        && reset_after_seconds > 0
+    {
+        return reset_after_seconds.saturating_mul(1000);
+    }
+    let reset_at_header = format!("{prefix}-reset-at");
+    let Some(reset_at_raw) = header_str(headers, &reset_at_header) else {
+        return 0;
+    };
+    let trimmed = reset_at_raw.trim();
+    let mut reset_at_ms: i64 = 0;
+    if !trimmed.is_empty() && trimmed.bytes().all(|b| b.is_ascii_digit()) {
+        if let Some(parsed) = parse_env_int(Some(trimmed))
+            && parsed > 0
+        {
+            reset_at_ms = if parsed < 10_000_000_000 {
+                parsed.saturating_mul(1000)
+            } else {
+                parsed
+            };
+        }
+    } else if let Some(parsed_date) = parse_date_ms(trimmed) {
+        reset_at_ms = parsed_date;
+    }
+    if reset_at_ms > now { reset_at_ms - now } else { 0 }
+}
+
+/// TS `getQuotaNearExhaustionWaitMs(headers, remainingThreshold, now)`.
+///
+/// `usedThreshold = 100 - clamp(remainingThreshold, 0, 100)`. For the
+/// `x-codex-primary` / `x-codex-secondary` windows whose `-used-percent`
+/// meets the threshold, collect positive window waits; none => 0; else
+/// `min(max(candidates), MAX_RATE_LIMIT_DELAY_MS)` — clamped AT SOURCE so a
+/// bogus upstream reset header can never yield an unbounded wait (defense in
+/// depth for stress audit H1).
+pub fn get_quota_near_exhaustion_wait_ms(
+    headers: &HeaderMap,
+    remaining_threshold: f64,
+    now: i64,
+) -> i64 {
+    let used_threshold = 100.0 - remaining_threshold.clamp(0.0, 100.0);
+    let mut candidates: Vec<i64> = Vec::new();
+    for prefix in ["x-codex-primary", "x-codex-secondary"] {
+        let used_header = format!("{prefix}-used-percent");
+        let used = match header_str(headers, &used_header) {
+            Some(raw) => js_number_of(&Value::String(raw.to_string())),
+            None => js_number_of(&Value::String(String::new())),
+        };
+        if !used.is_finite() || used < used_threshold {
+            continue;
+        }
+        let wait_ms = get_quota_window_wait_ms(headers, prefix, now);
+        if wait_ms > 0 {
+            candidates.push(wait_ms);
+        }
+    }
+    match candidates.iter().max() {
+        None => 0,
+        Some(&max_wait) => max_wait.min(MAX_RATE_LIMIT_DELAY_MS),
+    }
+}
+
+/// TS `normalizeExhaustionStatus(reason)` — `"rate-limit"` => 429, every
+/// other exhaustion reason => 503. Takes the reason's wire string because
+/// `ExhaustionReason` itself lives upstream in the runtime crate (the TS
+/// import direction is inverted by the Rust crate DAG).
+pub fn normalize_exhaustion_status(reason: &str) -> u16 {
+    if reason == "rate-limit" {
+        HTTP_STATUS.too_many_requests
+    } else {
+        503
+    }
+}
+
+/// TS `PinnedUnavailableErrorBody` — the JSON `error` body for a
+/// pinned-account 503. Serde field order is the exact TS shape. See issue
+/// #486 for the null-reason desync path.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct PinnedUnavailableErrorBody {
+    pub message: String,
+    /// Always `"codex_pinned_account_unavailable"`.
+    pub code: &'static str,
+    /// Serialized as an explicit `null` when unknown (desync path).
+    #[serde(rename = "pinnedAccountIndex")]
+    pub pinned_account_index: Option<i64>,
+    /// Serialized as an explicit `null` when absent.
+    pub reason: Option<String>,
+    /// Record of stringified account index -> skip reason, in caller order.
+    pub account_skip_reasons: Map<String, Value>,
+}
+
+/// TS `buildPinnedUnavailableErrorBody(pinnedIndex, accountSkipReasons)`.
+///
+/// `account_skip_reasons` entries keep their given order (the TS `Map`
+/// insertion order); a duplicate index keeps its first position with the
+/// last value, matching JS `Map` semantics.
+pub fn build_pinned_unavailable_error_body(
+    pinned_index: Option<i64>,
+    account_skip_reasons: &[(usize, String)],
+) -> PinnedUnavailableErrorBody {
+    let skip_reason: Option<String> = pinned_index.and_then(|pinned| {
+        // Map.get semantics: last write for the key wins.
+        account_skip_reasons
+            .iter()
+            .rev()
+            .find(|(index, _)| *index as i64 == pinned)
+            .map(|(_, reason)| reason.clone())
+    });
+    let reason_suffix = match &skip_reason {
+        Some(reason) => format!(" ({reason})"),
+        None => String::new(),
+    };
+    // On the desync path the pin index is unknown (null); claiming
+    // "account 1" there would contradict the machine-readable
+    // pinnedAccountIndex: null.
+    let account_phrase = match pinned_index {
+        None => "The pinned account".to_string(),
+        Some(index) => format!("Pinned account {}", index + 1),
+    };
+    let mut message = String::new();
+    let _ = write!(
+        message,
+        "{account_phrase} is currently unavailable{reason_suffix}; run `codex-multi-auth status` for details, or `codex-multi-auth unpin` to allow rotation."
+    );
+    let mut reasons = Map::new();
+    for (index, reason) in account_skip_reasons {
+        reasons.insert(index.to_string(), Value::String(reason.clone()));
+    }
+    PinnedUnavailableErrorBody {
+        message,
+        code: "codex_pinned_account_unavailable",
+        pinned_account_index: pinned_index,
+        reason: skip_reason,
+        account_skip_reasons: reasons,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::header::{HeaderName, HeaderValue};
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.insert(
+                name.parse::<HeaderName>().expect("header name"),
+                HeaderValue::from_str(value).expect("header value"),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn hostile_huge_retry_after_seconds_saturates_instead_of_wrapping() {
+        // H1 hostile-upstream hardening: an absurd `retry-after` (e.g. a
+        // leaked epoch-ns timestamp) must stay a huge POSITIVE ms value that
+        // the downstream markRateLimitedWithReason clamp turns into the 7-day
+        // bench — a wrapped negative would clamp to 0 and never bench.
+        let h = headers(&[("retry-after", "99999999999999999999")]);
+        assert_eq!(parse_retry_after_header_ms(&h, 0), Some(i64::MAX));
+        // In-i64-range seconds whose ms conversion overflows also saturate.
+        let h = headers(&[("retry-after", "9000000000000000000")]);
+        assert_eq!(parse_retry_after_header_ms(&h, 0), Some(i64::MAX));
+    }
+
+    fn utc_string(epoch_ms: i64) -> String {
+        chrono::DateTime::from_timestamp_millis(epoch_ms)
+            .expect("valid epoch")
+            .to_rfc2822()
+    }
+
+    mod token_invalidation {
+        use super::*;
+
+        #[test]
+        fn matches_known_phrases_case_insensitively() {
+            assert!(is_token_invalidation_error(
+                r#"{"message":"Invalidated OAuth Token"}"#
+            ));
+            assert!(is_token_invalidation_error(
+                "the authentication TOKEN has been INVALIDATED"
+            ));
+        }
+
+        #[test]
+        fn does_not_match_generic_401_bodies() {
+            assert!(!is_token_invalidation_error(r#"{"message":"token expired"}"#));
+            assert!(!is_token_invalidation_error(""));
+        }
+    }
+
+    mod refresh_retryable {
+        use super::*;
+
+        fn failed(reason: Option<TokenFailureReason>, status: Option<i64>) -> TokenFailure {
+            TokenFailure {
+                reason,
+                status_code: status,
+                message: None,
+            }
+        }
+
+        #[test]
+        fn transient_reasons_are_retryable() {
+            for reason in [
+                TokenFailureReason::NetworkError,
+                TokenFailureReason::Unknown,
+                TokenFailureReason::InvalidResponse,
+            ] {
+                assert!(is_token_refresh_retryable(&failed(Some(reason), None)));
+            }
+        }
+
+        #[test]
+        fn credential_level_http_errors_are_terminal_server_errors_retryable() {
+            for status in [400, 401, 403] {
+                assert!(!is_token_refresh_retryable(&failed(
+                    Some(TokenFailureReason::HttpError),
+                    Some(status)
+                )));
+            }
+            assert!(is_token_refresh_retryable(&failed(
+                Some(TokenFailureReason::HttpError),
+                Some(500)
+            )));
+            assert!(is_token_refresh_retryable(&failed(
+                Some(TokenFailureReason::HttpError),
+                Some(429)
+            )));
+        }
+
+        #[test]
+        fn missing_refresh_timeout_and_absent_reasons_are_non_retryable() {
+            assert!(!is_token_refresh_retryable(&failed(
+                Some(TokenFailureReason::MissingRefresh),
+                None
+            )));
+            assert!(!is_token_refresh_retryable(&failed(
+                Some(TokenFailureReason::Timeout),
+                None
+            )));
+            assert!(!is_token_refresh_retryable(&failed(None, None)));
+        }
+    }
+
+    mod retry_after_header {
+        use super::*;
+
+        // Realistic epoch: bare digit strings must land in the past.
+        const NOW: i64 = 1_700_000_000_000;
+
+        #[test]
+        fn prefers_retry_after_ms_over_retry_after() {
+            let h = headers(&[("retry-after-ms", "1500"), ("retry-after", "60")]);
+            assert_eq!(parse_retry_after_header_ms(&h, NOW), Some(1500));
+        }
+
+        #[test]
+        fn converts_retry_after_seconds_to_milliseconds() {
+            let h = headers(&[("retry-after", "30")]);
+            assert_eq!(parse_retry_after_header_ms(&h, NOW), Some(30_000));
+        }
+
+        #[test]
+        fn supports_http_date_values_in_the_future() {
+            let h = headers(&[("retry-after", &utc_string(NOW + 90_000))]);
+            let wait = parse_retry_after_header_ms(&h, NOW).expect("future date");
+            assert!(wait > 88_000);
+            assert!(wait <= 90_000);
+        }
+
+        #[test]
+        fn returns_none_for_absent_non_positive_or_unparseable() {
+            assert_eq!(parse_retry_after_header_ms(&headers(&[]), NOW), None);
+            assert_eq!(
+                parse_retry_after_header_ms(&headers(&[("retry-after", "0")]), NOW),
+                None
+            );
+            assert_eq!(
+                parse_retry_after_header_ms(&headers(&[("retry-after", "-5")]), NOW),
+                None
+            );
+            assert_eq!(
+                parse_retry_after_header_ms(&headers(&[("retry-after", "soon")]), NOW),
+                None
+            );
+            assert_eq!(
+                parse_retry_after_header_ms(
+                    &headers(&[("retry-after", &utc_string(NOW - 1_000))]),
+                    NOW
+                ),
+                None
+            );
+        }
+    }
+
+    mod retry_after_body {
+        use super::*;
+
+        // Epoch-ms scale so the resets_at heuristics are exercised.
+        const NOW: i64 = 5_000_000_000_000;
+
+        #[test]
+        fn reads_retry_after_ms_first_then_retry_after_seconds() {
+            assert_eq!(
+                parse_retry_after_body_ms(r#"{"error":{"retry_after_ms":2500}}"#, NOW),
+                Some(2500)
+            );
+            assert_eq!(
+                parse_retry_after_body_ms(r#"{"error":{"retry_after":12}}"#, NOW),
+                Some(12_000)
+            );
+        }
+
+        #[test]
+        fn derives_waits_from_resets_at_in_epoch_seconds_or_milliseconds() {
+            let resets_at_seconds = NOW / 1000 + 60;
+            assert_eq!(
+                parse_retry_after_body_ms(
+                    &format!(r#"{{"error":{{"resets_at":{resets_at_seconds}}}}}"#),
+                    NOW
+                ),
+                Some(resets_at_seconds * 1000 - NOW)
+            );
+            let reset_at_ms = NOW + 45_000;
+            assert_eq!(
+                parse_retry_after_body_ms(
+                    &format!(r#"{{"error":{{"reset_at":{reset_at_ms}}}}}"#),
+                    NOW
+                ),
+                Some(45_000)
+            );
+        }
+
+        #[test]
+        fn returns_none_for_empty_non_json_non_record_and_past_payloads() {
+            assert_eq!(parse_retry_after_body_ms("", NOW), None);
+            assert_eq!(parse_retry_after_body_ms("   ", NOW), None);
+            assert_eq!(parse_retry_after_body_ms("{not json", NOW), None);
+            assert_eq!(parse_retry_after_body_ms("[1,2]", NOW), None);
+            assert_eq!(parse_retry_after_body_ms(r#"{"error":[]}"#, NOW), None);
+            assert_eq!(
+                parse_retry_after_body_ms(
+                    &format!(r#"{{"error":{{"resets_at":{}}}}}"#, NOW - 1),
+                    NOW
+                ),
+                None
+            );
+        }
+    }
+
+    mod token_invalidation_body {
+        use super::*;
+
+        fn parse(body: &str) -> Value {
+            serde_json::from_str(body).expect("valid JSON")
+        }
+
+        #[test]
+        fn preserves_top_level_upstream_message_inside_stable_envelope() {
+            let body = parse(&build_token_invalidation_body(
+                r#"{"message":" token revoked "}"#,
+            ));
+            assert_eq!(
+                body["error"],
+                serde_json::json!({"message":"token revoked","code":"token_invalidated"})
+            );
+        }
+
+        #[test]
+        fn falls_back_to_nested_error_message() {
+            let body = parse(&build_token_invalidation_body(
+                r#"{"error":{"message":"oauth token has been invalidated"}}"#,
+            ));
+            assert_eq!(
+                body["error"]["message"],
+                "oauth token has been invalidated"
+            );
+        }
+
+        #[test]
+        fn uses_stable_fallback_for_non_json_empty_and_messageless_bodies() {
+            for upstream in ["", "<html>nope</html>", r#"{"message":"  "}"#] {
+                let body = parse(&build_token_invalidation_body(upstream));
+                assert_eq!(
+                    body["error"],
+                    serde_json::json!({
+                        "message": "OAuth token has been invalidated. Please re-login.",
+                        "code": "token_invalidated"
+                    }),
+                    "upstream={upstream:?}"
+                );
+            }
+        }
+
+        #[test]
+        fn emits_exact_byte_shape() {
+            assert_eq!(
+                build_token_invalidation_body(""),
+                r#"{"error":{"message":"OAuth token has been invalidated. Please re-login.","code":"token_invalidated"}}"#
+            );
+        }
+    }
+
+    mod error_code_extraction {
+        use super::*;
+
+        #[test]
+        fn reads_top_level_code_before_nested_error_code() {
+            assert_eq!(
+                extract_error_code_from_body(r#"{"code":" direct ","error":{"code":"nested"}}"#),
+                Some("direct".to_string())
+            );
+            assert_eq!(
+                extract_error_code_from_body(r#"{"error":{"code":"nested"}}"#),
+                Some("nested".to_string())
+            );
+        }
+
+        #[test]
+        fn returns_none_for_empty_malformed_non_record_and_whitespace_codes() {
+            assert_eq!(extract_error_code_from_body(""), None);
+            assert_eq!(extract_error_code_from_body("{oops"), None);
+            assert_eq!(extract_error_code_from_body("[]"), None);
+            assert_eq!(extract_error_code_from_body(r#"{"code":"  "}"#), None);
+            assert_eq!(extract_error_code_from_body(r#"{"error":{"code":42}}"#), None);
+        }
+    }
+
+    mod quota_near_exhaustion {
+        use super::*;
+
+        const NOW: i64 = 1_700_000_000_000;
+
+        #[test]
+        fn waits_on_window_at_or_above_used_threshold_via_reset_after_seconds() {
+            let h = headers(&[
+                ("x-codex-primary-used-percent", "97"),
+                ("x-codex-primary-reset-after-seconds", "120"),
+            ]);
+            assert_eq!(get_quota_near_exhaustion_wait_ms(&h, 5.0, NOW), 120_000);
+        }
+
+        #[test]
+        fn ignores_windows_below_the_threshold() {
+            let h = headers(&[
+                ("x-codex-primary-used-percent", "80"),
+                ("x-codex-primary-reset-after-seconds", "120"),
+            ]);
+            assert_eq!(get_quota_near_exhaustion_wait_ms(&h, 5.0, NOW), 0);
+        }
+
+        #[test]
+        fn takes_the_max_wait_across_primary_and_secondary_windows() {
+            let h = headers(&[
+                ("x-codex-primary-used-percent", "100"),
+                ("x-codex-primary-reset-after-seconds", "60"),
+                ("x-codex-secondary-used-percent", "100"),
+                ("x-codex-secondary-reset-after-seconds", "300"),
+            ]);
+            assert_eq!(get_quota_near_exhaustion_wait_ms(&h, 5.0, NOW), 300_000);
+        }
+
+        #[test]
+        fn h1_clamps_absurd_reset_after_to_seven_days() {
+            let seven_days_ms = 7 * 24 * 60 * 60 * 1000;
+            let h = headers(&[
+                ("x-codex-primary-used-percent", "100"),
+                // ~31 years in seconds — a bogus/buggy upstream value.
+                ("x-codex-primary-reset-after-seconds", "999999999"),
+            ]);
+            assert_eq!(get_quota_near_exhaustion_wait_ms(&h, 5.0, NOW), seven_days_ms);
+        }
+
+        #[test]
+        fn supports_reset_at_in_epoch_seconds_ms_and_date_strings() {
+            let epoch_seconds = NOW / 1000 + 60;
+            assert_eq!(
+                get_quota_near_exhaustion_wait_ms(
+                    &headers(&[
+                        ("x-codex-primary-used-percent", "100"),
+                        ("x-codex-primary-reset-at", &epoch_seconds.to_string()),
+                    ]),
+                    5.0,
+                    NOW
+                ),
+                epoch_seconds * 1000 - NOW
+            );
+            assert_eq!(
+                get_quota_near_exhaustion_wait_ms(
+                    &headers(&[
+                        ("x-codex-primary-used-percent", "100"),
+                        ("x-codex-primary-reset-at", &(NOW + 30_000).to_string()),
+                    ]),
+                    5.0,
+                    NOW
+                ),
+                30_000
+            );
+            let date_wait = get_quota_near_exhaustion_wait_ms(
+                &headers(&[
+                    ("x-codex-primary-used-percent", "100"),
+                    ("x-codex-primary-reset-at", &utc_string(NOW + 90_000)),
+                ]),
+                5.0,
+                NOW,
+            );
+            assert!(date_wait > 88_000);
+            assert!(date_wait <= 90_000);
+        }
+
+        #[test]
+        fn returns_zero_when_no_usable_reset_signal_exists() {
+            assert_eq!(get_quota_near_exhaustion_wait_ms(&headers(&[]), 5.0, NOW), 0);
+            assert_eq!(
+                get_quota_near_exhaustion_wait_ms(
+                    &headers(&[("x-codex-primary-used-percent", "100")]),
+                    5.0,
+                    NOW
+                ),
+                0
+            );
+        }
+    }
+
+    mod exhaustion_status {
+        use super::*;
+
+        #[test]
+        fn maps_rate_limit_to_429_everything_else_to_503() {
+            assert_eq!(normalize_exhaustion_status("rate-limit"), 429);
+            assert_eq!(normalize_exhaustion_status("server-error"), 503);
+            assert_eq!(normalize_exhaustion_status("auth-failure"), 503);
+            assert_eq!(normalize_exhaustion_status("no-account"), 503);
+            assert_eq!(normalize_exhaustion_status("budget"), 503);
+        }
+    }
+
+    mod pinned_unavailable {
+        use super::*;
+
+        #[test]
+        fn includes_one_based_pinned_index_and_skip_reason() {
+            let body = build_pinned_unavailable_error_body(
+                Some(1),
+                &[(0, "rate-limited".to_string()), (1, "disabled".to_string())],
+            );
+            assert_eq!(body.code, "codex_pinned_account_unavailable");
+            assert_eq!(body.pinned_account_index, Some(1));
+            assert_eq!(body.reason.as_deref(), Some("disabled"));
+            assert!(body.message.contains("Pinned account 2"));
+            assert!(body.message.contains("(disabled)"));
+            let serialized = serde_json::to_value(&body).expect("serialize");
+            assert_eq!(
+                serialized["account_skip_reasons"],
+                serde_json::json!({"0": "rate-limited", "1": "disabled"})
+            );
+        }
+
+        #[test]
+        fn null_index_desync_path_omits_index_parenthetical_and_reason() {
+            let body = build_pinned_unavailable_error_body(None, &[]);
+            assert_eq!(body.pinned_account_index, None);
+            assert_eq!(body.reason, None);
+            assert!(body
+                .message
+                .contains("The pinned account is currently unavailable;"));
+            assert!(!body.message.contains("Pinned account 1"));
+            assert!(!body.message.contains('('));
+            assert!(body.account_skip_reasons.is_empty());
+            // Machine-readable nulls must serialize explicitly.
+            let serialized = serde_json::to_value(&body).expect("serialize");
+            assert!(serialized["pinnedAccountIndex"].is_null());
+            assert!(serialized["reason"].is_null());
+        }
+
+        #[test]
+        fn serialized_field_order_matches_ts_shape() {
+            let body = build_pinned_unavailable_error_body(Some(0), &[(0, "x".to_string())]);
+            let serialized = stringify_compact(&body);
+            let message_pos = serialized.find("\"message\"").unwrap();
+            let code_pos = serialized.find("\"code\"").unwrap();
+            let index_pos = serialized.find("\"pinnedAccountIndex\"").unwrap();
+            let reason_pos = serialized.find("\"reason\"").unwrap();
+            let skips_pos = serialized.find("\"account_skip_reasons\"").unwrap();
+            assert!(message_pos < code_pos);
+            assert!(code_pos < index_pos);
+            assert!(index_pos < reason_pos);
+            assert!(reason_pos < skips_pos);
+        }
+    }
+}
diff --git a/crates/request/src/request_init.rs b/crates/request/src/request_init.rs
new file mode 100644
index 000000000..36428f20d
--- /dev/null
+++ b/crates/request/src/request_init.rs
@@ -0,0 +1,253 @@
+//! Port of `lib/request/request-init.ts` — `fetch(input, init)` normalization.
+//!
+//! Behavior source: spec 06 §16 + the TS source (authority).
+//!
+//! The polymorphic web-fetch shapes collapse into concrete Rust types here:
+//! - `Request | string | URL` input → [`FetchInput`] (a [`NormalizedRequest`]
+//!   carries the already-buffered method/headers/url/body the proxy surface
+//!   extracted from hyper);
+//! - `RequestInit` → [`RequestInit`] with an optional [`BodyInit`]
+//!   (string vs raw-bytes body, mirroring the TS string / Uint8Array /
+//!   ArrayBuffer / view / Blob union).
+
+use http::header::HeaderMap;
+use serde_json::{Map, Value};
+use url::Url;
+
+/// The `fetch` body slot: TS `string | Uint8Array | ArrayBuffer | view | Blob`
+/// collapses to text vs bytes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BodyInit {
+    Text(String),
+    Bytes(Vec<u8>),
+}
+
+impl BodyInit {
+    /// Body text when the body is a string (TS `typeof init.body === "string"`).
+    pub fn as_text(&self) -> Option<&str> {
+        match self {
+            BodyInit::Text(text) => Some(text),
+            BodyInit::Bytes(_) => None,
+        }
+    }
+}
+
+/// TS `RequestInit` (the subset this pipeline carries).
+#[derive(Debug, Clone, Default)]
+pub struct RequestInit {
+    pub method: Option<String>,
+    pub headers: Option<HeaderMap>,
+    pub body: Option<BodyInit>,
+}
+
+/// A fully-buffered incoming request (the `Request` object analogue).
+#[derive(Debug, Clone)]
+pub struct NormalizedRequest {
+    pub url: String,
+    pub method: String,
+    pub headers: HeaderMap,
+    pub body: Option<Vec<u8>>,
+}
+
+/// TS `Request | string | URL` fetch input.
+#[derive(Debug, Clone)]
+pub enum FetchInput<'a> {
+    Url(&'a str),
+    Parsed(&'a Url),
+    Request(&'a NormalizedRequest),
+}
+
+/// TS `normalizeRequestInit(requestInput, requestInit)`.
+///
+/// - An existing `init` always wins.
+/// - Non-`Request` input passes through (`None`).
+/// - `Request` input yields `{ method: input.method || "GET", headers }`, plus
+///   the buffered body text for non-GET/HEAD methods when non-empty.
+pub fn normalize_request_init(
+    input: &FetchInput<'_>,
+    init: Option<RequestInit>,
+) -> Option<RequestInit> {
+    if init.is_some() {
+        return init;
+    }
+    let FetchInput::Request(request) = input else {
+        return None;
+    };
+
+    let method = if request.method.is_empty() {
+        "GET".to_string()
+    } else {
+        request.method.clone()
+    };
+    let mut normalized = RequestInit {
+        method: Some(method.clone()),
+        headers: Some(request.headers.clone()),
+        body: None,
+    };
+
+    if method != "GET" && method != "HEAD" {
+        // TS reads `await input.clone().text()` (UTF-8 decode) and swallows
+        // read failures; the buffered body is already available here.
+        if let Some(bytes) = request.body.as_ref() {
+            let body_text = String::from_utf8_lossy(bytes);
+            if !body_text.is_empty() {
+                normalized.body = Some(BodyInit::Text(body_text.into_owned()));
+            }
+        }
+    }
+
+    Some(normalized)
+}
+
+/// TS `parseRequestBodyFromInit(body, logWarn)`.
+///
+/// - Falsy body (`None`, and the empty **string** — TS `if (!body)`) → `{}`
+///   silently.
+/// - Empty **bytes** still attempt `JSON.parse("")` → warn + `{}` (TS quirk:
+///   `new Uint8Array(0)` is truthy).
+/// - Any parse failure → `logWarn("Failed to parse request body, using empty
+///   object")` and `{}`.
+/// - JSON that parses to a non-object is coerced to `{}` (the TS version
+///   returns the raw value behind a `Record` cast; every downstream consumer
+///   gates on it being a non-empty object, so this is behavior-equivalent).
+pub fn parse_request_body_from_init(
+    body: Option<&BodyInit>,
+    log_warn: &dyn Fn(&str),
+) -> Map<String, Value> {
+    let Some(body) = body else {
+        return Map::new();
+    };
+    let text: std::borrow::Cow<'_, str> = match body {
+        BodyInit::Text(text) => {
+            if text.is_empty() {
+                return Map::new();
+            }
+            std::borrow::Cow::Borrowed(text.as_str())
+        }
+        BodyInit::Bytes(bytes) => String::from_utf8_lossy(bytes),
+    };
+
+    match serde_json::from_str::<Value>(&text) {
+        Ok(Value::Object(map)) => map,
+        Ok(_) => Map::new(),
+        Err(_) => {
+            log_warn("Failed to parse request body, using empty object");
+            Map::new()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use std::cell::RefCell;
+
+    #[test]
+    fn normalizes_a_request_when_no_init_is_provided() {
+        let mut headers = HeaderMap::new();
+        headers.insert("content-type", "application/json".parse().unwrap());
+        let request = NormalizedRequest {
+            url: "https://example.com".into(),
+            method: "POST".into(),
+            headers,
+            body: Some(br#"{"hello":"world"}"#.to_vec()),
+        };
+
+        let normalized = normalize_request_init(&FetchInput::Request(&request), None).unwrap();
+        assert_eq!(normalized.method.as_deref(), Some("POST"));
+        assert_eq!(
+            normalized.body,
+            Some(BodyInit::Text(r#"{"hello":"world"}"#.into()))
+        );
+        assert!(normalized.headers.unwrap().contains_key("content-type"));
+    }
+
+    #[test]
+    fn returns_provided_init_unchanged() {
+        let init = RequestInit {
+            method: Some("GET".into()),
+            ..Default::default()
+        };
+        let result =
+            normalize_request_init(&FetchInput::Url("https://example.com"), Some(init)).unwrap();
+        assert_eq!(result.method.as_deref(), Some("GET"));
+        assert!(result.body.is_none());
+    }
+
+    #[test]
+    fn passes_through_for_plain_url_input_without_init() {
+        assert!(normalize_request_init(&FetchInput::Url("https://example.com"), None).is_none());
+        let url = Url::parse("https://example.com").unwrap();
+        assert!(normalize_request_init(&FetchInput::Parsed(&url), None).is_none());
+    }
+
+    #[test]
+    fn skips_body_for_get_and_head_and_defaults_empty_method_to_get() {
+        let request = NormalizedRequest {
+            url: "https://example.com".into(),
+            method: String::new(),
+            headers: HeaderMap::new(),
+            body: Some(b"ignored".to_vec()),
+        };
+        let normalized = normalize_request_init(&FetchInput::Request(&request), None).unwrap();
+        assert_eq!(normalized.method.as_deref(), Some("GET"));
+        assert!(normalized.body.is_none());
+    }
+
+    #[test]
+    fn parses_multiple_body_shapes_and_warns_on_invalid_payloads() {
+        let warnings: RefCell<Vec<String>> = RefCell::new(Vec::new());
+        let warn = |message: &str| warnings.borrow_mut().push(message.to_string());
+
+        assert_eq!(
+            Value::Object(parse_request_body_from_init(
+                Some(&BodyInit::Text(r#"{"a":1}"#.into())),
+                &warn
+            )),
+            json!({ "a": 1 })
+        );
+        assert_eq!(
+            Value::Object(parse_request_body_from_init(
+                Some(&BodyInit::Bytes(br#"{"b":2}"#.to_vec())),
+                &warn
+            )),
+            json!({ "b": 2 })
+        );
+        assert!(warnings.borrow().is_empty());
+
+        assert!(
+            parse_request_body_from_init(Some(&BodyInit::Text("not json".into())), &warn)
+                .is_empty()
+        );
+        assert_eq!(
+            warnings.borrow().as_slice(),
+            ["Failed to parse request body, using empty object"]
+        );
+    }
+
+    #[test]
+    fn falsy_and_empty_bodies_follow_ts_truthiness() {
+        let warnings: RefCell<Vec<String>> = RefCell::new(Vec::new());
+        let warn = |message: &str| warnings.borrow_mut().push(message.to_string());
+
+        // None and "" are falsy → {} without warning.
+        assert!(parse_request_body_from_init(None, &warn).is_empty());
+        assert!(
+            parse_request_body_from_init(Some(&BodyInit::Text(String::new())), &warn).is_empty()
+        );
+        assert!(warnings.borrow().is_empty());
+
+        // Empty byte arrays are truthy in TS → JSON.parse("") fails → warn.
+        assert!(parse_request_body_from_init(Some(&BodyInit::Bytes(Vec::new())), &warn).is_empty());
+        assert_eq!(warnings.borrow().len(), 1);
+    }
+
+    #[test]
+    fn non_object_json_coerces_to_empty_map_without_warning() {
+        let warnings: RefCell<Vec<String>> = RefCell::new(Vec::new());
+        let warn = |message: &str| warnings.borrow_mut().push(message.to_string());
+        assert!(parse_request_body_from_init(Some(&BodyInit::Text("5".into())), &warn).is_empty());
+        assert!(warnings.borrow().is_empty());
+    }
+}
diff --git a/crates/request/src/resilience.rs b/crates/request/src/resilience.rs
new file mode 100644
index 000000000..1a0264159
--- /dev/null
+++ b/crates/request/src/resilience.rs
@@ -0,0 +1,333 @@
+//! Port of `lib/request/request-resilience.ts` — per-process pool-exhaustion
+//! and server-burst cooldowns plus the adaptive stream-failover candidate
+//! order (spec 06 §17).
+//!
+//! **CRITICAL anti-requirement (spec 06 §23):** this is per-process in-memory
+//! state only; it must NEVER be serialized into persisted account/rate-limit
+//! files. No type here implements `Serialize`.
+//!
+//! Every entry point takes an explicit `now` (epoch ms) — the TS default of
+//! `Date.now()` is supplied by callers via `cma_core::utils::now_ms()`.
+
+use std::collections::HashSet;
+use std::sync::Mutex;
+
+use cma_core::schemas::account_storage::RateLimitStateV3;
+
+const POOL_EXHAUSTION_COOLDOWN_MS: i64 = 15_000;
+const SERVER_BURST_COOLDOWN_MS: i64 = 10_000;
+const SERVER_BURST_THRESHOLD: usize = 3;
+
+#[derive(Debug)]
+struct ServerBurstState {
+    window_started_at: i64,
+    account_indices: HashSet<usize>,
+    cooldown_until: Option<i64>,
+}
+
+impl ServerBurstState {
+    fn cleared() -> Self {
+        Self {
+            window_started_at: 0,
+            account_indices: HashSet::new(),
+            cooldown_until: None,
+        }
+    }
+}
+
+static POOL_EXHAUSTION_COOLDOWN_UNTIL: Mutex<Option<i64>> = Mutex::new(None);
+static SERVER_BURST_STATE: Mutex<Option<ServerBurstState>> = Mutex::new(None);
+
+fn with_burst_state<T>(f: impl FnOnce(&mut ServerBurstState) -> T) -> T {
+    let mut guard = SERVER_BURST_STATE
+        .lock()
+        .expect("server burst state poisoned");
+    f(guard.get_or_insert_with(ServerBurstState::cleared))
+}
+
+/// TS `getPoolExhaustionCooldownRemaining(now)` — 0 when unset/expired.
+pub fn get_pool_exhaustion_cooldown_remaining(now: i64) -> i64 {
+    let guard = POOL_EXHAUSTION_COOLDOWN_UNTIL
+        .lock()
+        .expect("pool exhaustion cooldown poisoned");
+    match *guard {
+        Some(until) if until > now => until - now,
+        _ => 0,
+    }
+}
+
+/// TS `armPoolExhaustionCooldown(waitMs, now)` — `bounded = max(15_000,
+/// floor(waitMs))`; the expiry is MONOTONIC (`max(existing, now + bounded)` —
+/// re-arming with a shorter wait never shortens it). Returns the expiry.
+pub fn arm_pool_exhaustion_cooldown(wait_ms: f64, now: i64) -> i64 {
+    let bounded = if wait_ms.is_finite() {
+        (wait_ms.floor() as i64).max(POOL_EXHAUSTION_COOLDOWN_MS)
+    } else if wait_ms.is_infinite() && wait_ms > 0.0 {
+        i64::MAX - now // Math.floor(Infinity) stays Infinity in TS; saturate.
+    } else {
+        POOL_EXHAUSTION_COOLDOWN_MS
+    };
+    let next_expiry = now.saturating_add(bounded);
+    let mut guard = POOL_EXHAUSTION_COOLDOWN_UNTIL
+        .lock()
+        .expect("pool exhaustion cooldown poisoned");
+    let updated = guard.unwrap_or(0).max(next_expiry);
+    *guard = Some(updated);
+    updated
+}
+
+/// TS `clearPoolExhaustionCooldown()`.
+pub fn clear_pool_exhaustion_cooldown() {
+    *POOL_EXHAUSTION_COOLDOWN_UNTIL
+        .lock()
+        .expect("pool exhaustion cooldown poisoned") = None;
+}
+
+/// TS `getServerBurstCooldownRemaining(now)`.
+pub fn get_server_burst_cooldown_remaining(now: i64) -> i64 {
+    with_burst_state(|state| match state.cooldown_until {
+        Some(until) if until > now => until - now,
+        _ => 0,
+    })
+}
+
+/// TS `recordServerBurstFailure(accountIndex, now)`.
+///
+/// While a cooldown is active it is returned unchanged (no accumulation).
+/// A window older than 10 s (with no active cooldown) resets the window.
+/// Once >= 3 DISTINCT account indices fail inside the window, the 10 s
+/// cooldown arms. Returns `cooldown_until ?? 0`.
+pub fn record_server_burst_failure(account_index: usize, now: i64) -> i64 {
+    with_burst_state(|state| {
+        if let Some(until) = state.cooldown_until
+            && until > now
+        {
+            return until;
+        }
+        let cooldown_expired = match state.cooldown_until {
+            None => true,
+            Some(until) => until <= now,
+        };
+        if cooldown_expired && now - state.window_started_at > SERVER_BURST_COOLDOWN_MS {
+            *state = ServerBurstState {
+                window_started_at: now,
+                account_indices: HashSet::new(),
+                cooldown_until: None,
+            };
+        }
+        if state.window_started_at == 0 {
+            state.window_started_at = now;
+        }
+        state.account_indices.insert(account_index);
+        if state.account_indices.len() >= SERVER_BURST_THRESHOLD {
+            state.cooldown_until = Some(now + SERVER_BURST_COOLDOWN_MS);
+        }
+        state.cooldown_until.unwrap_or(0)
+    })
+}
+
+/// TS `clearServerBurstCooldown()`.
+pub fn clear_server_burst_cooldown() {
+    *SERVER_BURST_STATE
+        .lock()
+        .expect("server burst state poisoned") = Some(ServerBurstState::cleared());
+}
+
+/// The `Pick<ManagedAccount, ...>` slice consumed by
+/// [`build_adaptive_stream_failover_candidate_order`]. Callers map their
+/// `cma_accounts::ManagedAccount`s into this shape (`index`,
+/// `last_used`, `enabled`, `cooling_down_until`, `rate_limit_reset_times`).
+#[derive(Clone, Debug, Default)]
+pub struct AdaptiveFailoverAccount {
+    pub index: usize,
+    pub last_used: Option<i64>,
+    /// TS convention: only an explicit `false` disables.
+    pub enabled: Option<bool>,
+    pub cooling_down_until: Option<i64>,
+    pub rate_limit_reset_times: RateLimitStateV3,
+}
+
+/// TS `buildAdaptiveStreamFailoverCandidateOrder(primaryIndex, accounts, now)`.
+///
+/// Alternates are accounts other than the primary that are not explicitly
+/// disabled, not cooling down, and hold NO rate-limit reset time in the
+/// future; sorted most-recently-used first (stable), take 1. The primary is
+/// always first (its own index when present in the snapshot, else
+/// `primary_index`).
+pub fn build_adaptive_stream_failover_candidate_order(
+    primary_index: usize,
+    accounts: &[AdaptiveFailoverAccount],
+    now: i64,
+) -> Vec<usize> {
+    let primary = accounts.iter().find(|account| account.index == primary_index);
+    let mut alternates: Vec<&AdaptiveFailoverAccount> = accounts
+        .iter()
+        .filter(|account| account.index != primary_index && account.enabled != Some(false))
+        .filter(|account| {
+            if account.cooling_down_until.unwrap_or(0) > now {
+                return false;
+            }
+            !account
+                .rate_limit_reset_times
+                .iter()
+                .any(|(_, value)| value > now)
+        })
+        .collect();
+    // JS `Array.prototype.sort` is stable; sort lastUsed DESC.
+    alternates.sort_by_key(|account| std::cmp::Reverse(account.last_used.unwrap_or(0)));
+    let mut order = vec![primary.map(|account| account.index).unwrap_or(primary_index)];
+    order.extend(alternates.iter().take(1).map(|account| account.index));
+    order
+}
+
+/// TS `resetRequestResilienceStateForTests()`.
+pub fn reset_request_resilience_state_for_tests() {
+    clear_pool_exhaustion_cooldown();
+    clear_server_burst_cooldown();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    fn base_now() -> i64 {
+        // Date.parse("2026-04-06T00:00:00.000Z")
+        chrono::DateTime::parse_from_rfc3339("2026-04-06T00:00:00.000Z")
+            .expect("valid date")
+            .timestamp_millis()
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn arms_and_clears_the_pool_exhaustion_cooldown() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        arm_pool_exhaustion_cooldown(5_000.0, now);
+        // The 15s floor applies: 15_000 - 1_000 elapsed = 14_000.
+        assert_eq!(get_pool_exhaustion_cooldown_remaining(now + 1_000), 14_000);
+        clear_pool_exhaustion_cooldown();
+        assert_eq!(get_pool_exhaustion_cooldown_remaining(now + 1_000), 0);
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn keeps_pool_exhaustion_cooldown_monotonic_on_shorter_rearm() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        let first = arm_pool_exhaustion_cooldown(30_000.0, now);
+        let second = arm_pool_exhaustion_cooldown(5_000.0, now + 1_000);
+        assert_eq!(second, first);
+        assert_eq!(get_pool_exhaustion_cooldown_remaining(now + 2_000), 28_000);
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn arms_server_burst_cooldown_after_multi_account_5xx_failures() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        assert_eq!(record_server_burst_failure(0, now), 0);
+        assert_eq!(record_server_burst_failure(1, now + 500), 0);
+        let cooldown_until = record_server_burst_failure(2, now + 1_000);
+        assert!(cooldown_until > now + 1_000);
+        assert!(get_server_burst_cooldown_remaining(now + 2_000) > 0);
+        clear_server_burst_cooldown();
+        assert_eq!(get_server_burst_cooldown_remaining(now + 2_000), 0);
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn same_account_repeats_do_not_arm_the_burst_cooldown() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        assert_eq!(record_server_burst_failure(0, now), 0);
+        assert_eq!(record_server_burst_failure(0, now + 100), 0);
+        assert_eq!(record_server_burst_failure(0, now + 200), 0);
+        assert_eq!(get_server_burst_cooldown_remaining(now + 300), 0);
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn keeps_armed_burst_cooldown_active_across_later_failures() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        assert_eq!(record_server_burst_failure(0, now), 0);
+        assert_eq!(record_server_burst_failure(1, now + 5_000), 0);
+        let cooldown_until = record_server_burst_failure(2, now + 9_000);
+        assert!(cooldown_until > now + 9_000);
+
+        let later_failure = record_server_burst_failure(3, now + 12_000);
+        assert_eq!(later_failure, cooldown_until);
+        assert!(get_server_burst_cooldown_remaining(now + 12_500) > 0);
+    }
+
+    #[test]
+    #[serial(request_resilience)]
+    fn stale_window_resets_before_counting() {
+        reset_request_resilience_state_for_tests();
+        let now = base_now();
+        assert_eq!(record_server_burst_failure(0, now), 0);
+        assert_eq!(record_server_burst_failure(1, now + 1_000), 0);
+        // > 10s later: the window resets, so this is failure #1 of a new window.
+        assert_eq!(record_server_burst_failure(2, now + 12_000), 0);
+        assert_eq!(get_server_burst_cooldown_remaining(now + 12_100), 0);
+    }
+
+    fn account(
+        index: usize,
+        last_used: i64,
+        cooling_down_until: Option<i64>,
+    ) -> AdaptiveFailoverAccount {
+        AdaptiveFailoverAccount {
+            index,
+            last_used: Some(last_used),
+            enabled: Some(true),
+            cooling_down_until,
+            rate_limit_reset_times: RateLimitStateV3::new(),
+        }
+    }
+
+    #[test]
+    fn prefers_freshest_eligible_alternate_for_stream_failover() {
+        let now = base_now();
+        let accounts = vec![
+            account(0, now - 5_000, None),
+            account(1, now - 20_000, None),
+            account(2, now - 1_000, None),
+            account(3, now, Some(now + 10_000)),
+        ];
+        assert_eq!(
+            build_adaptive_stream_failover_candidate_order(0, &accounts, now),
+            vec![0, 2]
+        );
+    }
+
+    #[test]
+    fn skips_rate_limited_and_disabled_alternates() {
+        let now = base_now();
+        let mut rate_limited = account(1, now, None);
+        rate_limited
+            .rate_limit_reset_times
+            .insert("gpt-5.2", now + 60_000);
+        let disabled = AdaptiveFailoverAccount {
+            enabled: Some(false),
+            ..account(2, now, None)
+        };
+        let ok = account(3, now - 50_000, None);
+        let accounts = vec![account(0, now, None), rate_limited, disabled, ok.clone()];
+        assert_eq!(
+            build_adaptive_stream_failover_candidate_order(0, &accounts, now),
+            vec![0, 3]
+        );
+    }
+
+    #[test]
+    fn missing_primary_falls_back_to_requested_index() {
+        let now = base_now();
+        let accounts = vec![account(4, now, None)];
+        assert_eq!(
+            build_adaptive_stream_failover_candidate_order(9, &accounts, now),
+            vec![9, 4]
+        );
+    }
+}
diff --git a/crates/request/src/response_compaction.rs b/crates/request/src/response_compaction.rs
new file mode 100644
index 000000000..145caafa2
--- /dev/null
+++ b/crates/request/src/response_compaction.rs
@@ -0,0 +1,744 @@
+//! Port of `lib/request/response-compaction.ts` — server-side `/compact`
+//! history compaction with a local trim fallback.
+//!
+//! Behavior source: spec 06 §18 + the TS source (authority).
+//!
+//! Sibling seam: the TS module calls `request-transformer.trimInputForFastSession`
+//! directly. That transformer module is a sibling agent's file, so the trim is
+//! injected as [`TrimInputForFastSession`]; the pipeline wires it to
+//! `crate::transformer::trim_input_for_fast_session` once that lands. The
+//! seam's `Option` return encodes the TS reference-identity contract
+//! (spec 06 gotcha 24): `None` = "no trim applied / identical input" — the
+//! `unchanged` signal — while `Some(items)` is a genuinely trimmed list.
+//!
+//! The TS `fetchImpl` injection maps to a `&reqwest::Client`; the
+//! AbortSignal pair (caller signal + local timeout controller) maps to an
+//! optional `CancellationToken` plus a `tokio::time::sleep` race.
+
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{log_debug, log_warn};
+use http::header::HeaderMap;
+use serde_json::{Map, Value, json};
+use tokio_util::sync::CancellationToken;
+
+use crate::fetch_helpers::DeferredFastSessionInputTrim;
+use crate::model_map::get_model_capabilities;
+use crate::response_handler::BoxError;
+
+/// Injected `transformer::trim_input_for_fast_session` (sibling seam — see
+/// module docs). Arguments mirror the TS call:
+/// `(input, maxItems, preferLatestUserOnly)`; `None` means "unchanged".
+pub type TrimInputForFastSession<'a> =
+    &'a (dyn Fn(&[Value], f64, bool) -> Option<Vec<Value>> + Send + Sync);
+
+/// TS `ResponseCompactionResult.mode`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResponseCompactionMode {
+    Compacted,
+    Trimmed,
+    Unchanged,
+}
+
+impl ResponseCompactionMode {
+    /// The TS literal for this mode.
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ResponseCompactionMode::Compacted => "compacted",
+            ResponseCompactionMode::Trimmed => "trimmed",
+            ResponseCompactionMode::Unchanged => "unchanged",
+        }
+    }
+}
+
+/// TS `ResponseCompactionResult`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResponseCompactionResult {
+    pub body: Map<String, Value>,
+    pub mode: ResponseCompactionMode,
+}
+
+/// TS `ApplyResponseCompactionParams`.
+pub struct ApplyResponseCompactionParams<'a> {
+    /// The (already transformed) request body object.
+    pub body: &'a Map<String, Value>,
+    pub request_url: &'a str,
+    /// Headers of the original request; copied with `accept`/`content-type`
+    /// forced to `application/json` for the compaction POST.
+    pub headers: &'a HeaderMap,
+    pub trim: DeferredFastSessionInputTrim,
+    /// TS `fetchImpl`.
+    pub client: &'a reqwest::Client,
+    /// TS `signal` — caller-side abort.
+    pub cancel: Option<&'a CancellationToken>,
+    /// TS `timeoutMs` — floored at 250 ms, default 4_000 ms.
+    pub timeout_ms: Option<f64>,
+    /// Sibling seam (see module docs).
+    pub trim_input: TrimInputForFastSession<'a>,
+}
+
+fn is_input_item_array(value: &Value) -> Option<&Vec<Value>> {
+    let items = value.as_array()?;
+    // TS `isInputItemArray`: every element must be a record. An EMPTY array
+    // passes (`[].every(...)` is true) — the caller's length check handles it.
+    if items.iter().all(|item| item.is_object()) {
+        Some(items)
+    } else {
+        None
+    }
+}
+
+/// TS `extractCompactedInput(payload)` — first array-of-records among
+/// `payload.output`, `payload.input`, `payload.response.output`,
+/// `payload.response.input`.
+fn extract_compacted_input(payload: &Value) -> Option<Vec<Value>> {
+    if !payload.is_object() {
+        return None;
+    }
+    if let Some(items) = payload.get("output").and_then(is_input_item_array) {
+        return Some(items.clone());
+    }
+    if let Some(items) = payload.get("input").and_then(is_input_item_array) {
+        return Some(items.clone());
+    }
+    let response = payload.get("response")?;
+    if !response.is_object() {
+        return None;
+    }
+    if let Some(items) = response.get("output").and_then(is_input_item_array) {
+        return Some(items.clone());
+    }
+    if let Some(items) = response.get("input").and_then(is_input_item_array) {
+        return Some(items.clone());
+    }
+    None
+}
+
+/// TS `buildCompactionUrl(requestUrl)`: base path (query stripped) gets
+/// `/compact` appended (idempotent), query string preserved after it.
+fn build_compaction_url(request_url: &str) -> String {
+    let query_index = request_url.find('?');
+    let base_url = match query_index {
+        None => request_url,
+        Some(index) => &request_url[..index],
+    };
+    if base_url.ends_with("/compact") {
+        return request_url.to_string();
+    }
+    match query_index {
+        None => format!("{request_url}/compact"),
+        Some(index) => format!("{base_url}/compact{}", &request_url[index..]),
+    }
+}
+
+/// TS `createFallbackBody(body, trim)`: local trim of `body.input`; `None`
+/// when the input is not an array or the trim is an identity (the caller's
+/// "unchanged" signal).
+fn create_fallback_body(
+    body: &Map<String, Value>,
+    trim: &DeferredFastSessionInputTrim,
+    trim_input: TrimInputForFastSession<'_>,
+) -> Option<Map<String, Value>> {
+    let input = body.get("input")?.as_array()?;
+    let trimmed = trim_input(input, trim.max_items, trim.prefer_latest_user_only)?;
+    let mut fallback = body.clone();
+    fallback.insert("input".to_string(), Value::Array(trimmed));
+    Some(fallback)
+}
+
+enum CompactionRequestOutcome {
+    HttpFailure { status: u16, status_text: String },
+    Payload(Value),
+    TransportError(String),
+}
+
+async fn run_compaction_request(
+    params: &ApplyResponseCompactionParams<'_>,
+    compaction_url: &str,
+) -> CompactionRequestOutcome {
+    let mut compaction_headers = params.headers.clone();
+    compaction_headers.insert("accept", http::HeaderValue::from_static("application/json"));
+    compaction_headers.insert(
+        "content-type",
+        http::HeaderValue::from_static("application/json"),
+    );
+
+    // TS: JSON.stringify({ model, input }) — `model` is dropped only when
+    // absent (JS `undefined`); an explicit null survives.
+    let mut request_body = Map::new();
+    if let Some(model) = params.body.get("model") {
+        request_body.insert("model".to_string(), model.clone());
+    }
+    if let Some(input) = params.body.get("input") {
+        request_body.insert("input".to_string(), input.clone());
+    }
+
+    let response = match params
+        .client
+        .post(compaction_url)
+        .headers(compaction_headers)
+        .body(stringify_compact(&Value::Object(request_body)))
+        .send()
+        .await
+    {
+        Ok(response) => response,
+        Err(error) => return CompactionRequestOutcome::TransportError(error.to_string()),
+    };
+
+    let status = response.status();
+    if !status.is_success() {
+        return CompactionRequestOutcome::HttpFailure {
+            status: status.as_u16(),
+            status_text: status.canonical_reason().unwrap_or("").to_string(),
+        };
+    }
+
+    let text = match response.text().await {
+        Ok(text) => text,
+        Err(error) => return CompactionRequestOutcome::TransportError(error.to_string()),
+    };
+    match serde_json::from_str::<Value>(&text) {
+        Ok(payload) => CompactionRequestOutcome::Payload(payload),
+        Err(error) => CompactionRequestOutcome::TransportError(error.to_string()),
+    }
+}
+
+/// TS `applyResponseCompaction(params)`.
+///
+/// Errors only on caller abort (the TS rethrow of `params.signal.reason`);
+/// every other failure degrades to the local trim fallback.
+pub async fn apply_response_compaction(
+    params: ApplyResponseCompactionParams<'_>,
+) -> Result<ResponseCompactionResult, BoxError> {
+    let model_value = params.body.get("model").and_then(Value::as_str);
+
+    let Some(fallback_body) = create_fallback_body(params.body, &params.trim, params.trim_input)
+    else {
+        return Ok(ResponseCompactionResult {
+            body: params.body.clone(),
+            mode: ResponseCompactionMode::Unchanged,
+        });
+    };
+
+    if !get_model_capabilities(model_value).compaction {
+        return Ok(ResponseCompactionResult {
+            body: fallback_body,
+            mode: ResponseCompactionMode::Trimmed,
+        });
+    }
+
+    // TS `createTimedAbortSignal`: pre-aborted caller signal aborts before the
+    // fetch is issued; the catch path then rethrows the caller's reason.
+    if params.cancel.is_some_and(|token| token.is_cancelled()) {
+        return Err("Aborted".into());
+    }
+
+    let timeout_ms = params.timeout_ms.unwrap_or(4_000.0).max(250.0).floor() as u64;
+    let compaction_url = build_compaction_url(params.request_url);
+    let model_log = params.body.get("model").cloned().unwrap_or(Value::Null);
+
+    let outcome = {
+        let request = run_compaction_request(&params, &compaction_url);
+        tokio::pin!(request);
+        let timeout = tokio::time::sleep(std::time::Duration::from_millis(timeout_ms));
+        tokio::pin!(timeout);
+
+        let cancelled = async {
+            match params.cancel {
+                Some(token) => token.cancelled().await,
+                None => std::future::pending::<()>().await,
+            }
+        };
+        tokio::pin!(cancelled);
+
+        tokio::select! {
+            outcome = &mut request => Some(outcome),
+            _ = &mut timeout => None,
+            _ = &mut cancelled => {
+                // Caller abort — TS rethrows `params.signal.reason` (or a
+                // plain `Error("Aborted")`; the reason object itself does not
+                // survive the Rust boundary).
+                return Err("Aborted".into());
+            }
+        }
+    };
+
+    let Some(outcome) = outcome else {
+        // Local timeout abort: warn + trim fallback (frozen strings).
+        log_warn(
+            "Responses compaction failed; using trim fallback.",
+            Some(&json!({
+                "model": model_log,
+                "error": "Response compaction timeout",
+            })),
+        );
+        return Ok(ResponseCompactionResult {
+            body: fallback_body,
+            mode: ResponseCompactionMode::Trimmed,
+        });
+    };
+
+    match outcome {
+        CompactionRequestOutcome::HttpFailure {
+            status,
+            status_text,
+        } => {
+            log_warn(
+                "Responses compaction request failed; using trim fallback.",
+                Some(&json!({
+                    "status": status,
+                    "statusText": status_text,
+                    "model": model_log,
+                })),
+            );
+            Ok(ResponseCompactionResult {
+                body: fallback_body,
+                mode: ResponseCompactionMode::Trimmed,
+            })
+        }
+        CompactionRequestOutcome::TransportError(error) => {
+            log_warn(
+                "Responses compaction failed; using trim fallback.",
+                Some(&json!({ "model": model_log, "error": error })),
+            );
+            Ok(ResponseCompactionResult {
+                body: fallback_body,
+                mode: ResponseCompactionMode::Trimmed,
+            })
+        }
+        CompactionRequestOutcome::Payload(payload) => {
+            let compacted_input = extract_compacted_input(&payload);
+            let Some(compacted_input) = compacted_input.filter(|items| !items.is_empty()) else {
+                log_warn(
+                    "Responses compaction returned no reusable input; using trim fallback.",
+                    Some(&json!({ "model": model_log })),
+                );
+                return Ok(ResponseCompactionResult {
+                    body: fallback_body,
+                    mode: ResponseCompactionMode::Trimmed,
+                });
+            };
+
+            let original_input_length = params
+                .body
+                .get("input")
+                .and_then(Value::as_array)
+                .map(Vec::len)
+                .unwrap_or(0);
+            log_debug(
+                "Applied server-side response compaction.",
+                Some(&json!({
+                    "model": model_log,
+                    "originalInputLength": original_input_length,
+                    "compactedInputLength": compacted_input.len(),
+                })),
+            );
+
+            let mut compacted_body = params.body.clone();
+            compacted_body.insert("input".to_string(), Value::Array(compacted_input));
+            Ok(ResponseCompactionResult {
+                body: compacted_body,
+                mode: ResponseCompactionMode::Compacted,
+            })
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wiremock::matchers::{header, method, path, query_param};
+    use wiremock::{Mock, MockServer, Request, ResponseTemplate};
+
+    fn build_input(length: usize) -> Vec<Value> {
+        (0..length)
+            .map(|index| {
+                json!({
+                    "type": "message",
+                    "role": if index == 0 { "developer" } else { "user" },
+                    "content": if index == 0 {
+                        "system prompt".to_string()
+                    } else {
+                        format!("message-{index}")
+                    },
+                })
+            })
+            .collect()
+    }
+
+    fn body_with_input(model: &str, length: usize) -> Map<String, Value> {
+        let mut body = Map::new();
+        body.insert("model".to_string(), Value::String(model.to_string()));
+        body.insert("input".to_string(), Value::Array(build_input(length)));
+        body
+    }
+
+    /// Fake `trimInputForFastSession`: identity (`None`) when the input
+    /// already fits, else keep the last `max_items` items.
+    fn fake_trim(input: &[Value], max_items: f64, _prefer_latest_user_only: bool) -> Option<Vec<Value>> {
+        let max = max_items.floor().max(0.0) as usize;
+        if input.len() <= max {
+            return None;
+        }
+        Some(input[input.len() - max..].to_vec())
+    }
+
+    fn trim_directive(max_items: f64) -> DeferredFastSessionInputTrim {
+        DeferredFastSessionInputTrim {
+            max_items,
+            prefer_latest_user_only: false,
+        }
+    }
+
+    #[test]
+    fn compaction_url_builder_matches_ts() {
+        assert_eq!(
+            build_compaction_url("https://chatgpt.com/backend-api/codex/responses"),
+            "https://chatgpt.com/backend-api/codex/responses/compact"
+        );
+        assert_eq!(
+            build_compaction_url("https://chatgpt.com/backend-api/codex/responses?stream=true"),
+            "https://chatgpt.com/backend-api/codex/responses/compact?stream=true"
+        );
+        assert_eq!(
+            build_compaction_url("https://x.test/responses/compact?x=1"),
+            "https://x.test/responses/compact?x=1"
+        );
+        assert_eq!(
+            build_compaction_url("https://x.test/responses/compact"),
+            "https://x.test/responses/compact"
+        );
+    }
+
+    #[tokio::test]
+    async fn returns_unchanged_when_the_fast_session_trim_would_be_a_no_op() {
+        let body = body_with_input("gpt-5.4", 2);
+        let client = reqwest::Client::new();
+
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            // Unroutable: any fetch attempt would error rather than pass.
+            request_url: "http://127.0.0.1:9/responses",
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(result.mode, ResponseCompactionMode::Unchanged);
+        assert_eq!(result.body.get("input"), body.get("input"));
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_local_trimming_when_the_model_does_not_support_compaction() {
+        // gpt-5-codex resolves to gpt-5.3-codex → `basic` capabilities.
+        let body = body_with_input("gpt-5-codex", 10);
+        let client = reqwest::Client::new();
+
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: "http://127.0.0.1:9/responses",
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(result.mode, ResponseCompactionMode::Trimmed);
+        assert_eq!(result.body.get("input").unwrap().as_array().unwrap().len(), 8);
+    }
+
+    #[tokio::test]
+    async fn replaces_request_input_with_server_compacted_output_when_available() {
+        let compacted_output = vec![json!({
+            "type": "message",
+            "role": "assistant",
+            "content": "compacted summary",
+        })];
+
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/backend-api/codex/responses/compact"))
+            .and(header("accept", "application/json"))
+            .and(header("content-type", "application/json"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({ "output": compacted_output.clone() })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let body = body_with_input("gpt-5-mini", 12);
+        let client = reqwest::Client::new();
+        let mut headers = HeaderMap::new();
+        headers.insert("accept", "text/event-stream".parse().unwrap());
+
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+            headers: &headers,
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(result.mode, ResponseCompactionMode::Compacted);
+        assert_eq!(
+            result.body.get("input").unwrap(),
+            &Value::Array(compacted_output)
+        );
+
+        // The compaction POST carries {model, input} of the ORIGINAL body.
+        let requests = server.received_requests().await.unwrap();
+        let request: &Request = &requests[0];
+        let sent: Value = serde_json::from_slice(&request.body).unwrap();
+        assert_eq!(sent.get("model"), Some(&Value::String("gpt-5-mini".into())));
+        assert_eq!(
+            sent.get("input").unwrap().as_array().unwrap().len(),
+            12
+        );
+    }
+
+    #[tokio::test]
+    async fn inserts_compact_before_query_params_in_the_compaction_request_url() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/backend-api/codex/responses/compact"))
+            .and(query_param("stream", "true"))
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(json!({ "output": build_input(8) })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let body = body_with_input("gpt-5-mini", 12);
+        let client = reqwest::Client::new();
+
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses?stream=true", server.uri()),
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+        assert_eq!(result.mode, ResponseCompactionMode::Compacted);
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_local_trimming_when_the_compaction_request_fails() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/backend-api/codex/responses/compact"))
+            .respond_with(
+                ResponseTemplate::new(404).set_body_json(json!({
+                    "error": { "message": "nope" }
+                })),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+
+        let body = body_with_input("gpt-5.4", 12);
+        let client = reqwest::Client::new();
+
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(result.mode, ResponseCompactionMode::Trimmed);
+        assert_eq!(result.body.get("input").unwrap().as_array().unwrap().len(), 8);
+    }
+
+    #[tokio::test]
+    async fn empty_and_malformed_payloads_use_the_trim_fallback() {
+        for payload in [
+            json!({}),
+            json!({ "output": [] }),
+            json!({ "output": ["not-a-record"] }),
+            json!({ "response": { "input": [] } }),
+        ] {
+            let server = MockServer::start().await;
+            Mock::given(method("POST"))
+                .respond_with(ResponseTemplate::new(200).set_body_json(payload))
+                .mount(&server)
+                .await;
+
+            let body = body_with_input("gpt-5.4", 12);
+            let client = reqwest::Client::new();
+            let result = apply_response_compaction(ApplyResponseCompactionParams {
+                body: &body,
+                request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+                headers: &HeaderMap::new(),
+                trim: trim_directive(8.0),
+                client: &client,
+                cancel: None,
+                timeout_ms: None,
+                trim_input: &fake_trim,
+            })
+            .await
+            .unwrap();
+            assert_eq!(result.mode, ResponseCompactionMode::Trimmed);
+        }
+    }
+
+    #[tokio::test]
+    async fn nested_response_envelopes_are_extracted() {
+        let compacted = build_input(3);
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({ "response": { "output": compacted.clone() } })),
+            )
+            .mount(&server)
+            .await;
+
+        let body = body_with_input("gpt-5.4", 12);
+        let client = reqwest::Client::new();
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+        assert_eq!(result.mode, ResponseCompactionMode::Compacted);
+        assert_eq!(result.body.get("input").unwrap(), &Value::Array(compacted));
+    }
+
+    #[tokio::test]
+    async fn transport_failures_degrade_to_the_trim_fallback() {
+        let body = body_with_input("gpt-5.4", 12);
+        let client = reqwest::Client::new();
+        // Nothing listens on port 9 (discard) — connection refused.
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: "http://127.0.0.1:9/responses",
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            timeout_ms: Some(2_000.0),
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+        assert_eq!(result.mode, ResponseCompactionMode::Trimmed);
+    }
+
+    #[tokio::test]
+    async fn timeouts_degrade_to_the_trim_fallback() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({ "output": build_input(3) }))
+                    .set_delay(std::time::Duration::from_millis(5_000)),
+            )
+            .mount(&server)
+            .await;
+
+        let body = body_with_input("gpt-5.4", 12);
+        let client = reqwest::Client::new();
+        let started = std::time::Instant::now();
+        let result = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: None,
+            // Floors at 250 ms (TS `max(250, timeoutMs ?? 4000)`).
+            timeout_ms: Some(1.0),
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap();
+        assert_eq!(result.mode, ResponseCompactionMode::Trimmed);
+        assert!(started.elapsed() < std::time::Duration::from_secs(4));
+    }
+
+    #[tokio::test]
+    async fn caller_abort_is_rethrown_instead_of_falling_back() {
+        // Pre-aborted caller signal.
+        let body = body_with_input("gpt-5.4", 12);
+        let client = reqwest::Client::new();
+        let cancel = CancellationToken::new();
+        cancel.cancel();
+        let error = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: "http://127.0.0.1:9/responses",
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: Some(&cancel),
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap_err();
+        assert_eq!(error.to_string(), "Aborted");
+
+        // Abort while the request is in flight.
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({ "output": build_input(3) }))
+                    .set_delay(std::time::Duration::from_millis(5_000)),
+            )
+            .mount(&server)
+            .await;
+        let cancel = CancellationToken::new();
+        let abort_after = cancel.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+            abort_after.cancel();
+        });
+        let error = apply_response_compaction(ApplyResponseCompactionParams {
+            body: &body,
+            request_url: &format!("{}/backend-api/codex/responses", server.uri()),
+            headers: &HeaderMap::new(),
+            trim: trim_directive(8.0),
+            client: &client,
+            cancel: Some(&cancel),
+            timeout_ms: None,
+            trim_input: &fake_trim,
+        })
+        .await
+        .unwrap_err();
+        assert_eq!(error.to_string(), "Aborted");
+    }
+}
diff --git a/crates/request/src/response_handler.rs b/crates/request/src/response_handler.rs
new file mode 100644
index 000000000..5f3f6f44b
--- /dev/null
+++ b/crates/request/src/response_handler.rs
@@ -0,0 +1,1684 @@
+//! Port of `lib/request/response-handler.ts` — SSE parsing & response
+//! reconstruction (spec 06 §5; ARCHITECTURE §6.10 + §11 risk 1).
+//!
+//! This module is THE parity-critical SSE state machine:
+//! - `response.incomplete` is a SUCCESS terminal event (partial output IS the
+//!   answer — re-audit correction to stress-audit H7).
+//! - `error` / `response.failed` ⇒ synthetic 502 `sse_terminal_error` (or the
+//!   upstream status when it was already >= 400).
+//! - No terminal event and no error ⇒ raw SSE passthrough at the ORIGINAL
+//!   status (feeds the caller's empty-response retry path — never an error).
+//! - `data:` lines parse with AND without the space after the colon (M1).
+//! - `[DONE]` and empty payloads are skipped; malformed JSON is counted and
+//!   warned once (+ rollup), never fatal.
+//!
+//! The TS `Response` object is modelled as [`StreamResponse`]: status +
+//! statusText + `http::HeaderMap` + an optional boxed byte stream. reqwest
+//! (`bytes_stream()`) and hyper (`Body::from_stream`) both map onto it.
+
+use std::collections::HashSet;
+use std::sync::Arc;
+
+use bytes::Bytes;
+use futures::StreamExt;
+use futures::stream::BoxStream;
+use http::HeaderMap;
+use http::header::{CONTENT_TYPE, HeaderValue};
+use serde_json::{Map, Value};
+
+use cma_core::constants::{HTTP_STATUS, PLUGIN_NAME};
+use cma_core::json_io::stringify_compact;
+use cma_core::logger::{ScopedLogger, create_logger, log_request, logging_enabled};
+use cma_core::utils::is_record;
+
+/// 10 MiB limit to prevent memory exhaustion (TS `MAX_SSE_SIZE`).
+pub const MAX_SSE_SIZE: usize = 10 * 1024 * 1024;
+/// TS `DEFAULT_STREAM_STALL_TIMEOUT_MS`.
+pub const DEFAULT_STREAM_STALL_TIMEOUT_MS: f64 = 45_000.0;
+/// TS `MAX_SYNTHESIZED_EVENT_INDEX` — indexes above this are ignored, not errors.
+pub const MAX_SYNTHESIZED_EVENT_INDEX: usize = 255;
+
+/// Boxed error used across the request streaming layer (TS thrown `Error`s).
+pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
+/// Byte-stream body: the Rust analogue of a web `ReadableStream<Uint8Array>`.
+pub type BodyStream = BoxStream<'static, Result<Bytes, BoxError>>;
+/// TS `onResponseId` callback. Rust closures cannot throw, so the TS
+/// exception-swallowing around the callback has no analogue.
+pub type ResponseIdCallback = Arc<dyn Fn(&str) + Send + Sync + 'static>;
+
+fn log() -> ScopedLogger {
+    create_logger("response-handler")
+}
+
+// ---------------------------------------------------------------------------
+// StreamResponse — the fetch `Response` analogue shared by this crate's
+// streaming modules (stream_failover, stream_failover_runtime,
+// context_overflow all import it from here, mirroring the TS import graph).
+// ---------------------------------------------------------------------------
+
+/// Rust analogue of the web `Response` used by the TS request cluster.
+///
+/// The body is a one-shot byte stream (no `.clone()` — callers that need to
+/// inspect a body AND return it must buffer the bytes first; that is the TS
+/// "clone before read" pattern, e.g. `isEmptyResponse` callers clone the
+/// Response before parsing so the returned body stays readable).
+pub struct StreamResponse {
+    pub status: u16,
+    pub status_text: String,
+    pub headers: HeaderMap,
+    pub body: Option<BodyStream>,
+}
+
+impl std::fmt::Debug for StreamResponse {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StreamResponse")
+            .field("status", &self.status)
+            .field("status_text", &self.status_text)
+            .field("headers", &self.headers)
+            .field("body", &self.body.as_ref().map(|_| "<stream>"))
+            .finish()
+    }
+}
+
+/// Build a single-chunk body stream from bytes.
+pub fn body_stream_from_bytes(bytes: Bytes) -> BodyStream {
+    futures::stream::once(async move { Ok(bytes) }).boxed()
+}
+
+impl StreamResponse {
+    pub fn new(
+        status: u16,
+        status_text: impl Into<String>,
+        headers: HeaderMap,
+        body: Option<BodyStream>,
+    ) -> Self {
+        Self { status, status_text: status_text.into(), headers, body }
+    }
+
+    /// Response with a single-chunk UTF-8 text body.
+    pub fn from_text(
+        status: u16,
+        status_text: impl Into<String>,
+        headers: HeaderMap,
+        text: impl Into<String>,
+    ) -> Self {
+        Self::new(status, status_text, headers, Some(body_stream_from_bytes(Bytes::from(text.into()))))
+    }
+
+    /// Response with a single-chunk byte body.
+    pub fn from_bytes(
+        status: u16,
+        status_text: impl Into<String>,
+        headers: HeaderMap,
+        bytes: Bytes,
+    ) -> Self {
+        Self::new(status, status_text, headers, Some(body_stream_from_bytes(bytes)))
+    }
+
+    /// `response.ok` analogue: `true` for 2xx statuses.
+    pub fn ok(&self) -> bool {
+        (200..300).contains(&self.status)
+    }
+
+    /// Consume the body, collecting it into a lossily-decoded UTF-8 string
+    /// (TS `await response.text()`). A body-less response yields `""`.
+    /// Propagates the first stream error.
+    pub async fn collect_text(&mut self) -> Result<String, BoxError> {
+        let bytes = self.collect_bytes().await?;
+        Ok(String::from_utf8_lossy(&bytes).into_owned())
+    }
+
+    /// Consume the body into raw bytes.
+    pub async fn collect_bytes(&mut self) -> Result<Vec<u8>, BoxError> {
+        let Some(mut body) = self.body.take() else {
+            return Ok(Vec::new());
+        };
+        let mut out: Vec<u8> = Vec::new();
+        while let Some(item) = body.next().await {
+            out.extend_from_slice(&item?);
+        }
+        Ok(out)
+    }
+
+    /// Consume the body and parse it as JSON (TS `await response.json()`).
+    pub async fn collect_json(&mut self) -> Result<Value, BoxError> {
+        let text = self.collect_text().await?;
+        Ok(serde_json::from_str(&text)?)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Incremental UTF-8 decoder — `TextDecoder(..., { stream: true })` analogue.
+// ---------------------------------------------------------------------------
+
+/// Streaming UTF-8 decoder: holds back an incomplete trailing multi-byte
+/// sequence between chunks; invalid sequences become U+FFFD (lossy), matching
+/// the WHATWG TextDecoder's non-fatal mode closely enough for SSE payloads.
+#[derive(Debug, Default)]
+struct Utf8StreamDecoder {
+    carry: Vec<u8>,
+}
+
+/// Index where an incomplete trailing UTF-8 sequence starts, or `len` when the
+/// buffer ends on a complete (or irrecoverably invalid) boundary.
+fn incomplete_suffix_start(buf: &[u8]) -> usize {
+    let len = buf.len();
+    if len == 0 {
+        return 0;
+    }
+    let lower = len.saturating_sub(3);
+    let mut i = len;
+    while i > lower {
+        i -= 1;
+        let b = buf[i];
+        if b < 0x80 {
+            // ASCII: everything after it (continuations without a lead) is
+            // invalid, not incomplete — decode it all (lossy replacement).
+            return len;
+        }
+        if b >= 0xC0 {
+            // Lead byte: hold it back when its sequence is still incomplete.
+            let need = if b >= 0xF0 {
+                4
+            } else if b >= 0xE0 {
+                3
+            } else {
+                2
+            };
+            return if i + need > len { i } else { len };
+        }
+        // Continuation byte — keep scanning backwards.
+    }
+    len
+}
+
+impl Utf8StreamDecoder {
+    /// `decoder.decode(value, { stream: true })`.
+    fn decode_stream(&mut self, chunk: &[u8]) -> String {
+        let mut buf = std::mem::take(&mut self.carry);
+        buf.extend_from_slice(chunk);
+        let split = incomplete_suffix_start(&buf);
+        self.carry = buf[split..].to_vec();
+        String::from_utf8_lossy(&buf[..split]).into_owned()
+    }
+
+    /// `decoder.decode()` — flush: an incomplete trailing sequence becomes
+    /// replacement characters.
+    fn flush(&mut self) -> String {
+        let rest = std::mem::take(&mut self.carry);
+        String::from_utf8_lossy(&rest).into_owned()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// OrderedMap — JS `Map` semantics (insertion-order iteration, in-place update
+// on re-set, order-preserving delete). serde_json's preserve_order Map uses
+// swap_remove on delete, which would corrupt iteration order — so the parser
+// state uses this tiny Vec-backed map instead.
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone)]
+struct OrderedMap<K, V> {
+    entries: Vec<(K, V)>,
+}
+
+impl<K: PartialEq, V> OrderedMap<K, V> {
+    fn new() -> Self {
+        Self { entries: Vec::new() }
+    }
+
+    fn get(&self, key: &K) -> Option<&V> {
+        self.entries.iter().find(|(k, _)| k == key).map(|(_, v)| v)
+    }
+
+    fn get_mut(&mut self, key: &K) -> Option<&mut V> {
+        self.entries.iter_mut().find(|(k, _)| k == key).map(|(_, v)| v)
+    }
+
+    /// JS `map.set(key, value)`: update in place keeping position, else append.
+    fn set(&mut self, key: K, value: V) {
+        if let Some(existing) = self.get_mut(&key) {
+            *existing = value;
+        } else {
+            self.entries.push((key, value));
+        }
+    }
+
+    /// JS `map.delete(key)`: order of remaining entries preserved.
+    fn remove(&mut self, key: &K) {
+        if let Some(pos) = self.entries.iter().position(|(k, _)| k == key) {
+            self.entries.remove(pos);
+        }
+    }
+
+    fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    fn iter(&self) -> std::slice::Iter<'_, (K, V)> {
+        self.entries.iter()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Parser state
+// ---------------------------------------------------------------------------
+
+type JsonMap = Map<String, Value>;
+
+struct ParsedResponseState {
+    final_response: Option<JsonMap>,
+    last_phase: Option<String>,
+    output_items: OrderedMap<usize, JsonMap>,
+    output_text: OrderedMap<String, String>,
+    output_text_phases: OrderedMap<String, String>,
+    phase_text_segments: OrderedMap<String, String>,
+    phase_segment_order: OrderedMap<String, Vec<String>>,
+    phase_text: OrderedMap<String, String>,
+    reasoning_summary_text: OrderedMap<String, String>,
+    seen_response_ids: HashSet<String>,
+    encountered_error: bool,
+}
+
+fn create_parsed_response_state() -> ParsedResponseState {
+    ParsedResponseState {
+        final_response: None,
+        last_phase: None,
+        output_items: OrderedMap::new(),
+        output_text: OrderedMap::new(),
+        output_text_phases: OrderedMap::new(),
+        phase_text_segments: OrderedMap::new(),
+        phase_segment_order: OrderedMap::new(),
+        phase_text: OrderedMap::new(),
+        reasoning_summary_text: OrderedMap::new(),
+        seen_response_ids: HashSet::new(),
+        encountered_error: false,
+    }
+}
+
+fn to_mutable_record(value: Option<&Value>) -> Option<JsonMap> {
+    match value {
+        Some(Value::Object(map)) => Some(map.clone()),
+        _ => None,
+    }
+}
+
+fn get_number_field(record: &JsonMap, key: &str) -> Option<f64> {
+    record.get(key).and_then(Value::as_f64).filter(|v| v.is_finite())
+}
+
+/// Trimmed, non-empty string field for identifier-like values.
+/// Returns the ORIGINAL (untrimmed) string, matching TS `getStringField`.
+fn get_string_field(record: &JsonMap, key: &str) -> Option<String> {
+    match record.get(key) {
+        Some(Value::String(s)) if !s.trim().is_empty() => Some(s.clone()),
+        _ => None,
+    }
+}
+
+/// Non-empty string field where whitespace is meaningful (TS `getDeltaField`).
+fn get_delta_field(record: &JsonMap, key: &str) -> Option<String> {
+    match record.get(key) {
+        Some(Value::String(s)) if !s.is_empty() => Some(s.clone()),
+        _ => None,
+    }
+}
+
+/// TS `isValidSynthesizedIndex`: finite integer in `[0, 255]`.
+fn valid_synth_index(index: Option<f64>) -> Option<usize> {
+    let v = index?;
+    if v.is_finite() && v.fract() == 0.0 && (0.0..=MAX_SYNTHESIZED_EVENT_INDEX as f64).contains(&v) {
+        Some(v as usize)
+    } else {
+        None
+    }
+}
+
+fn clone_content_array(content: Option<&Value>) -> Vec<Value> {
+    match content {
+        Some(Value::Array(items)) => items
+            .iter()
+            .filter(|item| is_record(item))
+            .cloned()
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+/// TS `mergeRecord` — JS spread semantics: base keys keep their positions,
+/// update values overwrite in place, new update keys append; `content` arrays
+/// prefer the update's content when non-empty (or when base lacks content),
+/// else the base's cloned content.
+fn merge_record(base: Option<&JsonMap>, update: &JsonMap) -> JsonMap {
+    let Some(base) = base else {
+        return update.clone();
+    };
+    let mut merged = base.clone();
+    for (key, value) in update {
+        merged.insert(key.clone(), value.clone());
+    }
+    if update.contains_key("content") || base.contains_key("content") {
+        let update_content = clone_content_array(update.get("content"));
+        let content = if !update_content.is_empty() || !base.contains_key("content") {
+            update_content
+        } else {
+            clone_content_array(base.get("content"))
+        };
+        merged.insert("content".to_string(), Value::Array(content));
+    }
+    merged
+}
+
+fn make_output_text_key(output_index: Option<f64>, content_index: Option<f64>) -> Option<String> {
+    let oi = valid_synth_index(output_index)?;
+    let ci = valid_synth_index(content_index)?;
+    Some(format!("{oi}:{ci}"))
+}
+
+fn make_phase_text_segment_key(phase: &str, output_text_key: &str) -> String {
+    format!("{phase}\u{0000}{output_text_key}")
+}
+
+fn make_summary_key(output_index: Option<f64>, summary_index: Option<f64>) -> Option<String> {
+    let oi = valid_synth_index(output_index)?;
+    let si = valid_synth_index(summary_index)?;
+    Some(format!("{oi}:{si}"))
+}
+
+fn get_part_text(part: Option<&Value>) -> Option<String> {
+    match part {
+        Some(Value::Object(map)) => get_string_field(map, "text"),
+        _ => None,
+    }
+}
+
+fn capture_phase(state: &mut ParsedResponseState, phase: Option<&Value>) {
+    if let Some(Value::String(s)) = phase {
+        let trimmed = s.trim();
+        if !trimmed.is_empty() {
+            state.last_phase = Some(trimmed.to_string());
+        }
+    }
+}
+
+fn remember_phase_segment_order(state: &mut ParsedResponseState, phase: &str, segment_key: &str) {
+    if let Some(existing) = state.phase_segment_order.get(&phase.to_string())
+        && existing.iter().any(|k| k == segment_key)
+    {
+        return;
+    }
+    let mut next = state
+        .phase_segment_order
+        .get(&phase.to_string())
+        .cloned()
+        .unwrap_or_default();
+    next.push(segment_key.to_string());
+    state.phase_segment_order.set(phase.to_string(), next);
+}
+
+fn remove_phase_segment_order(state: &mut ParsedResponseState, phase: &str, segment_key: &str) {
+    let Some(existing) = state.phase_segment_order.get(&phase.to_string()) else {
+        return;
+    };
+    let next: Vec<String> = existing.iter().filter(|k| *k != segment_key).cloned().collect();
+    if next.is_empty() {
+        state.phase_segment_order.remove(&phase.to_string());
+        return;
+    }
+    state.phase_segment_order.set(phase.to_string(), next);
+}
+
+fn rebuild_phase_text(state: &mut ParsedResponseState, phase: &str) {
+    let ordered_keys = state
+        .phase_segment_order
+        .get(&phase.to_string())
+        .cloned()
+        .unwrap_or_default();
+    let text: String = ordered_keys
+        .iter()
+        .filter_map(|key| state.phase_text_segments.get(key))
+        .filter(|value| !value.is_empty())
+        .cloned()
+        .collect::<Vec<_>>()
+        .join("");
+    if text.is_empty() {
+        state.phase_text.remove(&phase.to_string());
+        return;
+    }
+    state.phase_text.set(phase.to_string(), text);
+}
+
+fn normalize_phase_for_key(
+    state: &ParsedResponseState,
+    phase: Option<&Value>,
+    output_text_key: &str,
+) -> Option<String> {
+    match phase {
+        Some(Value::String(s)) if !s.trim().is_empty() => Some(s.trim().to_string()),
+        _ => state.output_text_phases.get(&output_text_key.to_string()).cloned(),
+    }
+}
+
+fn set_phase_text_segment(
+    state: &mut ParsedResponseState,
+    phase: Option<&Value>,
+    output_text_key: &str,
+    text: Option<&str>,
+) {
+    let Some(normalized_phase) = normalize_phase_for_key(state, phase, output_text_key) else {
+        return;
+    };
+    state
+        .output_text_phases
+        .set(output_text_key.to_string(), normalized_phase.clone());
+    state.last_phase = Some(normalized_phase.clone());
+    let segment_key = make_phase_text_segment_key(&normalized_phase, output_text_key);
+    match text {
+        None | Some("") => {
+            state.phase_text_segments.remove(&segment_key);
+            remove_phase_segment_order(state, &normalized_phase, &segment_key);
+            rebuild_phase_text(state, &normalized_phase);
+        }
+        Some(text) => {
+            remember_phase_segment_order(state, &normalized_phase, &segment_key);
+            state.phase_text_segments.set(segment_key, text.to_string());
+            rebuild_phase_text(state, &normalized_phase);
+        }
+    }
+}
+
+fn append_phase_text_segment(
+    state: &mut ParsedResponseState,
+    phase: Option<&Value>,
+    output_text_key: &str,
+    delta: Option<&str>,
+) {
+    let Some(delta) = delta else {
+        return;
+    };
+    if delta.is_empty() {
+        return;
+    }
+    let Some(normalized_phase) = normalize_phase_for_key(state, phase, output_text_key) else {
+        return;
+    };
+    state
+        .output_text_phases
+        .set(output_text_key.to_string(), normalized_phase.clone());
+    state.last_phase = Some(normalized_phase.clone());
+    let segment_key = make_phase_text_segment_key(&normalized_phase, output_text_key);
+    remember_phase_segment_order(state, &normalized_phase, &segment_key);
+    let existing = state.phase_text_segments.get(&segment_key).cloned().unwrap_or_default();
+    state
+        .phase_text_segments
+        .set(segment_key.clone(), format!("{existing}{delta}"));
+    let is_latest_segment = state
+        .phase_segment_order
+        .get(&normalized_phase)
+        .and_then(|order| order.last())
+        .is_some_and(|last| last == &segment_key);
+    if is_latest_segment {
+        let existing_phase_text = state
+            .phase_text
+            .get(&normalized_phase)
+            .cloned()
+            .unwrap_or_default();
+        state
+            .phase_text
+            .set(normalized_phase, format!("{existing_phase_text}{delta}"));
+        return;
+    }
+    rebuild_phase_text(state, &normalized_phase);
+}
+
+fn upsert_output_item(state: &mut ParsedResponseState, output_index: Option<f64>, item: Option<&Value>) {
+    let Some(index) = valid_synth_index(output_index) else {
+        return;
+    };
+    let Some(item_map) = to_mutable_record(item) else {
+        return;
+    };
+    let current = state.output_items.get(&index).cloned();
+    let merged = merge_record(current.as_ref(), &item_map);
+    let phase = merged.get("phase").cloned();
+    state.output_items.set(index, merged);
+    capture_phase(state, phase.as_ref());
+}
+
+fn set_output_text_value(
+    state: &mut ParsedResponseState,
+    output_index: Option<f64>,
+    content_index: Option<f64>,
+    text: Option<String>,
+    phase: Option<&Value>,
+) {
+    let Some(key) = make_output_text_key(output_index, content_index) else {
+        return;
+    };
+    match text {
+        None => {
+            state.output_text.remove(&key);
+            set_phase_text_segment(state, phase, &key, None);
+        }
+        Some(text) => {
+            state.output_text.set(key.clone(), text.clone());
+            set_phase_text_segment(state, phase, &key, Some(&text));
+        }
+    }
+}
+
+fn append_output_text_value(
+    state: &mut ParsedResponseState,
+    output_index: Option<f64>,
+    content_index: Option<f64>,
+    delta: Option<String>,
+    phase: Option<&Value>,
+) {
+    let Some(delta) = delta else {
+        return;
+    };
+    let Some(key) = make_output_text_key(output_index, content_index) else {
+        return;
+    };
+    let existing = state.output_text.get(&key).cloned().unwrap_or_default();
+    state.output_text.set(key.clone(), format!("{existing}{delta}"));
+    append_phase_text_segment(state, phase, &key, Some(&delta));
+}
+
+fn set_reasoning_summary_value(
+    state: &mut ParsedResponseState,
+    output_index: Option<f64>,
+    summary_index: Option<f64>,
+    text: Option<String>,
+) {
+    let Some(key) = make_summary_key(output_index, summary_index) else {
+        return;
+    };
+    match text {
+        None => state.reasoning_summary_text.remove(&key),
+        Some(text) => state.reasoning_summary_text.set(key, text),
+    }
+}
+
+fn append_reasoning_summary_value(
+    state: &mut ParsedResponseState,
+    output_index: Option<f64>,
+    summary_index: Option<f64>,
+    delta: Option<String>,
+) {
+    let Some(delta) = delta else {
+        return;
+    };
+    let Some(key) = make_summary_key(output_index, summary_index) else {
+        return;
+    };
+    let existing = state.reasoning_summary_text.get(&key).cloned().unwrap_or_default();
+    state.reasoning_summary_text.set(key, format!("{existing}{delta}"));
+}
+
+// ---------------------------------------------------------------------------
+// Finalization
+// ---------------------------------------------------------------------------
+
+fn ensure_output_item_at_index(output: &mut Vec<Value>, index: usize) -> bool {
+    if index > MAX_SYNTHESIZED_EVENT_INDEX {
+        return false;
+    }
+    while output.len() <= index {
+        output.push(Value::Object(JsonMap::new()));
+    }
+    if !output[index].is_object() {
+        output[index] = Value::Object(JsonMap::new());
+    }
+    true
+}
+
+/// Pad/normalize `item.content` so `content[index]` is a record; returns
+/// whether the slot is usable. The caller re-borrows the part afterwards.
+fn ensure_content_part_at_index(item: &mut JsonMap, index: usize) -> bool {
+    if index > MAX_SYNTHESIZED_EVENT_INDEX {
+        return false;
+    }
+    let mut content: Vec<Value> = match item.get("content") {
+        Some(Value::Array(items)) => items.clone(),
+        _ => Vec::new(),
+    };
+    while content.len() <= index {
+        content.push(Value::Object(JsonMap::new()));
+    }
+    if !content[index].is_object() {
+        content[index] = Value::Object(JsonMap::new());
+    }
+    item.insert("content".to_string(), Value::Array(content));
+    true
+}
+
+fn apply_accumulated_output_text(response: &mut JsonMap, state: &mut ParsedResponseState) {
+    if state.output_text.is_empty() {
+        return;
+    }
+    let mut output: Vec<Value> = match response.get("output") {
+        Some(Value::Array(items)) => items.clone(),
+        _ => Vec::new(),
+    };
+
+    let entries: Vec<(String, String)> = state
+        .output_text
+        .iter()
+        .map(|(k, v)| (k.clone(), v.clone()))
+        .collect();
+    for (key, text) in entries {
+        let mut parts = key.split(':');
+        let output_index = parts.next().and_then(|s| s.parse::<f64>().ok());
+        let content_index = parts.next().and_then(|s| s.parse::<f64>().ok());
+        let (Some(output_index), Some(content_index)) =
+            (valid_synth_index(output_index), valid_synth_index(content_index))
+        else {
+            continue;
+        };
+        if !ensure_output_item_at_index(&mut output, output_index) {
+            continue;
+        }
+        // Re-borrow the item map, prepare the content slot, then decide.
+        let usable = {
+            let Some(item) = output[output_index].as_object_mut() else {
+                continue;
+            };
+            ensure_content_part_at_index(item, content_index)
+        };
+        if !usable {
+            continue;
+        }
+        // Read out what we need from the part before mutating state.
+        let (has_string_text, existing_text, part_phase, needs_type) = {
+            let item = output[output_index].as_object_mut().expect("ensured object");
+            let part = item
+                .get_mut("content")
+                .and_then(Value::as_array_mut)
+                .and_then(|c| c.get_mut(content_index))
+                .and_then(Value::as_object_mut)
+                .expect("ensured content part");
+            let needs_type = get_string_field(part, "type").is_none();
+            match part.get("text") {
+                Some(Value::String(s)) => (true, Some(s.clone()), part.get("phase").cloned(), needs_type),
+                _ => (false, None, None, needs_type),
+            }
+        };
+        {
+            let item = output[output_index].as_object_mut().expect("ensured object");
+            let part = item
+                .get_mut("content")
+                .and_then(Value::as_array_mut)
+                .and_then(|c| c.get_mut(content_index))
+                .and_then(Value::as_object_mut)
+                .expect("ensured content part");
+            if needs_type {
+                part.insert("type".to_string(), Value::String("output_text".to_string()));
+            }
+            if !has_string_text {
+                part.insert("text".to_string(), Value::String(text.clone()));
+            }
+        }
+        if has_string_text {
+            // Existing terminal text wins; re-register it as the phase segment.
+            set_phase_text_segment(state, part_phase.as_ref(), &key, existing_text.as_deref());
+            continue;
+        }
+    }
+
+    if !output.is_empty() {
+        response.insert("output".to_string(), Value::Array(output));
+    }
+}
+
+fn merge_output_items_into_response(response: &mut JsonMap, state: &ParsedResponseState) {
+    if state.output_items.is_empty() {
+        return;
+    }
+    let mut output: Vec<Value> = match response.get("output") {
+        Some(Value::Array(items)) => items.clone(),
+        _ => Vec::new(),
+    };
+
+    for (output_index, item) in state.output_items.iter() {
+        if *output_index > MAX_SYNTHESIZED_EVENT_INDEX {
+            continue;
+        }
+        while output.len() <= *output_index {
+            output.push(Value::Object(JsonMap::new()));
+        }
+        let base = match &output[*output_index] {
+            Value::Object(map) => Some(map.clone()),
+            _ => None,
+        };
+        output[*output_index] = Value::Object(merge_record(base.as_ref(), item));
+    }
+
+    response.insert("output".to_string(), Value::Array(output));
+}
+
+fn collect_message_output_text(output: &[Value]) -> String {
+    output
+        .iter()
+        .filter_map(Value::as_object)
+        .map(|item| {
+            if item.get("type").and_then(Value::as_str) != Some("message") {
+                return String::new();
+            }
+            let content = match item.get("content") {
+                Some(Value::Array(items)) => items.as_slice(),
+                _ => &[],
+            };
+            content
+                .iter()
+                .filter_map(Value::as_object)
+                .map(|part| {
+                    if part.get("type").and_then(Value::as_str) != Some("output_text") {
+                        return String::new();
+                    }
+                    match part.get("text") {
+                        Some(Value::String(s)) => s.clone(),
+                        _ => String::new(),
+                    }
+                })
+                .collect::<Vec<_>>()
+                .join("")
+        })
+        .filter(|text| !text.is_empty())
+        .collect::<Vec<_>>()
+        .join("")
+}
+
+fn collect_reasoning_summary_text(output: &[Value]) -> String {
+    output
+        .iter()
+        .filter_map(Value::as_object)
+        .map(|item| {
+            if item.get("type").and_then(Value::as_str) != Some("reasoning") {
+                return String::new();
+            }
+            let summary = match item.get("summary") {
+                Some(Value::Array(items)) => items.as_slice(),
+                _ => &[],
+            };
+            summary
+                .iter()
+                .filter_map(Value::as_object)
+                .map(|part| match part.get("text") {
+                    Some(Value::String(s)) => s.clone(),
+                    _ => String::new(),
+                })
+                .filter(|text| !text.is_empty())
+                .collect::<Vec<_>>()
+                .join("\n\n")
+        })
+        .filter(|text| !text.is_empty())
+        .collect::<Vec<_>>()
+        .join("\n\n")
+}
+
+fn apply_reasoning_summaries(response: &mut JsonMap, state: &ParsedResponseState) {
+    if state.reasoning_summary_text.is_empty() {
+        return;
+    }
+    let mut output: Vec<Value> = match response.get("output") {
+        Some(Value::Array(items)) => items.clone(),
+        _ => Vec::new(),
+    };
+
+    for (key, text) in state.reasoning_summary_text.iter() {
+        let mut parts = key.split(':');
+        let output_index = parts.next().and_then(|s| s.parse::<f64>().ok());
+        let summary_index = parts.next().and_then(|s| s.parse::<f64>().ok());
+        let (Some(output_index), Some(summary_index)) =
+            (valid_synth_index(output_index), valid_synth_index(summary_index))
+        else {
+            continue;
+        };
+        if !ensure_output_item_at_index(&mut output, output_index) {
+            continue;
+        }
+        let Some(item) = output[output_index].as_object_mut() else {
+            continue;
+        };
+        let mut summary: Vec<Value> = match item.get("summary") {
+            Some(Value::Array(items)) => items.clone(),
+            _ => Vec::new(),
+        };
+        while summary.len() <= summary_index {
+            summary.push(Value::Object(JsonMap::new()));
+        }
+        let mut next_part: JsonMap = match &summary[summary_index] {
+            Value::Object(map) => map.clone(),
+            _ => JsonMap::new(),
+        };
+        if get_string_field(&next_part, "type").is_none() {
+            next_part.insert("type".to_string(), Value::String("summary_text".to_string()));
+        }
+        if matches!(next_part.get("text"), Some(Value::String(_))) {
+            // Existing terminal text wins; the local pads/type-default are
+            // deliberately discarded (TS `continue` before assignment).
+            continue;
+        }
+        next_part.insert("text".to_string(), Value::String(text.clone()));
+        summary[summary_index] = Value::Object(next_part);
+        item.insert("summary".to_string(), Value::Array(summary));
+        if get_string_field(item, "type").is_none() {
+            item.insert("type".to_string(), Value::String("reasoning".to_string()));
+        }
+    }
+
+    if !output.is_empty() {
+        response.insert("output".to_string(), Value::Array(output));
+    }
+}
+
+fn finalize_parsed_response(state: &mut ParsedResponseState) -> Option<JsonMap> {
+    let mut response = state.final_response.clone()?;
+    if state.encountered_error {
+        return None;
+    }
+
+    merge_output_items_into_response(&mut response, state);
+    apply_accumulated_output_text(&mut response, state);
+    apply_reasoning_summaries(&mut response, state);
+
+    let output: Vec<Value> = match response.get("output") {
+        Some(Value::Array(items)) => items.clone(),
+        _ => Vec::new(),
+    };
+    if !matches!(response.get("output_text"), Some(Value::String(_))) {
+        let output_text = collect_message_output_text(&output);
+        if !output_text.is_empty() {
+            response.insert("output_text".to_string(), Value::String(output_text));
+        }
+    }
+
+    let reasoning_summary_text = collect_reasoning_summary_text(&output);
+    if !reasoning_summary_text.is_empty()
+        && !matches!(response.get("reasoning_summary_text"), Some(Value::String(_)))
+    {
+        response.insert(
+            "reasoning_summary_text".to_string(),
+            Value::String(reasoning_summary_text),
+        );
+    }
+
+    if let Some(last_phase) = &state.last_phase
+        && !matches!(response.get("phase"), Some(Value::String(_)))
+    {
+        response.insert("phase".to_string(), Value::String(last_phase.clone()));
+    }
+
+    if !state.phase_text.is_empty() {
+        let mut phase_text = JsonMap::new();
+        for (phase, text) in state.phase_text.iter() {
+            phase_text.insert(phase.clone(), Value::String(text.clone()));
+            if phase == "commentary" {
+                response.insert("commentary_text".to_string(), Value::String(text.clone()));
+            }
+            if phase == "final_answer" {
+                response.insert("final_answer_text".to_string(), Value::String(text.clone()));
+            }
+        }
+        response.insert("phase_text".to_string(), Value::Object(phase_text));
+    }
+
+    Some(response)
+}
+
+// ---------------------------------------------------------------------------
+// Response-id capture
+// ---------------------------------------------------------------------------
+
+fn extract_response_id(response: Option<&Value>) -> Option<String> {
+    let map = response?.as_object()?;
+    match map.get("id") {
+        Some(Value::String(s)) if !s.trim().is_empty() => Some(s.trim().to_string()),
+        _ => None,
+    }
+}
+
+fn notify_response_id(
+    state: &mut ParsedResponseState,
+    on_response_id: Option<&ResponseIdCallback>,
+    response: Option<&Value>,
+) {
+    let Some(response_id) = extract_response_id(response) else {
+        return;
+    };
+    let Some(on_response_id) = on_response_id else {
+        return;
+    };
+    if state.seen_response_ids.contains(&response_id) {
+        return;
+    }
+    state.seen_response_ids.insert(response_id.clone());
+    on_response_id(&response_id);
+}
+
+fn truncate_diagnostic_text(value: Option<&Value>, max_length: usize) -> Option<String> {
+    let Some(Value::String(s)) = value else {
+        return None;
+    };
+    let trimmed = s.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    if trimmed.chars().count() > max_length {
+        let cut: String = trimmed.chars().take(max_length).collect();
+        Some(format!("{cut}..."))
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn log_stream_diagnostics(final_response: &JsonMap) {
+    if !logging_enabled() {
+        return;
+    }
+    let response_id = extract_response_id(Some(&Value::Object(final_response.clone())));
+    let phase = get_string_field(final_response, "phase");
+    let commentary_text = truncate_diagnostic_text(final_response.get("commentary_text"), 400);
+    let final_answer_text = truncate_diagnostic_text(final_response.get("final_answer_text"), 400);
+    let reasoning_summary_text =
+        truncate_diagnostic_text(final_response.get("reasoning_summary_text"), 400);
+    if phase.is_some()
+        || commentary_text.is_some()
+        || final_answer_text.is_some()
+        || reasoning_summary_text.is_some()
+    {
+        let mut data = JsonMap::new();
+        if let Some(v) = response_id {
+            data.insert("responseId".to_string(), Value::String(v));
+        }
+        if let Some(v) = phase {
+            data.insert("phase".to_string(), Value::String(v));
+        }
+        if let Some(v) = commentary_text {
+            data.insert("commentaryText".to_string(), Value::String(v));
+        }
+        if let Some(v) = final_answer_text {
+            data.insert("finalAnswerText".to_string(), Value::String(v));
+        }
+        if let Some(v) = reasoning_summary_text {
+            data.insert("reasoningSummaryText".to_string(), Value::String(v));
+        }
+        log_request("stream-diagnostics", &data);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Event state machine
+// ---------------------------------------------------------------------------
+
+fn maybe_capture_response_event(
+    state: &mut ParsedResponseState,
+    data: &Value,
+    on_response_id: Option<&ResponseIdCallback>,
+) {
+    let event_type = data.get("type").and_then(Value::as_str).unwrap_or("");
+
+    if event_type == "error" {
+        log().error("SSE error event received", Some(&serde_json::json!({ "error": data })));
+        state.encountered_error = true;
+        return;
+    }
+
+    // response.failed is a genuine terminal failure: the turn did not produce
+    // a usable result even though HTTP opened 200 (stress audit H7).
+    if event_type == "response.failed" {
+        log().warn(
+            "SSE terminal failure event received",
+            Some(&serde_json::json!({ "type": event_type })),
+        );
+        state.encountered_error = true;
+        return;
+    }
+
+    // response.completed / response.done / response.incomplete are all
+    // terminal SUCCESS envelopes. response.incomplete (max_output_tokens /
+    // content filter) is a NORMAL early stop whose partial output is the
+    // answer (re-audit correction to H7).
+    if event_type == "response.done"
+        || event_type == "response.completed"
+        || event_type == "response.incomplete"
+    {
+        if let Some(Value::Object(response)) = data.get("response") {
+            state.final_response = Some(response.clone());
+        }
+        notify_response_id(state, on_response_id, data.get("response"));
+        return;
+    }
+
+    let Some(event_record) = data.as_object() else {
+        return;
+    };
+    let output_index = get_number_field(event_record, "output_index");
+
+    if event_type == "response.output_item.added" || event_type == "response.output_item.done" {
+        upsert_output_item(state, output_index, event_record.get("item"));
+        return;
+    }
+
+    if event_type == "response.output_text.delta" {
+        append_output_text_value(
+            state,
+            output_index,
+            get_number_field(event_record, "content_index"),
+            get_delta_field(event_record, "delta"),
+            event_record.get("phase"),
+        );
+        return;
+    }
+
+    if event_type == "response.output_text.done" {
+        set_output_text_value(
+            state,
+            output_index,
+            get_number_field(event_record, "content_index"),
+            get_string_field(event_record, "text"),
+            event_record.get("phase"),
+        );
+        return;
+    }
+
+    if event_type == "response.content_part.added" || event_type == "response.content_part.done" {
+        let part = to_mutable_record(event_record.get("part"));
+        match part {
+            Some(part) if get_string_field(&part, "type").as_deref() == Some("output_text") => {
+                let text = get_part_text(Some(&Value::Object(part.clone())));
+                let phase = part.get("phase").cloned();
+                set_output_text_value(
+                    state,
+                    output_index,
+                    get_number_field(event_record, "content_index"),
+                    text,
+                    phase.as_ref(),
+                );
+            }
+            Some(part) => {
+                let phase = part.get("phase").cloned();
+                capture_phase(state, phase.as_ref());
+            }
+            None => {
+                capture_phase(state, None);
+            }
+        }
+        return;
+    }
+
+    if event_type == "response.reasoning_summary_text.delta" {
+        append_reasoning_summary_value(
+            state,
+            output_index,
+            get_number_field(event_record, "summary_index"),
+            get_delta_field(event_record, "delta"),
+        );
+        return;
+    }
+
+    if event_type == "response.reasoning_summary_text.done" {
+        set_reasoning_summary_value(
+            state,
+            output_index,
+            get_number_field(event_record, "summary_index"),
+            get_string_field(event_record, "text"),
+        );
+        return;
+    }
+
+    if event_type == "response.reasoning_summary_part.added"
+        || event_type == "response.reasoning_summary_part.done"
+    {
+        set_reasoning_summary_value(
+            state,
+            output_index,
+            get_number_field(event_record, "summary_index"),
+            get_part_text(event_record.get("part")),
+        );
+        return;
+    }
+
+    capture_phase(state, event_record.get("phase"));
+}
+
+// ---------------------------------------------------------------------------
+// SSE line parsing
+// ---------------------------------------------------------------------------
+
+/// Parse a complete SSE stream text, extracting the final response.
+/// Returns `(final_response, encountered_error)`.
+fn parse_sse_stream(
+    sse_text: &str,
+    on_response_id: Option<&ResponseIdCallback>,
+) -> (Option<JsonMap>, bool) {
+    let mut state = create_parsed_response_state();
+
+    let mut malformed_chunk_count: u64 = 0;
+    let mut first_malformed_sample: Option<String> = None;
+    for line in sse_text.split('\n') {
+        let trimmed_line = line.trim();
+        // Accept "data:" with or without the optional trailing space. The SSE
+        // spec allows "data:value"; requiring the space silently dropped every
+        // event on an upstream/proxy formatting change (stress audit M1).
+        if let Some(rest) = trimmed_line.strip_prefix("data:") {
+            let payload = rest.trim();
+            if payload.is_empty() || payload == "[DONE]" {
+                continue;
+            }
+            let mut malformed_reason: Option<String> = None;
+            match serde_json::from_str::<Value>(payload) {
+                // JSON `null` payload: TS throws `TypeError` on `data.type`
+                // inside the same try block, so it counts as malformed.
+                Ok(Value::Null) => {
+                    malformed_reason =
+                        Some("Cannot read properties of null (reading 'type')".to_string());
+                }
+                Ok(data) => {
+                    maybe_capture_response_event(&mut state, &data, on_response_id);
+                    if state.encountered_error {
+                        return (None, true);
+                    }
+                }
+                Err(error) => {
+                    malformed_reason = Some(error.to_string());
+                }
+            }
+            if let Some(reason) = malformed_reason {
+                // AUDIT-H9 / H-03: surface a structured warn with bounded
+                // context (first 120 chars + error message) and a running
+                // tally instead of silently discarding.
+                malformed_chunk_count += 1;
+                if first_malformed_sample.is_none() {
+                    first_malformed_sample = Some(payload.chars().take(120).collect());
+                }
+                if malformed_chunk_count == 1 {
+                    log().warn(
+                        "SSE malformed JSON chunk discarded",
+                        Some(&serde_json::json!({
+                            "reason": reason,
+                            "sample": first_malformed_sample,
+                        })),
+                    );
+                }
+            }
+        }
+    }
+
+    if malformed_chunk_count > 1 {
+        log().warn(
+            "SSE malformed JSON chunks discarded (rollup)",
+            Some(&serde_json::json!({
+                "totalCount": malformed_chunk_count,
+                "firstSample": first_malformed_sample,
+            })),
+        );
+    }
+
+    let encountered_error = state.encountered_error;
+    (finalize_parsed_response(&mut state), encountered_error)
+}
+
+// ---------------------------------------------------------------------------
+// convertSseToJson
+// ---------------------------------------------------------------------------
+
+/// Options for [`convert_sse_to_json`].
+#[derive(Clone, Default)]
+pub struct ConvertSseOptions {
+    pub on_response_id: Option<ResponseIdCallback>,
+    pub stream_stall_timeout_ms: Option<f64>,
+}
+
+impl std::fmt::Debug for ConvertSseOptions {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ConvertSseOptions")
+            .field("on_response_id", &self.on_response_id.as_ref().map(|_| "<callback>"))
+            .field("stream_stall_timeout_ms", &self.stream_stall_timeout_ms)
+            .finish()
+    }
+}
+
+/// Convert an SSE stream response to a JSON response for non-streaming
+/// callers (TS `convertSseToJson`).
+///
+/// - No body ⇒ `Err("[codex-multi-auth] Response has no body")`.
+/// - Terminal failure event ⇒ synthetic non-2xx (`sse_terminal_error`).
+/// - No terminal event, no error ⇒ the raw SSE text at the ORIGINAL status
+///   (preserves the caller's empty-response retry path).
+/// - Success ⇒ compact JSON of the reconstructed final response at the
+///   original status with `content-type: application/json; charset=utf-8`.
+pub async fn convert_sse_to_json(
+    mut response: StreamResponse,
+    headers: &HeaderMap,
+    options: ConvertSseOptions,
+) -> Result<StreamResponse, BoxError> {
+    let Some(mut body) = response.body.take() else {
+        return Err(format!("[{PLUGIN_NAME}] Response has no body").into());
+    };
+
+    let stream_stall_timeout_ms = options
+        .stream_stall_timeout_ms
+        .unwrap_or(DEFAULT_STREAM_STALL_TIMEOUT_MS)
+        .floor()
+        .max(1_000.0) as u64;
+
+    // REQ-HIGH-03: accumulate decoded chunks in a Vec (O(n) total), with the
+    // size check BEFORE appending so peak memory is bounded to the cap.
+    let result: Result<StreamResponse, BoxError> = async {
+        let mut decoder = Utf8StreamDecoder::default();
+        let mut chunks: Vec<String> = Vec::new();
+        let mut total_size: usize = 0;
+
+        loop {
+            let read = tokio::time::timeout(
+                std::time::Duration::from_millis(stream_stall_timeout_ms),
+                body.next(),
+            )
+            .await;
+            let item = match read {
+                Ok(item) => item,
+                Err(_) => {
+                    return Err(format!(
+                        "SSE stream stalled for {stream_stall_timeout_ms}ms while waiting for a terminal response event"
+                    )
+                    .into());
+                }
+            };
+            match item {
+                None => break,
+                Some(Err(error)) => return Err(error),
+                Some(Ok(chunk)) => {
+                    let decoded = decoder.decode_stream(&chunk);
+                    let decoded_bytes = decoded.len();
+                    // Pre-append size check: reject before retaining the chunk
+                    // alongside the accumulated buffer.
+                    if total_size + decoded_bytes > MAX_SSE_SIZE {
+                        return Err(format!("SSE response exceeds {MAX_SSE_SIZE} bytes limit").into());
+                    }
+                    chunks.push(decoded);
+                    total_size += decoded_bytes;
+                }
+            }
+        }
+
+        let full_text = chunks.concat();
+
+        if logging_enabled() {
+            let mut data = JsonMap::new();
+            data.insert("fullContent".to_string(), Value::String(full_text.clone()));
+            log_request("stream-full", &data);
+        }
+
+        let (final_response, encountered_error) =
+            parse_sse_stream(&full_text, options.on_response_id.as_ref());
+
+        // A terminal failure event means the upstream turn failed even though
+        // HTTP opened 200. Returning the raw SSE at 200 here would make the
+        // proxy record an account success and skip rotation/retry (H6+H7).
+        if encountered_error {
+            log().warn("SSE stream ended with a terminal failure event", None);
+            let mut data = JsonMap::new();
+            data.insert(
+                "error".to_string(),
+                Value::String(
+                    "SSE stream terminated with an error/failed/incomplete event".to_string(),
+                ),
+            );
+            log_request("stream-error", &data);
+            let upstream_failed = response.status >= 400;
+            let status = if upstream_failed { response.status } else { HTTP_STATUS.bad_gateway };
+            let status_text = if upstream_failed {
+                response.status_text.clone()
+            } else {
+                "Bad Gateway".to_string()
+            };
+            let mut error_headers = headers.clone();
+            error_headers.insert(
+                CONTENT_TYPE,
+                HeaderValue::from_static("application/json; charset=utf-8"),
+            );
+            let payload = serde_json::json!({
+                "error": {
+                    "message": "Upstream SSE stream terminated with a failure event",
+                    "type": "upstream_stream_error",
+                    "code": "sse_terminal_error"
+                }
+            });
+            return Ok(StreamResponse::from_text(
+                status,
+                status_text,
+                error_headers,
+                stringify_compact(&payload),
+            ));
+        }
+
+        let Some(final_response) = final_response else {
+            log().warn("Could not find final response in SSE stream", None);
+            let mut data = JsonMap::new();
+            data.insert(
+                "error".to_string(),
+                Value::String("No terminal response event found in SSE stream".to_string()),
+            );
+            log_request("stream-error", &data);
+            // Return original stream if we can't parse (no error event, just
+            // no terminal response). Preserves the empty-response retry path.
+            return Ok(StreamResponse::from_text(
+                response.status,
+                response.status_text.clone(),
+                headers.clone(),
+                full_text,
+            ));
+        };
+
+        log_stream_diagnostics(&final_response);
+
+        let mut json_headers = headers.clone();
+        json_headers.insert(
+            CONTENT_TYPE,
+            HeaderValue::from_static("application/json; charset=utf-8"),
+        );
+
+        Ok(StreamResponse::from_text(
+            response.status,
+            response.status_text.clone(),
+            json_headers,
+            stringify_compact(&Value::Object(final_response)),
+        ))
+    }
+    .await;
+
+    if let Err(error) = &result {
+        log().error(
+            "Error converting stream",
+            Some(&serde_json::json!({ "error": error.to_string() })),
+        );
+        let mut data = JsonMap::new();
+        data.insert("error".to_string(), Value::String(error.to_string()));
+        log_request("stream-error", &data);
+        // Reader cancel + lock release: dropping the stream is the analogue.
+        drop(body);
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// ensureContentType / isEmptyResponse / attachResponseIdCapture
+// ---------------------------------------------------------------------------
+
+/// Copy the headers, setting `content-type: text/event-stream; charset=utf-8`
+/// only when absent (TS `ensureContentType`). Never mutates the input.
+pub fn ensure_content_type(headers: &HeaderMap) -> HeaderMap {
+    let mut response_headers = headers.clone();
+    if !response_headers.contains_key(CONTENT_TYPE) {
+        response_headers.insert(
+            CONTENT_TYPE,
+            HeaderValue::from_static("text/event-stream; charset=utf-8"),
+        );
+    }
+    response_headers
+}
+
+/// Check whether a parsed (non-streaming) response body is empty/malformed
+/// (TS `isEmptyResponse`). `None` models JS `undefined`.
+///
+/// Objects are only treated as potentially-empty when they carry
+/// `id`/`object`/`model`; a bare `{"foo":1}` object is NOT empty.
+pub fn is_empty_response(body: Option<&Value>) -> bool {
+    let Some(body) = body else {
+        return true;
+    };
+    match body {
+        Value::Null => true,
+        Value::String(s) => s.trim().is_empty(),
+        Value::Bool(_) | Value::Number(_) => false,
+        // JS `typeof [] === "object"`: empty array has zero keys ⇒ empty;
+        // a non-empty array has index keys and no id/object/model ⇒ not empty.
+        Value::Array(items) => items.is_empty(),
+        Value::Object(obj) => {
+            if obj.is_empty() {
+                return true;
+            }
+
+            let has_output = match obj.get("output") {
+                None | Some(Value::Null) => false,
+                Some(Value::Array(items)) => items.iter().any(|o| match o {
+                    Value::Null => false,
+                    Value::Object(map) => !map.is_empty(),
+                    Value::Array(arr) => !arr.is_empty(),
+                    _ => true,
+                }),
+                Some(Value::String(s)) => !s.trim().is_empty(),
+                Some(_) => true,
+            };
+            let has_choices = match obj.get("choices") {
+                Some(Value::Array(items)) => items.iter().any(|c| match c {
+                    Value::Object(map) => !map.is_empty(),
+                    Value::Array(arr) => !arr.is_empty(),
+                    _ => false,
+                }),
+                _ => false,
+            };
+            let has_content = match obj.get("content") {
+                None | Some(Value::Null) => false,
+                Some(Value::String(s)) => !s.trim().is_empty(),
+                Some(_) => true,
+            };
+
+            if obj.contains_key("id") || obj.contains_key("object") || obj.contains_key("model") {
+                return !has_output && !has_choices && !has_content;
+            }
+
+            false
+        }
+    }
+}
+
+struct CaptureStreamState {
+    inner: BodyStream,
+    decoder: Utf8StreamDecoder,
+    buffered_text: String,
+    logged_malformed_stream_chunk: bool,
+    parse_state: ParsedResponseState,
+    on_response_id: ResponseIdCallback,
+}
+
+impl CaptureStreamState {
+    fn process_buffered_lines(&mut self, flush: bool) {
+        if self.parse_state.encountered_error {
+            return;
+        }
+        let buffered = std::mem::take(&mut self.buffered_text);
+        let mut lines: Vec<&str> = buffered.split('\n').collect();
+        if !flush {
+            self.buffered_text = lines.pop().unwrap_or("").to_string();
+        }
+
+        for raw_line in lines {
+            let trimmed_line = raw_line.trim();
+            let Some(rest) = trimmed_line.strip_prefix("data:") else {
+                continue;
+            };
+            let payload = rest.trim();
+            if payload.is_empty() || payload == "[DONE]" {
+                continue;
+            }
+            let mut malformed_reason: Option<String> = None;
+            match serde_json::from_str::<Value>(payload) {
+                Ok(Value::Null) => {
+                    malformed_reason =
+                        Some("Cannot read properties of null (reading 'type')".to_string());
+                }
+                Ok(data) => {
+                    maybe_capture_response_event(
+                        &mut self.parse_state,
+                        &data,
+                        Some(&self.on_response_id),
+                    );
+                    if self.parse_state.encountered_error {
+                        break;
+                    }
+                }
+                Err(error) => {
+                    malformed_reason = Some(error.to_string());
+                }
+            }
+            if let Some(reason) = malformed_reason {
+                // AUDIT-H9 / H-03: raw bytes still reach the downstream
+                // consumer; warn ONCE with bounded context.
+                if !self.logged_malformed_stream_chunk {
+                    self.logged_malformed_stream_chunk = true;
+                    let sample: String = payload.chars().take(120).collect();
+                    log().warn(
+                        "SSE malformed JSON chunk in stream passthrough",
+                        Some(&serde_json::json!({ "reason": reason, "sample": sample })),
+                    );
+                }
+            }
+        }
+    }
+}
+
+fn create_response_id_capturing_stream(
+    body: BodyStream,
+    on_response_id: ResponseIdCallback,
+) -> BodyStream {
+    let state = CaptureStreamState {
+        inner: body,
+        decoder: Utf8StreamDecoder::default(),
+        buffered_text: String::new(),
+        logged_malformed_stream_chunk: false,
+        parse_state: create_parsed_response_state(),
+        on_response_id,
+    };
+    futures::stream::unfold(state, |mut st| async move {
+        match st.inner.next().await {
+            Some(Ok(chunk)) => {
+                let decoded = st.decoder.decode_stream(&chunk);
+                st.buffered_text.push_str(&decoded);
+                st.process_buffered_lines(false);
+                // Re-enqueue the chunk unmodified: bytes always flow through.
+                Some((Ok(chunk), st))
+            }
+            Some(Err(error)) => Some((Err(error), st)),
+            None => {
+                let flushed = st.decoder.flush();
+                st.buffered_text.push_str(&flushed);
+                st.process_buffered_lines(true);
+                None
+            }
+        }
+    })
+    .boxed()
+}
+
+/// Pipe the response body through a transform that sniffs SSE events for the
+/// final response id, re-emitting every byte unmodified
+/// (TS `attachResponseIdCapture`). Without a body or callback, the body is
+/// simply re-wrapped with the given headers.
+pub fn attach_response_id_capture(
+    mut response: StreamResponse,
+    headers: HeaderMap,
+    on_response_id: Option<ResponseIdCallback>,
+) -> StreamResponse {
+    let body = response.body.take();
+    match (body, on_response_id) {
+        (Some(body), Some(on_response_id)) => StreamResponse::new(
+            response.status,
+            response.status_text.clone(),
+            headers,
+            Some(create_response_id_capturing_stream(body, on_response_id)),
+        ),
+        (body, _) => StreamResponse::new(response.status, response.status_text.clone(), headers, body),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn utf8_decoder_carries_incomplete_sequences_across_chunks() {
+        let mut decoder = Utf8StreamDecoder::default();
+        let emoji = "😀".as_bytes(); // 4 bytes
+        let first = decoder.decode_stream(&emoji[..2]);
+        assert_eq!(first, "");
+        let second = decoder.decode_stream(&emoji[2..]);
+        assert_eq!(second, "😀");
+        assert_eq!(decoder.flush(), "");
+    }
+
+    #[test]
+    fn utf8_decoder_flush_replaces_incomplete_tail() {
+        let mut decoder = Utf8StreamDecoder::default();
+        let emoji = "😀".as_bytes();
+        assert_eq!(decoder.decode_stream(&emoji[..2]), "");
+        assert_eq!(decoder.flush(), "\u{FFFD}");
+    }
+
+    #[test]
+    fn utf8_decoder_ascii_passthrough_counts_bytes() {
+        let mut decoder = Utf8StreamDecoder::default();
+        let decoded = decoder.decode_stream(b"data: hello\n");
+        assert_eq!(decoded, "data: hello\n");
+        assert_eq!(decoded.len(), 12);
+    }
+
+    #[test]
+    fn ordered_map_preserves_insertion_order_on_update_and_delete() {
+        let mut map: OrderedMap<String, i32> = OrderedMap::new();
+        map.set("a".into(), 1);
+        map.set("b".into(), 2);
+        map.set("c".into(), 3);
+        map.set("a".into(), 10); // in-place update keeps position
+        map.remove(&"b".to_string());
+        let keys: Vec<&str> = map.iter().map(|(k, _)| k.as_str()).collect();
+        assert_eq!(keys, vec!["a", "c"]);
+        assert_eq!(map.get(&"a".to_string()), Some(&10));
+    }
+
+    #[test]
+    fn synthetic_terminal_error_body_is_byte_exact() {
+        let payload = serde_json::json!({
+            "error": {
+                "message": "Upstream SSE stream terminated with a failure event",
+                "type": "upstream_stream_error",
+                "code": "sse_terminal_error"
+            }
+        });
+        assert_eq!(
+            stringify_compact(&payload),
+            r#"{"error":{"message":"Upstream SSE stream terminated with a failure event","type":"upstream_stream_error","code":"sse_terminal_error"}}"#
+        );
+    }
+
+    #[test]
+    fn merge_record_prefers_nonempty_update_content() {
+        let base: JsonMap = serde_json::from_str(r#"{"id":"x","content":[{"type":"a"}]}"#).unwrap();
+        let update: JsonMap = serde_json::from_str(r#"{"content":[]}"#).unwrap();
+        // Update's empty content loses; base's cloned content wins.
+        let merged = merge_record(Some(&base), &update);
+        assert_eq!(
+            merged.get("content").unwrap(),
+            &serde_json::json!([{ "type": "a" }])
+        );
+        // Non-empty update content wins.
+        let update2: JsonMap = serde_json::from_str(r#"{"content":[{"type":"b"}]}"#).unwrap();
+        let merged2 = merge_record(Some(&base), &update2);
+        assert_eq!(
+            merged2.get("content").unwrap(),
+            &serde_json::json!([{ "type": "b" }])
+        );
+    }
+
+    #[test]
+    fn valid_synth_index_bounds() {
+        assert_eq!(valid_synth_index(Some(0.0)), Some(0));
+        assert_eq!(valid_synth_index(Some(255.0)), Some(255));
+        assert_eq!(valid_synth_index(Some(256.0)), None);
+        assert_eq!(valid_synth_index(Some(-1.0)), None);
+        assert_eq!(valid_synth_index(Some(1.5)), None);
+        assert_eq!(valid_synth_index(None), None);
+    }
+}
diff --git a/crates/request/src/response_metadata.rs b/crates/request/src/response_metadata.rs
new file mode 100644
index 000000000..240ae1768
--- /dev/null
+++ b/crates/request/src/response_metadata.rs
@@ -0,0 +1,274 @@
+//! Port of `lib/request/response-metadata.ts` — retry-hint parsing + log-safe
+//! header allowlist.
+//!
+//! Behavior source: spec 06 §19 + the TS source (authority).
+//!
+//! Note the deliberately TIGHTER clamp here: retry hints cap at 24 hours
+//! (`MAX_RETRY_HINT_MS`), versus the 7-day `MAX_RATE_LIMIT_DELAY_MS` used by
+//! `fetch_helpers`/`rate_limit_decision` (spec 06 gotcha 13).
+
+use cma_core::utils::now_ms;
+use http::header::HeaderMap;
+use serde_json::{Map, Value};
+
+/// TS private `MAX_RETRY_HINT_MS = 24 * 60 * 60 * 1000`.
+const MAX_RETRY_HINT_MS: i64 = 24 * 60 * 60 * 1000;
+
+/// TS private `clampRetryHintMs`: non-finite → None; floor; ≤ 0 → None;
+/// `min(value, 24h)`.
+fn clamp_retry_hint_ms(value: f64) -> Option<i64> {
+    if !value.is_finite() {
+        return None;
+    }
+    let normalized = value.floor();
+    if normalized <= 0.0 {
+        return None;
+    }
+    Some((normalized as i64).min(MAX_RETRY_HINT_MS))
+}
+
+fn header_str<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+    headers.get(name).and_then(|value| value.to_str().ok())
+}
+
+fn is_all_digits(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit())
+}
+
+/// JS `Number.parseInt(<all-digit string>, 10)` as f64 (huge inputs saturate
+/// through f64 exactly like JS numbers instead of failing an i64 parse).
+fn digits_to_f64(value: &str) -> f64 {
+    value.parse::<f64>().unwrap_or(f64::NAN)
+}
+
+/// JS `Date.parse` for the formats that reach this code path: RFC 2822 HTTP
+/// dates (`toUTCString()` output), RFC 3339/ISO 8601 date-times, and bare
+/// ISO dates (UTC midnight, matching the JS date-only rule).
+pub(crate) fn js_date_parse_ms(value: &str) -> Option<i64> {
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc2822(value) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(value) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(parsed) = chrono::NaiveDate::parse_from_str(value, "%Y-%m-%d") {
+        let midnight = parsed.and_hms_opt(0, 0, 0)?;
+        return Some(midnight.and_utc().timestamp_millis());
+    }
+    None
+}
+
+/// TS `parseRetryAfterHintMs(headers)`.
+///
+/// Precedence: `retry-after-ms` (all-digits, ms) → `retry-after` (all-digits
+/// seconds ×1000; otherwise HTTP date minus now) → `x-ratelimit-reset`
+/// (all-digits epoch with the `< 10_000_000_000 → seconds` heuristic, minus
+/// now). Every branch clamps to `[1, 24h]`; nothing matched → `None`.
+pub fn parse_retry_after_hint_ms(headers: &HeaderMap) -> Option<i64> {
+    parse_retry_after_hint_ms_at(headers, now_ms())
+}
+
+/// [`parse_retry_after_hint_ms`] against an explicit wall-clock instant (test
+/// seam for the TS fake-timer suites).
+pub fn parse_retry_after_hint_ms_at(headers: &HeaderMap, now_ms: i64) -> Option<i64> {
+    if let Some(retry_after_ms) = header_str(headers, "retry-after-ms").map(str::trim)
+        && is_all_digits(retry_after_ms) {
+            return clamp_retry_hint_ms(digits_to_f64(retry_after_ms));
+        }
+
+    if let Some(retry_after) = header_str(headers, "retry-after").map(str::trim) {
+        if is_all_digits(retry_after) {
+            return clamp_retry_hint_ms(digits_to_f64(retry_after) * 1000.0);
+        }
+        if !retry_after.is_empty()
+            && let Some(retry_at_ms) = js_date_parse_ms(retry_after) {
+                return clamp_retry_hint_ms((retry_at_ms - now_ms) as f64);
+            }
+    }
+
+    if let Some(reset_at) = header_str(headers, "x-ratelimit-reset").map(str::trim)
+        && is_all_digits(reset_at) {
+            let reset_raw = digits_to_f64(reset_at);
+            let reset_at_ms = if reset_raw < 10_000_000_000.0 {
+                reset_raw * 1000.0
+            } else {
+                reset_raw
+            };
+            return clamp_retry_hint_ms(reset_at_ms - now_ms as f64);
+        }
+
+    None
+}
+
+/// TS `sanitizeResponseHeadersForLog(headers)` — allowlist ONLY; everything
+/// else (especially auth headers) is dropped. Keys are lowercased; duplicate
+/// header values are joined with `", "` (the web `Headers` combine rule).
+pub fn sanitize_response_headers_for_log(headers: &HeaderMap) -> Map<String, Value> {
+    const ALLOWED: [&str; 16] = [
+        "content-type",
+        "x-request-id",
+        "x-openai-request-id",
+        "x-codex-plan-type",
+        "x-codex-active-limit",
+        "x-codex-primary-used-percent",
+        "x-codex-primary-window-minutes",
+        "x-codex-primary-reset-at",
+        "x-codex-primary-reset-after-seconds",
+        "x-codex-secondary-used-percent",
+        "x-codex-secondary-window-minutes",
+        "x-codex-secondary-reset-at",
+        "x-codex-secondary-reset-after-seconds",
+        "retry-after",
+        "x-ratelimit-reset",
+        "x-ratelimit-reset-requests",
+    ];
+
+    let mut sanitized = Map::new();
+    for name in headers.keys() {
+        let lower = name.as_str().to_lowercase();
+        if !ALLOWED.contains(&lower.as_str()) {
+            continue;
+        }
+        let combined = headers
+            .get_all(name)
+            .iter()
+            .map(|value| String::from_utf8_lossy(value.as_bytes()).into_owned())
+            .collect::<Vec<_>>()
+            .join(", ");
+        sanitized.insert(lower, Value::String(combined));
+    }
+    sanitized
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::header::{HeaderName, HeaderValue};
+
+    /// Fixed "now" matching the TS suite: 2026-03-22T00:00:00.000Z.
+    const NOW_MS: i64 = 1_774_137_600_000;
+
+    fn headers(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.append(
+                HeaderName::try_from(*name).unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn now_constant_matches_the_ts_fake_clock() {
+        let expected = chrono::DateTime::parse_from_rfc3339("2026-03-22T00:00:00.000Z")
+            .unwrap()
+            .timestamp_millis();
+        assert_eq!(NOW_MS, expected);
+    }
+
+    #[test]
+    fn parses_retry_after_ms_before_other_retry_headers() {
+        let headers = headers(&[("retry-after-ms", "1200"), ("retry-after", "30")]);
+        assert_eq!(parse_retry_after_hint_ms_at(&headers, NOW_MS), Some(1200));
+    }
+
+    #[test]
+    fn parses_retry_after_seconds_and_caps_extreme_values_to_one_day() {
+        let headers = headers(&[("retry-after", "999999")]);
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&headers, NOW_MS),
+            Some(86_400_000)
+        );
+    }
+
+    #[test]
+    fn parses_retry_after_dates_and_ratelimit_reset_timestamps() {
+        let date_headers = headers(&[("retry-after", "Sun, 22 Mar 2026 00:02:00 GMT")]);
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&date_headers, NOW_MS),
+            Some(120_000)
+        );
+
+        let reset_epoch_seconds = NOW_MS / 1000 + 45;
+        let reset_headers = headers(&[("x-ratelimit-reset", &reset_epoch_seconds.to_string())]);
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&reset_headers, NOW_MS),
+            Some(45_000)
+        );
+    }
+
+    #[test]
+    fn millisecond_epoch_reset_values_skip_the_seconds_multiplier() {
+        let reset_epoch_ms = NOW_MS + 30_000;
+        let reset_headers = headers(&[("x-ratelimit-reset", &reset_epoch_ms.to_string())]);
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&reset_headers, NOW_MS),
+            Some(30_000)
+        );
+    }
+
+    #[test]
+    fn returns_none_for_invalid_or_non_positive_retry_hints() {
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&headers(&[("retry-after-ms", "abc")]), NOW_MS),
+            None
+        );
+        let past = NOW_MS / 1000 - 5;
+        assert_eq!(
+            parse_retry_after_hint_ms_at(&headers(&[("x-ratelimit-reset", &past.to_string())]), NOW_MS),
+            None
+        );
+        // Zero values clamp to None WITHOUT falling through to later headers
+        // (the TS all-digits branches return unconditionally).
+        assert_eq!(
+            parse_retry_after_hint_ms_at(
+                &headers(&[
+                    ("retry-after-ms", "0"),
+                    ("retry-after", "Sun, 22 Mar 2026 00:02:00 GMT"),
+                ]),
+                NOW_MS
+            ),
+            None
+        );
+        assert_eq!(parse_retry_after_hint_ms_at(&HeaderMap::new(), NOW_MS), None);
+    }
+
+    #[test]
+    fn sanitizes_response_headers_down_to_the_allowed_logging_set() {
+        let headers = headers(&[
+            ("Content-Type", "application/json"),
+            ("X-Request-Id", "req_123"),
+            ("Authorization", "Bearer secret"),
+            ("Cookie", "session=secret"),
+            ("X-RateLimit-Reset", "12345"),
+        ]);
+
+        let sanitized = sanitize_response_headers_for_log(&headers);
+        assert_eq!(sanitized.len(), 3);
+        assert_eq!(
+            sanitized.get("content-type"),
+            Some(&Value::String("application/json".into()))
+        );
+        assert_eq!(
+            sanitized.get("x-request-id"),
+            Some(&Value::String("req_123".into()))
+        );
+        assert_eq!(
+            sanitized.get("x-ratelimit-reset"),
+            Some(&Value::String("12345".into()))
+        );
+        assert!(!sanitized.contains_key("authorization"));
+        assert!(!sanitized.contains_key("cookie"));
+    }
+
+    #[test]
+    fn joins_duplicate_allowed_headers_with_comma_space() {
+        let headers = headers(&[("retry-after", "1"), ("retry-after", "2")]);
+        let sanitized = sanitize_response_headers_for_log(&headers);
+        assert_eq!(
+            sanitized.get("retry-after"),
+            Some(&Value::String("1, 2".into()))
+        );
+    }
+}
diff --git a/crates/request/src/stream_failover.rs b/crates/request/src/stream_failover.rs
new file mode 100644
index 000000000..633ed701a
--- /dev/null
+++ b/crates/request/src/stream_failover.rs
@@ -0,0 +1,284 @@
+//! Port of `lib/request/stream-failover.ts` — client-visible stream failover
+//! wrapper (spec 06 §20).
+//!
+//! Wraps a streaming [`StreamResponse`] so the stream can switch to a fallback
+//! source when the primary stalls or errors — but ONLY before any bytes have
+//! been flushed to the consumer (`emitted_bytes > 0` refuses replay: reissuing
+//! the upstream request after partial output can duplicate streamed text and
+//! side-effectful tool activity). The overall failover cap is enforced
+//! elsewhere to 1 (`failover_config::cap_stream_failover_max`).
+//!
+//! Concurrency: the wrapper expects a single consumer of the returned body.
+//! The pump runs as a spawned task feeding a bounded channel, mirroring the
+//! TS `ReadableStream`/controller pattern; dropping the returned body cancels
+//! the pump and the current upstream stream (TS `cancel()`).
+
+use std::time::Duration;
+
+use bytes::Bytes;
+use futures::StreamExt;
+use tokio::sync::mpsc;
+
+use crate::response_handler::{BodyStream, BoxError, StreamResponse, ensure_content_type};
+
+pub const DEFAULT_MAX_FAILOVERS: f64 = 1.0;
+pub const DEFAULT_STALL_TIMEOUT_MS: f64 = 45_000.0;
+pub const DEFAULT_SOFT_TIMEOUT_MS: f64 = 15_000.0;
+pub const MAX_REQUEST_INSTANCE_ID_LENGTH: usize = 64;
+
+/// TS `StreamFailoverOptions`.
+#[derive(Debug, Clone, Default)]
+pub struct StreamFailoverOptions {
+    pub max_failovers: Option<f64>,
+    pub stall_timeout_ms: Option<f64>,
+    pub soft_timeout_ms: Option<f64>,
+    pub hard_timeout_ms: Option<f64>,
+    pub request_instance_id: Option<String>,
+}
+
+/// TS `StallTimeoutError` — message `"SSE stream stalled for {ms}ms"`.
+/// Detection is by downcast ([`is_stall_timeout_error`]); the TS structural
+/// `isStallTimeout` marker protocol has no Rust analogue (all producers are
+/// in-crate).
+#[derive(Debug)]
+pub struct StallTimeoutError {
+    pub timeout_ms: u64,
+}
+
+impl std::fmt::Display for StallTimeoutError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "SSE stream stalled for {}ms", self.timeout_ms)
+    }
+}
+
+impl std::error::Error for StallTimeoutError {}
+
+/// Whether an error is an SSE stall timeout.
+pub fn is_stall_timeout_error(error: &BoxError) -> bool {
+    error.downcast_ref::<StallTimeoutError>().is_some()
+}
+
+/// Trim + truncate a request instance id to 64 chars; empty ⇒ `None`.
+fn normalize_request_instance_id(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    if trimmed.chars().count() <= MAX_REQUEST_INSTANCE_ID_LENGTH {
+        return Some(trimmed.to_string());
+    }
+    Some(trimmed.chars().take(MAX_REQUEST_INSTANCE_ID_LENGTH).collect())
+}
+
+enum ReadOutcome {
+    Chunk(Bytes),
+    Done,
+}
+
+fn map_read_item(item: Option<Result<Bytes, BoxError>>) -> Result<ReadOutcome, BoxError> {
+    match item {
+        None => Ok(ReadOutcome::Done),
+        Some(Ok(bytes)) => Ok(ReadOutcome::Chunk(bytes)),
+        Some(Err(error)) => Err(error),
+    }
+}
+
+/// Read one chunk with a soft/hard stall window. A SINGLE logical read stays
+/// pending across both windows (the future is polled by reference — a chunk
+/// resolving during the second window is never dropped). A read ERROR during
+/// the soft window propagates immediately without opening the hard window.
+async fn read_chunk_with_soft_hard_timeout(
+    stream: &mut BodyStream,
+    soft_timeout_ms: u64,
+    hard_timeout_ms: u64,
+) -> Result<ReadOutcome, BoxError> {
+    let mut read_future = stream.next();
+    match tokio::time::timeout(Duration::from_millis(soft_timeout_ms), &mut read_future).await {
+        Ok(item) => map_read_item(item),
+        Err(_) => {
+            if hard_timeout_ms <= soft_timeout_ms {
+                return Err(Box::new(StallTimeoutError { timeout_ms: soft_timeout_ms }));
+            }
+            let remaining = hard_timeout_ms - soft_timeout_ms;
+            match tokio::time::timeout(Duration::from_millis(remaining), &mut read_future).await {
+                Ok(item) => map_read_item(item),
+                Err(_) => Err(Box::new(StallTimeoutError { timeout_ms: remaining })),
+            }
+        }
+    }
+}
+
+/// Wrap an SSE-like streaming response so it can fail over to fallback
+/// sources on stalls or errors (TS `withStreamingFailover`).
+///
+/// `get_fallback` receives the 1-based attempt number and total emitted bytes
+/// and returns the fallback response (`Ok(None)` / a body-less response ⇒ no
+/// fallback, the ORIGINAL error propagates; `Err` ⇒ THAT error propagates).
+/// On a successful failover an SSE comment marker
+/// `": codex-multi-auth failover {n}[ req:{id}]\n\n"` is injected (byte-exact
+/// contract, spec 06 gotcha 14).
+///
+/// Must be called within a tokio runtime (the pump is a spawned task).
+pub fn with_streaming_failover<F, Fut>(
+    mut initial_response: StreamResponse,
+    get_fallback_response: F,
+    options: StreamFailoverOptions,
+) -> StreamResponse
+where
+    F: FnMut(u32, u64) -> Fut + Send + 'static,
+    Fut: std::future::Future<Output = Result<Option<StreamResponse>, BoxError>> + Send + 'static,
+{
+    let max_failovers = options
+        .max_failovers
+        .unwrap_or(DEFAULT_MAX_FAILOVERS)
+        .floor()
+        .max(0.0) as i64;
+    let default_hard_timeout_ms = options.stall_timeout_ms.unwrap_or(DEFAULT_STALL_TIMEOUT_MS);
+    let soft_timeout_ms = options
+        .soft_timeout_ms
+        .unwrap_or_else(|| default_hard_timeout_ms.min(DEFAULT_SOFT_TIMEOUT_MS))
+        .floor()
+        .max(1_000.0);
+    let hard_timeout_ms = options
+        .hard_timeout_ms
+        .unwrap_or(default_hard_timeout_ms)
+        .floor()
+        .max(soft_timeout_ms);
+    let request_instance_id = normalize_request_instance_id(options.request_instance_id.as_deref());
+    let headers = ensure_content_type(&initial_response.headers);
+
+    if initial_response.body.is_none() || max_failovers <= 0 {
+        return initial_response;
+    }
+
+    let body = initial_response.body.take().expect("checked above");
+    let (tx, rx) = mpsc::channel::<Result<Bytes, BoxError>>(1);
+    tokio::spawn(pump(
+        body,
+        tx,
+        get_fallback_response,
+        max_failovers as u32,
+        soft_timeout_ms as u64,
+        hard_timeout_ms as u64,
+        request_instance_id,
+    ));
+
+    let wrapped: BodyStream = futures::stream::unfold(rx, |mut rx| async move {
+        rx.recv().await.map(|item| (item, rx))
+    })
+    .boxed();
+
+    StreamResponse::new(
+        initial_response.status,
+        initial_response.status_text.clone(),
+        headers,
+        Some(wrapped),
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn pump<F, Fut>(
+    mut current: BodyStream,
+    tx: mpsc::Sender<Result<Bytes, BoxError>>,
+    mut get_fallback_response: F,
+    max_failovers: u32,
+    soft_timeout_ms: u64,
+    hard_timeout_ms: u64,
+    request_instance_id: Option<String>,
+) where
+    F: FnMut(u32, u64) -> Fut + Send + 'static,
+    Fut: std::future::Future<Output = Result<Option<StreamResponse>, BoxError>> + Send + 'static,
+{
+    let mut failover_attempt: u32 = 0;
+    let mut emitted_bytes: u64 = 0;
+
+    loop {
+        let outcome = tokio::select! {
+            // Consumer cancelled the wrapped stream: stop pumping; dropping
+            // `current` cancels the upstream (TS cancel() → reader.cancel()).
+            _ = tx.closed() => return,
+            outcome = read_chunk_with_soft_hard_timeout(&mut current, soft_timeout_ms, hard_timeout_ms) => outcome,
+        };
+
+        match outcome {
+            Ok(ReadOutcome::Done) => {
+                // Normal end: dropping tx closes the channel (controller.close()).
+                return;
+            }
+            Ok(ReadOutcome::Chunk(bytes)) => {
+                if !bytes.is_empty() {
+                    emitted_bytes += bytes.len() as u64;
+                    if tx.send(Ok(bytes)).await.is_err() {
+                        return;
+                    }
+                }
+            }
+            Err(error) => {
+                // Stall or read error → attempt failover.
+                if failover_attempt >= max_failovers || emitted_bytes > 0 {
+                    // Never replay after partial output; propagate the error.
+                    let _ = tx.send(Err(error)).await;
+                    return;
+                }
+                failover_attempt += 1;
+                match get_fallback_response(failover_attempt, emitted_bytes).await {
+                    Err(failover_error) => {
+                        // Failover-callback exceptions error the stream with
+                        // THAT error.
+                        let _ = tx.send(Err(failover_error)).await;
+                        return;
+                    }
+                    Ok(fallback) => {
+                        let fallback_body = fallback.and_then(|mut r| r.body.take());
+                        let Some(fallback_body) = fallback_body else {
+                            // No usable fallback: give up, propagate original.
+                            let _ = tx.send(Err(error)).await;
+                            return;
+                        };
+                        // Release the old reader BEFORE the marker (TS order).
+                        drop(std::mem::replace(&mut current, fallback_body));
+                        let marker_label = match &request_instance_id {
+                            Some(id) => format!(
+                                ": codex-multi-auth failover {failover_attempt} req:{id}\n\n"
+                            ),
+                            None => format!(": codex-multi-auth failover {failover_attempt}\n\n"),
+                        };
+                        if tx.send(Ok(Bytes::from(marker_label))).await.is_err() {
+                            return;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalizes_request_instance_id() {
+        assert_eq!(normalize_request_instance_id(None), None);
+        assert_eq!(normalize_request_instance_id(Some("   ")), None);
+        assert_eq!(
+            normalize_request_instance_id(Some("  req-1  ")),
+            Some("req-1".to_string())
+        );
+        let long = "x".repeat(100);
+        assert_eq!(
+            normalize_request_instance_id(Some(&long)),
+            Some("x".repeat(MAX_REQUEST_INSTANCE_ID_LENGTH))
+        );
+    }
+
+    #[test]
+    fn stall_timeout_error_message_is_frozen() {
+        let error = StallTimeoutError { timeout_ms: 15_000 };
+        assert_eq!(error.to_string(), "SSE stream stalled for 15000ms");
+        let boxed: BoxError = Box::new(StallTimeoutError { timeout_ms: 1 });
+        assert!(is_stall_timeout_error(&boxed));
+        let other: BoxError = "some other error".to_string().into();
+        assert!(!is_stall_timeout_error(&other));
+    }
+}
diff --git a/crates/request/src/stream_failover_runtime.rs b/crates/request/src/stream_failover_runtime.rs
new file mode 100644
index 000000000..c9fee5c04
--- /dev/null
+++ b/crates/request/src/stream_failover_runtime.rs
@@ -0,0 +1,364 @@
+//! Port of `lib/request/stream-failover-runtime.ts` — proxy-side stream
+//! forwarding (spec 06 §21; ARCHITECTURE §6.10).
+//!
+//! Forwards an upstream [`StreamResponse`] onto the local rotation proxy's
+//! client connection, scrubbing hop-by-hop headers, `content-encoding` (the
+//! HTTP client already decoded the bytes), and every header under the private
+//! `x-codex-multi-auth-account-` prefix (account index/label/email/id must
+//! never reach the client; prefix matching blocks future additions by
+//! default).
+//!
+//! The Node `ServerResponse` is abstracted as [`ClientStreamWriter`] so the
+//! runtime crate can adapt it onto a hyper response channel; the runtime's
+//! `RuntimeRotationProxyStatus` counters are reached through
+//! [`StreamForwardStatus`] (cma-request must not depend on cma-runtime).
+
+use std::time::Duration;
+
+use futures::StreamExt;
+use futures::future::BoxFuture;
+use http::HeaderMap;
+
+use crate::response_handler::{BoxError, StreamResponse};
+
+/// TS `HOP_BY_HOP_HEADERS` (RFC 7230 §6.1 connection-specific headers plus
+/// `content-length`, which no longer matches the re-chunked body).
+pub const HOP_BY_HOP_HEADERS: [&str; 10] = [
+    "connection",
+    "content-length",
+    "expect",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+];
+
+// Any header under this prefix carries account-identifying rotation metadata
+// (index/label/email/id today) and must never reach the client; matching by
+// prefix means a future header added under it is blocked by default instead
+// of leaking until someone remembers to extend an allowlist.
+const PRIVATE_CLIENT_RESPONSE_HEADER_PREFIX: &str = "x-codex-multi-auth-account-";
+
+// The HTTP client returns decoded bytes while preserving the upstream
+// encoding header (TS `DECODED_UPSTREAM_RESPONSE_HEADERS`).
+const DECODED_UPSTREAM_RESPONSE_HEADERS: [&str; 1] = ["content-encoding"];
+
+/// Whether a (lowercased) header name is in [`HOP_BY_HOP_HEADERS`].
+pub fn is_hop_by_hop_header(name: &str) -> bool {
+    HOP_BY_HOP_HEADERS.contains(&name)
+}
+
+/// Copy upstream headers for the client, dropping hop-by-hop headers, private
+/// `x-codex-multi-auth-account-*` rotation metadata, and `content-encoding`
+/// (TS `responseHeadersForClient`). Multi-valued headers yield one pair per
+/// value; names are lowercase (`http::HeaderName` normalization). Values that
+/// are not valid UTF-8 are dropped.
+pub fn response_headers_for_client(upstream_headers: &HeaderMap) -> Vec<(String, String)> {
+    let mut headers: Vec<(String, String)> = Vec::new();
+    for (name, value) in upstream_headers {
+        let normalized_key = name.as_str(); // already lowercase
+        if is_hop_by_hop_header(normalized_key) {
+            continue;
+        }
+        if normalized_key.starts_with(PRIVATE_CLIENT_RESPONSE_HEADER_PREFIX) {
+            continue;
+        }
+        if DECODED_UPSTREAM_RESPONSE_HEADERS.contains(&normalized_key) {
+            continue;
+        }
+        let Ok(value) = value.to_str() else {
+            continue;
+        };
+        headers.push((normalized_key.to_string(), value.to_string()));
+    }
+    headers
+}
+
+/// Race a future against a timer (TS `withTimeout`). On timeout the returned
+/// error carries `message` and is produced BEFORE `on_timeout` runs — the TS
+/// ordering contract (onTimeout side effects, e.g. cancelling a stream
+/// reader, could otherwise settle the promise cleanly and win the race,
+/// turning a stall into silent success). In Rust the select is already
+/// decided when the timer fires, so the ordering holds structurally; the
+/// timed-out future is dropped (cancelled).
+///
+/// The timer is clamped to a minimum of 1 ms (TS `Math.max(1, timeoutMs)`).
+pub async fn with_timeout<T, F>(
+    future: F,
+    timeout_ms: f64,
+    on_timeout: impl FnOnce(),
+    message: &str,
+) -> Result<T, BoxError>
+where
+    F: std::future::Future<Output = T>,
+{
+    let clamped_ms = if timeout_ms.is_finite() {
+        timeout_ms.floor().max(1.0)
+    } else {
+        1.0
+    } as u64;
+    match tokio::time::timeout(Duration::from_millis(clamped_ms), future).await {
+        Ok(value) => Ok(value),
+        Err(_) => {
+            let error: BoxError = message.to_string().into();
+            on_timeout();
+            Err(error)
+        }
+    }
+}
+
+/// Default byte cap for [`read_error_body`] (TS `maxBytes = 1024 * 1024`).
+pub const READ_ERROR_BODY_DEFAULT_MAX_BYTES: usize = 1024 * 1024;
+
+/// Bounded error-body read (TS `readErrorBody`): per-chunk idle timeout AND a
+/// size cap (the chunk that would overflow the cap is dropped and the loop
+/// stops); the stream is cancelled (dropped) on exit. All failures degrade to
+/// returning whatever was collected (UTF-8 lossy) or `""` — this helper never
+/// errors.
+pub async fn read_error_body(
+    response: &mut StreamResponse,
+    timeout_ms: f64,
+    max_bytes: Option<usize>,
+) -> String {
+    let max_bytes = max_bytes.unwrap_or(READ_ERROR_BODY_DEFAULT_MAX_BYTES);
+    let Some(mut body) = response.body.take() else {
+        // TS falls back to `response.text()` for bodyless impls, which yields
+        // "" for a null body.
+        return String::new();
+    };
+
+    let idle_ms = if timeout_ms.is_finite() {
+        timeout_ms.floor().max(1.0)
+    } else {
+        1.0
+    } as u64;
+
+    let mut chunks: Vec<u8> = Vec::new();
+    let mut total: usize = 0;
+    loop {
+        let read = tokio::time::timeout(Duration::from_millis(idle_ms), body.next()).await;
+        match read {
+            Err(_) => break, // idle timeout: fall through with what we have
+            Ok(None) => break,
+            Ok(Some(Err(_))) => break, // stream error: degrade to partial body
+            Ok(Some(Ok(chunk))) => {
+                total += chunk.len();
+                if total > max_bytes {
+                    break; // cap: enough for diagnostics, no OOM
+                }
+                chunks.extend_from_slice(&chunk);
+            }
+        }
+    }
+    drop(body); // reader.cancel()
+    String::from_utf8_lossy(&chunks).into_owned()
+}
+
+/// Minimal view of the runtime proxy status counters this module mutates
+/// (TS mutates `RuntimeRotationProxyStatus.streamsStarted` / `.lastError`
+/// directly; the concrete struct lives in cma-runtime).
+pub trait StreamForwardStatus {
+    /// `status.streamsStarted += 1`.
+    fn increment_streams_started(&mut self);
+    /// `status.lastError = message`.
+    fn set_last_error(&mut self, message: String);
+}
+
+/// Node `ServerResponse` analogue for the rotation proxy's client connection.
+/// The runtime crate implements this over its hyper/axum response plumbing;
+/// tests use an in-memory fake.
+pub trait ClientStreamWriter: Send {
+    /// `res.writeHead(status, headers)`.
+    fn write_head(&mut self, status: u16, headers: Vec<(String, String)>);
+
+    /// `res.writableEnded`.
+    fn writable_ended(&self) -> bool;
+
+    /// `res.destroyed`.
+    fn destroyed(&self) -> bool;
+
+    /// `res.write(chunk)`: `Ok(true)` = accepted and ready for more,
+    /// `Ok(false)` = accepted but the client buffer is full (backpressure),
+    /// `Err` = the write threw (e.g. write-after-destroy).
+    fn write(&mut self, chunk: &[u8]) -> Result<bool, BoxError>;
+
+    /// Resolve once the client can accept more data again — and ALSO on
+    /// close/error, so a client that disconnects mid-backpressure cannot park
+    /// the forwarder forever (TS `waitForDrain`).
+    fn wait_for_drain(&mut self) -> BoxFuture<'_, ()>;
+
+    /// `res.end()`.
+    fn end(&mut self);
+
+    /// `res.destroy(error)`.
+    fn destroy(&mut self, error: Option<BoxError>);
+
+    /// Resolve when the client connection closes (TS `res.on("close")`); must
+    /// NOT resolve for a plain socket error without close. Used to stop
+    /// forwarding when the client disconnects mid-stream.
+    fn closed(&self) -> BoxFuture<'static, ()>;
+}
+
+/// Forward an upstream streaming response to the proxy client (TS
+/// `forwardStreamingResponse`). Returns `true` for a clean end (including a
+/// client disconnect observed via `closed()`), `false` when the stream failed
+/// (stall, upstream read error, or client write error) — in which case
+/// `status.lastError` is set, `on_stream_error` has fired, and the client
+/// response is destroyed with the error.
+pub async fn forward_streaming_response<W, S>(
+    mut upstream: StreamResponse,
+    res: &mut W,
+    status: &mut S,
+    on_stream_error: impl FnOnce(),
+    stream_stall_timeout_ms: u64,
+) -> bool
+where
+    W: ClientStreamWriter,
+    S: StreamForwardStatus,
+{
+    status.increment_streams_started();
+    res.write_head(upstream.status, response_headers_for_client(&upstream.headers));
+    let Some(mut body) = upstream.body.take() else {
+        res.end();
+        return true;
+    };
+
+    let mut closed = res.closed();
+    let stall_message = format!("upstream stream stalled after {stream_stall_timeout_ms}ms");
+
+    let error: BoxError = loop {
+        // TS installs a close handler that cancels the upstream reader so the
+        // pending read observes `done`; selecting on `closed()` here has the
+        // same observable effect (stop reading, end cleanly).
+        let outcome = tokio::select! {
+            biased;
+            _ = &mut closed => {
+                // Client disconnected: cancel upstream (drop) and finish via
+                // the clean end-of-stream path.
+                drop(body);
+                res.end();
+                return true;
+            }
+            read = tokio::time::timeout(
+                Duration::from_millis(stream_stall_timeout_ms.max(1)),
+                body.next(),
+            ) => read,
+        };
+
+        match outcome {
+            Err(_) => {
+                // Stall: the error is created before the reader is cancelled
+                // (drop on scope exit) — TS withTimeout ordering.
+                break stall_message.clone().into();
+            }
+            Ok(None) => {
+                res.end();
+                return true;
+            }
+            Ok(Some(Err(read_error))) => break read_error,
+            Ok(Some(Ok(chunk))) => {
+                if chunk.is_empty() {
+                    continue;
+                }
+                // If the response is already finished (clean end by a
+                // concurrent close-then-cancel path), stop writing. Do NOT
+                // guard on `destroyed()` here: a socket-error-during-
+                // backpressure scenario sets destroyed and then lets the next
+                // write throw so the catch path records the error and fires
+                // on_stream_error correctly.
+                if res.writable_ended() {
+                    res.end();
+                    return true;
+                }
+                match res.write(&chunk) {
+                    Err(write_error) => break write_error,
+                    Ok(ready) => {
+                        // Respect backpressure: when the client's socket
+                        // buffer is full, pause upstream reads until it
+                        // drains instead of buffering the whole stream in
+                        // memory for a slow consumer.
+                        if !ready && !res.destroyed() {
+                            res.wait_for_drain().await;
+                        }
+                    }
+                }
+            }
+        }
+    };
+
+    status.set_last_error(error.to_string());
+    on_stream_error();
+    if !res.destroyed() {
+        res.destroy(Some(error));
+    }
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::header::{HeaderName, HeaderValue};
+
+    fn header_map(pairs: &[(&str, &str)]) -> HeaderMap {
+        let mut map = HeaderMap::new();
+        for (name, value) in pairs {
+            map.append(
+                HeaderName::from_bytes(name.as_bytes()).unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn drops_hop_by_hop_private_and_content_encoding_headers() {
+        let upstream = header_map(&[
+            ("content-type", "application/json"),
+            ("x-request-id", "req_1"),
+            ("connection", "keep-alive"),
+            ("transfer-encoding", "chunked"),
+            ("content-encoding", "gzip"),
+            ("x-codex-multi-auth-account-email", "user@example.com"),
+            ("x-codex-multi-auth-account-id", "acc_1"),
+        ]);
+        let mut filtered = response_headers_for_client(&upstream);
+        filtered.sort();
+        assert_eq!(
+            filtered,
+            vec![
+                ("content-type".to_string(), "application/json".to_string()),
+                ("x-request-id".to_string(), "req_1".to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn blocks_any_header_under_the_private_account_prefix() {
+        // Regression: the filter used to be an exact-name allowlist, so a
+        // future x-codex-multi-auth-account-* header would have leaked.
+        let upstream = header_map(&[
+            ("content-type", "application/json"),
+            ("x-codex-multi-auth-account-plan", "pro"),
+            ("x-codex-multi-auth-account-future-field", "secret"),
+        ]);
+        assert_eq!(
+            response_headers_for_client(&upstream),
+            vec![("content-type".to_string(), "application/json".to_string())]
+        );
+    }
+
+    #[test]
+    fn covers_every_hop_by_hop_header_in_the_exported_set() {
+        let mut upstream = HeaderMap::new();
+        for name in HOP_BY_HOP_HEADERS {
+            upstream.append(
+                HeaderName::from_bytes(name.as_bytes()).unwrap(),
+                HeaderValue::from_static("1"),
+            );
+        }
+        assert_eq!(response_headers_for_client(&upstream), Vec::new());
+    }
+}
diff --git a/crates/request/src/token_refresh.rs b/crates/request/src/token_refresh.rs
new file mode 100644
index 000000000..ca9168cc7
--- /dev/null
+++ b/crates/request/src/token_refresh.rs
@@ -0,0 +1,532 @@
+//! Port of `lib/request/token-refresh.ts` — OAuth refresh + persistence.
+//!
+//! Behavior source: spec 06 §10 + the TS source (authority). `fetch_helpers`
+//! re-exports this module's public surface, mirroring the TS re-export
+//! contract.
+//!
+//! Persistence boundary (spec 06 §23): the TS module persists refreshed
+//! credentials ONLY through the host client
+//! (`client.auth.set({ path: { id: "openai" }, body: { type: "oauth", access,
+//! refresh, expires, multiAccount: true } })`). The Rust port replaces the
+//! host client with an injected [`AuthSetterFn`] (wired by the pipeline to
+//! storage/accounts persistence — ARCHITECTURE §6.10). `multiAccount: true`
+//! remains a required literal on [`AuthPersistPayload`].
+//!
+//! Mutation contract (spec 06 gotcha 20): `refreshAndUpdateToken` persists
+//! FIRST, then mutates the shared Auth object in place and returns the same
+//! reference. Rust mirrors this with `&mut Auth`: the setter future is awaited
+//! before the fields are overwritten. Same-token refreshes are serialized via
+//! `cma_auth::refresh_queue::queued_refresh`.
+
+use cma_core::constants::{ERROR_MESSAGES, HTTP_STATUS};
+use cma_core::errors::{CodexError, ErrorContext};
+use cma_core::fs_retry::{CodedError, code_of};
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult};
+use cma_core::types::OAuthAuthDetails;
+use cma_core::utils::now_ms;
+use futures::future::BoxFuture;
+use serde_json::Value;
+use std::error::Error as StdError;
+use std::future::Future;
+
+/// Boxed error carried by auth-setter failures (the TS thrown `unknown`).
+pub type BoxError = Box<dyn StdError + Send + Sync + 'static>;
+
+/// The TS `@codex-ai/sdk` `Auth` union, reduced to what this cluster needs:
+/// the OAuth arm (with its token fields) versus "anything else" (API key
+/// etc.), which always triggers a refresh and is never mutated.
+#[derive(Debug, Clone)]
+pub enum Auth {
+    OAuth(OAuthAuthDetails),
+    /// Any non-OAuth auth entry (the TS `{ type: "api", ... }` arm). Only its
+    /// not-OAuth-ness matters here.
+    Other,
+}
+
+impl Auth {
+    /// The OAuth details when this is the OAuth arm.
+    pub fn as_oauth(&self) -> Option<&OAuthAuthDetails> {
+        match self {
+            Auth::OAuth(details) => Some(details),
+            Auth::Other => None,
+        }
+    }
+}
+
+/// TS `client.auth.set` body: `{ type: "oauth", access, refresh, expires,
+/// multiAccount: true }`. The receiving store owns the on-disk format.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthPersistPayload {
+    /// Always `"oauth"` (TS literal).
+    pub auth_type: &'static str,
+    pub access: String,
+    pub refresh: String,
+    /// Epoch milliseconds.
+    pub expires: i64,
+    /// Always `true` (TS required literal `multiAccount: true`).
+    pub multi_account: bool,
+}
+
+/// The injected persistence hook replacing the TS `client.auth.set`.
+///
+/// Callers pass `None` to model a host without an auth setter — that maps to
+/// the TS "client.auth.set is missing / not a function" branch (frozen
+/// non-retryable failure, refresh never attempted).
+pub type AuthSetterFn<'a> =
+    &'a (dyn Fn(AuthPersistPayload) -> BoxFuture<'a, Result<(), BoxError>> + Send + Sync);
+
+/// TS `shouldRefreshToken(auth, skewMs = 0)`.
+///
+/// - Non-OAuth auth → `true`.
+/// - Empty access token → `true`.
+/// - Otherwise `expires <= Date.now() + max(0, floor(skewMs))`.
+pub fn should_refresh_token(auth: &Auth, skew_ms: f64) -> bool {
+    should_refresh_token_at(auth, skew_ms, now_ms())
+}
+
+/// [`should_refresh_token`] against an explicit wall-clock instant (test seam
+/// for the TS `Date.now()` mock).
+pub fn should_refresh_token_at(auth: &Auth, skew_ms: f64, now_ms: i64) -> bool {
+    let Auth::OAuth(details) = auth else {
+        return true;
+    };
+    if details.access.is_empty() {
+        return true;
+    }
+    let safe_skew_ms = if skew_ms.is_finite() {
+        skew_ms.floor().max(0.0) as i64
+    } else {
+        // JS `Math.max(0, Math.floor(NaN))` is NaN and `expires <= NaN` is
+        // false; treating non-finite skew as 0 keeps the comparison total
+        // with the same "no early refresh" effect for valid tokens.
+        0
+    };
+    details.expires <= now_ms.saturating_add(safe_skew_ms)
+}
+
+/// TS private `isRetryableRefreshFailure`.
+fn is_retryable_refresh_failure(failure: &TokenFailure) -> bool {
+    match failure.reason {
+        Some(
+            TokenFailureReason::NetworkError
+            | TokenFailureReason::Unknown
+            | TokenFailureReason::InvalidResponse,
+        ) => true,
+        Some(TokenFailureReason::MissingRefresh) => false,
+        Some(TokenFailureReason::HttpError) => !matches!(
+            failure.status_code,
+            Some(code)
+                if code == HTTP_STATUS.bad_request as i64
+                    || code == HTTP_STATUS.unauthorized as i64
+                    || code == HTTP_STATUS.forbidden as i64
+        ),
+        // TS `default:` — covers `timeout` and missing reasons.
+        _ => false,
+    }
+}
+
+/// TS private `isRetryableAuthSetterError`: `.code` (uppercased) in
+/// {EAGAIN, EBUSY, EPERM}, or `.status === 429`, recursing into `.cause`.
+///
+/// The Rust error-chain walk covers the shapes a setter can realistically
+/// surface: `io::Error` (errno via `fs_retry::code_of`), `CodedError`
+/// (synthetic errno strings), `CodexError` (code/status accessors), and
+/// `reqwest::Error` (HTTP status), then `source()` recursion (the `.cause`
+/// analogue; Rust chains are finite so no self-reference guard is needed).
+fn is_retryable_auth_setter_error(error: &(dyn StdError + 'static)) -> bool {
+    const RETRYABLE_CODES: [&str; 3] = ["EAGAIN", "EBUSY", "EPERM"];
+
+    let mut current: Option<&(dyn StdError + 'static)> = Some(error);
+    while let Some(err) = current {
+        if let Some(io_error) = err.downcast_ref::<std::io::Error>()
+            && let Some(code) = code_of(io_error)
+                && RETRYABLE_CODES.contains(&code.to_uppercase().as_str()) {
+                    return true;
+                }
+        if let Some(coded) = err.downcast_ref::<CodedError>()
+            && RETRYABLE_CODES.contains(&coded.code().to_uppercase().as_str()) {
+                return true;
+            }
+        if let Some(codex) = err.downcast_ref::<CodexError>() {
+            if RETRYABLE_CODES.contains(&codex.code().to_uppercase().as_str()) {
+                return true;
+            }
+            if codex.status() == Some(HTTP_STATUS.too_many_requests) {
+                return true;
+            }
+        }
+        if let Some(request_error) = err.downcast_ref::<reqwest::Error>()
+            && request_error.status().map(|status| status.as_u16())
+                == Some(HTTP_STATUS.too_many_requests)
+            {
+                return true;
+            }
+        // `io::Error::source()` skips its custom inner error (it forwards the
+        // INNER error's source), so step into `get_ref()` explicitly to keep
+        // the whole `.cause` chain visible.
+        current = match err.downcast_ref::<std::io::Error>().and_then(|io| io.get_ref()) {
+            Some(inner) => Some(inner as &(dyn StdError + 'static)),
+            None => err.source(),
+        };
+    }
+    false
+}
+
+fn token_refresh_failed_error() -> CodexError {
+    CodexError::auth(ERROR_MESSAGES.token_refresh_failed)
+}
+
+/// TS `refreshAndUpdateToken(currentAuth, client)` against the real refresh
+/// queue (`cma_auth::refresh_queue::queued_refresh`).
+///
+/// On success `current_auth` is mutated in place (access/refresh/expires)
+/// AFTER the setter future resolves, mirroring the TS mutation contract; the
+/// TS "returns the same reference" contract is the `&mut` borrow itself.
+pub async fn refresh_and_update_token(
+    current_auth: &mut Auth,
+    auth_setter: Option<AuthSetterFn<'_>>,
+) -> Result<(), CodexError> {
+    refresh_and_update_token_with(current_auth, auth_setter, |refresh_token| async move {
+        cma_auth::refresh_queue::queued_refresh(&refresh_token).await
+    })
+    .await
+}
+
+/// [`refresh_and_update_token`] with an injectable refresh runner (the TS
+/// tests' `queuedRefresh` mock seam). `run_refresh` receives the refresh
+/// token — `""` for non-OAuth auth, exactly like the TS
+/// `currentAuth.type === "oauth" ? currentAuth.refresh : ""`.
+pub async fn refresh_and_update_token_with<F, Fut>(
+    current_auth: &mut Auth,
+    auth_setter: Option<AuthSetterFn<'_>>,
+    run_refresh: F,
+) -> Result<(), CodexError>
+where
+    F: FnOnce(String) -> Fut,
+    Fut: Future<Output = TokenResult>,
+{
+    // TS: missing/malformed `client.auth.set` fails BEFORE any refresh work.
+    let Some(auth_setter) = auth_setter else {
+        return Err(token_refresh_failed_error().with_retryable(false));
+    };
+
+    let refresh_token = match current_auth {
+        Auth::OAuth(details) => details.refresh.clone(),
+        Auth::Other => String::new(),
+    };
+    let refresh_result = run_refresh(refresh_token).await;
+
+    let success = match refresh_result {
+        TokenResult::Failed(failure) => {
+            let mut context = ErrorContext::new();
+            if let Some(reason) = failure.reason {
+                context.insert(
+                    "refreshFailureReason".to_string(),
+                    Value::String(reason.as_str().to_string()),
+                );
+            }
+            if let Some(status_code) = failure.status_code {
+                context.insert("statusCode".to_string(), Value::from(status_code));
+            }
+            return Err(token_refresh_failed_error()
+                .with_retryable(is_retryable_refresh_failure(&failure))
+                .with_context(context));
+        }
+        TokenResult::Success(success) => success,
+    };
+
+    // Persist FIRST (TS awaits client.auth.set before the in-place mutation).
+    let payload = AuthPersistPayload {
+        auth_type: "oauth",
+        access: success.access.clone(),
+        refresh: success.refresh.clone(),
+        expires: success.expires,
+        multi_account: true,
+    };
+    if let Err(error) = auth_setter(payload).await {
+        let retryable = is_retryable_auth_setter_error(error.as_ref());
+        return Err(token_refresh_failed_error()
+            .with_retryable(retryable)
+            .with_cause(error));
+    }
+
+    // THEN mutate the shared auth reference (OAuth arm only).
+    if let Auth::OAuth(details) = current_auth {
+        details.access = success.access;
+        details.refresh = success.refresh;
+        details.expires = success.expires;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenSuccess;
+    use std::sync::Mutex;
+
+    fn oauth(access: &str, refresh: &str, expires: i64) -> Auth {
+        Auth::OAuth(OAuthAuthDetails {
+            access: access.to_string(),
+            refresh: refresh.to_string(),
+            expires,
+        })
+    }
+
+    fn success_result(access: &str, refresh: &str, expires: i64) -> TokenResult {
+        TokenResult::Success(TokenSuccess {
+            access: access.to_string(),
+            refresh: refresh.to_string(),
+            expires,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    fn failed_result(reason: TokenFailureReason, status_code: Option<i64>) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: Some(reason),
+            status_code,
+            message: None,
+        })
+    }
+
+    // -- shouldRefreshToken -------------------------------------------------
+
+    #[test]
+    fn returns_true_for_non_oauth_auth() {
+        assert!(should_refresh_token(&Auth::Other, 0.0));
+    }
+
+    #[test]
+    fn returns_true_when_access_token_is_missing() {
+        let auth = oauth("", "refresh-token", now_ms() + 1000);
+        assert!(should_refresh_token(&auth, 0.0));
+    }
+
+    #[test]
+    fn returns_true_when_token_is_expired() {
+        let auth = oauth("access-token", "refresh-token", now_ms() - 1000);
+        assert!(should_refresh_token(&auth, 0.0));
+    }
+
+    #[test]
+    fn returns_false_for_valid_oauth_token() {
+        let auth = oauth("access-token", "refresh-token", now_ms() + 10_000);
+        assert!(!should_refresh_token(&auth, 0.0));
+    }
+
+    #[test]
+    fn refreshes_token_early_when_within_skew_window() {
+        let auth = oauth("access-token", "refresh-token", 1_500);
+        assert!(should_refresh_token_at(&auth, 500.0, 1_000));
+        assert!(!should_refresh_token_at(&auth, 400.0, 1_000));
+        // Negative skew floors to 0.
+        assert!(!should_refresh_token_at(&auth, -1.0, 1_000));
+    }
+
+    // -- refreshAndUpdateToken ----------------------------------------------
+
+    #[tokio::test]
+    async fn throws_when_client_auth_setter_is_missing() {
+        let mut auth = oauth("old", "oldr", 0);
+        let refresh_calls = Mutex::new(0u32);
+        let error = refresh_and_update_token_with(&mut auth, None, |_token| {
+            *refresh_calls.lock().unwrap() += 1;
+            async { success_result("new", "newr", 123) }
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.message(), ERROR_MESSAGES.token_refresh_failed);
+        assert_eq!(error.retryable(), Some(false));
+        // The refresh queue must NOT be touched when the setter is missing.
+        assert_eq!(*refresh_calls.lock().unwrap(), 0);
+    }
+
+    #[tokio::test]
+    async fn throws_retryable_auth_errors_for_transient_refresh_failures() {
+        let mut auth = oauth("old", "bad", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| Box::pin(async { Ok(()) });
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            failed_result(TokenFailureReason::NetworkError, None)
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.retryable(), Some(true));
+        let context = error.context().unwrap();
+        assert_eq!(
+            context.get("refreshFailureReason"),
+            Some(&Value::String("network_error".into()))
+        );
+    }
+
+    #[tokio::test]
+    async fn throws_terminal_auth_errors_for_explicit_invalid_refresh_responses() {
+        let mut auth = oauth("old", "bad", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| Box::pin(async { Ok(()) });
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            failed_result(TokenFailureReason::HttpError, Some(401))
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.retryable(), Some(false));
+        let context = error.context().unwrap();
+        assert_eq!(context.get("statusCode"), Some(&Value::from(401)));
+    }
+
+    #[tokio::test]
+    async fn http_error_refresh_failures_stay_retryable_off_the_terminal_statuses() {
+        for (status, expected) in [(400, false), (401, false), (403, false), (500, true)] {
+            let mut auth = oauth("old", "bad", 0);
+            let setter: AuthSetterFn<'_> = &|_payload| Box::pin(async { Ok(()) });
+            let error =
+                refresh_and_update_token_with(&mut auth, Some(setter), |_token| async move {
+                    failed_result(TokenFailureReason::HttpError, Some(status))
+                })
+                .await
+                .unwrap_err();
+            assert_eq!(error.retryable(), Some(expected), "status {status}");
+        }
+    }
+
+    #[tokio::test]
+    async fn treats_missing_refresh_tokens_as_terminal_auth_errors() {
+        let mut auth = oauth("old", "", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| Box::pin(async { Ok(()) });
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            failed_result(TokenFailureReason::MissingRefresh, None)
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.retryable(), Some(false));
+    }
+
+    #[tokio::test]
+    async fn timeout_reason_falls_to_the_non_retryable_default_branch() {
+        let mut auth = oauth("old", "oldr", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| Box::pin(async { Ok(()) });
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            failed_result(TokenFailureReason::Timeout, None)
+        })
+        .await
+        .unwrap_err();
+        assert_eq!(error.retryable(), Some(false));
+    }
+
+    #[tokio::test]
+    async fn updates_stored_auth_on_success() {
+        let mut auth = oauth("old", "oldr", 0);
+        let persisted: Mutex<Vec<AuthPersistPayload>> = Mutex::new(Vec::new());
+        let setter: AuthSetterFn<'_> = &|payload| {
+            persisted.lock().unwrap().push(payload);
+            Box::pin(async { Ok(()) })
+        };
+
+        refresh_and_update_token_with(&mut auth, Some(setter), |token| async move {
+            assert_eq!(token, "oldr");
+            success_result("new", "newr", 123)
+        })
+        .await
+        .unwrap();
+
+        let calls = persisted.lock().unwrap();
+        assert_eq!(
+            calls.as_slice(),
+            [AuthPersistPayload {
+                auth_type: "oauth",
+                access: "new".into(),
+                refresh: "newr".into(),
+                expires: 123,
+                multi_account: true,
+            }]
+        );
+        let details = auth.as_oauth().unwrap();
+        assert_eq!(details.access, "new");
+        assert_eq!(details.refresh, "newr");
+        assert_eq!(details.expires, 123);
+    }
+
+    #[tokio::test]
+    async fn throws_retryable_auth_errors_when_auth_persistence_fails() {
+        let mut auth = oauth("old", "oldr", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| {
+            Box::pin(
+                async { Err(Box::new(CodedError::new("EBUSY", "persist failed")) as BoxError) },
+            )
+        };
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            success_result("new", "newr", 123)
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.retryable(), Some(true));
+        // Persist failed BEFORE mutation: the auth object must keep the old
+        // values (mutation only happens after a successful setter await).
+        let details = auth.as_oauth().unwrap();
+        assert_eq!(details.access, "old");
+        assert_eq!(details.refresh, "oldr");
+    }
+
+    #[tokio::test]
+    async fn throws_terminal_auth_errors_when_auth_persistence_fails_permanently() {
+        let mut auth = oauth("old", "oldr", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| {
+            Box::pin(async {
+                Err(Box::new(CodedError::new("EACCES", "persist failed")) as BoxError)
+            })
+        };
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            success_result("new", "newr", 123)
+        })
+        .await
+        .unwrap_err();
+
+        assert_eq!(error.retryable(), Some(false));
+    }
+
+    #[tokio::test]
+    async fn setter_429_status_and_nested_causes_are_retryable() {
+        // status === 429 detected through a nested cause chain (io::Error
+        // wrapping a CodexApiError), matching the TS `.cause` recursion.
+        let mut auth = oauth("old", "oldr", 0);
+        let setter: AuthSetterFn<'_> = &|_payload| {
+            Box::pin(async {
+                let inner = CodexError::api("throttled", 429);
+                let outer = std::io::Error::other(inner);
+                Err(Box::new(outer) as BoxError)
+            })
+        };
+        let error = refresh_and_update_token_with(&mut auth, Some(setter), |_token| async {
+            success_result("new", "newr", 123)
+        })
+        .await
+        .unwrap_err();
+        assert_eq!(error.retryable(), Some(true));
+    }
+
+    #[tokio::test]
+    async fn refreshes_using_non_oauth_auth_without_mutating_oauth_fields() {
+        let mut auth = Auth::Other;
+        let persisted: Mutex<u32> = Mutex::new(0);
+        let setter: AuthSetterFn<'_> = &|_payload| {
+            *persisted.lock().unwrap() += 1;
+            Box::pin(async { Ok(()) })
+        };
+
+        refresh_and_update_token_with(&mut auth, Some(setter), |token| async move {
+            // Non-OAuth auth refreshes with an empty refresh token.
+            assert_eq!(token, "");
+            success_result("new-access", "new-refresh", 60_000)
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(*persisted.lock().unwrap(), 1);
+        assert!(auth.as_oauth().is_none());
+    }
+}
diff --git a/crates/request/src/tool_utils.rs b/crates/request/src/tool_utils.rs
new file mode 100644
index 000000000..7d1b301f0
--- /dev/null
+++ b/crates/request/src/tool_utils.rs
@@ -0,0 +1,582 @@
+//! Port of `lib/request/helpers/tool-utils.ts` — strict JSON-Schema cleanup of
+//! tool definitions (spec 06 §4).
+//!
+//! The cleanup runs over raw `serde_json::Value`s (the TS operated on plain
+//! objects), so every odd shape a host can send — untyped tools, namespaces,
+//! non-record parameters — behaves exactly like the JS runtime guards. The
+//! typed [`RequestToolDefinition`] wrappers round-trip losslessly through
+//! `Value` (verified in `cma_core::types` tests).
+
+use cma_core::types::RequestToolDefinition;
+use serde_json::{Map, Value, json};
+
+/// TS `cleanupToolDefinitions` — `None` (TS non-array) passes through as
+/// `None`; each tool is cleaned independently.
+///
+/// Rules (per tool, `type:"function"` only; `type:"namespace"` recurses):
+/// 1. Filter `required` to properties that exist.
+/// 2. Inject a `_placeholder` property into empty object parameter schemas.
+/// 3. Flatten `anyOf`-of-`const` into `enum` (+ type inference).
+/// 4. Normalize nullable array types to a single type + `(nullable)` note.
+/// 5. Remove unsupported keywords (`additionalProperties`, `const`, `title`,
+///    `$schema`).
+pub fn cleanup_tool_definitions(
+    tools: Option<Vec<RequestToolDefinition>>,
+) -> Option<Vec<RequestToolDefinition>> {
+    let tools = tools?;
+    Some(
+        tools
+            .into_iter()
+            .map(|tool| {
+                // Value round-trip: lossless for every arm incl. `Other`.
+                let raw = serde_json::to_value(&tool).unwrap_or(Value::Null);
+                let cleaned = cleanup_tool_definition_value(raw);
+                serde_json::from_value(cleaned).unwrap_or(tool)
+            })
+            .collect(),
+    )
+}
+
+/// TS `cleanupToolDefinition` — dispatch on the `type` literal.
+fn cleanup_tool_definition_value(tool: Value) -> Value {
+    let Some(record) = tool.as_object() else {
+        return tool;
+    };
+    match record.get("type").and_then(Value::as_str) {
+        Some("function") => cleanup_function_tool_value(tool),
+        Some("namespace") if record.get("tools").is_some_and(Value::is_array) => {
+            let mut record = tool.as_object().cloned().unwrap_or_default();
+            if let Some(Value::Array(nested)) = record.get("tools").cloned() {
+                record.insert(
+                    "tools".to_string(),
+                    Value::Array(nested.into_iter().map(cleanup_tool_definition_value).collect()),
+                );
+            }
+            Value::Object(record)
+        }
+        _ => tool,
+    }
+}
+
+/// TS `cleanupFunctionTool` — only when `function` and `function.parameters`
+/// are both plain records (arrays/null/strings pass through untouched, TS
+/// `isRecord` parity).
+fn cleanup_function_tool_value(tool: Value) -> Value {
+    let Some(tool_record) = tool.as_object() else {
+        return tool;
+    };
+    let Some(function_def) = tool_record.get("function").and_then(Value::as_object) else {
+        return tool;
+    };
+    let Some(parameters) = function_def.get("parameters").and_then(Value::as_object) else {
+        return tool;
+    };
+
+    // TS clones via JSON.parse(JSON.stringify(...)) — a Value is already an
+    // owned JSON tree, so the circular/bigint clone-failure path cannot occur.
+    let mut cleaned_parameters = parameters.clone();
+    cleanup_schema(&mut cleaned_parameters);
+
+    let mut new_function = function_def.clone();
+    new_function.insert("parameters".to_string(), Value::Object(cleaned_parameters));
+    let mut new_tool = tool_record.clone();
+    new_tool.insert("function".to_string(), Value::Object(new_function));
+    Value::Object(new_tool)
+}
+
+/// JS-truthiness of an optional JSON value (`!schema.type` etc.).
+fn is_js_falsy(value: Option<&Value>) -> bool {
+    match value {
+        None | Some(Value::Null) => true,
+        Some(Value::Bool(flag)) => !flag,
+        Some(Value::String(text)) => text.is_empty(),
+        Some(Value::Number(number)) => number.as_f64().map(|f| f == 0.0).unwrap_or(false),
+        _ => false,
+    }
+}
+
+/// TS `cleanupSchema` — recursive, mutates in place. Step order matters and is
+/// preserved exactly.
+fn cleanup_schema(schema: &mut Map<String, Value>) {
+    // Step 0: delete `properties` keys whose value is undefined — JSON has no
+    // undefined, so this is structurally moot after the Value round-trip
+    // (spec 06 §4 notes it is "mostly moot after JSON clone" in TS too).
+
+    // Step 1: flatten anyOf → enum when EVERY option carries a `const` key.
+    if let Some(Value::Array(any_of)) = schema.get("anyOf") {
+        // TS `"const" in opt` — a non-object option would throw in JS; here it
+        // simply fails the all-const test.
+        let all_const = !any_of.is_empty()
+            && any_of
+                .iter()
+                .all(|option| option.as_object().is_some_and(|o| o.contains_key("const")));
+        if all_const {
+            let enum_values: Vec<Value> = any_of
+                .iter()
+                .map(|option| option.get("const").cloned().unwrap_or(Value::Null))
+                .collect();
+            let first = enum_values.first().cloned();
+            schema.insert("enum".to_string(), Value::Array(enum_values));
+            schema.remove("anyOf");
+
+            // Infer type from the first value if `type` is missing (falsy).
+            if is_js_falsy(schema.get("type")) {
+                let inferred = match first {
+                    Some(Value::String(_)) => Some("string"),
+                    Some(Value::Number(_)) => Some("number"),
+                    Some(Value::Bool(_)) => Some("boolean"),
+                    _ => None,
+                };
+                if let Some(inferred) = inferred {
+                    schema.insert("type".to_string(), Value::String(inferred.to_string()));
+                }
+            }
+        }
+    }
+
+    // Step 2: flatten nullable array types (["string","null"] → "string").
+    if let Some(Value::Array(types)) = schema.get("type").cloned() {
+        let is_nullable = types.iter().any(|t| t.as_str() == Some("null"));
+        let non_null: Vec<Value> = types
+            .into_iter()
+            .filter(|t| t.as_str() != Some("null"))
+            .collect();
+        if let Some(first) = non_null.first() {
+            schema.insert("type".to_string(), first.clone());
+            if is_nullable {
+                // TS `(schema.description as string) || ""` — non-string
+                // descriptions degrade to "" (the TS would throw on them).
+                let desc = schema
+                    .get("description")
+                    .and_then(Value::as_str)
+                    .unwrap_or("")
+                    .to_string();
+                if !desc.to_lowercase().contains("nullable") {
+                    let annotated = if desc.is_empty() {
+                        "(nullable)".to_string()
+                    } else {
+                        format!("{desc} (nullable)")
+                    };
+                    schema.insert("description".to_string(), Value::String(annotated));
+                }
+            }
+        }
+    }
+
+    // Step 3: filter `required` down to keys that exist in `properties`.
+    if let (Some(Value::Array(required)), Some(Value::Object(properties))) =
+        (schema.get("required"), schema.get("properties"))
+    {
+        let valid_required: Vec<Value> = required
+            .iter()
+            .filter(|key| {
+                key.as_str()
+                    .map(|key| properties.contains_key(key))
+                    .unwrap_or(false)
+            })
+            .cloned()
+            .collect();
+        if valid_required.is_empty() {
+            schema.remove("required");
+        } else if valid_required.len() != required.len() {
+            schema.insert("required".to_string(), Value::Array(valid_required));
+        }
+    }
+
+    // Step 4: inject a placeholder property into empty object schemas.
+    if schema.get("type").and_then(Value::as_str) == Some("object") {
+        let needs_placeholder = match schema.get("properties") {
+            // `!schema.properties` (falsy) or `Object.keys(...).length === 0`.
+            None | Some(Value::Null) => true,
+            Some(Value::Object(map)) => map.is_empty(),
+            Some(Value::Array(items)) => items.is_empty(),
+            Some(Value::String(text)) => text.is_empty(),
+            // Numbers/bools have no enumerable keys in JS.
+            Some(Value::Bool(_)) | Some(Value::Number(_)) => true,
+        };
+        if needs_placeholder {
+            schema.insert(
+                "properties".to_string(),
+                json!({
+                    "_placeholder": {
+                        "type": "boolean",
+                        "description": "This property is a placeholder and should be ignored.",
+                    }
+                }),
+            );
+        }
+    }
+
+    // Step 5: remove unsupported keywords.
+    schema.remove("additionalProperties");
+    schema.remove("const");
+    schema.remove("title");
+    schema.remove("$schema");
+
+    // Step 6: recurse into each property schema.
+    if let Some(Value::Object(properties)) = schema.get_mut("properties") {
+        for property in properties.values_mut() {
+            if let Value::Object(nested) = property {
+                cleanup_schema(nested);
+            }
+        }
+    }
+
+    // Step 7: recurse into array items.
+    if let Some(Value::Object(items)) = schema.get_mut("items") {
+        cleanup_schema(items);
+    }
+}
+
+// ===========================================================================
+// Tests — ported from test/tool-utils.test.ts
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Parse tools from JSON, clean them, and return the cleaned JSON.
+    fn cleanup(value: Value) -> Value {
+        let tools: Vec<RequestToolDefinition> =
+            serde_json::from_value(value).expect("test tools must parse");
+        serde_json::to_value(cleanup_tool_definitions(Some(tools)).unwrap()).unwrap()
+    }
+
+    fn function_tool(parameters: Value) -> Value {
+        json!([{ "type": "function", "function": { "name": "test", "parameters": parameters } }])
+    }
+
+    fn parameters_of(cleaned: &Value) -> &Value {
+        &cleaned[0]["function"]["parameters"]
+    }
+
+    #[test]
+    fn returns_none_for_none_input() {
+        assert!(cleanup_tool_definitions(None).is_none());
+    }
+
+    #[test]
+    fn returns_non_function_tools_unchanged() {
+        let tools = json!([{ "type": "other", "data": "value" }]);
+        assert_eq!(cleanup(tools.clone()), tools);
+    }
+
+    #[test]
+    fn preserves_typed_hosted_tools_unchanged() {
+        let tools = json!([
+            { "type": "tool_search", "max_num_results": 3, "search_context_size": "medium" },
+            {
+                "type": "mcp",
+                "server_label": "docs",
+                "server_url": "https://mcp.example.com",
+                "defer_loading": true,
+                "require_approval": "never",
+            },
+            {
+                "type": "computer_use_preview",
+                "display_width": 1024,
+                "display_height": 768,
+                "environment": "browser",
+            },
+        ]);
+        assert_eq!(cleanup(tools.clone()), tools);
+    }
+
+    #[test]
+    fn treats_array_parameters_as_non_records_and_leaves_tool_unchanged() {
+        let tools = json!([{
+            "type": "function",
+            "function": { "name": "array-params", "parameters": [] },
+        }]);
+        assert_eq!(cleanup(tools.clone()), tools);
+    }
+
+    #[test]
+    fn filters_required_array_to_only_existing_properties() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "a": { "type": "string" } },
+            "required": ["a", "b", "c"],
+        })));
+        assert_eq!(parameters_of(&cleaned)["required"], json!(["a"]));
+    }
+
+    #[test]
+    fn removes_required_array_when_no_valid_properties_remain() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "a": { "type": "string" } },
+            "required": ["b", "c"],
+        })));
+        assert!(parameters_of(&cleaned).get("required").is_none());
+    }
+
+    #[test]
+    fn keeps_required_array_unchanged_when_all_required_properties_exist() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "a": { "type": "string" }, "b": { "type": "number" } },
+            "required": ["a", "b"],
+        })));
+        assert_eq!(parameters_of(&cleaned)["required"], json!(["a", "b"]));
+    }
+
+    #[test]
+    fn injects_placeholder_for_empty_object_parameters() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {},
+        })));
+        assert_eq!(
+            parameters_of(&cleaned)["properties"]["_placeholder"],
+            json!({
+                "type": "boolean",
+                "description": "This property is a placeholder and should be ignored.",
+            })
+        );
+    }
+
+    #[test]
+    fn flattens_any_of_with_const_values_into_enum() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "status": {
+                    "anyOf": [{ "const": "active" }, { "const": "inactive" }, { "const": "pending" }],
+                },
+            },
+        })));
+        let status = &parameters_of(&cleaned)["properties"]["status"];
+        assert!(status.get("anyOf").is_none());
+        assert_eq!(status["enum"], json!(["active", "inactive", "pending"]));
+        assert_eq!(status["type"], json!("string"));
+    }
+
+    #[test]
+    fn infers_number_and_boolean_types_for_const_enums() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "level": { "anyOf": [{ "const": 1 }, { "const": 2 }, { "const": 3 }] },
+                "enabled": { "anyOf": [{ "const": true }, { "const": false }] },
+            },
+        })));
+        let level = &parameters_of(&cleaned)["properties"]["level"];
+        assert_eq!(level["enum"], json!([1, 2, 3]));
+        assert_eq!(level["type"], json!("number"));
+        let enabled = &parameters_of(&cleaned)["properties"]["enabled"];
+        assert_eq!(enabled["enum"], json!([true, false]));
+        assert_eq!(enabled["type"], json!("boolean"));
+    }
+
+    #[test]
+    fn does_not_infer_type_when_any_of_first_value_is_object_or_null() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "config": { "anyOf": [{ "const": { "nested": true } }, { "const": { "nested": false } }] },
+                "nullable": { "anyOf": [{ "const": null }, { "const": "value" }] },
+            },
+        })));
+        let config = &parameters_of(&cleaned)["properties"]["config"];
+        assert!(config.get("anyOf").is_none());
+        assert_eq!(config["enum"], json!([{ "nested": true }, { "nested": false }]));
+        assert!(config.get("type").is_none());
+        let nullable = &parameters_of(&cleaned)["properties"]["nullable"];
+        assert_eq!(nullable["enum"], json!([null, "value"]));
+        assert!(nullable.get("type").is_none());
+    }
+
+    #[test]
+    fn preserves_existing_type_when_any_of_has_const_values() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "status": { "type": "string", "anyOf": [{ "const": "a" }, { "const": "b" }] },
+            },
+        })));
+        let status = &parameters_of(&cleaned)["properties"]["status"];
+        assert!(status.get("anyOf").is_none());
+        assert_eq!(status["enum"], json!(["a", "b"]));
+        assert_eq!(status["type"], json!("string"));
+    }
+
+    #[test]
+    fn does_not_flatten_empty_any_of_or_mixed_any_of() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "empty": { "anyOf": [] },
+                "mixed": { "anyOf": [{ "const": "a" }, { "type": "string" }] },
+            },
+        })));
+        let empty = &parameters_of(&cleaned)["properties"]["empty"];
+        assert_eq!(empty["anyOf"], json!([]));
+        assert!(empty.get("enum").is_none());
+        let mixed = &parameters_of(&cleaned)["properties"]["mixed"];
+        assert!(mixed.get("anyOf").is_some());
+        assert!(mixed.get("enum").is_none());
+    }
+
+    #[test]
+    fn flattens_nullable_types_to_single_type_with_description() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "name": { "type": ["string", "null"], "description": "User name" },
+            },
+        })));
+        let name = &parameters_of(&cleaned)["properties"]["name"];
+        assert_eq!(name["type"], json!("string"));
+        assert_eq!(name["description"], json!("User name (nullable)"));
+    }
+
+    #[test]
+    fn does_not_duplicate_nullable_annotation() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "name": { "type": ["string", "null"], "description": "This is nullable already" },
+            },
+        })));
+        assert_eq!(
+            parameters_of(&cleaned)["properties"]["name"]["description"],
+            json!("This is nullable already")
+        );
+    }
+
+    #[test]
+    fn handles_nullable_type_without_description() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "noDesc": { "type": ["string", "null"] } },
+        })));
+        let no_desc = &parameters_of(&cleaned)["properties"]["noDesc"];
+        assert_eq!(no_desc["type"], json!("string"));
+        assert_eq!(no_desc["description"], json!("(nullable)"));
+    }
+
+    #[test]
+    fn handles_nullable_type_array_with_only_null_type() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "onlyNull": { "type": ["null"] } },
+        })));
+        assert_eq!(
+            parameters_of(&cleaned)["properties"]["onlyNull"]["type"],
+            json!(["null"])
+        );
+    }
+
+    #[test]
+    fn flattens_type_array_without_null_to_single_type() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "field": { "type": ["string", "number"] } },
+        })));
+        let field = &parameters_of(&cleaned)["properties"]["field"];
+        assert_eq!(field["type"], json!("string"));
+        assert!(field.get("description").is_none());
+    }
+
+    #[test]
+    fn removes_unsupported_keywords() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": { "a": { "type": "string" } },
+            "additionalProperties": false,
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "title": "TestParams",
+        })));
+        let params = parameters_of(&cleaned);
+        assert!(params.get("additionalProperties").is_none());
+        assert!(params.get("$schema").is_none());
+        assert!(params.get("title").is_none());
+    }
+
+    #[test]
+    fn recursively_cleans_nested_properties() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "nested": {
+                    "type": "object",
+                    "properties": { "inner": { "type": ["number", "null"] } },
+                    "additionalProperties": true,
+                },
+            },
+        })));
+        let nested = &parameters_of(&cleaned)["properties"]["nested"];
+        assert!(nested.get("additionalProperties").is_none());
+        assert_eq!(nested["properties"]["inner"]["type"], json!("number"));
+    }
+
+    #[test]
+    fn recursively_cleans_array_items() {
+        let cleaned = cleanup(function_tool(json!({
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": { "val": { "type": ["string", "null"] } },
+                        "additionalProperties": false,
+                    },
+                },
+            },
+        })));
+        let item_schema = &parameters_of(&cleaned)["properties"]["items"]["items"];
+        assert!(item_schema.get("additionalProperties").is_none());
+        assert_eq!(item_schema["properties"]["val"]["type"], json!("string"));
+    }
+
+    #[test]
+    fn handles_tool_without_parameters_property() {
+        let tools = json!([{ "type": "function", "function": { "name": "simple_action" } }]);
+        let cleaned = cleanup(tools);
+        assert_eq!(cleaned[0]["function"]["name"], json!("simple_action"));
+        assert!(cleaned[0]["function"].get("parameters").is_none());
+    }
+
+    #[test]
+    fn recursively_cleans_nested_function_tools_inside_namespace_bundles() {
+        let cleaned = cleanup(json!([
+            {
+                "type": "namespace",
+                "name": "search_bundle",
+                "tools": [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "lookup",
+                            "parameters": {
+                                "type": "object",
+                                "properties": {},
+                                "additionalProperties": false,
+                            },
+                        },
+                    },
+                    { "type": "tool_search", "max_num_results": 2 },
+                ],
+            },
+        ]));
+        let namespace_tools = cleaned[0]["tools"].as_array().unwrap();
+        let nested_params = &namespace_tools[0]["function"]["parameters"];
+        assert!(nested_params.get("additionalProperties").is_none());
+        assert_eq!(
+            nested_params["properties"],
+            json!({
+                "_placeholder": {
+                    "type": "boolean",
+                    "description": "This property is a placeholder and should be ignored.",
+                }
+            })
+        );
+        assert_eq!(
+            namespace_tools[1],
+            json!({ "type": "tool_search", "max_num_results": 2 })
+        );
+    }
+}
diff --git a/crates/request/src/transformer.rs b/crates/request/src/transformer.rs
new file mode 100644
index 000000000..f07322f2c
--- /dev/null
+++ b/crates/request/src/transformer.rs
@@ -0,0 +1,3146 @@
+//! Port of `lib/request/request-transformer.ts` — the Responses request-body
+//! transformation (spec 06 §2): model normalization, per-model config
+//! resolution, background-mode gating, fast-session tuning/trimming, tool
+//! sanitization, input surgery, reasoning/verbosity/include resolution.
+//!
+//! ## Prompt seam (Rust-only shape, documented)
+//!
+//! The TS transformer imports `CODEX_HOST_BRIDGE`, `TOOL_REMAP_MESSAGE`, and
+//! `getHostCodexPrompt()` from `lib/prompts/*` and is `async` solely because
+//! of that host-prompt fetch. Here [`TransformPrompts::default`] carries the
+//! real bridge/remap constants, [`transform_request_body`] is synchronous
+//! over a pre-fetched `cached_host_prompt`, and
+//! [`transform_request_body_fetching_host_prompt`] /
+//! [`filter_host_system_prompts`] are the async TS-parity wrappers that fetch
+//! the cached host prompt (fetch failure → `None`, exactly the TS catch).
+//! The TS positional/named dual-call overload collapses into the single
+//! [`TransformRequestBodyParams`] struct; its `TypeError("…requires
+//! body/codexInstructions")` guards are structurally unrepresentable.
+
+use std::collections::HashSet;
+use std::sync::LazyLock;
+
+use cma_core::constants::ModelReasoningEffort;
+use cma_core::logger::{log_debug, log_warn};
+use cma_core::model_family::ModelFamily;
+use cma_core::types::{
+    ConfigOptions, InputItem, ModelVariantConfig, ReasoningConfig, ReasoningSummary, RequestBody,
+    RequestToolDefinition, UserConfig,
+};
+use regex::Regex;
+use serde_json::{Map, Value, json};
+
+use crate::input_utils;
+use crate::model_map;
+use crate::tool_utils::cleanup_tool_definitions;
+
+// TS re-exports from `helpers/input-utils.js`.
+pub use crate::input_utils::{filter_host_system_prompts_with_cached_prompt, is_host_system_prompt};
+
+/// TS `FastSessionStrategy = "hybrid" | "always"`.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum FastSessionStrategy {
+    #[default]
+    Hybrid,
+    Always,
+}
+
+impl FastSessionStrategy {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            FastSessionStrategy::Hybrid => "hybrid",
+            FastSessionStrategy::Always => "always",
+        }
+    }
+
+    /// Exact-match parse of the TS literal.
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "hybrid" => Some(FastSessionStrategy::Hybrid),
+            "always" => Some(FastSessionStrategy::Always),
+            _ => None,
+        }
+    }
+}
+
+/// TS `CollaborationMode`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum CollaborationMode {
+    Plan,
+    Default,
+    Unknown,
+}
+
+impl CollaborationMode {
+    const fn as_str(self) -> &'static str {
+        match self {
+            CollaborationMode::Plan => "plan",
+            CollaborationMode::Default => "default",
+            CollaborationMode::Unknown => "unknown",
+        }
+    }
+}
+
+/// Prompt inputs the TS transformer pulled from `lib/prompts/*` internally
+/// (see the module docs). [`Default`] carries the real bridge/remap constants
+/// and no cached host prompt.
+#[derive(Debug, Clone)]
+pub struct TransformPrompts<'a> {
+    /// TS `CODEX_HOST_BRIDGE` (`lib/prompts/codex-host-bridge.ts`).
+    pub codex_host_bridge: &'a str,
+    /// TS `TOOL_REMAP_MESSAGE` (`lib/prompts/codex.ts`).
+    pub tool_remap_message: &'a str,
+    /// TS `await getHostCodexPrompt()` — `None` when the fetch failed (the TS
+    /// catch falls back to signature-only detection).
+    pub cached_host_prompt: Option<String>,
+}
+
+impl Default for TransformPrompts<'_> {
+    fn default() -> Self {
+        TransformPrompts {
+            codex_host_bridge: crate::prompts::host_bridge::CODEX_HOST_BRIDGE,
+            tool_remap_message: crate::prompts::codex::TOOL_REMAP_MESSAGE,
+            cached_host_prompt: None,
+        }
+    }
+}
+
+/// TS `TransformRequestBodyParams` (+ the positional-overload defaults).
+#[derive(Debug, Clone)]
+pub struct TransformRequestBodyParams<'a> {
+    pub body: RequestBody,
+    pub codex_instructions: &'a str,
+    /// `None` → `{ global: {}, models: {} }`.
+    pub user_config: Option<&'a UserConfig>,
+    /// TS default `true`.
+    pub codex_mode: bool,
+    /// TS default `false`.
+    pub fast_session: bool,
+    /// TS default `"hybrid"`.
+    pub fast_session_strategy: FastSessionStrategy,
+    /// TS default `30`.
+    pub fast_session_max_input_items: i64,
+    /// TS default `false`.
+    pub defer_fast_session_input_trimming: bool,
+    /// TS default `false`.
+    pub allow_background_responses: bool,
+    /// Rust-only prompt seam (see module docs).
+    pub prompts: TransformPrompts<'a>,
+}
+
+impl<'a> TransformRequestBodyParams<'a> {
+    /// Params with the exact TS positional-call defaults.
+    pub fn new(body: RequestBody, codex_instructions: &'a str) -> Self {
+        TransformRequestBodyParams {
+            body,
+            codex_instructions,
+            user_config: None,
+            codex_mode: true,
+            fast_session: false,
+            fast_session_strategy: FastSessionStrategy::Hybrid,
+            fast_session_max_input_items: 30,
+            defer_fast_session_input_trimming: false,
+            allow_background_responses: false,
+            prompts: TransformPrompts::default(),
+        }
+    }
+}
+
+/// Background-mode violations. `Display` is the FROZEN TS error message —
+/// downstream (`fetch-helpers`) matches on the `"Responses background mode"`
+/// prefix to decide rethrow-vs-swallow.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TransformRequestBodyError {
+    BackgroundResponsesDisabled,
+    BackgroundRequiresStore,
+}
+
+impl std::fmt::Display for TransformRequestBodyError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            TransformRequestBodyError::BackgroundResponsesDisabled => f.write_str(
+                "Responses background mode is disabled. Enable pluginConfig.backgroundResponses or CODEX_AUTH_BACKGROUND_RESPONSES=1 to opt in.",
+            ),
+            TransformRequestBodyError::BackgroundRequiresStore => f.write_str(
+                "Responses background mode requires store=true and cannot be combined with stateless store=false routing.",
+            ),
+        }
+    }
+}
+
+impl std::error::Error for TransformRequestBodyError {}
+
+const PLAN_MODE_ONLY_TOOLS: [&str; 1] = ["request_user_input"];
+
+/// TS `normalizeModel` — thin wrapper over the shared catalog resolver.
+pub fn normalize_model(model: Option<&str>) -> &'static str {
+    model_map::resolve_normalized_model(model)
+}
+
+// ---------------------------------------------------------------------------
+// Variant-suffix pattern (TS `VARIANT_SUFFIX_PATTERN`)
+// ---------------------------------------------------------------------------
+
+/// TS `REASONING_EFFORTS.filter(e => e !== "max")` — the unguarded suffix
+/// alternation (note `ultra` IS here; only `max` needs the codex lookbehind).
+const UNGUARDED_VARIANT_SUFFIXES: [ModelReasoningEffort; 7] = [
+    ModelReasoningEffort::None,
+    ModelReasoningEffort::Minimal,
+    ModelReasoningEffort::Low,
+    ModelReasoningEffort::Medium,
+    ModelReasoningEffort::High,
+    ModelReasoningEffort::Xhigh,
+    ModelReasoningEffort::Ultra,
+];
+
+/// `name` ends with `-{effort}` (ASCII case-insensitive) → the base slice.
+fn strip_dashed_suffix_ignore_ascii_case<'a>(name: &'a str, effort: &str) -> Option<&'a str> {
+    let dashed_len = effort.len() + 1;
+    if name.len() < dashed_len {
+        return None;
+    }
+    let tail = &name.as_bytes()[name.len() - dashed_len..];
+    if tail[0] == b'-' && tail[1..].eq_ignore_ascii_case(effort.as_bytes()) {
+        // tail starts with ASCII '-', so the cut is a valid char boundary.
+        Some(&name[..name.len() - dashed_len])
+    } else {
+        None
+    }
+}
+
+fn ends_with_ignore_ascii_case(name: &str, suffix: &str) -> bool {
+    name.len() >= suffix.len()
+        && name.as_bytes()[name.len() - suffix.len()..].eq_ignore_ascii_case(suffix.as_bytes())
+}
+
+/// TS `VARIANT_SUFFIX_PATTERN` =
+/// `/(?:-(none|minimal|low|medium|high|xhigh|ultra)|(?<!codex)-(max))$/i`.
+///
+/// The `regex` crate lacks lookbehind, so the `(?<!codex)-max` alternative is
+/// hand-rolled: `-max` strips ONLY when the preceding text does not end with
+/// `codex` (case-insensitive) — `gpt-5.1-codex-max` is a model id, not Codex
+/// at `max` effort, while `gpt-5.6-sol-max` still parses `max` and
+/// `gpt-5-codex-low` / `gpt-5-codex-ultra` still parse their suffix (no guard
+/// on the first alternation).
+///
+/// Returns `(base_without_suffix, matched_effort)`; at most ONE suffix is
+/// stripped (the TS regex is `$`-anchored and non-global).
+fn split_variant_suffix(name: &str) -> (&str, Option<ModelReasoningEffort>) {
+    for effort in UNGUARDED_VARIANT_SUFFIXES {
+        if let Some(base) = strip_dashed_suffix_ignore_ascii_case(name, effort.as_str()) {
+            return (base, Some(effort));
+        }
+    }
+    if let Some(base) = strip_dashed_suffix_ignore_ascii_case(name, "max")
+        && !ends_with_ignore_ascii_case(base, "codex")
+    {
+        return (base, Some(ModelReasoningEffort::Max));
+    }
+    (name, None)
+}
+
+// ---------------------------------------------------------------------------
+// getModelConfig
+// ---------------------------------------------------------------------------
+
+/// JS-spread merge of [`ConfigOptions`] layers — later layers override only
+/// the fields they actually carry; `extra` keys merge key-wise.
+fn merge_config_options(layers: &[&ConfigOptions]) -> ConfigOptions {
+    let mut merged = ConfigOptions::default();
+    for layer in layers {
+        if layer.reasoning_effort.is_some() {
+            merged.reasoning_effort = layer.reasoning_effort.clone();
+        }
+        if layer.reasoning_summary.is_some() {
+            merged.reasoning_summary = layer.reasoning_summary.clone();
+        }
+        if layer.text_verbosity.is_some() {
+            merged.text_verbosity = layer.text_verbosity.clone();
+        }
+        if layer.prompt_cache_retention.is_some() {
+            merged.prompt_cache_retention = layer.prompt_cache_retention.clone();
+        }
+        if layer.include.is_some() {
+            merged.include = layer.include.clone();
+        }
+        for (key, value) in &layer.extra {
+            merged.extra.insert(key.clone(), value.clone());
+        }
+    }
+    merged
+}
+
+/// TS variant entry minus its `disabled` key.
+fn variant_to_config_options(variant: &ModelVariantConfig) -> ConfigOptions {
+    ConfigOptions {
+        reasoning_effort: variant.reasoning_effort.clone(),
+        reasoning_summary: variant.reasoning_summary.clone(),
+        text_verbosity: variant.text_verbosity.clone(),
+        prompt_cache_retention: variant.prompt_cache_retention.clone(),
+        include: variant.include.clone(),
+        extra: variant.extra.clone(),
+    }
+}
+
+/// TS `getModelConfig` — merges global options with model-specific options
+/// (model-specific wins), honoring exact per-model keys first, then base-model
+/// keys (with variant merging for `-low`/`-xhigh`/… suffixed requests).
+pub fn get_model_config(model_name: &str, user_config: Option<&UserConfig>) -> ConfigOptions {
+    let default_config = UserConfig::default();
+    let user_config = user_config.unwrap_or(&default_config);
+    let global_options = &user_config.global;
+    let models = &user_config.models;
+
+    let stripped_model_name = model_map::strip_provider_prefix(model_name);
+    let normalized_model_name = normalize_model(Some(stripped_model_name));
+    let (base_model_name, requested_variant) = split_variant_suffix(stripped_model_name);
+    let normalized_base_model_name = normalize_model(Some(base_model_name));
+
+    // 1) Honor exact per-model keys first (including variant-specific keys).
+    let direct_entry = [model_name, stripped_model_name]
+        .iter()
+        .find_map(|key| models.get(*key));
+    if let Some(entry) = direct_entry
+        && let Some(options) = &entry.options
+    {
+        return merge_config_options(&[global_options, options]);
+    }
+
+    // 2) Resolve to base model config (provider-prefixed names + aliases).
+    let base_entry = [
+        base_model_name,
+        normalized_base_model_name,
+        normalized_model_name,
+    ]
+    .iter()
+    .find_map(|key| models.get(*key));
+    let default_options = ConfigOptions::default();
+    let base_options = base_entry
+        .and_then(|entry| entry.options.as_ref())
+        .unwrap_or(&default_options);
+
+    // 3) Variant options from the base entry (minus `disabled`).
+    let variant_options = requested_variant
+        .and_then(|variant| {
+            base_entry?
+                .variants
+                .as_ref()?
+                .get(variant.as_str())?
+                .as_ref()
+        })
+        .map(variant_to_config_options);
+
+    match &variant_options {
+        Some(variant) => merge_config_options(&[global_options, base_options, variant]),
+        None => merge_config_options(&[global_options, base_options]),
+    }
+}
+
+/// TS `applyFastSessionDefaults` — `global.reasoningEffort ??= "low"`,
+/// `global.textVerbosity ??= "low"` on a copy (explicit user values win).
+pub fn apply_fast_session_defaults(user_config: &UserConfig) -> UserConfig {
+    let mut result = user_config.clone();
+    if result.global.reasoning_effort.is_none() {
+        result.global.reasoning_effort = Some("low".to_string());
+    }
+    if result.global.text_verbosity.is_none() {
+        result.global.text_verbosity = Some("low".to_string());
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Reasoning config
+// ---------------------------------------------------------------------------
+
+/// TS `REASONING_FALLBACKS`.
+fn reasoning_fallbacks(effort: ModelReasoningEffort) -> &'static [ModelReasoningEffort] {
+    use ModelReasoningEffort as E;
+    match effort {
+        E::None => &[E::None, E::Low, E::Minimal, E::Medium, E::High, E::Xhigh],
+        E::Minimal => &[E::Minimal, E::Low, E::None, E::Medium, E::High, E::Xhigh],
+        E::Low => &[E::Low, E::Minimal, E::None, E::Medium, E::High, E::Xhigh],
+        E::Medium => &[E::Medium, E::Low, E::High, E::Minimal, E::None, E::Xhigh],
+        E::High => &[E::High, E::Medium, E::Xhigh, E::Low, E::Minimal, E::None],
+        E::Xhigh => &[E::Xhigh, E::High, E::Medium, E::Low, E::Minimal, E::None],
+        // `max`/`ultra` only exist on GPT-5.6 — step down one rung at a time.
+        E::Max => &[E::Max, E::Xhigh, E::High, E::Medium, E::Low, E::Minimal, E::None],
+        E::Ultra => &[
+            E::Ultra,
+            E::Max,
+            E::Xhigh,
+            E::High,
+            E::Medium,
+            E::Low,
+            E::Minimal,
+            E::None,
+        ],
+    }
+}
+
+/// TS `coerceReasoningEffort` — exact fallback-table walk with the two frozen
+/// warn messages. `requested_raw = None` means the config carried no effort
+/// (→ profile default, which every profile supports); an unparseable string
+/// behaves like the TS `REASONING_FALLBACKS[effort] ?? [defaultEffort]` miss.
+fn coerce_reasoning_effort(
+    model_name: &str,
+    requested_raw: Option<&str>,
+    supported: &[ModelReasoningEffort],
+    default_effort: ModelReasoningEffort,
+) -> ModelReasoningEffort {
+    let (requested_parsed, requested_label): (Option<ModelReasoningEffort>, &str) =
+        match requested_raw {
+            None => (Some(default_effort), default_effort.as_str()),
+            Some(raw) => (ModelReasoningEffort::parse(raw), raw),
+        };
+
+    if let Some(effort) = requested_parsed
+        && supported.contains(&effort)
+    {
+        return effort;
+    }
+
+    let default_only = [default_effort];
+    let fallback_order: &[ModelReasoningEffort] = match requested_parsed {
+        Some(effort) => reasoning_fallbacks(effort),
+        None => &default_only,
+    };
+    for candidate in fallback_order {
+        if supported.contains(candidate) {
+            log_warn(
+                "Coercing unsupported reasoning effort for model",
+                Some(&json!({
+                    "model": model_name,
+                    "requestedEffort": requested_label,
+                    "effectiveEffort": candidate.as_str(),
+                })),
+            );
+            return *candidate;
+        }
+    }
+
+    log_warn(
+        "Falling back to default reasoning effort for model",
+        Some(&json!({
+            "model": model_name,
+            "requestedEffort": requested_label,
+            "effectiveEffort": default_effort.as_str(),
+        })),
+    );
+    default_effort
+}
+
+/// TS `sanitizeReasoningSummary` — lowercased membership in
+/// {auto, concise, detailed}, everything else (incl. empty/absent) → `auto`.
+fn sanitize_reasoning_summary(summary: Option<&str>) -> ReasoningSummary {
+    let Some(summary) = summary.filter(|s| !s.is_empty()) else {
+        return ReasoningSummary::Auto;
+    };
+    match summary.to_lowercase().as_str() {
+        "concise" => ReasoningSummary::Concise,
+        "detailed" => ReasoningSummary::Detailed,
+        _ => ReasoningSummary::Auto,
+    }
+}
+
+/// TS `getReasoningConfig` — profile default + coercion; `ultra` → `max` on
+/// the wire (the API never sees `ultra`).
+pub fn get_reasoning_config(
+    model_name: Option<&str>,
+    user_config: &ConfigOptions,
+) -> ReasoningConfig {
+    let profile = model_map::get_model_profile(model_name);
+    let coerced = coerce_reasoning_effort(
+        profile.normalized_model,
+        user_config.reasoning_effort.as_deref(),
+        profile.supported_reasoning_efforts,
+        profile.default_reasoning_effort,
+    );
+    ReasoningConfig {
+        effort: coerced.to_wire(),
+        summary: sanitize_reasoning_summary(user_config.reasoning_summary.as_deref()),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Input filtering & fast-session machinery
+// ---------------------------------------------------------------------------
+
+/// TS `filterInput` — drop `item_reference` items (AI-SDK construct) and,
+/// when `strip_ids`, remove the `id` from every remaining item. `None` input
+/// passes through (TS non-array passthrough).
+pub fn filter_input(input: Option<Vec<InputItem>>, strip_ids: bool) -> Option<Vec<InputItem>> {
+    let input = input?;
+    Some(
+        input
+            .into_iter()
+            .filter_map(|mut item| {
+                if item.kind.as_deref() == Some("item_reference") {
+                    return None;
+                }
+                if strip_ids {
+                    item.id = None;
+                }
+                Some(item)
+            })
+            .collect(),
+    )
+}
+
+/// TS `extractMessageText` — string content as-is; array content joins the
+/// string elements / `text` fields (empties dropped) with `"\n"`.
+fn extract_message_text(content: Option<&Value>) -> String {
+    match content {
+        Some(Value::String(text)) => text.clone(),
+        Some(Value::Array(parts)) => parts
+            .iter()
+            .filter_map(|part| {
+                let text = match part {
+                    Value::String(text) => text.clone(),
+                    Value::Object(obj) => obj
+                        .get("text")
+                        .and_then(Value::as_str)
+                        .unwrap_or("")
+                        .to_string(),
+                    _ => String::new(),
+                };
+                if text.is_empty() { None } else { Some(text) }
+            })
+            .collect::<Vec<_>>()
+            .join("\n"),
+        _ => String::new(),
+    }
+}
+
+static LIST_MARKER_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"(?m)(?:^|\n)\s*(?:[-*]|[0-9]+\.)\s+\S").expect("static regex"));
+static TABLE_ROW_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\|.+\|").expect("static regex"));
+static URL_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?i)https?://").expect("static regex"));
+
+/// TS `isTrivialLatestPrompt`.
+fn is_trivial_latest_prompt(text: &str) -> bool {
+    let normalized = text.trim();
+    if normalized.is_empty() {
+        return false;
+    }
+    if normalized.chars().count() > 220 {
+        return false;
+    }
+    if normalized.contains('\n') {
+        return false;
+    }
+    if normalized.contains("```") {
+        return false;
+    }
+    if LIST_MARKER_RE.is_match(normalized) {
+        return false;
+    }
+    if URL_RE.is_match(normalized) {
+        return false;
+    }
+    if TABLE_ROW_RE.is_match(normalized) {
+        return false;
+    }
+    true
+}
+
+/// TS `isStructurallyComplexPrompt`.
+fn is_structurally_complex_prompt(text: &str) -> bool {
+    let normalized = text.trim();
+    if normalized.is_empty() {
+        return false;
+    }
+    if normalized.contains("```") {
+        return true;
+    }
+    let line_count = normalized
+        .split('\n')
+        .map(|line| line.strip_suffix('\r').unwrap_or(line))
+        .filter(|line| !line.is_empty())
+        .count();
+    if line_count >= 3 {
+        return true;
+    }
+    if LIST_MARKER_RE.is_match(normalized) {
+        return true;
+    }
+    if TABLE_ROW_RE.is_match(normalized) {
+        return true;
+    }
+    false
+}
+
+/// TS `isComplexFastSessionRequest` — lookback window of
+/// `max(12, floor(maxItems/2))` recent items; any tool traffic in the window
+/// is complex; a trivial LATEST user prompt short-circuits to NOT complex;
+/// else complex iff any of the last 3 user texts is structurally complex.
+fn is_complex_fast_session_request(body: &RequestBody, max_items: i64) -> bool {
+    let empty: [InputItem; 0] = [];
+    let input: &[InputItem] = body.input.as_deref().unwrap_or(&empty);
+    let lookback = ((max_items as f64) / 2.0).floor().max(12.0) as usize;
+    let start = input.len().saturating_sub(lookback);
+
+    let mut user_texts: Vec<String> = Vec::new();
+    for item in &input[start..] {
+        if matches!(
+            item.kind.as_deref(),
+            Some("function_call") | Some("function_call_output")
+        ) {
+            return true;
+        }
+        let role = item
+            .role
+            .as_deref()
+            .map(str::to_lowercase)
+            .unwrap_or_default();
+        if role != "user" {
+            continue;
+        }
+        let text = extract_message_text(item.content.as_ref());
+        if text.is_empty() {
+            continue;
+        }
+        user_texts.push(text);
+    }
+
+    if user_texts.is_empty() {
+        return false;
+    }
+    if let Some(latest) = user_texts.last()
+        && is_trivial_latest_prompt(latest)
+    {
+        return false;
+    }
+    let recent_start = user_texts.len().saturating_sub(3);
+    user_texts[recent_start..]
+        .iter()
+        .any(|text| is_structurally_complex_prompt(text))
+}
+
+/// TS `getLatestUserText`.
+fn get_latest_user_text(input: Option<&[InputItem]>) -> Option<String> {
+    let input = input?;
+    for item in input.iter().rev() {
+        let role = item
+            .role
+            .as_deref()
+            .map(str::to_lowercase)
+            .unwrap_or_default();
+        if role != "user" {
+            continue;
+        }
+        let text = extract_message_text(item.content.as_ref());
+        if !text.is_empty() {
+            return Some(text);
+        }
+    }
+    None
+}
+
+/// The `trim` half of [`FastSessionInputTrimPlan`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FastSessionTrimSettings {
+    pub max_items: i64,
+    pub prefer_latest_user_only: bool,
+}
+
+/// TS `FastSessionInputTrimPlan`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FastSessionInputTrimPlan {
+    pub should_apply: bool,
+    pub is_trivial_turn: bool,
+    pub trim: Option<FastSessionTrimSettings>,
+}
+
+/// TS `resolveFastSessionInputTrimPlan`.
+pub fn resolve_fast_session_input_trim_plan(
+    body: &RequestBody,
+    fast_session: bool,
+    fast_session_strategy: FastSessionStrategy,
+    fast_session_max_input_items: i64,
+) -> FastSessionInputTrimPlan {
+    let should_apply = fast_session
+        && (fast_session_strategy == FastSessionStrategy::Always
+            || !is_complex_fast_session_request(body, fast_session_max_input_items));
+    let latest_user_text = get_latest_user_text(body.input.as_deref());
+    let is_trivial_turn = is_trivial_latest_prompt(latest_user_text.as_deref().unwrap_or(""));
+    FastSessionInputTrimPlan {
+        should_apply,
+        is_trivial_turn,
+        trim: should_apply.then_some(FastSessionTrimSettings {
+            max_items: fast_session_max_input_items,
+            prefer_latest_user_only: should_apply && is_trivial_turn,
+        }),
+    }
+}
+
+/// TS `trimInputForFastSession` — keeps a small leading developer/system
+/// context plus the most recent items; the `prefer_latest_user_only` path
+/// keeps only a short head instruction and the last user item.
+pub fn trim_input_for_fast_session(
+    input: Option<Vec<InputItem>>,
+    max_items: i64,
+    prefer_latest_user_only: bool,
+) -> Option<Vec<InputItem>> {
+    let input = input?;
+    const MAX_HEAD_INSTRUCTION_CHARS: usize = 1200;
+    const MAX_HEAD_INSTRUCTION_CHARS_TRIVIAL: usize = 400;
+
+    if prefer_latest_user_only {
+        let mut keep_indexes: HashSet<usize> = HashSet::new();
+
+        // First developer/system item anywhere (exact-case roles, TS parity);
+        // scanning does NOT stop at user/assistant items.
+        for (index, item) in input.iter().enumerate() {
+            let role = item.role.as_deref().unwrap_or("");
+            if role == "developer" || role == "system" {
+                let head_text = extract_message_text(item.content.as_ref());
+                if head_text.chars().count() <= MAX_HEAD_INSTRUCTION_CHARS_TRIVIAL {
+                    keep_indexes.insert(index);
+                }
+                break;
+            }
+        }
+
+        // Last user item (lowercased role here — TS parity).
+        for (index, item) in input.iter().enumerate().rev() {
+            let role = item
+                .role
+                .as_deref()
+                .map(str::to_lowercase)
+                .unwrap_or_default();
+            if role == "user" {
+                keep_indexes.insert(index);
+                break;
+            }
+        }
+
+        let compacted: Vec<InputItem> = input
+            .iter()
+            .enumerate()
+            .filter(|(index, _)| keep_indexes.contains(index))
+            .map(|(_, item)| item.clone())
+            .collect();
+        if !compacted.is_empty() {
+            return Some(compacted);
+        }
+    }
+
+    // General path.
+    let safe_max = max_items.max(8) as usize; // Math.max(8, Math.floor(maxItems))
+    let mut keep_indexes: HashSet<usize> = HashSet::new();
+    let mut excluded_head_indexes: HashSet<usize> = HashSet::new();
+
+    let mut kept_head = 0usize;
+    for (index, item) in input.iter().enumerate() {
+        if kept_head >= 2 {
+            break;
+        }
+        let role = item.role.as_deref().unwrap_or("");
+        if role == "developer" || role == "system" {
+            let head_text = extract_message_text(item.content.as_ref());
+            if head_text.chars().count() <= MAX_HEAD_INSTRUCTION_CHARS {
+                keep_indexes.insert(index);
+                kept_head += 1;
+            } else {
+                excluded_head_indexes.insert(index);
+            }
+            continue;
+        }
+        break;
+    }
+
+    let tail_start = input.len().saturating_sub(safe_max);
+    for index in tail_start..input.len() {
+        if excluded_head_indexes.contains(&index) {
+            continue;
+        }
+        keep_indexes.insert(index);
+    }
+
+    let trimmed: Vec<InputItem> = input
+        .iter()
+        .enumerate()
+        .filter(|(index, _)| keep_indexes.contains(index))
+        .map(|(_, item)| item.clone())
+        .collect();
+    if trimmed.is_empty() {
+        return Some(input);
+    }
+    if (input.len() as i64) <= max_items && excluded_head_indexes.is_empty() {
+        return Some(input);
+    }
+    if trimmed.len() <= safe_max {
+        return Some(trimmed);
+    }
+
+    // Kept head items are always the LOWEST kept indexes, so they occupy the
+    // first `kept_head` entries of `trimmed`. Reserve budget for exactly that
+    // many (recounting kept indexes below tail_start would miss a head
+    // instruction that ALSO falls inside the tail window — see the TS
+    // in-code comment about the overlap bug).
+    let tail_budget = (safe_max - kept_head).max(1);
+    let mut result: Vec<InputItem> = trimmed[..kept_head].to_vec();
+    result.extend_from_slice(&trimmed[trimmed.len() - tail_budget..]);
+    Some(result)
+}
+
+/// TS fast-instruction limits + frozen compaction suffix.
+const FAST_INSTRUCTION_SUFFIX: &str = "\n\n[Fast session mode: keep answers concise, direct, and action-oriented. Do not output internal planning labels such as \"Thinking:\".]";
+
+/// TS `compactInstructionsForFastSession` — 320-char (trivial) / 900-char
+/// budget; prefers cutting at the last newline at/before the limit when that
+/// index is ≥ 180, else hard-cuts at the limit; appends the frozen suffix.
+fn compact_instructions_for_fast_session(instructions: &str, is_trivial_turn: bool) -> String {
+    let normalized = instructions.trim();
+    if normalized.is_empty() {
+        return instructions.to_string();
+    }
+    let limit = if is_trivial_turn { 320 } else { 900 };
+    let chars: Vec<char> = normalized.chars().collect();
+    if chars.len() <= limit {
+        return instructions.to_string();
+    }
+    // JS `lastIndexOf("\n", limit)` — last newline at index ≤ limit.
+    let split_index = (0..=limit).rev().find(|&index| chars[index] == '\n');
+    let safe_cutoff = match split_index {
+        Some(index) if index >= 180 => index,
+        _ => limit,
+    };
+    let compacted: String = chars[..safe_cutoff].iter().collect();
+    format!("{}{FAST_INSTRUCTION_SUFFIX}", compacted.trim_end())
+}
+
+// ---------------------------------------------------------------------------
+// Collaboration mode & tool sanitization
+// ---------------------------------------------------------------------------
+
+static COLLAB_PLAN_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"(?i)collaboration mode:\s*plan").expect("static regex"));
+static IN_PLAN_MODE_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"(?i)in plan mode").expect("static regex"));
+static COLLAB_DEFAULT_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"(?i)collaboration mode:\s*default").expect("static regex"));
+static IN_DEFAULT_MODE_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"(?i)in default mode").expect("static regex"));
+
+/// TS `parseCollaborationMode` — trimmed/lowercased; only `plan`/`default`.
+fn parse_collaboration_mode(value: Option<&str>) -> Option<CollaborationMode> {
+    let value = value.filter(|value| !value.is_empty())?;
+    match value.trim().to_lowercase().as_str() {
+        "plan" => Some(CollaborationMode::Plan),
+        "default" => Some(CollaborationMode::Default),
+        _ => None,
+    }
+}
+
+/// TS `detectCollaborationMode` — env `CODEX_COLLABORATION_MODE` wins; else
+/// scan developer/system input texts for plan/default markers.
+fn detect_collaboration_mode(body: &RequestBody) -> CollaborationMode {
+    if let Some(mode) =
+        parse_collaboration_mode(std::env::var("CODEX_COLLABORATION_MODE").ok().as_deref())
+    {
+        return mode;
+    }
+    let Some(input) = body.input.as_ref() else {
+        return CollaborationMode::Unknown;
+    };
+
+    let mut saw_plan = false;
+    let mut saw_default = false;
+    for item in input {
+        let role = item
+            .role
+            .as_deref()
+            .map(str::to_lowercase)
+            .unwrap_or_default();
+        if role != "developer" && role != "system" {
+            continue;
+        }
+        let text = extract_message_text(item.content.as_ref());
+        if text.is_empty() {
+            continue;
+        }
+        if COLLAB_PLAN_RE.is_match(&text) || IN_PLAN_MODE_RE.is_match(&text) {
+            saw_plan = true;
+        }
+        if COLLAB_DEFAULT_RE.is_match(&text) || IN_DEFAULT_MODE_RE.is_match(&text) {
+            saw_default = true;
+        }
+    }
+
+    if saw_plan && !saw_default {
+        return CollaborationMode::Plan;
+    }
+    if saw_default {
+        return CollaborationMode::Default;
+    }
+    CollaborationMode::Unknown
+}
+
+/// TS `sanitizePlanOnlyToolEntry` — Value-based so any-shaped entries behave
+/// like the JS record accesses. Returns `None` when the entry is removed.
+fn sanitize_plan_only_tool_entry(value: Value, removed: &mut usize) -> Option<Value> {
+    let Some(record) = value.as_object() else {
+        return Some(value);
+    };
+
+    if record.get("type").and_then(Value::as_str) == Some("namespace")
+        && let Some(Value::Array(nested)) = record.get("tools")
+    {
+        let nested_tools: Vec<Value> = nested
+            .iter()
+            .cloned()
+            .filter_map(|tool| sanitize_plan_only_tool_entry(tool, removed))
+            .collect();
+        if nested_tools.is_empty() {
+            return None;
+        }
+        let mut new_record = record.clone();
+        new_record.insert("tools".to_string(), Value::Array(nested_tools));
+        return Some(Value::Object(new_record));
+    }
+
+    // ANY object carrying `function.name` in the plan-only set is removed
+    // (the TS check does not require `type === "function"`).
+    let Some(function_def) = record.get("function").and_then(Value::as_object) else {
+        return Some(value);
+    };
+    match function_def.get("name").and_then(Value::as_str) {
+        Some(name) if PLAN_MODE_ONLY_TOOLS.contains(&name) => {
+            *removed += 1;
+            None
+        }
+        _ => Some(value),
+    }
+}
+
+/// TS `sanitizePlanOnlyTools` — removes `request_user_input` whenever mode is
+/// NOT `plan` (i.e. also in `unknown`); recurses into namespaces; a namespace
+/// whose tools all get removed is itself removed (not counted).
+fn sanitize_plan_only_tools(
+    tools: Option<Vec<RequestToolDefinition>>,
+    mode: CollaborationMode,
+) -> Option<Vec<RequestToolDefinition>> {
+    let tools = tools?;
+    if mode == CollaborationMode::Plan {
+        return Some(tools);
+    }
+
+    let mut removed = 0usize;
+    let filtered: Vec<RequestToolDefinition> = tools
+        .into_iter()
+        .filter_map(|tool| {
+            let raw = serde_json::to_value(&tool).unwrap_or(Value::Null);
+            sanitize_plan_only_tool_entry(raw, &mut removed)
+                .map(|value| serde_json::from_value(value).unwrap_or(tool))
+        })
+        .collect();
+
+    if removed > 0 {
+        log_warn(
+            &format!(
+                "Removed {removed} plan-mode-only tool definition(s) because collaboration mode is {}",
+                mode.as_str()
+            ),
+            None,
+        );
+    }
+    Some(filtered)
+}
+
+/// TS removal counters for `sanitizeModelIncompatibleTools`.
+#[derive(Default)]
+struct ToolCapabilityRemovalCounts {
+    tool_search: usize,
+    computer_use: usize,
+}
+
+/// TS `COMPUTER_TOOL_TYPES`.
+fn is_computer_tool_type(kind: &str) -> bool {
+    kind == "computer" || kind == "computer_use_preview"
+}
+
+/// TS `sanitizeModelIncompatibleToolEntry`.
+fn sanitize_model_incompatible_tool_entry(
+    value: Value,
+    capabilities: model_map::ModelCapabilities,
+    removed: &mut ToolCapabilityRemovalCounts,
+) -> Option<Value> {
+    let Some(record) = value.as_object() else {
+        return Some(value);
+    };
+    let kind = record.get("type").and_then(Value::as_str).unwrap_or("");
+    if kind == "tool_search" && !capabilities.tool_search {
+        removed.tool_search += 1;
+        return None;
+    }
+    if is_computer_tool_type(kind) && !capabilities.computer_use {
+        removed.computer_use += 1;
+        return None;
+    }
+    if kind == "namespace"
+        && let Some(Value::Array(nested)) = record.get("tools")
+    {
+        let nested_tools: Vec<Value> = nested
+            .iter()
+            .cloned()
+            .filter_map(|tool| sanitize_model_incompatible_tool_entry(tool, capabilities, removed))
+            .collect();
+        if nested_tools.is_empty() {
+            return None;
+        }
+        let mut new_record = record.clone();
+        new_record.insert("tools".to_string(), Value::Array(nested_tools));
+        return Some(Value::Object(new_record));
+    }
+    Some(value)
+}
+
+/// TS `sanitizeModelIncompatibleTools` — drops `tool_search` / computer tools
+/// the resolved model does not support (namespace-recursive), with the two
+/// frozen warn messages.
+fn sanitize_model_incompatible_tools(
+    tools: Option<Vec<RequestToolDefinition>>,
+    model: Option<&str>,
+) -> Option<Vec<RequestToolDefinition>> {
+    let tools = tools?;
+    let capabilities = model_map::get_model_capabilities(model);
+    let mut removed = ToolCapabilityRemovalCounts::default();
+    let filtered: Vec<RequestToolDefinition> = tools
+        .into_iter()
+        .filter_map(|tool| {
+            let raw = serde_json::to_value(&tool).unwrap_or(Value::Null);
+            sanitize_model_incompatible_tool_entry(raw, capabilities, &mut removed)
+                .map(|value| serde_json::from_value(value).unwrap_or(tool))
+        })
+        .collect();
+
+    let model_label = model.unwrap_or("the selected model");
+    if removed.tool_search > 0 {
+        log_warn(
+            &format!(
+                "Removed {} tool_search definition(s) because {model_label} does not support tool search",
+                removed.tool_search
+            ),
+            None,
+        );
+    }
+    if removed.computer_use > 0 {
+        log_warn(
+            &format!(
+                "Removed {} computer tool definition(s) because {model_label} does not support computer use",
+                removed.computer_use
+            ),
+            None,
+        );
+    }
+
+    Some(filtered)
+}
+
+// ---------------------------------------------------------------------------
+// Bridge / remap message helpers
+// ---------------------------------------------------------------------------
+
+fn prepend_developer_message(
+    input: Option<Vec<InputItem>>,
+    has_tools: bool,
+    text: &str,
+) -> Option<Vec<InputItem>> {
+    let input = input?;
+    if !has_tools {
+        return Some(input);
+    }
+    let message = InputItem {
+        id: None,
+        kind: Some("message".to_string()),
+        role: Some("developer".to_string()),
+        content: Some(json!([{ "type": "input_text", "text": text }])),
+        extra: Map::new(),
+    };
+    let mut result = Vec::with_capacity(input.len() + 1);
+    result.push(message);
+    result.extend(input);
+    Some(result)
+}
+
+/// TS `addCodexBridgeMessage` — prepends the CODEX_HOST_BRIDGE developer
+/// message when tools are present. `bridge_text` is the caller-supplied
+/// `crate::prompts::host_bridge::CODEX_HOST_BRIDGE` (see module docs).
+pub fn add_codex_bridge_message(
+    input: Option<Vec<InputItem>>,
+    has_tools: bool,
+    bridge_text: &str,
+) -> Option<Vec<InputItem>> {
+    prepend_developer_message(input, has_tools, bridge_text)
+}
+
+/// TS `addToolRemapMessage` — prepends the TOOL_REMAP_MESSAGE developer
+/// message when tools are present. `remap_text` is the caller-supplied
+/// `crate::prompts::codex::TOOL_REMAP_MESSAGE`.
+pub fn add_tool_remap_message(
+    input: Option<Vec<InputItem>>,
+    has_tools: bool,
+    remap_text: &str,
+) -> Option<Vec<InputItem>> {
+    prepend_developer_message(input, has_tools, remap_text)
+}
+
+// ---------------------------------------------------------------------------
+// Background mode & resolution helpers
+// ---------------------------------------------------------------------------
+
+fn is_background_mode_requested(body: &RequestBody) -> bool {
+    body.background == Some(true)
+}
+
+/// TS `assertBackgroundModeCompatibility` — `Ok(true)` iff background mode is
+/// requested AND allowed AND not combined with `store=false`.
+fn assert_background_mode_compatibility(
+    body: &RequestBody,
+    allow_background_responses: bool,
+) -> Result<bool, TransformRequestBodyError> {
+    if !is_background_mode_requested(body) {
+        return Ok(false);
+    }
+    if !allow_background_responses {
+        return Err(TransformRequestBodyError::BackgroundResponsesDisabled);
+    }
+    let provider_store = body
+        .provider_options
+        .as_ref()
+        .and_then(|options| options.openai.as_ref())
+        .and_then(|openai| openai.store);
+    if body.store == Some(false) || provider_store == Some(false) {
+        return Err(TransformRequestBodyError::BackgroundRequiresStore);
+    }
+    Ok(true)
+}
+
+/// TS `resolveReasoningConfig` — existing body/provider values override the
+/// model config (truthy-gated, so empty strings do NOT override), then
+/// [`get_reasoning_config`] coerces per model.
+fn resolve_reasoning_config(
+    model_name: &str,
+    model_config: &ConfigOptions,
+    body: &RequestBody,
+) -> ReasoningConfig {
+    let provider = body
+        .provider_options
+        .as_ref()
+        .and_then(|options| options.openai.as_ref());
+    let existing_effort = body
+        .reasoning
+        .as_ref()
+        .and_then(|reasoning| reasoning.effort.clone())
+        .or_else(|| provider.and_then(|openai| openai.reasoning_effort.clone()));
+    let existing_summary = body
+        .reasoning
+        .as_ref()
+        .and_then(|reasoning| reasoning.summary.clone())
+        .or_else(|| provider.and_then(|openai| openai.reasoning_summary.clone()));
+
+    let mut merged = model_config.clone();
+    if let Some(effort) = existing_effort.filter(|effort| !effort.is_empty()) {
+        merged.reasoning_effort = Some(effort);
+    }
+    if let Some(summary) = existing_summary.filter(|summary| !summary.is_empty()) {
+        merged.reasoning_summary = Some(summary);
+    }
+    get_reasoning_config(Some(model_name), &merged)
+}
+
+/// Spread the strict [`ReasoningConfig`] over the body's permissive
+/// `reasoning` slot (TS `body.reasoning = { ...body.reasoning, ...config }`).
+fn apply_reasoning(body: &mut RequestBody, config: ReasoningConfig) {
+    let mut settings = body.reasoning.take().unwrap_or_default();
+    settings.effort = Some(config.effort.as_str().to_string());
+    settings.summary = Some(config.summary.as_str().to_string());
+    body.reasoning = Some(settings);
+}
+
+/// TS `resolveTextVerbosity` — body → providerOptions → modelConfig →
+/// `"medium"` (nullish chain: empty strings win through).
+fn resolve_text_verbosity(model_config: &ConfigOptions, body: &RequestBody) -> String {
+    let provider = body
+        .provider_options
+        .as_ref()
+        .and_then(|options| options.openai.as_ref());
+    body.text
+        .as_ref()
+        .and_then(|text| text.verbosity.clone())
+        .or_else(|| provider.and_then(|openai| openai.text_verbosity.clone()))
+        .or_else(|| model_config.text_verbosity.clone())
+        .unwrap_or_else(|| "medium".to_string())
+}
+
+/// TS `resolvePromptCacheRetention` — body → providerOptions → modelConfig.
+fn resolve_prompt_cache_retention(
+    model_config: &ConfigOptions,
+    body: &RequestBody,
+) -> Option<String> {
+    let provider = body
+        .provider_options
+        .as_ref()
+        .and_then(|options| options.openai.as_ref());
+    body.prompt_cache_retention
+        .clone()
+        .or_else(|| provider.and_then(|openai| openai.prompt_cache_retention.clone()))
+        .or_else(|| model_config.prompt_cache_retention.clone())
+}
+
+/// Frozen include entry for stateless reasoning continuity.
+const REASONING_ENCRYPTED_CONTENT: &str = "reasoning.encrypted_content";
+
+// ---------------------------------------------------------------------------
+// transformRequestBody
+// ---------------------------------------------------------------------------
+
+/// TS `transformRequestBody` — the exact TS pipeline order (spec 06 §2):
+///
+/// 1. Model config lookup with the ORIGINAL model name (config keys like
+///    `"gpt-5-codex-low"` keep working), then `body.model` normalized.
+/// 2. Background-mode gating (two frozen error messages).
+/// 3. Fast-session plan; a trivial turn additionally disables tools.
+/// 4. `store=false` unless background; **`stream=true` ALWAYS**.
+/// 5. Tool cleanup → plan-only sanitize → model-capability sanitize
+///    (empty result → `tools` removed).
+/// 6. Instructions injection (fast sessions compact them).
+/// 7. Input pipeline: fast trim → id filtering (background PRESERVES ids) →
+///    host-prompt filter + bridge (codex mode) or tool-remap message →
+///    orphaned-output normalization → missing-output injection.
+/// 8. Reasoning / text-verbosity / prompt_cache_retention / include
+///    resolution; fast-session override clamps reasoning+verbosity.
+/// 9. `max_output_tokens` / `max_completion_tokens` removed.
+pub fn transform_request_body(
+    params: TransformRequestBodyParams<'_>,
+) -> Result<RequestBody, TransformRequestBodyError> {
+    let TransformRequestBodyParams {
+        mut body,
+        codex_instructions,
+        user_config,
+        codex_mode,
+        fast_session,
+        fast_session_strategy,
+        fast_session_max_input_items,
+        defer_fast_session_input_trimming,
+        allow_background_responses,
+        prompts,
+    } = params;
+
+    let default_user_config = UserConfig::default();
+    let resolved_user_config = user_config.unwrap_or(&default_user_config);
+
+    let original_model = body.model.clone();
+    let normalized_model = normalize_model(body.model.as_deref());
+
+    // Config keys use the ORIGINAL model name (`originalModel || normalized`).
+    let lookup_model: String = match &original_model {
+        Some(model) if !model.is_empty() => model.clone(),
+        _ => normalized_model.to_string(),
+    };
+    let model_config = get_model_config(&lookup_model, Some(resolved_user_config));
+    let normalized_profile = model_map::get_model_profile(Some(normalized_model));
+
+    log_debug(
+        &format!(
+            "Model config lookup: \"{lookup_model}\" \u{2192} normalized to \"{normalized_model}\" for API"
+        ),
+        Some(&json!({
+            "hasModelSpecificConfig": resolved_user_config.models.contains_key(&lookup_model),
+            "resolvedConfig": serde_json::to_value(&model_config).unwrap_or(Value::Null),
+        })),
+    );
+
+    body.model = Some(normalized_model.to_string());
+    let should_use_normalized_reasoning_model = normalized_profile.prompt_family
+        == ModelFamily::Gpt5Codex
+        && lookup_model.to_lowercase().contains("codex");
+    let reasoning_model: String = if should_use_normalized_reasoning_model {
+        normalized_model.to_string()
+    } else {
+        lookup_model.clone()
+    };
+
+    let background_mode_requested =
+        assert_background_mode_compatibility(&body, allow_background_responses)?;
+    let plan = resolve_fast_session_input_trim_plan(
+        &body,
+        fast_session,
+        fast_session_strategy,
+        fast_session_max_input_items,
+    );
+    let should_apply_fast_session_tuning = !background_mode_requested && plan.should_apply;
+    let is_trivial_turn = plan.is_trivial_turn;
+    let should_disable_tools_for_trivial_turn = should_apply_fast_session_tuning && is_trivial_turn;
+
+    // Codex required fields: store=false (stateless) unless background;
+    // stream=true ALWAYS — response handling reconstructs JSON later.
+    body.store = Some(background_mode_requested);
+    body.stream = Some(true);
+
+    let collaboration_mode = detect_collaboration_mode(&body);
+    if body.tools.is_some() && should_disable_tools_for_trivial_turn {
+        body.tools = None;
+    }
+    if body.tools.is_some() {
+        body.tools = cleanup_tool_definitions(body.tools.take());
+        body.tools = sanitize_plan_only_tools(body.tools.take(), collaboration_mode);
+        body.tools = sanitize_model_incompatible_tools(body.tools.take(), body.model.as_deref());
+        if body.tools.as_ref().is_some_and(Vec::is_empty) {
+            body.tools = None;
+        }
+    }
+
+    body.instructions = Some(if should_apply_fast_session_tuning {
+        compact_instructions_for_fast_session(codex_instructions, is_trivial_turn)
+    } else {
+        codex_instructions.to_string()
+    });
+
+    // Filter and transform input.
+    if body.input.is_some() {
+        let mut input_items = body.input.take();
+
+        if should_apply_fast_session_tuning && !defer_fast_session_input_trimming {
+            let prefer_latest_user_only = plan
+                .trim
+                .map(|trim| trim.prefer_latest_user_only)
+                .unwrap_or(false);
+            input_items = trim_input_for_fast_session(
+                input_items,
+                fast_session_max_input_items,
+                prefer_latest_user_only,
+            );
+        }
+
+        let truthy_ids = |items: Option<&[InputItem]>| -> Vec<String> {
+            items
+                .unwrap_or(&[])
+                .iter()
+                .filter_map(|item| item.id.clone().filter(|id| !id.is_empty()))
+                .collect()
+        };
+        let original_ids = truthy_ids(input_items.as_deref());
+        if !original_ids.is_empty() {
+            log_debug(
+                &format!("Filtering {} message IDs from input:", original_ids.len()),
+                Some(&json!(original_ids)),
+            );
+        }
+
+        // Background mode PRESERVES ids (stateful path).
+        body.input = filter_input(input_items, !background_mode_requested);
+
+        let remaining_ids = truthy_ids(body.input.as_deref());
+        if !remaining_ids.is_empty() && !background_mode_requested {
+            log_warn(
+                &format!(
+                    "WARNING: {} IDs still present after filtering:",
+                    remaining_ids.len()
+                ),
+                Some(&json!(remaining_ids)),
+            );
+        } else if !original_ids.is_empty() {
+            log_debug(
+                &format!("Successfully removed all {} message IDs", original_ids.len()),
+                None,
+            );
+        }
+
+        if codex_mode {
+            // CODEX_MODE: remove host system prompt, add bridge prompt.
+            body.input = filter_host_system_prompts_with_cached_prompt(
+                body.input.take(),
+                prompts.cached_host_prompt.as_deref(),
+            );
+            body.input = add_codex_bridge_message(
+                body.input.take(),
+                body.tools.is_some(),
+                prompts.codex_host_bridge,
+            );
+        } else {
+            // DEFAULT MODE: keep original behavior with tool remap message.
+            body.input = add_tool_remap_message(
+                body.input.take(),
+                body.tools.is_some(),
+                prompts.tool_remap_message,
+            );
+        }
+
+        // Orphaned tool outputs become messages (context preserved); calls
+        // without outputs get a cancelled-output injected.
+        if let Some(items) = body.input.take() {
+            let items = input_utils::normalize_orphaned_tool_outputs(items);
+            body.input = Some(input_utils::inject_missing_tool_outputs(items));
+        }
+    }
+
+    // Reasoning (existing body/provider options win over config defaults).
+    let reasoning_config = resolve_reasoning_config(&reasoning_model, &model_config, &body);
+    apply_reasoning(&mut body, reasoning_config);
+
+    // Text verbosity (preserves the host structured-output `text.format`).
+    let verbosity = resolve_text_verbosity(&model_config, &body);
+    let mut text = body.text.take().unwrap_or_default();
+    text.verbosity = Some(verbosity);
+    body.text = Some(text);
+
+    if let Some(retention) = resolve_prompt_cache_retention(&model_config, &body) {
+        body.prompt_cache_retention = Some(retention);
+    }
+
+    if should_apply_fast_session_tuning {
+        // Clamp to minimum reasoning + verbosity; getReasoningConfig
+        // normalizes unsupported values per model family (codex → "low").
+        let fast_reasoning = get_reasoning_config(
+            Some(&reasoning_model),
+            &ConfigOptions {
+                reasoning_effort: Some("none".to_string()),
+                reasoning_summary: Some("auto".to_string()),
+                ..Default::default()
+            },
+        );
+        apply_reasoning(&mut body, fast_reasoning);
+        let mut text = body.text.take().unwrap_or_default();
+        text.verbosity = Some("low".to_string());
+        body.text = Some(text);
+    }
+
+    // Include: background passes the raw chain through (may end absent);
+    // stateless defaults to (and always appends) reasoning.encrypted_content.
+    let provider_include = body
+        .provider_options
+        .as_ref()
+        .and_then(|options| options.openai.as_ref())
+        .and_then(|openai| openai.include.clone());
+    if background_mode_requested {
+        body.include = body
+            .include
+            .take()
+            .or(provider_include)
+            .or_else(|| model_config.include.clone());
+    } else {
+        let base = body
+            .include
+            .take()
+            .or(provider_include)
+            .or_else(|| model_config.include.clone())
+            .unwrap_or_else(|| vec![REASONING_ENCRYPTED_CONTENT.to_string()]);
+        let mut seen: HashSet<String> = HashSet::new();
+        let mut include: Vec<String> = base
+            .into_iter()
+            .filter(|entry| !entry.is_empty())
+            .filter(|entry| seen.insert(entry.clone()))
+            .collect();
+        if !include.iter().any(|entry| entry == REASONING_ENCRYPTED_CONTENT) {
+            include.push(REASONING_ENCRYPTED_CONTENT.to_string());
+        }
+        body.include = Some(include);
+    }
+
+    // Remove unsupported parameters.
+    body.max_output_tokens = None;
+    body.max_completion_tokens = None;
+
+    Ok(body)
+}
+
+/// Async TS-parity wrapper over [`transform_request_body`]: awaits the cached
+/// host prompt exactly like the TS `transformRequestBody` does internally
+/// (fetch failure → `None` → signature-only host-prompt detection), then runs
+/// the synchronous pipeline. An already-populated
+/// `params.prompts.cached_host_prompt` is kept as-is.
+pub async fn transform_request_body_fetching_host_prompt(
+    mut params: TransformRequestBodyParams<'_>,
+) -> Result<RequestBody, TransformRequestBodyError> {
+    if params.codex_mode && params.prompts.cached_host_prompt.is_none() {
+        params.prompts.cached_host_prompt =
+            crate::prompts::host_prompt::get_host_codex_prompt().await.ok();
+    }
+    transform_request_body(params)
+}
+
+/// TS `filterHostSystemPrompts` — fetches the cached host prompt for
+/// verification (failure → text-based detection only) and filters.
+pub async fn filter_host_system_prompts(
+    input: Option<Vec<InputItem>>,
+) -> Option<Vec<InputItem>> {
+    let cached_prompt = crate::prompts::host_prompt::get_host_codex_prompt().await.ok();
+    filter_host_system_prompts_with_cached_prompt(input, cached_prompt.as_deref())
+}
+
+// ===========================================================================
+// Tests — ported from test/request-transformer.test.ts
+// ===========================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::from_value;
+
+    const CODEX_INSTRUCTIONS: &str = "Test Codex Instructions";
+    const TEST_BRIDGE: &str = "TEST_CODEX_HOST_BRIDGE_PROMPT";
+    const TEST_REMAP: &str = "TEST_TOOL_REMAP apply_patch patch (preferred if available)";
+
+    fn body_of(value: Value) -> RequestBody {
+        from_value(value).expect("test body must parse")
+    }
+
+    fn base_params(value: Value) -> TransformRequestBodyParams<'static> {
+        let mut params = TransformRequestBodyParams::new(body_of(value), CODEX_INSTRUCTIONS);
+        params.prompts = TransformPrompts {
+            codex_host_bridge: TEST_BRIDGE,
+            tool_remap_message: TEST_REMAP,
+            cached_host_prompt: None,
+        };
+        params
+    }
+
+    fn transform(value: Value) -> RequestBody {
+        transform_request_body(base_params(value)).expect("transform must succeed")
+    }
+
+    fn transform_with(
+        value: Value,
+        adjust: impl FnOnce(&mut TransformRequestBodyParams<'static>),
+    ) -> RequestBody {
+        let mut params = base_params(value);
+        adjust(&mut params);
+        transform_request_body(params).expect("transform must succeed")
+    }
+
+    fn user_config(value: Value) -> UserConfig {
+        from_value(value).expect("test user config must parse")
+    }
+
+    fn effort_of(body: &RequestBody) -> &str {
+        body.reasoning
+            .as_ref()
+            .and_then(|r| r.effort.as_deref())
+            .unwrap_or("")
+    }
+
+    fn summary_of(body: &RequestBody) -> &str {
+        body.reasoning
+            .as_ref()
+            .and_then(|r| r.summary.as_deref())
+            .unwrap_or("")
+    }
+
+    fn verbosity_of(body: &RequestBody) -> &str {
+        body.text
+            .as_ref()
+            .and_then(|t| t.verbosity.as_deref())
+            .unwrap_or("")
+    }
+
+    fn tools_json(body: &RequestBody) -> Value {
+        serde_json::to_value(&body.tools).unwrap()
+    }
+
+    // --- variant-suffix pattern (the (?<!codex) lookbehind) ----------------
+
+    #[test]
+    fn variant_suffix_strips_reasoning_and_ultra_suffixes() {
+        assert_eq!(
+            split_variant_suffix("gpt-5-codex-low"),
+            ("gpt-5-codex", Some(ModelReasoningEffort::Low))
+        );
+        assert_eq!(
+            split_variant_suffix("gpt-5.6-sol-ultra"),
+            ("gpt-5.6-sol", Some(ModelReasoningEffort::Ultra))
+        );
+        // `ultra` has NO codex guard — codex-ultra still parses the suffix.
+        assert_eq!(
+            split_variant_suffix("gpt-5-codex-ultra"),
+            ("gpt-5-codex", Some(ModelReasoningEffort::Ultra))
+        );
+        assert_eq!(
+            split_variant_suffix("GPT-5.2-CODEX-XHIGH"),
+            ("GPT-5.2-CODEX", Some(ModelReasoningEffort::Xhigh))
+        );
+    }
+
+    #[test]
+    fn variant_suffix_max_is_guarded_by_the_codex_lookbehind() {
+        // `-max` after codex is part of the MODEL ID, not an effort.
+        assert_eq!(split_variant_suffix("gpt-5.1-codex-max"), ("gpt-5.1-codex-max", None));
+        assert_eq!(split_variant_suffix("codex-max"), ("codex-max", None));
+        assert_eq!(split_variant_suffix("GPT-5.1-CODEX-MAX"), ("GPT-5.1-CODEX-MAX", None));
+        // `-max` NOT preceded by codex is an effort suffix.
+        assert_eq!(
+            split_variant_suffix("gpt-5.6-sol-max"),
+            ("gpt-5.6-sol", Some(ModelReasoningEffort::Max))
+        );
+        // Only ONE suffix strips ($-anchored, non-global).
+        assert_eq!(
+            split_variant_suffix("gpt-5-high-low"),
+            ("gpt-5-high", Some(ModelReasoningEffort::Low))
+        );
+        // No suffix at all.
+        assert_eq!(split_variant_suffix("gpt-5.5"), ("gpt-5.5", None));
+    }
+
+    // --- normalizeModel -----------------------------------------------------
+
+    #[test]
+    fn normalize_model_handles_case_and_formatting_variations() {
+        assert_eq!(normalize_model(Some("GPT-5.4")), "gpt-5.4");
+        assert_eq!(normalize_model(Some("GPT-5-HIGH")), "gpt-5.5");
+        assert_eq!(normalize_model(Some("Gpt-5.4-Pro")), "gpt-5.4-pro");
+        assert_eq!(
+            normalize_model(Some("GPT 5 High (ChatGPT Subscription)")),
+            "gpt-5.5"
+        );
+        assert_eq!(
+            normalize_model(Some("GPT 5 Codex Low (ChatGPT Subscription)")),
+            "gpt-5.3-codex"
+        );
+        assert_eq!(normalize_model(None), "gpt-5.5");
+        assert_eq!(normalize_model(Some("")), "gpt-5.5");
+    }
+
+    // --- getModelConfig -----------------------------------------------------
+
+    #[test]
+    fn model_config_finds_per_model_options_using_config_key() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "medium" },
+            "models": {
+                "gpt-5-codex-low": { "options": { "reasoningEffort": "low", "textVerbosity": "low" } }
+            }
+        }));
+        let result = get_model_config("gpt-5-codex-low", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("low"));
+        assert_eq!(result.text_verbosity.as_deref(), Some("low"));
+    }
+
+    #[test]
+    fn model_config_resolves_provider_prefixed_ids_to_base_model_config() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "medium" },
+            "models": {
+                "gpt-5.2-codex": { "options": { "reasoningEffort": "xhigh", "reasoningSummary": "detailed" } }
+            }
+        }));
+        let result = get_model_config("openai/gpt-5.2-codex", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("xhigh"));
+        assert_eq!(result.reasoning_summary.as_deref(), Some("detailed"));
+    }
+
+    #[test]
+    fn model_config_applies_variants_from_base_model_config() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "medium", "reasoningSummary": "auto" },
+            "models": {
+                "gpt-5.2-codex": {
+                    "options": { "reasoningSummary": "auto" },
+                    "variants": { "xhigh": { "reasoningEffort": "xhigh", "reasoningSummary": "detailed" } }
+                }
+            }
+        }));
+        let result = get_model_config("openai/gpt-5.2-codex-xhigh", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("xhigh"));
+        assert_eq!(result.reasoning_summary.as_deref(), Some("detailed"));
+    }
+
+    #[test]
+    fn model_config_merges_global_and_per_model_options_per_model_wins() {
+        let config = user_config(json!({
+            "global": {
+                "reasoningEffort": "medium",
+                "textVerbosity": "medium",
+                "include": ["reasoning.encrypted_content"]
+            },
+            "models": {
+                "gpt-5-codex-high": { "options": { "reasoningEffort": "high" } }
+            }
+        }));
+        let result = get_model_config("gpt-5-codex-high", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("high"));
+        assert_eq!(result.text_verbosity.as_deref(), Some("medium"));
+        assert_eq!(
+            result.include,
+            Some(vec!["reasoning.encrypted_content".to_string()])
+        );
+    }
+
+    #[test]
+    fn model_config_returns_global_options_when_model_not_in_config() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "medium" },
+            "models": {
+                "gpt-5-codex-low": { "options": { "reasoningEffort": "low" } }
+            }
+        }));
+        let result = get_model_config("gpt-5-codex", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("medium"));
+    }
+
+    #[test]
+    fn model_config_handles_empty_and_absent_configs() {
+        assert_eq!(
+            get_model_config("gpt-5-codex", Some(&UserConfig::default())),
+            ConfigOptions::default()
+        );
+        assert_eq!(get_model_config("gpt-5", None), ConfigOptions::default());
+    }
+
+    #[test]
+    fn model_config_works_with_old_verbose_keys_and_extra_id_field() {
+        let config = user_config(json!({
+            "global": {},
+            "models": {
+                "GPT 5 Codex Low (ChatGPT Subscription)": { "options": { "reasoningEffort": "low" } }
+            }
+        }));
+        let result = get_model_config("GPT 5 Codex Low (ChatGPT Subscription)", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("low"));
+
+        // Unknown `id` key on the entry is tolerated (extra map).
+        let config = user_config(json!({
+            "global": {},
+            "models": {
+                "gpt-5-codex-low": { "id": "gpt-5-codex", "options": { "reasoningEffort": "low" } }
+            }
+        }));
+        let result = get_model_config("gpt-5-codex-low", Some(&config));
+        assert_eq!(result.reasoning_effort.as_deref(), Some("low"));
+    }
+
+    // --- applyFastSessionDefaults -------------------------------------------
+
+    #[test]
+    fn fast_session_defaults_fill_only_missing_values() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "high" },
+            "models": {}
+        }));
+        let result = apply_fast_session_defaults(&config);
+        assert_eq!(result.global.reasoning_effort.as_deref(), Some("high"));
+        assert_eq!(result.global.text_verbosity.as_deref(), Some("low"));
+
+        let result = apply_fast_session_defaults(&UserConfig::default());
+        assert_eq!(result.global.reasoning_effort.as_deref(), Some("low"));
+        assert_eq!(result.global.text_verbosity.as_deref(), Some("low"));
+    }
+
+    // --- filterInput --------------------------------------------------------
+
+    #[test]
+    fn filter_input_strips_all_ids_and_keeps_items() {
+        let input: Vec<InputItem> = from_value(json!([
+            { "id": "rs_123", "type": "message", "role": "assistant", "content": "hello" },
+            { "id": "msg_456", "type": "message", "role": "user", "content": "world" },
+            { "id": "assistant_789", "type": "message", "role": "assistant", "content": "test" },
+        ]))
+        .unwrap();
+        let result = filter_input(Some(input), true).unwrap();
+        assert_eq!(result.len(), 3);
+        assert!(result.iter().all(|item| item.id.is_none()));
+        assert_eq!(
+            result[0].content.as_ref().and_then(Value::as_str),
+            Some("hello")
+        );
+    }
+
+    #[test]
+    fn filter_input_preserves_other_properties_and_handles_edges() {
+        let input: Vec<InputItem> = from_value(json!([
+            { "id": "msg_123", "type": "message", "role": "user", "content": "test", "metadata": { "some": "data" } },
+            { "id": "", "type": "message", "role": "user", "content": "hello" },
+        ]))
+        .unwrap();
+        let result = filter_input(Some(input), true).unwrap();
+        assert_eq!(result.len(), 2);
+        assert!(result[0].id.is_none());
+        assert!(result[0].extra.contains_key("metadata"));
+        assert!(result[1].id.is_none());
+
+        assert!(filter_input(None, true).is_none());
+        assert_eq!(filter_input(Some(Vec::new()), true), Some(Vec::new()));
+    }
+
+    #[test]
+    fn filter_input_removes_item_reference_items_and_can_keep_ids() {
+        let input: Vec<InputItem> = from_value(json!([
+            { "id": "ref_1", "type": "item_reference" },
+            { "id": "msg_1", "type": "message", "role": "user", "content": "hi" },
+        ]))
+        .unwrap();
+        let stripped = filter_input(Some(input.clone()), true).unwrap();
+        assert_eq!(stripped.len(), 1);
+        assert!(stripped[0].id.is_none());
+
+        // stripIds=false (background mode) keeps ids but still drops refs.
+        let kept = filter_input(Some(input), false).unwrap();
+        assert_eq!(kept.len(), 1);
+        assert_eq!(kept[0].id.as_deref(), Some("msg_1"));
+    }
+
+    // --- add bridge / remap message ----------------------------------------
+
+    #[test]
+    fn add_messages_prepend_developer_message_only_with_tools() {
+        let input: Vec<InputItem> =
+            from_value(json!([{ "type": "message", "role": "user", "content": "hello" }])).unwrap();
+
+        let bridged = add_codex_bridge_message(Some(input.clone()), true, TEST_BRIDGE).unwrap();
+        assert_eq!(bridged.len(), 2);
+        assert_eq!(bridged[0].role.as_deref(), Some("developer"));
+        assert_eq!(bridged[0].kind.as_deref(), Some("message"));
+        let text = bridged[0].content.as_ref().unwrap()[0]["text"]
+            .as_str()
+            .unwrap();
+        assert_eq!(text, TEST_BRIDGE);
+
+        let remapped = add_tool_remap_message(Some(input.clone()), true, TEST_REMAP).unwrap();
+        assert!(
+            remapped[0].content.as_ref().unwrap()[0]["text"]
+                .as_str()
+                .unwrap()
+                .contains("apply_patch")
+        );
+
+        assert_eq!(
+            add_codex_bridge_message(Some(input.clone()), false, TEST_BRIDGE),
+            Some(input)
+        );
+        assert!(add_codex_bridge_message(None, true, TEST_BRIDGE).is_none());
+        assert!(add_tool_remap_message(None, true, TEST_REMAP).is_none());
+    }
+
+    // --- transformRequestBody: cache fields ---------------------------------
+
+    #[test]
+    fn preserves_prompt_cache_key_and_previous_response_id() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [],
+            "prompt_cache_key": "ses_host_key_123",
+        }));
+        assert_eq!(result.prompt_cache_key.as_deref(), Some("ses_host_key_123"));
+
+        let result = transform(json!({ "model": "gpt-5", "input": [] }));
+        assert!(result.prompt_cache_key.is_none());
+
+        let result = transform(json!({
+            "model": "gpt-5.4",
+            "input": [],
+            "previous_response_id": "resp_prior_123",
+        }));
+        assert_eq!(result.previous_response_id.as_deref(), Some("resp_prior_123"));
+    }
+
+    #[test]
+    fn prompt_cache_retention_precedence_body_provider_config() {
+        let result = transform(json!({
+            "model": "gpt-5.4",
+            "input": [],
+            "prompt_cache_key": "ses_cache_key_123",
+            "prompt_cache_retention": "24h",
+        }));
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("24h"));
+
+        let result = transform(json!({
+            "model": "gpt-5.4",
+            "input": [],
+            "providerOptions": { "openai": { "promptCacheRetention": "1h" } },
+        }));
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("1h"));
+
+        // providerOptions beats user config.
+        let config = user_config(json!({ "global": { "promptCacheRetention": "7d" }, "models": {} }));
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.4",
+                "input": [],
+                "providerOptions": { "openai": { "promptCacheRetention": "1h" } },
+            }),
+            |params| params.user_config = Some(Box::leak(Box::new(config))),
+        );
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("1h"));
+
+        // Body beats providerOptions.
+        let result = transform(json!({
+            "model": "gpt-5.4",
+            "input": [],
+            "prompt_cache_retention": "24h",
+            "providerOptions": { "openai": { "promptCacheRetention": "1h" } },
+        }));
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("24h"));
+    }
+
+    #[test]
+    fn inherits_prompt_cache_retention_from_user_config_layers() {
+        let global_only = user_config(json!({
+            "global": { "promptCacheRetention": "7d" },
+            "models": {}
+        }));
+        let result = transform_with(json!({ "model": "gpt-5.4", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(global_only)))
+        });
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("7d"));
+
+        let model_specific = user_config(json!({
+            "global": { "promptCacheRetention": "7d" },
+            "models": { "gpt-5.4": { "options": { "promptCacheRetention": "24h" } } }
+        }));
+        let result = transform_with(json!({ "model": "gpt-5.4", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(model_specific)))
+        });
+        assert_eq!(result.prompt_cache_retention.as_deref(), Some("24h"));
+    }
+
+    #[test]
+    fn preserves_text_format_when_applying_verbosity_defaults() {
+        let format = json!({
+            "type": "json_schema",
+            "name": "contract_response",
+            "schema": {
+                "type": "object",
+                "properties": { "answer": { "type": "string" } },
+                "required": ["answer"],
+            },
+            "strict": true,
+        });
+        let result = transform(json!({
+            "model": "gpt-5.4",
+            "input": [],
+            "text": { "format": format },
+        }));
+        assert_eq!(verbosity_of(&result), "medium");
+        assert_eq!(
+            serde_json::to_value(result.text.as_ref().unwrap().format.as_ref().unwrap()).unwrap(),
+            format
+        );
+    }
+
+    // --- required Codex fields ----------------------------------------------
+
+    #[test]
+    fn sets_required_codex_fields() {
+        let result = transform(json!({ "model": "gpt-5", "input": [] }));
+        assert_eq!(result.store, Some(false));
+        assert_eq!(result.stream, Some(true));
+        assert_eq!(result.instructions.as_deref(), Some(CODEX_INSTRUCTIONS));
+    }
+
+    #[test]
+    fn forces_stateless_invariants_even_with_conflicting_caller_values() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "stream": false,
+            "store": true,
+            "include": ["custom_field"],
+        }));
+        assert_eq!(result.stream, Some(true));
+        assert_eq!(result.store, Some(false));
+        assert_eq!(
+            result.include,
+            Some(vec![
+                "custom_field".to_string(),
+                "reasoning.encrypted_content".to_string()
+            ])
+        );
+    }
+
+    #[test]
+    fn normalizes_model_name() {
+        let result = transform(json!({ "model": "gpt-5-mini", "input": [] }));
+        assert_eq!(result.model.as_deref(), Some("gpt-5-mini"));
+        assert_eq!(effort_of(&result), "medium");
+    }
+
+    #[test]
+    fn removes_unsupported_parameters() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "max_output_tokens": 1000,
+            "max_completion_tokens": 2000,
+        }));
+        assert!(result.max_output_tokens.is_none());
+        assert!(result.max_completion_tokens.is_none());
+        // And they do not serialize at all.
+        let raw = serde_json::to_value(&result).unwrap();
+        assert!(raw.get("max_output_tokens").is_none());
+        assert!(raw.get("max_completion_tokens").is_none());
+    }
+
+    // --- reasoning & verbosity resolution -----------------------------------
+
+    #[test]
+    fn applies_gpt55_default_reasoning_for_stale_bare_gpt5_aliases() {
+        let result = transform(json!({ "model": "gpt-5", "input": [] }));
+        assert_eq!(effort_of(&result), "none");
+        assert_eq!(summary_of(&result), "auto");
+    }
+
+    #[test]
+    fn applies_user_reasoning_config() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "high", "reasoningSummary": "detailed" },
+            "models": {}
+        }));
+        let result = transform_with(json!({ "model": "gpt-5", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(effort_of(&result), "high");
+        assert_eq!(summary_of(&result), "detailed");
+    }
+
+    #[test]
+    fn respects_reasoning_config_already_set_in_body() {
+        let config = user_config(json!({
+            "global": { "reasoningEffort": "high", "reasoningSummary": "detailed" },
+            "models": {}
+        }));
+        let result = transform_with(
+            json!({
+                "model": "gpt-5",
+                "input": [],
+                "reasoning": { "effort": "low", "summary": "auto" },
+            }),
+            |params| params.user_config = Some(Box::leak(Box::new(config))),
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+    }
+
+    #[test]
+    fn uses_reasoning_config_from_provider_options() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "providerOptions": { "openai": { "reasoningEffort": "high", "reasoningSummary": "detailed" } },
+        }));
+        assert_eq!(effort_of(&result), "high");
+        assert_eq!(summary_of(&result), "detailed");
+    }
+
+    #[test]
+    fn text_verbosity_resolution_chain() {
+        let result = transform(json!({ "model": "gpt-5", "input": [] }));
+        assert_eq!(verbosity_of(&result), "medium");
+
+        let config = user_config(json!({ "global": { "textVerbosity": "low" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(verbosity_of(&result), "low");
+
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "providerOptions": { "openai": { "textVerbosity": "low" } },
+        }));
+        assert_eq!(verbosity_of(&result), "low");
+
+        // Body wins over providerOptions.
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "text": { "verbosity": "high" },
+            "providerOptions": { "openai": { "textVerbosity": "low" } },
+        }));
+        assert_eq!(verbosity_of(&result), "high");
+    }
+
+    #[test]
+    fn include_defaults_and_user_include() {
+        let result = transform(json!({ "model": "gpt-5", "input": [] }));
+        assert_eq!(
+            result.include,
+            Some(vec!["reasoning.encrypted_content".to_string()])
+        );
+
+        let config = user_config(json!({
+            "global": { "include": ["custom_field", "reasoning.encrypted_content"] },
+            "models": {}
+        }));
+        let result = transform_with(json!({ "model": "gpt-5", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(
+            result.include,
+            Some(vec![
+                "custom_field".to_string(),
+                "reasoning.encrypted_content".to_string()
+            ])
+        );
+    }
+
+    // --- effort coercion per model ------------------------------------------
+
+    #[test]
+    fn coerces_efforts_per_model_family() {
+        // minimal → low for codex.
+        let config = user_config(json!({ "global": { "reasoningEffort": "minimal" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5-codex", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(effort_of(&result), "low");
+
+        // none → low for codex aliases.
+        for model in ["gpt-5.2-codex", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.1-codex", "gpt-5.1-codex-max"] {
+            let config = user_config(json!({ "global": { "reasoningEffort": "none" }, "models": {} }));
+            let result = transform_with(json!({ "model": model, "input": [] }), |params| {
+                params.user_config = Some(Box::leak(Box::new(config)))
+            });
+            assert_eq!(result.model.as_deref(), Some("gpt-5.3-codex"), "{model}");
+            assert_eq!(effort_of(&result), "low", "{model}");
+        }
+
+        // none preserved for general models that support it.
+        let config = user_config(json!({ "global": { "reasoningEffort": "none" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5.2-none", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(result.model.as_deref(), Some("gpt-5.2"));
+        assert_eq!(effort_of(&result), "none");
+
+        let config = user_config(json!({ "global": { "reasoningEffort": "none" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5.1-none", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(result.model.as_deref(), Some("gpt-5.1"));
+        assert_eq!(effort_of(&result), "none");
+    }
+
+    #[test]
+    fn codex_defaults_and_xhigh_preservation() {
+        // Deprecated aliases route to the current codex model, default high.
+        for model in ["gpt-5.1-codex-max", "gpt-5.2-codex", "gpt-5.3-codex", "gpt-5.3-codex-spark"] {
+            let result = transform(json!({ "model": model, "input": [] }));
+            assert_eq!(result.model.as_deref(), Some("gpt-5.3-codex"), "{model}");
+            assert_eq!(effort_of(&result), "high", "{model}");
+        }
+
+        // Per-model xhigh config on the exact variant key is honored.
+        let config = user_config(json!({
+            "global": { "reasoningSummary": "auto" },
+            "models": {
+                "gpt-5.1-codex-max-xhigh": { "options": { "reasoningEffort": "xhigh", "reasoningSummary": "detailed" } }
+            }
+        }));
+        let result = transform_with(
+            json!({ "model": "gpt-5.1-codex-max-xhigh", "input": [] }),
+            |params| params.user_config = Some(Box::leak(Box::new(config))),
+        );
+        assert_eq!(result.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(effort_of(&result), "xhigh");
+        assert_eq!(summary_of(&result), "detailed");
+
+        // Global xhigh survives on codex (supported)…
+        let config = user_config(json!({ "global": { "reasoningEffort": "xhigh" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5.1-codex-high", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(result.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(effort_of(&result), "xhigh");
+
+        // …and codex-mini aliases keep the requested xhigh too.
+        let config = user_config(json!({ "global": { "reasoningEffort": "xhigh" }, "models": {} }));
+        let result = transform_with(
+            json!({ "model": "gpt-5.1-codex-mini-high", "input": [] }),
+            |params| params.user_config = Some(Box::leak(Box::new(config))),
+        );
+        assert_eq!(result.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(effort_of(&result), "xhigh");
+    }
+
+    #[test]
+    fn downgrades_xhigh_to_high_for_non_max_general_models() {
+        let config = user_config(json!({ "global": { "reasoningEffort": "xhigh" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5.1-high", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(result.model.as_deref(), Some("gpt-5.1"));
+        assert_eq!(effort_of(&result), "high");
+    }
+
+    #[test]
+    fn gpt55_reasoning_defaults_before_unsupported_model_fallback() {
+        let config = user_config(json!({ "global": { "reasoningEffort": "minimal" }, "models": {} }));
+        let result = transform_with(json!({ "model": "gpt-5.5-high", "input": [] }), |params| {
+            params.user_config = Some(Box::leak(Box::new(config)))
+        });
+        assert_eq!(result.model.as_deref(), Some("gpt-5.5"));
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(verbosity_of(&result), "medium");
+    }
+
+    #[test]
+    fn uses_medium_effort_for_lightweight_models() {
+        let result = transform(json!({ "model": "gpt-5-nano", "input": [] }));
+        assert_eq!(effort_of(&result), "medium");
+    }
+
+    // --- fast session --------------------------------------------------------
+
+    fn fast(value: Value, strategy: FastSessionStrategy) -> RequestBody {
+        transform_with(value, |params| {
+            params.fast_session = true;
+            params.fast_session_strategy = strategy;
+        })
+    }
+
+    #[test]
+    fn clamps_reasoning_and_text_for_fast_session_on_codex_models() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn allows_none_reasoning_for_fast_session_on_gpt51_general() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.1",
+                "input": [],
+                "reasoning": { "effort": "high", "summary": "auto" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "none");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn keeps_full_depth_settings_for_complex_prompts_in_hybrid_strategy() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{
+                    "type": "message",
+                    "role": "user",
+                    "content": "Please handle this request in depth:\n1. Inspect auth flow state transitions.\n2. Compare retry and backoff behavior.\n3. Explain likely failure modes.\n4. Propose fixes with tradeoffs.",
+                }],
+                "tools": [{ "type": "function", "function": { "name": "read_file" } }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "xhigh");
+        assert_eq!(summary_of(&result), "detailed");
+        assert_eq!(verbosity_of(&result), "high");
+    }
+
+    #[test]
+    fn compacts_long_instructions_for_trivial_turns_in_hybrid_strategy() {
+        let long_instructions = format!("RULES\n{}", "x".repeat(5000));
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{ "type": "message", "role": "user", "content": "hi" }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+            }),
+            |params| {
+                params.codex_instructions = Box::leak(long_instructions.clone().into_boxed_str());
+                params.fast_session = true;
+            },
+        );
+        let instructions = result.instructions.as_deref().unwrap();
+        assert!(instructions.len() < long_instructions.len());
+        assert!(instructions.contains("Fast session mode"));
+        assert_eq!(summary_of(&result), "auto");
+    }
+
+    #[test]
+    fn keeps_long_instructions_for_complex_turns_in_hybrid_strategy() {
+        let long_instructions = format!("RULES\n{}", "x".repeat(5000));
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{
+                    "type": "message",
+                    "role": "user",
+                    "content": "Please perform deep analysis:\n1. inspect auth flow\n2. inspect retries\n3. explain tradeoffs",
+                }],
+            }),
+            |params| {
+                params.codex_instructions = Box::leak(long_instructions.clone().into_boxed_str());
+                params.fast_session = true;
+            },
+        );
+        assert_eq!(result.instructions.as_deref(), Some(long_instructions.as_str()));
+    }
+
+    #[test]
+    fn applies_fast_settings_for_simple_prompts_and_disables_tools() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{ "type": "message", "role": "user", "content": "hi" }],
+                "tools": [{ "type": "function", "function": { "name": "read_file" } }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+        assert!(result.tools.is_none());
+    }
+
+    #[test]
+    fn keeps_fast_settings_for_short_multi_turn_chat_in_hybrid_strategy() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [
+                    { "type": "message", "role": "user", "content": "hi" },
+                    { "type": "message", "role": "assistant", "content": "hey" },
+                    { "type": "message", "role": "user", "content": "yo" },
+                    { "type": "message", "role": "assistant", "content": "sup" },
+                    { "type": "message", "role": "user", "content": "ok" },
+                ],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn drops_medium_length_head_scaffolds_for_trivial_turns() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [
+                    { "type": "message", "role": "developer", "content": format!("HEAD {}", "x".repeat(700)) },
+                    { "type": "message", "role": "user", "content": "hello" },
+                ],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        let has_head = result.input.as_deref().unwrap_or(&[]).iter().any(|item| {
+            item.role.as_deref() == Some("developer")
+                && extract_message_text(item.content.as_ref()).contains("HEAD")
+        });
+        assert!(!has_head);
+        assert_eq!(summary_of(&result), "auto");
+    }
+
+    #[test]
+    fn ultra_compacts_trivial_turns_in_hybrid_strategy() {
+        let mut input = vec![json!({ "type": "message", "role": "developer", "content": "Small stable scaffold" })];
+        for i in 0..18 {
+            input.push(json!({
+                "type": "message",
+                "role": if i % 2 == 0 { "assistant" } else { "user" },
+                "content": format!("history-{i}"),
+            }));
+        }
+        input.push(json!({ "type": "message", "role": "user", "content": "yo" }));
+
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.1",
+                "input": input,
+                "reasoning": { "effort": "high", "summary": "auto" },
+                "text": { "verbosity": "high" },
+            }),
+            |params| {
+                params.fast_session = true;
+                params.fast_session_max_input_items = 8;
+            },
+        );
+        let items = result.input.as_deref().unwrap();
+        assert!(items.len() <= 2);
+        let latest_user = items
+            .iter()
+            .rev()
+            .find(|item| item.role.as_deref() == Some("user"))
+            .unwrap();
+        assert_eq!(
+            latest_user.content.as_ref().and_then(Value::as_str),
+            Some("yo")
+        );
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn applies_fast_settings_when_tool_history_is_old_but_recent_turn_is_simple() {
+        let mut input = vec![json!({
+            "type": "function_call_output", "call_id": "old_1", "name": "read_file", "output": "{}"
+        })];
+        for i in 0..20 {
+            input.push(json!({
+                "type": "message",
+                "role": if i % 2 == 0 { "assistant" } else { "user" },
+                "content": format!("filler-{i}"),
+            }));
+        }
+        input.push(json!({ "type": "message", "role": "user", "content": "hi" }));
+
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": input,
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn keeps_full_depth_settings_when_recent_tool_call_history_exists() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [
+                    { "type": "message", "role": "user", "content": "quick check" },
+                    { "type": "function_call_output", "call_id": "recent_1", "name": "read_file", "output": "{}" },
+                ],
+                "tools": [{ "type": "function", "function": { "name": "read_file" } }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "xhigh");
+        assert_eq!(summary_of(&result), "detailed");
+        assert_eq!(verbosity_of(&result), "high");
+        assert_eq!(
+            tools_json(&result),
+            json!([{ "type": "function", "function": { "name": "read_file" } }])
+        );
+    }
+
+    #[test]
+    fn fast_settings_when_latest_user_prompt_is_trivial_even_after_complex_history() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [
+                    {
+                        "type": "message",
+                        "role": "user",
+                        "content": "Please analyze this thoroughly:\n- identify failure paths\n- map dependencies\n- suggest mitigations\n- call out risks",
+                    },
+                    { "type": "message", "role": "assistant", "content": "Understood." },
+                    { "type": "message", "role": "user", "content": "hi" },
+                ],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Hybrid,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn always_strategy_compacts_context_without_overriding_instructions() {
+        let mut input = vec![json!({ "type": "message", "role": "developer", "content": "Core instruction scaffold" })];
+        for i in 0..24 {
+            input.push(json!({
+                "type": "message",
+                "role": if i % 2 == 0 { "assistant" } else { "user" },
+                "content": format!("history-{i}"),
+            }));
+        }
+        input.push(json!({ "type": "message", "role": "user", "content": "hi" }));
+
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": input,
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            |params| {
+                params.fast_session = true;
+                params.fast_session_strategy = FastSessionStrategy::Always;
+                params.fast_session_max_input_items = 12;
+            },
+        );
+        let items = result.input.as_deref().unwrap();
+        assert!(items.len() <= 12);
+        let last_user = items
+            .iter()
+            .rev()
+            .find(|item| item.role.as_deref() == Some("user"))
+            .unwrap();
+        assert_eq!(last_user.content.as_ref().and_then(Value::as_str), Some("hi"));
+        assert_eq!(result.instructions.as_deref(), Some(CODEX_INSTRUCTIONS));
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(verbosity_of(&result), "low");
+    }
+
+    #[test]
+    fn always_strategy_forces_fast_settings_for_complex_prompts_but_keeps_tools() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{
+                    "type": "message",
+                    "role": "user",
+                    "content": "Please perform a full review:\n1. inspect account rotation\n2. inspect refresh queue\n3. inspect retry windows\n4. summarize issues and improvements",
+                }],
+                "tools": [{ "type": "function", "function": { "name": "read_file" } }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Always,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert_eq!(summary_of(&result), "auto");
+        assert_eq!(verbosity_of(&result), "low");
+        assert_eq!(
+            tools_json(&result),
+            json!([{ "type": "function", "function": { "name": "read_file" } }])
+        );
+    }
+
+    #[test]
+    fn always_strategy_disables_tools_for_trivial_turns() {
+        let result = fast(
+            json!({
+                "model": "gpt-5.3-codex",
+                "input": [{ "type": "message", "role": "user", "content": "hi" }],
+                "tools": [{ "type": "function", "function": { "name": "read_file" } }],
+                "reasoning": { "effort": "xhigh", "summary": "detailed" },
+                "text": { "verbosity": "high" },
+            }),
+            FastSessionStrategy::Always,
+        );
+        assert_eq!(effort_of(&result), "low");
+        assert!(result.tools.is_none());
+    }
+
+    #[test]
+    fn defers_fast_session_input_trimming_when_requested() {
+        let input: Vec<Value> = (0..12)
+            .map(|index| {
+                json!({
+                    "type": "message",
+                    "role": if index == 0 { "developer" } else { "user" },
+                    "content": if index == 0 { "system prompt".to_string() } else { format!("message-{index}") },
+                })
+            })
+            .collect();
+        let result = transform_with(json!({ "model": "gpt-5.4", "input": input }), |params| {
+            params.fast_session = true;
+            params.fast_session_strategy = FastSessionStrategy::Always;
+            params.fast_session_max_input_items = 8;
+            params.defer_fast_session_input_trimming = true;
+        });
+        assert_eq!(result.input.as_deref().unwrap().len(), 12);
+    }
+
+    // --- input surgery through the pipeline ---------------------------------
+
+    #[test]
+    fn removes_ids_from_input_array() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [
+                { "id": "rs_123", "type": "message", "role": "assistant", "content": "old" },
+                { "type": "message", "role": "user", "content": "new" },
+            ],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 2);
+        assert!(items.iter().all(|item| item.id.is_none()));
+        assert_eq!(items[0].content.as_ref().and_then(Value::as_str), Some("old"));
+        assert_eq!(items[1].content.as_ref().and_then(Value::as_str), Some("new"));
+    }
+
+    #[test]
+    fn adds_bridge_message_when_tools_present_in_codex_mode() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{ "type": "message", "role": "user", "content": "hello" }],
+            "tools": [{ "name": "test_tool" }],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 2);
+        assert_eq!(items[0].role.as_deref(), Some("developer"));
+        assert_eq!(
+            items[0].content.as_ref().unwrap()[0]["text"].as_str(),
+            Some(TEST_BRIDGE)
+        );
+    }
+
+    #[test]
+    fn filters_codex_prompts_in_codex_mode() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [
+                { "type": "message", "role": "developer", "content": "You are a coding agent running in the Codex" },
+                { "type": "message", "role": "user", "content": "hello" },
+            ],
+            "tools": [{ "name": "test_tool" }],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 2);
+        assert_eq!(items[0].role.as_deref(), Some("developer"));
+        assert_eq!(
+            items[0].content.as_ref().unwrap()[0]["text"].as_str(),
+            Some(TEST_BRIDGE)
+        );
+        assert_eq!(items[1].role.as_deref(), Some("user"));
+    }
+
+    #[test]
+    fn no_message_added_without_tools() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{ "type": "message", "role": "user", "content": "hello" }],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 1);
+        assert_eq!(items[0].role.as_deref(), Some("user"));
+    }
+
+    #[test]
+    fn uses_tool_remap_message_and_keeps_codex_prompts_when_codex_mode_off() {
+        let result = transform_with(
+            json!({
+                "model": "gpt-5",
+                "input": [
+                    { "type": "message", "role": "developer", "content": "You are a coding agent running in the Codex" },
+                    { "type": "message", "role": "user", "content": "hello" },
+                ],
+                "tools": [{ "name": "test_tool" }],
+            }),
+            |params| params.codex_mode = false,
+        );
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 3);
+        assert_eq!(items[0].role.as_deref(), Some("developer"));
+        let remap_text = items[0].content.as_ref().unwrap()[0]["text"].as_str().unwrap();
+        assert!(remap_text.contains("apply_patch"));
+        assert!(remap_text.contains("patch (preferred if available)"));
+        assert_eq!(items[1].role.as_deref(), Some("developer"));
+        assert_eq!(items[2].role.as_deref(), Some("user"));
+    }
+
+    #[test]
+    fn converts_orphaned_function_call_output_to_message() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [
+                { "type": "message", "role": "user", "content": "hello" },
+                { "type": "function_call_output", "role": "assistant", "call_id": "orphan_call", "name": "read", "output": "{}" },
+            ],
+        }));
+        assert!(result.tools.is_none());
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 2);
+        assert_eq!(items[0].kind.as_deref(), Some("message"));
+        assert_eq!(items[1].kind.as_deref(), Some("message"));
+        assert_eq!(items[1].role.as_deref(), Some("assistant"));
+        assert!(
+            items[1]
+                .content
+                .as_ref()
+                .and_then(Value::as_str)
+                .unwrap()
+                .contains("[Previous read result; call_id=orphan_call]")
+        );
+    }
+
+    #[test]
+    fn keeps_matched_tool_call_pairs() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [
+                { "type": "message", "role": "user", "content": "hello" },
+                { "type": "function_call", "call_id": "call_1", "name": "write", "arguments": "{}" },
+                { "type": "function_call_output", "call_id": "call_1", "output": "success" },
+            ],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 3);
+        assert_eq!(items[1].kind.as_deref(), Some("function_call"));
+        assert_eq!(items[2].kind.as_deref(), Some("function_call_output"));
+    }
+
+    #[test]
+    fn treats_local_shell_call_as_match_for_function_call_output() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [
+                { "type": "message", "role": "user", "content": "hello" },
+                { "type": "local_shell_call", "call_id": "shell_call", "action": { "type": "exec", "command": ["ls"] } },
+                { "type": "function_call_output", "call_id": "shell_call", "output": "ok" },
+            ],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 3);
+        assert_eq!(items[1].kind.as_deref(), Some("local_shell_call"));
+        assert_eq!(items[2].kind.as_deref(), Some("function_call_output"));
+    }
+
+    #[test]
+    fn keeps_matching_and_converts_orphaned_custom_tool_call_outputs() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [
+                { "type": "message", "role": "user", "content": "hello" },
+                { "type": "custom_tool_call", "call_id": "custom_call", "name": "mcp_tool", "input": "{}" },
+                { "type": "custom_tool_call_output", "call_id": "custom_call", "output": "done" },
+            ],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 3);
+        assert_eq!(items[1].kind.as_deref(), Some("custom_tool_call"));
+        assert_eq!(items[2].kind.as_deref(), Some("custom_tool_call_output"));
+
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [
+                { "type": "message", "role": "user", "content": "hello" },
+                { "type": "custom_tool_call_output", "call_id": "orphan_custom", "output": "oops" },
+            ],
+        }));
+        let items = result.input.as_deref().unwrap();
+        assert_eq!(items.len(), 2);
+        assert_eq!(items[1].kind.as_deref(), Some("message"));
+        assert!(
+            items[1]
+                .content
+                .as_ref()
+                .and_then(Value::as_str)
+                .unwrap()
+                .contains("[Previous tool result; call_id=orphan_custom]")
+        );
+    }
+
+    // --- collaboration mode & capability sanitization -----------------------
+
+    fn tool_names(body: &RequestBody) -> Vec<String> {
+        tools_json(body)
+            .as_array()
+            .map(|tools| {
+                tools
+                    .iter()
+                    .filter_map(|tool| tool["function"]["name"].as_str().map(str::to_string))
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+
+    #[test]
+    fn removes_request_user_input_tool_in_default_collaboration_mode() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{
+                "type": "message",
+                "role": "developer",
+                "content": [{ "type": "input_text", "text": "# Collaboration Mode: Default" }],
+            }],
+            "tools": [
+                { "type": "function", "function": { "name": "request_user_input", "parameters": { "type": "object", "properties": {} } } },
+                { "type": "function", "function": { "name": "exec_command", "parameters": { "type": "object", "properties": {} } } },
+            ],
+        }));
+        assert_eq!(tool_names(&result), vec!["exec_command".to_string()]);
+    }
+
+    #[test]
+    fn keeps_request_user_input_tool_in_plan_collaboration_mode() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{
+                "type": "message",
+                "role": "developer",
+                "content": [{ "type": "input_text", "text": "# Collaboration Mode: Plan" }],
+            }],
+            "tools": [
+                { "type": "function", "function": { "name": "request_user_input", "parameters": { "type": "object", "properties": {} } } },
+            ],
+        }));
+        assert_eq!(tool_names(&result), vec!["request_user_input".to_string()]);
+    }
+
+    #[test]
+    fn removes_nested_request_user_input_tools_outside_plan_mode() {
+        // No collaboration signal at all → "unknown" also removes plan-only tools.
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [],
+            "tools": [{
+                "type": "namespace",
+                "name": "planner",
+                "tools": [
+                    { "type": "function", "function": { "name": "request_user_input", "parameters": { "type": "object", "properties": {} } } },
+                    { "type": "function", "function": { "name": "exec_command", "parameters": { "type": "object", "properties": {} } } },
+                ],
+            }],
+        }));
+        let tools = tools_json(&result);
+        assert_eq!(tools[0]["type"], json!("namespace"));
+        assert_eq!(tools[0]["name"], json!("planner"));
+        let nested = tools[0]["tools"].as_array().unwrap();
+        assert_eq!(nested.len(), 1);
+        assert_eq!(nested[0]["function"]["name"], json!("exec_command"));
+    }
+
+    #[test]
+    fn drops_namespace_entirely_when_all_plan_only_tools_are_removed() {
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{
+                "type": "message",
+                "role": "developer",
+                "content": [{ "type": "input_text", "text": "# Collaboration Mode: Default" }],
+            }],
+            "tools": [{
+                "type": "namespace",
+                "name": "planner",
+                "tools": [
+                    { "type": "function", "function": { "name": "request_user_input", "parameters": { "type": "object", "properties": {} } } },
+                ],
+            }],
+        }));
+        assert!(result.tools.is_none());
+    }
+
+    #[test]
+    fn removes_tool_search_when_model_lacks_search_capability() {
+        let result = transform(json!({
+            "model": "gpt-5-nano",
+            "input": [],
+            "tools": [
+                { "type": "tool_search", "max_num_results": 3 },
+                { "type": "mcp", "server_label": "docs", "server_url": "https://mcp.example.com", "defer_loading": true },
+            ],
+        }));
+        assert_eq!(
+            tools_json(&result),
+            json!([
+                { "type": "mcp", "server_label": "docs", "server_url": "https://mcp.example.com", "defer_loading": true }
+            ])
+        );
+    }
+
+    #[test]
+    fn gpt55_pro_capability_surface_keeps_computer_use_but_drops_tool_search() {
+        let config = user_config(json!({ "global": { "reasoningEffort": "low" }, "models": {} }));
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.5-pro",
+                "input": [],
+                "tools": [
+                    { "type": "tool_search", "max_num_results": 3 },
+                    { "type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser" },
+                ],
+            }),
+            |params| params.user_config = Some(Box::leak(Box::new(config))),
+        );
+        assert_eq!(result.model.as_deref(), Some("gpt-5.5-pro"));
+        assert_eq!(effort_of(&result), "medium");
+        assert_eq!(verbosity_of(&result), "medium");
+        assert_eq!(
+            tools_json(&result),
+            json!([
+                { "type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser" }
+            ])
+        );
+    }
+
+    #[test]
+    fn removes_computer_tools_when_model_lacks_computer_use() {
+        let result = transform(json!({
+            "model": "gpt-5-nano",
+            "input": [],
+            "tools": [
+                { "type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser" },
+                { "type": "tool_search", "max_num_results": 1 },
+            ],
+        }));
+        assert!(result.tools.is_none());
+        assert_eq!(result.input.as_deref().unwrap().len(), 0);
+    }
+
+    #[test]
+    fn filters_unsupported_tools_from_nested_namespaces() {
+        let result = transform(json!({
+            "model": "gpt-5-nano",
+            "input": [],
+            "tools": [{
+                "type": "namespace",
+                "name": "outer_suite",
+                "tools": [{
+                    "type": "namespace",
+                    "name": "inner_suite",
+                    "tools": [
+                        { "type": "tool_search", "max_num_results": 2 },
+                        { "type": "mcp", "server_label": "remote-docs", "server_url": "https://mcp.example.com", "defer_loading": true },
+                    ],
+                }],
+            }],
+        }));
+        assert_eq!(
+            tools_json(&result),
+            json!([{
+                "type": "namespace",
+                "name": "outer_suite",
+                "tools": [{
+                    "type": "namespace",
+                    "name": "inner_suite",
+                    "tools": [
+                        { "type": "mcp", "server_label": "remote-docs", "server_url": "https://mcp.example.com", "defer_loading": true }
+                    ],
+                }],
+            }])
+        );
+    }
+
+    #[test]
+    #[serial_test::serial(env)]
+    fn env_collaboration_mode_overrides_input_detection() {
+        let mut sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        sandbox.set_var("CODEX_COLLABORATION_MODE", "plan");
+        // Input says Default, but the env override forces plan mode → the
+        // plan-only tool survives.
+        let result = transform(json!({
+            "model": "gpt-5",
+            "input": [{
+                "type": "message",
+                "role": "developer",
+                "content": [{ "type": "input_text", "text": "# Collaboration Mode: Default" }],
+            }],
+            "tools": [
+                { "type": "function", "function": { "name": "request_user_input", "parameters": { "type": "object", "properties": {} } } },
+            ],
+        }));
+        assert_eq!(tool_names(&result), vec!["request_user_input".to_string()]);
+    }
+
+    // --- tool schema cleaning through the pipeline ---------------------------
+
+    #[test]
+    fn cleans_tool_schemas_through_the_pipeline() {
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [],
+            "tools": [{
+                "type": "function",
+                "function": {
+                    "name": "test_tool",
+                    "parameters": {
+                        "type": "object",
+                        "properties": { "valid_param": { "type": "string" } },
+                        "required": ["valid_param", "invalid_param"],
+                    },
+                },
+            }],
+        }));
+        let tools = tools_json(&result);
+        assert_eq!(
+            tools[0]["function"]["parameters"]["required"],
+            json!(["valid_param"])
+        );
+
+        let result = transform(json!({
+            "model": "gpt-5-codex",
+            "input": [],
+            "tools": [{
+                "type": "function",
+                "function": {
+                    "name": "void_tool",
+                    "parameters": { "type": "object", "properties": {} },
+                },
+            }],
+        }));
+        let tools = tools_json(&result);
+        assert!(
+            tools[0]["function"]["parameters"]["properties"]
+                .get("_placeholder")
+                .is_some()
+        );
+    }
+
+    // --- background mode ------------------------------------------------------
+
+    #[test]
+    fn rejects_background_mode_unless_explicitly_enabled() {
+        let err = transform_request_body(base_params(json!({
+            "model": "gpt-5.4",
+            "background": true,
+            "input": [{ "type": "message", "role": "user", "content": "hello" }],
+        })))
+        .unwrap_err();
+        assert_eq!(
+            err.to_string(),
+            "Responses background mode is disabled. Enable pluginConfig.backgroundResponses or CODEX_AUTH_BACKGROUND_RESPONSES=1 to opt in."
+        );
+    }
+
+    #[test]
+    fn preserves_stateful_request_fields_when_background_mode_is_enabled() {
+        let result = transform_with(
+            json!({
+                "model": "gpt-5.4",
+                "background": true,
+                "input": [{ "id": "msg_stateful_123", "type": "message", "role": "user", "content": "hello" }],
+            }),
+            |params| {
+                params.fast_session = true;
+                params.fast_session_strategy = FastSessionStrategy::Always;
+                params.fast_session_max_input_items = 12;
+                params.allow_background_responses = true;
+            },
+        );
+        assert_eq!(result.background, Some(true));
+        assert_eq!(result.store, Some(true));
+        assert!(result.include.is_none());
+        assert_eq!(verbosity_of(&result), "medium");
+        let user_item = result
+            .input
+            .as_deref()
+            .unwrap()
+            .iter()
+            .find(|item| item.role.as_deref() == Some("user"))
+            .unwrap();
+        assert_eq!(user_item.id.as_deref(), Some("msg_stateful_123"));
+        assert_eq!(user_item.kind.as_deref(), Some("message"));
+        assert_eq!(
+            user_item.content.as_ref().and_then(Value::as_str),
+            Some("hello")
+        );
+    }
+
+    #[test]
+    fn rejects_background_mode_when_store_false_is_forced() {
+        let expected = "Responses background mode requires store=true and cannot be combined with stateless store=false routing.";
+
+        let err = transform_request_body({
+            let mut params = base_params(json!({
+                "model": "gpt-5.4",
+                "background": true,
+                "store": false,
+                "input": [{ "type": "message", "role": "user", "content": "hello" }],
+            }));
+            params.allow_background_responses = true;
+            params
+        })
+        .unwrap_err();
+        assert_eq!(err.to_string(), expected);
+
+        let err = transform_request_body({
+            let mut params = base_params(json!({
+                "model": "gpt-5.4",
+                "background": true,
+                "providerOptions": { "openai": { "store": false } },
+                "input": [{ "type": "message", "role": "user", "content": "hello" }],
+            }));
+            params.allow_background_responses = true;
+            params
+        })
+        .unwrap_err();
+        assert_eq!(err.to_string(), expected);
+    }
+
+    // --- trimInputForFastSession ---------------------------------------------
+
+    #[test]
+    fn trim_preserves_leading_developer_instruction_outside_the_tail_window() {
+        let mut input: Vec<InputItem> = vec![
+            from_value(json!({ "type": "message", "role": "developer", "content": "HEAD_INSTRUCTION" })).unwrap(),
+        ];
+        for i in 1..50 {
+            input.push(
+                from_value(json!({ "type": "message", "role": "user", "content": format!("msg-{i}") }))
+                    .unwrap(),
+            );
+        }
+
+        let max_items = 30;
+        let result = trim_input_for_fast_session(Some(input), max_items, false).unwrap();
+
+        assert_eq!(
+            result[0].content.as_ref().and_then(Value::as_str),
+            Some("HEAD_INSTRUCTION")
+        );
+        assert_eq!(result[0].role.as_deref(), Some("developer"));
+        assert_eq!(
+            result[result.len() - 1]
+                .content
+                .as_ref()
+                .and_then(Value::as_str),
+            Some("msg-49")
+        );
+        // Fills the item budget exactly.
+        assert_eq!(result.len() as i64, max_items);
+    }
+
+    #[test]
+    fn trim_keeps_every_preserved_head_instruction_when_input_just_exceeds_budget() {
+        let max_items: i64 = 10;
+        let mut input: Vec<InputItem> = vec![
+            from_value(json!({ "type": "message", "role": "developer", "content": "HEAD_ONE" })).unwrap(),
+            from_value(json!({ "type": "message", "role": "system", "content": "HEAD_TWO" })).unwrap(),
+        ];
+        for i in 2..=max_items {
+            input.push(
+                from_value(json!({ "type": "message", "role": "user", "content": format!("msg-{i}") }))
+                    .unwrap(),
+            );
+        }
+        assert_eq!(input.len() as i64, max_items + 1);
+
+        let result = trim_input_for_fast_session(Some(input), max_items, false).unwrap();
+
+        assert_eq!(
+            result[0].content.as_ref().and_then(Value::as_str),
+            Some("HEAD_ONE")
+        );
+        assert_eq!(
+            result[1].content.as_ref().and_then(Value::as_str),
+            Some("HEAD_TWO")
+        );
+        assert_eq!(
+            result[result.len() - 1]
+                .content
+                .as_ref()
+                .and_then(Value::as_str),
+            Some(format!("msg-{max_items}").as_str())
+        );
+        assert_eq!(result.len() as i64, max_items);
+    }
+
+    #[test]
+    fn trim_returns_input_untouched_when_within_budget() {
+        let input: Vec<InputItem> = from_value(json!([
+            { "type": "message", "role": "user", "content": "a" },
+            { "type": "message", "role": "assistant", "content": "b" },
+        ]))
+        .unwrap();
+        let result = trim_input_for_fast_session(Some(input.clone()), 30, false).unwrap();
+        assert_eq!(result, input);
+        assert!(trim_input_for_fast_session(None, 30, false).is_none());
+    }
+}
diff --git a/crates/request/src/url_rewriting.rs b/crates/request/src/url_rewriting.rs
new file mode 100644
index 000000000..bf57c8810
--- /dev/null
+++ b/crates/request/src/url_rewriting.rs
@@ -0,0 +1,527 @@
+//! Port of `lib/request/url-rewriting.ts` — URL rewrite & proxy resolution.
+//!
+//! Behavior source: spec 06 §9 + the TS source (authority).
+//!
+//! Proxy transport mapping: the TS module caches undici `ProxyAgent`
+//! dispatchers per proxy URL and attaches them to `RequestInit`. reqwest
+//! attaches proxies at `Client` build time, so the Rust analogue caches one
+//! `reqwest::Client` per proxy URL ([`resolve_client_for_request`]) and falls
+//! back to the shared proxy-free client from `fetch_helpers`
+//! (ARCHITECTURE §5.1: explicit `reqwest::Proxy` wiring lives here).
+
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+
+use cma_core::constants::{CODEX_BASE_URL, URL_PATHS};
+use cma_core::logger::log_warn;
+use serde_json::json;
+use url::Url;
+
+use crate::request_init::FetchInput;
+
+fn codex_base_url() -> &'static Url {
+    static BASE: OnceLock<Url> = OnceLock::new();
+    BASE.get_or_init(|| Url::parse(CODEX_BASE_URL).expect("CODEX_BASE_URL must parse"))
+}
+
+/// `/backend-api` — the Codex base path with any trailing slash stripped.
+fn codex_base_path_prefix() -> &'static str {
+    static PREFIX: OnceLock<String> = OnceLock::new();
+    PREFIX.get_or_init(|| {
+        let path = codex_base_url().path();
+        path.strip_suffix('/').unwrap_or(path).to_string()
+    })
+}
+
+/// Environment snapshot used for proxy resolution. The TS module reads
+/// `process.env` (own-key semantics); tests pass explicit maps.
+pub type EnvMap = HashMap<String, String>;
+
+/// Snapshot the process environment (exact key case, one entry per var).
+pub fn process_env_map() -> EnvMap {
+    std::env::vars().collect()
+}
+
+/// TS `extractRequestUrl(input)` — URL string from any fetch input shape.
+pub fn extract_request_url(input: &FetchInput<'_>) -> String {
+    match input {
+        FetchInput::Url(text) => (*text).to_string(),
+        FetchInput::Parsed(url) => url.to_string(),
+        FetchInput::Request(request) => request.url.clone(),
+    }
+}
+
+/// TS `rewriteUrlForCodex(url)`.
+///
+/// - `/responses` (first occurrence in the path) → `/codex/responses`;
+/// - path is prefixed with `/backend-api` unless it already equals/starts
+///   with it;
+/// - protocol+host are forced to `https://chatgpt.com` (no port), userinfo is
+///   cleared; query/fragment survive.
+///
+/// Invalid URLs error (the TS version throws `TypeError`).
+pub fn rewrite_url_for_codex(url: &str) -> Result<String, url::ParseError> {
+    let mut parsed = Url::parse(url)?;
+    let base = codex_base_url();
+
+    let path = parsed.path().to_string();
+    let rewritten = if path.contains(URL_PATHS.responses) {
+        path.replacen(URL_PATHS.responses, URL_PATHS.codex_responses, 1)
+    } else {
+        path
+    };
+    let prefix = codex_base_path_prefix();
+    let normalized = if rewritten == prefix || rewritten.starts_with(&format!("{prefix}/")) {
+        rewritten
+    } else if rewritten.starts_with('/') {
+        format!("{prefix}{rewritten}")
+    } else {
+        format!("{prefix}/{rewritten}")
+    };
+
+    // Assignment order mirrors the TS property writes; none of these can fail
+    // for an http(s) URL rewritten onto the https Codex origin.
+    let _ = parsed.set_scheme(base.scheme());
+    let _ = parsed.set_username("");
+    let _ = parsed.set_password(None);
+    let _ = parsed.set_host(base.host_str());
+    let _ = parsed.set_port(base.port());
+    parsed.set_path(&normalized);
+
+    Ok(parsed.to_string())
+}
+
+/// Own-key env resolution (spec 06 §24): when the lowercase key EXISTS its
+/// trimmed value wins — an empty value disables the variable entirely with NO
+/// fallback to the uppercase key. Otherwise the uppercase key's trimmed value
+/// is used (empty → `None`).
+fn resolve_proxy_env_value(env: &EnvMap, lower_key: &str, upper_key: &str) -> Option<String> {
+    if let Some(value) = env.get(lower_key) {
+        let trimmed = value.trim();
+        return if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed.to_string())
+        };
+    }
+    env.get(upper_key)
+        .map(|value| value.trim())
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+}
+
+struct NoProxyEntry {
+    hostname: String,
+    port: u32,
+}
+
+fn parse_no_proxy_entries(no_proxy_value: &str) -> Vec<NoProxyEntry> {
+    no_proxy_value
+        .split([',', ' ', '\t', '\n', '\r', '\u{0c}', '\u{0b}'])
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .map(|entry| {
+            // TS `/^(.+):(\d+)$/` — greedy host capture, trailing digit port.
+            if let Some(idx) = entry.rfind(':') {
+                let (host, port_text) = (&entry[..idx], &entry[idx + 1..]);
+                if !host.is_empty()
+                    && !port_text.is_empty()
+                    && port_text.bytes().all(|b| b.is_ascii_digit())
+                {
+                    return NoProxyEntry {
+                        hostname: host.to_lowercase(),
+                        port: port_text.parse().unwrap_or(0),
+                    };
+                }
+            }
+            NoProxyEntry {
+                hostname: entry.to_lowercase(),
+                port: 0,
+            }
+        })
+        .collect()
+}
+
+fn should_bypass_proxy_for_url(url: &Url, no_proxy_value: Option<&str>) -> bool {
+    let Some(no_proxy_value) = no_proxy_value else {
+        return false;
+    };
+    if no_proxy_value == "*" {
+        return true;
+    }
+
+    let hostname = url.host_str().unwrap_or("").to_lowercase();
+    let port: u32 = url
+        .port()
+        .map(u32::from)
+        .or_else(|| match url.scheme() {
+            "http" => Some(80),
+            "https" => Some(443),
+            _ => None,
+        })
+        .unwrap_or(0);
+
+    for entry in parse_no_proxy_entries(no_proxy_value) {
+        if entry.hostname == "*" {
+            return true;
+        }
+        if entry.port != 0 && entry.port != port {
+            continue;
+        }
+
+        if !entry.hostname.starts_with('.') && !entry.hostname.starts_with('*') {
+            if hostname == entry.hostname {
+                return true;
+            }
+            continue;
+        }
+
+        let suffix = entry.hostname.strip_prefix('*').unwrap_or(&entry.hostname);
+        if hostname.ends_with(suffix) {
+            return true;
+        }
+    }
+
+    false
+}
+
+/// TS `resolveProxyUrlForRequest(url, env)` — proxy URL for the request, or
+/// `None` (direct). Invalid URLs resolve to `None` (the TS version throws;
+/// callers only pass URLs that already survived `rewriteUrlForCodex`).
+pub fn resolve_proxy_url_for_request(url: &str, env: &EnvMap) -> Option<String> {
+    let parsed = Url::parse(url).ok()?;
+    if parsed.scheme() != "http" && parsed.scheme() != "https" {
+        return None;
+    }
+
+    let http_proxy = resolve_proxy_env_value(env, "http_proxy", "HTTP_PROXY");
+    let https_proxy = resolve_proxy_env_value(env, "https_proxy", "HTTPS_PROXY");
+    if http_proxy.is_none() && https_proxy.is_none() {
+        return None;
+    }
+
+    let no_proxy = resolve_proxy_env_value(env, "no_proxy", "NO_PROXY");
+    if should_bypass_proxy_for_url(&parsed, no_proxy.as_deref()) {
+        return None;
+    }
+
+    if parsed.scheme() == "https" {
+        https_proxy.or(http_proxy)
+    } else {
+        http_proxy
+    }
+}
+
+fn shared_proxy_clients() -> &'static Mutex<HashMap<String, reqwest::Client>> {
+    static CLIENTS: OnceLock<Mutex<HashMap<String, reqwest::Client>>> = OnceLock::new();
+    CLIENTS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Shared-dispatcher analogue: one proxied `reqwest::Client` per proxy URL.
+/// Returns `None` when the proxy client cannot be built (invalid proxy URL) —
+/// the caller falls back to the direct shared client with a warning.
+fn get_shared_proxy_client(proxy_url: &str) -> Option<reqwest::Client> {
+    let mut clients = shared_proxy_clients()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Some(existing) = clients.get(proxy_url) {
+        return Some(existing.clone());
+    }
+
+    let proxy = match reqwest::Proxy::all(proxy_url) {
+        Ok(proxy) => proxy,
+        Err(error) => {
+            log_warn(
+                "Failed to configure proxy transport; using direct connection",
+                Some(&json!({ "proxyUrl": proxy_url, "error": error.to_string() })),
+            );
+            return None;
+        }
+    };
+    let client = match reqwest::Client::builder().proxy(proxy).build() {
+        Ok(client) => client,
+        Err(error) => {
+            log_warn(
+                "Failed to configure proxy transport; using direct connection",
+                Some(&json!({ "proxyUrl": proxy_url, "error": error.to_string() })),
+            );
+            return None;
+        }
+    };
+    clients.insert(proxy_url.to_string(), client.clone());
+    Some(client)
+}
+
+/// TS `closeSharedProxyDispatchers()` — drains the cache in a loop so entries
+/// added re-entrantly while draining are also dropped. Dropped clients close
+/// their pooled connections when the last handle goes away.
+pub async fn close_shared_proxy_dispatchers() {
+    loop {
+        let drained: Vec<reqwest::Client> = {
+            let mut clients = shared_proxy_clients()
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if clients.is_empty() {
+                return;
+            }
+            clients.drain().map(|(_, client)| client).collect()
+        };
+        drop(drained);
+    }
+}
+
+/// TS `applyProxyCompatibleInit` analogue: the HTTP client to use for the
+/// request — a cached proxied client when proxy env applies, else the shared
+/// direct client from `fetch_helpers`. (`reqwest::Client` clones share the
+/// underlying pool.)
+pub fn resolve_client_for_request(url: &str, env: &EnvMap) -> reqwest::Client {
+    match resolve_proxy_url_for_request(url, env) {
+        Some(proxy_url) => get_shared_proxy_client(&proxy_url)
+            .unwrap_or_else(|| crate::fetch_helpers::shared_client().clone()),
+        None => crate::fetch_helpers::shared_client().clone(),
+    }
+}
+
+/// Register the dispatcher-drain with the process shutdown registry (the TS
+/// module does this at import time; Rust callers invoke it once from the
+/// pipeline bootstrap).
+pub fn register_proxy_dispatcher_cleanup() -> cma_core::shutdown::CleanupHandle {
+    cma_core::shutdown::register_cleanup(close_shared_proxy_dispatchers)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn env(pairs: &[(&str, &str)]) -> EnvMap {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn extracts_url_from_each_input_shape() {
+        assert_eq!(
+            extract_request_url(&FetchInput::Url("https://example.com/test")),
+            "https://example.com/test"
+        );
+        let url = Url::parse("https://example.com/test").unwrap();
+        assert_eq!(
+            extract_request_url(&FetchInput::Parsed(&url)),
+            "https://example.com/test"
+        );
+        let request = crate::request_init::NormalizedRequest {
+            url: "https://example.com/test".into(),
+            method: "GET".into(),
+            headers: http::HeaderMap::new(),
+            body: None,
+        };
+        assert_eq!(
+            extract_request_url(&FetchInput::Request(&request)),
+            "https://example.com/test"
+        );
+    }
+
+    #[test]
+    fn rewrites_responses_to_codex_responses() {
+        assert_eq!(
+            rewrite_url_for_codex("https://chatgpt.com/backend-api/responses").unwrap(),
+            "https://chatgpt.com/backend-api/codex/responses"
+        );
+    }
+
+    #[test]
+    fn preserves_response_subresource_paths() {
+        assert_eq!(
+            rewrite_url_for_codex("https://api.openai.com/v1/responses/resp_123").unwrap(),
+            "https://chatgpt.com/backend-api/v1/codex/responses/resp_123"
+        );
+        assert_eq!(
+            rewrite_url_for_codex("https://api.openai.com/v1/responses/resp_123/cancel").unwrap(),
+            "https://chatgpt.com/backend-api/v1/codex/responses/resp_123/cancel"
+        );
+    }
+
+    #[test]
+    fn keeps_backend_api_paths_on_codex_origin() {
+        let url = "https://chatgpt.com/backend-api/other";
+        assert_eq!(rewrite_url_for_codex(url).unwrap(), url);
+    }
+
+    #[test]
+    fn forces_codex_origin_and_preserves_query_params() {
+        assert_eq!(
+            rewrite_url_for_codex("https://example.com/backend-api/responses?foo=bar").unwrap(),
+            "https://chatgpt.com/backend-api/codex/responses?foo=bar"
+        );
+    }
+
+    #[test]
+    fn prefixes_backend_api_when_path_is_outside_backend_api() {
+        assert_eq!(
+            rewrite_url_for_codex("https://chatgpt.com/v1/other").unwrap(),
+            format!("{CODEX_BASE_URL}/v1/other")
+        );
+    }
+
+    #[test]
+    fn clears_userinfo_and_upgrades_scheme() {
+        assert_eq!(
+            rewrite_url_for_codex("http://user:pass@example.com/backend-api/responses").unwrap(),
+            "https://chatgpt.com/backend-api/codex/responses"
+        );
+    }
+
+    #[test]
+    fn errors_for_invalid_url_input() {
+        assert!(rewrite_url_for_codex("not-a-valid-url").is_err());
+    }
+
+    #[test]
+    fn prefers_lowercase_proxy_env_values_over_uppercase() {
+        let env = env(&[
+            ("HTTPS_PROXY", "http://uppercase-proxy:8080"),
+            ("https_proxy", "http://lowercase-proxy:8080"),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/v1/chat", &env).as_deref(),
+            Some("http://lowercase-proxy:8080")
+        );
+    }
+
+    #[test]
+    fn empty_lowercase_key_disables_without_uppercase_fallback() {
+        // Spec 06 gotcha 19.
+        let env = env(&[
+            ("HTTPS_PROXY", "http://uppercase-proxy:8080"),
+            ("https_proxy", "   "),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/v1/chat", &env),
+            None
+        );
+    }
+
+    #[test]
+    fn falls_back_to_http_proxy_for_https_requests() {
+        let env = env(&[("HTTP_PROXY", "http://shared-proxy:8080")]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/v1/chat", &env).as_deref(),
+            Some("http://shared-proxy:8080")
+        );
+    }
+
+    #[test]
+    fn http_requests_never_use_https_proxy() {
+        let env = env(&[("HTTPS_PROXY", "http://https-only-proxy:8080")]);
+        assert_eq!(
+            resolve_proxy_url_for_request("http://api.openai.com/v1/chat", &env),
+            None
+        );
+    }
+
+    #[test]
+    fn http_requests_prefer_http_proxy_when_both_are_set() {
+        let env = env(&[
+            ("HTTP_PROXY", "http://http-proxy:8080"),
+            ("HTTPS_PROXY", "http://https-proxy:8080"),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("http://api.openai.com/v1/chat", &env).as_deref(),
+            Some("http://http-proxy:8080")
+        );
+    }
+
+    #[test]
+    fn bypasses_proxy_when_no_proxy_matches_host() {
+        let env = env(&[
+            ("HTTPS_PROXY", "http://proxy.example:8080"),
+            ("NO_PROXY", "api.openai.com,.internal.example"),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/v1/chat", &env),
+            None
+        );
+        assert_eq!(
+            resolve_proxy_url_for_request("https://service.internal.example/v1/chat", &env),
+            None
+        );
+    }
+
+    #[test]
+    fn wildcard_entries_inside_no_proxy_lists_bypass_everything() {
+        let env = env(&[
+            ("HTTPS_PROXY", "http://proxy.example:8080"),
+            ("NO_PROXY", "api.openai.com,*,.internal.example"),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://unlisted.example/v1/chat", &env),
+            None
+        );
+    }
+
+    #[test]
+    fn no_proxy_port_entries_only_match_that_port() {
+        let env = env(&[
+            ("HTTPS_PROXY", "http://proxy.example:8080"),
+            ("NO_PROXY", "api.openai.com:8443"),
+        ]);
+        // Default https port 443 ≠ 8443 → still proxied.
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/v1/chat", &env).as_deref(),
+            Some("http://proxy.example:8080")
+        );
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com:8443/v1/chat", &env),
+            None
+        );
+    }
+
+    #[test]
+    fn star_prefixed_no_proxy_entries_are_suffix_matchers() {
+        let env = env(&[
+            ("HTTPS_PROXY", "http://proxy.example:8080"),
+            ("NO_PROXY", "*.internal.example"),
+        ]);
+        assert_eq!(
+            resolve_proxy_url_for_request("https://svc.internal.example/x", &env),
+            None
+        );
+        assert_eq!(
+            resolve_proxy_url_for_request("https://api.openai.com/x", &env).as_deref(),
+            Some("http://proxy.example:8080")
+        );
+    }
+
+    #[test]
+    fn non_http_schemes_resolve_to_no_proxy() {
+        let env = env(&[("HTTPS_PROXY", "http://proxy.example:8080")]);
+        assert_eq!(resolve_proxy_url_for_request("file:///tmp/x", &env), None);
+    }
+
+    #[tokio::test]
+    async fn caches_proxy_clients_and_recreates_after_cleanup() {
+        close_shared_proxy_dispatchers().await;
+        let first = get_shared_proxy_client("http://proxy.example:8080").unwrap();
+        let _again = get_shared_proxy_client("http://proxy.example:8080").unwrap();
+        {
+            let clients = shared_proxy_clients().lock().unwrap();
+            assert_eq!(clients.len(), 1);
+        }
+        drop(first);
+        close_shared_proxy_dispatchers().await;
+        {
+            let clients = shared_proxy_clients().lock().unwrap();
+            assert!(clients.is_empty());
+        }
+        let recreated = get_shared_proxy_client("http://proxy.example:8080");
+        assert!(recreated.is_some());
+        close_shared_proxy_dispatchers().await;
+    }
+
+    #[test]
+    fn invalid_proxy_urls_fall_back_to_none() {
+        assert!(get_shared_proxy_client("::not-a-proxy::").is_none());
+    }
+}
diff --git a/crates/request/src/wait_utils.rs b/crates/request/src/wait_utils.rs
new file mode 100644
index 000000000..498e8a796
--- /dev/null
+++ b/crates/request/src/wait_utils.rs
@@ -0,0 +1,268 @@
+//! Port of `lib/request/wait-utils.ts` — abortable sleep plus the toast
+//! countdown loop (spec 06 §22).
+//!
+//! All effects are injected (sleep / toast / wait-time formatting), so the
+//! countdown logic is pure and easy to test. The TS `AbortSignal` is modeled
+//! as a `tokio_util::sync::CancellationToken`; the frozen abort message is
+//! `"Aborted"`.
+
+use std::fmt;
+use std::future::Future;
+use std::time::Duration;
+
+use cma_core::utils::now_ms;
+use futures::FutureExt;
+use futures::future::BoxFuture;
+use tokio_util::sync::CancellationToken;
+
+/// The frozen TS abort rejection: `new Error("Aborted")`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct AbortedError;
+
+impl fmt::Display for AbortedError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("Aborted")
+    }
+}
+
+impl std::error::Error for AbortedError {}
+
+/// One abortable sleep: resolves after `ms`, or rejects with
+/// [`AbortedError`] immediately when the signal is already aborted or aborts
+/// mid-sleep. (The TS listener cleanup is implicit — dropping the future
+/// releases both branches.)
+pub async fn abortable_sleep(
+    ms: u64,
+    abort_signal: Option<&CancellationToken>,
+) -> Result<(), AbortedError> {
+    match abort_signal {
+        Some(token) if token.is_cancelled() => Err(AbortedError),
+        Some(token) => {
+            tokio::select! {
+                _ = token.cancelled() => Err(AbortedError),
+                _ = tokio::time::sleep(Duration::from_millis(ms)) => Ok(()),
+            }
+        }
+        None => {
+            tokio::time::sleep(Duration::from_millis(ms)).await;
+            Ok(())
+        }
+    }
+}
+
+/// TS `createAbortableSleep(abortSignal?)` — returns a reusable sleep
+/// function bound to the given signal. Each call produces an independent
+/// sleep future.
+pub fn create_abortable_sleep(
+    abort_signal: Option<CancellationToken>,
+) -> impl Fn(u64) -> BoxFuture<'static, Result<(), AbortedError>> {
+    move |ms: u64| {
+        let token = abort_signal.clone();
+        async move { abortable_sleep(ms, token.as_ref()).await }.boxed()
+    }
+}
+
+/// TS `sleepWithCountdown` params. The injected `show_toast` receives
+/// `(message, variant, duration_ms)` — the TS variant is always the literal
+/// `"warning"` and the options object carried a single `duration` field.
+pub struct SleepWithCountdownParams<'a, S, T, F> {
+    pub total_ms: i64,
+    pub message: &'a str,
+    pub sleep: S,
+    pub show_toast: T,
+    pub format_wait_time: F,
+    pub toast_duration_ms: i64,
+    pub abort_signal: Option<&'a CancellationToken>,
+    /// Defaults to 5000 when `None`.
+    pub interval_ms: Option<i64>,
+}
+
+/// TS `sleepWithCountdown(params)`.
+///
+/// Loops until `now >= start + total_ms`. Each iteration: an aborted signal
+/// throws `"Aborted"`; a toast
+/// `"{message} ({format_wait_time(remaining)} remaining)"` is shown with
+/// variant `"warning"` and `duration = min(interval_ms + 1000,
+/// toast_duration_ms)`; then sleeps `min(interval_ms, remaining)` (a
+/// non-positive sleep breaks the loop). An abort observed by the injected
+/// sleep propagates as [`AbortedError`], matching the TS rejection.
+pub async fn sleep_with_countdown<S, SFut, T, TFut, F>(
+    params: SleepWithCountdownParams<'_, S, T, F>,
+) -> Result<(), AbortedError>
+where
+    S: FnMut(i64) -> SFut,
+    SFut: Future<Output = Result<(), AbortedError>>,
+    T: FnMut(String, &'static str, i64) -> TFut,
+    TFut: Future<Output = ()>,
+    F: Fn(i64) -> String,
+{
+    let SleepWithCountdownParams {
+        total_ms,
+        message,
+        mut sleep,
+        mut show_toast,
+        format_wait_time,
+        toast_duration_ms,
+        abort_signal,
+        interval_ms,
+    } = params;
+    let start_time = now_ms();
+    let end_time = start_time + total_ms;
+    let interval_ms = interval_ms.unwrap_or(5_000);
+
+    while now_ms() < end_time {
+        if abort_signal.is_some_and(CancellationToken::is_cancelled) {
+            return Err(AbortedError);
+        }
+
+        let remaining = (end_time - now_ms()).max(0);
+        let wait_label = format_wait_time(remaining);
+        show_toast(
+            format!("{message} ({wait_label} remaining)"),
+            "warning",
+            (interval_ms + 1_000).min(toast_duration_ms),
+        )
+        .await;
+
+        let sleep_time = interval_ms.min(remaining);
+        if sleep_time > 0 {
+            sleep(sleep_time).await?;
+        } else {
+            break;
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::Mutex;
+
+    #[tokio::test]
+    async fn resolves_abortable_sleep_after_timeout() {
+        let sleep = create_abortable_sleep(None);
+        sleep(10).await.expect("sleep resolves");
+    }
+
+    #[tokio::test]
+    async fn rejects_abortable_sleep_when_aborted() {
+        let token = CancellationToken::new();
+        let sleep = create_abortable_sleep(Some(token.clone()));
+        let pending = sleep(60_000);
+        token.cancel();
+        let err = pending.await.expect_err("aborted");
+        assert_eq!(err.to_string(), "Aborted");
+    }
+
+    #[tokio::test]
+    async fn rejects_immediately_when_already_aborted() {
+        let token = CancellationToken::new();
+        token.cancel();
+        let sleep = create_abortable_sleep(Some(token));
+        let err = sleep(60_000).await.expect_err("already aborted");
+        assert_eq!(err, AbortedError);
+    }
+
+    type ToastLog = Arc<Mutex<Vec<(String, &'static str, i64)>>>;
+
+    #[tokio::test]
+    async fn shows_countdown_toasts_and_sleeps_in_intervals() {
+        let toasts: ToastLog = Arc::default();
+        let sleeps: Arc<Mutex<Vec<i64>>> = Arc::default();
+        let toast_log = toasts.clone();
+        let sleep_log = sleeps.clone();
+        sleep_with_countdown(SleepWithCountdownParams {
+            total_ms: 30,
+            message: "Waiting",
+            sleep: move |ms| {
+                sleep_log.lock().unwrap().push(ms);
+                async move {
+                    tokio::time::sleep(Duration::from_millis(ms as u64)).await;
+                    Ok(())
+                }
+            },
+            show_toast: move |message, variant, duration| {
+                toast_log.lock().unwrap().push((message, variant, duration));
+                async {}
+            },
+            format_wait_time: |ms| format!("{ms}ms"),
+            toast_duration_ms: 9_000,
+            abort_signal: None,
+            interval_ms: Some(10),
+        })
+        .await
+        .expect("countdown completes");
+
+        let toasts = toasts.lock().unwrap();
+        assert!(!toasts.is_empty());
+        let (message, variant, duration) = &toasts[0];
+        assert!(message.starts_with("Waiting ("));
+        assert!(message.ends_with("ms remaining)"));
+        assert_eq!(*variant, "warning");
+        // duration = min(intervalMs + 1000, toastDurationMs).
+        assert_eq!(*duration, 1_010);
+        assert!(!sleeps.lock().unwrap().is_empty());
+        // Each sleep is capped at the interval.
+        assert!(sleeps.lock().unwrap().iter().all(|&ms| ms <= 10));
+    }
+
+    #[tokio::test]
+    async fn countdown_throws_when_aborted_before_iteration() {
+        let token = CancellationToken::new();
+        token.cancel();
+        let err = sleep_with_countdown(SleepWithCountdownParams {
+            total_ms: 10_000,
+            message: "Waiting",
+            sleep: |_ms| async { Ok(()) },
+            show_toast: |_m, _v, _d| async {},
+            format_wait_time: |ms| format!("{ms}ms"),
+            toast_duration_ms: 9_000,
+            abort_signal: Some(&token),
+            interval_ms: Some(5_000),
+        })
+        .await
+        .expect_err("aborted");
+        assert_eq!(err.to_string(), "Aborted");
+    }
+
+    #[tokio::test]
+    async fn countdown_propagates_abort_from_injected_sleep() {
+        let err = sleep_with_countdown(SleepWithCountdownParams {
+            total_ms: 10_000,
+            message: "Waiting",
+            sleep: |_ms| async { Err(AbortedError) },
+            show_toast: |_m, _v, _d| async {},
+            format_wait_time: |ms| format!("{ms}ms"),
+            toast_duration_ms: 9_000,
+            abort_signal: None,
+            interval_ms: Some(5_000),
+        })
+        .await
+        .expect_err("sleep abort propagates");
+        assert_eq!(err, AbortedError);
+    }
+
+    #[tokio::test]
+    async fn zero_total_skips_the_loop() {
+        let toasted = Arc::new(Mutex::new(0u32));
+        let log = toasted.clone();
+        sleep_with_countdown(SleepWithCountdownParams {
+            total_ms: 0,
+            message: "Waiting",
+            sleep: |_ms| async { Ok(()) },
+            show_toast: move |_m, _v, _d| {
+                *log.lock().unwrap() += 1;
+                async {}
+            },
+            format_wait_time: |ms| format!("{ms}ms"),
+            toast_duration_ms: 9_000,
+            abort_signal: None,
+            interval_ms: Some(5_000),
+        })
+        .await
+        .expect("no-op countdown");
+        assert_eq!(*toasted.lock().unwrap(), 0);
+    }
+}
diff --git a/crates/request/tests/context_overflow_test.rs b/crates/request/tests/context_overflow_test.rs
new file mode 100644
index 000000000..7ad2e33a6
--- /dev/null
+++ b/crates/request/tests/context_overflow_test.rs
@@ -0,0 +1,235 @@
+//! Port of `test/context-overflow.test.ts`.
+//!
+//! The TS "handles response read errors gracefully" test stubs
+//! `response.clone()` to throw; Rust bodies are one-shot streams, so the
+//! equivalent scenario is a body stream that errors mid-read — it must
+//! degrade to `NotHandled` (read errors are swallowed).
+
+use bytes::Bytes;
+use futures::StreamExt;
+use http::HeaderMap;
+use http::header::HeaderName;
+use serde_json::Value;
+
+use cma_request::context_overflow::{
+    ContextOverflowOutcome, create_context_overflow_response, handle_context_overflow,
+    is_context_overflow_error,
+};
+use cma_request::response_handler::{
+    BodyStream, BoxError, ConvertSseOptions, StreamResponse, convert_sse_to_json,
+};
+
+fn body_response(status: u16, body: &str) -> StreamResponse {
+    StreamResponse::from_text(status, "", HeaderMap::new(), body)
+}
+
+fn header(response: &StreamResponse, name: &str) -> Option<String> {
+    response
+        .headers
+        .get(HeaderName::from_bytes(name.as_bytes()).unwrap())
+        .and_then(|v| v.to_str().ok())
+        .map(|v| v.to_string())
+}
+
+// ---------------------------------------------------------------------------
+// isContextOverflowError
+// ---------------------------------------------------------------------------
+
+#[test]
+fn returns_false_for_non_400_status() {
+    assert!(!is_context_overflow_error(200, "prompt is too long"));
+    assert!(!is_context_overflow_error(429, "prompt is too long"));
+    assert!(!is_context_overflow_error(500, "prompt is too long"));
+}
+
+#[test]
+fn returns_false_for_empty_body() {
+    assert!(!is_context_overflow_error(400, ""));
+}
+
+#[test]
+fn detects_prompt_too_long_pattern() {
+    assert!(is_context_overflow_error(400, r#"{"error": {"code": "prompt_too_long"}}"#));
+}
+
+#[test]
+fn detects_prompt_is_too_long_pattern() {
+    assert!(is_context_overflow_error(400, "Error: prompt is too long for this model"));
+}
+
+#[test]
+fn detects_context_length_exceeded_code_pattern() {
+    assert!(is_context_overflow_error(400, r#"{"error": {"code": "context_length_exceeded"}}"#));
+}
+
+#[test]
+fn detects_context_length_exceeded_text_pattern() {
+    assert!(is_context_overflow_error(400, "The context length exceeded the maximum"));
+}
+
+#[test]
+fn detects_maximum_context_length_pattern() {
+    assert!(is_context_overflow_error(400, "This request exceeds maximum context length"));
+}
+
+#[test]
+fn detects_token_limit_exceeded_pattern() {
+    assert!(is_context_overflow_error(400, "Token limit exceeded for this model"));
+}
+
+#[test]
+fn detects_too_many_tokens_pattern() {
+    assert!(is_context_overflow_error(400, "Request has too many tokens"));
+}
+
+#[test]
+fn is_case_insensitive() {
+    assert!(is_context_overflow_error(400, "PROMPT IS TOO LONG"));
+    assert!(is_context_overflow_error(400, "CONTEXT_LENGTH_EXCEEDED"));
+}
+
+#[test]
+fn returns_false_for_unrelated_400_errors() {
+    assert!(!is_context_overflow_error(400, r#"{"error": {"code": "invalid_api_key"}}"#));
+    assert!(!is_context_overflow_error(400, "Bad request: missing model parameter"));
+}
+
+// ---------------------------------------------------------------------------
+// createContextOverflowResponse
+// ---------------------------------------------------------------------------
+
+#[test]
+fn returns_a_200_ok_response() {
+    let response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    assert_eq!(response.status, 200);
+}
+
+#[test]
+fn has_text_event_stream_content_type() {
+    let response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    assert_eq!(header(&response, "content-type").as_deref(), Some("text/event-stream"));
+}
+
+#[test]
+fn has_synthetic_response_marker_headers() {
+    let response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    assert_eq!(header(&response, "x-codex-plugin-synthetic").as_deref(), Some("true"));
+    assert_eq!(
+        header(&response, "x-codex-plugin-error-type").as_deref(),
+        Some("context_overflow")
+    );
+}
+
+#[tokio::test]
+async fn includes_responses_api_sse_events_with_helpful_message() {
+    let mut response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    let text = response.collect_text().await.unwrap();
+
+    // Responses-API dialect (recovery-01) — NOT Anthropic Messages events.
+    assert!(text.contains("event: response.created"));
+    assert!(text.contains("event: response.output_item.added"));
+    assert!(text.contains("event: response.output_text.delta"));
+    assert!(text.contains("event: response.output_text.done"));
+    assert!(text.contains("event: response.completed"));
+    // Old Anthropic envelope must be gone.
+    assert!(!text.contains("event: message_start"));
+    assert!(!text.contains("content_block_delta"));
+    assert!(text.contains("/compact"));
+    assert!(text.contains("/clear"));
+    assert!(text.contains("/undo"));
+}
+
+#[tokio::test]
+async fn round_trips_through_the_responses_sse_parser_the_client_uses() {
+    let response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    let mut parsed = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .unwrap();
+    assert!(parsed.ok());
+    let body: Value = parsed.collect_json().await.unwrap();
+    // The notice is actually recoverable by the client (the whole point of
+    // recovery-01): both the flattened output_text and the structured output
+    // carry the advisory message.
+    assert!(body["output_text"].as_str().unwrap().contains("/compact"));
+    assert!(
+        body["output"][0]["content"][0]["text"]
+            .as_str()
+            .unwrap()
+            .contains("Context is too long")
+    );
+}
+
+#[tokio::test]
+async fn includes_model_in_response() {
+    let mut response = create_context_overflow_response(Some("gpt-5.1-codex"));
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains(r#""model":"gpt-5.1-codex""#));
+}
+
+#[tokio::test]
+async fn uses_unknown_as_default_model() {
+    let mut response = create_context_overflow_response(None);
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains(r#""model":"unknown""#));
+}
+
+// ---------------------------------------------------------------------------
+// handleContextOverflow
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn returns_not_handled_for_non_400_responses() {
+    let response = body_response(200, "OK");
+    let result = handle_context_overflow(response, Some("gpt-5.1-codex")).await;
+    assert!(!result.handled());
+}
+
+#[tokio::test]
+async fn returns_not_handled_for_400_without_overflow_pattern() {
+    let response = body_response(400, r#"{"error": {"code": "invalid_request"}}"#);
+    let result = handle_context_overflow(response, Some("gpt-5.1-codex")).await;
+    assert!(!result.handled());
+}
+
+#[tokio::test]
+async fn not_handled_response_keeps_a_readable_body() {
+    // Clone-before-return contract: the caller gets the original body back.
+    let original_body = r#"{"error": {"code": "invalid_request"}}"#;
+    let response = body_response(400, original_body);
+    let result = handle_context_overflow(response, Some("gpt-5.1-codex")).await;
+    match result {
+        ContextOverflowOutcome::NotHandled { mut response } => {
+            assert_eq!(response.status, 400);
+            assert_eq!(response.collect_text().await.unwrap(), original_body);
+        }
+        ContextOverflowOutcome::Handled { .. } => panic!("must not be handled"),
+    }
+}
+
+#[tokio::test]
+async fn returns_handled_with_synthetic_response_for_overflow_error() {
+    let response = body_response(400, r#"{"error": {"code": "prompt_too_long"}}"#);
+    let result = handle_context_overflow(response, Some("gpt-5.1-codex")).await;
+    assert!(result.handled());
+    match result {
+        ContextOverflowOutcome::Handled { response } => {
+            assert_eq!(response.status, 200);
+            assert_eq!(header(&response, "x-codex-plugin-synthetic").as_deref(), Some("true"));
+        }
+        ContextOverflowOutcome::NotHandled { .. } => panic!("must be handled"),
+    }
+}
+
+#[tokio::test]
+async fn handles_response_read_errors_gracefully() {
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"prompt is too long"))
+    })
+    .chain(futures::stream::once(async {
+        Err::<Bytes, BoxError>("Clone failed".to_string().into())
+    }))
+    .boxed();
+    let response = StreamResponse::new(400, "", HeaderMap::new(), Some(stream));
+    let result = handle_context_overflow(response, Some("gpt-5.1-codex")).await;
+    assert!(!result.handled());
+}
diff --git a/crates/request/tests/response_handler_test.rs b/crates/request/tests/response_handler_test.rs
new file mode 100644
index 000000000..0a8a101bc
--- /dev/null
+++ b/crates/request/tests/response_handler_test.rs
@@ -0,0 +1,943 @@
+//! Port of `test/response-handler.test.ts` + `test/response-handler-sse-buffer.test.ts`
+//! — the regression gate for ARCHITECTURE §11 risk 1 (SSE state machine).
+//!
+//! Not ported: `test/response-handler-logging.test.ts` (asserts on a mocked
+//! logger module; the Rust logger is not injectable — log-only behavior).
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use bytes::Bytes;
+use futures::StreamExt;
+use http::HeaderMap;
+use http::header::{CONTENT_TYPE, HeaderValue};
+use serde_json::{Value, json};
+
+use cma_request::response_handler::{
+    BodyStream, BoxError, ConvertSseOptions, ResponseIdCallback, StreamResponse,
+    attach_response_id_capture, convert_sse_to_json, ensure_content_type, is_empty_response,
+};
+
+const MAX_SSE_SIZE_FOR_TEST: usize = 10 * 1024 * 1024; // must match lib constant
+
+fn sse_response(content: &str) -> StreamResponse {
+    // TS `new Response(content)` — status 200, empty statusText.
+    StreamResponse::from_text(200, "", HeaderMap::new(), content)
+}
+
+async fn convert(response: StreamResponse) -> StreamResponse {
+    convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect("convertSseToJson should succeed")
+}
+
+async fn convert_json(response: StreamResponse) -> Value {
+    convert(response)
+        .await
+        .collect_json()
+        .await
+        .expect("JSON body")
+}
+
+fn recording_callback() -> (ResponseIdCallback, Arc<Mutex<Vec<String>>>) {
+    let calls: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+    let sink = calls.clone();
+    let callback: ResponseIdCallback = Arc::new(move |id: &str| {
+        sink.lock().unwrap().push(id.to_string());
+    });
+    (callback, calls)
+}
+
+fn counting_stream(chunks: Vec<Bytes>) -> (BodyStream, Arc<AtomicUsize>) {
+    let count = Arc::new(AtomicUsize::new(0));
+    let counter = count.clone();
+    let stream = futures::stream::iter(chunks.into_iter().map(Ok::<_, BoxError>))
+        .inspect(move |_| {
+            counter.fetch_add(1, Ordering::SeqCst);
+        })
+        .boxed();
+    (stream, count)
+}
+
+// ---------------------------------------------------------------------------
+// ensureContentType
+// ---------------------------------------------------------------------------
+
+#[test]
+fn ensure_content_type_preserves_existing_content_type() {
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+    let result = ensure_content_type(&headers);
+    assert_eq!(result.get(CONTENT_TYPE).unwrap(), "application/json");
+}
+
+#[test]
+fn ensure_content_type_adds_default_when_missing() {
+    let headers = HeaderMap::new();
+    let result = ensure_content_type(&headers);
+    assert_eq!(
+        result.get(CONTENT_TYPE).unwrap(),
+        "text/event-stream; charset=utf-8"
+    );
+}
+
+#[test]
+fn ensure_content_type_does_not_modify_original_headers() {
+    let headers = HeaderMap::new();
+    let result = ensure_content_type(&headers);
+    assert!(!headers.contains_key(CONTENT_TYPE));
+    assert!(result.contains_key(CONTENT_TYPE));
+}
+
+// ---------------------------------------------------------------------------
+// convertSseToJson
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn errors_when_response_has_no_body() {
+    let response = StreamResponse::new(200, "", HeaderMap::new(), None);
+    let error = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect_err("must error");
+    assert_eq!(error.to_string(), "[codex-multi-auth] Response has no body");
+}
+
+#[tokio::test]
+async fn parses_sse_stream_with_response_done_event() {
+    let sse_content = "data: {\"type\":\"response.started\"}\ndata: {\"type\":\"response.done\",\"response\":{\"id\":\"resp_123\",\"output\":\"test\"}}\n";
+    let mut result = convert(sse_response(sse_content)).await;
+    assert_eq!(
+        result.headers.get(CONTENT_TYPE).unwrap(),
+        "application/json; charset=utf-8"
+    );
+    let body = result.collect_json().await.unwrap();
+    assert_eq!(body, json!({ "id": "resp_123", "output": "test" }));
+}
+
+#[tokio::test]
+async fn parses_sse_stream_with_response_completed_event() {
+    let sse_content = "data: {\"type\":\"response.started\"}\ndata: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_456\",\"output\":\"done\"}}\n";
+    let body = convert_json(sse_response(sse_content)).await;
+    assert_eq!(body, json!({ "id": "resp_456", "output": "done" }));
+}
+
+#[tokio::test]
+async fn synthesizes_output_text_and_reasoning_summaries_from_semantic_events() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_semantic_123","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_123","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hello ","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"world","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Hello world","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_123","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"Need more context."}"#,
+        r#"data: {"type":"response.reasoning_summary_text.done","output_index":1,"summary_index":0,"text":"Need more context."}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_semantic_123","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["id"], json!("resp_semantic_123"));
+    assert_eq!(body["output_text"], json!("Hello world"));
+    assert_eq!(body["reasoning_summary_text"], json!("Need more context."));
+    assert_eq!(body["phase"], json!("final_answer"));
+    assert_eq!(body["final_answer_text"], json!("Hello world"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello world" }));
+    assert_eq!(
+        body["output"][0]["content"][0],
+        json!({ "type": "output_text", "text": "Hello world" })
+    );
+    assert_eq!(
+        body["output"][1]["summary"][0],
+        json!({ "type": "summary_text", "text": "Need more context." })
+    );
+}
+
+#[tokio::test]
+async fn preserves_canonical_terminal_reasoning_summary_text_over_synthesized() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_semantic_canonical","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_456","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"Draft summary"}"#,
+        r#"data: {"type":"response.reasoning_summary_text.done","output_index":1,"summary_index":0,"text":"Draft summary"}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_semantic_canonical","object":"response","reasoning_summary_text":"Canonical summary"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["reasoning_summary_text"], json!("Canonical summary"));
+    assert_eq!(body["output"][1]["summary"][0]["text"], json!("Draft summary"));
+}
+
+#[tokio::test]
+async fn preserves_canonical_terminal_reasoning_summary_parts_over_synthesized() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_semantic_part_canonical","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_789","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_part.added","output_index":1,"summary_index":0,"part":{"text":"Draft summary"}}"#,
+        r#"data: {"type":"response.reasoning_summary_part.done","output_index":1,"summary_index":0,"part":{"text":"Draft summary"}}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_semantic_part_canonical","object":"response","output":[{},{"type":"reasoning","summary":[{"type":"summary_text","text":"Canonical summary part"}]}]}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["reasoning_summary_text"], json!("Canonical summary part"));
+    assert_eq!(
+        body["output"][1]["summary"][0],
+        json!({ "type": "summary_text", "text": "Canonical summary part" })
+    );
+}
+
+#[tokio::test]
+async fn synthesizes_reasoning_summaries_from_part_events() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_summary_part","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_part","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_part.added","output_index":1,"summary_index":0,"part":{"text":"Draft summary"}}"#,
+        r#"data: {"type":"response.reasoning_summary_part.done","output_index":1,"summary_index":0,"part":{"text":"Need more context."}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_summary_part","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["reasoning_summary_text"], json!("Need more context."));
+    assert_eq!(
+        body["output"][1]["summary"][0],
+        json!({ "type": "summary_text", "text": "Need more context." })
+    );
+}
+
+#[tokio::test]
+async fn preserves_canonical_terminal_reasoning_summary_over_summary_deltas() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_semantic_nested","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_nested","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"Draft nested summary"}"#,
+        r#"data: {"type":"response.reasoning_summary_text.done","output_index":1,"summary_index":0,"text":"Draft nested summary"}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_semantic_nested","object":"response","output":[{},{"id":"rs_nested","type":"reasoning","summary":[{"type":"summary_text","text":"Canonical nested summary"}]}]}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(
+        body["output"][1]["summary"][0]["text"],
+        json!("Canonical nested summary")
+    );
+    assert_eq!(body["reasoning_summary_text"], json!("Canonical nested summary"));
+}
+
+#[tokio::test]
+async fn synthesizes_output_text_from_content_part_events() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_content_part","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_part","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hello ","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hello world","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_content_part","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(
+        body["output"][0]["content"][0],
+        json!({ "type": "output_text", "text": "Hello world" })
+    );
+    assert_eq!(body["output_text"], json!("Hello world"));
+    assert_eq!(body["final_answer_text"], json!("Hello world"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello world" }));
+}
+
+#[tokio::test]
+async fn preserves_whitespace_only_semantic_deltas_when_no_done_events_override() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_whitespace_delta","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_space","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hello","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" ","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"world","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_space","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"Need"}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":" "}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"context."}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_whitespace_delta","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["output"][0]["content"][0]["text"], json!("Hello world"));
+    assert_eq!(body["output_text"], json!("Hello world"));
+    assert_eq!(body["final_answer_text"], json!("Hello world"));
+    assert_eq!(body["output"][1]["summary"][0]["text"], json!("Need context."));
+    assert_eq!(body["reasoning_summary_text"], json!("Need context."));
+}
+
+#[tokio::test]
+async fn preserves_richer_terminal_output_when_semantic_items_have_empty_content() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_rich_123","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_123","type":"message","role":"assistant","content":[]}}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_rich_123","object":"response","output":[{"id":"msg_123","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hello rich world"},{"type":"annotation","label":"kept"}]}]}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["id"], json!("resp_rich_123"));
+    assert_eq!(
+        body["output"][0]["content"],
+        json!([
+            { "type": "output_text", "text": "Hello rich world" },
+            { "type": "annotation", "label": "kept" },
+        ])
+    );
+}
+
+#[tokio::test]
+async fn preserves_canonical_terminal_content_over_accumulated_deltas() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_canonical_slot","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_canonical","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Draft answer","phase":"final_answer"}"#,
+        r#"data: {"type":"response.completed","response":{"id":"resp_canonical_slot","object":"response","output":[{"id":"msg_canonical","type":"message","role":"assistant","content":[{"type":"output_text","text":"Canonical answer"}]}]}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["output"][0]["content"][0]["text"], json!("Canonical answer"));
+    assert_eq!(body["output_text"], json!("Canonical answer"));
+    assert_eq!(body["final_answer_text"], json!("Canonical answer"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Canonical answer" }));
+}
+
+#[tokio::test]
+async fn clears_stale_output_text_deltas_when_done_omits_canonical_text() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_stale_delta","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_stale","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hello ","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":" ","phase":"final_answer"}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_stale_delta","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert!(body["output"][0].get("content").is_none());
+    assert!(body.get("output_text").is_none());
+    assert!(body.get("final_answer_text").is_none());
+    assert!(body.get("phase_text").is_none());
+}
+
+#[tokio::test]
+async fn clears_stale_reasoning_summary_deltas_when_done_omits_canonical_text() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_stale_reasoning","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1,"item":{"id":"rs_stale","type":"reasoning"}}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","output_index":1,"summary_index":0,"delta":"Need more context"}"#,
+        r#"data: {"type":"response.reasoning_summary_text.done","output_index":1,"summary_index":0,"text":" "}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_stale_reasoning","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert!(body["output"][1].get("summary").is_none());
+    assert!(body.get("reasoning_summary_text").is_none());
+}
+
+#[tokio::test]
+async fn tracks_commentary_and_final_answer_phase_text_separately() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_phase_123","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_123","type":"message","role":"assistant","phase":"commentary"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Thinking...","phase":"commentary"}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Thinking...","phase":"commentary"}"#,
+        r#"data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_123","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":1,"text":"Done.","phase":"final_answer"}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_phase_123","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["phase"], json!("final_answer"));
+    assert_eq!(body["commentary_text"], json!("Thinking..."));
+    assert_eq!(body["final_answer_text"], json!("Done."));
+    assert_eq!(
+        body["phase_text"],
+        json!({ "commentary": "Thinking...", "final_answer": "Done." })
+    );
+    assert_eq!(body["output_text"], json!("Thinking...Done."));
+}
+
+#[tokio::test]
+async fn replaces_phase_text_when_output_text_done_corrects_earlier_deltas() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_phase_fix","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_fix","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hellp","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Hello","phase":"final_answer"}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_phase_fix","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["output"][0]["content"][0]["text"], json!("Hello"));
+    assert_eq!(body["output_text"], json!("Hello"));
+    assert_eq!(body["final_answer_text"], json!("Hello"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello" }));
+}
+
+#[tokio::test]
+async fn replaces_phase_text_when_output_text_done_omits_phase() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_phase_fix_missing","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_fix_missing","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hellp","phase":"final_answer"}"#,
+        r#"data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Hello"}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_phase_fix_missing","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["output"][0]["content"][0]["text"], json!("Hello"));
+    assert_eq!(body["output_text"], json!("Hello"));
+    assert_eq!(body["final_answer_text"], json!("Hello"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello" }));
+}
+
+#[tokio::test]
+async fn handles_content_part_added_for_output_text_parts() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_content_part_added","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_part_added","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hello from added part","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_content_part_added","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(
+        body["output"][0]["content"][0],
+        json!({ "type": "output_text", "text": "Hello from added part" })
+    );
+    assert_eq!(body["output_text"], json!("Hello from added part"));
+    assert_eq!(body["final_answer_text"], json!("Hello from added part"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello from added part" }));
+}
+
+#[tokio::test]
+async fn handles_content_part_done_for_output_text_parts() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_content_part_done","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_part_done","type":"message","role":"assistant","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hello from done part","phase":"final_answer"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_content_part_done","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(
+        body["output"][0]["content"][0],
+        json!({ "type": "output_text", "text": "Hello from done part" })
+    );
+    assert_eq!(body["output_text"], json!("Hello from done part"));
+    assert_eq!(body["final_answer_text"], json!("Hello from done part"));
+    assert_eq!(body["phase_text"], json!({ "final_answer": "Hello from done part" }));
+}
+
+#[tokio::test]
+async fn captures_phase_from_non_output_text_parts_without_mutating_output() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_content_part_annotation","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_part_annotation","type":"message","role":"assistant"}}"#,
+        r#"data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"annotation","text":"ignored","phase":"commentary"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_content_part_annotation","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+
+    assert_eq!(body["phase"], json!("commentary"));
+    assert!(body["output"][0].get("content").is_none());
+    assert!(body.get("output_text").is_none());
+    assert!(body.get("phase_text").is_none());
+}
+
+#[tokio::test]
+async fn returns_original_text_when_no_final_response_found() {
+    let sse_content = "data: {\"type\":\"response.started\"}\ndata: {\"type\":\"chunk\",\"delta\":\"text\"}\n";
+    let mut result = convert(sse_response(sse_content)).await;
+    let text = result.collect_text().await.unwrap();
+    assert_eq!(text, sse_content);
+}
+
+#[tokio::test]
+async fn skips_malformed_json_in_sse_stream() {
+    let sse_content = "data: not-json\ndata: {\"type\":\"response.done\",\"response\":{\"id\":\"resp_789\"}}\n";
+    let body = convert_json(sse_response(sse_content)).await;
+    assert_eq!(body, json!({ "id": "resp_789" }));
+}
+
+#[tokio::test]
+async fn handles_empty_sse_stream() {
+    let mut result = convert(sse_response("")).await;
+    let text = result.collect_text().await.unwrap();
+    assert_eq!(text, "");
+}
+
+#[tokio::test]
+async fn preserves_response_status_and_status_text() {
+    let sse_content = r#"data: {"type":"response.done","response":{"id":"x"}}"#;
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let result = convert(response).await;
+    assert_eq!(result.status, 200);
+    assert_eq!(result.status_text, "OK");
+}
+
+#[tokio::test]
+async fn reports_the_final_response_id_while_converting() {
+    let (callback, calls) = recording_callback();
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_123","object":"response"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_123","output":"test"}}"#,
+        "",
+    ]
+    .join("\n");
+    let mut result = convert_sse_to_json(
+        sse_response(&sse_content),
+        &HeaderMap::new(),
+        ConvertSseOptions { on_response_id: Some(callback), stream_stall_timeout_ms: None },
+    )
+    .await
+    .unwrap();
+    let body = result.collect_json().await.unwrap();
+    assert_eq!(body, json!({ "id": "resp_123", "output": "test" }));
+    assert_eq!(&*calls.lock().unwrap(), &["resp_123".to_string()]);
+}
+
+#[tokio::test]
+async fn h6_error_event_before_done_yields_non_2xx_and_no_id_capture() {
+    let (callback, calls) = recording_callback();
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_bad_123","object":"response"}}"#,
+        "",
+        r#"data: {"type":"error","message":"quota exceeded"}"#,
+        "",
+        r#"data: {"type":"response.done","response":{"id":"resp_bad_123","output":"bad"}}"#,
+        "",
+    ]
+    .join("\n");
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let result = convert_sse_to_json(
+        response,
+        &HeaderMap::new(),
+        ConvertSseOptions { on_response_id: Some(callback), stream_stall_timeout_ms: None },
+    )
+    .await
+    .unwrap();
+    assert!(!result.ok());
+    assert!(result.status >= 400);
+    assert!(calls.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn returns_raw_sse_text_when_stream_ends_without_terminal_event() {
+    let (callback, calls) = recording_callback();
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_partial_123","object":"response"}}"#,
+        "",
+        r#"data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"partial"}"#,
+        "",
+    ]
+    .join("\n");
+    let mut result = convert_sse_to_json(
+        sse_response(&sse_content),
+        &HeaderMap::new(),
+        ConvertSseOptions { on_response_id: Some(callback), stream_stall_timeout_ms: None },
+    )
+    .await
+    .unwrap();
+    let text = result.collect_text().await.unwrap();
+    assert_eq!(text, sse_content);
+    assert!(calls.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn ignores_oversized_semantic_indices() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_guarded_indices","object":"response"}}"#,
+        r#"data: {"type":"response.output_item.added","output_index":1000000,"item":{"id":"msg_big","type":"message","role":"assistant"}}"#,
+        r#"data: {"type":"response.output_text.done","output_index":1000000,"content_index":1000000,"text":"ignored"}"#,
+        r#"data: {"type":"response.reasoning_summary_part.done","output_index":1000000,"summary_index":1000000,"part":{"text":"ignored"}}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_guarded_indices","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+    assert_eq!(body, json!({ "id": "resp_guarded_indices", "object": "response" }));
+}
+
+#[tokio::test]
+async fn ignores_delta_events_with_missing_output_index() {
+    let sse_content = [
+        r#"data: {"type":"response.created","response":{"id":"resp_no_index","object":"response"}}"#,
+        r#"data: {"type":"response.output_text.delta","content_index":0,"delta":"orphan"}"#,
+        r#"data: {"type":"response.reasoning_summary_text.delta","summary_index":0,"delta":"orphan"}"#,
+        r#"data: {"type":"response.done","response":{"id":"resp_no_index","object":"response"}}"#,
+        "",
+    ]
+    .join("\n");
+    let body = convert_json(sse_response(&sse_content)).await;
+    assert_eq!(body["id"], json!("resp_no_index"));
+    assert!(body.get("output_text").is_none());
+    assert!(body.get("reasoning_summary_text").is_none());
+}
+
+#[tokio::test]
+async fn errors_when_sse_stream_exceeds_size_limit() {
+    let large_content = "a".repeat(20 * 1024 * 1024 + 1);
+    let error = convert_sse_to_json(
+        sse_response(&large_content),
+        &HeaderMap::new(),
+        ConvertSseOptions::default(),
+    )
+    .await
+    .expect_err("must exceed cap");
+    assert_eq!(error.to_string(), "SSE response exceeds 10485760 bytes limit");
+}
+
+#[tokio::test]
+async fn errors_when_stream_read_fails() {
+    let stream: BodyStream = futures::stream::once(async {
+        Err::<Bytes, BoxError>("Stream read error".to_string().into())
+    })
+    .boxed();
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+    let error = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect_err("must propagate read error");
+    assert_eq!(error.to_string(), "Stream read error");
+}
+
+#[tokio::test]
+async fn errors_when_stream_stalls_past_timeout() {
+    let stream: BodyStream = futures::stream::pending().boxed();
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+    let error = convert_sse_to_json(
+        response,
+        &HeaderMap::new(),
+        ConvertSseOptions { on_response_id: None, stream_stall_timeout_ms: Some(1_000.0) },
+    )
+    .await
+    .expect_err("must stall");
+    assert_eq!(
+        error.to_string(),
+        "SSE stream stalled for 1000ms while waiting for a terminal response event"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// attachResponseIdCapture
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn captures_response_ids_while_preserving_the_sse_stream() {
+    let (callback, calls) = recording_callback();
+    let sse_content = [
+        r#"data: {"type":"response.started"}"#,
+        "",
+        r#"data: {"type":"response.done","response":{"id":"resp_stream_123","output":"done"}}"#,
+        "",
+    ]
+    .join("\n");
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+
+    let mut captured =
+        attach_response_id_capture(sse_response(&sse_content), headers, Some(callback));
+    let text = captured.collect_text().await.unwrap();
+
+    assert_eq!(text, sse_content);
+    assert_eq!(&*calls.lock().unwrap(), &["resp_stream_123".to_string()]);
+    assert_eq!(captured.headers.get(CONTENT_TYPE).unwrap(), "text/event-stream");
+}
+
+#[tokio::test]
+async fn stops_capturing_response_ids_after_an_sse_error_event() {
+    let (callback, calls) = recording_callback();
+    let sse_content = [
+        r#"data: {"type":"error","message":"quota exceeded"}"#,
+        "",
+        r#"data: {"type":"response.done","response":{"id":"resp_bad_123","output":"done"}}"#,
+        "",
+    ]
+    .join("\n");
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+
+    let mut captured =
+        attach_response_id_capture(sse_response(&sse_content), headers, Some(callback));
+    let text = captured.collect_text().await.unwrap();
+
+    assert_eq!(text, sse_content);
+    assert!(calls.lock().unwrap().is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// isEmptyResponse
+// ---------------------------------------------------------------------------
+
+#[test]
+fn is_empty_response_suite() {
+    // null / undefined
+    assert!(is_empty_response(Some(&Value::Null)));
+    assert!(is_empty_response(None));
+    // empty / whitespace strings
+    assert!(is_empty_response(Some(&json!(""))));
+    assert!(is_empty_response(Some(&json!("   "))));
+    // empty object
+    assert!(is_empty_response(Some(&json!({}))));
+    // response object without meaningful content
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123" }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "model": "gpt-5.2" }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "object": "response" }))));
+    // null output (undefined output ≙ absent key, also empty)
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "output": null }))));
+    // empty output array
+    assert!(is_empty_response(Some(&json!({
+        "id": "resp_123",
+        "object": "response",
+        "model": "gpt-5.2",
+        "output": [],
+    }))));
+    // output entries all empty
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "output": [{}] }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "output": [{}, null] }))));
+    // empty / whitespace string output
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "output": "" }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "output": "   " }))));
+    // empty choices array
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "choices": [] }))));
+    // real output
+    assert!(!is_empty_response(Some(&json!({ "output": [{ "text": "hello" }] }))));
+    assert!(!is_empty_response(Some(&json!({ "id": "resp_123", "output": "some output" }))));
+    // real choices
+    assert!(!is_empty_response(Some(
+        &json!({ "choices": [{ "message": { "content": "hi" } }] })
+    )));
+    // empty choice objects
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "choices": [{}] }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "choices": [null] }))));
+    // content
+    assert!(!is_empty_response(Some(&json!({ "content": "hello world" }))));
+    assert!(!is_empty_response(Some(&json!({ "id": "resp_123", "content": [] }))));
+    // empty string content
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "content": "" }))));
+    assert!(is_empty_response(Some(&json!({ "id": "resp_123", "content": "   " }))));
+    // non-object primitives
+    assert!(!is_empty_response(Some(&json!(123))));
+    assert!(!is_empty_response(Some(&json!(true))));
+    assert!(!is_empty_response(Some(&json!("non-empty string"))));
+    // objects that are not response-like
+    assert!(!is_empty_response(Some(&json!({ "foo": "bar" }))));
+    assert!(!is_empty_response(Some(&json!({ "data": [1, 2, 3] }))));
+}
+
+// ---------------------------------------------------------------------------
+// SSE failure classification (stress audit H6/H7/M1)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn h6_mid_stream_error_event_yields_non_2xx() {
+    let sse_content = "data: {\"type\":\"response.output_text.delta\",\"delta\":\"partial\"}\ndata: {\"type\":\"error\",\"error\":{\"message\":\"upstream blew up\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let result = convert(response).await;
+    // Must NOT be a 200 — otherwise the caller records an account success.
+    assert!(!result.ok());
+    assert!(result.status >= 400);
+}
+
+#[tokio::test]
+async fn h7_response_failed_terminal_event_yields_non_2xx() {
+    let sse_content = "data: {\"type\":\"response.created\",\"response\":{\"id\":\"r1\"}}\ndata: {\"type\":\"response.failed\",\"response\":{\"id\":\"r1\",\"status\":\"failed\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let result = convert(response).await;
+    assert!(!result.ok());
+    assert!(result.status >= 400);
+}
+
+#[tokio::test]
+async fn h7_terminal_error_body_shape_is_byte_exact() {
+    let sse_content = "data: {\"type\":\"response.failed\",\"response\":{\"id\":\"r1\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let mut result = convert(response).await;
+    assert_eq!(result.status, 502);
+    assert_eq!(result.status_text, "Bad Gateway");
+    assert_eq!(
+        result.headers.get(CONTENT_TYPE).unwrap(),
+        "application/json; charset=utf-8"
+    );
+    let text = result.collect_text().await.unwrap();
+    assert_eq!(
+        text,
+        r#"{"error":{"message":"Upstream SSE stream terminated with a failure event","type":"upstream_stream_error","code":"sse_terminal_error"}}"#
+    );
+}
+
+#[tokio::test]
+async fn h7_response_incomplete_delivers_partial_response_as_success() {
+    // Hitting max_output_tokens / a content filter is a NORMAL early stop.
+    let sse_content = "data: {\"type\":\"response.created\",\"response\":{\"id\":\"r2\"}}\ndata: {\"type\":\"response.incomplete\",\"response\":{\"id\":\"r2\",\"status\":\"incomplete\",\"output\":\"partial\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let mut result = convert(response).await;
+    assert!(result.ok());
+    let body = result.collect_json().await.unwrap();
+    assert_eq!(body["id"], json!("r2"));
+    assert_eq!(body["status"], json!("incomplete"));
+}
+
+#[tokio::test]
+async fn control_clean_response_completed_stream_is_a_200_success() {
+    let sse_content = "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"ok1\",\"output\":\"done\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let mut result = convert(response).await;
+    assert!(result.ok());
+    let body = result.collect_json().await.unwrap();
+    assert_eq!(body, json!({ "id": "ok1", "output": "done" }));
+}
+
+#[tokio::test]
+async fn m1_parses_data_events_with_no_space_after_the_colon() {
+    let sse_content = "data:{\"type\":\"response.completed\",\"response\":{\"id\":\"nospace\",\"output\":\"ok\"}}\n";
+    let response = StreamResponse::from_text(200, "OK", HeaderMap::new(), sse_content);
+    let mut result = convert(response).await;
+    assert!(result.ok());
+    let body = result.collect_json().await.unwrap();
+    assert_eq!(body, json!({ "id": "nospace", "output": "ok" }));
+}
+
+// ---------------------------------------------------------------------------
+// REQ-HIGH-03: linear buffering with pre-append cap
+// (port of test/response-handler-sse-buffer.test.ts)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn accumulates_many_chunks_under_the_cap_without_throwing() {
+    let filler = "x".repeat(9 * 1024 * 1024);
+    let sse = format!(
+        "data: {{\"type\":\"response.started\"}}\ndata: {{\"type\":\"response.done\",\"response\":{{\"id\":\"resp_big\",\"output\":{}}}}}\n",
+        serde_json::to_string(&filler).unwrap()
+    );
+    let bytes = sse.as_bytes();
+    assert!(bytes.len() < MAX_SSE_SIZE_FOR_TEST);
+
+    let chunk_size = 128 * 1024;
+    let chunks: Vec<Bytes> = bytes
+        .chunks(chunk_size)
+        .map(Bytes::copy_from_slice)
+        .collect();
+    assert!(chunks.len() > 1);
+    let expected_chunks = chunks.len();
+
+    let (stream, count) = counting_stream(chunks);
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+    let body = convert_json(response).await;
+
+    assert_eq!(body["id"], json!("resp_big"));
+    assert_eq!(body["output"].as_str().unwrap().len(), filler.len());
+    // Every chunk was consumed (the done signal is the stream ending).
+    assert_eq!(count.load(Ordering::SeqCst), expected_chunks);
+}
+
+#[tokio::test]
+async fn throws_on_the_first_chunk_that_would_exceed_the_cap() {
+    // Chunk 1 stays under the cap; chunk 2 is small but pushes the total past
+    // MAX_SSE_SIZE. The pre-append check must reject before retaining it.
+    let near_cap = Bytes::from(vec![0x61u8; MAX_SSE_SIZE_FOR_TEST - 16]); // 'a'
+    let overflow = Bytes::from(vec![0x62u8; 64]); // 'b'
+    let (stream, count) = counting_stream(vec![near_cap, overflow]);
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+
+    let error = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect_err("must exceed cap");
+    assert!(error.to_string().contains("exceeds"));
+    assert!(error.to_string().contains("bytes limit"));
+    // Two reads: first accepted, second rejected pre-append; none after.
+    assert_eq!(count.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn throws_on_the_very_first_chunk_when_it_alone_exceeds_the_cap() {
+    let too_big = Bytes::from(vec![0x63u8; MAX_SSE_SIZE_FOR_TEST + 1]); // 'c'
+    let (stream, count) = counting_stream(vec![too_big]);
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+
+    let error = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect_err("must exceed cap");
+    assert!(error.to_string().contains("exceeds"));
+    assert_eq!(count.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn counts_utf8_bytes_rather_than_utf16_code_units_in_the_guard() {
+    // 😀 is 2 UTF-16 code units but 4 UTF-8 bytes. The guard must count bytes.
+    let repeats = (MAX_SSE_SIZE_FOR_TEST + 16).div_ceil(4);
+    let filler = "😀".repeat(repeats);
+    let sse = format!(
+        "data: {{\"type\":\"response.started\"}}\ndata: {{\"type\":\"response.done\",\"response\":{{\"id\":\"resp_emoji\",\"output\":{}}}}}\n",
+        serde_json::to_string(&filler).unwrap()
+    );
+    let bytes = sse.into_bytes();
+    assert!(bytes.len() > MAX_SSE_SIZE_FOR_TEST);
+
+    let (stream, count) = counting_stream(vec![Bytes::from(bytes)]);
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+
+    let error = convert_sse_to_json(response, &HeaderMap::new(), ConvertSseOptions::default())
+        .await
+        .expect_err("must exceed cap");
+    assert!(error.to_string().contains("exceeds"));
+    assert_eq!(count.load(Ordering::SeqCst), 1);
+}
+
+// ---------------------------------------------------------------------------
+// UTF-8 chunk-boundary integrity through the capture stream
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn attach_capture_handles_multibyte_sequences_split_across_chunks() {
+    let sse = "data: {\"type\":\"response.done\",\"response\":{\"id\":\"resp_😀\"}}\n";
+    let bytes = sse.as_bytes();
+    // Split inside the emoji's 4-byte sequence.
+    let split = sse.find("😀").unwrap() + 2;
+    let chunks = vec![
+        Bytes::copy_from_slice(&bytes[..split]),
+        Bytes::copy_from_slice(&bytes[split..]),
+    ];
+    let (stream, _count) = counting_stream(chunks);
+    let response = StreamResponse::new(200, "OK", HeaderMap::new(), Some(stream));
+
+    let (callback, calls) = recording_callback();
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+    let mut captured = attach_response_id_capture(response, headers, Some(callback));
+    let text = captured.collect_text().await.unwrap();
+
+    assert_eq!(text, sse);
+    assert_eq!(&*calls.lock().unwrap(), &["resp_😀".to_string()]);
+}
diff --git a/crates/request/tests/stream_failover_runtime_test.rs b/crates/request/tests/stream_failover_runtime_test.rs
new file mode 100644
index 000000000..62b810615
--- /dev/null
+++ b/crates/request/tests/stream_failover_runtime_test.rs
@@ -0,0 +1,556 @@
+//! Port of `test/stream-failover-runtime.test.ts`.
+//!
+//! `FakeServerResponse` mirrors the TS test double for Node's
+//! `ServerResponse` via the `ClientStreamWriter` trait: per-index
+//! backpressure, an event log for ordering assertions, drain/close/error
+//! signals, and production-faithful write-after-destroy throwing.
+
+use std::collections::HashSet;
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use bytes::Bytes;
+use futures::StreamExt;
+use futures::future::BoxFuture;
+use http::HeaderMap;
+use http::header::{HeaderName, HeaderValue};
+
+use cma_request::response_handler::{BodyStream, BoxError, StreamResponse};
+use cma_request::stream_failover_runtime::{
+    ClientStreamWriter, HOP_BY_HOP_HEADERS, StreamForwardStatus, forward_streaming_response,
+    read_error_body, response_headers_for_client, with_timeout,
+};
+
+// ---------------------------------------------------------------------------
+// Test doubles
+// ---------------------------------------------------------------------------
+
+/// TS `createStatus()` — only the fields this module touches.
+#[derive(Default)]
+struct TestStatus {
+    streams_started: u32,
+    last_error: Option<String>,
+}
+
+impl StreamForwardStatus for TestStatus {
+    fn increment_streams_started(&mut self) {
+        self.streams_started += 1;
+    }
+
+    fn set_last_error(&mut self, message: String) {
+        self.last_error = Some(message);
+    }
+}
+
+#[derive(Default)]
+struct FakeState {
+    status_code: Option<u16>,
+    headers: Vec<(String, String)>,
+    chunks: Vec<Vec<u8>>,
+    ended: bool,
+    destroyed: bool,
+    destroy_error: Option<String>,
+    /// Indices (0-based write order) for which write() reports a full buffer.
+    backpressure_writes: HashSet<usize>,
+    events: Vec<String>,
+}
+
+struct FakeInner {
+    state: Mutex<FakeState>,
+    /// Settles `wait_for_drain` (drain OR close OR error).
+    settle: tokio::sync::Notify,
+    closed_tx: tokio::sync::watch::Sender<bool>,
+    closed_rx: tokio::sync::watch::Receiver<bool>,
+}
+
+#[derive(Clone)]
+struct FakeServerResponse {
+    inner: Arc<FakeInner>,
+}
+
+impl FakeServerResponse {
+    fn new() -> Self {
+        let (closed_tx, closed_rx) = tokio::sync::watch::channel(false);
+        Self {
+            inner: Arc::new(FakeInner {
+                state: Mutex::new(FakeState::default()),
+                settle: tokio::sync::Notify::new(),
+                closed_tx,
+                closed_rx,
+            }),
+        }
+    }
+
+    fn with_backpressure(indices: &[usize]) -> Self {
+        let fake = Self::new();
+        fake.inner.state.lock().unwrap().backpressure_writes = indices.iter().copied().collect();
+        fake
+    }
+
+    fn emit_drain(&self) {
+        self.inner.state.lock().unwrap().events.push("drain".to_string());
+        self.inner.settle.notify_waiters();
+    }
+
+    fn emit_close(&self) {
+        let _ = self.inner.closed_tx.send(true);
+        self.inner.settle.notify_waiters();
+    }
+
+    /// Node destroys the response on a socket error before emitting it.
+    fn emit_error_after_destroy(&self) {
+        self.inner.state.lock().unwrap().destroyed = true;
+        self.inner.settle.notify_waiters();
+    }
+
+    fn state<T>(&self, f: impl FnOnce(&FakeState) -> T) -> T {
+        f(&self.inner.state.lock().unwrap())
+    }
+
+    fn body_text(&self) -> String {
+        self.state(|s| {
+            String::from_utf8_lossy(&s.chunks.iter().flatten().copied().collect::<Vec<u8>>())
+                .into_owned()
+        })
+    }
+}
+
+impl ClientStreamWriter for FakeServerResponse {
+    fn write_head(&mut self, status: u16, headers: Vec<(String, String)>) {
+        let mut state = self.inner.state.lock().unwrap();
+        state.status_code = Some(status);
+        state.headers = headers;
+    }
+
+    fn writable_ended(&self) -> bool {
+        self.inner.state.lock().unwrap().ended
+    }
+
+    fn destroyed(&self) -> bool {
+        self.inner.state.lock().unwrap().destroyed
+    }
+
+    fn write(&mut self, chunk: &[u8]) -> Result<bool, BoxError> {
+        let mut state = self.inner.state.lock().unwrap();
+        // Production-faithful: writing to a destroyed ServerResponse throws.
+        if state.destroyed {
+            return Err("ERR_STREAM_DESTROYED: write after destroy".to_string().into());
+        }
+        let index = state.chunks.len();
+        state.chunks.push(chunk.to_vec());
+        state.events.push(format!("write:{index}"));
+        Ok(!state.backpressure_writes.contains(&index))
+    }
+
+    fn wait_for_drain(&mut self) -> BoxFuture<'_, ()> {
+        let inner = self.inner.clone();
+        Box::pin(async move {
+            inner.settle.notified().await;
+        })
+    }
+
+    fn end(&mut self) {
+        self.inner.state.lock().unwrap().ended = true;
+    }
+
+    fn destroy(&mut self, error: Option<BoxError>) {
+        let mut state = self.inner.state.lock().unwrap();
+        state.destroyed = true;
+        state.destroy_error = error.map(|e| e.to_string());
+    }
+
+    fn closed(&self) -> BoxFuture<'static, ()> {
+        let mut rx = self.inner.closed_rx.clone();
+        Box::pin(async move {
+            loop {
+                if *rx.borrow() {
+                    return;
+                }
+                if rx.changed().await.is_err() {
+                    futures::future::pending::<()>().await;
+                }
+            }
+        })
+    }
+}
+
+fn stream_of(chunks: Vec<Bytes>) -> BodyStream {
+    futures::stream::iter(chunks.into_iter().map(Ok::<_, BoxError>)).boxed()
+}
+
+fn upstream_with_chunks(status: u16, headers: HeaderMap, chunks: Vec<&str>) -> StreamResponse {
+    StreamResponse::new(
+        status,
+        "",
+        headers,
+        Some(stream_of(chunks.into_iter().map(|c| Bytes::copy_from_slice(c.as_bytes())).collect())),
+    )
+}
+
+fn header_map(pairs: &[(&str, &str)]) -> HeaderMap {
+    let mut map = HeaderMap::new();
+    for (name, value) in pairs {
+        map.append(
+            HeaderName::from_bytes(name.as_bytes()).unwrap(),
+            HeaderValue::from_str(value).unwrap(),
+        );
+    }
+    map
+}
+
+fn error_counter() -> (Arc<AtomicU32>, impl FnOnce()) {
+    let count = Arc::new(AtomicU32::new(0));
+    let inc = count.clone();
+    (count, move || {
+        inc.fetch_add(1, Ordering::SeqCst);
+    })
+}
+
+// ---------------------------------------------------------------------------
+// responseHeadersForClient
+// ---------------------------------------------------------------------------
+
+#[test]
+fn drops_hop_by_hop_private_rotation_and_content_encoding_headers() {
+    let upstream = header_map(&[
+        ("content-type", "application/json"),
+        ("x-request-id", "req_1"),
+        ("connection", "keep-alive"),
+        ("transfer-encoding", "chunked"),
+        ("content-encoding", "gzip"),
+        ("x-codex-multi-auth-account-email", "user@example.com"),
+        ("x-codex-multi-auth-account-id", "acc_1"),
+    ]);
+    let mut filtered = response_headers_for_client(&upstream);
+    filtered.sort();
+    assert_eq!(
+        filtered,
+        vec![
+            ("content-type".to_string(), "application/json".to_string()),
+            ("x-request-id".to_string(), "req_1".to_string()),
+        ]
+    );
+}
+
+#[test]
+fn blocks_any_header_under_the_private_account_prefix_not_just_known_names() {
+    let upstream = header_map(&[
+        ("content-type", "application/json"),
+        ("x-codex-multi-auth-account-plan", "pro"),
+        ("x-codex-multi-auth-account-future-field", "secret"),
+    ]);
+    assert_eq!(
+        response_headers_for_client(&upstream),
+        vec![("content-type".to_string(), "application/json".to_string())]
+    );
+}
+
+#[test]
+fn covers_every_hop_by_hop_header_in_the_exported_set() {
+    let mut upstream = HeaderMap::new();
+    for name in HOP_BY_HOP_HEADERS {
+        upstream.append(
+            HeaderName::from_bytes(name.as_bytes()).unwrap(),
+            HeaderValue::from_static("1"),
+        );
+    }
+    assert_eq!(response_headers_for_client(&upstream), Vec::new());
+}
+
+// ---------------------------------------------------------------------------
+// withTimeout
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn with_timeout_resolves_with_the_underlying_future_before_the_deadline() {
+    let result = with_timeout(async { "ok" }, 1_000.0, || (), "stalled").await;
+    assert_eq!(result.unwrap(), "ok");
+}
+
+#[tokio::test]
+async fn with_timeout_rejects_with_message_and_fires_on_timeout_on_stall() {
+    let (count, on_timeout) = error_counter();
+    let error = with_timeout(
+        futures::future::pending::<()>(),
+        30.0,
+        on_timeout,
+        "upstream stalled",
+    )
+    .await
+    .expect_err("must time out");
+    assert_eq!(error.to_string(), "upstream stalled");
+    assert_eq!(count.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn with_timeout_enforces_a_minimum_1ms_timer_for_non_positive_timeouts() {
+    let error = with_timeout(futures::future::pending::<()>(), 0.0, || (), "stalled")
+        .await
+        .expect_err("must time out");
+    assert_eq!(error.to_string(), "stalled");
+}
+
+// ---------------------------------------------------------------------------
+// readErrorBody
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn reads_a_streamed_body_to_completion() {
+    let mut response = StreamResponse::new(
+        200,
+        "",
+        HeaderMap::new(),
+        Some(stream_of(vec![
+            Bytes::from_static(br#"{"error":"#),
+            Bytes::from_static(br#""nope"}"#),
+        ])),
+    );
+    assert_eq!(read_error_body(&mut response, 1_000.0, None).await, r#"{"error":"nope"}"#);
+}
+
+#[tokio::test]
+async fn caps_the_body_at_max_bytes_and_returns_the_bytes_read_so_far() {
+    let big = Bytes::from(vec![b'x'; 64]);
+    let mut response = StreamResponse::new(
+        200,
+        "",
+        HeaderMap::new(),
+        Some(stream_of(vec![big.clone(), big.clone(), big])),
+    );
+    // Cap below the second chunk's cumulative size: the overflowing chunk is
+    // dropped, so only the first 64 bytes survive.
+    assert_eq!(
+        read_error_body(&mut response, 1_000.0, Some(100)).await,
+        "x".repeat(64)
+    );
+}
+
+#[tokio::test]
+async fn returns_the_partial_body_when_a_later_chunk_stalls_past_the_idle_timeout() {
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"partial"))
+    })
+    .chain(futures::stream::pending())
+    .boxed();
+    let mut response = StreamResponse::new(200, "", HeaderMap::new(), Some(stream));
+    assert_eq!(read_error_body(&mut response, 25.0, None).await, "partial");
+}
+
+#[tokio::test]
+async fn falls_back_to_empty_when_the_response_has_no_streamable_body() {
+    let mut response = StreamResponse::new(200, "", HeaderMap::new(), None);
+    assert_eq!(read_error_body(&mut response, 50.0, None).await, "");
+}
+
+// ---------------------------------------------------------------------------
+// forwardStreamingResponse
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn forwards_status_filtered_headers_and_chunks_then_ends() {
+    let mut res = FakeServerResponse::new();
+    let mut status = TestStatus::default();
+    let upstream = upstream_with_chunks(
+        200,
+        header_map(&[
+            ("content-type", "text/event-stream"),
+            ("connection", "keep-alive"),
+            ("x-codex-multi-auth-account-id", "acc_1"),
+        ]),
+        vec!["data: a\n\n", "data: b\n\n"],
+    );
+
+    let (errors, on_stream_error) = error_counter();
+    let ok = forward_streaming_response(upstream, &mut res, &mut status, on_stream_error, 1_000).await;
+
+    assert!(ok);
+    assert_eq!(status.streams_started, 1);
+    assert_eq!(res.state(|s| s.status_code), Some(200));
+    assert_eq!(
+        res.state(|s| s.headers.clone()),
+        vec![("content-type".to_string(), "text/event-stream".to_string())]
+    );
+    assert_eq!(res.body_text(), "data: a\n\ndata: b\n\n");
+    assert!(res.state(|s| s.ended));
+    assert_eq!(errors.load(Ordering::SeqCst), 0);
+}
+
+#[tokio::test]
+async fn pauses_writes_while_the_client_buffer_is_full_and_resumes_on_drain() {
+    let mut res = FakeServerResponse::with_backpressure(&[0]);
+    let mut status = TestStatus::default();
+    let upstream = upstream_with_chunks(200, HeaderMap::new(), vec!["data: a\n\n", "data: b\n\n"]);
+
+    let drain_handle = {
+        let res = res.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+            res.emit_drain();
+        })
+    };
+
+    let ok =
+        forward_streaming_response(upstream, &mut res, &mut status, || (), 5_000).await;
+    drain_handle.await.unwrap();
+
+    assert!(ok);
+    assert_eq!(res.body_text(), "data: a\n\ndata: b\n\n");
+    let events = res.state(|s| s.events.clone());
+    let drain = events.iter().position(|e| e == "drain").unwrap();
+    let write0 = events.iter().position(|e| e == "write:0").unwrap();
+    let write1 = events.iter().position(|e| e == "write:1").unwrap();
+    assert!(drain > write0);
+    assert!(write1 > drain);
+    assert!(res.state(|s| s.ended));
+}
+
+#[tokio::test]
+async fn waits_for_a_drain_per_backpressured_write_across_multiple_chunks() {
+    let mut res = FakeServerResponse::with_backpressure(&[0, 2]);
+    let mut status = TestStatus::default();
+    let upstream = upstream_with_chunks(200, HeaderMap::new(), vec!["a", "b", "c"]);
+
+    // Each backpressured write gets its own drain; emit one per pause.
+    let drain_task = {
+        let res = res.clone();
+        tokio::spawn(async move {
+            loop {
+                tokio::time::sleep(Duration::from_millis(15)).await;
+                res.emit_drain();
+            }
+        })
+    };
+
+    let ok =
+        forward_streaming_response(upstream, &mut res, &mut status, || (), 5_000).await;
+    drain_task.abort();
+
+    assert!(ok);
+    assert_eq!(res.body_text(), "abc");
+    let events = res.state(|s| s.events.clone());
+    let first_drain = events.iter().position(|e| e == "drain").unwrap();
+    let last_drain = events.iter().rposition(|e| e == "drain").unwrap();
+    let write0 = events.iter().position(|e| e == "write:0").unwrap();
+    let write1 = events.iter().position(|e| e == "write:1").unwrap();
+    let write2 = events.iter().position(|e| e == "write:2").unwrap();
+    assert!(first_drain > write0);
+    assert!(write1 > first_drain);
+    assert!(last_drain > write2);
+    assert!(res.state(|s| s.ended));
+}
+
+#[tokio::test]
+async fn does_not_park_forever_when_the_client_closes_during_backpressure() {
+    let mut res = FakeServerResponse::with_backpressure(&[0]);
+    let mut status = TestStatus::default();
+    let upstream = upstream_with_chunks(200, HeaderMap::new(), vec!["data: a\n\n", "data: b\n\n"]);
+
+    // The client disconnects instead of draining: the forwarder must finish
+    // via the client-close path instead of parking on the drain wait.
+    let close_handle = {
+        let res = res.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+            res.emit_close();
+        })
+    };
+
+    let ok =
+        forward_streaming_response(upstream, &mut res, &mut status, || (), 5_000).await;
+    close_handle.await.unwrap();
+
+    assert!(ok);
+    assert_eq!(res.body_text(), "data: a\n\n");
+}
+
+#[tokio::test]
+async fn fails_the_stream_when_the_socket_errors_during_backpressure() {
+    // The error event settles the drain wait silently; the failure must then
+    // surface through the next write throwing on the destroyed response and
+    // the catch path recording it.
+    let mut res = FakeServerResponse::with_backpressure(&[0]);
+    let mut status = TestStatus::default();
+    let upstream = upstream_with_chunks(200, HeaderMap::new(), vec!["data: a\n\n", "data: b\n\n"]);
+
+    let error_handle = {
+        let res = res.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+            res.emit_error_after_destroy();
+        })
+    };
+
+    let (errors, on_stream_error) = error_counter();
+    let ok =
+        forward_streaming_response(upstream, &mut res, &mut status, on_stream_error, 5_000).await;
+    error_handle.await.unwrap();
+
+    assert!(!ok);
+    assert_eq!(errors.load(Ordering::SeqCst), 1);
+    assert!(status.last_error.unwrap().contains("write after destroy"));
+    assert_eq!(res.body_text(), "data: a\n\n");
+    assert!(!res.state(|s| s.ended));
+}
+
+#[tokio::test]
+async fn ends_immediately_when_the_upstream_has_no_body() {
+    let mut res = FakeServerResponse::new();
+    let mut status = TestStatus::default();
+    let upstream = StreamResponse::new(204, "", HeaderMap::new(), None);
+
+    let ok = forward_streaming_response(upstream, &mut res, &mut status, || (), 1_000).await;
+
+    assert!(ok);
+    assert_eq!(res.state(|s| s.status_code), Some(204));
+    assert!(res.state(|s| s.ended));
+    assert!(res.state(|s| s.chunks.is_empty()));
+}
+
+#[tokio::test]
+async fn records_the_stall_error_destroys_the_response_and_reports_failure() {
+    let mut res = FakeServerResponse::new();
+    let mut status = TestStatus::default();
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"data: a\n\n"))
+    })
+    .chain(futures::stream::pending())
+    .boxed();
+    let upstream = StreamResponse::new(200, "", HeaderMap::new(), Some(stream));
+
+    let (errors, on_stream_error) = error_counter();
+    let ok = forward_streaming_response(upstream, &mut res, &mut status, on_stream_error, 25).await;
+
+    assert!(!ok);
+    assert_eq!(errors.load(Ordering::SeqCst), 1);
+    assert_eq!(status.last_error.as_deref(), Some("upstream stream stalled after 25ms"));
+    assert!(res.state(|s| s.destroyed));
+    assert!(res.state(|s| s.destroy_error.is_some()));
+    assert_eq!(res.body_text(), "data: a\n\n");
+    assert!(!res.state(|s| s.ended));
+}
+
+#[tokio::test]
+async fn fails_the_stream_when_the_upstream_read_rejects_mid_stream() {
+    let mut res = FakeServerResponse::new();
+    let mut status = TestStatus::default();
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"data: a\n\n"))
+    })
+    .chain(futures::stream::once(async {
+        Err::<Bytes, BoxError>("socket reset".to_string().into())
+    }))
+    .boxed();
+    let upstream = StreamResponse::new(200, "", HeaderMap::new(), Some(stream));
+
+    let (errors, on_stream_error) = error_counter();
+    let ok =
+        forward_streaming_response(upstream, &mut res, &mut status, on_stream_error, 1_000).await;
+
+    assert!(!ok);
+    assert_eq!(errors.load(Ordering::SeqCst), 1);
+    assert_eq!(status.last_error.as_deref(), Some("socket reset"));
+    assert!(res.state(|s| s.destroyed));
+    assert!(res.state(|s| s.destroy_error.is_some()));
+    assert!(!res.state(|s| s.ended));
+}
diff --git a/crates/request/tests/stream_failover_test.rs b/crates/request/tests/stream_failover_test.rs
new file mode 100644
index 000000000..bc4f8ec5e
--- /dev/null
+++ b/crates/request/tests/stream_failover_test.rs
@@ -0,0 +1,288 @@
+//! Port of `test/stream-failover.test.ts`.
+//!
+//! Not ported 1:1: the two "unhandled rejection" tests (hostile
+//! `releaseLock`, pump-rejection safety net) exercise web-streams lock
+//! mechanics with no Rust analogue; the cancellation test below covers the
+//! equivalent guarantee (dropping the wrapped body cancels the source).
+//!
+//! Timing note: soft/stall timeouts floor at 1000 ms (same as TS), so the
+//! stall-driven tests each take about a second of wall time.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+
+use bytes::Bytes;
+use futures::StreamExt;
+use http::HeaderMap;
+use http::header::{CONTENT_TYPE, HeaderValue};
+
+use cma_request::response_handler::{BodyStream, BoxError, StreamResponse};
+use cma_request::stream_failover::{StreamFailoverOptions, with_streaming_failover};
+
+fn event_stream_headers() -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+    headers
+}
+
+fn make_sse_response(payload: &str) -> StreamResponse {
+    StreamResponse::from_text(200, "", event_stream_headers(), payload)
+}
+
+/// A response whose stream yields one chunk then stalls forever.
+fn make_stalling_response() -> StreamResponse {
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"data: first\n\n"))
+    })
+    .chain(futures::stream::pending())
+    .boxed();
+    StreamResponse::new(200, "", event_stream_headers(), Some(stream))
+}
+
+/// A response whose stream never yields anything.
+fn make_idle_response() -> StreamResponse {
+    let stream: BodyStream = futures::stream::pending().boxed();
+    StreamResponse::new(200, "", event_stream_headers(), Some(stream))
+}
+
+#[tokio::test]
+async fn returns_original_response_when_max_failovers_disabled() {
+    let mut response = with_streaming_failover(
+        make_sse_response("data: ok\n\n"),
+        |_attempt, _emitted| async { Ok(Some(make_sse_response("data: fallback\n\n"))) },
+        StreamFailoverOptions {
+            max_failovers: Some(0.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains("data: ok"));
+}
+
+#[tokio::test]
+async fn switches_to_fallback_stream_when_primary_stalls() {
+    let calls = Arc::new(AtomicU32::new(0));
+    let counter = calls.clone();
+    let mut response = with_streaming_failover(
+        make_idle_response(),
+        move |_attempt, _emitted| {
+            let counter = counter.clone();
+            async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                Ok(Some(make_sse_response("data: second\n\n")))
+            }
+        },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains("codex-multi-auth failover 1"));
+    assert!(text.contains("data: second"));
+    assert_eq!(calls.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn includes_request_id_marker_when_provided() {
+    let mut response = with_streaming_failover(
+        make_idle_response(),
+        |_attempt, _emitted| async { Ok(Some(make_sse_response("data: fallback\n\n"))) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            request_instance_id: Some("req-123".to_string()),
+            ..Default::default()
+        },
+    );
+    let text = response.collect_text().await.unwrap();
+    assert!(text.contains("codex-multi-auth failover 1 req:req-123"));
+}
+
+#[tokio::test]
+async fn failover_marker_bytes_are_exact() {
+    let mut response = with_streaming_failover(
+        make_idle_response(),
+        |_attempt, _emitted| async { Ok(Some(make_sse_response("data: fallback\n\n"))) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let text = response.collect_text().await.unwrap();
+    // Byte-exact SSE comment contract (spec 06 gotcha 14).
+    assert_eq!(text, ": codex-multi-auth failover 1\n\ndata: fallback\n\n");
+}
+
+#[tokio::test]
+async fn errors_when_fallback_is_unavailable() {
+    let mut response = with_streaming_failover(
+        make_idle_response(),
+        |_attempt, _emitted| async { Ok(None) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let error = response.collect_text().await.expect_err("must stall");
+    assert!(error.to_string().contains("SSE stream stalled"));
+}
+
+#[tokio::test]
+async fn propagates_fallback_provider_exceptions_deterministically() {
+    let mut response = with_streaming_failover(
+        make_idle_response(),
+        |_attempt, _emitted| async { Err::<Option<StreamResponse>, BoxError>("fallback exploded".to_string().into()) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let error = response.collect_text().await.expect_err("must explode");
+    assert!(error.to_string().contains("fallback exploded"));
+}
+
+#[tokio::test]
+async fn does_not_trigger_fallback_when_read_error_races_after_bytes_emitted() {
+    let calls = Arc::new(AtomicU32::new(0));
+    let counter = calls.clone();
+    // Primary emits a chunk, then errors ~20ms later.
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"data: first\n\n"))
+    })
+    .chain(futures::stream::once(async {
+        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+        Err::<Bytes, BoxError>("primary read failure".to_string().into())
+    }))
+    .boxed();
+    let race_response = StreamResponse::new(200, "", event_stream_headers(), Some(stream));
+
+    let mut response = with_streaming_failover(
+        race_response,
+        move |_attempt, _emitted| {
+            let counter = counter.clone();
+            async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                Ok(Some(make_sse_response("data: fallback\n\n")))
+            }
+        },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            soft_timeout_ms: Some(10.0),
+            hard_timeout_ms: Some(20.0),
+            ..Default::default()
+        },
+    );
+    let error = response.collect_text().await.expect_err("must fail");
+    assert!(error.to_string().contains("primary read failure"));
+    assert_eq!(calls.load(Ordering::SeqCst), 0);
+}
+
+#[tokio::test]
+async fn does_not_replay_after_bytes_have_already_been_emitted() {
+    let calls = Arc::new(AtomicU32::new(0));
+    let counter = calls.clone();
+    let mut response = with_streaming_failover(
+        make_stalling_response(),
+        move |_attempt, _emitted| {
+            let counter = counter.clone();
+            async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                Ok(Some(make_sse_response("data: fallback\n\n")))
+            }
+        },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10.0),
+            ..Default::default()
+        },
+    );
+    let error = response.collect_text().await.expect_err("must stall");
+    assert!(error.to_string().contains("SSE stream stalled"));
+    assert_eq!(calls.load(Ordering::SeqCst), 0);
+}
+
+/// Guard whose Drop marks the source stream as cancelled.
+struct DropGuard(Arc<AtomicBool>);
+
+impl Drop for DropGuard {
+    fn drop(&mut self) {
+        self.0.store(true, Ordering::SeqCst);
+    }
+}
+
+#[tokio::test]
+async fn releases_underlying_source_when_wrapped_stream_is_cancelled() {
+    let cancelled = Arc::new(AtomicBool::new(false));
+    let guard = DropGuard(cancelled.clone());
+    // Source: one chunk, then pending forever; dropping it drops the guard.
+    let stream: BodyStream = futures::stream::unfold(
+        (Some(Bytes::from_static(b"data: first\n\n")), guard),
+        |(chunk, guard)| async move {
+            match chunk {
+                Some(chunk) => Some((Ok::<_, BoxError>(chunk), (None, guard))),
+                None => {
+                    futures::future::pending::<()>().await;
+                    unreachable!()
+                }
+            }
+        },
+    )
+    .boxed();
+    let source = StreamResponse::new(200, "", event_stream_headers(), Some(stream));
+
+    let mut response = with_streaming_failover(
+        source,
+        |_attempt, _emitted| async { Ok(None) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            stall_timeout_ms: Some(10_000.0),
+            ..Default::default()
+        },
+    );
+
+    let mut body = response.body.take().expect("wrapped body");
+    let first = body.next().await.expect("first chunk").expect("ok chunk");
+    assert_eq!(&first[..], b"data: first\n\n");
+
+    // Cancel the wrapped stream (TS reader.cancel()): drop it, give the pump
+    // a moment to observe the closed channel, then check the source was
+    // cancelled (dropped).
+    drop(body);
+    for _ in 0..50 {
+        if cancelled.load(Ordering::SeqCst) {
+            break;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+    }
+    assert!(cancelled.load(Ordering::SeqCst));
+}
+
+#[tokio::test]
+async fn preserves_status_and_ensures_content_type_on_the_wrapper() {
+    // Headers WITHOUT content-type: the wrapper must add the SSE default.
+    let stream: BodyStream = futures::stream::once(async {
+        Ok::<_, BoxError>(Bytes::from_static(b"data: ok\n\n"))
+    })
+    .boxed();
+    let source = StreamResponse::new(201, "Created", HeaderMap::new(), Some(stream));
+    let response = with_streaming_failover(
+        source,
+        |_attempt, _emitted| async { Ok(None) },
+        StreamFailoverOptions {
+            max_failovers: Some(1.0),
+            ..Default::default()
+        },
+    );
+    assert_eq!(response.status, 201);
+    assert_eq!(response.status_text, "Created");
+    assert_eq!(
+        response.headers.get(CONTENT_TYPE).unwrap(),
+        "text/event-stream; charset=utf-8"
+    );
+}
diff --git a/crates/rotation/Cargo.toml b/crates/rotation/Cargo.toml
new file mode 100644
index 000000000..f6da1bea9
--- /dev/null
+++ b/crates/rotation/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+name = "cma-rotation"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde_json.workspace = true
+tokio.workspace = true
+rand.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/rotation/src/circuit_breaker.rs b/crates/rotation/src/circuit_breaker.rs
new file mode 100644
index 000000000..df0a38810
--- /dev/null
+++ b/crates/rotation/src/circuit_breaker.rs
@@ -0,0 +1,730 @@
+//! Port of `lib/circuit-breaker.ts` — classic closed/open/half-open breaker
+//! plus a bounded process-global registry.
+//!
+//! Contracts carried over verbatim (spec 04 §2 + gotcha 5):
+//! - `can_execute()` **THROWS** [`CircuitOpenError`] (never returns `false`
+//!   when blocked) and MUTATES (half-open attempt counter, automatic
+//!   open→half-open transition); `is_available*` is the pure, non-mutating
+//!   predicate.
+//! - Defaults: 3 failures / 60 s window, 30 s reset timeout, 1 half-open
+//!   probe. Config is honored only at construction.
+//! - Registry cap 100 with **insertion-order** eviction (first map key — the
+//!   oldest-created entry, NOT LRU). `remove_circuit_breaker` exists so a
+//!   removed-then-re-added account starts with a fresh closed circuit
+//!   (accounts-02).
+//!
+//! In-memory only; nothing here implements `Serialize` (never-persist
+//! boundary, ARCHITECTURE §8.4). The wall clock is injectable purely as the
+//! test seam replacing vitest fake timers.
+
+use std::sync::{Arc, LazyLock, Mutex, MutexGuard};
+
+use cma_core::clock::{Clock, system_clock};
+
+/// `CircuitBreakerConfig`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CircuitBreakerConfig {
+    /// Failures within the window required to open the circuit.
+    pub failure_threshold: usize,
+    /// Sliding window (ms) in which failures are counted.
+    pub failure_window_ms: i64,
+    /// Wait (ms) before an open circuit admits a half-open probe.
+    pub reset_timeout_ms: i64,
+    /// Probe budget per half-open window.
+    pub half_open_max_attempts: u32,
+}
+
+/// `DEFAULT_CIRCUIT_BREAKER_CONFIG` = `{ 3, 60_000, 30_000, 1 }`.
+pub const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig = CircuitBreakerConfig {
+    failure_threshold: 3,
+    failure_window_ms: 60_000,
+    reset_timeout_ms: 30_000,
+    half_open_max_attempts: 1,
+};
+
+impl Default for CircuitBreakerConfig {
+    fn default() -> Self {
+        DEFAULT_CIRCUIT_BREAKER_CONFIG
+    }
+}
+
+/// `CircuitState = "closed" | "open" | "half-open"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum CircuitState {
+    /// Normal operation.
+    Closed,
+    /// Blocking; waiting out the reset timeout.
+    Open,
+    /// Admitting a bounded number of probe requests.
+    HalfOpen,
+}
+
+impl CircuitState {
+    /// The TS string form (`"closed" | "open" | "half-open"`).
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            CircuitState::Closed => "closed",
+            CircuitState::Open => "open",
+            CircuitState::HalfOpen => "half-open",
+        }
+    }
+}
+
+impl std::fmt::Display for CircuitState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// `CircuitOpenError` — thrown by [`CircuitBreaker::can_execute`] when the
+/// circuit blocks execution. `name = "CircuitOpenError"`; default message
+/// `"Circuit is open"` (half-open saturation uses `"Circuit is half-open"`).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CircuitOpenError {
+    message: String,
+}
+
+impl CircuitOpenError {
+    /// The TS `Error.name`.
+    pub const NAME: &'static str = "CircuitOpenError";
+
+    /// Error with the default message `"Circuit is open"`.
+    pub fn new() -> Self {
+        Self::with_message("Circuit is open")
+    }
+
+    /// Error with a custom message.
+    pub fn with_message(message: impl Into<String>) -> Self {
+        CircuitOpenError {
+            message: message.into(),
+        }
+    }
+
+    /// The frozen error message.
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    /// The TS `Error.name` (`"CircuitOpenError"`).
+    pub fn name(&self) -> &'static str {
+        Self::NAME
+    }
+}
+
+impl Default for CircuitOpenError {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl std::fmt::Display for CircuitOpenError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for CircuitOpenError {}
+
+/// Mutable breaker state. In-memory only; never serialized.
+#[derive(Debug)]
+struct BreakerState {
+    state: CircuitState,
+    /// Failure timestamps (epoch ms) inside the sliding window.
+    failures: Vec<i64>,
+    last_state_change: i64,
+    half_open_attempts: u32,
+}
+
+/// Per-key circuit breaker gating accounts after repeated failures.
+///
+/// Thread-safe (interior mutability) so registry entries can be shared as
+/// [`Arc<CircuitBreaker>`] across callers, mirroring the shared TS instances.
+pub struct CircuitBreaker {
+    config: CircuitBreakerConfig,
+    clock: Arc<dyn Clock>,
+    inner: Mutex<BreakerState>,
+}
+
+impl Default for CircuitBreaker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl CircuitBreaker {
+    /// Breaker with [`DEFAULT_CIRCUIT_BREAKER_CONFIG`] and the system clock.
+    pub fn new() -> Self {
+        Self::with_config(DEFAULT_CIRCUIT_BREAKER_CONFIG)
+    }
+
+    /// Breaker with a custom config (TS `Partial<…>` merge ⇒ struct-update
+    /// syntax over [`CircuitBreakerConfig::default`]).
+    pub fn with_config(config: CircuitBreakerConfig) -> Self {
+        Self::with_config_and_clock(config, system_clock())
+    }
+
+    /// Test seam: custom config plus an injected clock (fake-timer analogue).
+    pub fn with_config_and_clock(config: CircuitBreakerConfig, clock: Arc<dyn Clock>) -> Self {
+        let now = clock.now_ms();
+        CircuitBreaker {
+            config,
+            clock,
+            inner: Mutex::new(BreakerState {
+                state: CircuitState::Closed,
+                failures: Vec::new(),
+                last_state_change: now,
+                half_open_attempts: 0,
+            }),
+        }
+    }
+
+    fn lock(&self) -> MutexGuard<'_, BreakerState> {
+        self.inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+
+    /// Gate a request through the breaker. Returns `Ok(true)` when execution
+    /// is admitted; **returns `Err(CircuitOpenError)` instead of `false`**
+    /// when blocked. Mutates: an elapsed open circuit transitions to
+    /// half-open, and admitted half-open probes consume the attempt budget.
+    pub fn can_execute(&self) -> Result<bool, CircuitOpenError> {
+        let now = self.clock.now_ms();
+        let mut state = self.lock();
+
+        if state.state == CircuitState::Open {
+            if now - state.last_state_change >= self.config.reset_timeout_ms {
+                // transitionToHalfOpen
+                state.state = CircuitState::HalfOpen;
+                state.last_state_change = now;
+                state.half_open_attempts = 0;
+            } else {
+                return Err(CircuitOpenError::new());
+            }
+        }
+
+        if state.state == CircuitState::HalfOpen {
+            if state.half_open_attempts >= self.config.half_open_max_attempts {
+                if now - state.last_state_change >= self.config.reset_timeout_ms {
+                    // resetHalfOpenProbeWindow
+                    state.last_state_change = now;
+                    state.half_open_attempts = 0;
+                } else {
+                    return Err(CircuitOpenError::with_message("Circuit is half-open"));
+                }
+            }
+            state.half_open_attempts += 1;
+            return Ok(true);
+        }
+
+        Ok(true)
+    }
+
+    /// Pure, non-mutating availability predicate at the current wall time.
+    pub fn is_available(&self) -> bool {
+        self.is_available_at(self.clock.now_ms())
+    }
+
+    /// Pure, non-mutating availability predicate at an explicit `now`
+    /// (TS `isAvailable(now = Date.now())`).
+    pub fn is_available_at(&self, now: i64) -> bool {
+        let state = self.lock();
+        match state.state {
+            CircuitState::Open => now - state.last_state_change >= self.config.reset_timeout_ms,
+            CircuitState::HalfOpen => {
+                state.half_open_attempts < self.config.half_open_max_attempts
+                    || now - state.last_state_change >= self.config.reset_timeout_ms
+            }
+            CircuitState::Closed => true,
+        }
+    }
+
+    /// Half-open ⇒ full reset to closed (clears failures). Closed ⇒ prune
+    /// failures outside the window. Open ⇒ no-op.
+    pub fn record_success(&self) {
+        let now = self.clock.now_ms();
+        let mut state = self.lock();
+        match state.state {
+            CircuitState::HalfOpen => reset_to_closed(&mut state, now),
+            CircuitState::Closed => prune_failures(&mut state, self.config.failure_window_ms, now),
+            CircuitState::Open => {}
+        }
+    }
+
+    /// Prune + record a failure timestamp. Half-open ⇒ reopen; closed with
+    /// `failures >= threshold` ⇒ open.
+    pub fn record_failure(&self) {
+        let now = self.clock.now_ms();
+        let mut state = self.lock();
+        prune_failures(&mut state, self.config.failure_window_ms, now);
+        state.failures.push(now);
+
+        if state.state == CircuitState::HalfOpen {
+            transition_to_open(&mut state, now);
+            return;
+        }
+
+        if state.state == CircuitState::Closed
+            && state.failures.len() >= self.config.failure_threshold
+        {
+            transition_to_open(&mut state, now);
+        }
+    }
+
+    /// Current state.
+    pub fn get_state(&self) -> CircuitState {
+        self.lock().state
+    }
+
+    /// Force-close and clear failures.
+    pub fn reset(&self) {
+        let now = self.clock.now_ms();
+        let mut state = self.lock();
+        reset_to_closed(&mut state, now);
+    }
+
+    /// Failure count after pruning the sliding window (mutating, like TS).
+    pub fn get_failure_count(&self) -> usize {
+        let now = self.clock.now_ms();
+        let mut state = self.lock();
+        prune_failures(&mut state, self.config.failure_window_ms, now);
+        state.failures.len()
+    }
+
+    /// Remaining wait until an open circuit admits a probe; 0 when not open.
+    pub fn get_time_until_reset(&self) -> i64 {
+        let now = self.clock.now_ms();
+        let state = self.lock();
+        if state.state != CircuitState::Open {
+            return 0;
+        }
+        let elapsed = now - state.last_state_change;
+        (self.config.reset_timeout_ms - elapsed).max(0)
+    }
+
+    /// Remaining wait until the breaker can admit a request at the current
+    /// wall time (open, or half-open with an exhausted probe budget).
+    pub fn get_time_until_available(&self) -> i64 {
+        self.get_time_until_available_at(self.clock.now_ms())
+    }
+
+    /// [`Self::get_time_until_available`] at an explicit `now`
+    /// (TS `getTimeUntilAvailable(now = Date.now())`).
+    pub fn get_time_until_available_at(&self, now: i64) -> i64 {
+        let state = self.lock();
+        if state.state == CircuitState::Open {
+            return (self.config.reset_timeout_ms - (now - state.last_state_change)).max(0);
+        }
+        if state.state == CircuitState::HalfOpen
+            && state.half_open_attempts >= self.config.half_open_max_attempts
+        {
+            return (self.config.reset_timeout_ms - (now - state.last_state_change)).max(0);
+        }
+        0
+    }
+}
+
+fn prune_failures(state: &mut BreakerState, failure_window_ms: i64, now: i64) {
+    let cutoff = now - failure_window_ms;
+    state.failures.retain(|timestamp| *timestamp >= cutoff);
+}
+
+fn transition_to_open(state: &mut BreakerState, now: i64) {
+    state.state = CircuitState::Open;
+    state.last_state_change = now;
+    state.half_open_attempts = 0;
+}
+
+fn reset_to_closed(state: &mut BreakerState, now: i64) {
+    state.state = CircuitState::Closed;
+    state.last_state_change = now;
+    state.half_open_attempts = 0;
+    state.failures.clear();
+}
+
+// ============================================================================
+// Bounded global registry
+// ============================================================================
+
+const MAX_CIRCUIT_BREAKERS: usize = 100;
+
+/// One registry slot: `(key, breaker)`.
+type RegistryEntry = (String, Arc<CircuitBreaker>);
+
+/// Insertion-ordered registry (TS `Map` semantics: re-adding a deleted key
+/// appends at the tail). Cap 100 with oldest-created eviction, NOT LRU.
+static CIRCUIT_BREAKERS: LazyLock<Mutex<Vec<RegistryEntry>>> =
+    LazyLock::new(|| Mutex::new(Vec::new()));
+
+fn lock_registry() -> MutexGuard<'static, Vec<RegistryEntry>> {
+    CIRCUIT_BREAKERS
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+/// Get-or-create the breaker for `key`. `config` is only used at creation.
+/// On create when the registry holds 100 entries, the FIRST entry (insertion
+/// order — oldest-created) is evicted.
+pub fn get_circuit_breaker(key: &str, config: Option<CircuitBreakerConfig>) -> Arc<CircuitBreaker> {
+    let mut registry = lock_registry();
+    if let Some((_, breaker)) = registry.iter().find(|(entry_key, _)| entry_key == key) {
+        return breaker.clone();
+    }
+    if registry.len() >= MAX_CIRCUIT_BREAKERS {
+        registry.remove(0);
+    }
+    let breaker = Arc::new(match config {
+        Some(config) => CircuitBreaker::with_config(config),
+        None => CircuitBreaker::new(),
+    });
+    registry.push((key.to_string(), breaker.clone()));
+    breaker
+}
+
+/// `resetAllCircuitBreakers()` — `.reset()` every registered breaker
+/// (instances are kept).
+pub fn reset_all_circuit_breakers() {
+    let registry = lock_registry();
+    for (_, breaker) in registry.iter() {
+        breaker.reset();
+    }
+}
+
+/// `clearCircuitBreakers()` — drop every registered breaker.
+pub fn clear_circuit_breakers() {
+    lock_registry().clear();
+}
+
+/// Remove a single circuit breaker by key. Used when an account is removed so
+/// a later re-add of the same identity starts with a fresh (closed) circuit
+/// rather than inheriting an open one (accounts-02).
+pub fn remove_circuit_breaker(key: &str) {
+    lock_registry().retain(|(entry_key, _)| entry_key != key);
+}
+
+// ============================================================================
+// Tests (ported from test/circuit-breaker.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::clock::ManualClock;
+    use serial_test::serial;
+
+    fn breaker_with_clock() -> (CircuitBreaker, Arc<ManualClock>) {
+        let clock = Arc::new(ManualClock::new(0));
+        let breaker =
+            CircuitBreaker::with_config_and_clock(DEFAULT_CIRCUIT_BREAKER_CONFIG, clock.clone());
+        (breaker, clock)
+    }
+
+    fn trip(breaker: &CircuitBreaker) {
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.record_failure();
+    }
+
+    #[test]
+    fn starts_closed_with_default_config() {
+        let breaker = CircuitBreaker::new();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert_eq!(DEFAULT_CIRCUIT_BREAKER_CONFIG.failure_threshold, 3);
+    }
+
+    #[test]
+    fn allows_execution_when_closed() {
+        let breaker = CircuitBreaker::new();
+        assert_eq!(breaker.can_execute(), Ok(true));
+    }
+
+    #[test]
+    fn opens_after_threshold_failures_within_window() {
+        let (breaker, _clock) = breaker_with_clock();
+        trip(&breaker);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+    }
+
+    #[test]
+    fn does_not_open_if_failures_are_outside_window() {
+        let (breaker, clock) = breaker_with_clock();
+        breaker.record_failure();
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.failure_window_ms + 1);
+        breaker.record_failure();
+        breaker.record_failure();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn throws_circuit_open_error_while_open() {
+        let (breaker, _clock) = breaker_with_clock();
+        trip(&breaker);
+        let err = breaker.can_execute().unwrap_err();
+        assert_eq!(err.message(), "Circuit is open");
+        assert_eq!(err.name(), "CircuitOpenError");
+    }
+
+    #[test]
+    fn transitions_to_half_open_after_reset_timeout() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+    }
+
+    #[test]
+    fn allows_a_single_trial_request_in_half_open() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+        let err = breaker.can_execute().unwrap_err();
+        assert_eq!(err.message(), "Circuit is half-open");
+    }
+
+    #[test]
+    fn closes_on_success_from_half_open() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        breaker.can_execute().unwrap();
+        breaker.record_success();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert_eq!(breaker.can_execute(), Ok(true));
+    }
+
+    #[test]
+    fn reopens_on_failure_from_half_open() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        breaker.can_execute().unwrap();
+        breaker.record_failure();
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        assert!(breaker.can_execute().is_err());
+    }
+
+    #[test]
+    fn reset_returns_to_closed_and_clears_failures() {
+        let (breaker, _clock) = breaker_with_clock();
+        breaker.record_failure();
+        breaker.record_failure();
+        breaker.reset();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert_eq!(breaker.can_execute(), Ok(true));
+    }
+
+    #[test]
+    fn prunes_failures_on_success_in_closed_state() {
+        let (breaker, clock) = breaker_with_clock();
+        breaker.record_failure();
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.failure_window_ms + 1);
+        breaker.record_success();
+        breaker.record_failure();
+        breaker.record_failure();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn half_open_max_attempts_can_be_customized() {
+        let clock = Arc::new(ManualClock::new(0));
+        let breaker = CircuitBreaker::with_config_and_clock(
+            CircuitBreakerConfig {
+                half_open_max_attempts: 2,
+                ..CircuitBreakerConfig::default()
+            },
+            clock.clone(),
+        );
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+        assert_eq!(breaker.can_execute(), Ok(true));
+        assert!(breaker.can_execute().is_err());
+    }
+
+    #[test]
+    fn uses_failure_window_threshold_boundary() {
+        let (breaker, clock) = breaker_with_clock();
+        breaker.record_failure();
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.failure_window_ms - 1);
+        breaker.record_failure();
+        breaker.record_failure();
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+    }
+
+    #[test]
+    fn get_failure_count_returns_pruned_failure_count() {
+        let (breaker, clock) = breaker_with_clock();
+        breaker.record_failure();
+        breaker.record_failure();
+        assert_eq!(breaker.get_failure_count(), 2);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.failure_window_ms + 1);
+        assert_eq!(breaker.get_failure_count(), 0);
+    }
+
+    #[test]
+    fn get_time_until_reset_zero_when_not_open() {
+        let (breaker, _clock) = breaker_with_clock();
+        assert_eq!(breaker.get_time_until_reset(), 0);
+        breaker.record_failure();
+        assert_eq!(breaker.get_time_until_reset(), 0);
+    }
+
+    #[test]
+    fn get_time_until_reset_returns_remaining_time_when_open() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        clock.set(10_000);
+        assert_eq!(
+            breaker.get_time_until_reset(),
+            DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms - 10_000
+        );
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1000);
+        assert_eq!(breaker.get_time_until_reset(), 0);
+    }
+
+    #[test]
+    fn get_time_until_available_while_half_open_probe_slot_exhausted() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1001);
+
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+        assert_eq!(
+            breaker.get_time_until_available(),
+            DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms - 1000
+        );
+    }
+
+    #[test]
+    fn get_time_until_available_stays_zero_with_probe_capacity() {
+        let clock = Arc::new(ManualClock::new(0));
+        let breaker = CircuitBreaker::with_config_and_clock(
+            CircuitBreakerConfig {
+                half_open_max_attempts: 2,
+                ..CircuitBreakerConfig::default()
+            },
+            clock.clone(),
+        );
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+        assert_eq!(breaker.get_time_until_available(), 0);
+    }
+
+    #[test]
+    fn is_available_false_while_open_true_after_reset_timeout() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        assert!(!breaker.is_available());
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert!(breaker.is_available());
+    }
+
+    #[test]
+    fn is_available_becomes_false_when_half_open_attempts_exhausted() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert!(breaker.is_available());
+        breaker.can_execute().unwrap();
+        assert!(!breaker.is_available());
+    }
+
+    #[test]
+    fn is_available_does_not_mutate_state() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        // The pure predicate must NOT perform the open→half-open transition.
+        assert!(breaker.is_available());
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+    }
+
+    #[test]
+    fn allows_a_new_half_open_probe_after_the_exhausted_wait_window() {
+        let (breaker, clock) = breaker_with_clock();
+        trip(&breaker);
+        clock.set(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms + 1);
+        assert_eq!(breaker.can_execute(), Ok(true));
+
+        clock.advance(DEFAULT_CIRCUIT_BREAKER_CONFIG.reset_timeout_ms);
+
+        assert!(breaker.is_available());
+        assert_eq!(breaker.get_time_until_available(), 0);
+        assert_eq!(breaker.can_execute(), Ok(true));
+    }
+
+    // ---------------- registry ----------------
+
+    #[test]
+    #[serial(circuit_registry)]
+    fn registry_returns_singleton_per_key() {
+        clear_circuit_breakers();
+        let first = get_circuit_breaker("alpha", None);
+        let second = get_circuit_breaker("alpha", None);
+        assert!(Arc::ptr_eq(&first, &second));
+
+        let other = get_circuit_breaker("beta", None);
+        assert!(!Arc::ptr_eq(&first, &other));
+    }
+
+    #[test]
+    #[serial(circuit_registry)]
+    fn registry_evicts_oldest_entry_when_max_exceeded() {
+        clear_circuit_breakers();
+        for i in 0..100 {
+            get_circuit_breaker(&format!("key-{i}"), None);
+        }
+        let first_breaker = get_circuit_breaker("key-0", None);
+        get_circuit_breaker("new-key-101", None);
+        let refetched_first = get_circuit_breaker("key-0", None);
+        assert!(!Arc::ptr_eq(&refetched_first, &first_breaker));
+    }
+
+    #[test]
+    #[serial(circuit_registry)]
+    fn registry_reset_all_resets_breakers_to_closed() {
+        clear_circuit_breakers();
+        let breaker1 = get_circuit_breaker("reset-test-1", None);
+        let breaker2 = get_circuit_breaker("reset-test-2", None);
+        trip(&breaker1);
+        trip(&breaker2);
+        assert_eq!(breaker1.get_state(), CircuitState::Open);
+        assert_eq!(breaker2.get_state(), CircuitState::Open);
+        reset_all_circuit_breakers();
+        assert_eq!(breaker1.get_state(), CircuitState::Closed);
+        assert_eq!(breaker2.get_state(), CircuitState::Closed);
+    }
+
+    #[test]
+    #[serial(circuit_registry)]
+    fn registry_clear_removes_all_breakers() {
+        clear_circuit_breakers();
+        let breaker = get_circuit_breaker("clear-test", None);
+        breaker.record_failure();
+        clear_circuit_breakers();
+        let new_breaker = get_circuit_breaker("clear-test", None);
+        assert_eq!(new_breaker.get_failure_count(), 0);
+        clear_circuit_breakers();
+    }
+
+    #[test]
+    #[serial(circuit_registry)]
+    fn registry_remove_gives_a_fresh_closed_circuit_on_re_add() {
+        clear_circuit_breakers();
+        let breaker = get_circuit_breaker("remove-test", None);
+        trip(&breaker);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        remove_circuit_breaker("remove-test");
+        let fresh = get_circuit_breaker("remove-test", None);
+        assert!(!Arc::ptr_eq(&fresh, &breaker));
+        assert_eq!(fresh.get_state(), CircuitState::Closed);
+        clear_circuit_breakers();
+    }
+}
diff --git a/crates/rotation/src/lib.rs b/crates/rotation/src/lib.rs
new file mode 100644
index 000000000..53557160f
--- /dev/null
+++ b/crates/rotation/src/lib.rs
@@ -0,0 +1,5 @@
+//! cma-rotation - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod circuit_breaker;
+pub mod routing_mutex;
+pub mod selector;
+pub mod trackers;
diff --git a/crates/rotation/src/routing_mutex.rs b/crates/rotation/src/routing_mutex.rs
new file mode 100644
index 000000000..48aacaded
--- /dev/null
+++ b/crates/rotation/src/routing_mutex.rs
@@ -0,0 +1,328 @@
+//! Port of `lib/routing-mutex.ts` (PR-N / R4) — in-memory, in-process async
+//! mutex serializing cursor-mutation sites in the rotation pipeline.
+//!
+//! Concurrency background: the legacy rotation path reads `activeIndex` /
+//! `activeIndexByFamily`, picks a candidate, and writes the cursor back
+//! without any lock; two simultaneous requests can observe the same cursor,
+//! both rotate to the same candidate, and race on `markSwitched` /
+//! `markAccountCoolingDown` ("lost update"). Gated behind
+//! `PluginConfig.routingMutex = "legacy" | "enabled"` (default `"legacy"`).
+//!
+//! Rust mapping (ARCHITECTURE §5.4):
+//! - TS promise-chain FIFO mutex → [`tokio::sync::Mutex`] (fair FIFO queue).
+//!   A task's own error propagates through its returned value; a failed
+//!   critical section can never poison waiters (the guard drops either way).
+//! - TS `AsyncLocalStorage<true>` reentrancy guard → `tokio::task_local!`
+//!   flag scoped around the critical-section future. The underlying mutex is
+//!   strictly non-reentrant: a section that re-entered `with_routing_mutex`
+//!   without the flag would enqueue behind itself and deadlock, hence nested
+//!   calls run inline (spec 04 gotcha 6 — the proxy's enabled-mode
+//!   select+commit depends on this).
+//! - The task-local flag does NOT cross `tokio::spawn`: a spawned task inside
+//!   a held section starts un-held and would re-acquire. Any spawn inside a
+//!   scoped region must re-wrap explicitly.
+//!
+//! Non-goal (verbatim from TS): no cross-process coordination — the pool
+//! manager is a process singleton.
+
+use std::future::Future;
+use std::sync::LazyLock;
+
+use tokio::sync::Mutex;
+
+pub use cma_core::schemas::account_storage::SwitchReason;
+
+/// `RoutingMutexMode = "enabled" | "legacy"`. Config-side default is
+/// `"legacy"` (env `CODEX_AUTH_ROUTING_MUTEX`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub enum RoutingMutexMode {
+    /// Serialize every cursor-mutation critical section through the mutex.
+    Enabled,
+    /// Run inline with no lock and no allocation (zero behaviour change).
+    #[default]
+    Legacy,
+}
+
+impl RoutingMutexMode {
+    /// The config-file string form.
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            RoutingMutexMode::Enabled => "enabled",
+            RoutingMutexMode::Legacy => "legacy",
+        }
+    }
+
+    /// Parse the config-file string form; unknown values yield `None`.
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "enabled" => Some(RoutingMutexMode::Enabled),
+            "legacy" => Some(RoutingMutexMode::Legacy),
+            _ => None,
+        }
+    }
+}
+
+impl std::fmt::Display for RoutingMutexMode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Single selection decision emitted by the rotation pipeline.
+///
+/// Threaded through the fetch loop so downstream consumers (observability,
+/// why-selected trace, failure-policy telemetry) can inspect *why* a
+/// particular account was picked for a given request without recomputing
+/// scores. All fields are optional except the core identity + reason +
+/// timestamp so the record can be produced from both the legacy fast-path
+/// and the full scoring path.
+#[derive(Debug, Clone, PartialEq)]
+pub struct SelectionRecord {
+    /// Index of the selected account inside the managed pool.
+    pub account_index: usize,
+    /// Stable account identifier (accountId, email, or runtime key).
+    pub account_id: String,
+    /// Coarse-grained classification of why this account was selected
+    /// (`"initial" | "rotation" | "rate-limit" | "best" | "restore" | "manual"`).
+    pub reason: SwitchReason,
+    /// Wall-clock timestamp (ms since epoch) when the decision was made.
+    pub timestamp: i64,
+    /// Quota tracker key (e.g. `"codex"` or `"codex:gpt-5-codex"`) when scoped.
+    pub tracker_key_quota: Option<String>,
+    /// Health score (0-100) used when ranking candidates.
+    pub health: Option<f64>,
+    /// Token bucket remaining count used when ranking candidates.
+    pub tokens: Option<f64>,
+    /// Final hybrid score used during selection.
+    pub score: Option<f64>,
+}
+
+/// Lazy singleton mutex for rotation critical sections (TS
+/// `getRoutingMutex()`); state fully resets whenever unlocked, so no
+/// test-reset hook is needed.
+static ROUTING_MUTEX: LazyLock<Mutex<()>> = LazyLock::new(|| Mutex::new(()));
+
+tokio::task_local! {
+    /// Reentrancy guard: `true` while executing inside a held
+    /// `with_routing_mutex(Enabled, …)` section in the same async context
+    /// (mirrors `routingMutexHeldContext` / `isStorageLockHeld`).
+    static ROUTING_MUTEX_HELD: bool;
+}
+
+/// Reports whether the caller is already running inside a
+/// [`with_routing_mutex`] critical section (in `Enabled` mode). Callers that
+/// may run both standalone and nested under a held mutex use this to avoid
+/// re-acquiring and deadlocking.
+pub fn is_routing_mutex_held() -> bool {
+    ROUTING_MUTEX_HELD.try_with(|held| *held).unwrap_or(false)
+}
+
+/// Run `f` under the routing mutex when `mode == Enabled`, otherwise run it
+/// inline. Hot-path helper used by account-pool mutation sites so the flag
+/// check stays O(1) per call.
+///
+/// Reentrant: if the caller is already inside a held section
+/// ([`is_routing_mutex_held`] is `true`), `f` runs inline rather than
+/// re-acquiring the non-reentrant FIFO queue, which would otherwise deadlock.
+/// When the lock is acquired, `f`'s future runs inside the held-context scope
+/// so any nested `with_routing_mutex` calls it makes are detected as
+/// reentrant. Errors propagate through `T` (e.g. a `Result`); the mutex is
+/// released either way.
+pub async fn with_routing_mutex<F, Fut, T>(mode: RoutingMutexMode, f: F) -> T
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = T>,
+{
+    match mode {
+        RoutingMutexMode::Enabled => {
+            if is_routing_mutex_held() {
+                // Already inside the critical section for this async context:
+                // run inline so we don't enqueue behind ourselves and deadlock.
+                return f().await;
+            }
+            let _guard = ROUTING_MUTEX.lock().await;
+            ROUTING_MUTEX_HELD.scope(true, f()).await
+        }
+        RoutingMutexMode::Legacy => f().await,
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/routing-mutex.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Arc, Mutex as StdMutex};
+    use std::time::Duration;
+
+    fn push(events: &Arc<StdMutex<Vec<String>>>, event: &str) {
+        events
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .push(event.to_string());
+    }
+
+    #[tokio::test]
+    async fn enabled_mode_serializes_concurrent_tasks_fifo() {
+        let events: Arc<StdMutex<Vec<String>>> = Arc::new(StdMutex::new(Vec::new()));
+
+        let make_task = |name: &'static str, delay_ms: u64| {
+            let events = events.clone();
+            with_routing_mutex(RoutingMutexMode::Enabled, move || async move {
+                push(&events, &format!("{name}:start"));
+                tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+                push(&events, &format!("{name}:end"));
+                name
+            })
+        };
+
+        // join! polls in order on the current-thread runtime, so the fair
+        // FIFO mutex admits A, then B, then C — mirroring the TS chain.
+        let (a, b, c) = tokio::join!(make_task("A", 10), make_task("B", 5), make_task("C", 1));
+
+        let recorded = events
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone();
+        assert_eq!(
+            recorded,
+            vec!["A:start", "A:end", "B:start", "B:end", "C:start", "C:end"]
+        );
+        assert_eq!((a, b, c), ("A", "B", "C"));
+    }
+
+    #[tokio::test]
+    async fn propagates_errors_but_keeps_the_mutex_alive() {
+        let failing: Result<(), String> =
+            with_routing_mutex(RoutingMutexMode::Enabled, || async {
+                Err("boom".to_string())
+            })
+            .await;
+        assert_eq!(failing, Err("boom".to_string()));
+
+        // A failed section must not poison later waiters.
+        let recovered = with_routing_mutex(RoutingMutexMode::Enabled, || async { "ok" }).await;
+        assert_eq!(recovered, "ok");
+        assert!(!is_routing_mutex_held());
+    }
+
+    #[tokio::test]
+    async fn legacy_mode_runs_inline_without_entering_the_mutex() {
+        let (result, held_inside) = with_routing_mutex(RoutingMutexMode::Legacy, || async {
+            ("legacy-result", is_routing_mutex_held())
+        })
+        .await;
+        assert_eq!(result, "legacy-result");
+        // Inline execution must not flip the held flag.
+        assert!(!held_inside);
+    }
+
+    #[tokio::test]
+    async fn enabled_mode_routes_through_the_shared_mutex() {
+        let held_inside = with_routing_mutex(RoutingMutexMode::Enabled, || async {
+            is_routing_mutex_held()
+        })
+        .await;
+        assert!(held_inside);
+        assert!(!is_routing_mutex_held());
+    }
+
+    #[tokio::test]
+    async fn enabled_mode_is_reentrant_within_a_held_section() {
+        // A nested acquisition inside the held section must run inline
+        // (re-enqueueing behind ourselves would deadlock — 5 s timeout guard).
+        let result = tokio::time::timeout(
+            Duration::from_secs(5),
+            with_routing_mutex(RoutingMutexMode::Enabled, || async {
+                assert!(is_routing_mutex_held());
+                let inner = with_routing_mutex(RoutingMutexMode::Enabled, || async {
+                    is_routing_mutex_held()
+                })
+                .await;
+                assert!(inner);
+                42
+            }),
+        )
+        .await
+        .expect("nested with_routing_mutex deadlocked");
+        assert_eq!(result, 42);
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn enabled_mode_serializes_spawned_callers_without_interleaving() {
+        let events: Arc<StdMutex<Vec<String>>> = Arc::new(StdMutex::new(Vec::new()));
+        let mut handles = Vec::new();
+        for name in ["a", "b", "c", "d"] {
+            let events = events.clone();
+            handles.push(tokio::spawn(async move {
+                with_routing_mutex(RoutingMutexMode::Enabled, move || async move {
+                    push(&events, &format!("{name}:in"));
+                    tokio::time::sleep(Duration::from_millis(1)).await;
+                    push(&events, &format!("{name}:out"));
+                })
+                .await;
+            }));
+        }
+        for handle in handles {
+            handle.await.expect("task panicked");
+        }
+
+        // No interleaving: every in/out pair must be contiguous.
+        let order = events
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone();
+        assert_eq!(order.len(), 8);
+        for pair in order.chunks(2) {
+            let label = pair[0].split(':').next().unwrap();
+            assert_eq!(pair[0], format!("{label}:in"));
+            assert_eq!(pair[1], format!("{label}:out"));
+        }
+    }
+
+    #[test]
+    fn selection_record_accepts_minimum_and_full_payloads() {
+        let minimal = SelectionRecord {
+            account_index: 2,
+            account_id: "acct_123".to_string(),
+            reason: SwitchReason::Rotation,
+            timestamp: cma_core::utils::now_ms(),
+            tracker_key_quota: None,
+            health: None,
+            tokens: None,
+            score: None,
+        };
+        assert_eq!(minimal.account_index, 2);
+        assert_eq!(minimal.reason.as_str(), "rotation");
+
+        let full = SelectionRecord {
+            account_index: 0,
+            account_id: "acct_0".to_string(),
+            reason: SwitchReason::Best,
+            timestamp: 1_700_000_000_000,
+            tracker_key_quota: Some("codex:gpt-5-codex".to_string()),
+            health: Some(93.0),
+            tokens: Some(48.0),
+            score: Some(512.0),
+        };
+        assert_eq!(full.tracker_key_quota.as_deref(), Some("codex:gpt-5-codex"));
+        assert_eq!(full.score, Some(512.0));
+    }
+
+    #[test]
+    fn routing_mutex_mode_parses_and_defaults_to_legacy() {
+        assert_eq!(RoutingMutexMode::default(), RoutingMutexMode::Legacy);
+        assert_eq!(
+            RoutingMutexMode::parse("enabled"),
+            Some(RoutingMutexMode::Enabled)
+        );
+        assert_eq!(
+            RoutingMutexMode::parse("legacy"),
+            Some(RoutingMutexMode::Legacy)
+        );
+        assert_eq!(RoutingMutexMode::parse("bogus"), None);
+        assert_eq!(RoutingMutexMode::Enabled.as_str(), "enabled");
+    }
+}
diff --git a/crates/rotation/src/selector.rs b/crates/rotation/src/selector.rs
new file mode 100644
index 000000000..e8b15f570
--- /dev/null
+++ b/crates/rotation/src/selector.rs
@@ -0,0 +1,971 @@
+//! Port of `lib/rotation.ts` selection half — hybrid account selection plus
+//! the jitter/backoff utilities.
+//!
+//! Contracts carried over verbatim (spec 04 §1):
+//! - `select_hybrid_account` returns **`None` when zero accounts are
+//!   available** — never an LRU fallback to a blocked candidate
+//!   (AUDIT-H2 / D-01; spec 04 gotcha 2). The traced variant mirrors this.
+//! - Hybrid weights: health 2 / tokens 5 / freshness 2.0; PID bonus
+//!   `(pid % 100) * 0.01`; per-account pseudo-random term
+//!   `((index * 0.131 + pidBonus) % 1) * freshnessWeight * 0.1`.
+//! - Ties resolve to the first candidate in iteration order (strict `>`).
+//! - `exponential_backoff` validates BEFORE any jitter is drawn, with the
+//!   exact frozen `TypeError` texts (surfaced as [`ArgError`], ARCHITECTURE
+//!   §8.2).
+//!
+//! The TS `TypeError`s for "accounts is not an array" / "missing trackers"
+//! are unrepresentable in Rust's type system and have no port.
+//!
+//! Nothing here is ever persisted (no `Serialize` anywhere in this crate).
+
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use cma_core::logger::{ScopedLogger, create_logger};
+use cma_core::utils::now_ms;
+use serde_json::json;
+
+use crate::trackers::{HealthScoreTracker, TokenBucketTracker, TrackerKey};
+
+static LOG: LazyLock<ScopedLogger> = LazyLock::new(|| create_logger("rotation"));
+
+// ============================================================================
+// Argument validation error (plain, NOT CodexError — ARCHITECTURE §8.2)
+// ============================================================================
+
+/// Plain argument-contract error for dual-call helpers; carries the exact
+/// frozen `"<helper> requires …"` message from the TS `TypeError`s.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ArgError {
+    message: String,
+}
+
+impl ArgError {
+    /// Create an [`ArgError`] with the given frozen message.
+    pub fn new(message: impl Into<String>) -> Self {
+        ArgError {
+            message: message.into(),
+        }
+    }
+
+    /// The frozen error message.
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl std::fmt::Display for ArgError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ArgError {}
+
+// ============================================================================
+// Hybrid account selection
+// ============================================================================
+
+/// `AccountWithMetrics` — selection candidate handed to the hybrid selector.
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountWithMetrics {
+    /// Index of the account inside the managed pool.
+    pub index: usize,
+    /// Stable tracker key override; falls back to `index` when absent.
+    pub tracker_key: Option<TrackerKey>,
+    /// Whether the account is currently selectable.
+    pub is_available: bool,
+    /// Wall-clock ms timestamp of last use (0 = never).
+    pub last_used: i64,
+}
+
+/// `HybridSelectionConfig` — scoring weights.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct HybridSelectionConfig {
+    /// Weight for health score (default: 2).
+    pub health_weight: f64,
+    /// Weight for token count (default: 5).
+    pub token_weight: f64,
+    /// Weight for freshness/last used (default: 2.0).
+    pub freshness_weight: f64,
+}
+
+const DEFAULT_HYBRID_SELECTION_CONFIG: HybridSelectionConfig = HybridSelectionConfig {
+    health_weight: 2.0,
+    token_weight: 5.0,
+    freshness_weight: 2.0,
+};
+
+impl Default for HybridSelectionConfig {
+    fn default() -> Self {
+        DEFAULT_HYBRID_SELECTION_CONFIG
+    }
+}
+
+/// `HybridSelectionOptions`.
+#[derive(Debug, Clone, Default)]
+pub struct HybridSelectionOptions {
+    /// Adds a small deterministic per-process offset so parallel processes
+    /// spread across accounts.
+    pub pid_offset_enabled: bool,
+    /// Optional per-account additive score boost keyed by pool index.
+    /// Non-finite values are ignored (treated as 0).
+    pub score_boost_by_account: HashMap<usize, f64>,
+}
+
+/// `SelectHybridAccountParams` — named-argument bundle (the TS overloads'
+/// positional form collapses into this one struct in Rust).
+#[derive(Clone)]
+pub struct SelectHybridAccountParams<'a> {
+    /// Candidate accounts.
+    pub accounts: &'a [AccountWithMetrics],
+    /// Health tracker consulted per candidate (scoped by `quota_key`).
+    pub health_tracker: &'a HealthScoreTracker,
+    /// Token tracker consulted per candidate (scoped by `quota_key`).
+    pub token_tracker: &'a TokenBucketTracker,
+    /// Optional quota key scoping health/token lookups.
+    pub quota_key: Option<&'a str>,
+    /// Scoring weights (defaults: health 2 / tokens 5 / freshness 2.0).
+    pub config: HybridSelectionConfig,
+    /// Selection options (PID offset, capability boosts).
+    pub options: HybridSelectionOptions,
+}
+
+impl<'a> SelectHybridAccountParams<'a> {
+    /// Params with default quota key, config, and options.
+    pub fn new(
+        accounts: &'a [AccountWithMetrics],
+        health_tracker: &'a HealthScoreTracker,
+        token_tracker: &'a TokenBucketTracker,
+    ) -> Self {
+        SelectHybridAccountParams {
+            accounts,
+            health_tracker,
+            token_tracker,
+            quota_key: None,
+            config: HybridSelectionConfig::default(),
+            options: HybridSelectionOptions::default(),
+        }
+    }
+}
+
+/// `SelectHybridAccountTracedParams` — same shape as the plain params.
+pub type SelectHybridAccountTracedParams<'a> = SelectHybridAccountParams<'a>;
+
+fn resolve_tracker_key(account: &AccountWithMetrics) -> TrackerKey {
+    account
+        .tracker_key
+        .clone()
+        .unwrap_or(TrackerKey::Number(account.index as i64))
+}
+
+fn capability_boost_for(options: &HybridSelectionOptions, index: usize) -> f64 {
+    match options.score_boost_by_account.get(&index) {
+        Some(boost) if boost.is_finite() => *boost,
+        _ => 0.0,
+    }
+}
+
+/// Raw score breakdown for one candidate (internal).
+struct ScoreBreakdown {
+    score: f64,
+    health: f64,
+    tokens: f64,
+    hours_since_used: f64,
+    capability_boost: f64,
+}
+
+fn score_account(
+    account: &AccountWithMetrics,
+    params: &SelectHybridAccountParams<'_>,
+    cfg: &HybridSelectionConfig,
+    now: i64,
+    pid_bonus: f64,
+) -> ScoreBreakdown {
+    let tracker_key = resolve_tracker_key(account);
+    let health = params
+        .health_tracker
+        .get_score(tracker_key.clone(), params.quota_key);
+    let tokens = params
+        .token_tracker
+        .get_tokens(tracker_key, params.quota_key);
+    let hours_since_used = (now - account.last_used) as f64 / (1000.0 * 60.0 * 60.0);
+    let capability_boost = capability_boost_for(&params.options, account.index);
+
+    let mut score = health * cfg.health_weight
+        + tokens * cfg.token_weight
+        + hours_since_used * cfg.freshness_weight
+        + capability_boost;
+
+    // PID-based offset distributes selection across parallel agents.
+    if params.options.pid_offset_enabled {
+        score += ((account.index as f64 * 0.131 + pid_bonus) % 1.0) * cfg.freshness_weight * 0.1;
+    }
+
+    ScoreBreakdown {
+        score,
+        health,
+        tokens,
+        hours_since_used,
+        capability_boost,
+    }
+}
+
+/// Selects the best account using a weighted hybrid score:
+///
+/// `score = health*healthWeight + tokens*tokenWeight + hoursSinceUsed*freshnessWeight (+ boost + PID term)`
+///
+/// Returns `None` when NO account is available (all cooling down,
+/// rate-limited, circuit-open, or otherwise blocked) — the caller is
+/// responsible for surfacing the pool-exhaustion condition instead of
+/// retrying through a blocked candidate (AUDIT-H2 / D-01).
+pub fn select_hybrid_account(params: SelectHybridAccountParams<'_>) -> Option<AccountWithMetrics> {
+    select_hybrid_account_with_pid(params, std::process::id())
+}
+
+/// PID-injectable core of [`select_hybrid_account`] (test seam mirroring the
+/// TS suite's `process.pid` redefinition).
+fn select_hybrid_account_with_pid(
+    params: SelectHybridAccountParams<'_>,
+    pid: u32,
+) -> Option<AccountWithMetrics> {
+    let cfg = params.config;
+    let available: Vec<&AccountWithMetrics> =
+        params.accounts.iter().filter(|a| a.is_available).collect();
+
+    // Contract: if NO account is currently available the selector returns
+    // None rather than handing back a known-unavailable candidate via an LRU
+    // fallback (AUDIT-H2 / D-01).
+    if available.is_empty() {
+        return None;
+    }
+    if available.len() == 1 {
+        return available.first().map(|account| (*account).clone());
+    }
+
+    let now = now_ms();
+    let mut best_account: Option<&AccountWithMetrics> = None;
+    let mut best_score = f64::NEG_INFINITY;
+
+    // PID offset: each process gets a small deterministic bonus based on pid.
+    let pid_bonus = if params.options.pid_offset_enabled {
+        f64::from(pid % 100) * 0.01
+    } else {
+        0.0
+    };
+
+    for account in available.iter().copied() {
+        let breakdown = score_account(account, &params, &cfg, now, pid_bonus);
+        if breakdown.score > best_score {
+            best_score = breakdown.score;
+            best_account = Some(account);
+        }
+    }
+
+    if let Some(best) = best_account
+        && available.len() > 1
+    {
+        let tracker_key = resolve_tracker_key(best);
+        let health = params
+            .health_tracker
+            .get_score(tracker_key.clone(), params.quota_key);
+        let tokens = params
+            .token_tracker
+            .get_tokens(tracker_key, params.quota_key);
+        LOG.debug(
+            "Selected account",
+            Some(&json!({
+                "index": best.index,
+                "health": health.round() as i64,
+                "tokens": tokens.round() as i64,
+                "score": best_score.round() as i64,
+                "candidateCount": available.len(),
+            })),
+        );
+    }
+
+    best_account.cloned()
+}
+
+// ============================================================================
+// Trace-mode selection (non-mutating, diagnostic)
+// ============================================================================
+
+/// Per-candidate score breakdown emitted by [`select_hybrid_account_traced`].
+/// Raw (unrounded) numbers so callers can display exact values.
+#[derive(Debug, Clone, PartialEq)]
+pub struct HybridSelectionCandidateTrace {
+    /// Pool index.
+    pub index: usize,
+    /// Resolved tracker key (override or index).
+    pub tracker_key: TrackerKey,
+    /// Availability at trace time.
+    pub is_available: bool,
+    /// Last-used wall-clock ms.
+    pub last_used: i64,
+    /// Health score used in the formula.
+    pub health: f64,
+    /// Token count used in the formula.
+    pub tokens: f64,
+    /// Hours since last use.
+    pub hours_since_used: f64,
+    /// Applied capability boost (0 when absent/non-finite).
+    pub capability_boost: f64,
+    /// Applied PID bonus (0 when the offset is disabled).
+    pub pid_bonus: f64,
+    /// Final hybrid score.
+    pub score: f64,
+    /// Set only for unavailable candidates.
+    pub reason: Option<&'static str>,
+}
+
+/// Result of [`select_hybrid_account_traced`].
+#[derive(Debug, Clone, PartialEq)]
+pub struct HybridSelectionTraceResult {
+    /// The winning account (mirrors production selection), if any.
+    pub selected: Option<AccountWithMetrics>,
+    /// Winning pool index, if any.
+    pub selected_index: Option<usize>,
+    /// Human-readable selection reason (exact TS strings).
+    pub selection_reason: String,
+    /// All candidates, sorted descending by score.
+    pub candidates: Vec<HybridSelectionCandidateTrace>,
+    /// The resolved scoring weights.
+    pub config: HybridSelectionConfig,
+    /// The quota key the lookups were scoped to.
+    pub quota_key: Option<String>,
+    /// Number of available accounts.
+    pub available_count: usize,
+}
+
+const UNAVAILABLE_REASON: &str = "unavailable (rate-limited, cooling down, or circuit open)";
+
+/// Non-mutating variant of [`select_hybrid_account`] returning the winner
+/// alongside a per-candidate score breakdown (used by `why-selected --now`).
+/// Scores ALL accounts (unavailable ones get a `reason`); candidates are
+/// sorted descending by score. Mirrors the production null-contract exactly.
+pub fn select_hybrid_account_traced(
+    params: SelectHybridAccountTracedParams<'_>,
+) -> HybridSelectionTraceResult {
+    select_hybrid_account_traced_with_pid(params, std::process::id())
+}
+
+/// PID-injectable core of [`select_hybrid_account_traced`] (test seam).
+fn select_hybrid_account_traced_with_pid(
+    params: SelectHybridAccountTracedParams<'_>,
+    pid: u32,
+) -> HybridSelectionTraceResult {
+    let cfg = params.config;
+    let now = now_ms();
+    let pid_bonus = if params.options.pid_offset_enabled {
+        f64::from(pid % 100) * 0.01
+    } else {
+        0.0
+    };
+
+    let accounts = params.accounts;
+    let available_accounts: Vec<&AccountWithMetrics> =
+        accounts.iter().filter(|a| a.is_available).collect();
+
+    let mut candidates: Vec<HybridSelectionCandidateTrace> = accounts
+        .iter()
+        .map(|account| {
+            let breakdown = score_account(account, &params, &cfg, now, pid_bonus);
+            HybridSelectionCandidateTrace {
+                index: account.index,
+                tracker_key: resolve_tracker_key(account),
+                is_available: account.is_available,
+                last_used: account.last_used,
+                health: breakdown.health,
+                tokens: breakdown.tokens,
+                hours_since_used: breakdown.hours_since_used,
+                capability_boost: breakdown.capability_boost,
+                pid_bonus: if params.options.pid_offset_enabled {
+                    pid_bonus
+                } else {
+                    0.0
+                },
+                score: breakdown.score,
+                reason: if account.is_available {
+                    None
+                } else {
+                    Some(UNAVAILABLE_REASON)
+                },
+            }
+        })
+        .collect();
+
+    // Stable descending sort — ties keep original order, matching JS.
+    candidates.sort_by(|a, b| {
+        b.score
+            .partial_cmp(&a.score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+
+    let mut selected: Option<AccountWithMetrics> = None;
+    let mut selection_reason = String::from("no accounts provided");
+
+    if accounts.is_empty() {
+        selection_reason = String::from("no accounts configured");
+    } else if available_accounts.is_empty() {
+        // AUDIT-H2 / D-01 contract: when no account is available, selection
+        // returns None rather than a blocked LRU candidate; the trace mirrors
+        // production so why-selected diagnostics match actual behaviour.
+        selected = None;
+        selection_reason =
+            String::from("all accounts unavailable (rate-limited, cooling down, or circuit open)");
+    } else if available_accounts.len() == 1 {
+        selected = available_accounts.first().map(|a| (*a).clone());
+        selection_reason = String::from("single available account");
+    } else if let Some(best_candidate) = candidates.iter().find(|candidate| candidate.is_available)
+    {
+        selected = accounts
+            .iter()
+            .find(|account| account.index == best_candidate.index)
+            .cloned();
+        selection_reason = format!(
+            "highest hybrid score ({:.2}) across {} available account(s)",
+            best_candidate.score,
+            available_accounts.len()
+        );
+    }
+
+    let selected_index = selected.as_ref().map(|account| account.index);
+    HybridSelectionTraceResult {
+        selected,
+        selected_index,
+        selection_reason,
+        candidates,
+        config: cfg,
+        quota_key: params.quota_key.map(str::to_string),
+        available_count: available_accounts.len(),
+    }
+}
+
+// ============================================================================
+// Utility functions
+// ============================================================================
+
+/// Adds symmetric random jitter to a delay value:
+/// `max(0, floor(baseMs + baseMs*jitterFactor*(rand()*2 - 1)))`.
+/// TS default `jitter_factor` is `0.1` (±10 %).
+pub fn add_jitter(base_ms: f64, jitter_factor: f64) -> i64 {
+    let jitter = base_ms * jitter_factor * (rand::random::<f64>() * 2.0 - 1.0);
+    (base_ms + jitter).floor().max(0.0) as i64
+}
+
+/// Returns a random delay within `[min_ms, max_ms)`:
+/// `floor(minMs + rand()*(maxMs - minMs))`.
+pub fn random_delay(min_ms: f64, max_ms: f64) -> i64 {
+    (min_ms + rand::random::<f64>() * (max_ms - min_ms)).floor() as i64
+}
+
+/// `ExponentialBackoffOptions` — named-argument bundle. `attempt` is `f64`
+/// so the "positive integer" contract (incl. NaN/∞ rejection) ports exactly.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ExponentialBackoffOptions {
+    /// Attempt number (1-based; must be a positive integer).
+    pub attempt: f64,
+    /// Base delay in ms (default 1000).
+    pub base_ms: Option<f64>,
+    /// Maximum delay in ms (default 60000).
+    pub max_ms: Option<f64>,
+    /// Jitter factor in `[0, 1]` (default 0.1).
+    pub jitter_factor: Option<f64>,
+}
+
+impl ExponentialBackoffOptions {
+    /// Options with TS defaults for everything but `attempt`.
+    pub fn new(attempt: f64) -> Self {
+        ExponentialBackoffOptions {
+            attempt,
+            base_ms: None,
+            max_ms: None,
+            jitter_factor: None,
+        }
+    }
+}
+
+/// Calculates exponential backoff with jitter:
+/// `addJitter(min(baseMs * 2^(attempt-1), maxMs), jitterFactor)`.
+///
+/// Validates all arguments BEFORE any jitter is drawn; invalid arguments
+/// yield an [`ArgError`] with the exact frozen TS `TypeError` message.
+pub fn exponential_backoff(options: ExponentialBackoffOptions) -> Result<i64, ArgError> {
+    let attempt = options.attempt;
+    let base_ms = options.base_ms.unwrap_or(1000.0);
+    let max_ms = options.max_ms.unwrap_or(60000.0);
+    let jitter_factor = options.jitter_factor.unwrap_or(0.1);
+
+    if !(attempt.is_finite() && attempt.fract() == 0.0) || attempt < 1.0 {
+        return Err(ArgError::new(
+            "exponentialBackoff requires attempt to be a positive integer",
+        ));
+    }
+    if !base_ms.is_finite() || base_ms < 0.0 {
+        return Err(ArgError::new(
+            "exponentialBackoff requires baseMs to be a finite non-negative number",
+        ));
+    }
+    if !max_ms.is_finite() || max_ms < 0.0 {
+        return Err(ArgError::new(
+            "exponentialBackoff requires maxMs to be a finite non-negative number",
+        ));
+    }
+    if !jitter_factor.is_finite() || !(0.0..=1.0).contains(&jitter_factor) {
+        return Err(ArgError::new(
+            "exponentialBackoff requires jitterFactor to be between 0 and 1",
+        ));
+    }
+
+    let delay = (base_ms * 2f64.powf(attempt - 1.0)).min(max_ms);
+    Ok(add_jitter(delay, jitter_factor))
+}
+
+// ============================================================================
+// Tests (ported from test/rotation.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn account(index: usize, is_available: bool, last_used: i64) -> AccountWithMetrics {
+        AccountWithMetrics {
+            index,
+            tracker_key: None,
+            is_available,
+            last_used,
+        }
+    }
+
+    fn trackers() -> (HealthScoreTracker, TokenBucketTracker) {
+        (HealthScoreTracker::new(), TokenBucketTracker::new())
+    }
+
+    #[test]
+    fn returns_none_when_no_accounts() {
+        let (health, token) = trackers();
+        let result = select_hybrid_account(SelectHybridAccountParams::new(&[], &health, &token));
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn returns_none_when_all_accounts_unavailable_audit_h2_contract() {
+        let (health, token) = trackers();
+        let accounts = vec![account(0, false, 100), account(1, false, 50)];
+        // Previously returned the least-recently-used unavailable account as a
+        // "fallback" (AUDIT-H2 / D-01). New contract: None.
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn returns_none_when_single_account_unavailable() {
+        let (health, token) = trackers();
+        let accounts = vec![account(0, false, 0)];
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn returns_the_only_available_account() {
+        let (health, token) = trackers();
+        let accounts = vec![account(0, true, 0)];
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(result.map(|a| a.index), Some(0));
+    }
+
+    #[test]
+    fn prefers_healthier_accounts() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        health.record_failure(0usize, None);
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(result.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    fn prefers_accounts_with_more_tokens() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        token.drain(0usize, None, 40.0);
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(result.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    fn considers_freshness_in_selection() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![
+            account(0, true, now),
+            account(1, true, now - 1000 * 60 * 60 * 24),
+        ];
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(result.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    fn uses_tracker_key_when_runtime_state_keyed_by_identity() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![
+            AccountWithMetrics {
+                index: 0,
+                tracker_key: Some(TrackerKey::Text("email:first@example.com".into())),
+                is_available: true,
+                last_used: now,
+            },
+            AccountWithMetrics {
+                index: 1,
+                tracker_key: Some(TrackerKey::Text("email:second@example.com".into())),
+                is_available: true,
+                last_used: now,
+            },
+        ];
+        health.record_failure("email:first@example.com", None);
+        let result =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(result.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    fn pid_offset_disabled_does_not_change_selection() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.pid_offset_enabled = false;
+        let with_flag = select_hybrid_account(params);
+        let baseline =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(
+            with_flag.map(|a| a.index),
+            baseline.map(|a| a.index)
+        );
+    }
+
+    #[test]
+    fn pid_offset_enabled_returns_a_valid_account() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.pid_offset_enabled = true;
+        let result = select_hybrid_account(params);
+        assert!(matches!(result.map(|a| a.index), Some(0) | Some(1)));
+    }
+
+    #[test]
+    fn pid_offset_differentiates_selection_across_pids() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![
+            account(0, true, now),
+            account(1, true, now),
+            account(2, true, now),
+            account(3, true, now),
+        ];
+        let mut selected = std::collections::HashSet::new();
+        for pid in (0..100u32).step_by(10) {
+            let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+            params.options.pid_offset_enabled = true;
+            if let Some(result) = select_hybrid_account_with_pid(params, pid) {
+                selected.insert(result.index);
+            }
+        }
+        assert!(selected.len() > 1);
+    }
+
+    #[test]
+    fn applies_score_boost_to_deterministically_change_winner() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+
+        let baseline =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(baseline.map(|a| a.index), Some(0));
+
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.score_boost_by_account = HashMap::from([(1usize, 25.0)]);
+        let boosted = select_hybrid_account(params);
+        assert_eq!(boosted.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    fn ignores_non_finite_score_boosts() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+
+        let baseline =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token))
+                .map(|a| a.index);
+
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.score_boost_by_account = HashMap::from([(1usize, f64::NAN)]);
+        let with_nan = select_hybrid_account(params).map(|a| a.index);
+
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.score_boost_by_account = HashMap::from([(1usize, f64::INFINITY)]);
+        let with_inf = select_hybrid_account(params).map(|a| a.index);
+
+        assert_eq!(with_nan, baseline);
+        assert_eq!(with_inf, baseline);
+    }
+
+    #[test]
+    fn boost_behavior_stable_when_pid_offset_enabled() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        let mut params = SelectHybridAccountParams::new(&accounts, &health, &token);
+        params.options.pid_offset_enabled = true;
+        params.options.score_boost_by_account = HashMap::from([(1usize, 100.0)]);
+        let result = select_hybrid_account(params);
+        assert_eq!(result.map(|a| a.index), Some(1));
+    }
+
+    // ---------------- traced ----------------
+
+    #[test]
+    fn traced_returns_empty_result_for_no_accounts() {
+        let (health, token) = trackers();
+        let result =
+            select_hybrid_account_traced(SelectHybridAccountParams::new(&[], &health, &token));
+        assert!(result.selected.is_none());
+        assert!(result.candidates.is_empty());
+        assert_eq!(result.available_count, 0);
+        assert_eq!(result.selection_reason, "no accounts configured");
+    }
+
+    #[test]
+    fn traced_returns_the_single_available_account() {
+        let (health, token) = trackers();
+        let accounts = vec![account(0, true, now_ms() - 3_600_000)];
+        let result = select_hybrid_account_traced(SelectHybridAccountParams::new(
+            &accounts, &health, &token,
+        ));
+        assert_eq!(result.selected.as_ref().map(|a| a.index), Some(0));
+        assert_eq!(result.selected_index, Some(0));
+        assert_eq!(result.candidates.len(), 1);
+        assert_eq!(result.selection_reason, "single available account");
+    }
+
+    #[test]
+    fn traced_sorts_candidates_descending_and_picks_top() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        token.drain(0usize, None, 40.0);
+        let accounts = vec![account(0, true, now - 60_000), account(1, true, now - 60_000)];
+        let result = select_hybrid_account_traced(SelectHybridAccountParams::new(
+            &accounts, &health, &token,
+        ));
+        assert_eq!(result.selected.as_ref().map(|a| a.index), Some(1));
+        assert_eq!(result.candidates[0].index, 1);
+        assert!(result.candidates[0].score >= result.candidates[1].score);
+        assert!(
+            result
+                .selection_reason
+                .starts_with("highest hybrid score ("),
+            "unexpected reason: {}",
+            result.selection_reason
+        );
+        assert!(
+            result
+                .selection_reason
+                .ends_with("across 2 available account(s)"),
+            "unexpected reason: {}",
+            result.selection_reason
+        );
+    }
+
+    #[test]
+    fn traced_returns_none_when_no_accounts_available_audit_h2_contract() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        let accounts = vec![account(0, false, now - 1_000), account(1, false, now - 10_000)];
+        let result = select_hybrid_account_traced(SelectHybridAccountParams::new(
+            &accounts, &health, &token,
+        ));
+        assert_eq!(result.available_count, 0);
+        assert!(result.selected.is_none());
+        assert_eq!(
+            result.selection_reason,
+            "all accounts unavailable (rate-limited, cooling down, or circuit open)"
+        );
+        for candidate in &result.candidates {
+            assert_eq!(
+                candidate.reason,
+                Some("unavailable (rate-limited, cooling down, or circuit open)")
+            );
+        }
+    }
+
+    #[test]
+    fn traced_does_not_mutate_trackers() {
+        let (health, token) = trackers();
+        let before_health = health.get_score(0usize, None);
+        let before_tokens = token.get_tokens(0usize, None);
+        let now = now_ms();
+        let accounts = vec![account(0, true, now), account(1, true, now)];
+        select_hybrid_account_traced(SelectHybridAccountParams::new(&accounts, &health, &token));
+        assert_eq!(health.get_score(0usize, None), before_health);
+        assert_eq!(token.get_tokens(0usize, None), before_tokens);
+    }
+
+    #[test]
+    fn traced_agrees_with_plain_selector_on_winning_index() {
+        let (health, token) = trackers();
+        let now = now_ms();
+        token.drain(0usize, None, 30.0);
+        let accounts = vec![
+            account(0, true, now - 10_000),
+            account(1, true, now - 10_000),
+            account(2, true, now - 10_000),
+        ];
+        let plain =
+            select_hybrid_account(SelectHybridAccountParams::new(&accounts, &health, &token))
+                .map(|a| a.index);
+        let traced = select_hybrid_account_traced(SelectHybridAccountParams::new(
+            &accounts, &health, &token,
+        ));
+        assert_eq!(traced.selected.map(|a| a.index), plain);
+    }
+
+    // ---------------- utilities ----------------
+
+    #[test]
+    fn add_jitter_stays_within_range() {
+        let base = 1000.0;
+        let factor = 0.2;
+        for _ in 0..100 {
+            let result = add_jitter(base, factor);
+            assert!(result as f64 >= base * (1.0 - factor));
+            assert!(result as f64 <= base * (1.0 + factor));
+        }
+    }
+
+    #[test]
+    fn add_jitter_returns_non_negative_values() {
+        for _ in 0..100 {
+            assert!(add_jitter(10.0, 2.0) >= 0);
+        }
+    }
+
+    #[test]
+    fn random_delay_within_range() {
+        for _ in 0..100 {
+            let result = random_delay(100.0, 500.0);
+            assert!(result >= 100);
+            assert!(result <= 500);
+        }
+    }
+
+    #[test]
+    fn exponential_backoff_increases_delay_exponentially() {
+        let delay1 = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 1.0,
+            base_ms: Some(1000.0),
+            max_ms: Some(60000.0),
+            jitter_factor: Some(0.0),
+        })
+        .unwrap();
+        let delay2 = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 2.0,
+            base_ms: Some(1000.0),
+            max_ms: Some(60000.0),
+            jitter_factor: Some(0.0),
+        })
+        .unwrap();
+        let delay3 = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 3.0,
+            base_ms: Some(1000.0),
+            max_ms: Some(60000.0),
+            jitter_factor: Some(0.0),
+        })
+        .unwrap();
+        assert_eq!(delay2, delay1 * 2);
+        assert_eq!(delay3, delay1 * 4);
+    }
+
+    #[test]
+    fn exponential_backoff_caps_at_max_ms() {
+        let result = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 10.0,
+            base_ms: Some(1000.0),
+            max_ms: Some(5000.0),
+            jitter_factor: Some(0.0),
+        })
+        .unwrap();
+        assert_eq!(result, 5000);
+    }
+
+    #[test]
+    fn exponential_backoff_defaults_match_ts() {
+        // attempt only ⇒ base 1000, max 60000, jitter 0.1 (±10 %).
+        let result = exponential_backoff(ExponentialBackoffOptions::new(1.0)).unwrap();
+        assert!((900..=1100).contains(&result));
+    }
+
+    #[test]
+    fn exponential_backoff_rejects_invalid_inputs_with_frozen_messages() {
+        let attempt_msg = "exponentialBackoff requires attempt to be a positive integer";
+        for attempt in [0.0, -1.0, f64::NAN, f64::INFINITY, 1.5] {
+            let err = exponential_backoff(ExponentialBackoffOptions {
+                attempt,
+                base_ms: Some(1000.0),
+                max_ms: Some(60000.0),
+                jitter_factor: Some(0.1),
+            })
+            .unwrap_err();
+            assert_eq!(err.message(), attempt_msg);
+        }
+
+        let err = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 1.0,
+            base_ms: Some(-1.0),
+            max_ms: Some(60000.0),
+            jitter_factor: Some(0.1),
+        })
+        .unwrap_err();
+        assert_eq!(
+            err.message(),
+            "exponentialBackoff requires baseMs to be a finite non-negative number"
+        );
+
+        let err = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 1.0,
+            base_ms: Some(1000.0),
+            max_ms: Some(-1.0),
+            jitter_factor: Some(0.1),
+        })
+        .unwrap_err();
+        assert_eq!(
+            err.message(),
+            "exponentialBackoff requires maxMs to be a finite non-negative number"
+        );
+
+        let err = exponential_backoff(ExponentialBackoffOptions {
+            attempt: 1.0,
+            base_ms: None,
+            max_ms: None,
+            jitter_factor: Some(2.0),
+        })
+        .unwrap_err();
+        assert_eq!(
+            err.message(),
+            "exponentialBackoff requires jitterFactor to be between 0 and 1"
+        );
+    }
+}
diff --git a/crates/rotation/src/trackers.rs b/crates/rotation/src/trackers.rs
new file mode 100644
index 000000000..19b7fcbc5
--- /dev/null
+++ b/crates/rotation/src/trackers.rs
@@ -0,0 +1,1132 @@
+//! Port of `lib/rotation.ts` trackers — [`HealthScoreTracker`] and
+//! [`TokenBucketTracker`].
+//!
+//! **HARD RULE (spec 04 gotcha 1 / ARCHITECTURE §8.4): nothing in this module
+//! is ever persisted.** No state type here implements `serde::Serialize`; that
+//! absence is the compiler-enforced never-persist boundary. Writing local
+//! token-bucket state into the persisted `rateLimitResetTimes` was the critical
+//! 6.4.0 regression (fixed in 6.4.1) — do not add `Serialize` derives.
+//!
+//! Composite tracker keying (spec 04 §1): every entry is keyed by
+//! `JSON.stringify([String(accountKey), quotaKey ?? null])`, so a numeric key
+//! `3` and the string key `"3"` normalize identically, and quota scopes
+//! (`"codex"` / `"codex:gpt-5-codex"`) isolate state per account × quota.
+//!
+//! Timing constants (spec 04 §13): health +1 success / −10 rate-limit / −20
+//! failure, clamped 0..100, +2/hour passive recovery; token bucket 50 max,
+//! 6/min fractional refill, 90 000 ms refund window.
+//!
+//! The wall clock is injectable ([`cma_core::clock::Clock`]) purely as the test
+//! seam replacing vitest fake timers; production paths use the system clock.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex, MutexGuard, OnceLock};
+
+use cma_core::clock::{Clock, system_clock};
+
+// ============================================================================
+// Tracker keying
+// ============================================================================
+
+/// `type TrackerKey = number | string` from `lib/rotation.ts`.
+///
+/// Account keys are either pool indexes (numbers) or sticky identity strings
+/// (e.g. `"email:user@example.com"`). Both normalize to the string form used
+/// inside the composite JSON key, so [`TrackerKey::Number`]`(3)` and
+/// [`TrackerKey::Text`]`("3")` address the same entry.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum TrackerKey {
+    /// Numeric account key (JS `number`; typically a pool index).
+    Number(i64),
+    /// String account key (stable identity key).
+    Text(String),
+}
+
+impl TrackerKey {
+    /// The JS `String(accountKey)` normalization: numbers render in decimal.
+    pub fn normalized(&self) -> String {
+        match self {
+            TrackerKey::Number(n) => n.to_string(),
+            TrackerKey::Text(s) => s.clone(),
+        }
+    }
+}
+
+impl std::fmt::Display for TrackerKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.normalized())
+    }
+}
+
+impl From<i64> for TrackerKey {
+    fn from(value: i64) -> Self {
+        TrackerKey::Number(value)
+    }
+}
+
+impl From<i32> for TrackerKey {
+    fn from(value: i32) -> Self {
+        TrackerKey::Number(i64::from(value))
+    }
+}
+
+impl From<u32> for TrackerKey {
+    fn from(value: u32) -> Self {
+        TrackerKey::Number(i64::from(value))
+    }
+}
+
+impl From<usize> for TrackerKey {
+    fn from(value: usize) -> Self {
+        TrackerKey::Number(value as i64)
+    }
+}
+
+impl From<&str> for TrackerKey {
+    fn from(value: &str) -> Self {
+        TrackerKey::Text(value.to_string())
+    }
+}
+
+impl From<String> for TrackerKey {
+    fn from(value: String) -> Self {
+        TrackerKey::Text(value)
+    }
+}
+
+impl From<&String> for TrackerKey {
+    fn from(value: &String) -> Self {
+        TrackerKey::Text(value.clone())
+    }
+}
+
+/// `normalizeTrackerKey`: `JSON.stringify([String(accountKey), quotaKey ?? null])`.
+///
+/// Byte-identical to the TS composite key (compact JSON, `null` for an absent
+/// quota key) so diagnostic dumps of tracker keys line up between ports.
+fn normalize_tracker_key(account_key: &TrackerKey, quota_key: Option<&str>) -> String {
+    serde_json::to_string(&(account_key.normalized(), quota_key))
+        .expect("tracker key serialization cannot fail")
+}
+
+/// Parse a composite tracker key back into `(accountKey, quotaKey)`.
+/// Malformed keys yield `None` (TS wraps `JSON.parse` in try/catch and
+/// ignores failures).
+fn parse_tracker_key(key: &str) -> Option<(String, Option<String>)> {
+    serde_json::from_str::<(String, Option<String>)>(key).ok()
+}
+
+/// `/^\d+$/` — ASCII digits only, non-empty.
+fn is_all_digits(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|b| b.is_ascii_digit())
+}
+
+fn lock_entries<'a, T>(mutex: &'a Mutex<T>) -> MutexGuard<'a, T> {
+    mutex
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+// ============================================================================
+// Health score tracking
+// ============================================================================
+
+/// `HealthScoreConfig` — deltas and bounds for [`HealthScoreTracker`].
+/// NEVER derives `Serialize` (never-persist boundary).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct HealthScoreConfig {
+    /// Points added on successful request.
+    pub success_delta: f64,
+    /// Points deducted on rate limit (negative).
+    pub rate_limit_delta: f64,
+    /// Points deducted on other failures (negative).
+    pub failure_delta: f64,
+    /// Maximum health score.
+    pub max_score: f64,
+    /// Minimum health score.
+    pub min_score: f64,
+    /// Points recovered per hour of inactivity.
+    pub passive_recovery_per_hour: f64,
+}
+
+/// `DEFAULT_HEALTH_SCORE_CONFIG` = `{ +1, −10, −20, 100, 0, +2/hr }`.
+pub const DEFAULT_HEALTH_SCORE_CONFIG: HealthScoreConfig = HealthScoreConfig {
+    success_delta: 1.0,
+    rate_limit_delta: -10.0,
+    failure_delta: -20.0,
+    max_score: 100.0,
+    min_score: 0.0,
+    passive_recovery_per_hour: 2.0,
+};
+
+impl Default for HealthScoreConfig {
+    fn default() -> Self {
+        DEFAULT_HEALTH_SCORE_CONFIG
+    }
+}
+
+/// Per-key health entry. In-memory only; never serialized.
+#[derive(Debug, Clone)]
+struct HealthEntry {
+    score: f64,
+    last_updated: i64,
+    consecutive_failures: u32,
+}
+
+/// Tracks health scores for accounts to prioritize healthy accounts.
+/// Accounts with higher health scores are preferred for selection.
+///
+/// Thread-safe (interior mutability) so the process-wide singleton returned by
+/// [`get_health_tracker`] can be shared by reference.
+pub struct HealthScoreTracker {
+    entries: Mutex<HashMap<String, HealthEntry>>,
+    config: HealthScoreConfig,
+    clock: Arc<dyn Clock>,
+}
+
+impl Default for HealthScoreTracker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl HealthScoreTracker {
+    /// Tracker with [`DEFAULT_HEALTH_SCORE_CONFIG`] and the system clock.
+    pub fn new() -> Self {
+        Self::with_config(DEFAULT_HEALTH_SCORE_CONFIG)
+    }
+
+    /// Tracker with a custom config (TS `new HealthScoreTracker(partial)`;
+    /// use struct-update syntax over [`HealthScoreConfig::default`] for the
+    /// `Partial<…>` merge).
+    pub fn with_config(config: HealthScoreConfig) -> Self {
+        Self::with_config_and_clock(config, system_clock())
+    }
+
+    /// Test seam: custom config plus an injected clock (fake-timer analogue).
+    pub fn with_config_and_clock(config: HealthScoreConfig, clock: Arc<dyn Clock>) -> Self {
+        HealthScoreTracker {
+            entries: Mutex::new(HashMap::new()),
+            config,
+            clock,
+        }
+    }
+
+    fn key(&self, account_key: &TrackerKey, quota_key: Option<&str>) -> String {
+        normalize_tracker_key(account_key, quota_key)
+    }
+
+    /// `min(score + hoursSinceUpdate * passiveRecoveryPerHour, maxScore)`.
+    fn apply_passive_recovery(&self, entry: &HealthEntry, now: i64) -> f64 {
+        let hours_since_update = (now - entry.last_updated) as f64 / (1000.0 * 60.0 * 60.0);
+        let recovery = hours_since_update * self.config.passive_recovery_per_hour;
+        (entry.score + recovery).min(self.config.max_score)
+    }
+
+    /// Unknown key ⇒ `maxScore`; known ⇒ passive-recovered score.
+    /// **Read does not mutate** the stored entry.
+    pub fn get_score(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) -> f64 {
+        let key = self.key(&account_key.into(), quota_key);
+        let now = self.clock.now_ms();
+        let entries = lock_entries(&self.entries);
+        match entries.get(&key) {
+            Some(entry) => self.apply_passive_recovery(entry, now),
+            None => self.config.max_score,
+        }
+    }
+
+    /// Consecutive failure count; 0 when unknown.
+    pub fn get_consecutive_failures(
+        &self,
+        account_key: impl Into<TrackerKey>,
+        quota_key: Option<&str>,
+    ) -> u32 {
+        let key = self.key(&account_key.into(), quota_key);
+        let entries = lock_entries(&self.entries);
+        entries
+            .get(&key)
+            .map(|entry| entry.consecutive_failures)
+            .unwrap_or(0)
+    }
+
+    /// `min(base + successDelta, maxScore)`; resets consecutive failures.
+    pub fn record_success(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) {
+        self.record(
+            account_key.into(),
+            quota_key,
+            self.config.success_delta,
+            true,
+        );
+    }
+
+    /// `max(base + rateLimitDelta, minScore)`; consecutive failures +1.
+    pub fn record_rate_limit(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) {
+        self.record(
+            account_key.into(),
+            quota_key,
+            self.config.rate_limit_delta,
+            false,
+        );
+    }
+
+    /// `max(base + failureDelta, minScore)`; consecutive failures +1.
+    pub fn record_failure(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) {
+        self.record(
+            account_key.into(),
+            quota_key,
+            self.config.failure_delta,
+            false,
+        );
+    }
+
+    fn record(&self, account_key: TrackerKey, quota_key: Option<&str>, delta: f64, success: bool) {
+        let key = self.key(&account_key, quota_key);
+        let now = self.clock.now_ms();
+        let mut entries = lock_entries(&self.entries);
+        let entry = entries.get(&key);
+        let base_score = match entry {
+            Some(entry) => self.apply_passive_recovery(entry, now),
+            None => self.config.max_score,
+        };
+        // Clamp by METHOD identity, exactly like TS: recordSuccess uses
+        // `min(base + delta, maxScore)` (no lower clamp); recordRateLimit /
+        // recordFailure use `max(base + delta, minScore)` (no upper clamp).
+        // Inferring the clamp from the delta's sign would diverge for custom
+        // configs with sign-flipped deltas.
+        let new_score = if success {
+            (base_score + delta).min(self.config.max_score)
+        } else {
+            (base_score + delta).max(self.config.min_score)
+        };
+        let consecutive_failures = if success {
+            0
+        } else {
+            entry.map(|e| e.consecutive_failures).unwrap_or(0) + 1
+        };
+        entries.insert(
+            key,
+            HealthEntry {
+                score: new_score,
+                last_updated: now,
+                consecutive_failures,
+            },
+        );
+    }
+
+    /// Delete one composite key.
+    pub fn reset(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) {
+        let key = self.key(&account_key.into(), quota_key);
+        lock_entries(&self.entries).remove(&key);
+    }
+
+    /// Delete all entries.
+    pub fn clear(&self) {
+        lock_entries(&self.entries).clear();
+    }
+
+    /// Delete every entry whose parsed account key is all-digits and
+    /// `>= start_index` (index-removal fixups). Malformed keys are ignored.
+    pub fn clear_numeric_keys_at_or_above(&self, start_index: usize) {
+        let mut entries = lock_entries(&self.entries);
+        clear_numeric_keys_at_or_above_in(&mut entries, start_index);
+    }
+
+    /// Delete every entry (across all quota-key variants) for a given account
+    /// key. Used when an account is removed so a later re-add of the same
+    /// identity does not inherit stale health penalties (accounts-02).
+    pub fn clear_account_key(&self, account_key: impl Into<TrackerKey>) {
+        let normalized = account_key.into().normalized();
+        let mut entries = lock_entries(&self.entries);
+        clear_account_key_in(&mut entries, &normalized);
+    }
+}
+
+fn clear_numeric_keys_at_or_above_in<V>(entries: &mut HashMap<String, V>, start_index: usize) {
+    let to_remove: Vec<String> = entries
+        .keys()
+        .filter(|key| {
+            parse_tracker_key(key)
+                .map(|(account_key, _)| {
+                    is_all_digits(&account_key)
+                        && account_key
+                            .parse::<f64>()
+                            .map(|n| n >= start_index as f64)
+                            .unwrap_or(false)
+                })
+                .unwrap_or(false)
+        })
+        .cloned()
+        .collect();
+    for key in to_remove {
+        entries.remove(&key);
+    }
+}
+
+fn clear_account_key_in<V>(entries: &mut HashMap<String, V>, normalized: &str) {
+    let to_remove: Vec<String> = entries
+        .keys()
+        .filter(|key| {
+            parse_tracker_key(key)
+                .map(|(account_key, _)| account_key == normalized)
+                .unwrap_or(false)
+        })
+        .cloned()
+        .collect();
+    for key in to_remove {
+        entries.remove(&key);
+    }
+}
+
+// ============================================================================
+// Token bucket rate limiting
+// ============================================================================
+
+/// `TokenBucketConfig`. NEVER derives `Serialize` (never-persist boundary).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TokenBucketConfig {
+    /// Maximum tokens in bucket.
+    pub max_tokens: f64,
+    /// Tokens regenerated per minute (fractional refill allowed).
+    pub tokens_per_minute: f64,
+}
+
+/// `DEFAULT_TOKEN_BUCKET_CONFIG` = `{ maxTokens: 50, tokensPerMinute: 6 }`.
+pub const DEFAULT_TOKEN_BUCKET_CONFIG: TokenBucketConfig = TokenBucketConfig {
+    max_tokens: 50.0,
+    tokens_per_minute: 6.0,
+};
+
+impl Default for TokenBucketConfig {
+    fn default() -> Self {
+        DEFAULT_TOKEN_BUCKET_CONFIG
+    }
+}
+
+/// Default `drainAmount` for [`TokenBucketTracker::drain`] (TS default param).
+pub const DEFAULT_DRAIN_AMOUNT: f64 = 10.0;
+
+// Must cover the full request lifetime so a token consumed at request start can
+// still be refunded when the request fails at the very end. The runtime proxy
+// refunds on network error / upstream timeout, and the default fetch timeout is
+// 60_000ms (config fetchTimeoutMs) — measured AFTER token consumption and a
+// token refresh. 90_000ms = that 60s timeout plus slack for the refresh and
+// processing, so a genuinely timed-out request's token is reversed instead of
+// leaking (gradual token-bucket starvation -> spurious token-exhausted skips).
+const TOKEN_REFUND_WINDOW_MS: i64 = 90_000;
+
+/// Per-key bucket entry. In-memory only; never serialized.
+#[derive(Debug, Clone)]
+struct TokenBucketEntry {
+    tokens: f64,
+    last_refill: i64,
+    consumptions: Vec<i64>,
+}
+
+/// Client-side token bucket for rate limiting requests per account.
+/// Prevents sending requests to accounts that are likely to be rate-limited.
+///
+/// Thread-safe (interior mutability); see [`get_token_tracker`].
+pub struct TokenBucketTracker {
+    buckets: Mutex<HashMap<String, TokenBucketEntry>>,
+    config: TokenBucketConfig,
+    clock: Arc<dyn Clock>,
+}
+
+impl Default for TokenBucketTracker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl TokenBucketTracker {
+    /// Tracker with [`DEFAULT_TOKEN_BUCKET_CONFIG`] and the system clock.
+    pub fn new() -> Self {
+        Self::with_config(DEFAULT_TOKEN_BUCKET_CONFIG)
+    }
+
+    /// Tracker with a custom config (TS `Partial<TokenBucketConfig>` merge ⇒
+    /// struct-update syntax over [`TokenBucketConfig::default`]).
+    pub fn with_config(config: TokenBucketConfig) -> Self {
+        Self::with_config_and_clock(config, system_clock())
+    }
+
+    /// Test seam: custom config plus an injected clock.
+    pub fn with_config_and_clock(config: TokenBucketConfig, clock: Arc<dyn Clock>) -> Self {
+        TokenBucketTracker {
+            buckets: Mutex::new(HashMap::new()),
+            config,
+            clock,
+        }
+    }
+
+    fn key(&self, account_key: &TrackerKey, quota_key: Option<&str>) -> String {
+        normalize_tracker_key(account_key, quota_key)
+    }
+
+    /// `min(tokens + minutesSinceRefill * tokensPerMinute, maxTokens)`.
+    fn refill_tokens(&self, entry: &TokenBucketEntry, now: i64) -> f64 {
+        let minutes_since_refill = (now - entry.last_refill) as f64 / (1000.0 * 60.0);
+        let tokens_to_add = minutes_since_refill * self.config.tokens_per_minute;
+        (entry.tokens + tokens_to_add).min(self.config.max_tokens)
+    }
+
+    /// Unknown key ⇒ `maxTokens`; else the refilled value (no mutation).
+    pub fn get_tokens(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) -> f64 {
+        let key = self.key(&account_key.into(), quota_key);
+        let now = self.clock.now_ms();
+        let buckets = lock_entries(&self.buckets);
+        match buckets.get(&key) {
+            Some(entry) => self.refill_tokens(entry, now),
+            None => self.config.max_tokens,
+        }
+    }
+
+    /// Attempt to consume a token. Returns `true` if successful, `false` if
+    /// the bucket is empty. Resets `lastRefill = now` on success (refill
+    /// accrual restarts on every mutation — spec 04 gotcha 4).
+    pub fn try_consume(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) -> bool {
+        let key = self.key(&account_key.into(), quota_key);
+        let now = self.clock.now_ms();
+        let mut buckets = lock_entries(&self.buckets);
+        let entry = buckets.get(&key);
+        let current_tokens = match entry {
+            Some(entry) => self.refill_tokens(entry, now),
+            None => self.config.max_tokens,
+        };
+
+        if current_tokens < 1.0 {
+            return false;
+        }
+
+        let cutoff = now - TOKEN_REFUND_WINDOW_MS;
+        let mut consumptions: Vec<i64> = entry
+            .map(|e| {
+                e.consumptions
+                    .iter()
+                    .copied()
+                    .filter(|timestamp| *timestamp >= cutoff)
+                    .collect()
+            })
+            .unwrap_or_default();
+        consumptions.push(now);
+
+        buckets.insert(
+            key,
+            TokenBucketEntry {
+                tokens: current_tokens - 1.0,
+                last_refill: now,
+                consumptions,
+            },
+        );
+        true
+    }
+
+    /// Attempt to refund a token consumed within the 90 s refund window.
+    /// Use this when a request fails due to network errors (not rate limits —
+    /// a 429 is genuine quota consumption and is NOT refunded, gotcha 17).
+    /// Removes the FIRST in-window consumption; returns `false` if no valid
+    /// consumption is found. Resets `lastRefill = now` on success.
+    pub fn refund_token(
+        &self,
+        account_key: impl Into<TrackerKey>,
+        quota_key: Option<&str>,
+    ) -> bool {
+        let key = self.key(&account_key.into(), quota_key);
+        let now = self.clock.now_ms();
+        let mut buckets = lock_entries(&self.buckets);
+        let Some(entry) = buckets.get_mut(&key) else {
+            return false;
+        };
+        if entry.consumptions.is_empty() {
+            return false;
+        }
+
+        let cutoff = now - TOKEN_REFUND_WINDOW_MS;
+        let Some(valid_index) = entry
+            .consumptions
+            .iter()
+            .position(|timestamp| *timestamp >= cutoff)
+        else {
+            return false;
+        };
+
+        entry.consumptions.remove(valid_index);
+        // Refill from the pre-refund entry state (tokens + lastRefill), then
+        // add the refunded token back, capped at maxTokens.
+        let entry_snapshot = TokenBucketEntry {
+            tokens: entry.tokens,
+            last_refill: entry.last_refill,
+            consumptions: Vec::new(),
+        };
+        let current_tokens = self.refill_tokens(&entry_snapshot, now);
+        entry.tokens = (current_tokens + 1.0).min(self.config.max_tokens);
+        entry.last_refill = now;
+        true
+    }
+
+    /// Drain tokens on rate limit to prevent immediate retries. Creates the
+    /// entry if absent (starting from `maxTokens`); preserves consumptions and
+    /// resets `lastRefill = now`. TS default `drainAmount` is
+    /// [`DEFAULT_DRAIN_AMOUNT`].
+    pub fn drain(
+        &self,
+        account_key: impl Into<TrackerKey>,
+        quota_key: Option<&str>,
+        drain_amount: f64,
+    ) {
+        let key = self.key(&account_key.into(), quota_key);
+        let now = self.clock.now_ms();
+        let mut buckets = lock_entries(&self.buckets);
+        let entry = buckets.get(&key);
+        let current_tokens = match entry {
+            Some(entry) => self.refill_tokens(entry, now),
+            None => self.config.max_tokens,
+        };
+        let consumptions = entry.map(|e| e.consumptions.clone()).unwrap_or_default();
+        buckets.insert(
+            key,
+            TokenBucketEntry {
+                tokens: (current_tokens - drain_amount).max(0.0),
+                last_refill: now,
+                consumptions,
+            },
+        );
+    }
+
+    /// Delete one composite key.
+    pub fn reset(&self, account_key: impl Into<TrackerKey>, quota_key: Option<&str>) {
+        let key = self.key(&account_key.into(), quota_key);
+        lock_entries(&self.buckets).remove(&key);
+    }
+
+    /// Delete all buckets.
+    pub fn clear(&self) {
+        lock_entries(&self.buckets).clear();
+    }
+
+    /// Delete every bucket whose parsed account key is all-digits and
+    /// `>= start_index`. Malformed keys are ignored.
+    pub fn clear_numeric_keys_at_or_above(&self, start_index: usize) {
+        let mut buckets = lock_entries(&self.buckets);
+        clear_numeric_keys_at_or_above_in(&mut buckets, start_index);
+    }
+
+    /// Delete every bucket (across all quota-key variants) for a given account
+    /// key, so a removed-then-re-added account does not inherit stale token
+    /// state (accounts-02).
+    pub fn clear_account_key(&self, account_key: impl Into<TrackerKey>) {
+        let normalized = account_key.into().normalized();
+        let mut buckets = lock_entries(&self.buckets);
+        clear_account_key_in(&mut buckets, &normalized);
+    }
+}
+
+// ============================================================================
+// Singleton instances
+// ============================================================================
+
+static HEALTH_TRACKER_INSTANCE: OnceLock<HealthScoreTracker> = OnceLock::new();
+static TOKEN_TRACKER_INSTANCE: OnceLock<TokenBucketTracker> = OnceLock::new();
+
+/// Lazy process-wide health tracker singleton. `config` is honored only on the
+/// first call (spec 04 gotcha 27).
+pub fn get_health_tracker(config: Option<HealthScoreConfig>) -> &'static HealthScoreTracker {
+    HEALTH_TRACKER_INSTANCE.get_or_init(|| match config {
+        Some(config) => HealthScoreTracker::with_config(config),
+        None => HealthScoreTracker::new(),
+    })
+}
+
+/// Lazy process-wide token tracker singleton. `config` is honored only on the
+/// first call (spec 04 gotcha 27).
+pub fn get_token_tracker(config: Option<TokenBucketConfig>) -> &'static TokenBucketTracker {
+    TOKEN_TRACKER_INSTANCE.get_or_init(|| match config {
+        Some(config) => TokenBucketTracker::with_config(config),
+        None => TokenBucketTracker::new(),
+    })
+}
+
+/// `resetTrackers()` — clears both singletons **if instantiated** (does NOT
+/// null them out; the instances and their configs survive).
+pub fn reset_trackers() {
+    if let Some(tracker) = HEALTH_TRACKER_INSTANCE.get() {
+        tracker.clear();
+    }
+    if let Some(tracker) = TOKEN_TRACKER_INSTANCE.get() {
+        tracker.clear();
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/rotation.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::clock::ManualClock;
+
+    /// 2026-01-30T12:00:00Z, the fake-timer epoch used by rotation.test.ts.
+    const T0: i64 = 1_769_774_400_000;
+
+    fn health_with_clock() -> (HealthScoreTracker, Arc<ManualClock>) {
+        let clock = Arc::new(ManualClock::new(T0));
+        let tracker =
+            HealthScoreTracker::with_config_and_clock(DEFAULT_HEALTH_SCORE_CONFIG, clock.clone());
+        (tracker, clock)
+    }
+
+    fn tokens_with_clock() -> (TokenBucketTracker, Arc<ManualClock>) {
+        let clock = Arc::new(ManualClock::new(T0));
+        let tracker =
+            TokenBucketTracker::with_config_and_clock(DEFAULT_TOKEN_BUCKET_CONFIG, clock.clone());
+        (tracker, clock)
+    }
+
+    #[test]
+    fn tracker_key_normalization_is_composite_json() {
+        assert_eq!(
+            normalize_tracker_key(&TrackerKey::Number(3), None),
+            "[\"3\",null]"
+        );
+        assert_eq!(
+            normalize_tracker_key(&TrackerKey::Text("3".into()), None),
+            "[\"3\",null]"
+        );
+        assert_eq!(
+            normalize_tracker_key(&TrackerKey::Text("acc".into()), Some("codex:gpt-5-codex")),
+            "[\"acc\",\"codex:gpt-5-codex\"]"
+        );
+    }
+
+    // ---------------- HealthScoreTracker ----------------
+
+    #[test]
+    fn health_returns_max_score_for_unknown_accounts() {
+        let (tracker, _clock) = health_with_clock();
+        assert_eq!(
+            tracker.get_score(0usize, None),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert_eq!(
+            tracker.get_score(0usize, Some("quota-a")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+    }
+
+    #[test]
+    fn health_record_success_increases_score_and_resets_failures() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_rate_limit(0usize, None);
+        let after_rate_limit = tracker.get_score(0usize, None);
+        tracker.record_success(0usize, None);
+        assert!(tracker.get_score(0usize, None) > after_rate_limit);
+
+        tracker.record_failure(0usize, None);
+        tracker.record_failure(0usize, None);
+        assert_eq!(tracker.get_consecutive_failures(0usize, None), 2);
+        tracker.record_success(0usize, None);
+        assert_eq!(tracker.get_consecutive_failures(0usize, None), 0);
+    }
+
+    #[test]
+    fn health_success_does_not_exceed_max_score() {
+        let (tracker, _clock) = health_with_clock();
+        for _ in 0..200 {
+            tracker.record_success(0usize, None);
+        }
+        assert!(tracker.get_score(0usize, None) <= DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+    }
+
+    #[test]
+    fn health_rate_limit_decreases_score_and_increments_failures() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_rate_limit(0usize, None);
+        let expected =
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score + DEFAULT_HEALTH_SCORE_CONFIG.rate_limit_delta;
+        assert_eq!(tracker.get_score(0usize, None), expected);
+        assert_eq!(tracker.get_consecutive_failures(0usize, None), 1);
+        tracker.record_rate_limit(0usize, None);
+        assert_eq!(tracker.get_consecutive_failures(0usize, None), 2);
+    }
+
+    #[test]
+    fn health_failure_decreases_score_by_failure_delta() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_failure(0usize, None);
+        let expected =
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score + DEFAULT_HEALTH_SCORE_CONFIG.failure_delta;
+        assert_eq!(tracker.get_score(0usize, None), expected);
+    }
+
+    #[test]
+    fn health_does_not_go_below_min_score() {
+        let (tracker, _clock) = health_with_clock();
+        for _ in 0..10 {
+            tracker.record_failure(0usize, None);
+        }
+        assert_eq!(
+            tracker.get_score(0usize, None),
+            DEFAULT_HEALTH_SCORE_CONFIG.min_score
+        );
+    }
+
+    #[test]
+    fn health_passive_recovery_over_time() {
+        let (tracker, clock) = health_with_clock();
+        tracker.record_rate_limit(0usize, None);
+        let after_rate_limit = tracker.get_score(0usize, None);
+
+        clock.advance(1000 * 60 * 60);
+        let after_one_hour = tracker.get_score(0usize, None);
+        let expected_recovery = DEFAULT_HEALTH_SCORE_CONFIG.passive_recovery_per_hour;
+        assert!((after_one_hour - (after_rate_limit + expected_recovery)).abs() < 0.1);
+
+        clock.advance(1000 * 60 * 60 * 100);
+        assert!(tracker.get_score(0usize, None) <= DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+    }
+
+    #[test]
+    fn health_read_does_not_mutate_the_stored_entry() {
+        let (tracker, clock) = health_with_clock();
+        tracker.record_rate_limit(0usize, None); // 90 at T0
+        clock.advance(1000 * 60 * 60); // +2 recovery on read
+        let first = tracker.get_score(0usize, None);
+        let second = tracker.get_score(0usize, None);
+        assert_eq!(first, second);
+        assert_eq!(tracker.get_consecutive_failures(0usize, None), 1);
+    }
+
+    #[test]
+    fn health_reset_and_clear() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_failure(0usize, None);
+        tracker.record_failure(1usize, None);
+
+        tracker.reset(0usize, None);
+        assert_eq!(
+            tracker.get_score(0usize, None),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert!(tracker.get_score(1usize, None) < DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+
+        tracker.record_failure(2usize, None);
+        tracker.clear();
+        for index in 0usize..3 {
+            assert_eq!(
+                tracker.get_score(index, None),
+                DEFAULT_HEALTH_SCORE_CONFIG.max_score
+            );
+        }
+    }
+
+    #[test]
+    fn health_isolates_scores_by_quota_key() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_failure(0usize, Some("quota-a"));
+        tracker.record_success(0usize, Some("quota-b"));
+
+        assert!(tracker.get_score(0usize, Some("quota-a")) < DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+        assert_eq!(
+            tracker.get_score(0usize, Some("quota-b")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+    }
+
+    #[test]
+    fn health_clear_account_key_clears_every_quota_variant() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_failure("acc", Some("codex"));
+        tracker.record_failure("acc", Some("codex:gpt-5.1"));
+        tracker.record_failure("other", Some("codex"));
+
+        tracker.clear_account_key("acc");
+
+        assert_eq!(
+            tracker.get_score("acc", Some("codex")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert_eq!(
+            tracker.get_score("acc", Some("codex:gpt-5.1")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert!(tracker.get_score("other", Some("codex")) < DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+    }
+
+    #[test]
+    fn health_clear_account_key_normalizes_numeric_keys() {
+        let (tracker, _clock) = health_with_clock();
+        // Write under the numeric key but clear with the string form.
+        tracker.record_failure(3usize, Some("codex"));
+        tracker.clear_account_key("3");
+        assert_eq!(
+            tracker.get_score(3usize, Some("codex")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+    }
+
+    #[test]
+    fn health_clear_numeric_keys_at_or_above() {
+        let (tracker, _clock) = health_with_clock();
+        tracker.record_failure(0usize, None);
+        tracker.record_failure(1usize, Some("codex"));
+        tracker.record_failure(2usize, None);
+        tracker.record_failure("identity", Some("codex"));
+
+        tracker.clear_numeric_keys_at_or_above(1);
+
+        assert!(tracker.get_score(0usize, None) < DEFAULT_HEALTH_SCORE_CONFIG.max_score);
+        assert_eq!(
+            tracker.get_score(1usize, Some("codex")),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert_eq!(
+            tracker.get_score(2usize, None),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        // Non-numeric identity keys survive.
+        assert!(
+            tracker.get_score("identity", Some("codex")) < DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+    }
+
+    // ---------------- TokenBucketTracker ----------------
+
+    #[test]
+    fn tokens_returns_max_for_unknown_accounts() {
+        let (tracker, _clock) = tokens_with_clock();
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    fn tokens_try_consume_consumes_one_token() {
+        let (tracker, _clock) = tokens_with_clock();
+        assert!(tracker.try_consume(0usize, None));
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens - 1.0
+        );
+    }
+
+    #[test]
+    fn tokens_try_consume_returns_false_when_empty() {
+        let (tracker, _clock) = tokens_with_clock();
+        for _ in 0..DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens as usize {
+            tracker.try_consume(0usize, None);
+        }
+        assert!(!tracker.try_consume(0usize, None));
+    }
+
+    #[test]
+    fn tokens_refund_within_window() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.try_consume(0usize, None);
+        assert!(tracker.refund_token(0usize, None));
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    fn tokens_refund_covers_the_55s_request_lifetime() {
+        // tokensPerMinute: 0 so refill can't mask the refund's restored token.
+        let clock = Arc::new(ManualClock::new(T0));
+        let no_refill = TokenBucketTracker::with_config_and_clock(
+            TokenBucketConfig {
+                tokens_per_minute: 0.0,
+                ..TokenBucketConfig::default()
+            },
+            clock.clone(),
+        );
+        no_refill.try_consume(0usize, None);
+        let before_refund = no_refill.get_tokens(0usize, None);
+
+        clock.advance(55_000);
+
+        assert!(no_refill.refund_token(0usize, None));
+        assert_eq!(no_refill.get_tokens(0usize, None), before_refund + 1.0);
+    }
+
+    #[test]
+    fn tokens_refund_window_boundary_is_inclusive() {
+        // The cutoff is `timestamp >= now - TOKEN_REFUND_WINDOW_MS`.
+        let clock = Arc::new(ManualClock::new(T0));
+        let no_refill = TokenBucketTracker::with_config_and_clock(
+            TokenBucketConfig {
+                tokens_per_minute: 0.0,
+                ..TokenBucketConfig::default()
+            },
+            clock.clone(),
+        );
+        no_refill.try_consume(0usize, None);
+        let before_refund = no_refill.get_tokens(0usize, None);
+
+        clock.advance(TOKEN_REFUND_WINDOW_MS);
+
+        assert!(no_refill.refund_token(0usize, None));
+        assert_eq!(no_refill.get_tokens(0usize, None), before_refund + 1.0);
+    }
+
+    #[test]
+    fn tokens_refund_rejected_for_ancient_consumption() {
+        let (tracker, clock) = tokens_with_clock();
+        tracker.try_consume(0usize, None);
+        clock.advance(TOKEN_REFUND_WINDOW_MS + 1);
+        assert!(!tracker.refund_token(0usize, None));
+    }
+
+    #[test]
+    fn tokens_refund_returns_false_without_consumptions() {
+        let (tracker, _clock) = tokens_with_clock();
+        assert!(!tracker.refund_token(0usize, None));
+    }
+
+    #[test]
+    fn tokens_refund_does_not_exceed_max_tokens() {
+        let (tracker, clock) = tokens_with_clock();
+        tracker.try_consume(0usize, None);
+        clock.advance(10_000);
+        assert!(tracker.refund_token(0usize, None));
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    fn tokens_refill_over_time_and_cap() {
+        let (tracker, clock) = tokens_with_clock();
+        for _ in 0..10 {
+            tracker.try_consume(0usize, None);
+        }
+        let after_drain = tracker.get_tokens(0usize, None);
+        clock.advance(1000 * 60);
+        assert!(tracker.get_tokens(0usize, None) > after_drain);
+
+        clock.advance(1000 * 60 * 60);
+        assert!(tracker.get_tokens(0usize, None) <= DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens);
+    }
+
+    #[test]
+    fn tokens_drain_removes_specified_tokens() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.drain(0usize, None, 20.0);
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens - 20.0
+        );
+    }
+
+    #[test]
+    fn tokens_drain_does_not_go_below_zero() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.drain(0usize, None, 100.0);
+        assert_eq!(tracker.get_tokens(0usize, None), 0.0);
+    }
+
+    #[test]
+    fn tokens_drain_creates_entry_starting_from_max() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.drain(5usize, Some("new-quota"), 5.0);
+        assert_eq!(
+            tracker.get_tokens(5usize, Some("new-quota")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens - 5.0
+        );
+    }
+
+    #[test]
+    fn tokens_reset_and_clear() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.drain(0usize, None, 30.0);
+        tracker.drain(1usize, None, 30.0);
+
+        tracker.reset(0usize, None);
+        assert_eq!(
+            tracker.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+        assert!(tracker.get_tokens(1usize, None) < DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens);
+
+        tracker.clear();
+        assert_eq!(
+            tracker.get_tokens(1usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    fn tokens_clear_account_key_clears_every_quota_variant() {
+        let (tracker, _clock) = tokens_with_clock();
+        tracker.drain("acc", Some("codex"), 30.0);
+        tracker.drain("acc", Some("codex:gpt-5.1"), 30.0);
+        tracker.drain("other", Some("codex"), 30.0);
+
+        tracker.clear_account_key("acc");
+
+        assert_eq!(
+            tracker.get_tokens("acc", Some("codex")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+        assert_eq!(
+            tracker.get_tokens("acc", Some("codex:gpt-5.1")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+        assert!(tracker.get_tokens("other", Some("codex")) < DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens);
+    }
+
+    #[test]
+    fn tokens_clear_account_key_normalizes_numeric_keys() {
+        let (tracker, _clock) = tokens_with_clock();
+        // Drain under the string key but clear with the numeric form.
+        tracker.drain("3", Some("codex"), 30.0);
+        tracker.clear_account_key(3usize);
+        assert_eq!(
+            tracker.get_tokens("3", Some("codex")),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+
+    #[test]
+    fn tokens_consume_resets_last_refill_to_now() {
+        // lastRefill must be reset to `now` on every mutation (gotcha 4):
+        // otherwise refill accrual double-counts the elapsed time.
+        let (tracker, clock) = tokens_with_clock();
+        tracker.drain(0usize, None, 30.0); // 20 tokens, lastRefill = T0
+        clock.advance(30_000); // refill view: 20 + 3 = 23
+        assert_eq!(tracker.get_tokens(0usize, None), 23.0);
+        tracker.try_consume(0usize, None); // 23 - 1 = 22, lastRefill = T0+30s
+        clock.advance(10_000); // +1 from the NEW lastRefill
+        // A non-reset lastRefill (still T0) would yield 22 + 4 = 26 here.
+        assert_eq!(tracker.get_tokens(0usize, None), 23.0);
+    }
+
+    // ---------------- singletons ----------------
+
+    #[test]
+    #[serial_test::serial(rotation_tracker_singletons)]
+    fn singletons_are_process_wide_and_reset_clears_them() {
+        let first = get_health_tracker(None);
+        let second = get_health_tracker(None);
+        assert!(std::ptr::eq(first, second));
+
+        let token_first = get_token_tracker(None);
+        let token_second = get_token_tracker(None);
+        assert!(std::ptr::eq(token_first, token_second));
+
+        first.record_failure(0usize, None);
+        token_first.drain(0usize, None, 30.0);
+        reset_trackers();
+        assert_eq!(
+            first.get_score(0usize, None),
+            DEFAULT_HEALTH_SCORE_CONFIG.max_score
+        );
+        assert_eq!(
+            token_first.get_tokens(0usize, None),
+            DEFAULT_TOKEN_BUCKET_CONFIG.max_tokens
+        );
+    }
+}
diff --git a/crates/runtime/Cargo.toml b/crates/runtime/Cargo.toml
new file mode 100644
index 000000000..d4008f886
--- /dev/null
+++ b/crates/runtime/Cargo.toml
@@ -0,0 +1,41 @@
+[package]
+name = "cma-runtime"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-storage = { path = "../storage" }
+cma-auth = { path = "../auth" }
+cma-accounts = { path = "../accounts" }
+cma-rotation = { path = "../rotation" }
+cma-request = { path = "../request" }
+cma-quota = { path = "../quota" }
+cma-cli-mirror = { path = "../climirror" }
+cma-usage = { path = "../usage" }
+serde.workspace = true
+serde_json.workspace = true
+sha1.workspace = true
+sha2.workspace = true
+tokio.workspace = true
+reqwest.workspace = true
+uuid.workspace = true
+rand.workspace = true
+chrono.workspace = true
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.60", features = ["Win32_System_Threading"] }
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/runtime/src/account_check.rs b/crates/runtime/src/account_check.rs
new file mode 100644
index 000000000..d530357b1
--- /dev/null
+++ b/crates/runtime/src/account_check.rs
@@ -0,0 +1,968 @@
+//! Port of `lib/runtime/account-check.ts` (+ `account-check-helpers.ts`,
+//! `account-check-types.ts`) — the CLI `check` command engine
+//! (spec 10 §13).
+//!
+//! Output contract: every `[i/total] label: ...` progress line and the
+//! `Results: ...` summary are frozen strings (spec 10 §25).
+//!
+//! Note: disabled accounts are counted + printed as `DISABLED` and skipped —
+//! the "re-enable working disabled accounts" behavior lives in the manager
+//! crate's `health_check.rs` (TS `lib/codex-manager/health-check.ts`), not
+//! here (the runtime TS module has no re-enable path).
+
+use cma_core::errors::CodexError;
+use cma_core::logger::mask_email;
+use cma_core::model_family::{MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3, ActiveIndexByFamily};
+use cma_core::schemas::flagged::{FlaggedAccountMetadataV1, FlaggedAccountStorageV1};
+use cma_core::schemas::token::{TokenFailure, TokenResult};
+use cma_core::token_utils::{
+    extract_account_email, extract_account_id, resolve_request_account_id, sanitize_email,
+    should_update_account_id_from_token,
+};
+use cma_quota::probe::{CODEX_UNAVAILABLE_PROBE_NOTE, CodexQuotaSnapshot};
+use cma_storage::matching::reconcile_pinned_account_index;
+use std::collections::HashSet;
+
+/// Codex CLI token-cache lookup result (TS inline
+/// `{refreshToken?, accessToken, expiresAt?}`).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct CliCachedTokens {
+    pub access_token: String,
+    pub refresh_token: Option<String>,
+    /// Kept as `f64` to mirror the tolerant CLI-state parse (`Number()`
+    /// coercion); non-finite values behave like "no expiry".
+    pub expires_at: Option<f64>,
+}
+
+/// TS `AccountCheckWorkingState` (account-check-types.ts).
+#[derive(Debug)]
+pub struct AccountCheckWorkingState {
+    pub storage_changed: bool,
+    pub flagged_changed: bool,
+    pub ok: u32,
+    pub errors: u32,
+    pub warnings: u32,
+    pub disabled: u32,
+    pub remove_from_active: HashSet<String>,
+    pub flagged_storage: FlaggedAccountStorageV1,
+}
+
+/// TS `createAccountCheckWorkingState(flaggedStorage)`.
+pub fn create_account_check_working_state(
+    flagged_storage: FlaggedAccountStorageV1,
+) -> AccountCheckWorkingState {
+    AccountCheckWorkingState {
+        storage_changed: false,
+        flagged_changed: false,
+        ok: 0,
+        errors: 0,
+        warnings: 0,
+        disabled: 0,
+        remove_from_active: HashSet::new(),
+        flagged_storage,
+    }
+}
+
+/// TS `clampActiveIndices(storage, families)` (account-check-helpers.ts).
+pub fn clamp_active_indices(storage: &mut AccountStorageV3, families: &[ModelFamily]) {
+    let count = storage.accounts.len();
+    if count == 0 {
+        storage.active_index = 0;
+        storage.active_index_by_family = Some(ActiveIndexByFamily::default());
+        return;
+    }
+    let max_index = count as i64 - 1;
+    storage.active_index = storage.active_index.clamp(0, max_index);
+    let mut by_family = storage.active_index_by_family.take().unwrap_or_default();
+    for family in families {
+        let candidate = by_family.get(*family).unwrap_or(storage.active_index);
+        by_family.set(*family, Some(candidate.clamp(0, max_index)));
+    }
+    storage.active_index_by_family = Some(by_family);
+}
+
+/// TS `isFlaggableFailure(failure)` — `missing_refresh`, HTTP 401, or a 400
+/// whose message mentions a revoked/invalid refresh grant.
+pub fn is_flaggable_failure(failure: &TokenFailure) -> bool {
+    use cma_core::schemas::token::TokenFailureReason;
+    if failure.reason == Some(TokenFailureReason::MissingRefresh) {
+        return true;
+    }
+    if failure.status_code == Some(401) {
+        return true;
+    }
+    if failure.status_code != Some(400) {
+        return false;
+    }
+    let message = failure
+        .message
+        .as_deref()
+        .unwrap_or("")
+        .to_lowercase();
+    message.contains("invalid_grant")
+        || message.contains("invalid refresh")
+        || message.contains("token has been revoked")
+}
+
+/// JS `message.slice(0, n)` (UTF-16 approximated with scalar values).
+fn truncate_chars(message: &str, limit: usize) -> String {
+    message.chars().take(limit).collect()
+}
+
+/// I/O seams of [`run_runtime_account_check`]. Pure helpers
+/// (token extraction, masking, clamping, flag classification) are called
+/// directly — the TS DI for those existed only for unit tests.
+#[allow(async_fn_in_trait)]
+pub trait AccountCheckDeps {
+    async fn hydrate_emails(
+        &mut self,
+        storage: Option<AccountStorageV3>,
+    ) -> Result<Option<AccountStorageV3>, CodexError>;
+    async fn load_accounts(&mut self) -> Result<Option<AccountStorageV3>, CodexError>;
+    async fn load_flagged_accounts(&mut self) -> Result<FlaggedAccountStorageV1, CodexError>;
+    /// Lookup errors are swallowed at the call site in TS
+    /// (`.catch(() => null)`) — return `None` on failure.
+    async fn lookup_codex_cli_tokens_by_email(
+        &mut self,
+        email: Option<&str>,
+    ) -> Option<CliCachedTokens>;
+    async fn queued_refresh(&mut self, refresh_token: &str) -> TokenResult;
+    async fn fetch_codex_quota_snapshot(
+        &mut self,
+        account_id: &str,
+        access_token: &str,
+    ) -> Result<CodexQuotaSnapshot, CodexError>;
+    fn format_codex_quota_line(&mut self, snapshot: &CodexQuotaSnapshot) -> String {
+        crate::quota_probe::format_codex_quota_line(snapshot)
+    }
+    async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError>;
+    async fn save_flagged_accounts(
+        &mut self,
+        storage: &FlaggedAccountStorageV1,
+    ) -> Result<(), CodexError>;
+    /// TS optional `persistAccountAndFlaggedStorage` — override BOTH methods
+    /// to enable the single combined persist.
+    fn supports_combined_persist(&self) -> bool {
+        false
+    }
+    async fn persist_account_and_flagged_storage(
+        &mut self,
+        accounts: &AccountStorageV3,
+        flagged: &FlaggedAccountStorageV1,
+    ) -> Result<(), CodexError> {
+        let _ = (accounts, flagged);
+        Ok(())
+    }
+    fn invalidate_account_manager_cache(&mut self);
+    fn now_ms(&mut self) -> i64 {
+        cma_core::utils::now_ms()
+    }
+    fn show_line(&mut self, message: &str);
+}
+
+/// Per-account outcome of the token-acquisition ladder.
+enum TokenOutcome {
+    /// `(access_token, token_account_id, auth_detail)`
+    Token(String, Option<String>, &'static str),
+    /// Refresh failed; the progress line was already printed.
+    RefreshFailed,
+    /// The ladder produced no token (TS `throw new Error("Missing access
+    /// token after refresh")` — caught by the outer per-account catch).
+    MissingAfterRefresh,
+}
+
+/// TS `runRuntimeAccountCheck(deepProbe, deps)`.
+pub async fn run_runtime_account_check<D: AccountCheckDeps>(
+    deep_probe: bool,
+    deps: &mut D,
+) -> Result<(), CodexError> {
+    let loaded = deps.load_accounts().await?;
+    let loaded_storage = deps.hydrate_emails(loaded).await?;
+    let mut working_storage = match loaded_storage {
+        Some(storage) => {
+            let mut clone = storage.clone();
+            if clone.active_index_by_family.is_none() {
+                clone.active_index_by_family = Some(ActiveIndexByFamily::default());
+            }
+            clone
+        }
+        None => AccountStorageV3::empty(),
+    };
+
+    if working_storage.accounts.is_empty() {
+        deps.show_line("\nNo accounts to check.\n");
+        return Ok(());
+    }
+
+    let flagged_storage = deps.load_flagged_accounts().await?;
+    let mut state = create_account_check_working_state(flagged_storage);
+    let total = working_storage.accounts.len();
+
+    deps.show_line(&format!(
+        "\nChecking {} for all accounts...\n",
+        if deep_probe { "full account health" } else { "quotas" }
+    ));
+
+    for i in 0..total {
+        let Some(account_snapshot) = working_storage.accounts.get(i).cloned() else {
+            continue;
+        };
+        let masked_email = account_snapshot.email.as_deref().map(mask_email);
+        let label = account_snapshot
+            .account_label
+            .clone()
+            .or(masked_email)
+            .unwrap_or_else(|| format!("Account {}", i + 1));
+
+        if account_snapshot.enabled == Some(false) {
+            state.disabled += 1;
+            deps.show_line(&format!("[{}/{total}] {label}: DISABLED", i + 1));
+            continue;
+        }
+
+        let now_ms = deps.now_ms();
+
+        // --- Token-acquisition ladder (mutates the working account). ---
+        let outcome = {
+            let account = working_storage
+                .accounts
+                .get_mut(i)
+                .expect("index in range");
+            let mut access_token: Option<String> = None;
+            let mut token_account_id: Option<String> = None;
+            let mut auth_detail: &'static str = "OK";
+
+            // (a) Stored access token still valid.
+            let stored_access_valid = account
+                .access_token
+                .as_deref()
+                .is_some_and(|t| !t.is_empty())
+                && account.expires_at.is_none_or(|expires| expires > now_ms);
+            if stored_access_valid {
+                access_token = account.access_token.clone();
+                auth_detail = "OK (cached access)";
+                token_account_id = extract_account_id(account.access_token.as_deref());
+                if let Some(token_id) = token_account_id.as_deref()
+                    && should_update_account_id_from_token(
+                        account.account_id_source.as_ref(),
+                        account.account_id.as_deref(),
+                    )
+                    && Some(token_id) != account.account_id.as_deref()
+                {
+                    account.account_id = Some(token_id.to_string());
+                    account.account_id_source = Some(AccountIdSource::Token);
+                    state.storage_changed = true;
+                }
+            }
+
+            // (b) Codex CLI token cache by email.
+            if access_token.is_none() {
+                let cached = deps
+                    .lookup_codex_cli_tokens_by_email(account_snapshot.email.as_deref())
+                    .await;
+                if let Some(cached) = cached {
+                    let cached_valid = match cached.expires_at {
+                        None => true,
+                        Some(v) if !v.is_finite() => true,
+                        Some(v) => v > now_ms as f64,
+                    };
+                    if cached_valid {
+                        access_token = Some(cached.access_token.clone());
+                        auth_detail = "OK (Codex CLI cache)";
+                        if !cached.access_token.is_empty()
+                            && Some(cached.access_token.as_str())
+                                != account.access_token.as_deref()
+                        {
+                            account.access_token = Some(cached.access_token.clone());
+                            state.storage_changed = true;
+                        }
+                        let cached_expires: Option<i64> = cached
+                            .expires_at
+                            .filter(|v| v.is_finite())
+                            .map(|v| v as i64);
+                        if cached_expires != account.expires_at {
+                            account.expires_at = cached_expires;
+                            state.storage_changed = true;
+                        }
+
+                        let hydrated_email = sanitize_email(
+                            extract_account_email(Some(&cached.access_token), None).as_deref(),
+                        );
+                        if let Some(email) = hydrated_email
+                            && Some(email.as_str()) != account.email.as_deref()
+                        {
+                            account.email = Some(email);
+                            state.storage_changed = true;
+                        }
+
+                        token_account_id = extract_account_id(Some(&cached.access_token));
+                        if let Some(token_id) = token_account_id.as_deref()
+                            && should_update_account_id_from_token(
+                                account.account_id_source.as_ref(),
+                                account.account_id.as_deref(),
+                            )
+                            && Some(token_id) != account.account_id.as_deref()
+                        {
+                            account.account_id = Some(token_id.to_string());
+                            account.account_id_source = Some(AccountIdSource::Token);
+                            state.storage_changed = true;
+                        }
+                    }
+                }
+            }
+
+            // (c) Queued refresh.
+            if access_token.is_none() {
+                let refresh_result = deps.queued_refresh(&account.refresh_token).await;
+                match refresh_result {
+                    TokenResult::Failed(failure) => {
+                        state.errors += 1;
+                        let message = failure
+                            .message
+                            .clone()
+                            .or_else(|| failure.reason.map(|r| r.as_str().to_string()))
+                            .unwrap_or_else(|| "refresh failed".to_string());
+                        deps.show_line(&format!(
+                            "[{}/{total}] {label}: ERROR ({message})",
+                            i + 1
+                        ));
+                        if deep_probe && is_flaggable_failure(&failure) {
+                            let flagged_record = FlaggedAccountMetadataV1::from_account(
+                                account.clone(),
+                                now_ms,
+                                Some("token-invalid".to_string()),
+                                Some(message),
+                            );
+                            let existing_index = state
+                                .flagged_storage
+                                .accounts
+                                .iter()
+                                .position(|f| f.refresh_token == account.refresh_token);
+                            match existing_index {
+                                Some(index) => {
+                                    state.flagged_storage.accounts[index] = flagged_record;
+                                }
+                                None => state.flagged_storage.accounts.push(flagged_record),
+                            }
+                            state
+                                .remove_from_active
+                                .insert(account.refresh_token.clone());
+                            state.flagged_changed = true;
+                        }
+                        TokenOutcome::RefreshFailed
+                    }
+                    TokenResult::Success(refreshed) => {
+                        access_token = Some(refreshed.access.clone());
+                        auth_detail = "OK";
+                        if refreshed.refresh != account.refresh_token {
+                            account.refresh_token = refreshed.refresh.clone();
+                            state.storage_changed = true;
+                        }
+                        if !refreshed.access.is_empty()
+                            && Some(refreshed.access.as_str()) != account.access_token.as_deref()
+                        {
+                            account.access_token = Some(refreshed.access.clone());
+                            state.storage_changed = true;
+                        }
+                        if Some(refreshed.expires) != account.expires_at {
+                            account.expires_at = Some(refreshed.expires);
+                            state.storage_changed = true;
+                        }
+                        let hydrated_email = sanitize_email(
+                            extract_account_email(
+                                Some(&refreshed.access),
+                                refreshed.id_token.as_deref(),
+                            )
+                            .as_deref(),
+                        );
+                        if let Some(email) = hydrated_email
+                            && Some(email.as_str()) != account.email.as_deref()
+                        {
+                            account.email = Some(email);
+                            state.storage_changed = true;
+                        }
+                        token_account_id = extract_account_id(Some(&refreshed.access));
+                        if let Some(token_id) = token_account_id.as_deref()
+                            && should_update_account_id_from_token(
+                                account.account_id_source.as_ref(),
+                                account.account_id.as_deref(),
+                            )
+                            && Some(token_id) != account.account_id.as_deref()
+                        {
+                            account.account_id = Some(token_id.to_string());
+                            account.account_id_source = Some(AccountIdSource::Token);
+                            state.storage_changed = true;
+                        }
+                        match access_token {
+                            Some(token) => {
+                                TokenOutcome::Token(token, token_account_id.clone(), auth_detail)
+                            }
+                            None => TokenOutcome::MissingAfterRefresh,
+                        }
+                    }
+                }
+            } else {
+                match access_token {
+                    Some(token) => {
+                        TokenOutcome::Token(token, token_account_id.clone(), auth_detail)
+                    }
+                    None => TokenOutcome::MissingAfterRefresh,
+                }
+            }
+        };
+
+        let (access_token, token_account_id, auth_detail) = match outcome {
+            TokenOutcome::RefreshFailed => continue,
+            TokenOutcome::MissingAfterRefresh => {
+                // TS `throw new Error("Missing access token after refresh")`
+                // caught by the outer per-account catch (120-char slice).
+                state.errors += 1;
+                deps.show_line(&format!(
+                    "[{}/{total}] {label}: ERROR ({})",
+                    i + 1,
+                    truncate_chars("Missing access token after refresh", 120)
+                ));
+                continue;
+            }
+            TokenOutcome::Token(token, id, detail) => (token, id, detail),
+        };
+
+        if deep_probe {
+            state.ok += 1;
+            let detail = match token_account_id.as_deref() {
+                Some(token_id) => {
+                    let chars: Vec<char> = token_id.chars().collect();
+                    let start = chars.len().saturating_sub(6);
+                    let suffix: String = chars[start..].iter().collect();
+                    format!("{auth_detail} (id:{suffix})")
+                }
+                None => auth_detail.to_string(),
+            };
+            deps.show_line(&format!("[{}/{total}] {label}: {detail}", i + 1));
+            continue;
+        }
+
+        // --- Quota probe (inner try/catch, 160-char truncation). ---
+        let account_ref = &working_storage.accounts[i];
+        let request_account_id = resolve_request_account_id(
+            account_ref.account_id.as_deref(),
+            account_ref.account_id_source.as_ref(),
+            token_account_id.as_deref(),
+        )
+        .or_else(|| token_account_id.clone())
+        .or_else(|| account_ref.account_id.clone());
+
+        let probe_result: Result<String, CodexError> = match request_account_id {
+            None => Err(CodexError::new("Missing accountId for quota probe")),
+            Some(request_account_id) => deps
+                .fetch_codex_quota_snapshot(&request_account_id, &access_token)
+                .await
+                .map(|snapshot| deps.format_codex_quota_line(&snapshot)),
+        };
+
+        match probe_result {
+            Ok(line) => {
+                state.ok += 1;
+                deps.show_line(&format!("[{}/{total}] {label}: {line}", i + 1));
+            }
+            Err(error) if error.is_codex_unavailable() => {
+                state.warnings += 1;
+                state.ok += 1;
+                deps.show_line(&format!(
+                    "[{}/{total}] {label}: {CODEX_UNAVAILABLE_PROBE_NOTE}",
+                    i + 1
+                ));
+            }
+            Err(error) => {
+                state.errors += 1;
+                deps.show_line(&format!(
+                    "[{}/{total}] {label}: ERROR ({})",
+                    i + 1,
+                    truncate_chars(error.message(), 160)
+                ));
+            }
+        }
+    }
+
+    if !state.remove_from_active.is_empty() {
+        // Follow the manual pin by IDENTITY across the removal (#474): the
+        // filter can drop several accounts at once, so a raw index would
+        // point at the wrong account or out of range.
+        let pinned_account = working_storage
+            .pinned_account_index
+            .and_then(|index| usize::try_from(index).ok())
+            .and_then(|index| working_storage.accounts.get(index).cloned());
+        working_storage
+            .accounts
+            .retain(|account| !state.remove_from_active.contains(&account.refresh_token));
+        clamp_active_indices(&mut working_storage, &MODEL_FAMILIES);
+        working_storage.pinned_account_index =
+            reconcile_pinned_account_index(pinned_account.as_ref(), &working_storage.accounts)
+                .map(|index| index as i64);
+        state.storage_changed = true;
+    }
+
+    let can_persist_together =
+        state.flagged_changed && state.storage_changed && deps.supports_combined_persist();
+    if can_persist_together {
+        deps.persist_account_and_flagged_storage(&working_storage, &state.flagged_storage)
+            .await?;
+        deps.invalidate_account_manager_cache();
+    } else {
+        if state.flagged_changed {
+            deps.save_flagged_accounts(&state.flagged_storage).await?;
+        }
+        if state.storage_changed {
+            deps.save_accounts(&working_storage).await?;
+            deps.invalidate_account_manager_cache();
+        }
+    }
+
+    deps.show_line("");
+    if state.warnings > 0 {
+        deps.show_line(&format!(
+            "Results: {} ok, {} warning, {} error, {} disabled",
+            state.ok, state.warnings, state.errors, state.disabled
+        ));
+    } else {
+        deps.show_line(&format!(
+            "Results: {} ok, {} error, {} disabled",
+            state.ok, state.errors, state.disabled
+        ));
+    }
+    if !state.remove_from_active.is_empty() {
+        deps.show_line(&format!(
+            "Moved {} account(s) to flagged pool (invalid refresh token).",
+            state.remove_from_active.len()
+        ));
+    }
+    deps.show_line("");
+    Ok(())
+}
+
+// =============================================================================
+// Tests — ported from test/account-check-helpers.test.ts +
+// test/runtime-account-check.test.ts (output contract)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_core::schemas::token::{TokenFailureReason, TokenSuccess};
+    use cma_quota::probe::CodexQuotaWindow;
+    use serde_json::json;
+
+    /// Minimal base64url (no padding) — the runtime crate has no base64
+    /// dev-dependency.
+    fn b64url(bytes: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut out = String::new();
+        for chunk in bytes.chunks(3) {
+            let b = [chunk[0], *chunk.get(1).unwrap_or(&0), *chunk.get(2).unwrap_or(&0)];
+            let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+            out.push(ALPHABET[(n >> 18) as usize & 63] as char);
+            out.push(ALPHABET[(n >> 12) as usize & 63] as char);
+            if chunk.len() > 1 {
+                out.push(ALPHABET[(n >> 6) as usize & 63] as char);
+            }
+            if chunk.len() > 2 {
+                out.push(ALPHABET[n as usize & 63] as char);
+            }
+        }
+        out
+    }
+
+    fn make_jwt(account_id: &str, email: &str) -> String {
+        let header = b64url(br#"{"alg":"none"}"#);
+        let payload = json!({
+            "https://api.openai.com/auth": {"chatgpt_account_id": account_id},
+            "email": email,
+        });
+        let body = b64url(&serde_json::to_vec(&payload).unwrap());
+        format!("{header}.{body}.sig")
+    }
+
+    // ---- helpers ----
+
+    #[test]
+    fn clamp_active_indices_matches_ts() {
+        let mut storage = AccountStorageV3::empty();
+        storage.active_index = 7;
+        clamp_active_indices(&mut storage, &MODEL_FAMILIES);
+        assert_eq!(storage.active_index, 0);
+        assert!(storage.active_index_by_family.as_ref().unwrap().is_empty());
+
+        let mut storage = AccountStorageV3::empty();
+        for i in 0..2 {
+            storage
+                .accounts
+                .push(AccountMetadataV3::new(format!("rt-{i}"), 1, 1));
+        }
+        storage.active_index = 9;
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(ModelFamily::Codex, Some(5));
+        storage.active_index_by_family = Some(by_family);
+        clamp_active_indices(&mut storage, &MODEL_FAMILIES);
+        assert_eq!(storage.active_index, 1);
+        let by_family = storage.active_index_by_family.as_ref().unwrap();
+        assert_eq!(by_family.get(ModelFamily::Codex), Some(1));
+        // Missing families fall back to the clamped activeIndex.
+        assert_eq!(by_family.get(ModelFamily::Gpt5_2), Some(1));
+    }
+
+    #[test]
+    fn is_flaggable_failure_matches_ts() {
+        let failure = |reason: Option<TokenFailureReason>,
+                       status: Option<i64>,
+                       message: Option<&str>| TokenFailure {
+            reason,
+            status_code: status,
+            message: message.map(str::to_string),
+        };
+        assert!(is_flaggable_failure(&failure(
+            Some(TokenFailureReason::MissingRefresh),
+            None,
+            None
+        )));
+        assert!(is_flaggable_failure(&failure(None, Some(401), None)));
+        assert!(!is_flaggable_failure(&failure(None, Some(500), None)));
+        assert!(!is_flaggable_failure(&failure(None, None, None)));
+        assert!(is_flaggable_failure(&failure(
+            None,
+            Some(400),
+            Some("INVALID_GRANT: bad token")
+        )));
+        assert!(is_flaggable_failure(&failure(
+            None,
+            Some(400),
+            Some("your Token Has Been Revoked")
+        )));
+        assert!(!is_flaggable_failure(&failure(
+            None,
+            Some(400),
+            Some("some other 400")
+        )));
+    }
+
+    // ---- engine ----
+
+    struct FakeDeps {
+        storage: Option<AccountStorageV3>,
+        flagged: FlaggedAccountStorageV1,
+        cli_cache: Option<CliCachedTokens>,
+        refresh_result: Option<TokenResult>,
+        probe_result: Option<Result<CodexQuotaSnapshot, String>>,
+        probe_unavailable: bool,
+        lines: Vec<String>,
+        saved_storage: Option<AccountStorageV3>,
+        saved_flagged: Option<FlaggedAccountStorageV1>,
+        invalidations: u32,
+        now: i64,
+    }
+
+    impl Default for FakeDeps {
+        fn default() -> Self {
+            Self {
+                storage: None,
+                flagged: FlaggedAccountStorageV1::empty(),
+                cli_cache: None,
+                refresh_result: None,
+                probe_result: None,
+                probe_unavailable: false,
+                lines: Vec::new(),
+                saved_storage: None,
+                saved_flagged: None,
+                invalidations: 0,
+                now: 0,
+            }
+        }
+    }
+
+    impl AccountCheckDeps for FakeDeps {
+        async fn hydrate_emails(
+            &mut self,
+            storage: Option<AccountStorageV3>,
+        ) -> Result<Option<AccountStorageV3>, CodexError> {
+            Ok(storage)
+        }
+        async fn load_accounts(&mut self) -> Result<Option<AccountStorageV3>, CodexError> {
+            Ok(self.storage.clone())
+        }
+        async fn load_flagged_accounts(&mut self) -> Result<FlaggedAccountStorageV1, CodexError> {
+            Ok(self.flagged.clone())
+        }
+        async fn lookup_codex_cli_tokens_by_email(
+            &mut self,
+            _email: Option<&str>,
+        ) -> Option<CliCachedTokens> {
+            self.cli_cache.clone()
+        }
+        async fn queued_refresh(&mut self, _refresh_token: &str) -> TokenResult {
+            self.refresh_result
+                .clone()
+                .unwrap_or(TokenResult::Failed(TokenFailure::default()))
+        }
+        async fn fetch_codex_quota_snapshot(
+            &mut self,
+            _account_id: &str,
+            _access_token: &str,
+        ) -> Result<CodexQuotaSnapshot, CodexError> {
+            if self.probe_unavailable {
+                return Err(CodexError::unavailable("Model unsupported"));
+            }
+            match self.probe_result.clone() {
+                Some(Ok(snapshot)) => Ok(snapshot),
+                Some(Err(message)) => Err(CodexError::new(message)),
+                None => Err(CodexError::new("no probe configured")),
+            }
+        }
+        async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError> {
+            self.saved_storage = Some(storage.clone());
+            Ok(())
+        }
+        async fn save_flagged_accounts(
+            &mut self,
+            storage: &FlaggedAccountStorageV1,
+        ) -> Result<(), CodexError> {
+            self.saved_flagged = Some(storage.clone());
+            Ok(())
+        }
+        fn invalidate_account_manager_cache(&mut self) {
+            self.invalidations += 1;
+        }
+        fn now_ms(&mut self) -> i64 {
+            self.now
+        }
+        fn show_line(&mut self, message: &str) {
+            self.lines.push(message.to_string());
+        }
+    }
+
+    fn storage_with_account(account: AccountMetadataV3) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(account);
+        storage
+    }
+
+    #[tokio::test]
+    async fn empty_pool_prints_no_accounts() {
+        let mut deps = FakeDeps {
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+        assert_eq!(deps.lines, vec!["\nNo accounts to check.\n"]);
+    }
+
+    #[tokio::test]
+    async fn disabled_accounts_are_counted_and_skipped() {
+        let mut account = AccountMetadataV3::new("rt-1", 1, 1);
+        account.enabled = Some(false);
+        account.account_label = Some("Work".to_string());
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+        assert_eq!(
+            deps.lines,
+            vec![
+                "\nChecking full account health for all accounts...\n",
+                "[1/1] Work: DISABLED",
+                "",
+                "Results: 0 ok, 0 error, 1 disabled",
+                "",
+            ]
+        );
+        assert!(deps.saved_storage.is_none());
+    }
+
+    #[tokio::test]
+    async fn deep_probe_prints_ok_with_id_suffix() {
+        let access = make_jwt("acc_1234567890", "user@example.com");
+        let mut account = AccountMetadataV3::new("rt-1", 1, 1);
+        account.email = Some("user@example.com".to_string());
+        account.access_token = Some(access);
+        account.expires_at = Some(999_999_999_999_999);
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+        assert_eq!(deps.lines[0], "\nChecking full account health for all accounts...\n");
+        assert_eq!(
+            deps.lines[1],
+            "[1/1] us***@***.com: OK (cached access) (id:567890)"
+        );
+        assert_eq!(deps.lines[3], "Results: 1 ok, 0 error, 0 disabled");
+        // accountId was adopted from the token.
+        let saved = deps.saved_storage.expect("storage saved");
+        assert_eq!(saved.accounts[0].account_id.as_deref(), Some("acc_1234567890"));
+        assert_eq!(
+            saved.accounts[0].account_id_source,
+            Some(AccountIdSource::Token)
+        );
+        assert_eq!(deps.invalidations, 1);
+    }
+
+    #[tokio::test]
+    async fn flaggable_refresh_failure_moves_account_to_flagged_pool() {
+        let account = AccountMetadataV3::new("rt-bad", 1, 1);
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            refresh_result: Some(TokenResult::Failed(TokenFailure {
+                reason: None,
+                status_code: Some(401),
+                message: Some("invalid refresh token".to_string()),
+            })),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+
+        assert_eq!(
+            deps.lines[1],
+            "[1/1] Account 1: ERROR (invalid refresh token)"
+        );
+        assert_eq!(deps.lines[3], "Results: 0 ok, 1 error, 0 disabled");
+        assert_eq!(
+            deps.lines[4],
+            "Moved 1 account(s) to flagged pool (invalid refresh token)."
+        );
+
+        let flagged = deps.saved_flagged.expect("flagged saved");
+        assert_eq!(flagged.accounts.len(), 1);
+        assert_eq!(flagged.accounts[0].refresh_token, "rt-bad");
+        assert_eq!(flagged.accounts[0].flagged_at, 1_000);
+        assert_eq!(
+            flagged.accounts[0].flagged_reason.as_deref(),
+            Some("token-invalid")
+        );
+        assert_eq!(
+            flagged.accounts[0].last_error.as_deref(),
+            Some("invalid refresh token")
+        );
+        // Account removed from the active pool.
+        let saved = deps.saved_storage.expect("storage saved");
+        assert!(saved.accounts.is_empty());
+    }
+
+    #[tokio::test]
+    async fn quota_mode_prints_snapshot_line_and_unavailable_note() {
+        let access = make_jwt("acc_1", "q@example.com");
+        let mut account = AccountMetadataV3::new("rt-1", 1, 1);
+        account.email = Some("q@example.com".to_string());
+        account.access_token = Some(access.clone());
+        account.expires_at = None; // missing expiry → treated as valid
+        let snapshot = CodexQuotaSnapshot {
+            status: 200,
+            plan_type: None,
+            active_limit: None,
+            primary: CodexQuotaWindow {
+                used_percent: Some(20.0),
+                window_minutes: Some(300),
+                reset_at_ms: None,
+            },
+            secondary: CodexQuotaWindow {
+                used_percent: Some(5.0),
+                window_minutes: Some(10080),
+                reset_at_ms: None,
+            },
+            model: "gpt-5.5".to_string(),
+        };
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account.clone())),
+            probe_result: Some(Ok(snapshot)),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(false, &mut deps).await.unwrap();
+        assert_eq!(deps.lines[0], "\nChecking quotas for all accounts...\n");
+        assert_eq!(deps.lines[1], "[1/1] q***@***.com: 5h 80% left, 7d 95% left");
+        assert_eq!(deps.lines[3], "Results: 1 ok, 0 error, 0 disabled");
+
+        // Unavailable → warning + ok + constant note + 4-part summary.
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            probe_unavailable: true,
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(false, &mut deps).await.unwrap();
+        assert_eq!(
+            deps.lines[1],
+            "[1/1] q***@***.com: Codex not available for this account"
+        );
+        assert_eq!(deps.lines[3], "Results: 1 ok, 1 warning, 0 error, 0 disabled");
+    }
+
+    #[tokio::test]
+    async fn quota_probe_errors_truncate_to_160_chars() {
+        let access = make_jwt("acc_1", "e@example.com");
+        let mut account = AccountMetadataV3::new("rt-1", 1, 1);
+        account.email = Some("e@example.com".to_string());
+        account.access_token = Some(access);
+        account.expires_at = None;
+        let long_message = "x".repeat(200);
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            probe_result: Some(Err(long_message)),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(false, &mut deps).await.unwrap();
+        let expected = format!("[1/1] e***@***.com: ERROR ({})", "x".repeat(160));
+        assert_eq!(deps.lines[1], expected);
+    }
+
+    #[tokio::test]
+    async fn cli_cache_path_syncs_tokens_into_storage() {
+        let cli_access = make_jwt("acc_cli", "cli@example.com");
+        let account = AccountMetadataV3::new("rt-1", 1, 1);
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            cli_cache: Some(CliCachedTokens {
+                access_token: cli_access.clone(),
+                refresh_token: None,
+                expires_at: Some(999_999_999_999_999.0),
+            }),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+        assert!(deps.lines[1].contains("OK (Codex CLI cache)"), "{}", deps.lines[1]);
+        let saved = deps.saved_storage.expect("storage saved");
+        assert_eq!(saved.accounts[0].access_token.as_deref(), Some(cli_access.as_str()));
+        assert_eq!(saved.accounts[0].email.as_deref(), Some("cli@example.com"));
+        assert_eq!(saved.accounts[0].account_id.as_deref(), Some("acc_cli"));
+    }
+
+    #[tokio::test]
+    async fn successful_refresh_updates_rotated_tokens() {
+        let new_access = make_jwt("acc_rot", "rot@example.com");
+        let account = AccountMetadataV3::new("rt-old", 1, 1);
+        let mut deps = FakeDeps {
+            storage: Some(storage_with_account(account)),
+            refresh_result: Some(TokenResult::Success(TokenSuccess {
+                access: new_access.clone(),
+                refresh: "rt-new".to_string(),
+                expires: 2_000_000,
+                id_token: None,
+                multi_account: None,
+            })),
+            now: 1_000,
+            ..FakeDeps::default()
+        };
+        run_runtime_account_check(true, &mut deps).await.unwrap();
+        let saved = deps.saved_storage.expect("storage saved");
+        assert_eq!(saved.accounts[0].refresh_token, "rt-new");
+        assert_eq!(saved.accounts[0].access_token.as_deref(), Some(new_access.as_str()));
+        assert_eq!(saved.accounts[0].expires_at, Some(2_000_000));
+        assert_eq!(saved.accounts[0].email.as_deref(), Some("rot@example.com"));
+    }
+}
diff --git a/crates/runtime/src/account_pool.rs b/crates/runtime/src/account_pool.rs
new file mode 100644
index 000000000..421fd262d
--- /dev/null
+++ b/crates/runtime/src/account_pool.rs
@@ -0,0 +1,454 @@
+//! Port of `lib/runtime/account-pool.ts` — `persistAccountPoolResults`:
+//! folds OAuth login results into accounts.json inside ONE storage
+//! transaction (spec 10 §17, workspace tracking #491/#512).
+//!
+//! DI absorption: the TS version injects `withAccountStorageTransaction`,
+//! `findMatchingAccountIndex` and the token helpers for tests; the Rust port
+//! calls `cma_storage` / `cma_core::token_utils` directly (tests run against
+//! a sandboxed real storage path).
+
+use cma_core::errors::CodexError;
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::schemas::account_storage::{
+    AccountIdSource, AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily, Workspace,
+};
+use cma_core::token_utils::{extract_account_email, extract_account_id, sanitize_email};
+use cma_core::utils::now_ms;
+use cma_storage::matching::{
+    AccountMatchOptions, AccountSelectionCandidate, find_matching_account_index,
+};
+use cma_storage::transactions::with_account_storage_transaction;
+
+use crate::account_selection::TokenSuccessWithAccount;
+
+/// Initial `currentWorkspaceIndex` for a NEW account: the workspace whose
+/// `id === accountId`, else the first with `enabled !== false`, else 0 —
+/// only when workspaces are non-empty.
+fn initial_workspace_index(
+    workspaces: Option<&[Workspace]>,
+    account_id: Option<&str>,
+) -> Option<i64> {
+    let workspaces = workspaces.filter(|w| !w.is_empty())?;
+    if let Some(account_id) = account_id
+        && let Some(matching) = workspaces.iter().position(|w| w.id == account_id)
+    {
+        return Some(matching as i64);
+    }
+    let first_enabled = workspaces.iter().position(|w| w.enabled);
+    Some(first_enabled.unwrap_or(0) as i64)
+}
+
+/// Re-resolve `currentWorkspaceIndex` for an EXISTING account after a
+/// workspace merge: previously-current id → `isDefault === true` → first
+/// enabled → 0; empty merged list keeps the old index.
+fn next_current_workspace_index(
+    merged: Option<&[Workspace]>,
+    current_workspace_id: Option<&str>,
+    existing_index: Option<i64>,
+) -> Option<i64> {
+    let Some(merged) = merged.filter(|w| !w.is_empty()) else {
+        return existing_index;
+    };
+    if let Some(current_id) = current_workspace_id
+        && let Some(matching) = merged.iter().position(|w| w.id == current_id)
+    {
+        return Some(matching as i64);
+    }
+    if let Some(default_index) = merged.iter().position(|w| w.is_default == Some(true)) {
+        return Some(default_index as i64);
+    }
+    let first_enabled = merged.iter().position(|w| w.enabled);
+    Some(first_enabled.unwrap_or(0) as i64)
+}
+
+/// TS `persistAccountPoolResults({results, replaceAll, ...})`.
+pub async fn persist_account_pool_results(
+    results: &[TokenSuccessWithAccount],
+    replace_all: bool,
+) -> Result<(), CodexError> {
+    if results.is_empty() {
+        return Ok(());
+    }
+
+    let results = results.to_vec();
+    with_account_storage_transaction(move |loaded_storage, persist| async move {
+        let now = now_ms();
+        let stored = if replace_all { None } else { loaded_storage };
+        let mut accounts: Vec<AccountMetadataV3> = stored
+            .as_ref()
+            .map(|s| s.accounts.clone())
+            .unwrap_or_default();
+
+        for result in &results {
+            let account_id = result
+                .account_id_override
+                .clone()
+                .or_else(|| extract_account_id(Some(&result.tokens.access)));
+            let account_id_source: Option<AccountIdSource> = if account_id.is_some() {
+                result.account_id_source.or(Some(
+                    if result.account_id_override.is_some() {
+                        AccountIdSource::Manual
+                    } else {
+                        AccountIdSource::Token
+                    },
+                ))
+            } else {
+                None
+            };
+            let account_label = result.account_label.clone();
+            let account_email = sanitize_email(
+                extract_account_email(
+                    Some(&result.tokens.access),
+                    result.tokens.id_token.as_deref(),
+                )
+                .as_deref(),
+            );
+
+            let candidate = AccountSelectionCandidate {
+                account_id: account_id.clone(),
+                email: account_email.clone(),
+                refresh_token: Some(result.tokens.refresh.clone()),
+            };
+            let existing_index = find_matching_account_index(
+                &accounts,
+                &candidate,
+                AccountMatchOptions {
+                    allow_unique_account_id_fallback_without_email: true,
+                },
+            );
+
+            let Some(existing_index) = existing_index else {
+                // New account.
+                let current_workspace_index = initial_workspace_index(
+                    result.workspaces.as_deref(),
+                    account_id.as_deref(),
+                );
+                accounts.push(AccountMetadataV3 {
+                    account_id,
+                    account_id_source,
+                    account_label,
+                    email: account_email,
+                    refresh_token: result.tokens.refresh.clone(),
+                    access_token: Some(result.tokens.access.clone()),
+                    expires_at: Some(result.tokens.expires),
+                    enabled: None,
+                    added_at: now,
+                    last_used: now,
+                    last_switch_reason: None,
+                    rate_limit_reset_times: None,
+                    cooling_down_until: None,
+                    cooldown_reason: None,
+                    workspaces: result.workspaces.clone(),
+                    current_workspace_index,
+                });
+                continue;
+            };
+
+            let existing = accounts[existing_index].clone();
+
+            let next_email = account_email.or_else(|| sanitize_email(existing.email.as_deref()));
+            let next_account_id = account_id.clone().or_else(|| existing.account_id.clone());
+            let next_account_id_source = if account_id.is_some() {
+                account_id_source.or(existing.account_id_source)
+            } else {
+                existing.account_id_source
+            };
+            let next_account_label = account_label.or_else(|| existing.account_label.clone());
+
+            // Workspace merge (#491/#512): the new list wins, but per-
+            // workspace enabled/disabledAt carry over by id.
+            let merged_workspaces: Option<Vec<Workspace>> = match result.workspaces.as_ref() {
+                Some(new_workspaces) => Some(
+                    new_workspaces
+                        .iter()
+                        .map(|new_ws| {
+                            match existing
+                                .workspaces
+                                .as_ref()
+                                .and_then(|old| old.iter().find(|w| w.id == new_ws.id))
+                            {
+                                Some(existing_ws) => Workspace {
+                                    enabled: existing_ws.enabled,
+                                    disabled_at: existing_ws.disabled_at,
+                                    ..new_ws.clone()
+                                },
+                                None => new_ws.clone(),
+                            }
+                        })
+                        .collect(),
+                ),
+                None => existing.workspaces.clone(),
+            };
+
+            let current_workspace_id: Option<String> = existing.workspaces.as_ref().and_then(
+                |workspaces| {
+                    let index = existing.current_workspace_index.unwrap_or(0);
+                    usize::try_from(index)
+                        .ok()
+                        .and_then(|i| workspaces.get(i))
+                        .map(|w| w.id.clone())
+                },
+            );
+            let next_current_workspace_index = next_current_workspace_index(
+                merged_workspaces.as_deref(),
+                current_workspace_id.as_deref(),
+                existing.current_workspace_index,
+            );
+
+            accounts[existing_index] = AccountMetadataV3 {
+                account_id: next_account_id,
+                account_id_source: next_account_id_source,
+                account_label: next_account_label,
+                email: next_email,
+                refresh_token: result.tokens.refresh.clone(),
+                access_token: Some(result.tokens.access.clone()),
+                expires_at: Some(result.tokens.expires),
+                last_used: now,
+                workspaces: merged_workspaces,
+                current_workspace_index: next_current_workspace_index,
+                ..existing
+            };
+        }
+
+        if accounts.is_empty() {
+            return Ok(());
+        }
+
+        let active_index: i64 = if replace_all {
+            0
+        } else {
+            stored.as_ref().map(|s| s.active_index).unwrap_or(0)
+        };
+        let clamped_active_index = active_index.clamp(0, accounts.len() as i64 - 1);
+
+        let mut active_index_by_family = ActiveIndexByFamily::default();
+        for family in MODEL_FAMILIES {
+            let stored_family_index = stored
+                .as_ref()
+                .and_then(|s| s.active_index_by_family.as_ref())
+                .and_then(|map| map.get(family));
+            let raw_family_index = if replace_all {
+                0
+            } else {
+                stored_family_index.unwrap_or(clamped_active_index)
+            };
+            active_index_by_family.set(
+                family,
+                Some(raw_family_index.clamp(0, accounts.len() as i64 - 1)),
+            );
+        }
+
+        persist
+            .persist(&AccountStorageV3 {
+                version: Default::default(),
+                accounts,
+                active_index: clamped_active_index,
+                active_index_by_family: Some(active_index_by_family),
+                pinned_account_index: None,
+                affinity_generation: None,
+            })
+            .await
+    })
+    .await
+}
+
+// =============================================================================
+// Tests — ported from test/account-pool.test.ts (fold semantics)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenSuccess;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serde_json::json;
+    use serial_test::serial;
+
+    /// Minimal base64url (no padding) — no base64 dev-dependency here.
+    fn b64url(bytes: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut out = String::new();
+        for chunk in bytes.chunks(3) {
+            let b = [chunk[0], *chunk.get(1).unwrap_or(&0), *chunk.get(2).unwrap_or(&0)];
+            let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+            out.push(ALPHABET[(n >> 18) as usize & 63] as char);
+            out.push(ALPHABET[(n >> 12) as usize & 63] as char);
+            if chunk.len() > 1 {
+                out.push(ALPHABET[(n >> 6) as usize & 63] as char);
+            }
+            if chunk.len() > 2 {
+                out.push(ALPHABET[n as usize & 63] as char);
+            }
+        }
+        out
+    }
+
+    fn make_jwt(account_id: &str, email: &str) -> String {
+        let header = b64url(br#"{"alg":"none"}"#);
+        let payload = json!({
+            "https://api.openai.com/auth": {"chatgpt_account_id": account_id},
+            "email": email,
+        });
+        let body = b64url(&serde_json::to_vec(&payload).unwrap());
+        format!("{header}.{body}.sig")
+    }
+
+    fn result_for(account_id: &str, email: &str, refresh: &str) -> TokenSuccessWithAccount {
+        TokenSuccessWithAccount::plain(TokenSuccess {
+            access: make_jwt(account_id, email),
+            refresh: refresh.to_string(),
+            expires: 9_999_999_999_999,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    async fn load_storage() -> AccountStorageV3 {
+        cma_storage::load::load_accounts()
+            .await
+            .expect("storage present")
+            .storage
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn empty_results_are_a_no_op() {
+        let _sandbox = EnvSandbox::new();
+        persist_account_pool_results(&[], false).await.unwrap();
+        // No transaction ran → no accounts file was ever written.
+        let path = cma_storage::facade::get_storage_path();
+        assert!(!std::path::Path::new(&path).exists(), "unexpected write: {path}");
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn inserts_new_accounts_and_seeds_family_indexes() {
+        let _sandbox = EnvSandbox::new();
+        let results = vec![
+            result_for("acc_alpha", "a@example.com", "rt-a"),
+            result_for("acc_beta", "b@example.com", "rt-b"),
+        ];
+        persist_account_pool_results(&results, false).await.unwrap();
+
+        let storage = load_storage().await;
+        assert_eq!(storage.accounts.len(), 2);
+        assert_eq!(storage.accounts[0].email.as_deref(), Some("a@example.com"));
+        assert_eq!(storage.accounts[0].account_id.as_deref(), Some("acc_alpha"));
+        assert_eq!(
+            storage.accounts[0].account_id_source,
+            Some(AccountIdSource::Token)
+        );
+        assert_eq!(storage.active_index, 0);
+        let by_family = storage.active_index_by_family.as_ref().expect("families");
+        for (_, value) in by_family.iter() {
+            assert_eq!(value, Some(0));
+        }
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn updates_existing_account_by_identity_and_keeps_fallbacks() {
+        let _sandbox = EnvSandbox::new();
+        let mut first = result_for("acc_alpha", "a@example.com", "rt-old");
+        first.account_label = Some("Alpha".to_string());
+        persist_account_pool_results(&[first], false).await.unwrap();
+
+        // Same identity, new refresh token, no label → label falls back.
+        let update = result_for("acc_alpha", "a@example.com", "rt-new");
+        persist_account_pool_results(&[update], false).await.unwrap();
+
+        let storage = load_storage().await;
+        assert_eq!(storage.accounts.len(), 1);
+        assert_eq!(storage.accounts[0].refresh_token, "rt-new");
+        assert_eq!(storage.accounts[0].account_label.as_deref(), Some("Alpha"));
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn replace_all_resets_pool_and_indexes() {
+        let _sandbox = EnvSandbox::new();
+        let results = vec![
+            result_for("acc_alpha", "a@example.com", "rt-a"),
+            result_for("acc_beta", "b@example.com", "rt-b"),
+        ];
+        persist_account_pool_results(&results, false).await.unwrap();
+
+        let replacement = vec![result_for("acc_gamma", "c@example.com", "rt-c")];
+        persist_account_pool_results(&replacement, true).await.unwrap();
+
+        let storage = load_storage().await;
+        assert_eq!(storage.accounts.len(), 1);
+        assert_eq!(storage.accounts[0].account_id.as_deref(), Some("acc_gamma"));
+        assert_eq!(storage.active_index, 0);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn workspace_merge_carries_enabled_state_and_recomputes_index() {
+        let _sandbox = EnvSandbox::new();
+        let mut first = result_for("acc_ws", "w@example.com", "rt-w");
+        first.workspaces = Some(vec![
+            Workspace {
+                id: "ws-1".into(),
+                name: Some("One".into()),
+                enabled: true,
+                disabled_at: None,
+                is_default: None,
+            },
+            Workspace {
+                id: "acc_ws".into(),
+                name: Some("Personal".into()),
+                enabled: true,
+                disabled_at: None,
+                is_default: Some(true),
+            },
+        ]);
+        persist_account_pool_results(&[first], false).await.unwrap();
+
+        let storage = load_storage().await;
+        // New account: currentWorkspaceIndex = workspace whose id == accountId.
+        assert_eq!(storage.accounts[0].current_workspace_index, Some(1));
+
+        // Disable ws-1 on disk, then re-login with a fresh list: enabled
+        // carries over by id, and the previously-current workspace id keeps
+        // the index pointing at it.
+        let mut mutated = storage.clone();
+        if let Some(workspaces) = mutated.accounts[0].workspaces.as_mut() {
+            workspaces[0].enabled = false;
+            workspaces[0].disabled_at = Some(123);
+        }
+        cma_storage::save::save_accounts(&mutated).await.unwrap();
+
+        let mut second = result_for("acc_ws", "w@example.com", "rt-w");
+        second.workspaces = Some(vec![
+            Workspace {
+                id: "acc_ws".into(),
+                name: Some("Personal".into()),
+                enabled: true,
+                disabled_at: None,
+                is_default: Some(true),
+            },
+            Workspace {
+                id: "ws-1".into(),
+                name: Some("One (renamed)".into()),
+                enabled: true,
+                disabled_at: None,
+                is_default: None,
+            },
+        ]);
+        persist_account_pool_results(&[second], false).await.unwrap();
+
+        let storage = load_storage().await;
+        let account = &storage.accounts[0];
+        let workspaces = account.workspaces.as_ref().expect("workspaces");
+        assert_eq!(workspaces.len(), 2);
+        // ws-1 kept its disabled state despite the new list saying enabled.
+        let ws1 = workspaces.iter().find(|w| w.id == "ws-1").unwrap();
+        assert!(!ws1.enabled);
+        assert_eq!(ws1.disabled_at, Some(123));
+        assert_eq!(ws1.name.as_deref(), Some("One (renamed)"));
+        // Previously-current workspace (acc_ws) followed to its new position.
+        assert_eq!(account.current_workspace_index, Some(0));
+    }
+}
diff --git a/crates/runtime/src/account_selection.rs b/crates/runtime/src/account_selection.rs
new file mode 100644
index 000000000..f43eda1f6
--- /dev/null
+++ b/crates/runtime/src/account_selection.rs
@@ -0,0 +1,578 @@
+//! Port of `lib/runtime/account-selection.ts` (+ absorbed
+//! `lib/runtime/account-select-event.ts`) — login-time account selection and
+//! the FIFO-serialized `account.select` event mutation (spec 10 §18–19).
+//!
+//! Type note (spec 10 gotcha 18): TS has TWO distinct `TokenSuccessWithAccount`
+//! types with the same name — a generic one here and a concrete one in
+//! `account-pool.ts`. The Rust port unifies them into the single concrete
+//! [`TokenSuccessWithAccount`] below (over `cma_core` `TokenSuccess`, which
+//! already carries `idToken`/`multiAccount`).
+
+use cma_core::errors::CodexError;
+use cma_core::model_family::{MODEL_FAMILIES, ModelFamily};
+use cma_core::schemas::account_storage::{
+    AccountIdSource, AccountStorageV3, SwitchReason, Workspace,
+};
+use cma_core::schemas::token::TokenSuccess;
+use cma_core::token_utils::{
+    AccountIdCandidate, get_account_id_candidates, select_best_account_candidate,
+};
+use cma_core::utils::now_ms;
+use serde_json::Value;
+
+/// TS `TokenSuccessWithAccount` — a successful token exchange plus the
+/// account-identity extras resolved at login time.
+#[derive(Clone, Debug, PartialEq)]
+pub struct TokenSuccessWithAccount {
+    pub tokens: TokenSuccess,
+    pub account_id_override: Option<String>,
+    pub account_id_source: Option<AccountIdSource>,
+    pub account_label: Option<String>,
+    pub workspaces: Option<Vec<Workspace>>,
+}
+
+impl TokenSuccessWithAccount {
+    /// Wrap plain tokens with no extras (the TS "return tokens untouched"
+    /// arm).
+    pub fn plain(tokens: TokenSuccess) -> Self {
+        Self {
+            tokens,
+            account_id_override: None,
+            account_id_source: None,
+            account_label: None,
+            workspaces: None,
+        }
+    }
+}
+
+/// Dependencies for [`resolve_account_selection`].
+///
+/// The TS version also injects `getAccountIdCandidates` /
+/// `selectBestAccountCandidate`; those are pure functions in
+/// `cma_core::token_utils` and are called directly (DI-shim absorption per
+/// the architecture).
+pub struct ResolveAccountSelectionDeps<'a> {
+    /// Caller passes `process.env.CODEX_AUTH_ACCOUNT_ID`.
+    pub env_account_id: Option<String>,
+    pub log_info: &'a mut dyn FnMut(&str),
+}
+
+/// TS `resolveAccountSelection(tokens, deps)`.
+pub fn resolve_account_selection(
+    tokens: TokenSuccess,
+    deps: &mut ResolveAccountSelectionDeps<'_>,
+) -> TokenSuccessWithAccount {
+    let override_id = deps
+        .env_account_id
+        .as_deref()
+        .unwrap_or("")
+        .trim()
+        .to_string();
+    if !override_id.is_empty() {
+        let suffix: String = if override_id.chars().count() > 6 {
+            let chars: Vec<char> = override_id.chars().collect();
+            chars[chars.len() - 6..].iter().collect()
+        } else {
+            override_id.clone()
+        };
+        (deps.log_info)(&format!(
+            "Using account override from CODEX_AUTH_ACCOUNT_ID (id:{suffix})."
+        ));
+        return TokenSuccessWithAccount {
+            account_id_override: Some(override_id),
+            account_id_source: Some(AccountIdSource::Manual),
+            account_label: Some(format!("Override [id:{suffix}]")),
+            workspaces: None,
+            tokens,
+        };
+    }
+
+    let candidates = get_account_id_candidates(Some(&tokens.access), tokens.id_token.as_deref());
+    if candidates.is_empty() {
+        return TokenSuccessWithAccount::plain(tokens);
+    }
+
+    let workspaces: Vec<Workspace> = candidates
+        .iter()
+        .map(|candidate| Workspace {
+            id: candidate.account_id.clone(),
+            name: Some(candidate.label.clone()),
+            enabled: true,
+            disabled_at: None,
+            is_default: candidate.is_default,
+        })
+        .collect();
+
+    if candidates.len() == 1 {
+        let candidate = &candidates[0];
+        return TokenSuccessWithAccount {
+            account_id_override: Some(candidate.account_id.clone()),
+            account_id_source: Some(candidate.source),
+            account_label: Some(candidate.label.clone()),
+            workspaces: Some(workspaces),
+            tokens,
+        };
+    }
+
+    let Some(choice) = select_best_account_candidate(&candidates) else {
+        return TokenSuccessWithAccount::plain(tokens);
+    };
+    let choice: AccountIdCandidate = choice.clone();
+
+    TokenSuccessWithAccount {
+        account_id_override: Some(choice.account_id),
+        account_id_source: Some(choice.source),
+        account_label: Some(choice.label),
+        workspaces: Some(workspaces),
+        tokens,
+    }
+}
+
+/// Runtime wiring: env `CODEX_AUTH_ACCOUNT_ID` + core candidate helpers
+/// (the closure the TS manual-oauth-flow overload builds).
+pub fn resolve_account_selection_runtime(
+    tokens: TokenSuccess,
+    log_info: &mut dyn FnMut(&str),
+) -> TokenSuccessWithAccount {
+    let env_account_id = std::env::var("CODEX_AUTH_ACCOUNT_ID").ok();
+    resolve_account_selection(
+        tokens,
+        &mut ResolveAccountSelectionDeps {
+            env_account_id,
+            log_info,
+        },
+    )
+}
+
+// =============================================================================
+// account-select-event.ts — FIFO-serialized select-event mutation
+// =============================================================================
+
+/// The runtime event shape (`{type, properties?}`).
+#[derive(Clone, Debug, PartialEq)]
+pub struct RuntimeEvent {
+    pub event_type: String,
+    pub properties: Option<Value>,
+}
+
+/// Dependencies of [`handle_account_select_event`] (the TS `input` object
+/// minus the event itself).
+#[allow(async_fn_in_trait)]
+pub trait AccountSelectEventDeps {
+    fn provider_id(&self) -> &str;
+    async fn load_accounts(&mut self) -> Result<Option<AccountStorageV3>, CodexError>;
+    async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError>;
+    fn model_families(&self) -> &[ModelFamily] {
+        &MODEL_FAMILIES
+    }
+    /// TS `getCachedAccountManager() !== null`.
+    fn has_cached_account_manager(&self) -> bool;
+    async fn sync_codex_cli_active_selection_for_index(
+        &mut self,
+        index: usize,
+    ) -> Result<(), CodexError>;
+    fn set_last_codex_cli_active_sync_index(&mut self, index: usize);
+    async fn reload_account_manager_from_disk(&mut self) -> Result<(), CodexError>;
+    async fn show_toast(&mut self, message: &str, variant: &str) -> Result<(), CodexError>;
+}
+
+/// Module-level FIFO write queue (TS `serializeAccountSelectMutation`) —
+/// concurrent select events must not interleave load-modify-save.
+static ACCOUNT_SELECT_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+fn event_index(properties: Option<&Value>) -> IndexOutcome {
+    let Some(props) = properties.filter(|p| p.is_object()) else {
+        // Non-object properties behave like `{}` → rawIndex undefined.
+        return IndexOutcome::NotInteger;
+    };
+    // `props.index ?? props.accountIndex` — null/undefined fall through.
+    let raw = match props.get("index").filter(|v| !v.is_null()) {
+        Some(value) => Some(value),
+        None => props.get("accountIndex").filter(|v| !v.is_null()),
+    };
+    let Some(raw) = raw else {
+        return IndexOutcome::NotInteger;
+    };
+    // `Number.isInteger(rawIndex)` — a JSON number with an integral value.
+    match raw.as_f64() {
+        Some(v) if v.is_finite() && v.fract() == 0.0 => IndexOutcome::Index(v as i64),
+        _ => IndexOutcome::NotInteger,
+    }
+}
+
+enum IndexOutcome {
+    Index(i64),
+    NotInteger,
+}
+
+/// TS `handleAccountSelectEvent(input)` — `Ok(true)` = event consumed.
+pub async fn handle_account_select_event<D: AccountSelectEventDeps>(
+    event: &RuntimeEvent,
+    deps: &mut D,
+) -> Result<bool, CodexError> {
+    if event.event_type != "account.select" && event.event_type != "openai.account.select" {
+        return Ok(false);
+    }
+
+    let props = event.properties.as_ref();
+    let provider = props
+        .and_then(|p| p.get("provider"))
+        .and_then(Value::as_str);
+    if let Some(provider) = provider
+        && provider != "openai"
+        && provider != deps.provider_id()
+    {
+        return Ok(false);
+    }
+
+    let index = match event_index(props) {
+        // Bad index → consumed (true) without mutation (gotcha 21).
+        IndexOutcome::NotInteger => return Ok(true),
+        IndexOutcome::Index(index) => index,
+    };
+
+    let _guard = ACCOUNT_SELECT_QUEUE.lock().await;
+
+    let Some(mut storage) = deps.load_accounts().await? else {
+        return Ok(true);
+    };
+    if index < 0 || index as usize >= storage.accounts.len() {
+        return Ok(true);
+    }
+    let index = index as usize;
+
+    let now = now_ms();
+    if let Some(account) = storage.accounts.get_mut(index) {
+        account.last_used = now;
+        account.last_switch_reason = Some(SwitchReason::Rotation);
+    }
+    storage.active_index = index as i64;
+    let mut by_family = storage.active_index_by_family.take().unwrap_or_default();
+    for family in deps.model_families() {
+        by_family.set(*family, Some(index as i64));
+    }
+    storage.active_index_by_family = Some(by_family);
+
+    deps.save_accounts(&storage).await?;
+
+    if deps.has_cached_account_manager() {
+        deps.sync_codex_cli_active_selection_for_index(index).await?;
+    }
+    deps.set_last_codex_cli_active_sync_index(index);
+
+    if deps.has_cached_account_manager() {
+        deps.reload_account_manager_from_disk().await?;
+    }
+
+    deps.show_toast(&format!("Switched to account {}", index + 1), "info")
+        .await?;
+    Ok(true)
+}
+
+// =============================================================================
+// Tests — ported from test/account-selection.test.ts +
+// test/account-select-event.test.ts (highest-value assertions)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// Minimal base64url (no padding) — no base64 dev-dependency here.
+    fn b64url(bytes: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut out = String::new();
+        for chunk in bytes.chunks(3) {
+            let b = [chunk[0], *chunk.get(1).unwrap_or(&0), *chunk.get(2).unwrap_or(&0)];
+            let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+            out.push(ALPHABET[(n >> 18) as usize & 63] as char);
+            out.push(ALPHABET[(n >> 12) as usize & 63] as char);
+            if chunk.len() > 1 {
+                out.push(ALPHABET[(n >> 6) as usize & 63] as char);
+            }
+            if chunk.len() > 2 {
+                out.push(ALPHABET[n as usize & 63] as char);
+            }
+        }
+        out
+    }
+
+    fn make_jwt(payload: &Value) -> String {
+        let header = b64url(br#"{"alg":"none"}"#);
+        let body = b64url(&serde_json::to_vec(payload).unwrap());
+        format!("{header}.{body}.sig")
+    }
+
+    fn tokens_with_account(account_id: &str) -> TokenSuccess {
+        let access = make_jwt(&json!({
+            "https://api.openai.com/auth": {"chatgpt_account_id": account_id}
+        }));
+        TokenSuccess {
+            access,
+            refresh: "rt".to_string(),
+            expires: 9_999_999_999_999,
+            id_token: None,
+            multi_account: None,
+        }
+    }
+
+    fn plain_tokens() -> TokenSuccess {
+        TokenSuccess {
+            access: "not-a-jwt".to_string(),
+            refresh: "rt".to_string(),
+            expires: 9_999_999_999_999,
+            id_token: None,
+            multi_account: None,
+        }
+    }
+
+    #[test]
+    fn env_override_wins_and_logs_suffix() {
+        let mut logged = Vec::new();
+        let mut log = |m: &str| logged.push(m.to_string());
+        let result = resolve_account_selection(
+            plain_tokens(),
+            &mut ResolveAccountSelectionDeps {
+                env_account_id: Some("  acc_1234567890  ".to_string()),
+                log_info: &mut log,
+            },
+        );
+        assert_eq!(result.account_id_override.as_deref(), Some("acc_1234567890"));
+        assert_eq!(result.account_id_source, Some(AccountIdSource::Manual));
+        assert_eq!(result.account_label.as_deref(), Some("Override [id:567890]"));
+        assert!(result.workspaces.is_none());
+        assert_eq!(
+            logged,
+            vec!["Using account override from CODEX_AUTH_ACCOUNT_ID (id:567890)."]
+        );
+
+        // Short override uses the whole id as suffix.
+        let mut log = |_: &str| {};
+        let result = resolve_account_selection(
+            plain_tokens(),
+            &mut ResolveAccountSelectionDeps {
+                env_account_id: Some("abc".to_string()),
+                log_info: &mut log,
+            },
+        );
+        assert_eq!(result.account_label.as_deref(), Some("Override [id:abc]"));
+    }
+
+    #[test]
+    fn no_candidates_returns_tokens_untouched() {
+        let mut log = |_: &str| {};
+        let result = resolve_account_selection(
+            plain_tokens(),
+            &mut ResolveAccountSelectionDeps {
+                env_account_id: None,
+                log_info: &mut log,
+            },
+        );
+        assert_eq!(result, TokenSuccessWithAccount::plain(plain_tokens()));
+    }
+
+    #[test]
+    fn single_candidate_selected_with_workspaces() {
+        let mut log = |_: &str| {};
+        let result = resolve_account_selection(
+            tokens_with_account("acc_workspace1"),
+            &mut ResolveAccountSelectionDeps {
+                env_account_id: None,
+                log_info: &mut log,
+            },
+        );
+        assert_eq!(result.account_id_override.as_deref(), Some("acc_workspace1"));
+        assert_eq!(result.account_id_source, Some(AccountIdSource::Token));
+        let workspaces = result.workspaces.expect("workspaces");
+        assert_eq!(workspaces.len(), 1);
+        assert_eq!(workspaces[0].id, "acc_workspace1");
+        assert!(workspaces[0].enabled);
+    }
+
+    // ---- account-select-event ----
+
+    struct FakeDeps {
+        storage: Option<AccountStorageV3>,
+        saved: Option<AccountStorageV3>,
+        has_manager: bool,
+        synced: Vec<usize>,
+        last_sync_index: Option<usize>,
+        reloads: usize,
+        toasts: Vec<(String, String)>,
+    }
+
+    impl FakeDeps {
+        fn with_accounts(count: usize) -> Self {
+            let mut storage = AccountStorageV3::empty();
+            for i in 0..count {
+                storage.accounts.push(
+                    cma_core::schemas::account_storage::AccountMetadataV3::new(
+                        format!("rt-{i}"),
+                        1,
+                        1,
+                    ),
+                );
+            }
+            Self {
+                storage: Some(storage),
+                saved: None,
+                has_manager: true,
+                synced: Vec::new(),
+                last_sync_index: None,
+                reloads: 0,
+                toasts: Vec::new(),
+            }
+        }
+    }
+
+    impl AccountSelectEventDeps for FakeDeps {
+        fn provider_id(&self) -> &str {
+            "custom-provider"
+        }
+        async fn load_accounts(&mut self) -> Result<Option<AccountStorageV3>, CodexError> {
+            Ok(self.storage.clone())
+        }
+        async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError> {
+            self.saved = Some(storage.clone());
+            Ok(())
+        }
+        fn has_cached_account_manager(&self) -> bool {
+            self.has_manager
+        }
+        async fn sync_codex_cli_active_selection_for_index(
+            &mut self,
+            index: usize,
+        ) -> Result<(), CodexError> {
+            self.synced.push(index);
+            Ok(())
+        }
+        fn set_last_codex_cli_active_sync_index(&mut self, index: usize) {
+            self.last_sync_index = Some(index);
+        }
+        async fn reload_account_manager_from_disk(&mut self) -> Result<(), CodexError> {
+            self.reloads += 1;
+            Ok(())
+        }
+        async fn show_toast(&mut self, message: &str, variant: &str) -> Result<(), CodexError> {
+            self.toasts.push((message.to_string(), variant.to_string()));
+            Ok(())
+        }
+    }
+
+    fn event(event_type: &str, properties: Value) -> RuntimeEvent {
+        RuntimeEvent {
+            event_type: event_type.to_string(),
+            properties: Some(properties),
+        }
+    }
+
+    #[tokio::test]
+    async fn ignores_unknown_event_types_and_foreign_providers() {
+        let mut deps = FakeDeps::with_accounts(2);
+        let consumed = handle_account_select_event(
+            &event("other.event", json!({"index": 1})),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(!consumed);
+
+        let consumed = handle_account_select_event(
+            &event("account.select", json!({"index": 1, "provider": "anthropic"})),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(!consumed);
+        assert!(deps.saved.is_none());
+
+        // Matching custom provider id is accepted.
+        let consumed = handle_account_select_event(
+            &event(
+                "account.select",
+                json!({"index": 1, "provider": "custom-provider"}),
+            ),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(consumed);
+        assert!(deps.saved.is_some());
+    }
+
+    #[tokio::test]
+    async fn bad_index_consumes_without_mutation() {
+        let mut deps = FakeDeps::with_accounts(2);
+        for props in [
+            json!({}),
+            json!({"index": "1"}),
+            json!({"index": 1.5}),
+            json!({"index": null}),
+        ] {
+            let consumed =
+                handle_account_select_event(&event("account.select", props), &mut deps)
+                    .await
+                    .unwrap();
+            assert!(consumed);
+        }
+        // Out of range → consumed, no save.
+        let consumed = handle_account_select_event(
+            &event("openai.account.select", json!({"index": 9})),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(consumed);
+        assert!(deps.saved.is_none());
+        assert!(deps.toasts.is_empty());
+    }
+
+    #[tokio::test]
+    async fn valid_select_mutates_saves_syncs_and_toasts() {
+        let mut deps = FakeDeps::with_accounts(3);
+        let consumed = handle_account_select_event(
+            &event("account.select", json!({"accountIndex": 1, "provider": "openai"})),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(consumed);
+
+        let saved = deps.saved.as_ref().expect("saved");
+        assert_eq!(saved.active_index, 1);
+        let by_family = saved.active_index_by_family.as_ref().expect("families");
+        for (family, value) in by_family.iter() {
+            assert_eq!(value, Some(1), "family {family:?}");
+        }
+        assert_eq!(
+            saved.accounts[1].last_switch_reason,
+            Some(SwitchReason::Rotation)
+        );
+        assert_eq!(deps.synced, vec![1]);
+        assert_eq!(deps.last_sync_index, Some(1));
+        assert_eq!(deps.reloads, 1);
+        assert_eq!(
+            deps.toasts,
+            vec![("Switched to account 2".to_string(), "info".to_string())]
+        );
+    }
+
+    #[tokio::test]
+    async fn no_cached_manager_skips_sync_and_reload() {
+        let mut deps = FakeDeps::with_accounts(2);
+        deps.has_manager = false;
+        let consumed = handle_account_select_event(
+            &event("account.select", json!({"index": 0})),
+            &mut deps,
+        )
+        .await
+        .unwrap();
+        assert!(consumed);
+        assert!(deps.synced.is_empty());
+        assert_eq!(deps.reloads, 0);
+        // setLastCodexCliActiveSyncIndex still always fires.
+        assert_eq!(deps.last_sync_index, Some(0));
+    }
+}
diff --git a/crates/runtime/src/account_state.rs b/crates/runtime/src/account_state.rs
new file mode 100644
index 000000000..af7f05216
--- /dev/null
+++ b/crates/runtime/src/account_state.rs
@@ -0,0 +1,7 @@
+//! Port of `lib/runtime/account-state.ts` — a pure re-export shim over
+//! `account-status.ts` (spec 10 §22). Kept as its own module for 1:1 file
+//! parity with the TS tree.
+
+pub use crate::account_status::{
+    format_rate_limit_entry, get_rate_limit_reset_time_for_family, resolve_active_index,
+};
diff --git a/crates/runtime/src/account_status.rs b/crates/runtime/src/account_status.rs
new file mode 100644
index 000000000..12478b477
--- /dev/null
+++ b/crates/runtime/src/account_status.rs
@@ -0,0 +1,157 @@
+//! Port of `lib/runtime/account-status.ts` (spec 10 §22) — active-index
+//! resolution and per-family rate-limit reset lookups.
+//!
+//! Per-model keys look like `codex:gpt-5.4`; a key matches a family when it
+//! is exactly the family literal or starts with `"{family}:"`.
+
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::{AccountStorageV3, RateLimitStateV3};
+
+/// TS `resolveActiveIndex(storage, family = "codex")` — 0 accounts → 0;
+/// candidate = `activeIndexByFamily[family] ?? activeIndex`; non-finite → 0;
+/// clamp `[0, len-1]`.
+pub fn resolve_active_index(storage: &AccountStorageV3, family: ModelFamily) -> usize {
+    let total = storage.accounts.len();
+    if total == 0 {
+        return 0;
+    }
+    let raw_candidate = storage
+        .active_index_by_family
+        .as_ref()
+        .and_then(|map| map.get(family))
+        .unwrap_or(storage.active_index);
+    let raw = raw_candidate.max(0) as usize;
+    raw.min(total - 1)
+}
+
+/// TS `getRateLimitResetTimeForFamily(account, now, family)` — min over
+/// entries with numeric value `> now` whose key is exactly `family` or
+/// starts with `"{family}:"`; none → `None`.
+pub fn get_rate_limit_reset_time_for_family(
+    rate_limit_reset_times: Option<&RateLimitStateV3>,
+    now: i64,
+    family: ModelFamily,
+) -> Option<i64> {
+    let times = rate_limit_reset_times?;
+    let family_key = family.as_str();
+    let prefix = format!("{family_key}:");
+
+    let mut min_reset: Option<i64> = None;
+    for (key, value) in times.iter() {
+        if value <= now {
+            continue;
+        }
+        if key != family_key && !key.starts_with(&prefix) {
+            continue;
+        }
+        min_reset = Some(match min_reset {
+            Some(current) if current <= value => current,
+            _ => value,
+        });
+    }
+    min_reset
+}
+
+/// TS `formatRateLimitEntry(account, now, formatWaitTime, family = "codex")`
+/// — `None` when no future reset; else `"resets in {formatWaitTime(delta)}"`.
+pub fn format_rate_limit_entry(
+    rate_limit_reset_times: Option<&RateLimitStateV3>,
+    now: i64,
+    format_wait_time: &dyn Fn(i64) -> String,
+    family: ModelFamily,
+) -> Option<String> {
+    let reset_at = get_rate_limit_reset_time_for_family(rate_limit_reset_times, now, family)?;
+    let remaining = reset_at - now;
+    if remaining <= 0 {
+        return None;
+    }
+    Some(format!("resets in {}", format_wait_time(remaining)))
+}
+
+// =============================================================================
+// Tests — ported from test/account-status.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, ActiveIndexByFamily};
+
+    fn storage_with(count: usize, active_index: i64) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        for i in 0..count {
+            storage
+                .accounts
+                .push(AccountMetadataV3::new(format!("rt-{i}"), 1, 1));
+        }
+        storage.active_index = active_index;
+        storage
+    }
+
+    #[test]
+    fn resolve_active_index_clamps_and_prefers_family() {
+        assert_eq!(resolve_active_index(&storage_with(0, 5), ModelFamily::Codex), 0);
+        assert_eq!(resolve_active_index(&storage_with(3, 2), ModelFamily::Codex), 2);
+        assert_eq!(resolve_active_index(&storage_with(3, 9), ModelFamily::Codex), 2);
+        assert_eq!(resolve_active_index(&storage_with(3, -4), ModelFamily::Codex), 0);
+
+        let mut storage = storage_with(3, 0);
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(ModelFamily::Codex, Some(1));
+        storage.active_index_by_family = Some(by_family);
+        assert_eq!(resolve_active_index(&storage, ModelFamily::Codex), 1);
+        // Families without an entry fall back to activeIndex.
+        assert_eq!(resolve_active_index(&storage, ModelFamily::Gpt5_2), 0);
+    }
+
+    #[test]
+    fn rate_limit_reset_matches_family_and_prefixed_keys() {
+        let times: RateLimitStateV3 = [
+            ("codex".to_string(), 2_000i64),
+            ("codex:gpt-5.4".to_string(), 1_500i64),
+            ("gpt-5.2".to_string(), 1_200i64),
+            ("codex-past".to_string(), 5_000i64),
+        ]
+        .into_iter()
+        .collect();
+
+        // Min over exact family + "family:" prefixed keys ("codex-past" is
+        // neither: prefix requires the colon).
+        assert_eq!(
+            get_rate_limit_reset_time_for_family(Some(&times), 1_000, ModelFamily::Codex),
+            Some(1_500)
+        );
+        // Values <= now are ignored.
+        assert_eq!(
+            get_rate_limit_reset_time_for_family(Some(&times), 1_800, ModelFamily::Codex),
+            Some(2_000)
+        );
+        assert_eq!(
+            get_rate_limit_reset_time_for_family(Some(&times), 2_500, ModelFamily::Codex),
+            None
+        );
+        assert_eq!(
+            get_rate_limit_reset_time_for_family(None, 0, ModelFamily::Codex),
+            None
+        );
+        // gpt-5.2 family sees only its own key.
+        assert_eq!(
+            get_rate_limit_reset_time_for_family(Some(&times), 1_000, ModelFamily::Gpt5_2),
+            Some(1_200)
+        );
+    }
+
+    #[test]
+    fn format_rate_limit_entry_formats_remaining() {
+        let times: RateLimitStateV3 = [("codex".to_string(), 61_000i64)].into_iter().collect();
+        let format = |ms: i64| format!("{}s", ms / 1000);
+        assert_eq!(
+            format_rate_limit_entry(Some(&times), 1_000, &format, ModelFamily::Codex),
+            Some("resets in 60s".to_string())
+        );
+        assert_eq!(
+            format_rate_limit_entry(Some(&times), 61_000, &format, ModelFamily::Codex),
+            None
+        );
+    }
+}
diff --git a/crates/runtime/src/app_bind.rs b/crates/runtime/src/app_bind.rs
new file mode 100644
index 000000000..36416594b
--- /dev/null
+++ b/crates/runtime/src/app_bind.rs
@@ -0,0 +1,1950 @@
+//! Port of `lib/runtime/app-bind.ts` — binds the Codex **desktop app** to the
+//! local runtime-rotation proxy by rewriting `~/.codex/config.toml`, spawning
+//! a detached router process, and installing OS auto-start entries. Fully
+//! reversible via a JSON backup of the original config.
+//!
+//! R3 decision (ARCHITECTURE §0): the bind state keeps its exact JSON SHAPE,
+//! but `nodePath` now stores the **Rust router binary path**
+//! (`codex-multi-auth-app-router`) and `routerScriptPath` stores `""`. Old
+//! TS-written bind states (non-empty `routerScriptPath`) are detected via
+//! [`is_legacy_ts_bind_state`] and re-bound on the next `rotation enable`.
+//!
+//! Critical invariants (spec 10 §1 + gotchas):
+//! - `boundConfigHash` = sha256 of the exact written config.toml text; the
+//!   unbind "user edited it" branch depends on the byte-exact rewrite in
+//!   [`crate::config_toml`] — one byte off and unbind refuses the surgical
+//!   restore. That is INTENTIONAL.
+//! - Per-bindDir async mutex around bind/unbind.
+//! - Orphaned-bind self-heal (#614): no state + no backup but config.toml
+//!   still bound → restore via the without-backup path.
+//! - Bind never writes `port=0` into config.toml.
+//! - `formatAppBindStatus` never prints labels containing `@` (privacy).
+
+use std::collections::HashMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+use std::sync::{Arc, LazyLock, Mutex as StdMutex};
+
+use serde::Serialize;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use tokio::sync::Mutex as TokioMutex;
+
+use cma_core::fs_retry::with_file_operation_retry;
+use cma_core::json_io::{
+    stringify_pretty2, write_json_atomic, TrailingNewline, WriteJsonOptions,
+};
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::now_ms;
+
+use crate::config_toml::{
+    config_has_runtime_rotation_provider, restore_config_toml_from_runtime_rotation_provider,
+    restore_config_toml_from_runtime_rotation_provider_without_backup,
+    rewrite_config_toml_for_runtime_rotation_provider,
+};
+
+pub const APP_BIND_DIR_NAME: &str = "app-bind";
+pub const APP_BIND_STATE_FILE: &str = "runtime-rotation-app-bind.json";
+pub const APP_BIND_BACKUP_FILE: &str = "codex-config-backup.json";
+pub const APP_BIND_STATUS_FILE: &str = "runtime-rotation-app-bind-status.json";
+pub const WINDOWS_STARTUP_FILE: &str = "Codex Multi Auth Runtime Router.cmd";
+pub const MACOS_LAUNCH_AGENT_ID: &str = "com.ndycode.codex-multi-auth.runtime-router";
+const DEFAULT_ROUTER_READY_TIMEOUT_MS: u64 = 15_000;
+const ROUTER_STATUS_POLL_INTERVAL_MS: u64 = 100;
+pub const APP_ROUTER_MAX_LOG_BYTES: u64 = 1024 * 1024;
+const APP_BIND_LOG_FILE: &str = "runtime-rotation-app-router.log";
+/// The Rust router binary name (R3 — replaces `scripts/codex-app-router.js`).
+pub const APP_ROUTER_BIN_NAME: &str = "codex-multi-auth-app-router";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppBindPaths {
+    pub codex_home: PathBuf,
+    pub config_path: PathBuf,
+    pub bind_dir: PathBuf,
+    pub state_path: PathBuf,
+    pub backup_path: PathBuf,
+    pub status_path: PathBuf,
+    pub log_path: PathBuf,
+    /// The router executable (TS `routerScriptPath` slot; R3: a native binary).
+    pub router_bin_path: PathBuf,
+    pub startup_path: Option<PathBuf>,
+    pub launch_agent_path: Option<PathBuf>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct AppBindBackup {
+    config_path: String,
+    existed: bool,
+    content: String,
+    created_at: i64,
+}
+
+/// Persisted state file shape (spec 10 §12.1). Serde field order is the JS
+/// property insertion order — byte-identical output matters.
+/// `startupPath`/`launchAgentPath` serialize as explicit `null` when absent.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AppBindState {
+    pub version: i64,
+    pub platform: String,
+    pub host: String,
+    pub port: i64,
+    pub base_url: String,
+    pub config_path: String,
+    pub state_path: String,
+    pub backup_path: String,
+    pub status_path: String,
+    pub log_path: String,
+    /// R3: the Rust router binary path (was Node's `process.execPath`).
+    pub node_path: String,
+    /// R3: `""` for Rust-written states; non-empty (a `.js` path) only in
+    /// legacy TS-written states.
+    pub router_script_path: String,
+    pub client_api_key: String,
+    pub startup_path: Option<String>,
+    pub launch_agent_path: Option<String>,
+    pub bound_config_hash: String,
+    pub updated_at: i64,
+}
+
+/// Router-written status JSON, parsed leniently (strings must be non-empty
+/// after trim, numbers finite; otherwise null).
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AppBindRouterStatus {
+    pub state: Option<String>,
+    pub pid: Option<i64>,
+    pub base_url: Option<String>,
+    pub total_requests: Option<i64>,
+    pub last_account_index: Option<i64>,
+    pub last_account_label: Option<String>,
+    pub last_account_email: Option<String>,
+    pub last_account_id: Option<String>,
+    pub updated_at: Option<i64>,
+    pub last_error: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AppBindStatus {
+    pub bound: bool,
+    pub running: bool,
+    /// True when config.toml is bound to the runtime proxy but the app-bind
+    /// state file is gone (orphaned bind, #614). Then `bound` is also true and
+    /// `state` is None.
+    pub unmanaged_bind: bool,
+    pub state: Option<AppBindState>,
+    pub router: Option<AppBindRouterStatus>,
+    pub paths: AppBindPaths,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AppBindResult {
+    pub status: AppBindStatus,
+    pub message: String,
+}
+
+/// A `(message) -> ()` sink (TS `log?: (message: string) => void`).
+pub type LogSink = Box<dyn Fn(&str) + Send + Sync>;
+/// A `() -> epoch-ms` clock (TS `now?: () => number`).
+pub type NowFn = Box<dyn Fn() -> i64 + Send + Sync>;
+
+/// Test-injectable options (TS `AppBindOptions`). `env: None` reads the
+/// process environment; `platform`/`home` default to the current process.
+#[derive(Default)]
+pub struct AppBindOptions {
+    pub env: Option<HashMap<String, String>>,
+    pub platform: Option<String>,
+    pub home: Option<PathBuf>,
+    pub now: Option<NowFn>,
+    /// Router binary override (TS `nodePath`/`routerScriptPath` collapse into
+    /// this single path under R3).
+    pub router_bin_path: Option<PathBuf>,
+    /// Candidate list override for resolution-failure tests
+    /// (TS `routerScriptCandidates`).
+    pub router_bin_candidates: Option<Vec<PathBuf>>,
+    pub spawn_detached: Option<bool>,
+    pub router_ready_timeout_ms: Option<u64>,
+    pub log: Option<LogSink>,
+}
+
+impl AppBindOptions {
+    fn env_var(&self, key: &str) -> Option<String> {
+        match &self.env {
+            Some(map) => map.get(key).cloned(),
+            None => std::env::var(key).ok(),
+        }
+    }
+
+    fn platform(&self) -> String {
+        self.platform
+            .clone()
+            .unwrap_or_else(|| current_platform().to_string())
+    }
+
+    fn home(&self) -> PathBuf {
+        self.home.clone().unwrap_or_else(default_home_dir)
+    }
+
+    fn now(&self) -> i64 {
+        match &self.now {
+            Some(now) => now(),
+            None => now_ms(),
+        }
+    }
+
+    fn log(&self, message: &str) {
+        if let Some(log) = &self.log {
+            log(message);
+        }
+    }
+}
+
+/// `os.homedir()` analogue via the env ladder (spec 02 §2.1 — env vars
+/// first). The `home` crate is not a cma-runtime dependency; this mirrors the
+/// same USERPROFILE/HOME/HOMEDRIVE+HOMEPATH resolution.
+fn default_home_dir() -> PathBuf {
+    let non_blank = |key: &str| {
+        std::env::var(key)
+            .ok()
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    };
+    if cfg!(windows) {
+        if let Some(profile) = non_blank("USERPROFILE") {
+            return PathBuf::from(profile);
+        }
+        if let Some(home) = non_blank("HOME") {
+            return PathBuf::from(home);
+        }
+        if let (Some(drive), Some(path)) = (non_blank("HOMEDRIVE"), non_blank("HOMEPATH")) {
+            return PathBuf::from(format!("{drive}{path}"));
+        }
+    } else if let Some(home) = non_blank("HOME") {
+        return PathBuf::from(home);
+    }
+    PathBuf::from(".")
+}
+
+/// Node `process.platform` analogue.
+pub fn current_platform() -> &'static str {
+    if cfg!(windows) {
+        "win32"
+    } else if cfg!(target_os = "macos") {
+        "darwin"
+    } else if cfg!(target_os = "linux") {
+        "linux"
+    } else {
+        "unknown"
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Per-bindDir async mutex (TS `withAppBindLock`)
+// ---------------------------------------------------------------------------
+
+static APP_BIND_LOCKS: LazyLock<StdMutex<HashMap<PathBuf, Arc<TokioMutex<()>>>>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+
+fn lock_for(key: &Path) -> Arc<TokioMutex<()>> {
+    let mut guard = APP_BIND_LOCKS
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    guard
+        .entry(key.to_path_buf())
+        .or_insert_with(|| Arc::new(TokioMutex::new(())))
+        .clone()
+}
+
+// ---------------------------------------------------------------------------
+// Config-toml aliases (TS thin wrappers)
+// ---------------------------------------------------------------------------
+
+pub fn rewrite_config_toml_for_app_bind(
+    raw_config: &str,
+    base_url: &str,
+    client_api_key: &str,
+) -> String {
+    rewrite_config_toml_for_runtime_rotation_provider(raw_config, base_url, client_api_key)
+}
+
+pub fn restore_config_toml_from_app_bind(current_config: &str, original_config: &str) -> String {
+    restore_config_toml_from_runtime_rotation_provider(current_config, original_config)
+}
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+
+fn sha256_hex(value: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(value.as_bytes());
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+fn create_app_bind_client_api_key() -> String {
+    use rand::TryRngCore;
+    let mut bytes = [0u8; 32];
+    rand::rngs::OsRng
+        .try_fill_bytes(&mut bytes)
+        .expect("OS entropy source unavailable");
+    let mut out = String::with_capacity(64);
+    for byte in bytes {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+fn read_string(record: &serde_json::Map<String, Value>, key: &str) -> Option<String> {
+    match record.get(key) {
+        Some(Value::String(value)) => {
+            let trimmed = value.trim();
+            if trimmed.is_empty() {
+                None
+            } else {
+                Some(trimmed.to_string())
+            }
+        }
+        _ => None,
+    }
+}
+
+fn read_number(record: &serde_json::Map<String, Value>, key: &str) -> Option<i64> {
+    match record.get(key) {
+        Some(value) if value.is_number() => value.as_i64().or_else(|| {
+            // Finite non-integer numbers truncate (corrupt-file tolerance).
+            value.as_f64().filter(|f| f.is_finite()).map(|f| f as i64)
+        }),
+        _ => None,
+    }
+}
+
+async fn read_json_record(path: &Path) -> Option<serde_json::Map<String, Value>> {
+    let raw = tokio::fs::read_to_string(path).await.ok()?;
+    match serde_json::from_str::<Value>(&raw) {
+        Ok(Value::Object(map)) => Some(map),
+        _ => None,
+    }
+}
+
+/// Atomic write (mkdir -p → temp in target dir → fsync → rename), the whole
+/// operation wrapped in the shared file-operation retry (transient Windows
+/// EBUSY/EPERM). Mode 0o600 unless overridden.
+async fn atomic_write_file(target: &Path, content: &str, mode: u32) -> io::Result<()> {
+    with_file_operation_retry(|| async {
+        write_json_atomic(
+            target,
+            content,
+            Some(mode),
+            &WriteJsonOptions {
+                trailing_newline: TrailingNewline::None,
+                fsync: true,
+                ensure_parent_dir: true,
+                // The outer retry drives re-attempts with a fresh temp file,
+                // matching the TS withFileOperationRetry(atomicWrite) shape.
+                rename_max_attempts: 1,
+                ..WriteJsonOptions::default()
+            },
+        )
+        .await
+    })
+    .await
+}
+
+async fn unlink_if_exists(path: &Path) -> io::Result<()> {
+    let result = with_file_operation_retry(|| async { tokio::fs::remove_file(path).await }).await;
+    match result {
+        Ok(()) => Ok(()),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+fn path_to_string(path: &Path) -> String {
+    path.to_string_lossy().into_owned()
+}
+
+// ---------------------------------------------------------------------------
+// State / backup / status readers (lenient)
+// ---------------------------------------------------------------------------
+
+fn read_app_bind_state_record(record: &serde_json::Map<String, Value>) -> Option<AppBindState> {
+    let port = read_number(record, "port")?;
+    let host = read_string(record, "host")?;
+    let base_url = read_string(record, "baseUrl")?;
+    let config_path = read_string(record, "configPath")?;
+    let backup_path = read_string(record, "backupPath")?;
+    let state_path = read_string(record, "statePath")?;
+    let status_path = read_string(record, "statusPath")?;
+    let log_path = read_string(record, "logPath")?;
+    let node_path = read_string(record, "nodePath")?;
+    // R3: Rust-written states store `""` here; the TS reader required a
+    // non-blank string. Accept any string (including blank) so our own states
+    // re-read; missing/non-string still invalidates the whole state.
+    let router_script_path = match record.get("routerScriptPath") {
+        Some(Value::String(value)) => value.trim().to_string(),
+        _ => return None,
+    };
+    let client_api_key = read_string(record, "clientApiKey")?;
+    let bound_config_hash = read_string(record, "boundConfigHash")?;
+    let updated_at = read_number(record, "updatedAt")?;
+    Some(AppBindState {
+        version: 1,
+        platform: read_string(record, "platform")
+            .unwrap_or_else(|| current_platform().to_string()),
+        host,
+        port,
+        base_url,
+        config_path,
+        state_path,
+        backup_path,
+        status_path,
+        log_path,
+        node_path,
+        router_script_path,
+        client_api_key,
+        startup_path: read_string(record, "startupPath"),
+        launch_agent_path: read_string(record, "launchAgentPath"),
+        bound_config_hash,
+        updated_at,
+    })
+}
+
+async fn read_app_bind_state(path: &Path) -> Option<AppBindState> {
+    let record = read_json_record(path).await?;
+    read_app_bind_state_record(&record)
+}
+
+async fn read_app_bind_backup(path: &Path) -> Option<AppBindBackup> {
+    let record = read_json_record(path).await?;
+    let config_path = read_string(&record, "configPath")?;
+    // `content` is a string (empty allowed — do NOT trim).
+    let content = match record.get("content") {
+        Some(Value::String(value)) => value.clone(),
+        _ => return None,
+    };
+    let created_at = read_number(&record, "createdAt")?;
+    Some(AppBindBackup {
+        config_path,
+        existed: record.get("existed") == Some(&Value::Bool(true)),
+        content,
+        created_at,
+    })
+}
+
+async fn read_router_status(path: &Path) -> Option<AppBindRouterStatus> {
+    let record = read_json_record(path).await?;
+    Some(AppBindRouterStatus {
+        state: read_string(&record, "state"),
+        pid: read_number(&record, "pid"),
+        base_url: read_string(&record, "baseUrl"),
+        total_requests: read_number(&record, "totalRequests"),
+        last_account_index: read_number(&record, "lastAccountIndex"),
+        last_account_label: read_string(&record, "lastAccountLabel"),
+        last_account_email: read_string(&record, "lastAccountEmail"),
+        last_account_id: read_string(&record, "lastAccountId"),
+        updated_at: read_number(&record, "updatedAt"),
+        last_error: read_string(&record, "lastError"),
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Process liveness / signaling (no unsafe: shell out to OS tools)
+// ---------------------------------------------------------------------------
+
+/// `process.kill(pid, 0)` analogue. **EPERM counts as alive**; falsy pid →
+/// false. Implemented without unsafe code: Linux consults `/proc/<pid>`;
+/// other unix uses `kill -0`; Windows uses `tasklist` filtered by PID.
+pub fn is_process_alive(pid: Option<i64>) -> bool {
+    let Some(pid) = pid else { return false };
+    if pid <= 0 {
+        return false;
+    }
+    #[cfg(target_os = "linux")]
+    {
+        Path::new(&format!("/proc/{pid}")).exists()
+    }
+    #[cfg(all(unix, not(target_os = "linux")))]
+    {
+        match Command::new("kill")
+            .args(["-0", &pid.to_string()])
+            .stdout(Stdio::null())
+            .stderr(Stdio::piped())
+            .output()
+        {
+            Ok(output) => {
+                if output.status.success() {
+                    true
+                } else {
+                    // EPERM (signal blocked by ownership) still means alive.
+                    let stderr = String::from_utf8_lossy(&output.stderr).to_lowercase();
+                    stderr.contains("not permitted") || stderr.contains("eperm")
+                }
+            }
+            Err(_) => false,
+        }
+    }
+    #[cfg(windows)]
+    {
+        let filter = format!("PID eq {pid}");
+        let mut command = Command::new("tasklist");
+        command
+            .args(["/NH", "/FO", "CSV", "/FI", &filter])
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null());
+        {
+            use std::os::windows::process::CommandExt;
+            const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+            command.creation_flags(CREATE_NO_WINDOW);
+        }
+        match command.output() {
+            Ok(output) => String::from_utf8_lossy(&output.stdout)
+                .contains(&format!("\"{pid}\"")),
+            Err(_) => false,
+        }
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        false
+    }
+}
+
+/// `process.kill(pid, "SIGTERM")` analogue (on Windows, Node terminates the
+/// process unconditionally; `taskkill /F` matches that).
+fn terminate_process(pid: i64) {
+    if pid <= 0 {
+        return;
+    }
+    #[cfg(unix)]
+    {
+        let _ = Command::new("kill")
+            .arg(pid.to_string())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .status();
+    }
+    #[cfg(windows)]
+    {
+        let mut command = Command::new("taskkill");
+        command
+            .args(["/PID", &pid.to_string(), "/T", "/F"])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null());
+        {
+            use std::os::windows::process::CommandExt;
+            const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+            command.creation_flags(CREATE_NO_WINDOW);
+        }
+        let _ = command.status();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+fn resolve_windows_startup_path(options: &AppBindOptions, home: &Path) -> PathBuf {
+    let app_data = options
+        .env_var("APPDATA")
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join("AppData").join("Roaming"));
+    app_data
+        .join("Microsoft")
+        .join("Windows")
+        .join("Start Menu")
+        .join("Programs")
+        .join("Startup")
+        .join(WINDOWS_STARTUP_FILE)
+}
+
+fn resolve_mac_launch_agent_path(home: &Path) -> PathBuf {
+    home.join("Library")
+        .join("LaunchAgents")
+        .join(format!("{MACOS_LAUNCH_AGENT_ID}.plist"))
+}
+
+/// Resolve the router binary (R3): explicit override wins; otherwise the
+/// sibling of the current executable named `codex-multi-auth-app-router`.
+/// Throws (frozen format, binary name substituted per R3):
+/// `codex-multi-auth-app-router not found; checked: <list>`.
+fn resolve_router_bin_path(options: &AppBindOptions) -> Result<PathBuf, String> {
+    if let Some(override_path) = &options.router_bin_path {
+        return Ok(override_path.clone());
+    }
+    let candidates: Vec<PathBuf> = match &options.router_bin_candidates {
+        Some(candidates) => candidates.clone(),
+        None => {
+            let bin_name = format!("{APP_ROUTER_BIN_NAME}{}", std::env::consts::EXE_SUFFIX);
+            match std::env::current_exe()
+                .ok()
+                .and_then(|exe| exe.parent().map(|dir| dir.join(&bin_name)))
+            {
+                Some(sibling) => vec![sibling],
+                None => Vec::new(),
+            }
+        }
+    };
+    for candidate in &candidates {
+        if candidate.exists() {
+            return Ok(candidate.clone());
+        }
+    }
+    Err(format!(
+        "{APP_ROUTER_BIN_NAME} not found; checked: {}",
+        candidates
+            .iter()
+            .map(|candidate| path_to_string(candidate))
+            .collect::<Vec<_>>()
+            .join(", ")
+    ))
+}
+
+pub fn resolve_app_bind_paths(options: &AppBindOptions) -> Result<AppBindPaths, String> {
+    let platform = options.platform();
+    let home = options.home();
+    let codex_home = options
+        .env_var("CODEX_MULTI_AUTH_APP_BIND_CODEX_HOME")
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join(".codex"));
+    let multi_auth_dir = options
+        .env_var("CODEX_MULTI_AUTH_DIR")
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(get_codex_multi_auth_dir);
+    let bind_dir = multi_auth_dir.join(APP_BIND_DIR_NAME);
+    Ok(AppBindPaths {
+        config_path: codex_home.join("config.toml"),
+        codex_home,
+        state_path: bind_dir.join(APP_BIND_STATE_FILE),
+        backup_path: bind_dir.join(APP_BIND_BACKUP_FILE),
+        status_path: bind_dir.join(APP_BIND_STATUS_FILE),
+        log_path: bind_dir.join(APP_BIND_LOG_FILE),
+        router_bin_path: resolve_router_bin_path(options)?,
+        startup_path: if platform == "win32" {
+            Some(resolve_windows_startup_path(options, &home))
+        } else {
+            None
+        },
+        launch_agent_path: if platform == "darwin" {
+            Some(resolve_mac_launch_agent_path(&home))
+        } else {
+            None
+        },
+        bind_dir,
+    })
+}
+
+fn format_base_url(host: &str, port: i64) -> String {
+    let normalized_host = if host.contains(':') && !host.starts_with('[') {
+        format!("[{host}]")
+    } else {
+        host.to_string()
+    };
+    format!("http://{normalized_host}:{port}")
+}
+
+fn read_port_from_base_url(base_url: Option<&str>, fallback: i64) -> i64 {
+    let Some(url) = base_url else { return fallback };
+    let rest = url.split_once("://").map(|(_, tail)| tail).unwrap_or(url);
+    let authority = rest.split(['/', '?', '#']).next().unwrap_or("");
+    let port_str = if let Some(end) = authority.rfind(']') {
+        authority[end + 1..].strip_prefix(':')
+    } else {
+        authority.rsplit_once(':').map(|(_, port)| port)
+    };
+    match port_str.and_then(|port| port.parse::<i64>().ok()) {
+        Some(port) if port > 0 => port,
+        _ => fallback,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Startup entries (Windows .cmd / macOS LaunchAgent)
+// ---------------------------------------------------------------------------
+
+fn escape_windows_batch_path(value: &str) -> String {
+    value.replace('%', "%%")
+}
+
+/// Router argv shared by the spawn, the .cmd, and the plist. R3: no script
+/// argument when `router_script_path` is empty.
+fn router_args(state: &AppBindState) -> Vec<String> {
+    let mut args = Vec::new();
+    if !state.router_script_path.is_empty() {
+        args.push(state.router_script_path.clone());
+    }
+    args.extend([
+        "--port".to_string(),
+        state.port.to_string(),
+        "--status".to_string(),
+        state.status_path.clone(),
+        "--state".to_string(),
+        state.state_path.clone(),
+        "--log".to_string(),
+        state.log_path.clone(),
+        "--max-log-bytes".to_string(),
+        APP_ROUTER_MAX_LOG_BYTES.to_string(),
+    ]);
+    args
+}
+
+fn create_windows_startup_command(state: &AppBindState) -> String {
+    let node_path = escape_windows_batch_path(&state.node_path);
+    let status_path = escape_windows_batch_path(&state.status_path);
+    let state_path = escape_windows_batch_path(&state.state_path);
+    let log_path = escape_windows_batch_path(&state.log_path);
+    let router_part = if state.router_script_path.is_empty() {
+        String::new()
+    } else {
+        format!(
+            " \"{}\"",
+            escape_windows_batch_path(&state.router_script_path)
+        )
+    };
+    [
+        "@echo off".to_string(),
+        format!(
+            "\"{node_path}\"{router_part} --port {} --status \"{status_path}\" --state \"{state_path}\" --log \"{log_path}\" --max-log-bytes {APP_ROUTER_MAX_LOG_BYTES} >> \"{log_path}\" 2>&1",
+            state.port
+        ),
+        String::new(),
+    ]
+    .join("\r\n")
+}
+
+fn xml_escape(value: &str) -> String {
+    value
+        .replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+}
+
+fn create_mac_launch_agent_plist(state: &AppBindState) -> String {
+    let mut args = vec![state.node_path.clone()];
+    args.extend(router_args(state));
+    let mut lines = vec![
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>".to_string(),
+        "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">"
+            .to_string(),
+        "<plist version=\"1.0\">".to_string(),
+        "<dict>".to_string(),
+        "  <key>Label</key>".to_string(),
+        format!("  <string>{MACOS_LAUNCH_AGENT_ID}</string>"),
+        "  <key>ProgramArguments</key>".to_string(),
+        "  <array>".to_string(),
+    ];
+    for arg in &args {
+        lines.push(format!("    <string>{}</string>", xml_escape(arg)));
+    }
+    lines.extend([
+        "  </array>".to_string(),
+        "  <key>RunAtLoad</key>".to_string(),
+        "  <true/>".to_string(),
+        "  <key>KeepAlive</key>".to_string(),
+        "  <true/>".to_string(),
+        "  <key>StandardOutPath</key>".to_string(),
+        format!("  <string>{}</string>", xml_escape(&state.log_path)),
+        "  <key>StandardErrorPath</key>".to_string(),
+        format!("  <string>{}</string>", xml_escape(&state.log_path)),
+        "</dict>".to_string(),
+        "</plist>".to_string(),
+        String::new(),
+    ]);
+    lines.join("\n")
+}
+
+async fn write_app_bind_startup(state: &AppBindState) -> io::Result<()> {
+    if state.platform == "win32"
+        && let Some(startup_path) = &state.startup_path
+    {
+        let startup_path = PathBuf::from(startup_path);
+        if let Some(parent) = startup_path.parent() {
+            tokio::fs::create_dir_all(parent).await?;
+        }
+        return atomic_write_file(&startup_path, &create_windows_startup_command(state), 0o600)
+            .await;
+    }
+    if state.platform == "darwin"
+        && let Some(launch_agent_path) = &state.launch_agent_path
+    {
+        let launch_agent_path = PathBuf::from(launch_agent_path);
+        if let Some(parent) = launch_agent_path.parent() {
+            tokio::fs::create_dir_all(parent).await?;
+        }
+        return atomic_write_file(
+            &launch_agent_path,
+            &create_mac_launch_agent_plist(state),
+            0o600,
+        )
+        .await;
+    }
+    Ok(())
+}
+
+async fn remove_app_bind_startup(state: &AppBindState) {
+    for candidate in [&state.startup_path, &state.launch_agent_path]
+        .into_iter()
+        .flatten()
+    {
+        // Best-effort cleanup.
+        let _ = unlink_if_exists(Path::new(candidate)).await;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Router lifecycle
+// ---------------------------------------------------------------------------
+
+/// Spawn the router detached: stdio to the append-mode log file (0o600),
+/// Windows `CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS` creation flags (no
+/// console, survives parent); unix children survive the parent by default
+/// (stdin null, stdout/stderr to the log — TS parity).
+fn spawn_router(state: &AppBindState) -> io::Result<()> {
+    let log_path = Path::new(&state.log_path);
+    if let Some(parent) = log_path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let mut open_options = std::fs::OpenOptions::new();
+    open_options.append(true).create(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        open_options.mode(0o600);
+    }
+    let log_file = open_options.open(log_path)?;
+    let log_file_err = log_file.try_clone()?;
+    let mut command = Command::new(&state.node_path);
+    command
+        .args(router_args(state))
+        .stdin(Stdio::null())
+        .stdout(Stdio::from(log_file))
+        .stderr(Stdio::from(log_file_err));
+    #[cfg(windows)]
+    {
+        use std::os::windows::process::CommandExt;
+        use windows_sys::Win32::System::Threading::{
+            CREATE_NEW_PROCESS_GROUP, DETACHED_PROCESS,
+        };
+        command.creation_flags(CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS);
+    }
+    // Deliberately not waited on (Node `unref()` parity). CLI processes exit
+    // shortly after, so the OS re-parents the detached router.
+    let _child = command.spawn()?;
+    Ok(())
+}
+
+async fn maybe_start_router(state: &AppBindState, options: &AppBindOptions) -> io::Result<bool> {
+    if options.spawn_detached == Some(false) {
+        return Ok(false);
+    }
+    let router = read_router_status(Path::new(&state.status_path)).await;
+    if let Some(router) = router
+        && is_process_alive(router.pid)
+        && router.state.as_deref() == Some("running")
+    {
+        return Ok(false);
+    }
+    spawn_router(state)?;
+    Ok(true)
+}
+
+fn resolve_router_ready_timeout_ms(options: &AppBindOptions) -> u64 {
+    match options.router_ready_timeout_ms {
+        Some(value) if value > 0 => value,
+        _ => DEFAULT_ROUTER_READY_TIMEOUT_MS,
+    }
+}
+
+async fn wait_for_router_status(
+    status_path: &Path,
+    timeout_ms: u64,
+) -> Result<AppBindRouterStatus, String> {
+    let mut latest: Option<AppBindRouterStatus> = None;
+    let deadline = now_ms() + timeout_ms as i64;
+    while now_ms() < deadline {
+        let router = read_router_status(status_path).await;
+        if let Some(router) = router {
+            if router.state.as_deref() == Some("error") {
+                let suffix = router
+                    .last_error
+                    .as_deref()
+                    .map(|error| format!(": {error}"))
+                    .unwrap_or_default();
+                return Err(format!("Codex app runtime router failed to start{suffix}"));
+            }
+            if router.state.as_deref() == Some("running") && is_process_alive(router.pid) {
+                return Ok(router);
+            }
+            latest = Some(router);
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(
+            ROUTER_STATUS_POLL_INTERVAL_MS,
+        ))
+        .await;
+    }
+    let suffix = latest
+        .and_then(|router| router.last_error)
+        .map(|error| format!(": {error}"))
+        .unwrap_or_default();
+    Err(format!("Codex app runtime router did not report ready{suffix}"))
+}
+
+async fn stop_router(router: Option<&AppBindRouterStatus>) {
+    let Some(pid) = router.and_then(|router| router.pid) else {
+        return;
+    };
+    if !is_process_alive(Some(pid)) {
+        return;
+    }
+    terminate_process(pid);
+    for _ in 0..20 {
+        if !is_process_alive(Some(pid)) {
+            return;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+    }
+}
+
+async fn read_config_if_exists(config_path: &Path) -> (bool, String) {
+    match tokio::fs::read_to_string(config_path).await {
+        Ok(content) => (true, content),
+        Err(_) => (false, String::new()),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Status / bind / unbind
+// ---------------------------------------------------------------------------
+
+/// Detects legacy TS-written bind states (R3): `routerScriptPath` non-empty
+/// means the state still points `node` at `codex-app-router.js`; the manager
+/// re-binds these on the next `rotation enable`.
+pub fn is_legacy_ts_bind_state(state: &AppBindState) -> bool {
+    !state.router_script_path.trim().is_empty()
+}
+
+pub async fn get_app_bind_status(options: &AppBindOptions) -> Result<AppBindStatus, String> {
+    let paths = resolve_app_bind_paths(options)?;
+    let state = read_app_bind_state(&paths.state_path).await;
+    let router = read_router_status(&paths.status_path).await;
+    // When no state file is present, the bind may still be live in config.toml
+    // (orphaned bind, #614).
+    let mut unmanaged_bind = false;
+    if state.is_none() {
+        let (existed, content) = read_config_if_exists(&paths.config_path).await;
+        unmanaged_bind = existed && config_has_runtime_rotation_provider(&content);
+    }
+    Ok(AppBindStatus {
+        bound: state.is_some() || unmanaged_bind,
+        running: router
+            .as_ref()
+            .is_some_and(|router| {
+                router.state.as_deref() == Some("running") && is_process_alive(router.pid)
+            }),
+        unmanaged_bind,
+        state,
+        router,
+        paths,
+    })
+}
+
+pub async fn bind_codex_app_runtime_rotation(
+    options: &AppBindOptions,
+) -> Result<AppBindResult, String> {
+    let paths = resolve_app_bind_paths(options)?;
+    let lock = lock_for(&paths.bind_dir);
+    let _guard = lock.lock().await;
+    bind_codex_app_runtime_rotation_locked(options, &paths).await
+}
+
+async fn bind_codex_app_runtime_rotation_locked(
+    options: &AppBindOptions,
+    paths: &AppBindPaths,
+) -> Result<AppBindResult, String> {
+    let platform = options.platform();
+    let now = options.now();
+    let existing_state = read_app_bind_state(&paths.state_path).await;
+    let host = existing_state
+        .as_ref()
+        .map(|state| state.host.clone())
+        .unwrap_or_else(|| "127.0.0.1".to_string());
+    let mut port = match &existing_state {
+        Some(state) if state.port > 0 => state.port,
+        _ => 0,
+    };
+    let mut base_url = existing_state
+        .as_ref()
+        .map(|state| state.base_url.clone())
+        .unwrap_or_else(|| format_base_url(&host, port));
+    let client_api_key = match &existing_state {
+        Some(state) if !state.client_api_key.is_empty() => state.client_api_key.clone(),
+        _ => create_app_bind_client_api_key(),
+    };
+    let (existed, content) = read_config_if_exists(&paths.config_path).await;
+    let backup = match read_app_bind_backup(&paths.backup_path).await {
+        Some(backup) => backup,
+        None => AppBindBackup {
+            config_path: path_to_string(&paths.config_path),
+            existed,
+            content: content.clone(),
+            created_at: now,
+        },
+    };
+    let bound_config = rewrite_config_toml_for_app_bind(&content, &base_url, &client_api_key);
+    let mut state = AppBindState {
+        version: 1,
+        platform: platform.clone(),
+        host,
+        port,
+        base_url: base_url.clone(),
+        config_path: path_to_string(&paths.config_path),
+        state_path: path_to_string(&paths.state_path),
+        backup_path: path_to_string(&paths.backup_path),
+        status_path: path_to_string(&paths.status_path),
+        log_path: path_to_string(&paths.log_path),
+        // R3: nodePath = the Rust router binary; routerScriptPath = "".
+        node_path: path_to_string(&paths.router_bin_path),
+        router_script_path: String::new(),
+        client_api_key: client_api_key.clone(),
+        startup_path: paths.startup_path.as_ref().map(|path| path_to_string(path)),
+        launch_agent_path: paths
+            .launch_agent_path
+            .as_ref()
+            .map(|path| path_to_string(path)),
+        bound_config_hash: sha256_hex(&bound_config),
+        updated_at: now,
+    };
+
+    tokio::fs::create_dir_all(&paths.bind_dir)
+        .await
+        .map_err(|error| error.to_string())?;
+    if let Some(config_dir) = paths.config_path.parent() {
+        tokio::fs::create_dir_all(config_dir)
+            .await
+            .map_err(|error| error.to_string())?;
+    }
+    atomic_write_file(
+        &paths.backup_path,
+        &format!("{}\n", stringify_backup(&backup)),
+        0o600,
+    )
+    .await
+    .map_err(|error| error.to_string())?;
+    // Write bootstrap state before spawning so the router can read --state on
+    // startup.
+    atomic_write_file(
+        &paths.state_path,
+        &format!("{}\n", stringify_pretty2(&state)),
+        0o600,
+    )
+    .await
+    .map_err(|error| error.to_string())?;
+
+    let started_router = maybe_start_router(&state, options)
+        .await
+        .map_err(|error| error.to_string())?;
+    let router = if started_router {
+        Some(
+            wait_for_router_status(
+                Path::new(&state.status_path),
+                resolve_router_ready_timeout_ms(options),
+            )
+            .await?,
+        )
+    } else {
+        read_router_status(Path::new(&state.status_path)).await
+    };
+    let router_base_url = router.as_ref().and_then(|router| router.base_url.clone());
+    let router_is_usable = router_base_url.is_some()
+        && router.as_ref().is_some_and(|router| {
+            started_router
+                || (router.state.as_deref() == Some("running") && is_process_alive(router.pid))
+        });
+    if router_is_usable {
+        port = read_port_from_base_url(router_base_url.as_deref(), port);
+        base_url = router_base_url.clone().expect("router base url present");
+    } else if !started_router
+        && let Some(existing) = &existing_state
+        && existing.port > 0
+        && router.as_ref().is_some_and(|router| {
+            router.state.as_deref() == Some("running") && is_process_alive(router.pid)
+        })
+    {
+        // Only reuse existingState.port when the router process is verifiably
+        // alive — stale status JSON of a dead router must not win.
+        port = existing.port;
+        base_url = existing.base_url.clone();
+    }
+    if port <= 0 {
+        if started_router {
+            // Best-effort stop of the router we just spawned.
+            let orphan = read_router_status(Path::new(&state.status_path)).await;
+            stop_router(orphan.as_ref()).await;
+        }
+        return Err(
+            "Codex app bind could not resolve a runtime router port; refusing to write config.toml with port=0."
+                .to_string(),
+        );
+    }
+    let bound_config = rewrite_config_toml_for_app_bind(&content, &base_url, &client_api_key);
+    state.port = port;
+    state.base_url = base_url.clone();
+    state.bound_config_hash = sha256_hex(&bound_config);
+    state.updated_at = options.now();
+    if started_router {
+        options.log(&format!("Codex app runtime router started on {base_url}"));
+    }
+    atomic_write_file(&paths.config_path, &bound_config, 0o600)
+        .await
+        .map_err(|error| error.to_string())?;
+    atomic_write_file(
+        &paths.state_path,
+        &format!("{}\n", stringify_pretty2(&state)),
+        0o600,
+    )
+    .await
+    .map_err(|error| error.to_string())?;
+    write_app_bind_startup(&state)
+        .await
+        .map_err(|error| error.to_string())?;
+    let status = get_app_bind_status(options).await?;
+    Ok(AppBindResult {
+        status,
+        message: format!(
+            "Bound Codex app config {} to {base_url}",
+            path_to_string(&paths.config_path)
+        ),
+    })
+}
+
+/// Backup JSON keeps the TS property order: version, configPath, existed,
+/// content, createdAt.
+fn stringify_backup(backup: &AppBindBackup) -> String {
+    #[derive(Serialize)]
+    #[serde(rename_all = "camelCase")]
+    struct BackupWire<'a> {
+        version: i64,
+        config_path: &'a str,
+        existed: bool,
+        content: &'a str,
+        created_at: i64,
+    }
+    stringify_pretty2(&BackupWire {
+        version: 1,
+        config_path: &backup.config_path,
+        existed: backup.existed,
+        content: &backup.content,
+        created_at: backup.created_at,
+    })
+}
+
+pub async fn unbind_codex_app_runtime_rotation(
+    options: &AppBindOptions,
+) -> Result<AppBindResult, String> {
+    let paths = resolve_app_bind_paths(options)?;
+    let lock = lock_for(&paths.bind_dir);
+    let _guard = lock.lock().await;
+    unbind_codex_app_runtime_rotation_locked(options, &paths).await
+}
+
+async fn unbind_codex_app_runtime_rotation_locked(
+    options: &AppBindOptions,
+    paths: &AppBindPaths,
+) -> Result<AppBindResult, String> {
+    let state = read_app_bind_state(&paths.state_path).await;
+    let router = read_router_status(&paths.status_path).await;
+    if let Some(state) = &state {
+        stop_router(router.as_ref()).await;
+        if let Some(pid) = router.as_ref().and_then(|router| router.pid)
+            && is_process_alive(Some(pid))
+        {
+            options.log(&format!(
+                "Warning: runtime router (pid {pid}) did not stop; continuing cleanup"
+            ));
+        }
+        remove_app_bind_startup(state).await;
+    }
+
+    let backup = read_app_bind_backup(&paths.backup_path).await;
+    let mut self_healed = false;
+    if let Some(backup) = &backup {
+        let backup_config_path = PathBuf::from(&backup.config_path);
+        let (current_existed, current_content) = read_config_if_exists(&backup_config_path).await;
+        let user_edited = state.as_ref().is_some_and(|state| {
+            current_existed && sha256_hex(&current_content) != state.bound_config_hash
+        });
+        if user_edited {
+            atomic_write_file(
+                &backup_config_path,
+                &restore_config_toml_from_app_bind(&current_content, &backup.content),
+                0o600,
+            )
+            .await
+            .map_err(|error| error.to_string())?;
+        } else if backup.existed {
+            if let Some(parent) = backup_config_path.parent() {
+                tokio::fs::create_dir_all(parent)
+                    .await
+                    .map_err(|error| error.to_string())?;
+            }
+            atomic_write_file(&backup_config_path, &backup.content, 0o600)
+                .await
+                .map_err(|error| error.to_string())?;
+        } else {
+            unlink_if_exists(&backup_config_path)
+                .await
+                .map_err(|error| error.to_string())?;
+        }
+    } else if let Some(state) = &state {
+        let state_config_path = PathBuf::from(&state.config_path);
+        let (current_existed, current_content) = read_config_if_exists(&state_config_path).await;
+        if current_existed {
+            atomic_write_file(
+                &state_config_path,
+                &restore_config_toml_from_app_bind(&current_content, ""),
+                0o600,
+            )
+            .await
+            .map_err(|error| error.to_string())?;
+        }
+    } else {
+        // Orphaned-bind recovery (#614): no backup and no state file, but the
+        // config may still be bound to the runtime proxy. Consult the config
+        // directly and self-heal it back to a working provider when bound.
+        let (current_existed, current_content) = read_config_if_exists(&paths.config_path).await;
+        if current_existed && config_has_runtime_rotation_provider(&current_content) {
+            atomic_write_file(
+                &paths.config_path,
+                &restore_config_toml_from_runtime_rotation_provider_without_backup(
+                    &current_content,
+                    None,
+                ),
+                0o600,
+            )
+            .await
+            .map_err(|error| error.to_string())?;
+            self_healed = true;
+        }
+    }
+
+    for candidate in [&paths.state_path, &paths.backup_path, &paths.status_path] {
+        // Best-effort cleanup (ENOENT already ignored inside).
+        let _ = unlink_if_exists(candidate).await;
+    }
+
+    let status = get_app_bind_status(options).await?;
+    let message = if let Some(backup) = &backup {
+        format!("Unbound Codex app config {}", backup.config_path)
+    } else if self_healed {
+        format!(
+            "Restored Codex app config {} from an orphaned runtime-proxy bind (no backup was present)",
+            path_to_string(&paths.config_path)
+        )
+    } else {
+        "Codex app bind was not configured".to_string()
+    };
+    Ok(AppBindResult { status, message })
+}
+
+pub fn format_app_bind_status(status: &AppBindStatus) -> String {
+    if status.unmanaged_bind && status.state.is_none() {
+        return [
+            format!(
+                "Codex app bind: bound but unmanaged (config={} points at the runtime proxy, but no app-bind state/backup is present)",
+                path_to_string(&status.paths.config_path)
+            ),
+            [
+                "Run `codex-multi-auth rotation unbind-app` to restore the original",
+                "Codex provider/config. This recovers the orphaned bind even though no",
+                "backup was saved (#614).",
+            ]
+            .join(" "),
+        ]
+        .join("\n");
+    }
+    let Some(state) = status.state.as_ref().filter(|_| status.bound) else {
+        return "Codex app bind: not configured".to_string();
+    };
+    let mut parts = vec![
+        if status.running {
+            "running".to_string()
+        } else {
+            "configured but router not running".to_string()
+        },
+        format!("port={}", state.port),
+        format!("config={}", state.config_path),
+    ];
+    let router_label = status
+        .router
+        .as_ref()
+        .and_then(|router| router.last_account_label.as_deref());
+    match router_label {
+        // Privacy: never print an email-shaped label.
+        Some(label) if !label.contains('@') => {
+            parts.push(format!("lastAccount={label}"));
+        }
+        _ => {
+            if let Some(index) = status
+                .router
+                .as_ref()
+                .and_then(|router| router.last_account_index)
+            {
+                parts.push(format!("lastAccount=Account {}", index + 1));
+            }
+        }
+    }
+    [
+        format!("Codex app bind: {}", parts.join(", ")),
+        [
+            "Note: Codex Desktop may hide history while the app bind selects the",
+            "codex-multi-auth-runtime-proxy provider; use `codex-multi-auth rotation",
+            "unbind-app` or `codex-multi-auth rotation disable` to restore the original",
+            "Codex provider/config.",
+        ]
+        .join(" "),
+        [
+            "Model speed/reasoning controls stay in Codex config/CLI flags; set",
+            "`model_reasoning_effort` in",
+            state.config_path.as_str(),
+            "or pass",
+            "`-c model_reasoning_effort=<level>` for wrapper-launched CLI sessions.",
+        ]
+        .join(" "),
+    ]
+    .join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::constants::RUNTIME_ROTATION_PROXY_PROVIDER_ID;
+    use serial_test::serial;
+
+    fn test_env(root: &Path) -> HashMap<String, String> {
+        let mut env = HashMap::new();
+        env.insert(
+            "CODEX_MULTI_AUTH_DIR".to_string(),
+            path_to_string(&root.join("multi%auth")),
+        );
+        env.insert(
+            "CODEX_MULTI_AUTH_APP_BIND_CODEX_HOME".to_string(),
+            path_to_string(&root.join("codex%home")),
+        );
+        env.insert(
+            "APPDATA".to_string(),
+            path_to_string(&root.join("App%20Data").join("Roaming")),
+        );
+        env
+    }
+
+    fn options_for(
+        root: &Path,
+        platform: &str,
+        env: HashMap<String, String>,
+        router_bin: &Path,
+    ) -> AppBindOptions {
+        AppBindOptions {
+            env: Some(env),
+            platform: Some(platform.to_string()),
+            home: Some(root.to_path_buf()),
+            router_bin_path: Some(router_bin.to_path_buf()),
+            spawn_detached: Some(false),
+            now: Some(Box::new(|| 123)),
+            ..AppBindOptions::default()
+        }
+    }
+
+    async fn seed_existing_app_bind_state(
+        options: &AppBindOptions,
+        port: i64,
+        base_url: &str,
+        node_path: &str,
+        router_script_path: &str,
+    ) -> AppBindPaths {
+        let paths = resolve_app_bind_paths(options).expect("paths resolve");
+        let state = AppBindState {
+            version: 1,
+            platform: options.platform(),
+            host: "127.0.0.1".to_string(),
+            port,
+            base_url: base_url.to_string(),
+            config_path: path_to_string(&paths.config_path),
+            state_path: path_to_string(&paths.state_path),
+            backup_path: path_to_string(&paths.backup_path),
+            status_path: path_to_string(&paths.status_path),
+            log_path: path_to_string(&paths.log_path),
+            node_path: node_path.to_string(),
+            router_script_path: router_script_path.to_string(),
+            client_api_key: "a".repeat(64),
+            startup_path: paths.startup_path.as_ref().map(|p| path_to_string(p)),
+            launch_agent_path: paths.launch_agent_path.as_ref().map(|p| path_to_string(p)),
+            bound_config_hash: sha256_hex("seed"),
+            updated_at: 1,
+        };
+        tokio::fs::create_dir_all(&paths.bind_dir).await.unwrap();
+        tokio::fs::write(
+            &paths.state_path,
+            format!("{}\n", stringify_pretty2(&state)),
+        )
+        .await
+        .unwrap();
+        paths
+    }
+
+    // app-bind.test.ts "resolves app bind paths from the provided environment"
+    #[test]
+    #[serial(env)]
+    fn resolves_app_bind_paths_from_the_provided_environment() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let env = test_env(root);
+        let options = AppBindOptions {
+            env: Some(env),
+            platform: Some("win32".to_string()),
+            home: Some(root.to_path_buf()),
+            router_bin_path: Some(root.join("router.exe")),
+            ..AppBindOptions::default()
+        };
+        let paths = resolve_app_bind_paths(&options).expect("resolve");
+        assert_eq!(paths.config_path, root.join("codex%home").join("config.toml"));
+        assert_eq!(paths.bind_dir, root.join("multi%auth").join("app-bind"));
+        assert_eq!(
+            paths.startup_path,
+            Some(
+                root.join("App%20Data")
+                    .join("Roaming")
+                    .join("Microsoft")
+                    .join("Windows")
+                    .join("Start Menu")
+                    .join("Programs")
+                    .join("Startup")
+                    .join(WINDOWS_STARTUP_FILE)
+            )
+        );
+        assert!(paths.launch_agent_path.is_none());
+    }
+
+    // app-bind.test.ts "fails fast when the router script cannot be resolved"
+    // (message adapted to the R3 router binary name).
+    #[test]
+    #[serial(env)]
+    fn fails_fast_when_the_router_binary_cannot_be_resolved() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let options = AppBindOptions {
+            env: Some(test_env(root)),
+            platform: Some("linux".to_string()),
+            home: Some(root.to_path_buf()),
+            router_bin_candidates: Some(vec![
+                root.join("missing-router-a"),
+                root.join("missing-router-b"),
+            ]),
+            spawn_detached: Some(false),
+            ..AppBindOptions::default()
+        };
+        let error = resolve_app_bind_paths(&options).expect_err("must fail");
+        assert!(error.contains("codex-multi-auth-app-router not found"));
+        assert!(error.contains("missing-router-a"));
+        assert!(error.contains("missing-router-b"));
+    }
+
+    // app-bind.test.ts "binds and unbinds the Windows app config without
+    // spawning during tests" (+ orphan recovery pieces below).
+    #[tokio::test]
+    #[serial(env)]
+    async fn binds_and_unbinds_the_windows_app_config_without_spawning() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let env = test_env(root);
+        let codex_home = root.join("codex%home");
+        let router_bin = root.join("Router%20Dir").join("codex-multi-auth-app-router.exe");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        tokio::fs::write(codex_home.join("config.toml"), "model_provider = \"openai\"\n")
+            .await
+            .unwrap();
+
+        let options = options_for(root, "win32", env.clone(), &router_bin);
+        seed_existing_app_bind_state(&options, 4567, "http://127.0.0.1:4567", "node", "legacy.js")
+            .await;
+
+        let result = bind_codex_app_runtime_rotation(&options)
+            .await
+            .expect("bind succeeds");
+        assert!(result.status.bound);
+        assert!(!result.status.running);
+        let state = result.status.state.as_ref().expect("state present");
+        assert_eq!(
+            state.state_path,
+            path_to_string(
+                &root
+                    .join("multi%auth")
+                    .join("app-bind")
+                    .join("runtime-rotation-app-bind.json")
+            )
+        );
+        // R3: nodePath is the router binary; routerScriptPath is "".
+        assert_eq!(state.node_path, path_to_string(&router_bin));
+        assert_eq!(state.router_script_path, "");
+        assert_eq!(state.port, 4567);
+        let config = tokio::fs::read_to_string(codex_home.join("config.toml"))
+            .await
+            .unwrap();
+        assert!(config.contains(&format!(
+            "[model_providers.{RUNTIME_ROTATION_PROXY_PROVIDER_ID}]"
+        )));
+        assert!(config.contains(&state.base_url));
+        assert!(config.contains("requires_openai_auth = false"));
+        assert!(config.contains(&format!(
+            "experimental_bearer_token = \"{}\"",
+            state.client_api_key
+        )));
+        assert!(!config.contains("env_key"));
+        // boundConfigHash gates unbind: must be the hash of the written text.
+        assert_eq!(state.bound_config_hash, sha256_hex(&config));
+
+        let startup_path = result.status.paths.startup_path.clone().expect("startup");
+        let startup = tokio::fs::read_to_string(&startup_path).await.unwrap();
+        assert!(startup.contains("--state"));
+        assert!(startup.contains("--log"));
+        assert!(startup.contains("--max-log-bytes 1048576"));
+        assert!(startup.contains("runtime-rotation-app-bind.json"));
+        assert!(startup.contains("Router%%20Dir"));
+        assert!(startup.contains("multi%%auth"));
+        assert!(!startup.contains("Router%20Dir"));
+        assert!(!startup.contains(&state.client_api_key));
+        // CRLF joined, `@echo off` first line.
+        assert!(startup.starts_with("@echo off\r\n"));
+        assert!(startup.ends_with("2>&1\r\n"));
+
+        let unbind_options = options_for(root, "win32", env, &router_bin);
+        let unbound = unbind_codex_app_runtime_rotation(&unbind_options)
+            .await
+            .expect("unbind succeeds");
+        assert!(!unbound.status.bound);
+        assert!(unbound.message.starts_with("Unbound Codex app config "));
+        assert_eq!(
+            tokio::fs::read_to_string(codex_home.join("config.toml"))
+                .await
+                .unwrap(),
+            "model_provider = \"openai\"\n"
+        );
+        assert!(!startup_path.exists());
+    }
+
+    // app-bind.test.ts "refuses to bind without spawning when no router port
+    // is known"
+    #[tokio::test]
+    #[serial(env)]
+    async fn refuses_to_bind_without_spawning_when_no_router_port_is_known() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let codex_home = root.join("codex%home");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        let options = options_for(root, "linux", test_env(root), &root.join("router-bin"));
+        let error = bind_codex_app_runtime_rotation(&options)
+            .await
+            .expect_err("must refuse");
+        assert!(error.contains("port=0"));
+    }
+
+    // app-bind.test.ts "rejects corrupt app bind state without a client token"
+    #[tokio::test]
+    #[serial(env)]
+    async fn rejects_corrupt_app_bind_state_without_a_client_token() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let options = options_for(root, "linux", test_env(root), &root.join("router-bin"));
+        let paths = resolve_app_bind_paths(&options).unwrap();
+        tokio::fs::create_dir_all(&paths.bind_dir).await.unwrap();
+        // clientApiKey missing → whole state treated as null → port unknown.
+        let corrupt = serde_json::json!({
+            "version": 1,
+            "platform": "linux",
+            "host": "127.0.0.1",
+            "port": 4567,
+            "baseUrl": "http://127.0.0.1:4567",
+            "configPath": path_to_string(&paths.config_path),
+            "statePath": path_to_string(&paths.state_path),
+            "backupPath": path_to_string(&paths.backup_path),
+            "statusPath": path_to_string(&paths.status_path),
+            "logPath": path_to_string(&paths.log_path),
+            "nodePath": "node",
+            "routerScriptPath": "router.js",
+            "boundConfigHash": "abc",
+            "updatedAt": 1
+        });
+        tokio::fs::write(&paths.state_path, stringify_pretty2(&corrupt))
+            .await
+            .unwrap();
+        let error = bind_codex_app_runtime_rotation(&options)
+            .await
+            .expect_err("must refuse");
+        assert!(error.contains("port=0"));
+    }
+
+    // app-bind.test.ts "serializes concurrent binds so state and config stay
+    // coherent"
+    #[tokio::test]
+    #[serial(env)]
+    async fn serializes_concurrent_binds_so_state_and_config_stay_coherent() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let env = test_env(root);
+        let codex_home = root.join("codex%home");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        tokio::fs::write(codex_home.join("config.toml"), "model_provider = \"openai\"\n")
+            .await
+            .unwrap();
+        let seed_options = options_for(root, "linux", env.clone(), &root.join("router-bin"));
+        let paths = seed_existing_app_bind_state(
+            &seed_options,
+            4567,
+            "http://127.0.0.1:4567",
+            "node",
+            "router.js",
+        )
+        .await;
+
+        let options_a = options_for(root, "linux", env.clone(), &root.join("router-bin"));
+        let options_b = options_for(root, "linux", env, &root.join("router-bin"));
+        let (first, second) = tokio::join!(
+            bind_codex_app_runtime_rotation(&options_a),
+            bind_codex_app_runtime_rotation(&options_b),
+        );
+        assert!(first.expect("first bind").status.bound);
+        assert!(second.expect("second bind").status.bound);
+
+        let config = tokio::fs::read_to_string(&paths.config_path).await.unwrap();
+        let state: Value = serde_json::from_str(
+            &tokio::fs::read_to_string(&paths.state_path).await.unwrap(),
+        )
+        .unwrap();
+        let backup: Value = serde_json::from_str(
+            &tokio::fs::read_to_string(&paths.backup_path).await.unwrap(),
+        )
+        .unwrap();
+        assert!(config.contains(&format!(
+            "model_provider = \"{RUNTIME_ROTATION_PROXY_PROVIDER_ID}\""
+        )));
+        let client_api_key = state["clientApiKey"].as_str().unwrap();
+        assert!(config.contains(&format!("experimental_bearer_token = \"{client_api_key}\"")));
+        assert_eq!(state["boundConfigHash"].as_str().unwrap(), sha256_hex(&config));
+        assert_eq!(
+            backup["content"].as_str().unwrap(),
+            "model_provider = \"openai\"\n"
+        );
+    }
+
+    // app-bind.test.ts "reports unmanagedBind when config is bound but no
+    // state file exists" (#614)
+    #[tokio::test]
+    #[serial(env)]
+    async fn reports_unmanaged_bind_when_config_is_bound_but_no_state_file_exists() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let codex_home = root.join("codex%home");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        let bound = rewrite_config_toml_for_app_bind(
+            "model_provider = \"openai\"\n",
+            "http://127.0.0.1:4567",
+            "secret",
+        );
+        tokio::fs::write(codex_home.join("config.toml"), &bound)
+            .await
+            .unwrap();
+        let options = options_for(root, "linux", test_env(root), &root.join("router-bin"));
+        let status = get_app_bind_status(&options).await.expect("status");
+        assert!(status.bound);
+        assert!(status.unmanaged_bind);
+        assert!(status.state.is_none());
+        let formatted = format_app_bind_status(&status);
+        assert!(formatted.contains("bound but unmanaged"));
+        assert!(formatted.contains("#614"));
+    }
+
+    // app-bind.test.ts "self-heals a bound config with no backup/state on
+    // unbind" (#614)
+    #[tokio::test]
+    #[serial(env)]
+    async fn self_heals_a_bound_config_with_no_backup_or_state_on_unbind() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let codex_home = root.join("codex%home");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        let bound = rewrite_config_toml_for_app_bind(
+            "model_provider = \"openai\"\n",
+            "http://127.0.0.1:4567",
+            "secret",
+        );
+        tokio::fs::write(codex_home.join("config.toml"), &bound)
+            .await
+            .unwrap();
+        let options = options_for(root, "linux", test_env(root), &root.join("router-bin"));
+        let result = unbind_codex_app_runtime_rotation(&options)
+            .await
+            .expect("unbind");
+        assert!(result
+            .message
+            .contains("from an orphaned runtime-proxy bind (no backup was present)"));
+        let config = tokio::fs::read_to_string(codex_home.join("config.toml"))
+            .await
+            .unwrap();
+        assert!(config.contains("model_provider = \"openai\""));
+        assert!(!config.contains(RUNTIME_ROTATION_PROXY_PROVIDER_ID));
+        let status = get_app_bind_status(&options).await.expect("status");
+        assert!(!status.bound);
+        assert!(!status.unmanaged_bind);
+    }
+
+    // app-bind.test.ts "is a no-op for an already-clean config"
+    #[tokio::test]
+    #[serial(env)]
+    async fn unbind_is_a_no_op_for_an_already_clean_config() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let codex_home = root.join("codex%home");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        tokio::fs::write(codex_home.join("config.toml"), "model_provider = \"openai\"\n")
+            .await
+            .unwrap();
+        let options = options_for(root, "linux", test_env(root), &root.join("router-bin"));
+        let result = unbind_codex_app_runtime_rotation(&options)
+            .await
+            .expect("unbind");
+        assert_eq!(result.message, "Codex app bind was not configured");
+        assert_eq!(
+            tokio::fs::read_to_string(codex_home.join("config.toml"))
+                .await
+                .unwrap(),
+            "model_provider = \"openai\"\n"
+        );
+    }
+
+    // app-bind.test.ts "writes a macOS LaunchAgent for login-time router
+    // startup" (content shape only; no spawn).
+    #[tokio::test]
+    #[serial(env)]
+    async fn writes_a_macos_launch_agent_for_login_time_router_startup() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        let env = test_env(root);
+        let codex_home = root.join("codex%home");
+        let router_bin = root.join("bin").join("codex-multi-auth-app-router");
+        tokio::fs::create_dir_all(&codex_home).await.unwrap();
+        tokio::fs::write(
+            codex_home.join("config.toml"),
+            "model_provider = \"open&i\"\n",
+        )
+        .await
+        .unwrap();
+        let options = options_for(root, "darwin", env, &router_bin);
+        seed_existing_app_bind_state(&options, 4567, "http://127.0.0.1:4567", "node", "router.js")
+            .await;
+        let result = bind_codex_app_runtime_rotation(&options)
+            .await
+            .expect("bind succeeds");
+        let launch_agent_path = result
+            .status
+            .paths
+            .launch_agent_path
+            .clone()
+            .expect("launch agent path");
+        let plist = tokio::fs::read_to_string(&launch_agent_path).await.unwrap();
+        assert!(plist.contains(&format!("<string>{MACOS_LAUNCH_AGENT_ID}</string>")));
+        assert!(plist.contains("<key>RunAtLoad</key>"));
+        assert!(plist.contains("<key>KeepAlive</key>"));
+        assert!(plist.contains("<string>--max-log-bytes</string>"));
+        assert!(plist.contains("<string>1048576</string>"));
+        // R3: the binary is argv[0]; no .js argument follows.
+        assert!(plist.contains(&format!("<string>{}</string>", xml_escape(&path_to_string(&router_bin)))));
+        assert!(!plist.contains("router.js"));
+        assert!(plist.ends_with("</plist>\n"));
+    }
+
+    // formatAppBindStatus privacy contract (spec 10 gotcha 19).
+    #[test]
+    fn format_app_bind_status_never_prints_email_labels() {
+        let paths = AppBindPaths {
+            codex_home: PathBuf::from("/h/.codex"),
+            config_path: PathBuf::from("/h/.codex/config.toml"),
+            bind_dir: PathBuf::from("/h/.codex/multi-auth/app-bind"),
+            state_path: PathBuf::from("/h/state"),
+            backup_path: PathBuf::from("/h/backup"),
+            status_path: PathBuf::from("/h/status"),
+            log_path: PathBuf::from("/h/log"),
+            router_bin_path: PathBuf::from("/h/router"),
+            startup_path: None,
+            launch_agent_path: None,
+        };
+        let state = AppBindState {
+            version: 1,
+            platform: "linux".to_string(),
+            host: "127.0.0.1".to_string(),
+            port: 4567,
+            base_url: "http://127.0.0.1:4567".to_string(),
+            config_path: "/h/.codex/config.toml".to_string(),
+            state_path: "/h/state".to_string(),
+            backup_path: "/h/backup".to_string(),
+            status_path: "/h/status".to_string(),
+            log_path: "/h/log".to_string(),
+            node_path: "/h/router".to_string(),
+            router_script_path: String::new(),
+            client_api_key: "k".repeat(64),
+            startup_path: None,
+            launch_agent_path: None,
+            bound_config_hash: "hash".to_string(),
+            updated_at: 1,
+        };
+        let router = AppBindRouterStatus {
+            state: Some("running".to_string()),
+            pid: Some(1),
+            last_account_label: Some("user@example.com".to_string()),
+            last_account_index: Some(2),
+            ..AppBindRouterStatus::default()
+        };
+        let status = AppBindStatus {
+            bound: true,
+            running: true,
+            unmanaged_bind: false,
+            state: Some(state),
+            router: Some(router),
+            paths,
+        };
+        let formatted = format_app_bind_status(&status);
+        assert!(!formatted.contains("user@example.com"));
+        assert!(formatted.contains("lastAccount=Account 3"));
+        assert!(formatted.contains("port=4567"));
+        assert!(formatted.contains("Codex app bind: running"));
+    }
+
+    #[test]
+    fn format_app_bind_status_not_configured() {
+        let paths = AppBindPaths {
+            codex_home: PathBuf::from("/h/.codex"),
+            config_path: PathBuf::from("/h/.codex/config.toml"),
+            bind_dir: PathBuf::from("/h/mad/app-bind"),
+            state_path: PathBuf::from("/h/state"),
+            backup_path: PathBuf::from("/h/backup"),
+            status_path: PathBuf::from("/h/status"),
+            log_path: PathBuf::from("/h/log"),
+            router_bin_path: PathBuf::from("/h/router"),
+            startup_path: None,
+            launch_agent_path: None,
+        };
+        let status = AppBindStatus {
+            bound: false,
+            running: false,
+            unmanaged_bind: false,
+            state: None,
+            router: None,
+            paths,
+        };
+        assert_eq!(format_app_bind_status(&status), "Codex app bind: not configured");
+    }
+
+    // State serialization: exact key order + null startup fields (spec 12.1).
+    #[test]
+    fn state_serializes_in_ts_property_order_with_null_optionals() {
+        let state = AppBindState {
+            version: 1,
+            platform: "win32".to_string(),
+            host: "127.0.0.1".to_string(),
+            port: 8123,
+            base_url: "http://127.0.0.1:8123".to_string(),
+            config_path: "c".to_string(),
+            state_path: "s".to_string(),
+            backup_path: "b".to_string(),
+            status_path: "t".to_string(),
+            log_path: "l".to_string(),
+            node_path: "n".to_string(),
+            router_script_path: String::new(),
+            client_api_key: "k".to_string(),
+            startup_path: None,
+            launch_agent_path: None,
+            bound_config_hash: "h".to_string(),
+            updated_at: 1_753_500_000_000,
+        };
+        let raw = stringify_pretty2(&state);
+        let keys = [
+            "\"version\"",
+            "\"platform\"",
+            "\"host\"",
+            "\"port\"",
+            "\"baseUrl\"",
+            "\"configPath\"",
+            "\"statePath\"",
+            "\"backupPath\"",
+            "\"statusPath\"",
+            "\"logPath\"",
+            "\"nodePath\"",
+            "\"routerScriptPath\"",
+            "\"clientApiKey\"",
+            "\"startupPath\"",
+            "\"launchAgentPath\"",
+            "\"boundConfigHash\"",
+            "\"updatedAt\"",
+        ];
+        let mut last = 0;
+        for key in keys {
+            let idx = raw.find(key).unwrap_or_else(|| panic!("missing {key}"));
+            assert!(idx > last || last == 0, "key out of order: {key}");
+            last = idx;
+        }
+        assert!(raw.contains("\"startupPath\": null"));
+        assert!(raw.contains("\"launchAgentPath\": null"));
+        assert!(raw.contains("\"routerScriptPath\": \"\""));
+    }
+
+    #[test]
+    fn legacy_ts_bind_state_detection() {
+        let mut state = AppBindState {
+            version: 1,
+            platform: "linux".to_string(),
+            host: "127.0.0.1".to_string(),
+            port: 1,
+            base_url: "http://127.0.0.1:1".to_string(),
+            config_path: "c".to_string(),
+            state_path: "s".to_string(),
+            backup_path: "b".to_string(),
+            status_path: "t".to_string(),
+            log_path: "l".to_string(),
+            node_path: "/usr/bin/node".to_string(),
+            router_script_path: "/x/scripts/codex-app-router.js".to_string(),
+            client_api_key: "k".to_string(),
+            startup_path: None,
+            launch_agent_path: None,
+            bound_config_hash: "h".to_string(),
+            updated_at: 1,
+        };
+        assert!(is_legacy_ts_bind_state(&state));
+        state.router_script_path = String::new();
+        assert!(!is_legacy_ts_bind_state(&state));
+    }
+
+    #[test]
+    fn format_base_url_brackets_ipv6_hosts() {
+        assert_eq!(format_base_url("127.0.0.1", 8080), "http://127.0.0.1:8080");
+        assert_eq!(format_base_url("::1", 8080), "http://[::1]:8080");
+        assert_eq!(format_base_url("[::1]", 8080), "http://[::1]:8080");
+    }
+
+    #[test]
+    fn read_port_from_base_url_parses_and_falls_back() {
+        assert_eq!(read_port_from_base_url(Some("http://127.0.0.1:8123"), 1), 8123);
+        assert_eq!(read_port_from_base_url(Some("http://[::1]:9000"), 1), 9000);
+        assert_eq!(read_port_from_base_url(Some("not a url"), 7), 7);
+        assert_eq!(read_port_from_base_url(None, 7), 7);
+        assert_eq!(read_port_from_base_url(Some("http://h:0"), 7), 7);
+    }
+}
diff --git a/crates/runtime/src/app_launcher.rs b/crates/runtime/src/app_launcher.rs
new file mode 100644
index 000000000..1f2d9336f
--- /dev/null
+++ b/crates/runtime/src/app_launcher.rs
@@ -0,0 +1,1178 @@
+//! Port of `scripts/codex-app-launcher.js` — installs/removes the Codex app
+//! launcher routing (`codex-multi-auth-app-launcher` binary, ARCHITECTURE §2).
+//!
+//! Windows: retargets existing user-level `Codex.lnk` shortcuts (Start Menu,
+//! taskbar pins, desktops) through codex-multi-auth via a generated PowerShell
+//! script, backing originals up to `<mad>/app-shortcuts.json`. macOS: creates
+//! a managed `Codex Multi Auth.app` bundle. Linux: a managed `.desktop` file.
+//! `--dry-run` prints planned changes; `--remove` restores/removes.
+//!
+//! R3 adaptation: the TS plan launched `node scripts/codex.js app`; the Rust
+//! plan launches the wrapper binary `codex-multi-auth-codex app` directly
+//! (`command_path` = wrapper binary, `command_argv` drops the script path).
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use cma_core::fs_retry::with_file_operation_retry;
+use serde_json::Value;
+
+pub const OFFICIAL_LAUNCHER_NAME: &str = "Codex";
+pub const MANAGED_LAUNCHER_NAME: &str = "Codex Multi Auth";
+const WINDOWS_SHORTCUT_NAME: &str = "Codex.lnk";
+const LINUX_DESKTOP_FILE_NAME: &str = "codex-multi-auth.desktop";
+const MACOS_APP_NAME: &str = "Codex Multi Auth.app";
+const WINDOWS_BACKUP_FILE_NAME: &str = "app-shortcuts.json";
+const MANAGED_SHORTCUT_DESCRIPTION: &str =
+    "Launch Codex through codex-multi-auth runtime rotation";
+/// The wrapper binary the launcher routes through (R3).
+pub const CODEX_WRAPPER_BIN_NAME: &str = "codex-multi-auth-codex";
+
+pub type EnvMap = HashMap<String, String>;
+/// A shared `(message) -> ()` sink (TS `log?: (message: string) => void`).
+pub type SharedLogSink = Arc<dyn Fn(&str) + Send + Sync>;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AppLauncherMode {
+    RouteExisting,
+    CreateManaged,
+}
+
+impl AppLauncherMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            AppLauncherMode::RouteExisting => "route-existing",
+            AppLauncherMode::CreateManaged => "create-managed",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AppLauncherPlan {
+    pub platform: String,
+    pub mode: AppLauncherMode,
+    pub launcher_path: PathBuf,
+    /// win32 only: shortcut roots scanned for `Codex.lnk`.
+    pub shortcut_roots: Vec<PathBuf>,
+    /// win32 only: original-shortcut backup file.
+    pub backup_path: Option<PathBuf>,
+    pub command_path: PathBuf,
+    pub command_args: String,
+    pub command_argv: Vec<String>,
+    pub working_directory: PathBuf,
+    pub icon_path: String,
+}
+
+#[derive(Default)]
+pub struct AppLauncherOptions {
+    pub env: Option<EnvMap>,
+    pub platform: Option<String>,
+    pub home: Option<PathBuf>,
+    /// Wrapper binary override (tests / non-standard layouts).
+    pub codex_bin_path: Option<PathBuf>,
+    pub dry_run: bool,
+    pub remove: bool,
+    pub log: Option<SharedLogSink>,
+}
+
+impl AppLauncherOptions {
+    fn env_var(&self, key: &str) -> Option<String> {
+        match &self.env {
+            Some(map) => map.get(key).cloned(),
+            None => std::env::var(key).ok(),
+        }
+    }
+
+    fn env_var_non_blank(&self, key: &str) -> Option<String> {
+        self.env_var(key)
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    fn log(&self, message: &str) {
+        match &self.log {
+            Some(log) => log(message),
+            None => println!("{message}"),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Quoting helpers (verbatim ports)
+// ---------------------------------------------------------------------------
+
+fn quote_powershell_single(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "''"))
+}
+
+fn quote_powershell_boolean(value: bool) -> &'static str {
+    if value { "$true" } else { "$false" }
+}
+
+fn quote_powershell_array(values: &[String]) -> String {
+    if values.is_empty() {
+        return "@()".to_string();
+    }
+    format!(
+        "@({})",
+        values
+            .iter()
+            .map(|value| quote_powershell_single(value))
+            .collect::<Vec<_>>()
+            .join(", ")
+    )
+}
+
+fn quote_desktop_exec(value: &str) -> String {
+    format!("\"{}\"", value.replace('\\', "\\\\").replace('"', "\\\""))
+}
+
+fn quote_posix_shell(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "'\\''"))
+}
+
+fn unique_strings(values: Vec<String>) -> Vec<String> {
+    let mut seen = Vec::new();
+    for value in values {
+        if value.trim().is_empty() {
+            continue;
+        }
+        if !seen.contains(&value) {
+            seen.push(value);
+        }
+    }
+    seen
+}
+
+/// Base64 (standard alphabet, padded) of the UTF-16LE encoding — PowerShell
+/// `-EncodedCommand` transport. Hand-rolled: `base64` is not a cma-runtime
+/// dependency.
+fn encode_powershell_command(value: &str) -> String {
+    let mut bytes = Vec::with_capacity(value.len() * 2);
+    for unit in value.encode_utf16() {
+        bytes.extend_from_slice(&unit.to_le_bytes());
+    }
+    base64_encode(&bytes)
+}
+
+fn base64_encode(bytes: &[u8]) -> String {
+    const ALPHABET: &[u8; 64] =
+        b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
+    for chunk in bytes.chunks(3) {
+        let b0 = chunk[0] as u32;
+        let b1 = chunk.get(1).copied().unwrap_or(0) as u32;
+        let b2 = chunk.get(2).copied().unwrap_or(0) as u32;
+        let triple = (b0 << 16) | (b1 << 8) | b2;
+        out.push(ALPHABET[(triple >> 18) as usize & 0x3f] as char);
+        out.push(ALPHABET[(triple >> 12) as usize & 0x3f] as char);
+        out.push(if chunk.len() > 1 {
+            ALPHABET[(triple >> 6) as usize & 0x3f] as char
+        } else {
+            '='
+        });
+        out.push(if chunk.len() > 2 {
+            ALPHABET[triple as usize & 0x3f] as char
+        } else {
+            '='
+        });
+    }
+    out
+}
+
+// ---------------------------------------------------------------------------
+// Directory resolution
+// ---------------------------------------------------------------------------
+
+fn resolve_app_data(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    options
+        .env_var_non_blank("APPDATA")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join("AppData").join("Roaming"))
+}
+
+fn resolve_windows_start_menu_dir(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    resolve_app_data(options, home)
+        .join("Microsoft")
+        .join("Windows")
+        .join("Start Menu")
+        .join("Programs")
+}
+
+fn resolve_windows_powershell_path(options: &AppLauncherOptions) -> PathBuf {
+    let system_root = options
+        .env_var_non_blank("SystemRoot")
+        .or_else(|| options.env_var_non_blank("SYSTEMROOT"))
+        .unwrap_or_else(|| "C:\\Windows".to_string());
+    PathBuf::from(system_root)
+        .join("System32")
+        .join("WindowsPowerShell")
+        .join("v1.0")
+        .join("powershell.exe")
+}
+
+fn resolve_windows_taskbar_pinned_dir(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    resolve_app_data(options, home)
+        .join("Microsoft")
+        .join("Internet Explorer")
+        .join("Quick Launch")
+        .join("User Pinned")
+        .join("TaskBar")
+}
+
+fn resolve_windows_desktop_dirs(options: &AppLauncherOptions, home: &Path) -> Vec<String> {
+    let configured = options
+        .env_var("CODEX_MULTI_AUTH_APP_LAUNCHER_WINDOWS_DESKTOP_DIR")
+        .map(|value| value.trim().to_string())
+        .unwrap_or_default();
+    let mut values = vec![configured];
+    for key in ["OneDrive", "OneDriveConsumer", "OneDriveCommercial"] {
+        if let Some(root) = options.env_var_non_blank(key) {
+            values.push(PathBuf::from(root).join("Desktop").to_string_lossy().into_owned());
+        }
+    }
+    values.push(home.join("Desktop").to_string_lossy().into_owned());
+    unique_strings(values)
+}
+
+fn resolve_codex_multi_auth_dir(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    options
+        .env_var_non_blank("CODEX_MULTI_AUTH_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join(".codex").join("multi-auth"))
+}
+
+fn resolve_linux_applications_dir(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    options
+        .env_var_non_blank("XDG_DATA_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join(".local").join("share"))
+        .join("applications")
+}
+
+fn resolve_mac_applications_dir(options: &AppLauncherOptions, home: &Path) -> PathBuf {
+    options
+        .env_var_non_blank("CODEX_MULTI_AUTH_APP_LAUNCHER_MACOS_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join("Applications"))
+}
+
+fn default_home(options: &AppLauncherOptions) -> PathBuf {
+    let non_blank = |key: &str| options.env_var_non_blank(key).map(PathBuf::from);
+    if cfg!(windows) {
+        non_blank("USERPROFILE")
+            .or_else(|| non_blank("HOME"))
+            .unwrap_or_else(|| PathBuf::from("."))
+    } else {
+        non_blank("HOME").unwrap_or_else(|| PathBuf::from("."))
+    }
+}
+
+/// Resolve the `codex-multi-auth-codex` wrapper binary (R3): override wins,
+/// else the sibling of the current executable. Existence is not required for
+/// plan building (dry runs print the target either way).
+fn resolve_codex_wrapper_bin(options: &AppLauncherOptions) -> PathBuf {
+    if let Some(override_path) = &options.codex_bin_path {
+        return override_path.clone();
+    }
+    let bin_name = format!("{CODEX_WRAPPER_BIN_NAME}{}", std::env::consts::EXE_SUFFIX);
+    std::env::current_exe()
+        .ok()
+        .and_then(|exe| exe.parent().map(|dir| dir.join(&bin_name)))
+        .unwrap_or_else(|| PathBuf::from(bin_name))
+}
+
+/// `resolveAppLauncherPlan` — pure plan builder.
+pub fn resolve_app_launcher_plan(options: &AppLauncherOptions) -> AppLauncherPlan {
+    let platform = options
+        .platform
+        .clone()
+        .unwrap_or_else(|| crate::app_bind::current_platform().to_string());
+    let home = options.home.clone().unwrap_or_else(|| default_home(options));
+    let wrapper_bin = resolve_codex_wrapper_bin(options);
+    let wrapper_bin_str = wrapper_bin.to_string_lossy().into_owned();
+
+    if platform == "win32" {
+        let start_menu_dir = resolve_windows_start_menu_dir(options, &home);
+        let command = [
+            "$ErrorActionPreference = 'Stop'".to_string(),
+            format!(
+                "Set-Location -LiteralPath {}",
+                quote_powershell_single(&home.to_string_lossy())
+            ),
+            format!("& {} app", quote_powershell_single(&wrapper_bin_str)),
+        ]
+        .join("; ");
+        let mut shortcut_roots = vec![
+            start_menu_dir.clone(),
+            resolve_windows_taskbar_pinned_dir(options, &home),
+        ];
+        shortcut_roots.extend(
+            resolve_windows_desktop_dirs(options, &home)
+                .into_iter()
+                .map(PathBuf::from),
+        );
+        return AppLauncherPlan {
+            platform,
+            mode: AppLauncherMode::RouteExisting,
+            launcher_path: start_menu_dir.join(WINDOWS_SHORTCUT_NAME),
+            shortcut_roots,
+            backup_path: Some(
+                resolve_codex_multi_auth_dir(options, &home).join(WINDOWS_BACKUP_FILE_NAME),
+            ),
+            command_path: resolve_windows_powershell_path(options),
+            command_args: format!(
+                "-NoProfile -ExecutionPolicy Bypass -EncodedCommand {}",
+                encode_powershell_command(&command)
+            ),
+            command_argv: vec!["app".to_string()],
+            working_directory: home,
+            icon_path: wrapper_bin_str,
+        };
+    }
+
+    if platform == "darwin" {
+        let app_path = resolve_mac_applications_dir(options, &home).join(MACOS_APP_NAME);
+        return AppLauncherPlan {
+            platform,
+            mode: AppLauncherMode::CreateManaged,
+            launcher_path: app_path,
+            shortcut_roots: Vec::new(),
+            backup_path: None,
+            command_path: wrapper_bin,
+            command_args: "app".to_string(),
+            command_argv: vec!["app".to_string()],
+            working_directory: home,
+            icon_path: wrapper_bin_str,
+        };
+    }
+
+    let desktop_path = resolve_linux_applications_dir(options, &home).join(LINUX_DESKTOP_FILE_NAME);
+    AppLauncherPlan {
+        platform,
+        mode: AppLauncherMode::CreateManaged,
+        launcher_path: desktop_path,
+        shortcut_roots: Vec::new(),
+        backup_path: None,
+        command_path: wrapper_bin,
+        command_args: "app %F".to_string(),
+        command_argv: vec!["app".to_string(), "%F".to_string()],
+        working_directory: home,
+        icon_path: "utilities-terminal".to_string(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Windows PowerShell script (verbatim port with R3 target)
+// ---------------------------------------------------------------------------
+
+/// `createWindowsShortcutPowerShellScript` — builds the routing (or restore)
+/// script run through `powershell.exe`. Emits a single compressed JSON result
+/// line consumed by [`install_codex_app_launcher`].
+pub fn create_windows_shortcut_powershell_script(
+    plan: &AppLauncherPlan,
+    dry_run: bool,
+    remove: bool,
+) -> String {
+    let shortcut_roots: Vec<String> = plan
+        .shortcut_roots
+        .iter()
+        .map(|root| root.to_string_lossy().into_owned())
+        .collect();
+    let backup_path = plan
+        .backup_path
+        .as_ref()
+        .map(|path| path.to_string_lossy().into_owned())
+        .unwrap_or_default();
+
+    if remove {
+        return [
+            "$ErrorActionPreference = 'Stop'".to_string(),
+            format!("$DryRun = {}", quote_powershell_boolean(dry_run)),
+            format!("$BackupPath = {}", quote_powershell_single(&backup_path)),
+            "$Restored = @()".to_string(),
+            "$Skipped = @()".to_string(),
+            "if (Test-Path -LiteralPath $BackupPath) {".to_string(),
+            "  $Raw = Get-Content -LiteralPath $BackupPath -Raw -Encoding UTF8".to_string(),
+            "  $Backups = @($Raw | ConvertFrom-Json)".to_string(),
+            "  $Shell = New-Object -ComObject WScript.Shell".to_string(),
+            "  foreach ($Backup in $Backups) {".to_string(),
+            "    if ($null -eq $Backup.Path -or -not (Test-Path -LiteralPath $Backup.Path)) {"
+                .to_string(),
+            "      if ($null -ne $Backup.Path) { $Skipped += [string]$Backup.Path }".to_string(),
+            "      continue".to_string(),
+            "    }".to_string(),
+            "    if (-not $DryRun) {".to_string(),
+            "      $Shortcut = $Shell.CreateShortcut([string]$Backup.Path)".to_string(),
+            "      $Shortcut.TargetPath = [string]$Backup.TargetPath".to_string(),
+            "      $Shortcut.Arguments = [string]$Backup.Arguments".to_string(),
+            "      $Shortcut.WorkingDirectory = [string]$Backup.WorkingDirectory".to_string(),
+            "      $Shortcut.IconLocation = [string]$Backup.IconLocation".to_string(),
+            "      $Shortcut.Description = [string]$Backup.Description".to_string(),
+            "      $Shortcut.Save()".to_string(),
+            "    }".to_string(),
+            "    $Restored += [string]$Backup.Path".to_string(),
+            "  }".to_string(),
+            "  if (-not $DryRun) { Remove-Item -LiteralPath $BackupPath -Force -ErrorAction SilentlyContinue }"
+                .to_string(),
+            "}".to_string(),
+            "$Result = [ordered]@{ action = 'restore'; dryRun = $DryRun; backupPath = $BackupPath; restored = @($Restored); skipped = @($Skipped) }"
+                .to_string(),
+            "$Result | ConvertTo-Json -Depth 6 -Compress".to_string(),
+        ]
+        .join("\r\n");
+    }
+
+    [
+        "$ErrorActionPreference = 'Stop'".to_string(),
+        format!("$DryRun = {}", quote_powershell_boolean(dry_run)),
+        format!("$ShortcutRoots = {}", quote_powershell_array(&shortcut_roots)),
+        "$ShellDesktop = [Environment]::GetFolderPath('Desktop')".to_string(),
+        "if (-not [string]::IsNullOrWhiteSpace($ShellDesktop)) { $ShortcutRoots = @($ShortcutRoots + $ShellDesktop) | Sort-Object -Unique }"
+            .to_string(),
+        format!("$BackupPath = {}", quote_powershell_single(&backup_path)),
+        format!(
+            "$ShortcutName = {}",
+            quote_powershell_single(OFFICIAL_LAUNCHER_NAME)
+        ),
+        format!(
+            "$TargetPath = {}",
+            quote_powershell_single(&plan.command_path.to_string_lossy())
+        ),
+        format!("$Arguments = {}", quote_powershell_single(&plan.command_args)),
+        format!(
+            "$WorkingDirectory = {}",
+            quote_powershell_single(&plan.working_directory.to_string_lossy())
+        ),
+        format!(
+            "$ManagedDescription = {}",
+            quote_powershell_single(MANAGED_SHORTCUT_DESCRIPTION)
+        ),
+        "$Candidates = @()".to_string(),
+        "$PackagedApps = @()".to_string(),
+        "foreach ($Root in $ShortcutRoots) {".to_string(),
+        "  if (-not (Test-Path -LiteralPath $Root)) { continue }".to_string(),
+        "  $Candidates += Get-ChildItem -LiteralPath $Root -Filter '*.lnk' -File -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.BaseName -ieq $ShortcutName } | ForEach-Object { $_.FullName }"
+            .to_string(),
+        "}".to_string(),
+        "$Candidates = @($Candidates | Sort-Object -Unique)".to_string(),
+        "try {".to_string(),
+        "  $AppsFolder = (New-Object -ComObject Shell.Application).Namespace('shell:AppsFolder')"
+            .to_string(),
+        "  if ($null -ne $AppsFolder) {".to_string(),
+        "    $PackagedApps = @($AppsFolder.Items() | Where-Object { $_.Name -ieq $ShortcutName } | ForEach-Object { [ordered]@{ Name = [string]$_.Name; Path = [string]$_.Path } })"
+            .to_string(),
+        "  }".to_string(),
+        "} catch { $PackagedApps = @() }".to_string(),
+        "$Shell = New-Object -ComObject WScript.Shell".to_string(),
+        "$ExistingBackups = @()".to_string(),
+        "if (Test-Path -LiteralPath $BackupPath) {".to_string(),
+        "  try {".to_string(),
+        "    $Raw = Get-Content -LiteralPath $BackupPath -Raw -Encoding UTF8".to_string(),
+        "    if ($Raw.Trim().Length -gt 0) { $ExistingBackups = @($Raw | ConvertFrom-Json) }"
+            .to_string(),
+        "  } catch { $ExistingBackups = @() }".to_string(),
+        "}".to_string(),
+        "$BackupByPath = @{}".to_string(),
+        "$BackupsToWrite = New-Object System.Collections.ArrayList".to_string(),
+        "foreach ($Backup in $ExistingBackups) {".to_string(),
+        "  if ($null -eq $Backup.Path) { continue }".to_string(),
+        "  $BackupByPath[[string]$Backup.Path] = $Backup".to_string(),
+        "  [void]$BackupsToWrite.Add($Backup)".to_string(),
+        "}".to_string(),
+        "$Routed = @()".to_string(),
+        "$Skipped = @()".to_string(),
+        "foreach ($Path in $Candidates) {".to_string(),
+        "  $Shortcut = $Shell.CreateShortcut($Path)".to_string(),
+        "  $ShortcutText = (($Shortcut.TargetPath, $Shortcut.Arguments, $Shortcut.Description) -join ' ')"
+            .to_string(),
+        "  if ($ShortcutText -notmatch '(?i)codex') {".to_string(),
+        "    $Skipped += $Path".to_string(),
+        "    continue".to_string(),
+        "  }".to_string(),
+        "  $AlreadyManaged = (([string]$Shortcut.Description) -eq $ManagedDescription) -or ((([string]$Shortcut.TargetPath) -ieq $TargetPath) -and (([string]$Shortcut.Arguments) -ieq $Arguments))"
+            .to_string(),
+        "  if (-not $BackupByPath.ContainsKey($Path) -and -not $AlreadyManaged) {".to_string(),
+        "    $IconLocation = [string]$Shortcut.IconLocation".to_string(),
+        "    if ([string]::IsNullOrWhiteSpace($IconLocation)) { $IconLocation = [string]$Shortcut.TargetPath }"
+            .to_string(),
+        "    $Backup = [ordered]@{".to_string(),
+        "      Path = [string]$Path".to_string(),
+        "      TargetPath = [string]$Shortcut.TargetPath".to_string(),
+        "      Arguments = [string]$Shortcut.Arguments".to_string(),
+        "      WorkingDirectory = [string]$Shortcut.WorkingDirectory".to_string(),
+        "      IconLocation = $IconLocation".to_string(),
+        "      Description = [string]$Shortcut.Description".to_string(),
+        "    }".to_string(),
+        "    [void]$BackupsToWrite.Add($Backup)".to_string(),
+        "    $BackupByPath[$Path] = $Backup".to_string(),
+        "  }".to_string(),
+        "  if (-not $DryRun) {".to_string(),
+        "    $Backup = $BackupByPath[$Path]".to_string(),
+        "    $Shortcut.TargetPath = $TargetPath".to_string(),
+        "    $Shortcut.Arguments = $Arguments".to_string(),
+        "    $Shortcut.WorkingDirectory = $WorkingDirectory".to_string(),
+        "    if ($null -ne $Backup -and $null -ne $Backup.IconLocation) { $Shortcut.IconLocation = [string]$Backup.IconLocation }"
+            .to_string(),
+        "    $Shortcut.Description = $ManagedDescription".to_string(),
+        "    $Shortcut.Save()".to_string(),
+        "  }".to_string(),
+        "  $Routed += $Path".to_string(),
+        "}".to_string(),
+        "if (-not $DryRun -and $Routed.Count -gt 0) {".to_string(),
+        "  New-Item -ItemType Directory -Force -Path (Split-Path -Parent $BackupPath) | Out-Null"
+            .to_string(),
+        "  @($BackupsToWrite) | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $BackupPath -Encoding UTF8"
+            .to_string(),
+        "}".to_string(),
+        "$Result = [ordered]@{ action = 'route'; dryRun = $DryRun; backupPath = $BackupPath; candidates = @($Candidates); packagedApps = @($PackagedApps); routed = @($Routed); skipped = @($Skipped); targetPath = $TargetPath; arguments = $Arguments }"
+            .to_string(),
+        "$Result | ConvertTo-Json -Depth 6 -Compress".to_string(),
+    ]
+    .join("\r\n")
+}
+
+// ---------------------------------------------------------------------------
+// Managed launcher file contents (Linux / macOS)
+// ---------------------------------------------------------------------------
+
+fn create_linux_desktop_file(plan: &AppLauncherPlan) -> String {
+    [
+        "[Desktop Entry]".to_string(),
+        "Type=Application".to_string(),
+        format!("Name={MANAGED_LAUNCHER_NAME}"),
+        "Comment=Launch Codex through codex-multi-auth runtime rotation".to_string(),
+        format!(
+            "Exec={} {}",
+            quote_desktop_exec(&plan.command_path.to_string_lossy()),
+            plan.command_args
+        ),
+        format!("Path={}", plan.working_directory.to_string_lossy()),
+        format!("Icon={}", plan.icon_path),
+        "Terminal=false".to_string(),
+        "Categories=Development;".to_string(),
+        "StartupNotify=true".to_string(),
+        String::new(),
+    ]
+    .join("\n")
+}
+
+fn create_mac_info_plist() -> String {
+    [
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+        "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">",
+        "<plist version=\"1.0\">",
+        "<dict>",
+        "  <key>CFBundleExecutable</key>",
+        "  <string>Codex</string>",
+        "  <key>CFBundleIdentifier</key>",
+        "  <string>com.ndycode.codex-multi-auth.launcher</string>",
+        "  <key>CFBundleName</key>",
+        &format!("  <string>{MANAGED_LAUNCHER_NAME}</string>"),
+        "  <key>CFBundlePackageType</key>",
+        "  <string>APPL</string>",
+        "</dict>",
+        "</plist>",
+        "",
+    ]
+    .join("\n")
+}
+
+fn create_mac_launcher_script(plan: &AppLauncherPlan) -> String {
+    let args = plan
+        .command_argv
+        .iter()
+        .map(|arg| quote_posix_shell(arg))
+        .collect::<Vec<_>>()
+        .join(" ");
+    [
+        "#!/bin/sh".to_string(),
+        format!(
+            "cd {}",
+            quote_posix_shell(&plan.working_directory.to_string_lossy())
+        ),
+        format!(
+            "exec {} {}",
+            quote_posix_shell(&plan.command_path.to_string_lossy()),
+            args
+        ),
+        String::new(),
+    ]
+    .join("\n")
+}
+
+// ---------------------------------------------------------------------------
+// Install / remove
+// ---------------------------------------------------------------------------
+
+async fn write_text_file_with_retry(path: &Path, content: &str) -> Result<(), String> {
+    with_file_operation_retry(|| async {
+        if let Some(parent) = path.parent() {
+            tokio::fs::create_dir_all(parent).await?;
+        }
+        tokio::fs::write(path, content).await
+    })
+    .await
+    .map_err(|error: std::io::Error| error.to_string())
+}
+
+#[cfg(unix)]
+fn chmod_755(path: &Path) -> Result<(), String> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755))
+        .map_err(|error| error.to_string())
+}
+
+#[cfg(not(unix))]
+fn chmod_755(_path: &Path) -> Result<(), String> {
+    Ok(())
+}
+
+async fn install_linux_desktop_file(plan: &AppLauncherPlan) -> Result<(), String> {
+    write_text_file_with_retry(&plan.launcher_path, &create_linux_desktop_file(plan)).await?;
+    chmod_755(&plan.launcher_path)
+}
+
+async fn install_mac_app_bundle(plan: &AppLauncherPlan) -> Result<(), String> {
+    let contents_dir = plan.launcher_path.join("Contents");
+    let macos_dir = contents_dir.join("MacOS");
+    tokio::fs::create_dir_all(&macos_dir)
+        .await
+        .map_err(|error| error.to_string())?;
+    write_text_file_with_retry(&contents_dir.join("Info.plist"), &create_mac_info_plist()).await?;
+    let launcher_script_path = macos_dir.join("Codex");
+    write_text_file_with_retry(&launcher_script_path, &create_mac_launcher_script(plan)).await?;
+    chmod_755(&launcher_script_path)
+}
+
+/// `rm -rf` analogue (force: missing paths are fine; recursive for the .app
+/// bundle), wrapped in the shared transient-error retry.
+async fn remove_path_recursive(path: &Path) -> Result<(), String> {
+    with_file_operation_retry(|| async {
+        match tokio::fs::metadata(path).await {
+            Ok(metadata) if metadata.is_dir() => tokio::fs::remove_dir_all(path).await,
+            Ok(_) => tokio::fs::remove_file(path).await,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+            Err(error) => Err(error),
+        }
+    })
+    .await
+    .map_err(|error: std::io::Error| error.to_string())
+}
+
+async fn run_powershell(
+    powershell: &Path,
+    script: &str,
+    env: Option<&EnvMap>,
+) -> Result<(String, String), String> {
+    let mut command = tokio::process::Command::new(powershell);
+    command.args(["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script]);
+    if let Some(env) = env {
+        command.envs(env.iter());
+    }
+    command.stdin(std::process::Stdio::null());
+    #[cfg(windows)]
+    {
+        const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+        command.creation_flags(CREATE_NO_WINDOW);
+    }
+    let output = command
+        .output()
+        .await
+        .map_err(|error| error.to_string())?;
+    let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+    let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+    if !output.status.success() {
+        let code = output
+            .status
+            .code()
+            .map(|code| code.to_string())
+            .unwrap_or_else(|| "unknown".to_string());
+        return Err(format!(
+            "{} exited with {code}: {}",
+            powershell.to_string_lossy(),
+            stderr.trim()
+        ));
+    }
+    Ok((stdout, stderr))
+}
+
+async fn install_windows_shortcut(
+    plan: &AppLauncherPlan,
+    options: &AppLauncherOptions,
+) -> Result<Value, String> {
+    let script = create_windows_shortcut_powershell_script(plan, options.dry_run, options.remove);
+    let powershell = resolve_windows_powershell_path(options);
+    let (stdout, _stderr) = run_powershell(&powershell, &script, options.env.as_ref()).await?;
+    let output = stdout
+        .trim()
+        .split(['\r', '\n'])
+        .rfind(|line| !line.is_empty());
+    let Some(output) = output else {
+        return Ok(serde_json::json!({
+            "action": if options.remove { "restore" } else { "route" },
+            "routed": [],
+            "restored": [],
+            "skipped": [],
+        }));
+    };
+    serde_json::from_str::<Value>(output).map_err(|error| {
+        let tail: String = {
+            let trimmed = stdout.trim();
+            let chars: Vec<char> = trimmed.chars().collect();
+            let start = chars.len().saturating_sub(512);
+            chars[start..].iter().collect()
+        };
+        format!("codex-multi-auth-app-launcher: unexpected powershell output ({error}): {tail}")
+    })
+}
+
+fn array_len(result: &Value, key: &str) -> usize {
+    result
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|values| values.len())
+        .unwrap_or(0)
+}
+
+/// `installCodexAppLauncher` — routes/installs (or removes/restores) the
+/// launcher per the plan; logs the frozen user-visible messages; returns the
+/// plan.
+pub async fn install_codex_app_launcher(
+    options: &AppLauncherOptions,
+) -> Result<AppLauncherPlan, String> {
+    let plan = resolve_app_launcher_plan(options);
+
+    if plan.platform == "win32" {
+        let result = install_windows_shortcut(&plan, options).await?;
+        let routed_count = array_len(&result, "routed");
+        let restored_count = array_len(&result, "restored");
+        let packaged_app_count = array_len(&result, "packagedApps");
+        if options.remove {
+            let prefix = if options.dry_run {
+                "[dry-run] Would restore"
+            } else {
+                "Restored"
+            };
+            options.log(&format!(
+                "{prefix} {restored_count} Codex app shortcut(s) from {}",
+                plan.backup_path
+                    .as_ref()
+                    .map(|path| path.to_string_lossy().into_owned())
+                    .unwrap_or_default()
+            ));
+            return Ok(plan);
+        }
+        if routed_count == 0 {
+            let prefix = if options.dry_run { "[dry-run] No" } else { "No" };
+            options.log(&format!(
+                "{prefix} existing Codex app shortcuts or taskbar pins found to route through codex-multi-auth."
+            ));
+            if packaged_app_count > 0 {
+                options.log(&format!(
+                    "Detected {packaged_app_count} packaged Codex app entry; packaged app entries cannot be retargeted without a persistent background router."
+                ));
+            }
+            return Ok(plan);
+        }
+        let prefix = if options.dry_run {
+            "[dry-run] Would route"
+        } else {
+            "Routed"
+        };
+        options.log(&format!(
+            "{prefix} {routed_count} existing Codex app shortcut(s) through codex-multi-auth"
+        ));
+        if options.dry_run {
+            options.log(&format!(
+                "[dry-run] Target: {} {}",
+                plan.command_path.to_string_lossy(),
+                plan.command_args
+            ));
+        }
+        return Ok(plan);
+    }
+
+    if options.remove {
+        if options.dry_run {
+            options.log(&format!(
+                "[dry-run] Would remove {}",
+                plan.launcher_path.to_string_lossy()
+            ));
+            return Ok(plan);
+        }
+        remove_path_recursive(&plan.launcher_path).await?;
+        options.log(&format!(
+            "Removed {MANAGED_LAUNCHER_NAME} app launcher: {}",
+            plan.launcher_path.to_string_lossy()
+        ));
+        return Ok(plan);
+    }
+
+    if options.dry_run {
+        options.log(&format!(
+            "[dry-run] Would install {MANAGED_LAUNCHER_NAME} app launcher: {}",
+            plan.launcher_path.to_string_lossy()
+        ));
+        options.log(&format!(
+            "[dry-run] Target: {} {}",
+            plan.command_path.to_string_lossy(),
+            plan.command_args
+        ));
+        return Ok(plan);
+    }
+
+    if plan.platform == "darwin" {
+        install_mac_app_bundle(&plan).await?;
+    } else {
+        install_linux_desktop_file(&plan).await?;
+    }
+    options.log(&format!(
+        "Installed {MANAGED_LAUNCHER_NAME} app launcher: {}",
+        plan.launcher_path.to_string_lossy()
+    ));
+    Ok(plan)
+}
+
+fn print_help() {
+    println!(
+        "{}",
+        [
+            "Usage: codex-multi-auth-app-launcher [--remove] [--dry-run]",
+            "",
+            "Routes existing user-level Codex app shortcuts through codex-multi-auth on Windows.",
+            &format!(
+                "On other platforms, installs a user-level {MANAGED_LAUNCHER_NAME} app launcher that runs `codex app` through codex-multi-auth."
+            ),
+            "",
+            "Options:",
+            "  --remove   Remove the managed launcher",
+            "  --dry-run  Print planned changes without writing",
+            "  --help     Show this help",
+            "",
+        ]
+        .join("\n")
+    );
+}
+
+/// Binary entry (`codex-multi-auth-app-launcher`, ARCHITECTURE §2): `--help`
+/// prints usage; otherwise install/remove with `--dry-run`/`--remove`. Errors
+/// print `Codex app launcher routing failed: <message>` to stderr, exit 1.
+pub async fn run(args: &[String]) -> i32 {
+    let arg_set: std::collections::HashSet<&str> =
+        args.iter().map(String::as_str).collect();
+    if arg_set.contains("--help") || arg_set.contains("-h") {
+        print_help();
+        return 0;
+    }
+    let options = AppLauncherOptions {
+        dry_run: arg_set.contains("--dry-run"),
+        remove: arg_set.contains("--remove"),
+        ..AppLauncherOptions::default()
+    };
+    match install_codex_app_launcher(&options).await {
+        Ok(_) => 0,
+        Err(error) => {
+            eprintln!("Codex app launcher routing failed: {error}");
+            1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn env_of(pairs: &[(&str, &str)]) -> EnvMap {
+        pairs
+            .iter()
+            .map(|(key, value)| (key.to_string(), value.to_string()))
+            .collect()
+    }
+
+    fn options(platform: &str, home: &Path, env: EnvMap) -> AppLauncherOptions {
+        AppLauncherOptions {
+            env: Some(env),
+            platform: Some(platform.to_string()),
+            home: Some(home.to_path_buf()),
+            codex_bin_path: Some(home.join("bin").join("codex-multi-auth-codex")),
+            ..AppLauncherOptions::default()
+        }
+    }
+
+    #[test]
+    fn base64_utf16le_encoding_matches_node_buffer_output() {
+        // Buffer.from("ab", "utf16le").toString("base64") === "YQBiAA=="
+        assert_eq!(encode_powershell_command("ab"), "YQBiAA==");
+        // Buffer.from("$x = 1", "utf16le").toString("base64")
+        assert_eq!(encode_powershell_command("$x = 1"), "JAB4ACAAPQAgADEA");
+        assert_eq!(base64_encode(b""), "");
+        assert_eq!(base64_encode(b"f"), "Zg==");
+        assert_eq!(base64_encode(b"fo"), "Zm8=");
+        assert_eq!(base64_encode(b"foo"), "Zm9v");
+    }
+
+    #[test]
+    fn quoting_helpers_match_js() {
+        assert_eq!(quote_powershell_single("a'b"), "'a''b'");
+        assert_eq!(quote_powershell_boolean(true), "$true");
+        assert_eq!(quote_powershell_array(&[]), "@()");
+        assert_eq!(
+            quote_powershell_array(&["a".to_string(), "b'c".to_string()]),
+            "@('a', 'b''c')"
+        );
+        assert_eq!(quote_desktop_exec("C:\\x \"y\""), "\"C:\\\\x \\\"y\\\"\"");
+        assert_eq!(quote_posix_shell("a'b"), "'a'\\''b'");
+    }
+
+    #[test]
+    fn resolves_windows_route_existing_plan() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let app_data = home.join("Roaming");
+        let env = env_of(&[
+            ("APPDATA", &app_data.to_string_lossy()),
+            ("CODEX_MULTI_AUTH_DIR", &home.join("mad").to_string_lossy()),
+            ("OneDrive", &home.join("OneDrive").to_string_lossy()),
+            ("SystemRoot", "C:\\Windows"),
+        ]);
+        let plan = resolve_app_launcher_plan(&options("win32", home, env));
+        assert_eq!(plan.mode, AppLauncherMode::RouteExisting);
+        let start_menu = app_data
+            .join("Microsoft")
+            .join("Windows")
+            .join("Start Menu")
+            .join("Programs");
+        assert_eq!(plan.launcher_path, start_menu.join("Codex.lnk"));
+        assert_eq!(
+            plan.backup_path,
+            Some(home.join("mad").join(WINDOWS_BACKUP_FILE_NAME))
+        );
+        // Roots: start menu, taskbar pins, OneDrive desktop, home desktop.
+        assert_eq!(plan.shortcut_roots[0], start_menu);
+        assert!(plan
+            .shortcut_roots
+            .iter()
+            .any(|root| root.ends_with("TaskBar")));
+        assert!(plan
+            .shortcut_roots
+            .contains(&home.join("OneDrive").join("Desktop")));
+        assert!(plan.shortcut_roots.contains(&home.join("Desktop")));
+        assert_eq!(
+            plan.command_path,
+            PathBuf::from("C:\\Windows")
+                .join("System32")
+                .join("WindowsPowerShell")
+                .join("v1.0")
+                .join("powershell.exe")
+        );
+        assert!(plan
+            .command_args
+            .starts_with("-NoProfile -ExecutionPolicy Bypass -EncodedCommand "));
+        assert_eq!(plan.command_argv, vec!["app".to_string()]);
+        assert_eq!(plan.working_directory, home);
+    }
+
+    #[test]
+    fn resolves_linux_and_mac_create_managed_plans() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let wrapper = home.join("bin").join("codex-multi-auth-codex");
+
+        let linux_plan = resolve_app_launcher_plan(&options("linux", home, EnvMap::new()));
+        assert_eq!(linux_plan.mode, AppLauncherMode::CreateManaged);
+        assert_eq!(
+            linux_plan.launcher_path,
+            home.join(".local")
+                .join("share")
+                .join("applications")
+                .join(LINUX_DESKTOP_FILE_NAME)
+        );
+        assert_eq!(linux_plan.command_path, wrapper);
+        assert_eq!(linux_plan.command_args, "app %F");
+        assert_eq!(
+            linux_plan.command_argv,
+            vec!["app".to_string(), "%F".to_string()]
+        );
+        assert_eq!(linux_plan.icon_path, "utilities-terminal");
+
+        let xdg = env_of(&[("XDG_DATA_HOME", &home.join("xdg").to_string_lossy())]);
+        let xdg_plan = resolve_app_launcher_plan(&options("linux", home, xdg));
+        assert_eq!(
+            xdg_plan.launcher_path,
+            home.join("xdg").join("applications").join(LINUX_DESKTOP_FILE_NAME)
+        );
+
+        let mac_plan = resolve_app_launcher_plan(&options("darwin", home, EnvMap::new()));
+        assert_eq!(mac_plan.mode, AppLauncherMode::CreateManaged);
+        assert_eq!(
+            mac_plan.launcher_path,
+            home.join("Applications").join(MACOS_APP_NAME)
+        );
+        assert_eq!(mac_plan.command_args, "app");
+        let mac_dir = env_of(&[(
+            "CODEX_MULTI_AUTH_APP_LAUNCHER_MACOS_DIR",
+            &home.join("Custom").to_string_lossy(),
+        )]);
+        let custom_mac = resolve_app_launcher_plan(&options("darwin", home, mac_dir));
+        assert_eq!(
+            custom_mac.launcher_path,
+            home.join("Custom").join(MACOS_APP_NAME)
+        );
+    }
+
+    #[test]
+    fn windows_powershell_script_contains_frozen_markers() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let env = env_of(&[("CODEX_MULTI_AUTH_DIR", &home.join("m'ad").to_string_lossy())]);
+        let plan = resolve_app_launcher_plan(&options("win32", home, env));
+
+        let route = create_windows_shortcut_powershell_script(&plan, true, false);
+        assert!(route.starts_with("$ErrorActionPreference = 'Stop'\r\n$DryRun = $true"));
+        assert!(route.contains("$ShortcutName = 'Codex'"));
+        assert!(route.contains(
+            "$ManagedDescription = 'Launch Codex through codex-multi-auth runtime rotation'"
+        ));
+        // Single-quote escaping in the backup path.
+        assert!(route.contains("m''ad"));
+        assert!(route.contains("ConvertTo-Json -Depth 6 -Compress"));
+        assert!(route.contains("$Result = [ordered]@{ action = 'route';"));
+
+        let restore = create_windows_shortcut_powershell_script(&plan, false, true);
+        assert!(restore.contains("$DryRun = $false"));
+        assert!(restore.contains("$Result = [ordered]@{ action = 'restore';"));
+        assert!(restore.contains("Remove-Item -LiteralPath $BackupPath -Force"));
+    }
+
+    #[test]
+    fn linux_desktop_file_and_mac_bundle_contents() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let wrapper = home.join("bin").join("codex-multi-auth-codex");
+        let linux_plan = resolve_app_launcher_plan(&options("linux", home, EnvMap::new()));
+        let desktop = create_linux_desktop_file(&linux_plan);
+        assert!(desktop.starts_with("[Desktop Entry]\nType=Application\n"));
+        assert!(desktop.contains("Name=Codex Multi Auth"));
+        assert!(desktop.contains(&format!(
+            "Exec={} app %F",
+            quote_desktop_exec(&wrapper.to_string_lossy())
+        )));
+        assert!(desktop.contains("Terminal=false"));
+        assert!(desktop.ends_with("StartupNotify=true\n"));
+
+        let mac_plan = resolve_app_launcher_plan(&options("darwin", home, EnvMap::new()));
+        let plist = create_mac_info_plist();
+        assert!(plist.contains("<string>com.ndycode.codex-multi-auth.launcher</string>"));
+        assert!(plist.contains("<string>Codex Multi Auth</string>"));
+        assert!(plist.ends_with("</plist>\n"));
+        let script = create_mac_launcher_script(&mac_plan);
+        assert!(script.starts_with("#!/bin/sh\n"));
+        assert!(script.contains(&format!(
+            "exec {} 'app'",
+            quote_posix_shell(&wrapper.to_string_lossy())
+        )));
+        assert!(script.ends_with("\n"));
+    }
+
+    #[tokio::test]
+    async fn installs_and_removes_the_linux_desktop_launcher() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let logs: Arc<std::sync::Mutex<Vec<String>>> =
+            Arc::new(std::sync::Mutex::new(Vec::new()));
+        let log_sink = {
+            let logs = logs.clone();
+            Arc::new(move |message: &str| {
+                logs.lock().unwrap().push(message.to_string());
+            })
+        };
+        let mut install_options = options("linux", home, EnvMap::new());
+        install_options.log = Some(log_sink.clone());
+        let plan = install_codex_app_launcher(&install_options)
+            .await
+            .expect("install succeeds");
+        assert!(plan.launcher_path.exists());
+        assert!(logs
+            .lock()
+            .unwrap()
+            .iter()
+            .any(|line| line
+                == &format!(
+                    "Installed Codex Multi Auth app launcher: {}",
+                    plan.launcher_path.to_string_lossy()
+                )));
+
+        // Dry-run remove leaves the file and prints the plan.
+        let mut dry_remove = options("linux", home, EnvMap::new());
+        dry_remove.remove = true;
+        dry_remove.dry_run = true;
+        dry_remove.log = Some(log_sink.clone());
+        install_codex_app_launcher(&dry_remove).await.unwrap();
+        assert!(plan.launcher_path.exists());
+        assert!(logs
+            .lock()
+            .unwrap()
+            .iter()
+            .any(|line| line.starts_with("[dry-run] Would remove ")));
+
+        let mut remove_options = options("linux", home, EnvMap::new());
+        remove_options.remove = true;
+        remove_options.log = Some(log_sink);
+        install_codex_app_launcher(&remove_options).await.unwrap();
+        assert!(!plan.launcher_path.exists());
+        assert!(logs
+            .lock()
+            .unwrap()
+            .iter()
+            .any(|line| line.starts_with("Removed Codex Multi Auth app launcher: ")));
+    }
+
+    #[tokio::test]
+    async fn installs_the_mac_app_bundle_shape() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let mut install_options = options("darwin", home, EnvMap::new());
+        install_options.log = Some(Arc::new(|_message: &str| {}));
+        let plan = install_codex_app_launcher(&install_options)
+            .await
+            .expect("install succeeds");
+        assert!(plan.launcher_path.join("Contents").join("Info.plist").exists());
+        assert!(plan
+            .launcher_path
+            .join("Contents")
+            .join("MacOS")
+            .join("Codex")
+            .exists());
+        // Remove deletes the whole bundle directory.
+        let mut remove_options = options("darwin", home, EnvMap::new());
+        remove_options.remove = true;
+        remove_options.log = Some(Arc::new(|_message: &str| {}));
+        install_codex_app_launcher(&remove_options).await.unwrap();
+        assert!(!plan.launcher_path.exists());
+    }
+
+    #[tokio::test]
+    async fn dry_run_install_prints_target_without_writing() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let logs: Arc<std::sync::Mutex<Vec<String>>> =
+            Arc::new(std::sync::Mutex::new(Vec::new()));
+        let mut dry = options("linux", home, EnvMap::new());
+        dry.dry_run = true;
+        dry.log = Some({
+            let logs = logs.clone();
+            Arc::new(move |message: &str| logs.lock().unwrap().push(message.to_string()))
+        });
+        let plan = install_codex_app_launcher(&dry).await.unwrap();
+        assert!(!plan.launcher_path.exists());
+        let logs = logs.lock().unwrap();
+        assert!(logs
+            .iter()
+            .any(|line| line.starts_with("[dry-run] Would install Codex Multi Auth app launcher: ")));
+        assert!(logs
+            .iter()
+            .any(|line| line.starts_with("[dry-run] Target: ")));
+    }
+}
diff --git a/crates/runtime/src/capability_boost.rs b/crates/runtime/src/capability_boost.rs
new file mode 100644
index 000000000..eb90566e3
--- /dev/null
+++ b/crates/runtime/src/capability_boost.rs
@@ -0,0 +1,209 @@
+//! Port of `lib/runtime/capability-boost.ts` — per-account capability
+//! boost vector for the rotation selector (spec 10 §22 + gotcha 22,
+//! ARCHITECTURE §6.12).
+//!
+//! The TS function returned a SPARSE `number[]` (unassigned slots stay
+//! holes/`undefined`); the faithful Rust representation is
+//! `Vec<Option<f64>>` — the selector consumer merges only the `Some`
+//! entries into its boost map, exactly like the JS holes contributed
+//! nothing.
+
+use cma_accounts::entitlement_cache::{resolve_entitlement_account_key, EntitlementAccountRef};
+
+/// TS `AccountSnapshotCandidate` (the fields the boost calc reads —
+/// `resolve_entitlement_account_key` uses id/email/index).
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct AccountSnapshotCandidate {
+    /// TS `index: number` — may be negative/out-of-range (skipped).
+    pub index: i64,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub account_label: Option<String>,
+}
+
+/// The snapshot source pair (TS `accountSnapshotSource`): prefer
+/// `get_accounts_snapshot`; when it yields an empty list and
+/// `get_account_by_index` exists, build the list by probing indexes
+/// `0..account_count`.
+pub struct AccountSnapshotSource<'a> {
+    pub get_accounts_snapshot: Option<&'a dyn Fn() -> Vec<AccountSnapshotCandidate>>,
+    pub get_account_by_index: Option<&'a dyn Fn(usize) -> Option<AccountSnapshotCandidate>>,
+}
+
+/// TS `buildCapabilityBoostByAccount(input)` — one slot per pool index;
+/// capability key = `model ?? modelFamily`.
+pub fn build_capability_boost_by_account(
+    account_count: usize,
+    model: Option<&str>,
+    model_family: &str,
+    account_snapshot_source: &AccountSnapshotSource<'_>,
+    get_boost: &mut dyn FnMut(&str, &str) -> f64,
+) -> Vec<Option<f64>> {
+    let mut boosts: Vec<Option<f64>> = vec![None; account_count];
+
+    let mut account_snapshot_list = account_snapshot_source
+        .get_accounts_snapshot
+        .map(|get| get())
+        .unwrap_or_default();
+
+    if account_snapshot_list.is_empty()
+        && let Some(get_account_by_index) = account_snapshot_source.get_account_by_index
+    {
+        for account_snapshot_index in 0..account_count {
+            if let Some(candidate) = get_account_by_index(account_snapshot_index) {
+                account_snapshot_list.push(candidate);
+            }
+        }
+    }
+
+    let capability_key = model.unwrap_or(model_family);
+    for candidate in account_snapshot_list {
+        if candidate.index < 0 || candidate.index as usize >= boosts.len() {
+            continue;
+        }
+        let account_key = resolve_entitlement_account_key(&EntitlementAccountRef {
+            account_id: candidate.account_id.clone(),
+            email: candidate.email.clone(),
+            refresh_token: None,
+            index: Some(candidate.index),
+        });
+        boosts[candidate.index as usize] = Some(get_boost(&account_key, capability_key));
+    }
+
+    boosts
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn keeps_sparse_slots_and_prefers_model_over_model_family() {
+        let mut calls: Vec<(String, String)> = Vec::new();
+        let mut returns = vec![7.0, 5.0]; // popped in reverse
+        let mut get_boost = |account_key: &str, capability_key: &str| {
+            calls.push((account_key.to_string(), capability_key.to_string()));
+            returns.pop().unwrap()
+        };
+        let snapshot = || {
+            vec![
+                AccountSnapshotCandidate {
+                    index: 1,
+                    account_id: Some("acc_1".to_string()),
+                    ..Default::default()
+                },
+                AccountSnapshotCandidate {
+                    index: 3,
+                    email: Some("User@example.com".to_string()),
+                    ..Default::default()
+                },
+            ]
+        };
+
+        let boosts = build_capability_boost_by_account(
+            4,
+            Some("gpt-5-codex"),
+            "codex",
+            &AccountSnapshotSource {
+                get_accounts_snapshot: Some(&snapshot),
+                get_account_by_index: None,
+            },
+            &mut get_boost,
+        );
+
+        assert_eq!(boosts.len(), 4);
+        assert_eq!(boosts[0], None); // hole
+        assert_eq!(boosts[1], Some(5.0));
+        assert_eq!(boosts[2], None); // hole
+        assert_eq!(boosts[3], Some(7.0));
+        assert_eq!(
+            calls,
+            vec![
+                (
+                    "account:acc_1::idx:1".to_string(),
+                    "gpt-5-codex".to_string()
+                ),
+                ("email:user@example.com".to_string(), "gpt-5-codex".to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn falls_back_to_get_account_by_index_and_skips_invalid_snapshot_indices() {
+        let mut calls: Vec<(String, String)> = Vec::new();
+        let mut returns = vec![22.0, 11.0];
+        let mut get_boost = |account_key: &str, capability_key: &str| {
+            calls.push((account_key.to_string(), capability_key.to_string()));
+            returns.pop().unwrap()
+        };
+        let empty_snapshot = Vec::new;
+        let probe_count = std::cell::Cell::new(0usize);
+        let get_account_by_index = |index: usize| -> Option<AccountSnapshotCandidate> {
+            probe_count.set(probe_count.get() + 1);
+            match index {
+                0 => Some(AccountSnapshotCandidate {
+                    index: 0,
+                    account_id: Some("acc_0".to_string()),
+                    ..Default::default()
+                }),
+                1 => Some(AccountSnapshotCandidate {
+                    index: -1,
+                    email: Some("ignored-negative@example.com".to_string()),
+                    ..Default::default()
+                }),
+                2 => Some(AccountSnapshotCandidate {
+                    index: 5,
+                    email: Some("ignored-out-of-range@example.com".to_string()),
+                    ..Default::default()
+                }),
+                3 => Some(AccountSnapshotCandidate {
+                    index: 2,
+                    email: Some("final@example.com".to_string()),
+                    ..Default::default()
+                }),
+                _ => None,
+            }
+        };
+
+        let boosts = build_capability_boost_by_account(
+            4,
+            None,
+            "codex",
+            &AccountSnapshotSource {
+                get_accounts_snapshot: Some(&empty_snapshot),
+                get_account_by_index: Some(&get_account_by_index),
+            },
+            &mut get_boost,
+        );
+
+        assert_eq!(boosts.len(), 4);
+        assert_eq!(boosts[0], Some(11.0));
+        assert_eq!(boosts[1], None);
+        assert_eq!(boosts[2], Some(22.0));
+        assert_eq!(boosts[3], None);
+        assert_eq!(probe_count.get(), 4);
+        assert_eq!(
+            calls,
+            vec![
+                ("account:acc_0::idx:0".to_string(), "codex".to_string()),
+                ("email:final@example.com".to_string(), "codex".to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn zero_account_count_yields_an_empty_vector() {
+        let mut get_boost = |_k: &str, _c: &str| panic!("no boost expected");
+        let boosts = build_capability_boost_by_account(
+            0,
+            None,
+            "codex",
+            &AccountSnapshotSource {
+                get_accounts_snapshot: None,
+                get_account_by_index: None,
+            },
+            &mut get_boost,
+        );
+        assert!(boosts.is_empty());
+    }
+}
diff --git a/crates/runtime/src/config_toml.rs b/crates/runtime/src/config_toml.rs
new file mode 100644
index 000000000..40364eed4
--- /dev/null
+++ b/crates/runtime/src/config_toml.rs
@@ -0,0 +1,830 @@
+//! Port of `lib/runtime/config-toml.ts` — byte-exact line/string manipulation
+//! over Codex's `config.toml`.
+//!
+//! NOT a real TOML parser: line-based rewriting with the file's dominant EOL
+//! preserved (any `\r\n` in the input ⇒ output joined with `\r\n`, else `\n`).
+//! `boundConfigHash` in the app-bind state is the sha256 of the exact rewrite
+//! output, so every helper here must reproduce the TS byte-for-byte: the single
+//! blank line before the provider block, `experimental_bearer_token` inserted
+//! at index 4, uppercase `\uXXXX` escapes, and the LF-only final newline of
+//! `ensure_toml_trailing_newline` even in CRLF files (except the
+//! `..._without_backup` path, which force-normalizes ALL EOLs to the input
+//! style). See spec 10 §2 + gotcha 1.
+
+use cma_core::constants::RUNTIME_ROTATION_PROXY_PROVIDER_ID;
+
+/// Double-quoted TOML basic string; escapes control chars (U+0000–U+001F,
+/// U+007F), `\` and `"`. Named escapes for `\b \t \n \f \r " \\`; everything
+/// else in the class becomes `\uXXXX` with UPPERCASE 4-hex digits.
+pub fn toml_string_literal(value: &str) -> String {
+    let mut out = String::with_capacity(value.len() + 2);
+    out.push('"');
+    for character in value.chars() {
+        match character {
+            '\u{0008}' => out.push_str("\\b"),
+            '\t' => out.push_str("\\t"),
+            '\n' => out.push_str("\\n"),
+            '\u{000c}' => out.push_str("\\f"),
+            '\r' => out.push_str("\\r"),
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            c if (c as u32) <= 0x001f || c as u32 == 0x007f => {
+                out.push_str(&format!("\\u{:04X}", c as u32));
+            }
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+    out
+}
+
+/// `readTomlTableName` — emulates `^\s*\[{1,2}\s*([^\]]+?)\s*\]{1,2}\s*$`.
+/// Returns the trimmed table name for `[t]` / `[[t]]` headers, else `None`.
+fn read_toml_table_name(line: &str) -> Option<&str> {
+    let trimmed = line.trim_matches(is_js_whitespace);
+    if !trimmed.starts_with('[') || !trimmed.ends_with(']') {
+        return None;
+    }
+    let open = if trimmed.starts_with("[[") { 2 } else { 1 };
+    let close = if trimmed.ends_with("]]") { 2 } else { 1 };
+    if trimmed.len() < open + close {
+        return None;
+    }
+    let inner = &trimmed[open..trimmed.len() - close];
+    let name = inner.trim_matches(is_js_whitespace);
+    // `[^\]]+?` — the name may not contain `]` and must be non-empty.
+    if name.is_empty() || name.contains(']') {
+        return None;
+    }
+    Some(name)
+}
+
+/// JS `\s` approximation (Unicode whitespace + BOM; `char::is_whitespace`
+/// covers the JS class for every character plausible in a config file).
+fn is_js_whitespace(c: char) -> bool {
+    c.is_whitespace() || c == '\u{feff}'
+}
+
+/// `rawConfig.split(/\r?\n/)` — split on `\n`, stripping ONE optional
+/// preceding `\r` from each piece.
+fn split_lines(raw: &str) -> Vec<&str> {
+    raw.split('\n')
+        .map(|piece| piece.strip_suffix('\r').unwrap_or(piece))
+        .collect()
+}
+
+/// `rawConfig.length > 0 ? split : []` guard used by several helpers.
+fn split_lines_guarded(raw: &str) -> Vec<&str> {
+    if raw.is_empty() {
+        Vec::new()
+    } else {
+        split_lines(raw)
+    }
+}
+
+fn dominant_eol(raw: &str) -> &'static str {
+    if raw.contains("\r\n") { "\r\n" } else { "\n" }
+}
+
+/// `/^\s*<key>\s*=/` test.
+fn is_key_assignment(line: &str, key: &str) -> bool {
+    let rest = line.trim_start_matches(is_js_whitespace);
+    let Some(rest) = rest.strip_prefix(key) else {
+        return false;
+    };
+    rest.trim_start_matches(is_js_whitespace).starts_with('=')
+}
+
+/// `/^\s*disable_response_storage\s*=\s*true\s*(?:#.*)?$/i` test.
+fn is_disable_response_storage_true(line: &str) -> bool {
+    let lower = line.to_lowercase();
+    let rest = lower.trim_start_matches(is_js_whitespace);
+    let Some(rest) = rest.strip_prefix("disable_response_storage") else {
+        return false;
+    };
+    let rest = rest.trim_start_matches(is_js_whitespace);
+    let Some(rest) = rest.strip_prefix('=') else {
+        return false;
+    };
+    let rest = rest.trim_start_matches(is_js_whitespace);
+    let Some(rest) = rest.strip_prefix("true") else {
+        return false;
+    };
+    let rest = rest.trim_start_matches(is_js_whitespace);
+    rest.is_empty() || rest.starts_with('#')
+}
+
+/// Strip ALL trailing `\r`/`\n` characters (`.replace(/[\r\n]*$/, "")`).
+fn strip_trailing_newlines(value: &str) -> &str {
+    value.trim_end_matches(['\r', '\n'])
+}
+
+/// `ensureTomlTrailingNewline` — `value.replace(/[\r\n]*$/, "\n")`. The final
+/// newline is always LF even in CRLF files (deliberate/observed TS behavior).
+fn ensure_toml_trailing_newline(value: &str) -> String {
+    format!("{}\n", strip_trailing_newlines(value))
+}
+
+fn provider_table_name() -> String {
+    format!("model_providers.{RUNTIME_ROTATION_PROXY_PROVIDER_ID}")
+}
+
+fn remove_runtime_rotation_provider_block(raw_config: &str) -> String {
+    let lines = split_lines(raw_config);
+    let provider_table = provider_table_name();
+    let child_prefix = format!("{provider_table}.");
+    let mut output: Vec<&str> = Vec::with_capacity(lines.len());
+    let mut skipping = false;
+    for line in lines {
+        let table_name = read_toml_table_name(line);
+        if table_name == Some(provider_table.as_str()) {
+            skipping = true;
+            continue;
+        }
+        if skipping && let Some(name) = table_name {
+            if name == provider_table || name.starts_with(child_prefix.as_str()) {
+                continue;
+            }
+            skipping = false;
+        }
+        if !skipping {
+            output.push(line);
+        }
+    }
+    output.join(dominant_eol(raw_config))
+}
+
+fn rewrite_top_level_model_provider(raw_config: &str) -> String {
+    let line_ending = dominant_eol(raw_config);
+    let lines = split_lines_guarded(raw_config);
+    let rewritten_line = format!(
+        "model_provider = {}",
+        toml_string_literal(RUNTIME_ROTATION_PROXY_PROVIDER_ID)
+    );
+    let mut replaced = false;
+    let mut output: Vec<String> = Vec::with_capacity(lines.len() + 1);
+
+    for line in lines {
+        let is_table = read_toml_table_name(line).is_some();
+        if !replaced && is_table {
+            output.push(rewritten_line.clone());
+            replaced = true;
+        }
+        if !replaced && is_key_assignment(line, "model_provider") {
+            output.push(rewritten_line.clone());
+            replaced = true;
+            continue;
+        }
+        output.push(line.to_string());
+    }
+
+    if !replaced {
+        output.push(rewritten_line);
+    }
+    output.join(line_ending)
+}
+
+fn enable_top_level_response_storage(raw_config: &str) -> String {
+    let line_ending = dominant_eol(raw_config);
+    let lines = split_lines_guarded(raw_config);
+    let mut output: Vec<String> = Vec::with_capacity(lines.len());
+    let mut in_top_level = true;
+
+    for line in lines {
+        if read_toml_table_name(line).is_some() {
+            in_top_level = false;
+            output.push(line.to_string());
+            continue;
+        }
+        if in_top_level && is_disable_response_storage_true(line) {
+            output.push("disable_response_storage = false".to_string());
+            continue;
+        }
+        output.push(line.to_string());
+    }
+
+    output.join(line_ending)
+}
+
+/// Verbatim first `^\s*<key>\s*=` line (incl. indentation/comment) before any
+/// table header.
+fn extract_top_level_line<'a>(raw_config: &'a str, key: &str) -> Option<&'a str> {
+    for line in split_lines(raw_config) {
+        if read_toml_table_name(line).is_some() {
+            return None;
+        }
+        if is_key_assignment(line, key) {
+            return Some(line);
+        }
+    }
+    None
+}
+
+/// Replaces the first `model_provider = …` line containing the proxy id with
+/// the original config's top-level `model_provider` line (or drops it when the
+/// original had none). Un-replaced original lines are spliced back before the
+/// first section header only when the current config has no top-level
+/// `model_provider` at all (avoids duplicate keys on half-orphaned configs).
+pub fn restore_top_level_model_provider(current_config: &str, original_config: &str) -> String {
+    let line_ending = dominant_eol(current_config);
+    let original_line = extract_top_level_line(original_config, "model_provider");
+    let lines = split_lines_guarded(current_config);
+    let mut output: Vec<String> = Vec::with_capacity(lines.len() + 1);
+    let mut handled = false;
+
+    for line in lines {
+        let is_runtime_provider_line = is_key_assignment(line, "model_provider")
+            && line.contains(RUNTIME_ROTATION_PROXY_PROVIDER_ID);
+        if is_runtime_provider_line && !handled {
+            if let Some(original) = original_line {
+                output.push(original.to_string());
+            }
+            handled = true;
+            continue;
+        }
+        output.push(line.to_string());
+    }
+
+    if !handled && let Some(original) = original_line {
+        let has_top_level_model_provider = {
+            let mut found = false;
+            for line in &output {
+                if read_toml_table_name(line).is_some() {
+                    break;
+                }
+                if is_key_assignment(line, "model_provider") {
+                    found = true;
+                    break;
+                }
+            }
+            found
+        };
+        if !has_top_level_model_provider {
+            // Splice the restored line into the root table — appending at tail
+            // would land it inside whatever section appears last.
+            let first_section_idx = output
+                .iter()
+                .position(|line| read_toml_table_name(line).is_some());
+            match first_section_idx {
+                None => output.push(original.to_string()),
+                Some(idx) => output.insert(idx, original.to_string()),
+            }
+        }
+    }
+
+    output.join(line_ending)
+}
+
+/// Same pattern for `disable_response_storage`: replaces the first top-level
+/// occurrence with the original line (or drops the bind-written residue when
+/// the original had none); un-replaced original lines are spliced before the
+/// first section header.
+pub fn restore_top_level_response_storage(current_config: &str, original_config: &str) -> String {
+    let line_ending = dominant_eol(current_config);
+    let original_line = extract_top_level_line(original_config, "disable_response_storage");
+    let lines = split_lines_guarded(current_config);
+    let mut output: Vec<String> = Vec::with_capacity(lines.len() + 1);
+    let mut handled = false;
+    let mut in_top_level = true;
+
+    for line in lines {
+        if read_toml_table_name(line).is_some() {
+            in_top_level = false;
+            output.push(line.to_string());
+            continue;
+        }
+        if !handled && in_top_level && is_key_assignment(line, "disable_response_storage") {
+            if let Some(original) = original_line {
+                output.push(original.to_string());
+            }
+            // If no original line, drop the line we wrote during bind.
+            handled = true;
+            continue;
+        }
+        output.push(line.to_string());
+    }
+
+    if !handled && let Some(original) = original_line {
+        // Mirror restore_top_level_model_provider: splice before the first
+        // section header instead of appending at tail.
+        let first_section_idx = output
+            .iter()
+            .position(|line| read_toml_table_name(line).is_some());
+        match first_section_idx {
+            None => output.push(original.to_string()),
+            Some(idx) => output.insert(idx, original.to_string()),
+        }
+    }
+
+    output.join(line_ending)
+}
+
+fn create_runtime_rotation_provider_block(base_url: &str, client_api_key: &str) -> Vec<String> {
+    let mut lines = vec![
+        format!("[model_providers.{RUNTIME_ROTATION_PROXY_PROVIDER_ID}]"),
+        "name = \"codex-multi-auth\"".to_string(),
+        format!("base_url = {}", toml_string_literal(base_url)),
+        "requires_openai_auth = false".to_string(),
+        "wire_api = \"responses\"".to_string(),
+    ];
+    if !client_api_key.trim().is_empty() {
+        lines.insert(
+            4,
+            format!(
+                "experimental_bearer_token = {}",
+                toml_string_literal(client_api_key)
+            ),
+        );
+    }
+    lines
+}
+
+/// Bind rewrite: strip any existing proxy provider block, rewrite/insert the
+/// top-level `model_provider`, flip a top-level `disable_response_storage =
+/// true` to `false`, then append the provider block after one blank line.
+/// Output always ends with exactly one EOL (the input's dominant style).
+pub fn rewrite_config_toml_for_runtime_rotation_provider(
+    raw_config: &str,
+    base_url: &str,
+    client_api_key: &str,
+) -> String {
+    let line_ending = dominant_eol(raw_config);
+    let without_old_provider = remove_runtime_rotation_provider_block(raw_config);
+    let without_old_provider = strip_trailing_newlines(&without_old_provider);
+    let with_model_provider = rewrite_top_level_model_provider(without_old_provider);
+    let with_model_provider = strip_trailing_newlines(&with_model_provider);
+    let with_response_storage = enable_top_level_response_storage(with_model_provider);
+    let with_response_storage = strip_trailing_newlines(&with_response_storage);
+    let provider_block =
+        create_runtime_rotation_provider_block(base_url, client_api_key).join(line_ending);
+    format!("{with_response_storage}{line_ending}{line_ending}{provider_block}{line_ending}")
+}
+
+/// Unbind restore: strip the provider block, restore the original top-level
+/// `disable_response_storage` line, restore the original top-level
+/// `model_provider` line; trailing whitespace normalized to a single `\n`
+/// (LF even in CRLF files — deliberate TS behavior).
+pub fn restore_config_toml_from_runtime_rotation_provider(
+    current_config: &str,
+    original_config: &str,
+) -> String {
+    let without_provider = remove_runtime_rotation_provider_block(current_config);
+    let with_response_storage =
+        restore_top_level_response_storage(&without_provider, original_config);
+    let restored = restore_top_level_model_provider(&with_response_storage, original_config);
+    ensure_toml_trailing_newline(strip_trailing_newlines(&restored))
+}
+
+/// True when the proxy table header exists anywhere, or a **top-level**
+/// `model_provider = …` line contains the proxy id. Empty string → false.
+/// Only lines before the first table header count as top-level. Used to
+/// recover an orphaned bind (#614) whose state/backup files were lost.
+pub fn config_has_runtime_rotation_provider(raw_config: &str) -> bool {
+    if raw_config.is_empty() {
+        return false;
+    }
+    let provider_table = provider_table_name();
+    let mut in_top_level = true;
+    for line in split_lines(raw_config) {
+        if let Some(table_name) = read_toml_table_name(line) {
+            if table_name == provider_table {
+                return true;
+            }
+            in_top_level = false;
+            continue;
+        }
+        if in_top_level
+            && is_key_assignment(line, "model_provider")
+            && line.contains(RUNTIME_ROTATION_PROXY_PROVIDER_ID)
+        {
+            return true;
+        }
+    }
+    false
+}
+
+/// Orphaned-bind recovery restore (no backup available): synthesizes a minimal
+/// original config of `model_provider = "<default_provider>"` and runs the
+/// shared restore, then force-normalizes ALL line endings of the result to the
+/// input config's style (CRLF stays CRLF, LF stays LF) — this is the one
+/// restore path with full-EOL normalization.
+pub fn restore_config_toml_from_runtime_rotation_provider_without_backup(
+    current_config: &str,
+    default_provider: Option<&str>,
+) -> String {
+    let default_provider = default_provider.unwrap_or("openai");
+    let line_ending = dominant_eol(current_config);
+    let synthetic_original = format!(
+        "model_provider = {}{line_ending}",
+        toml_string_literal(default_provider)
+    );
+    let restored =
+        restore_config_toml_from_runtime_rotation_provider(current_config, &synthetic_original);
+    if line_ending == "\r\n" {
+        // `.replace(/\r?\n/g, "\r\n")` — every `\n` (with one optional
+        // preceding `\r`) becomes `\r\n`.
+        let mut out = String::with_capacity(restored.len() + 16);
+        let mut rest = restored.as_str();
+        while let Some(idx) = rest.find('\n') {
+            let (mut text, tail) = rest.split_at(idx);
+            if let Some(stripped) = text.strip_suffix('\r') {
+                text = stripped;
+            }
+            out.push_str(text);
+            out.push_str("\r\n");
+            rest = &tail[1..];
+        }
+        out.push_str(rest);
+        out
+    } else {
+        restored.replace("\r\n", "\n")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const PROXY_ID: &str = RUNTIME_ROTATION_PROXY_PROVIDER_ID;
+
+    // ----- tomlStringLiteral (app-bind.test.ts "escapes TOML basic-string control characters") -----
+
+    #[test]
+    fn escapes_toml_basic_string_control_characters() {
+        let input = "line\ncarriage\rtab\tbackspace\u{0008}form\u{000c}quote\"slash\\nul\u{0000}unit\u{001f}del\u{007f}";
+        assert_eq!(
+            toml_string_literal(input),
+            "\"line\\ncarriage\\rtab\\tbackspace\\bform\\fquote\\\"slash\\\\nul\\u0000unit\\u001Fdel\\u007F\""
+        );
+    }
+
+    // ----- rewrite + restore round trip (app-bind.test.ts) -----
+
+    #[test]
+    fn rewrites_and_restores_codex_config_toml_without_disturbing_other_sections() {
+        let original = [
+            "model_provider = \"openai\"",
+            "model = \"gpt-5.4\"",
+            "disable_response_storage = true",
+            "",
+            "[profiles.default]",
+            "model = \"gpt-5.4\"",
+            "disable_response_storage = true",
+            "",
+        ]
+        .join("\n");
+
+        let bound = rewrite_config_toml_for_runtime_rotation_provider(
+            &original,
+            "http://127.0.0.1:32123",
+            "app-secret",
+        );
+        assert!(bound.contains(&format!("model_provider = \"{PROXY_ID}\"")));
+        assert!(bound.contains(&format!("[model_providers.{PROXY_ID}]")));
+        assert!(bound.contains("name = \"codex-multi-auth\""));
+        assert!(bound.contains("base_url = \"http://127.0.0.1:32123\""));
+        assert!(bound.contains("requires_openai_auth = false"));
+        assert!(bound.contains("experimental_bearer_token = \"app-secret\""));
+        assert!(bound.contains("wire_api = \"responses\""));
+        assert!(bound.contains("disable_response_storage = false"));
+        assert!(
+            bound.contains(
+                "[profiles.default]\nmodel = \"gpt-5.4\"\ndisable_response_storage = true"
+            )
+        );
+        assert!(!bound.contains("env_key"));
+
+        let restored = restore_config_toml_from_runtime_rotation_provider(&bound, &original);
+        assert_eq!(restored, original);
+    }
+
+    #[test]
+    fn bearer_token_omitted_when_client_api_key_blank() {
+        let bound =
+            rewrite_config_toml_for_runtime_rotation_provider("", "http://127.0.0.1:1", "  ");
+        assert!(!bound.contains("experimental_bearer_token"));
+        let idx_requires = bound.find("requires_openai_auth = false").unwrap();
+        let idx_wire = bound.find("wire_api = \"responses\"").unwrap();
+        assert!(idx_requires < idx_wire);
+    }
+
+    #[test]
+    fn keeps_model_provider_top_level_before_toml_array_tables() {
+        let original = ["[[profiles.experimental]]", "model = \"gpt-5.4\"", ""].join("\n");
+        let bound = rewrite_config_toml_for_runtime_rotation_provider(
+            &original,
+            "http://127.0.0.1:32123",
+            "app-secret",
+        );
+        let provider_line = format!("model_provider = \"{PROXY_ID}\"");
+        assert!(bound.starts_with(&provider_line));
+        assert!(
+            bound.find(&provider_line).unwrap() < bound.find("[[profiles.experimental]]").unwrap()
+        );
+    }
+
+    #[test]
+    fn removes_runtime_provider_subtables_when_restoring() {
+        let bound = [
+            format!("model_provider = \"{PROXY_ID}\""),
+            String::new(),
+            format!("[model_providers.{PROXY_ID}]"),
+            "name = \"codex-multi-auth\"".to_string(),
+            "base_url = \"http://127.0.0.1:32123\"".to_string(),
+            format!("[model_providers.{PROXY_ID}.http_headers]"),
+            "authorization = \"Bearer secret\"".to_string(),
+            "[profiles.default]".to_string(),
+            "model = \"gpt-5.4\"".to_string(),
+            String::new(),
+        ]
+        .join("\n");
+
+        let restored = restore_config_toml_from_runtime_rotation_provider(
+            &bound,
+            "model_provider = \"openai\"\n",
+        );
+        assert!(!restored.contains(PROXY_ID));
+        assert!(!restored.contains("Bearer secret"));
+        assert!(restored.contains("[profiles.default]"));
+    }
+
+    // ----- restoreTopLevelModelProvider (config-toml-restore.test.ts) -----
+
+    #[test]
+    fn rewrites_the_runtime_rotation_provider_line_back_to_the_original() {
+        let original = "model_provider = \"openai\"\n[profiles.default]\nmodel = \"gpt-5\"\n";
+        let current =
+            format!("model_provider = \"{PROXY_ID}\"\n[profiles.default]\nmodel = \"gpt-5\"\n");
+        assert_eq!(restore_top_level_model_provider(&current, original), original);
+    }
+
+    #[test]
+    fn splices_the_original_model_provider_before_the_first_section_when_current_omits_it() {
+        let original = "model_provider = \"openai\"\n[profiles.default]\nmodel = \"gpt-5\"\n";
+        let current = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        let restored = restore_top_level_model_provider(current, original);
+        let lines: Vec<&str> = restored.split('\n').collect();
+        let provider_idx = lines
+            .iter()
+            .position(|l| is_key_assignment(l, "model_provider"))
+            .expect("provider line present");
+        let section_idx = lines
+            .iter()
+            .position(|l| l.trim_start().starts_with('['))
+            .expect("section header present");
+        assert!(provider_idx < section_idx);
+    }
+
+    #[test]
+    fn appends_the_original_model_provider_at_tail_when_no_section_header_exists() {
+        let original = "model_provider = \"openai\"\n";
+        let current = "# nothing here\n";
+        let restored = restore_top_level_model_provider(current, original);
+        assert!(restored.contains("model_provider = \"openai\""));
+    }
+
+    #[test]
+    fn preserves_crlf_line_endings_end_to_end() {
+        let original =
+            "model_provider = \"openai\"\r\n[profiles.default]\r\nmodel = \"gpt-5\"\r\n";
+        let current = format!(
+            "model_provider = \"{PROXY_ID}\"\r\n[profiles.default]\r\nmodel = \"gpt-5\"\r\n"
+        );
+        let restored = restore_top_level_model_provider(&current, original);
+        assert_eq!(restored, original);
+        assert!(!restored.replace("\r\n", "").contains('\n'));
+    }
+
+    #[test]
+    fn leaves_config_untouched_when_neither_side_has_the_runtime_line() {
+        let original = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        let current = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        assert_eq!(restore_top_level_model_provider(current, original), current);
+    }
+
+    // ----- restoreTopLevelResponseStorage -----
+
+    #[test]
+    fn restores_the_original_disable_response_storage_line_when_present() {
+        let original = "disable_response_storage = true\n[profiles.default]\n";
+        let current = "disable_response_storage = false\n[profiles.default]\n";
+        assert_eq!(restore_top_level_response_storage(current, original), original);
+    }
+
+    #[test]
+    fn drops_bind_time_disable_response_storage_residue_when_original_lacks_it() {
+        let original = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        let current = "disable_response_storage = false\n[profiles.default]\nmodel = \"gpt-5\"\n";
+        let restored = restore_top_level_response_storage(current, original);
+        assert!(!restored.contains("disable_response_storage"));
+        assert!(restored.contains("[profiles.default]"));
+    }
+
+    #[test]
+    fn splices_the_original_response_storage_line_before_the_first_section_when_current_omits_it()
+    {
+        let original = "disable_response_storage = true\n[profiles.default]\n";
+        let current = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        let restored = restore_top_level_response_storage(current, original);
+        let lines: Vec<&str> = restored.split('\n').collect();
+        let setting_idx = lines
+            .iter()
+            .position(|l| is_key_assignment(l, "disable_response_storage"))
+            .expect("setting line present");
+        let section_idx = lines
+            .iter()
+            .position(|l| l.trim_start().starts_with('['))
+            .expect("section header present");
+        assert!(setting_idx < section_idx);
+        assert!(restored.contains("disable_response_storage = true"));
+    }
+
+    #[test]
+    fn appends_the_original_response_storage_line_at_tail_when_no_section_header() {
+        let original = "disable_response_storage = true\n";
+        let current = "# nothing here\n";
+        let restored = restore_top_level_response_storage(current, original);
+        assert!(restored.contains("disable_response_storage = true"));
+    }
+
+    #[test]
+    fn does_not_strip_a_disable_response_storage_written_inside_a_section() {
+        let original = "[profiles.default]\nmodel = \"gpt-5\"\n";
+        let current = "[profiles.default]\ndisable_response_storage = false\nmodel = \"gpt-5\"\n";
+        let restored = restore_top_level_response_storage(current, original);
+        assert!(restored.contains("disable_response_storage = false"));
+    }
+
+    // ----- configHasRuntimeRotationProvider -----
+
+    #[test]
+    fn detects_a_top_level_model_provider_bound_to_the_proxy() {
+        let config =
+            format!("model_provider = \"{PROXY_ID}\"\n[profiles.default]\nmodel = \"gpt-5\"\n");
+        assert!(config_has_runtime_rotation_provider(&config));
+    }
+
+    #[test]
+    fn detects_the_proxy_provider_block_even_when_model_provider_is_native() {
+        let config = format!(
+            "model_provider = \"openai\"\n[model_providers.{PROXY_ID}]\nname = \"codex-multi-auth\"\n"
+        );
+        assert!(config_has_runtime_rotation_provider(&config));
+    }
+
+    #[test]
+    fn returns_false_for_an_unbound_config() {
+        let config = "model_provider = \"openai\"\n[profiles.default]\nmodel = \"gpt-5\"\n";
+        assert!(!config_has_runtime_rotation_provider(config));
+    }
+
+    #[test]
+    fn returns_false_for_empty_config() {
+        assert!(!config_has_runtime_rotation_provider(""));
+    }
+
+    #[test]
+    fn does_not_match_a_proxy_id_that_only_appears_inside_a_non_provider_section() {
+        let config = format!("[profiles.default]\nnote = \"{PROXY_ID}\"\n");
+        assert!(!config_has_runtime_rotation_provider(&config));
+    }
+
+    // ----- restoreConfigTomlFromRuntimeRotationProviderWithoutBackup -----
+
+    #[test]
+    fn rewrites_a_bound_model_provider_to_the_default_and_strips_the_proxy_block() {
+        let bound = [
+            format!("model_provider = \"{PROXY_ID}\""),
+            "[profiles.default]".to_string(),
+            "model = \"gpt-5\"".to_string(),
+            String::new(),
+            format!("[model_providers.{PROXY_ID}]"),
+            "name = \"codex-multi-auth\"".to_string(),
+            "base_url = \"http://127.0.0.1:51758\"".to_string(),
+            "requires_openai_auth = false".to_string(),
+            "wire_api = \"responses\"".to_string(),
+            String::new(),
+        ]
+        .join("\n");
+
+        let restored =
+            restore_config_toml_from_runtime_rotation_provider_without_backup(&bound, None);
+        assert!(restored.contains("model_provider = \"openai\""));
+        assert!(!restored.contains(PROXY_ID));
+        assert!(restored.contains("[profiles.default]"));
+        assert!(!config_has_runtime_rotation_provider(&restored));
+    }
+
+    #[test]
+    fn honors_a_custom_default_provider() {
+        let bound = format!("model_provider = \"{PROXY_ID}\"\n");
+        let restored = restore_config_toml_from_runtime_rotation_provider_without_backup(
+            &bound,
+            Some("my-provider"),
+        );
+        assert!(restored.contains("model_provider = \"my-provider\""));
+    }
+
+    #[test]
+    fn preserves_crlf_endings_when_recovering() {
+        let bound = format!(
+            "model_provider = \"{PROXY_ID}\"\r\n[model_providers.{PROXY_ID}]\r\nname = \"codex-multi-auth\"\r\n"
+        );
+        let restored =
+            restore_config_toml_from_runtime_rotation_provider_without_backup(&bound, None);
+        assert!(restored.contains("model_provider = \"openai\""));
+        assert!(!restored.contains(PROXY_ID));
+        assert!(!restored.replace("\r\n", "").contains('\n'));
+    }
+
+    #[test]
+    fn does_not_duplicate_model_provider_on_half_orphan() {
+        let half_orphan = [
+            "model_provider = \"openai\"".to_string(),
+            "[profiles.default]".to_string(),
+            "model = \"gpt-5\"".to_string(),
+            String::new(),
+            format!("[model_providers.{PROXY_ID}]"),
+            "name = \"codex-multi-auth\"".to_string(),
+            "base_url = \"http://127.0.0.1:51758\"".to_string(),
+            "wire_api = \"responses\"".to_string(),
+            String::new(),
+        ]
+        .join("\n");
+
+        let restored =
+            restore_config_toml_from_runtime_rotation_provider_without_backup(&half_orphan, None);
+        let provider_lines = restored
+            .split('\n')
+            .filter(|line| is_key_assignment(line, "model_provider"))
+            .count();
+        assert_eq!(provider_lines, 1);
+        assert!(restored.contains("model_provider = \"openai\""));
+        assert!(!restored.contains(PROXY_ID));
+        assert!(restored.contains("[profiles.default]"));
+    }
+
+    #[test]
+    fn drops_bind_injected_disable_response_storage_during_no_backup_recovery() {
+        let bound = [
+            format!("model_provider = \"{PROXY_ID}\""),
+            "disable_response_storage = false".to_string(),
+            "[profiles.default]".to_string(),
+            "model = \"gpt-5\"".to_string(),
+            String::new(),
+            format!("[model_providers.{PROXY_ID}]"),
+            "wire_api = \"responses\"".to_string(),
+            String::new(),
+        ]
+        .join("\n");
+
+        let restored =
+            restore_config_toml_from_runtime_rotation_provider_without_backup(&bound, None);
+        assert!(restored.contains("model_provider = \"openai\""));
+        assert!(!restored.contains("disable_response_storage"));
+        assert!(!restored.contains(PROXY_ID));
+    }
+
+    // ----- byte-exactness details -----
+
+    #[test]
+    fn bind_output_ends_with_exactly_one_eol_and_one_blank_line_before_block() {
+        let original = "model_provider = \"openai\"\n";
+        let bound =
+            rewrite_config_toml_for_runtime_rotation_provider(original, "http://127.0.0.1:9", "");
+        let expected = format!(
+            "model_provider = \"{PROXY_ID}\"\n\n[model_providers.{PROXY_ID}]\nname = \"codex-multi-auth\"\nbase_url = \"http://127.0.0.1:9\"\nrequires_openai_auth = false\nwire_api = \"responses\"\n"
+        );
+        assert_eq!(bound, expected);
+    }
+
+    #[test]
+    fn restore_final_newline_is_lf_even_in_crlf_files() {
+        let original = "model_provider = \"openai\"\r\nmodel = \"gpt-5\"\r\n";
+        let bound = rewrite_config_toml_for_runtime_rotation_provider(
+            original,
+            "http://127.0.0.1:9",
+            "key",
+        );
+        assert!(bound.contains("\r\n"));
+        let restored = restore_config_toml_from_runtime_rotation_provider(&bound, original);
+        assert!(restored.ends_with('\n'));
+        assert!(!restored.ends_with("\r\n"));
+    }
+
+    #[test]
+    fn table_name_parser_matches_regex_semantics() {
+        assert_eq!(read_toml_table_name("[a]"), Some("a"));
+        assert_eq!(
+            read_toml_table_name("  [[ profiles.default ]]  "),
+            Some("profiles.default")
+        );
+        assert_eq!(read_toml_table_name("[[a]"), Some("a"));
+        assert_eq!(read_toml_table_name("[a]]"), Some("a"));
+        assert_eq!(read_toml_table_name("[]"), None);
+        assert_eq!(read_toml_table_name("[a] # comment"), None);
+        assert_eq!(read_toml_table_name("[a]b]"), None);
+        assert_eq!(read_toml_table_name("key = \"[a]\""), None);
+        assert_eq!(read_toml_table_name("[[[a]]]"), None);
+    }
+}
diff --git a/crates/runtime/src/current_account.rs b/crates/runtime/src/current_account.rs
new file mode 100644
index 000000000..264a209bf
--- /dev/null
+++ b/crates/runtime/src/current_account.rs
@@ -0,0 +1,931 @@
+//! Port of `lib/runtime/runtime-current-account.ts` (+ the duplicate
+//! `status-marker.ts` helper) — answers "which account is the *runtime*
+//! actually using right now?" by merging three status signals against the
+//! account storage.
+//!
+//! Behavioral contracts (spec 10 §4 + gotcha 17): 24 h staleness cap; signals
+//! sorted newest-first with source-rank tie-break
+//! (runtime-observability < app-bind < app-helper); app-bind signals require
+//! `state == "running"` but no pid check; app-helper signals require
+//! kind + state + live pid; the index fallback is rejected when it contradicts
+//! the signal's account id or email.
+
+use std::path::PathBuf;
+
+use serde_json::Value;
+
+use cma_core::constants::APP_RUNTIME_HELPER_STATUS_FILE;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::utils::now_ms;
+
+use crate::app_bind::{is_process_alive, AppBindRouterStatus};
+use crate::observability::RuntimeObservabilitySnapshot;
+use crate::ui_runtime::{get_status_marker, RuntimeStatus, StatusMarkerTheme};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RuntimeCurrentAccountSource {
+    RuntimeObservability,
+    AppBind,
+    AppHelper,
+}
+
+impl RuntimeCurrentAccountSource {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            RuntimeCurrentAccountSource::RuntimeObservability => "runtime-observability",
+            RuntimeCurrentAccountSource::AppBind => "app-bind",
+            RuntimeCurrentAccountSource::AppHelper => "app-helper",
+        }
+    }
+
+    fn rank(self) -> u8 {
+        match self {
+            RuntimeCurrentAccountSource::RuntimeObservability => 0,
+            RuntimeCurrentAccountSource::AppBind => 1,
+            RuntimeCurrentAccountSource::AppHelper => 2,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RuntimeCurrentAccountMatch {
+    AccountId,
+    Email,
+    Index,
+}
+
+impl RuntimeCurrentAccountMatch {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            RuntimeCurrentAccountMatch::AccountId => "account-id",
+            RuntimeCurrentAccountMatch::Email => "email",
+            RuntimeCurrentAccountMatch::Index => "index",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountCurrentMarker {
+    Current,
+    InUse,
+    Selected,
+}
+
+impl AccountCurrentMarker {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            AccountCurrentMarker::Current => "current",
+            AccountCurrentMarker::InUse => "in-use",
+            AccountCurrentMarker::Selected => "selected",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct RuntimeAccountSignal {
+    pub source: Option<RuntimeCurrentAccountSource>,
+    pub last_account_index: Option<i64>,
+    pub last_account_id: Option<String>,
+    pub last_account_email: Option<String>,
+    pub last_account_label: Option<String>,
+    pub last_account_updated_at: Option<i64>,
+    pub updated_at: Option<i64>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct RuntimeCurrentAccountSelection {
+    pub index: usize,
+    pub source: RuntimeCurrentAccountSource,
+    pub matched_by: RuntimeCurrentAccountMatch,
+    pub updated_at: i64,
+    pub last_account_id: Option<String>,
+    pub last_account_email: Option<String>,
+    pub last_account_label: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RuntimeCurrentAccountOptions {
+    pub now: Option<i64>,
+    pub max_age_ms: Option<i64>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct RuntimeCurrentAccountSources {
+    pub runtime_snapshot: Option<RuntimeObservabilitySnapshot>,
+    pub app_bind_status: Option<AppBindRouterStatus>,
+    pub app_helper_status: Option<RuntimeAccountSignal>,
+}
+
+pub const RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS: i64 = 24 * 60 * 60 * 1000;
+const APP_RUNTIME_HELPER_KIND: &str = "codex-app-runtime-rotation-helper";
+const MAX_STATUS_FILE_BYTES: u64 = 1024 * 1024; // 1 MB sanity cap
+
+/// `runtime-rotation-app-helper.json` shape (all nullable, spec 10 §12.6).
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AppRuntimeHelperAccountStatus {
+    pub kind: Option<String>,
+    pub state: Option<String>,
+    pub pid: Option<i64>,
+    pub last_account_index: Option<i64>,
+    pub last_account_label: Option<String>,
+    pub last_account_email: Option<String>,
+    pub last_account_id: Option<String>,
+    pub last_account_updated_at: Option<i64>,
+    pub updated_at: Option<i64>,
+}
+
+fn normalize_string(value: Option<&str>) -> Option<String> {
+    let trimmed = value?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn normalize_account_id(value: Option<&str>) -> Option<String> {
+    normalize_string(value)
+}
+
+fn normalize_email(value: Option<&str>) -> Option<String> {
+    normalize_string(value).map(|email| email.to_lowercase())
+}
+
+/// Index normalization: truncate toward zero; negative → None.
+fn normalize_index(value: Option<i64>) -> Option<i64> {
+    match value {
+        Some(index) if index >= 0 => Some(index),
+        _ => None,
+    }
+}
+
+fn normalize_timestamp_value(value: Option<i64>) -> Option<i64> {
+    value.filter(|timestamp| *timestamp > 0)
+}
+
+/// Effective timestamp of a signal = max of the positive finite values.
+fn normalize_timestamp(signal: &RuntimeAccountSignal) -> Option<i64> {
+    [
+        normalize_timestamp_value(signal.last_account_updated_at),
+        normalize_timestamp_value(signal.updated_at),
+    ]
+    .into_iter()
+    .flatten()
+    .max()
+}
+
+fn read_optional_number(record: &serde_json::Map<String, Value>, key: &str) -> Option<i64> {
+    match record.get(key) {
+        Some(value) if value.is_number() => value.as_i64().or_else(|| {
+            // Fractional values truncate toward zero (JS Math.trunc happens at
+            // the index-normalization layer; other numeric fields tolerate it).
+            value.as_f64().filter(|f| f.is_finite()).map(|f| f.trunc() as i64)
+        }),
+        _ => None,
+    }
+}
+
+fn read_optional_string(record: &serde_json::Map<String, Value>, key: &str) -> Option<String> {
+    match record.get(key) {
+        Some(Value::String(value)) => normalize_string(Some(value)),
+        _ => None,
+    }
+}
+
+/// `readAppRuntimeHelperStatus` — reads
+/// `<multiAuthDir>/runtime-rotation-app-helper.json`; None when missing,
+/// larger than 1 MB, unparseable, or not a JSON object. Strings must be
+/// non-empty after trim; numbers finite.
+pub fn read_app_runtime_helper_status() -> Option<AppRuntimeHelperAccountStatus> {
+    read_app_runtime_helper_status_at(
+        &get_codex_multi_auth_dir().join(APP_RUNTIME_HELPER_STATUS_FILE),
+    )
+}
+
+fn read_app_runtime_helper_status_at(status_path: &PathBuf) -> Option<AppRuntimeHelperAccountStatus> {
+    let metadata = std::fs::metadata(status_path).ok()?;
+    if metadata.len() > MAX_STATUS_FILE_BYTES {
+        return None;
+    }
+    let raw = std::fs::read_to_string(status_path).ok()?;
+    let parsed: Value = serde_json::from_str(&raw).ok()?;
+    let record = parsed.as_object()?;
+    Some(AppRuntimeHelperAccountStatus {
+        kind: read_optional_string(record, "kind"),
+        state: read_optional_string(record, "state"),
+        pid: read_optional_number(record, "pid"),
+        last_account_index: read_optional_number(record, "lastAccountIndex"),
+        last_account_label: read_optional_string(record, "lastAccountLabel"),
+        last_account_email: read_optional_string(record, "lastAccountEmail"),
+        last_account_id: read_optional_string(record, "lastAccountId"),
+        last_account_updated_at: read_optional_number(record, "lastAccountUpdatedAt"),
+        updated_at: read_optional_number(record, "updatedAt"),
+    })
+}
+
+/// `appRuntimeHelperStatusToSignal` — trusted only when
+/// `kind == "codex-app-runtime-rotation-helper"`, `state == "running"`, and
+/// the pid is alive (EPERM counts as alive).
+pub fn app_runtime_helper_status_to_signal(
+    status: Option<&AppRuntimeHelperAccountStatus>,
+) -> Option<RuntimeAccountSignal> {
+    let status = status?;
+    if status.kind.as_deref() != Some(APP_RUNTIME_HELPER_KIND) {
+        return None;
+    }
+    if status.state.as_deref() != Some("running") {
+        return None;
+    }
+    if !is_process_alive(status.pid) {
+        return None;
+    }
+    Some(RuntimeAccountSignal {
+        source: Some(RuntimeCurrentAccountSource::AppHelper),
+        last_account_index: status.last_account_index,
+        last_account_id: status.last_account_id.clone(),
+        last_account_email: status.last_account_email.clone(),
+        last_account_label: status.last_account_label.clone(),
+        last_account_updated_at: status.last_account_updated_at,
+        updated_at: status.updated_at,
+    })
+}
+
+/// `readAppRuntimeHelperAccountSignal` — composition of the two above.
+pub fn read_app_runtime_helper_account_signal() -> Option<RuntimeAccountSignal> {
+    app_runtime_helper_status_to_signal(read_app_runtime_helper_status().as_ref())
+}
+
+fn runtime_snapshot_to_signal(
+    snapshot: Option<&RuntimeObservabilitySnapshot>,
+) -> Option<RuntimeAccountSignal> {
+    let snapshot = snapshot?;
+    Some(RuntimeAccountSignal {
+        source: Some(RuntimeCurrentAccountSource::RuntimeObservability),
+        last_account_index: snapshot.last_account_index,
+        last_account_id: snapshot.last_account_id.clone(),
+        last_account_email: snapshot.last_account_email.clone(),
+        last_account_label: snapshot.last_account_label.clone(),
+        last_account_updated_at: snapshot.last_account_updated_at,
+        updated_at: Some(snapshot.updated_at),
+    })
+}
+
+/// App-bind router status is eligible **only when `state == "running"`** — no
+/// pid check here (spec 10 §4 step 2).
+fn app_bind_status_to_signal(status: Option<&AppBindRouterStatus>) -> Option<RuntimeAccountSignal> {
+    let status = status?;
+    if status.state.as_deref() != Some("running") {
+        return None;
+    }
+    Some(RuntimeAccountSignal {
+        source: Some(RuntimeCurrentAccountSource::AppBind),
+        last_account_index: status.last_account_index,
+        last_account_id: status.last_account_id.clone(),
+        last_account_email: status.last_account_email.clone(),
+        last_account_label: status.last_account_label.clone(),
+        last_account_updated_at: None,
+        updated_at: status.updated_at,
+    })
+}
+
+fn find_unique_email_index(storage: &AccountStorageV3, email: &str) -> Option<usize> {
+    let mut match_index: Option<usize> = None;
+    for (index, account) in storage.accounts.iter().enumerate() {
+        if normalize_email(account.email.as_deref()).as_deref() != Some(email) {
+            continue;
+        }
+        if match_index.is_some() {
+            return None;
+        }
+        match_index = Some(index);
+    }
+    match_index
+}
+
+fn find_unique_account_id_index(storage: &AccountStorageV3, account_id: &str) -> Option<usize> {
+    let mut match_index: Option<usize> = None;
+    for (index, account) in storage.accounts.iter().enumerate() {
+        if normalize_account_id(account.account_id.as_deref()).as_deref() != Some(account_id) {
+            continue;
+        }
+        if match_index.is_some() {
+            return None;
+        }
+        match_index = Some(index);
+    }
+    match_index
+}
+
+fn match_signal_to_account(
+    storage: &AccountStorageV3,
+    signal: &RuntimeAccountSignal,
+) -> Option<(usize, RuntimeCurrentAccountMatch)> {
+    let account_id = normalize_account_id(signal.last_account_id.as_deref());
+    if let Some(account_id) = &account_id
+        && let Some(id_index) = find_unique_account_id_index(storage, account_id)
+    {
+        return Some((id_index, RuntimeCurrentAccountMatch::AccountId));
+    }
+
+    let email = normalize_email(signal.last_account_email.as_deref());
+    if let Some(email) = &email
+        && let Some(email_index) = find_unique_email_index(storage, email)
+    {
+        return Some((email_index, RuntimeCurrentAccountMatch::Email));
+    }
+
+    let index = normalize_index(signal.last_account_index)?;
+    let index = usize::try_from(index).ok()?;
+    if index >= storage.accounts.len() {
+        return None;
+    }
+    let indexed_account = storage.accounts.get(index)?;
+
+    // Guard: an index fallback that contradicts the signal's id/email is no
+    // match at all.
+    let indexed_account_id = normalize_account_id(indexed_account.account_id.as_deref());
+    if let (Some(signal_id), Some(indexed_id)) = (&account_id, &indexed_account_id)
+        && indexed_id != signal_id
+    {
+        return None;
+    }
+    let indexed_email = normalize_email(indexed_account.email.as_deref());
+    if let (Some(signal_email), Some(indexed_email)) = (&email, &indexed_email)
+        && indexed_email != signal_email
+    {
+        return None;
+    }
+    Some((index, RuntimeCurrentAccountMatch::Index))
+}
+
+/// `resolveRuntimeCurrentAccount` — see spec 10 §4 for the exact precedence.
+pub fn resolve_runtime_current_account(
+    storage: &AccountStorageV3,
+    sources: &RuntimeCurrentAccountSources,
+    options: RuntimeCurrentAccountOptions,
+) -> Option<RuntimeCurrentAccountSelection> {
+    if storage.accounts.is_empty() {
+        return None;
+    }
+    let now = options.now.unwrap_or_else(now_ms);
+    let max_age_ms = options.max_age_ms.unwrap_or(RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS);
+
+    let mut signals: Vec<(RuntimeAccountSignal, i64)> = [
+        runtime_snapshot_to_signal(sources.runtime_snapshot.as_ref()),
+        app_bind_status_to_signal(sources.app_bind_status.as_ref()),
+        sources.app_helper_status.clone(),
+    ]
+    .into_iter()
+    .flatten()
+    .filter_map(|signal| {
+        let updated_at = normalize_timestamp(&signal)?;
+        if now - updated_at > max_age_ms {
+            return None;
+        }
+        Some((signal, updated_at))
+    })
+    .collect();
+    signals.sort_by(|(left_signal, left_ts), (right_signal, right_ts)| {
+        right_ts.cmp(left_ts).then_with(|| {
+            let left_rank = left_signal.source.map(|s| s.rank()).unwrap_or(u8::MAX);
+            let right_rank = right_signal.source.map(|s| s.rank()).unwrap_or(u8::MAX);
+            left_rank.cmp(&right_rank)
+        })
+    });
+
+    for (signal, updated_at) in signals {
+        let Some((index, matched_by)) = match_signal_to_account(storage, &signal) else {
+            continue;
+        };
+        return Some(RuntimeCurrentAccountSelection {
+            index,
+            source: signal
+                .source
+                .unwrap_or(RuntimeCurrentAccountSource::AppHelper),
+            matched_by,
+            updated_at,
+            last_account_id: normalize_account_id(signal.last_account_id.as_deref()),
+            last_account_email: normalize_email(signal.last_account_email.as_deref()),
+            last_account_label: normalize_string(signal.last_account_label.as_deref()),
+        });
+    }
+
+    None
+}
+
+/// `resolveAccountCurrentMarkers` — no runtime signal (or runtime index ==
+/// stored index): `["current"]` at the stored index, else `[]`; divergent:
+/// `"in-use"` at the runtime index, `"selected"` at the stored index.
+pub fn resolve_account_current_markers(
+    index: usize,
+    stored_current_index: usize,
+    runtime_current: Option<&RuntimeCurrentAccountSelection>,
+) -> Vec<AccountCurrentMarker> {
+    let Some(runtime_current) = runtime_current else {
+        return if index == stored_current_index {
+            vec![AccountCurrentMarker::Current]
+        } else {
+            Vec::new()
+        };
+    };
+    if runtime_current.index == stored_current_index {
+        return if index == stored_current_index {
+            vec![AccountCurrentMarker::Current]
+        } else {
+            Vec::new()
+        };
+    }
+    let mut markers = Vec::new();
+    if index == runtime_current.index {
+        markers.push(AccountCurrentMarker::InUse);
+    }
+    if index == stored_current_index {
+        markers.push(AccountCurrentMarker::Selected);
+    }
+    markers
+}
+
+/// `isDisplayCurrentAccount` — the runtime index wins when a runtime signal
+/// exists, else the stored index.
+pub fn is_display_current_account(
+    index: usize,
+    stored_current_index: usize,
+    runtime_current: Option<&RuntimeCurrentAccountSelection>,
+) -> bool {
+    match runtime_current {
+        Some(runtime_current) => index == runtime_current.index,
+        None => index == stored_current_index,
+    }
+}
+
+/// `getRuntimeStatusMarker` (from `status-marker.ts`) — identical duplicate of
+/// [`crate::ui_runtime::get_status_marker`].
+pub fn get_runtime_status_marker(ui: &StatusMarkerTheme, status: RuntimeStatus) -> String {
+    get_status_marker(ui, status)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn account(email: Option<&str>, account_id: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(
+            format!(
+                "rt-{}-{}",
+                email.unwrap_or("none"),
+                account_id.unwrap_or("none")
+            ),
+            0,
+            0,
+        );
+        account.email = email.map(str::to_string);
+        account.account_id = account_id.map(str::to_string);
+        account
+    }
+
+    fn storage(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = accounts;
+        storage
+    }
+
+    fn observability_signal_snapshot(
+        updated_at: i64,
+        index: Option<i64>,
+        id: Option<&str>,
+        email: Option<&str>,
+    ) -> RuntimeObservabilitySnapshot {
+        let mut snapshot = crate::observability::create_default_snapshot();
+        snapshot.updated_at = updated_at;
+        snapshot.last_account_index = index;
+        snapshot.last_account_id = id.map(str::to_string);
+        snapshot.last_account_email = email.map(str::to_string);
+        snapshot
+    }
+
+    // runtime-current-account.test.ts: "uses the freshest runtime source and
+    // matches by account id"
+    #[test]
+    fn uses_the_freshest_runtime_source_and_matches_by_account_id() {
+        let storage = storage(vec![
+            account(Some("a@example.com"), Some("acc_a")),
+            account(Some("b@example.com"), Some("acc_b")),
+        ]);
+        let now = 1_000_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - 5_000,
+                Some(0),
+                Some("acc_a"),
+                None,
+            )),
+            app_bind_status: Some(AppBindRouterStatus {
+                state: Some("running".to_string()),
+                last_account_id: Some("acc_b".to_string()),
+                updated_at: Some(now - 1_000),
+                ..AppBindRouterStatus::default()
+            }),
+            app_helper_status: None,
+        };
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        // app-bind is fresher → wins despite lower source rank.
+        assert_eq!(selection.index, 1);
+        assert_eq!(selection.source, RuntimeCurrentAccountSource::AppBind);
+        assert_eq!(selection.matched_by, RuntimeCurrentAccountMatch::AccountId);
+        assert_eq!(selection.last_account_id.as_deref(), Some("acc_b"));
+    }
+
+    // "uses deterministic source precedence for equal timestamp signals"
+    #[test]
+    fn uses_deterministic_source_precedence_for_equal_timestamp_signals() {
+        let storage = storage(vec![
+            account(Some("a@example.com"), Some("acc_a")),
+            account(Some("b@example.com"), Some("acc_b")),
+        ]);
+        let now = 1_000_000;
+        let ts = now - 2_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(ts, None, Some("acc_a"), None)),
+            app_bind_status: Some(AppBindRouterStatus {
+                state: Some("running".to_string()),
+                last_account_id: Some("acc_b".to_string()),
+                updated_at: Some(ts),
+                ..AppBindRouterStatus::default()
+            }),
+            app_helper_status: None,
+        };
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        // Tie → runtime-observability (rank 0) wins.
+        assert_eq!(selection.source, RuntimeCurrentAccountSource::RuntimeObservability);
+        assert_eq!(selection.index, 0);
+    }
+
+    // "ignores stale runtime account signals"
+    #[test]
+    fn ignores_stale_runtime_account_signals() {
+        let storage = storage(vec![account(Some("a@example.com"), Some("acc_a"))]);
+        let now = RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS * 2;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS - 1,
+                Some(0),
+                Some("acc_a"),
+                None,
+            )),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        assert!(resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .is_none());
+    }
+
+    // "keeps live sessions current when heartbeat is newer than switch
+    // timestamp" — effective ts = max(lastAccountUpdatedAt, updatedAt).
+    #[test]
+    fn keeps_live_sessions_current_when_heartbeat_is_newer_than_switch_timestamp() {
+        let storage = storage(vec![account(Some("a@example.com"), Some("acc_a"))]);
+        let now = RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS * 3;
+        let mut snapshot = observability_signal_snapshot(0, Some(0), Some("acc_a"), None);
+        // Old switch stamp but a fresh heartbeat.
+        snapshot.last_account_updated_at = Some(now - RUNTIME_CURRENT_ACCOUNT_MAX_AGE_MS * 2);
+        snapshot.updated_at = now - 60_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(snapshot),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        assert_eq!(selection.updated_at, now - 60_000);
+    }
+
+    // "does not accept ambiguous duplicate account-id matches"
+    #[test]
+    fn does_not_accept_ambiguous_duplicate_account_id_matches() {
+        let storage = storage(vec![
+            account(Some("a@example.com"), Some("acc_dup")),
+            account(Some("b@example.com"), Some("acc_dup")),
+        ]);
+        let now = 1_000_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - 1_000,
+                None,
+                Some("acc_dup"),
+                Some("b@example.com"),
+            )),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        // Duplicate id disqualifies the id path; unique email still matches.
+        assert_eq!(selection.matched_by, RuntimeCurrentAccountMatch::Email);
+        assert_eq!(selection.index, 1);
+    }
+
+    // "ignores app-bind router status that is not running"
+    #[test]
+    fn ignores_app_bind_router_status_that_is_not_running() {
+        let storage = storage(vec![account(Some("a@example.com"), Some("acc_a"))]);
+        let now = 1_000_000;
+        let sources = RuntimeCurrentAccountSources {
+            app_bind_status: Some(AppBindRouterStatus {
+                state: Some("stopped".to_string()),
+                last_account_id: Some("acc_a".to_string()),
+                updated_at: Some(now - 100),
+                ..AppBindRouterStatus::default()
+            }),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        assert!(resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .is_none());
+    }
+
+    // "only turns a running live app helper status into a runtime signal"
+    #[test]
+    fn only_turns_a_running_live_app_helper_status_into_a_runtime_signal() {
+        let mut status = AppRuntimeHelperAccountStatus {
+            kind: Some(APP_RUNTIME_HELPER_KIND.to_string()),
+            state: Some("running".to_string()),
+            pid: Some(i64::from(std::process::id())),
+            last_account_index: Some(0),
+            updated_at: Some(123),
+            ..AppRuntimeHelperAccountStatus::default()
+        };
+        let signal =
+            app_runtime_helper_status_to_signal(Some(&status)).expect("live helper is a signal");
+        assert_eq!(signal.source, Some(RuntimeCurrentAccountSource::AppHelper));
+
+        status.state = Some("stopped".to_string());
+        assert!(app_runtime_helper_status_to_signal(Some(&status)).is_none());
+        status.state = Some("running".to_string());
+        status.kind = Some("other-kind".to_string());
+        assert!(app_runtime_helper_status_to_signal(Some(&status)).is_none());
+        status.kind = Some(APP_RUNTIME_HELPER_KIND.to_string());
+        status.pid = None;
+        assert!(app_runtime_helper_status_to_signal(Some(&status)).is_none());
+        assert!(app_runtime_helper_status_to_signal(None).is_none());
+    }
+
+    // "labels stored selected and runtime in-use rows separately"
+    #[test]
+    fn labels_stored_selected_and_runtime_in_use_rows_separately() {
+        let runtime = RuntimeCurrentAccountSelection {
+            index: 2,
+            source: RuntimeCurrentAccountSource::RuntimeObservability,
+            matched_by: RuntimeCurrentAccountMatch::Index,
+            updated_at: 1,
+            last_account_id: None,
+            last_account_email: None,
+            last_account_label: None,
+        };
+        assert_eq!(
+            resolve_account_current_markers(2, 0, Some(&runtime)),
+            vec![AccountCurrentMarker::InUse]
+        );
+        assert_eq!(
+            resolve_account_current_markers(0, 0, Some(&runtime)),
+            vec![AccountCurrentMarker::Selected]
+        );
+        assert!(resolve_account_current_markers(1, 0, Some(&runtime)).is_empty());
+        // Runtime == stored: only "current" at the stored index.
+        let aligned = RuntimeCurrentAccountSelection { index: 0, ..runtime };
+        assert_eq!(
+            resolve_account_current_markers(0, 0, Some(&aligned)),
+            vec![AccountCurrentMarker::Current]
+        );
+        assert!(resolve_account_current_markers(1, 0, Some(&aligned)).is_empty());
+        // No runtime signal.
+        assert_eq!(
+            resolve_account_current_markers(0, 0, None),
+            vec![AccountCurrentMarker::Current]
+        );
+        assert!(resolve_account_current_markers(1, 0, None).is_empty());
+        // Display-current follows the runtime index when present.
+        assert!(is_display_current_account(2, 0, Some(&RuntimeCurrentAccountSelection { index: 2, ..aligned.clone() })));
+        assert!(!is_display_current_account(0, 0, Some(&RuntimeCurrentAccountSelection { index: 2, ..aligned })));
+        assert!(is_display_current_account(0, 0, None));
+    }
+
+    // "falls back to the reported index when id and email are absent"
+    #[test]
+    fn falls_back_to_the_reported_index_when_id_and_email_are_absent() {
+        let storage = storage(vec![
+            account(Some("a@example.com"), Some("acc_a")),
+            account(Some("b@example.com"), Some("acc_b")),
+        ]);
+        let now = 1_000_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(now - 100, Some(1), None, None)),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        assert_eq!(selection.index, 1);
+        assert_eq!(selection.matched_by, RuntimeCurrentAccountMatch::Index);
+    }
+
+    // "truncates fractional indices and rejects negative or out-of-range ones"
+    #[test]
+    fn rejects_negative_or_out_of_range_indices() {
+        let storage = storage(vec![account(Some("a@example.com"), None)]);
+        let now = 1_000_000;
+        for bad_index in [Some(-1), Some(5)] {
+            let sources = RuntimeCurrentAccountSources {
+                runtime_snapshot: Some(observability_signal_snapshot(
+                    now - 100,
+                    bad_index,
+                    None,
+                    None,
+                )),
+                ..RuntimeCurrentAccountSources::default()
+            };
+            assert!(
+                resolve_runtime_current_account(
+                    &storage,
+                    &sources,
+                    RuntimeCurrentAccountOptions {
+                        now: Some(now),
+                        max_age_ms: None,
+                    },
+                )
+                .is_none(),
+                "index {bad_index:?} must not match"
+            );
+        }
+    }
+
+    // "rejects an index fallback that contradicts the signal account id or
+    // email"
+    #[test]
+    fn rejects_an_index_fallback_that_contradicts_the_signal_identity() {
+        let storage = storage(vec![
+            account(Some("a@example.com"), Some("acc_a")),
+            account(Some("b@example.com"), Some("acc_b")),
+        ]);
+        let now = 1_000_000;
+        // Signal id "acc_zz" (matches nothing uniquely) + index 0 whose
+        // account has a DIFFERENT id → no match.
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - 100,
+                Some(0),
+                Some("acc_zz"),
+                None,
+            )),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        assert!(resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .is_none());
+        // Same for a contradicting email.
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - 100,
+                Some(0),
+                None,
+                Some("zz@example.com"),
+            )),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        assert!(resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .is_none());
+    }
+
+    // "ignores whitespace-only ids and emails when matching by index"
+    #[test]
+    fn ignores_whitespace_only_ids_and_emails_when_matching_by_index() {
+        let storage = storage(vec![account(Some("  "), Some("   "))]);
+        let now = 1_000_000;
+        let sources = RuntimeCurrentAccountSources {
+            runtime_snapshot: Some(observability_signal_snapshot(
+                now - 100,
+                Some(0),
+                Some("acc_a"),
+                Some("a@example.com"),
+            )),
+            ..RuntimeCurrentAccountSources::default()
+        };
+        // The indexed account's blank id/email normalize to None → the
+        // contradiction guard does not fire → index match.
+        let selection = resolve_runtime_current_account(
+            &storage,
+            &sources,
+            RuntimeCurrentAccountOptions {
+                now: Some(now),
+                max_age_ms: None,
+            },
+        )
+        .expect("selection");
+        assert_eq!(selection.matched_by, RuntimeCurrentAccountMatch::Index);
+    }
+
+    // readAppRuntimeHelperStatus file-shape tests.
+    #[test]
+    #[serial(env)]
+    fn read_app_runtime_helper_status_file_contract() {
+        let sandbox = EnvSandbox::new();
+        let dir = sandbox.codex_multi_auth_dir();
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join(APP_RUNTIME_HELPER_STATUS_FILE);
+
+        // Missing file → None.
+        assert!(read_app_runtime_helper_status().is_none());
+
+        // Malformed JSON → None; array → None.
+        std::fs::write(&path, "{not json").unwrap();
+        assert!(read_app_runtime_helper_status().is_none());
+        std::fs::write(&path, "[1,2,3]").unwrap();
+        assert!(read_app_runtime_helper_status().is_none());
+
+        // >1 MB → None.
+        let big = format!(
+            "{{\"kind\": \"{APP_RUNTIME_HELPER_KIND}\", \"pad\": \"{}\"}}",
+            "x".repeat((MAX_STATUS_FILE_BYTES as usize) + 10)
+        );
+        std::fs::write(&path, big).unwrap();
+        assert!(read_app_runtime_helper_status().is_none());
+
+        // Types normalized: strings trimmed, wrong-typed values dropped.
+        std::fs::write(
+            &path,
+            format!(
+                "{{\"kind\": \"  {APP_RUNTIME_HELPER_KIND}  \", \"state\": 5, \"pid\": \"nope\", \"lastAccountIndex\": 2, \"lastAccountLabel\": \"  \", \"updatedAt\": 42}}"
+            ),
+        )
+        .unwrap();
+        let status = read_app_runtime_helper_status().expect("status record");
+        assert_eq!(status.kind.as_deref(), Some(APP_RUNTIME_HELPER_KIND));
+        assert!(status.state.is_none());
+        assert!(status.pid.is_none());
+        assert_eq!(status.last_account_index, Some(2));
+        assert!(status.last_account_label.is_none());
+        assert_eq!(status.updated_at, Some(42));
+    }
+}
diff --git a/crates/runtime/src/event_handler.rs b/crates/runtime/src/event_handler.rs
new file mode 100644
index 000000000..723ab12b4
--- /dev/null
+++ b/crates/runtime/src/event_handler.rs
@@ -0,0 +1,97 @@
+//! Port of `lib/runtime/event-handler.ts` — the never-throwing wrapper that
+//! wires a runtime plugin event into the account-select handler
+//! (spec 10 §19).
+
+use crate::account_selection::{AccountSelectEventDeps, RuntimeEvent, handle_account_select_event};
+
+/// Extra wiring for [`handle_runtime_event`] beyond the select-event deps.
+pub struct RuntimeEventParams<'a> {
+    pub plugin_name: &'a str,
+    pub log_debug: &'a mut dyn FnMut(&str),
+}
+
+/// TS `handleRuntimeEvent(params)` — delegates to
+/// [`handle_account_select_event`]; errors are debug-logged as
+/// `"[{plugin}] Event handler error: {msg}"` and never propagated.
+pub async fn handle_runtime_event<D: AccountSelectEventDeps>(
+    event: &RuntimeEvent,
+    deps: &mut D,
+    params: &mut RuntimeEventParams<'_>,
+) {
+    if let Err(error) = handle_account_select_event(event, deps).await {
+        (params.log_debug)(&format!(
+            "[{}] Event handler error: {}",
+            params.plugin_name,
+            error.message()
+        ));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::errors::CodexError;
+    use cma_core::schemas::account_storage::AccountStorageV3;
+    use serde_json::json;
+
+    /// Deps whose save always fails — proves the wrapper swallows errors.
+    struct FailingDeps;
+
+    impl AccountSelectEventDeps for FailingDeps {
+        fn provider_id(&self) -> &str {
+            "openai"
+        }
+        async fn load_accounts(&mut self) -> Result<Option<AccountStorageV3>, CodexError> {
+            let mut storage = AccountStorageV3::empty();
+            storage.accounts.push(
+                cma_core::schemas::account_storage::AccountMetadataV3::new("rt", 1, 1),
+            );
+            Ok(Some(storage))
+        }
+        async fn save_accounts(&mut self, _: &AccountStorageV3) -> Result<(), CodexError> {
+            Err(CodexError::new("disk full"))
+        }
+        fn has_cached_account_manager(&self) -> bool {
+            false
+        }
+        async fn sync_codex_cli_active_selection_for_index(
+            &mut self,
+            _: usize,
+        ) -> Result<(), CodexError> {
+            Ok(())
+        }
+        fn set_last_codex_cli_active_sync_index(&mut self, _: usize) {}
+        async fn reload_account_manager_from_disk(&mut self) -> Result<(), CodexError> {
+            Ok(())
+        }
+        async fn show_toast(&mut self, _: &str, _: &str) -> Result<(), CodexError> {
+            Ok(())
+        }
+    }
+
+    #[tokio::test]
+    async fn swallows_errors_and_logs_debug_line() {
+        let mut logged = Vec::new();
+        let mut log = |m: &str| logged.push(m.to_string());
+        let event = RuntimeEvent {
+            event_type: "account.select".to_string(),
+            properties: Some(json!({"index": 0})),
+        };
+        handle_runtime_event(
+            &event,
+            &mut FailingDeps,
+            &mut RuntimeEventParams {
+                plugin_name: "codex-multi-auth",
+                log_debug: &mut log,
+            },
+        )
+        .await;
+        assert_eq!(logged.len(), 1);
+        assert!(
+            logged[0].starts_with("[codex-multi-auth] Event handler error: "),
+            "{}",
+            logged[0]
+        );
+        assert!(logged[0].contains("disk full"));
+    }
+}
diff --git a/crates/runtime/src/first_run.rs b/crates/runtime/src/first_run.rs
new file mode 100644
index 000000000..60b10fc8d
--- /dev/null
+++ b/crates/runtime/src/first_run.rs
@@ -0,0 +1,920 @@
+//! Port of `lib/runtime/first-run.ts` — lazy first-run setup (audit roadmap
+//! §4.5.4) replacing the old npm postinstall: detects the packaged Codex
+//! desktop app, auto-binds runtime rotation, installs launcher shortcuts.
+//!
+//! Once per runtime root, guarded by an exclusive-create marker file
+//! (`first-run-setup.json`, **TAB-indented** JSON + trailing `\n`, mode 0o600,
+//! O_EXCL claim so concurrent first invocations run at most once). Every step
+//! is best-effort: failures are debug-logged (messages only — never tokens or
+//! emails) and the command proceeds normally; `ensure_first_run_setup` never
+//! fails the caller.
+//!
+//! CI-detection quirk (spec 10 gotcha 13): any non-empty CI var that is not an
+//! explicit false token counts as CI (`CI=banana` ⇒ CI; `CI=0` ⇒ not CI).
+//! Rotation-enabled defaults TRUE on config error (gotcha 14).
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde::Serialize;
+
+use cma_config::getters::get_codex_runtime_rotation_proxy;
+use cma_config::load::load_plugin_config;
+use cma_core::json_io::{
+    stringify_pretty_tab, write_json_atomic_sync, TrailingNewline, WriteJsonOptions,
+};
+use cma_core::logger::create_logger;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::now_ms;
+
+use crate::app_bind::{bind_codex_app_runtime_rotation, get_app_bind_status, AppBindOptions};
+use crate::app_launcher::{install_codex_app_launcher, AppLauncherOptions};
+
+pub const FIRST_RUN_MARKER_FILE: &str = "first-run-setup.json";
+pub const FIRST_RUN_MARKER_VERSION: i64 = 1;
+
+const TRUE_VALUES: &[&str] = &["1", "true", "yes"];
+const FALSE_VALUES: &[&str] = &["0", "false", "no"];
+const CI_ENV_KEYS: &[&str] = &[
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "BUILDKITE",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+    "JENKINS_URL",
+    "TRAVIS",
+    "APPVEYOR",
+    "BITBUCKET_BUILD_NUMBER",
+];
+
+/// Environment override map for tests (`None` entries are simply absent).
+pub type EnvMap = HashMap<String, String>;
+
+fn env_get(env: Option<&EnvMap>, key: &str) -> Option<String> {
+    match env {
+        Some(map) => map.get(key).cloned(),
+        None => std::env::var(key).ok(),
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FirstRunStepStatus {
+    Completed,
+    Skipped,
+    Failed,
+}
+
+impl FirstRunStepStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            FirstRunStepStatus::Completed => "completed",
+            FirstRunStepStatus::Skipped => "skipped",
+            FirstRunStepStatus::Failed => "failed",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FirstRunSkipReason {
+    Ci,
+    NotInstalled,
+    AlreadyDone,
+    ClaimRace,
+    Error,
+}
+
+impl FirstRunSkipReason {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            FirstRunSkipReason::Ci => "ci",
+            FirstRunSkipReason::NotInstalled => "not-installed",
+            FirstRunSkipReason::AlreadyDone => "already-done",
+            FirstRunSkipReason::ClaimRace => "claim-race",
+            FirstRunSkipReason::Error => "error",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FirstRunResult {
+    Ran {
+        app_bind: FirstRunStepStatus,
+        launcher: FirstRunStepStatus,
+    },
+    Skipped(FirstRunSkipReason),
+}
+
+/// A setup step: resolves to a status, or an error message (mapped to
+/// `"failed"` + debug log by the runner — the TS `catch` branch).
+pub type FirstRunStep = Box<
+    dyn FnOnce() -> Pin<Box<dyn Future<Output = Result<FirstRunStepStatus, String>> + Send>>
+        + Send,
+>;
+
+/// Test-injectable dependencies (TS `FirstRunSetupDeps`).
+#[derive(Default)]
+pub struct FirstRunSetupDeps {
+    pub env: Option<EnvMap>,
+    pub marker_path: Option<PathBuf>,
+    pub installed_context: Option<bool>,
+    pub detect_desktop_app: Option<Box<dyn Fn() -> bool + Send + Sync>>,
+    pub resolve_rotation: Option<Box<dyn Fn() -> bool + Send + Sync>>,
+    pub bind_codex_app: Option<FirstRunStep>,
+    pub install_launcher: Option<FirstRunStep>,
+    pub notify: Option<crate::app_launcher::SharedLogSink>,
+    pub now: Option<crate::app_bind::NowFn>,
+}
+
+/// `readOptionalBoolean` — tri-state: TRUE_VALUES → true, FALSE_VALUES →
+/// false, unset/blank/unknown → None.
+fn read_optional_boolean(value: Option<&str>) -> Option<bool> {
+    let value = value?;
+    if value.trim().is_empty() {
+        return None;
+    }
+    let normalized = value.trim().to_lowercase();
+    if TRUE_VALUES.contains(&normalized.as_str()) {
+        return Some(true);
+    }
+    if FALSE_VALUES.contains(&normalized.as_str()) {
+        return Some(false);
+    }
+    None
+}
+
+/// Set + non-blank + not an explicit false token ⇒ enabled (`CI=banana` is
+/// enabled; `CI=0` is not).
+fn is_enabled_env_flag(env: Option<&EnvMap>, key: &str) -> bool {
+    let Some(value) = env_get(env, key) else {
+        return false;
+    };
+    if value.trim().is_empty() {
+        return false;
+    }
+    read_optional_boolean(Some(&value)) != Some(false)
+}
+
+pub fn is_ci_environment(env: Option<&EnvMap>) -> bool {
+    if read_optional_boolean(env_get(env, "npm_config_ignore_scripts").as_deref()) == Some(true) {
+        return true;
+    }
+    CI_ENV_KEYS.iter().any(|key| is_enabled_env_flag(env, key))
+}
+
+fn directory_contains_entry_with_prefix(directory: &Path, prefix: &str) -> bool {
+    match std::fs::read_dir(directory) {
+        Ok(entries) => entries.flatten().any(|entry| {
+            entry
+                .file_name()
+                .to_string_lossy()
+                .starts_with(prefix)
+        }),
+        Err(_) => false,
+    }
+}
+
+/// `hasCodexDesktopApp` — win32: `OpenAI.Codex_*` under
+/// `%LOCALAPPDATA%\Packages` (fallback `home/AppData/Local`) or
+/// `%ProgramFiles%|%ProgramW6432%\WindowsApps` (fallback
+/// `C:\Program Files`); darwin: `Codex.app` under `/Applications` or
+/// `~/Applications`; other platforms: false. Directory read failures → false.
+pub fn has_codex_desktop_app(
+    env: Option<&EnvMap>,
+    platform: Option<&str>,
+    home: Option<&Path>,
+) -> bool {
+    let platform = platform.unwrap_or(crate::app_bind::current_platform());
+    let default_home;
+    let home = match home {
+        Some(home) => home,
+        None => {
+            default_home = env_get(env, "USERPROFILE")
+                .or_else(|| env_get(env, "HOME"))
+                .map(PathBuf::from)
+                .unwrap_or_else(|| PathBuf::from("."));
+            &default_home
+        }
+    };
+
+    if platform == "win32" {
+        let local_app_data = env_get(env, "LOCALAPPDATA")
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from)
+            .unwrap_or_else(|| home.join("AppData").join("Local"));
+        let program_files = env_get(env, "ProgramFiles")
+            .or_else(|| env_get(env, "ProgramW6432"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from)
+            .unwrap_or_else(|| PathBuf::from("C:\\Program Files"));
+        return directory_contains_entry_with_prefix(
+            &local_app_data.join("Packages"),
+            "OpenAI.Codex_",
+        ) || directory_contains_entry_with_prefix(
+            &program_files.join("WindowsApps"),
+            "OpenAI.Codex_",
+        );
+    }
+
+    if platform == "darwin" {
+        return Path::new("/Applications/Codex.app").exists()
+            || home.join("Applications").join("Codex.app").exists();
+    }
+
+    false
+}
+
+/// `resolveRotationEnabled` — env override
+/// `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY` wins; else the config reader;
+/// reader errors default to **true** (rotation defaults on; a malformed
+/// config must not block first-run setup).
+pub fn resolve_rotation_enabled(
+    env: Option<&EnvMap>,
+    read_config_rotation: impl Fn() -> Result<bool, String>,
+) -> bool {
+    if let Some(env_override) = read_optional_boolean(
+        env_get(env, "CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY").as_deref(),
+    ) {
+        return env_override;
+    }
+    read_config_rotation().unwrap_or(true)
+}
+
+fn default_read_config_rotation() -> Result<bool, String> {
+    Ok(get_codex_runtime_rotation_proxy(&load_plugin_config()))
+}
+
+/// `shouldBindCodexAppOnFirstRun` — CI always wins; then
+/// `CODEX_MULTI_AUTH_APP_BIND` (tri-state), then
+/// `CODEX_MULTI_AUTH_APP_BIND_INSTALL` (tri-state), then
+/// `rotation_enabled && app_detected`.
+pub fn should_bind_codex_app_on_first_run(
+    env: Option<&EnvMap>,
+    rotation_enabled: bool,
+    app_detected: bool,
+) -> bool {
+    if is_ci_environment(env) {
+        return false;
+    }
+    if let Some(bind_override) =
+        read_optional_boolean(env_get(env, "CODEX_MULTI_AUTH_APP_BIND").as_deref())
+    {
+        return bind_override;
+    }
+    if let Some(install_override) =
+        read_optional_boolean(env_get(env, "CODEX_MULTI_AUTH_APP_BIND_INSTALL").as_deref())
+    {
+        return install_override;
+    }
+    if !rotation_enabled {
+        return false;
+    }
+    app_detected
+}
+
+/// `shouldInstallCodexAppLauncherOnFirstRun` — CI wins; then
+/// `CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL` (tri-state), then
+/// `rotation_enabled`.
+pub fn should_install_codex_app_launcher_on_first_run(
+    env: Option<&EnvMap>,
+    rotation_enabled: bool,
+) -> bool {
+    if is_ci_environment(env) {
+        return false;
+    }
+    if let Some(install_override) =
+        read_optional_boolean(env_get(env, "CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL").as_deref())
+    {
+        return install_override;
+    }
+    rotation_enabled
+}
+
+/// First-run setup only fires for a durable, machine-level install.
+///
+/// The TS gate keyed off the module path (`node_modules` + not `_npx` + not
+/// project-local). The Rust binary has no `node_modules` analogue, so the
+/// port's explicit equivalent semantics (spec 10 §3 port note) are:
+///
+/// - NOT an npx cache run (`_npx` path segment) — someone trying the tool once
+///   must not burn the once-only marker;
+/// - NOT a cargo dev build (a `target/debug` or `target/release` segment pair
+///   — repo checkouts and test runs stay side-effect-free);
+/// - NOT inside the invoking working directory (a project-local binary is not
+///   a machine-level install).
+pub fn is_installed_package_context(exe_path: Option<&Path>, cwd: Option<&Path>) -> bool {
+    let resolved_exe;
+    let exe_path = match exe_path {
+        Some(path) => path,
+        None => match std::env::current_exe() {
+            Ok(path) => {
+                resolved_exe = path;
+                &resolved_exe
+            }
+            Err(_) => return false,
+        },
+    };
+    let resolved_cwd;
+    let cwd = match cwd {
+        Some(path) => path,
+        None => match std::env::current_dir() {
+            Ok(path) => {
+                resolved_cwd = path;
+                &resolved_cwd
+            }
+            Err(_) => return false,
+        },
+    };
+
+    let segments: Vec<String> = exe_path
+        .components()
+        .map(|component| component.as_os_str().to_string_lossy().into_owned())
+        .collect();
+    if segments.iter().any(|segment| segment == "_npx") {
+        return false;
+    }
+    let is_cargo_build_dir = segments.windows(2).any(|pair| {
+        pair[0] == "target" && (pair[1] == "debug" || pair[1] == "release")
+    });
+    if is_cargo_build_dir {
+        return false;
+    }
+    if exe_path.starts_with(cwd) {
+        return false;
+    }
+    true
+}
+
+fn get_first_run_marker_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(FIRST_RUN_MARKER_FILE)
+}
+
+#[derive(Serialize)]
+struct ClaimMarker {
+    version: i64,
+    #[serde(rename = "startedAt")]
+    started_at: i64,
+}
+
+#[derive(Serialize)]
+struct FinalMarker {
+    version: i64,
+    #[serde(rename = "startedAt")]
+    started_at: i64,
+    #[serde(rename = "completedAt")]
+    completed_at: i64,
+    #[serde(rename = "appBind")]
+    app_bind: &'static str,
+    launcher: &'static str,
+}
+
+/// Claims the marker with an exclusive create (O_EXCL, mode 0o600, payload
+/// `{"version":1,"startedAt":N}` TAB-indented + `\n`) so at most one process
+/// runs the setup. `Ok(false)` when another process already holds (or
+/// completed) the claim.
+fn claim_first_run_marker(marker_path: &Path, started_at: i64) -> io::Result<bool> {
+    if let Some(parent) = marker_path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let payload = format!(
+        "{}\n",
+        stringify_pretty_tab(&ClaimMarker {
+            version: FIRST_RUN_MARKER_VERSION,
+            started_at,
+        })
+    );
+    let mut open_options = std::fs::OpenOptions::new();
+    open_options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        open_options.mode(0o600);
+    }
+    match open_options.open(marker_path) {
+        Ok(mut file) => {
+            use std::io::Write;
+            file.write_all(payload.as_bytes())?;
+            Ok(true)
+        }
+        Err(error) if error.kind() == io::ErrorKind::AlreadyExists => Ok(false),
+        Err(error) => Err(error),
+    }
+}
+
+/// Finalize the marker atomically. Failures are only debug-logged — the claim
+/// file already guarantees once-only behavior.
+fn finalize_first_run_marker(
+    marker_path: &Path,
+    started_at: i64,
+    app_bind: FirstRunStepStatus,
+    launcher: FirstRunStepStatus,
+    now: i64,
+) {
+    let payload = stringify_pretty_tab(&FinalMarker {
+        version: FIRST_RUN_MARKER_VERSION,
+        started_at,
+        completed_at: now,
+        app_bind: app_bind.as_str(),
+        launcher: launcher.as_str(),
+    });
+    let result = write_json_atomic_sync(
+        marker_path,
+        &payload,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::Lf,
+            ..WriteJsonOptions::default()
+        },
+    );
+    if let Err(error) = result {
+        create_logger("first-run").debug(
+            "first-run marker finalize failed",
+            Some(&serde_json::json!({ "error": error.to_string() })),
+        );
+    }
+}
+
+async fn default_bind_codex_app(
+    env: Option<&EnvMap>,
+    rotation_enabled: bool,
+    detect_desktop_app: &(dyn Fn() -> bool + Send + Sync),
+    notify: &(dyn Fn(&str) + Send + Sync),
+) -> Result<FirstRunStepStatus, String> {
+    let current_status = get_app_bind_status(&AppBindOptions::default()).await.ok();
+    let app_detected =
+        detect_desktop_app() || current_status.map(|status| status.bound) == Some(true);
+    if !should_bind_codex_app_on_first_run(env, rotation_enabled, app_detected) {
+        return Ok(FirstRunStepStatus::Skipped);
+    }
+    let result = bind_codex_app_runtime_rotation(&AppBindOptions::default()).await?;
+    if !result.message.is_empty() {
+        notify(&result.message);
+    }
+    Ok(FirstRunStepStatus::Completed)
+}
+
+async fn default_install_launcher(
+    env: Option<&EnvMap>,
+    rotation_enabled: bool,
+    notify: Arc<dyn Fn(&str) + Send + Sync>,
+) -> Result<FirstRunStepStatus, String> {
+    if !should_install_codex_app_launcher_on_first_run(env, rotation_enabled) {
+        return Ok(FirstRunStepStatus::Skipped);
+    }
+    // TS resolved the installer with a dynamic import (`loadLauncherInstall`)
+    // and skipped when the script was missing; the Rust launcher is compiled
+    // into this crate, so it is always present.
+    install_codex_app_launcher(&AppLauncherOptions {
+        log: Some(notify),
+        ..AppLauncherOptions::default()
+    })
+    .await?;
+    Ok(FirstRunStepStatus::Completed)
+}
+
+/// Runs the lazily deferred install setup (Codex app bind + launcher routing)
+/// exactly once per runtime root. Never fails the caller: every error path
+/// resolves with a skip/failed status and only debug-logs sanitized messages.
+pub async fn ensure_first_run_setup(deps: FirstRunSetupDeps) -> FirstRunResult {
+    let log = create_logger("first-run");
+    match ensure_first_run_setup_inner(deps, &log).await {
+        Ok(result) => result,
+        Err(error) => {
+            log.debug(
+                "first-run setup skipped",
+                Some(&serde_json::json!({ "error": error })),
+            );
+            FirstRunResult::Skipped(FirstRunSkipReason::Error)
+        }
+    }
+}
+
+async fn ensure_first_run_setup_inner(
+    deps: FirstRunSetupDeps,
+    log: &cma_core::logger::ScopedLogger,
+) -> Result<FirstRunResult, String> {
+    let env = deps.env;
+    let env_ref = env.as_ref();
+    if is_ci_environment(env_ref) {
+        return Ok(FirstRunResult::Skipped(FirstRunSkipReason::Ci));
+    }
+    let installed = deps
+        .installed_context
+        .unwrap_or_else(|| is_installed_package_context(None, None));
+    if !installed {
+        return Ok(FirstRunResult::Skipped(FirstRunSkipReason::NotInstalled));
+    }
+    let marker_path = deps.marker_path.unwrap_or_else(get_first_run_marker_path);
+    if marker_path.exists() {
+        return Ok(FirstRunResult::Skipped(FirstRunSkipReason::AlreadyDone));
+    }
+    let now: Box<dyn Fn() -> i64 + Send + Sync> = deps.now.unwrap_or_else(|| Box::new(now_ms));
+    let started_at = now();
+    if !claim_first_run_marker(&marker_path, started_at).map_err(|error| error.to_string())? {
+        return Ok(FirstRunResult::Skipped(FirstRunSkipReason::ClaimRace));
+    }
+
+    // Library default goes through the structured logger; the CLI entrypoint
+    // passes a stderr notify so interactive users still see bind messages.
+    let notify: Arc<dyn Fn(&str) + Send + Sync> = deps.notify.unwrap_or_else(|| {
+        Arc::new(|message: &str| {
+            create_logger("first-run").info(message, None);
+        })
+    });
+    let detect_desktop_app: Box<dyn Fn() -> bool + Send + Sync> =
+        deps.detect_desktop_app.unwrap_or_else(|| {
+            let env = env.clone();
+            Box::new(move || has_codex_desktop_app(env.as_ref(), None, None))
+        });
+    let rotation_enabled = match &deps.resolve_rotation {
+        Some(resolve) => resolve(),
+        None => resolve_rotation_enabled(env.as_ref(), default_read_config_rotation),
+    };
+
+    let app_bind_result = match deps.bind_codex_app {
+        Some(step) => step().await,
+        None => {
+            default_bind_codex_app(
+                env.as_ref(),
+                rotation_enabled,
+                detect_desktop_app.as_ref(),
+                notify.as_ref(),
+            )
+            .await
+        }
+    };
+    let app_bind = match app_bind_result {
+        Ok(status) => status,
+        Err(error) => {
+            log.debug(
+                "first-run app bind skipped",
+                Some(&serde_json::json!({ "error": error })),
+            );
+            FirstRunStepStatus::Failed
+        }
+    };
+
+    let launcher_result = match deps.install_launcher {
+        Some(step) => step().await,
+        None => default_install_launcher(env.as_ref(), rotation_enabled, notify.clone()).await,
+    };
+    let launcher = match launcher_result {
+        Ok(status) => status,
+        Err(error) => {
+            log.debug(
+                "first-run launcher install skipped",
+                Some(&serde_json::json!({ "error": error })),
+            );
+            FirstRunStepStatus::Failed
+        }
+    };
+
+    finalize_first_run_marker(&marker_path, started_at, app_bind, launcher, now());
+    Ok(FirstRunResult::Ran { app_bind, launcher })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    fn env_of(pairs: &[(&str, &str)]) -> EnvMap {
+        pairs
+            .iter()
+            .map(|(key, value)| (key.to_string(), value.to_string()))
+            .collect()
+    }
+
+    fn step(status: FirstRunStepStatus) -> FirstRunStep {
+        Box::new(move || Box::pin(async move { Ok(status) }))
+    }
+
+    fn failing_step(message: &'static str) -> FirstRunStep {
+        Box::new(move || Box::pin(async move { Err(message.to_string()) }))
+    }
+
+    // first-run.test.ts: "detects the packaged Windows Codex app from
+    // LOCALAPPDATA packages"
+    #[test]
+    fn detects_the_packaged_windows_codex_app_from_localappdata_packages() {
+        let temp = tempfile::tempdir().unwrap();
+        let local_app_data = temp.path().join("Local");
+        std::fs::create_dir_all(local_app_data.join("Packages").join("OpenAI.Codex_1.0_x64"))
+            .unwrap();
+        let env = env_of(&[("LOCALAPPDATA", &local_app_data.to_string_lossy())]);
+        assert!(has_codex_desktop_app(
+            Some(&env),
+            Some("win32"),
+            Some(temp.path())
+        ));
+        // Without the package entry → false.
+        let empty = tempfile::tempdir().unwrap();
+        let env = env_of(&[(
+            "LOCALAPPDATA",
+            &empty.path().join("Local").to_string_lossy(),
+        )]);
+        assert!(!has_codex_desktop_app(
+            Some(&env),
+            Some("win32"),
+            Some(empty.path())
+        ));
+        // Non-desktop platforms → false.
+        assert!(!has_codex_desktop_app(Some(&EnvMap::new()), Some("linux"), None));
+    }
+
+    // "binds the Codex app on first run only when detected with rotation
+    // enabled"
+    #[test]
+    fn binds_only_when_detected_with_rotation_enabled() {
+        let empty = EnvMap::new();
+        assert!(should_bind_codex_app_on_first_run(Some(&empty), true, true));
+        assert!(!should_bind_codex_app_on_first_run(Some(&empty), true, false));
+        assert!(!should_bind_codex_app_on_first_run(Some(&empty), false, true));
+        // Env override wins over detection.
+        let on = env_of(&[("CODEX_MULTI_AUTH_APP_BIND", "1")]);
+        assert!(should_bind_codex_app_on_first_run(Some(&on), false, false));
+        let off = env_of(&[("CODEX_MULTI_AUTH_APP_BIND", "no")]);
+        assert!(!should_bind_codex_app_on_first_run(Some(&off), true, true));
+        // _INSTALL fallback override is consulted after APP_BIND.
+        let install_on = env_of(&[("CODEX_MULTI_AUTH_APP_BIND_INSTALL", "yes")]);
+        assert!(should_bind_codex_app_on_first_run(Some(&install_on), false, false));
+        let bind_wins = env_of(&[
+            ("CODEX_MULTI_AUTH_APP_BIND", "0"),
+            ("CODEX_MULTI_AUTH_APP_BIND_INSTALL", "1"),
+        ]);
+        assert!(!should_bind_codex_app_on_first_run(Some(&bind_wins), true, true));
+        // Unknown token → no override.
+        let junk = env_of(&[("CODEX_MULTI_AUTH_APP_BIND", "banana")]);
+        assert!(should_bind_codex_app_on_first_run(Some(&junk), true, true));
+        assert!(!should_bind_codex_app_on_first_run(Some(&junk), false, true));
+    }
+
+    // "keeps CI and ignored-scripts guards ahead of explicit opt-ins"
+    #[test]
+    fn keeps_ci_and_ignored_scripts_guards_ahead_of_explicit_opt_ins() {
+        let ci = env_of(&[("CI", "1"), ("CODEX_MULTI_AUTH_APP_BIND", "1")]);
+        assert!(!should_bind_codex_app_on_first_run(Some(&ci), true, true));
+        let ci = env_of(&[
+            ("CI", "banana"),
+            ("CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL", "1"),
+        ]);
+        assert!(!should_install_codex_app_launcher_on_first_run(Some(&ci), true));
+        // Explicit false CI token does NOT count as CI.
+        let not_ci = env_of(&[("CI", "0")]);
+        assert!(!is_ci_environment(Some(&not_ci)));
+        assert!(should_install_codex_app_launcher_on_first_run(Some(&not_ci), true));
+        // npm_config_ignore_scripts=true counts as CI.
+        let ignored = env_of(&[("npm_config_ignore_scripts", "true")]);
+        assert!(is_ci_environment(Some(&ignored)));
+        // CI=banana counts as CI (gotcha 13).
+        let banana = env_of(&[("CI", "banana")]);
+        assert!(is_ci_environment(Some(&banana)));
+        assert!(!is_ci_environment(Some(&EnvMap::new())));
+    }
+
+    // "installs launcher routing on first run when rotation is enabled"
+    #[test]
+    fn installs_launcher_routing_when_rotation_is_enabled() {
+        let empty = EnvMap::new();
+        assert!(should_install_codex_app_launcher_on_first_run(Some(&empty), true));
+        assert!(!should_install_codex_app_launcher_on_first_run(Some(&empty), false));
+        let off = env_of(&[("CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL", "false")]);
+        assert!(!should_install_codex_app_launcher_on_first_run(Some(&off), true));
+        let on = env_of(&[("CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL", "1")]);
+        assert!(should_install_codex_app_launcher_on_first_run(Some(&on), false));
+    }
+
+    // "resolves rotation default-on with env override and config fallback"
+    #[test]
+    fn resolves_rotation_default_on_with_env_override_and_config_fallback() {
+        let empty = EnvMap::new();
+        assert!(resolve_rotation_enabled(Some(&empty), || Ok(true)));
+        assert!(!resolve_rotation_enabled(Some(&empty), || Ok(false)));
+        // Config error → default TRUE (gotcha 14).
+        assert!(resolve_rotation_enabled(Some(&empty), || Err(
+            "boom".to_string()
+        )));
+        let off = env_of(&[("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY", "0")]);
+        assert!(!resolve_rotation_enabled(Some(&off), || Ok(true)));
+        let on = env_of(&[("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY", "yes")]);
+        assert!(resolve_rotation_enabled(Some(&on), || Ok(false)));
+        // Unknown token → no override, config wins.
+        let junk = env_of(&[("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY", "maybe")]);
+        assert!(!resolve_rotation_enabled(Some(&junk), || Ok(false)));
+    }
+
+    // "only treats durable global-style installs as installed package
+    // contexts" (semantics adapted to the Rust binary, see fn docs).
+    #[test]
+    fn only_treats_durable_installs_as_installed_package_contexts() {
+        let cwd = Path::new("/work/project");
+        // Durable install outside cwd → true.
+        assert!(is_installed_package_context(
+            Some(Path::new("/home/user/.cargo/bin/codex-multi-auth")),
+            Some(cwd),
+        ));
+        // Cargo dev build → false.
+        assert!(!is_installed_package_context(
+            Some(Path::new("/repo/target/debug/codex-multi-auth")),
+            Some(cwd),
+        ));
+        assert!(!is_installed_package_context(
+            Some(Path::new("/repo/target/release/codex-multi-auth")),
+            Some(cwd),
+        ));
+        // npx cache run → false.
+        assert!(!is_installed_package_context(
+            Some(Path::new("/home/user/.npm/_npx/abc123/node_modules/.bin/codex-multi-auth")),
+            Some(cwd),
+        ));
+        // Project-local (inside cwd) → false.
+        assert!(!is_installed_package_context(
+            Some(Path::new("/work/project/bin/codex-multi-auth")),
+            Some(cwd),
+        ));
+    }
+
+    // "runs setup once and records the outcome in the marker"
+    #[tokio::test]
+    async fn runs_setup_once_and_records_the_outcome_in_the_marker() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join("mad").join(FIRST_RUN_MARKER_FILE);
+        let result = ensure_first_run_setup(FirstRunSetupDeps {
+            env: Some(EnvMap::new()),
+            marker_path: Some(marker_path.clone()),
+            installed_context: Some(true),
+            bind_codex_app: Some(step(FirstRunStepStatus::Completed)),
+            install_launcher: Some(step(FirstRunStepStatus::Skipped)),
+            now: Some(Box::new(|| 777)),
+            ..FirstRunSetupDeps::default()
+        })
+        .await;
+        assert_eq!(
+            result,
+            FirstRunResult::Ran {
+                app_bind: FirstRunStepStatus::Completed,
+                launcher: FirstRunStepStatus::Skipped,
+            }
+        );
+        let raw = std::fs::read_to_string(&marker_path).unwrap();
+        // TAB-indented, trailing newline, exact field set.
+        assert!(raw.starts_with("{\n\t\"version\": 1"));
+        assert!(raw.ends_with("\n"));
+        assert!(raw.contains("\t\"startedAt\": 777"));
+        assert!(raw.contains("\t\"completedAt\": 777"));
+        assert!(raw.contains("\t\"appBind\": \"completed\""));
+        assert!(raw.contains("\t\"launcher\": \"skipped\""));
+    }
+
+    // "skips setup on the second run once the marker exists"
+    #[tokio::test]
+    async fn skips_setup_on_the_second_run_once_the_marker_exists() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join(FIRST_RUN_MARKER_FILE);
+        let deps = || FirstRunSetupDeps {
+            env: Some(EnvMap::new()),
+            marker_path: Some(marker_path.clone()),
+            installed_context: Some(true),
+            bind_codex_app: Some(step(FirstRunStepStatus::Completed)),
+            install_launcher: Some(step(FirstRunStepStatus::Completed)),
+            ..FirstRunSetupDeps::default()
+        };
+        let first = ensure_first_run_setup(deps()).await;
+        assert!(matches!(first, FirstRunResult::Ran { .. }));
+        let second = ensure_first_run_setup(deps()).await;
+        assert_eq!(
+            second,
+            FirstRunResult::Skipped(FirstRunSkipReason::AlreadyDone)
+        );
+    }
+
+    // "runs setup at most once under concurrent first invocations" — the
+    // claim itself is the cross-process gate.
+    #[test]
+    fn claim_marker_is_exclusive() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join("nested").join(FIRST_RUN_MARKER_FILE);
+        assert!(claim_first_run_marker(&marker_path, 1).unwrap());
+        assert!(!claim_first_run_marker(&marker_path, 2).unwrap());
+        let raw = std::fs::read_to_string(&marker_path).unwrap();
+        assert_eq!(raw, "{\n\t\"version\": 1,\n\t\"startedAt\": 1\n}\n");
+    }
+
+    // "never fails the command when setup steps throw, and still writes the
+    // marker"
+    #[tokio::test]
+    async fn never_fails_when_setup_steps_error_and_still_writes_the_marker() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join(FIRST_RUN_MARKER_FILE);
+        let result = ensure_first_run_setup(FirstRunSetupDeps {
+            env: Some(EnvMap::new()),
+            marker_path: Some(marker_path.clone()),
+            installed_context: Some(true),
+            bind_codex_app: Some(failing_step("bind exploded")),
+            install_launcher: Some(failing_step("launcher exploded")),
+            ..FirstRunSetupDeps::default()
+        })
+        .await;
+        assert_eq!(
+            result,
+            FirstRunResult::Ran {
+                app_bind: FirstRunStepStatus::Failed,
+                launcher: FirstRunStepStatus::Failed,
+            }
+        );
+        let raw = std::fs::read_to_string(&marker_path).unwrap();
+        assert!(raw.contains("\"appBind\": \"failed\""));
+        assert!(raw.contains("\"launcher\": \"failed\""));
+    }
+
+    // "resolves instead of throwing when even the marker claim fails"
+    #[tokio::test]
+    async fn resolves_instead_of_throwing_when_even_the_marker_claim_fails() {
+        let temp = tempfile::tempdir().unwrap();
+        // Marker path IS a directory → exists() false? No: a dir exists().
+        // Use a path whose parent is a FILE so mkdir fails.
+        let blocker = temp.path().join("blocker");
+        std::fs::write(&blocker, "x").unwrap();
+        let marker_path = blocker.join(FIRST_RUN_MARKER_FILE);
+        let result = ensure_first_run_setup(FirstRunSetupDeps {
+            env: Some(EnvMap::new()),
+            marker_path: Some(marker_path),
+            installed_context: Some(true),
+            bind_codex_app: Some(step(FirstRunStepStatus::Completed)),
+            install_launcher: Some(step(FirstRunStepStatus::Completed)),
+            ..FirstRunSetupDeps::default()
+        })
+        .await;
+        assert_eq!(result, FirstRunResult::Skipped(FirstRunSkipReason::Error));
+    }
+
+    // "skips entirely in CI without creating the marker"
+    #[tokio::test]
+    async fn skips_entirely_in_ci_without_creating_the_marker() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join(FIRST_RUN_MARKER_FILE);
+        let result = ensure_first_run_setup(FirstRunSetupDeps {
+            env: Some(env_of(&[("CI", "true")])),
+            marker_path: Some(marker_path.clone()),
+            installed_context: Some(true),
+            ..FirstRunSetupDeps::default()
+        })
+        .await;
+        assert_eq!(result, FirstRunResult::Skipped(FirstRunSkipReason::Ci));
+        assert!(!marker_path.exists());
+    }
+
+    // "skips outside installed package contexts without touching the
+    // filesystem"
+    #[tokio::test]
+    async fn skips_outside_installed_package_contexts_without_touching_the_filesystem() {
+        let temp = tempfile::tempdir().unwrap();
+        let marker_path = temp.path().join(FIRST_RUN_MARKER_FILE);
+        let result = ensure_first_run_setup(FirstRunSetupDeps {
+            env: Some(EnvMap::new()),
+            marker_path: Some(marker_path.clone()),
+            installed_context: Some(false),
+            ..FirstRunSetupDeps::default()
+        })
+        .await;
+        assert_eq!(
+            result,
+            FirstRunResult::Skipped(FirstRunSkipReason::NotInstalled)
+        );
+        assert!(!marker_path.exists());
+    }
+
+    #[test]
+    fn read_optional_boolean_tri_state() {
+        assert_eq!(read_optional_boolean(None), None);
+        assert_eq!(read_optional_boolean(Some("")), None);
+        assert_eq!(read_optional_boolean(Some("  ")), None);
+        assert_eq!(read_optional_boolean(Some("1")), Some(true));
+        assert_eq!(read_optional_boolean(Some("TRUE")), Some(true));
+        assert_eq!(read_optional_boolean(Some(" yes ")), Some(true));
+        assert_eq!(read_optional_boolean(Some("0")), Some(false));
+        assert_eq!(read_optional_boolean(Some("False")), Some(false));
+        assert_eq!(read_optional_boolean(Some("no")), Some(false));
+        assert_eq!(read_optional_boolean(Some("banana")), None);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn is_ci_environment_reads_process_env_when_no_map_given() {
+        let mut sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        for key in CI_ENV_KEYS {
+            sandbox.remove_var(key);
+        }
+        sandbox.remove_var("npm_config_ignore_scripts");
+        assert!(!is_ci_environment(None));
+        sandbox.set_var("CI", "1");
+        assert!(is_ci_environment(None));
+    }
+}
diff --git a/crates/runtime/src/hydrate_emails.rs b/crates/runtime/src/hydrate_emails.rs
new file mode 100644
index 000000000..243d0dac7
--- /dev/null
+++ b/crates/runtime/src/hydrate_emails.rs
@@ -0,0 +1,314 @@
+//! Port of `lib/runtime/hydrate-emails.ts` — backfills missing account
+//! emails via queued token refreshes (spec 10 §15).
+//!
+//! Gotcha 7: patches are applied **by index, never by accountId** — multiple
+//! accounts can share `accountId === undefined`, and an id-keyed map would
+//! collapse them and cross-apply tokens.
+//!
+//! Deviation (recorded): the TS version refreshes all targets in parallel
+//! (`Promise.all`); the Rust port awaits them sequentially (the runtime
+//! crate has no join-all dependency; `queuedRefresh` already serializes
+//! same-token refreshes, so only wall-clock time differs).
+
+use cma_core::errors::CodexError;
+use cma_core::schemas::account_storage::{AccountIdSource, AccountStorageV3};
+use cma_core::schemas::token::TokenResult;
+use cma_core::token_utils::{
+    extract_account_email, extract_account_id, sanitize_email, should_update_account_id_from_token,
+};
+
+/// I/O seams of [`hydrate_runtime_emails`].
+#[allow(async_fn_in_trait)]
+pub trait HydrateEmailsDeps {
+    async fn queued_refresh(&mut self, refresh_token: &str) -> TokenResult;
+    async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError>;
+    fn log_warn(&mut self, message: &str);
+    fn plugin_name(&self) -> &str;
+}
+
+/// TS skip guard: `VITEST_WORKER_ID` set, `NODE_ENV === "test"`, or
+/// `CODEX_SKIP_EMAIL_HYDRATE === "1"`.
+fn should_skip_hydrate() -> bool {
+    std::env::var_os("VITEST_WORKER_ID").is_some()
+        || std::env::var("NODE_ENV").is_ok_and(|v| v == "test")
+        || std::env::var("CODEX_SKIP_EMAIL_HYDRATE").is_ok_and(|v| v == "1")
+}
+
+/// TS `hydrateRuntimeEmails(storage, deps)` — returns the (possibly
+/// mutated) storage.
+pub async fn hydrate_runtime_emails<D: HydrateEmailsDeps>(
+    storage: Option<AccountStorageV3>,
+    deps: &mut D,
+) -> Result<Option<AccountStorageV3>, CodexError> {
+    let Some(mut storage) = storage else {
+        return Ok(None);
+    };
+    if should_skip_hydrate() {
+        return Ok(Some(storage));
+    }
+
+    let mut accounts_copy = storage.accounts.clone();
+    let targets: Vec<usize> = accounts_copy
+        .iter()
+        .enumerate()
+        .filter(|(_, account)| {
+            account
+                .email
+                .as_deref()
+                .is_none_or(str::is_empty)
+        })
+        .map(|(index, _)| index)
+        .collect();
+    if targets.is_empty() {
+        return Ok(Some(storage));
+    }
+
+    let mut changed = false;
+    for index in targets {
+        let refresh_token = accounts_copy[index].refresh_token.clone();
+        let refreshed = deps.queued_refresh(&refresh_token).await;
+        let TokenResult::Success(refreshed) = refreshed else {
+            continue;
+        };
+        let account = &mut accounts_copy[index];
+
+        let id = extract_account_id(Some(&refreshed.access));
+        let email = sanitize_email(
+            extract_account_email(Some(&refreshed.access), refreshed.id_token.as_deref())
+                .as_deref(),
+        );
+        if let Some(id) = id.as_deref()
+            && Some(id) != account.account_id.as_deref()
+            && should_update_account_id_from_token(
+                account.account_id_source.as_ref(),
+                account.account_id.as_deref(),
+            )
+        {
+            account.account_id = Some(id.to_string());
+            account.account_id_source = Some(AccountIdSource::Token);
+            changed = true;
+        }
+        if let Some(email) = email
+            && Some(email.as_str()) != account.email.as_deref()
+        {
+            account.email = Some(email);
+            changed = true;
+        }
+        if !refreshed.access.is_empty()
+            && Some(refreshed.access.as_str()) != account.access_token.as_deref()
+        {
+            account.access_token = Some(refreshed.access.clone());
+            changed = true;
+        }
+        if Some(refreshed.expires) != account.expires_at {
+            account.expires_at = Some(refreshed.expires);
+            changed = true;
+        }
+        if !refreshed.refresh.is_empty() && refreshed.refresh != account.refresh_token {
+            account.refresh_token = refreshed.refresh.clone();
+            changed = true;
+        }
+    }
+
+    // Note: the TS per-account catch (`"[{plugin}] Failed to hydrate email
+    // for account"` via log_warn) guards a throwing queuedRefresh; the Rust
+    // TokenResult already encodes failures as values, so that path is
+    // unreachable by construction (log_warn/plugin_name remain on the trait
+    // for wired implementations that can fail internally).
+
+    if changed {
+        // Patch back by index, never by accountId (gotcha 7).
+        storage.accounts = accounts_copy;
+        deps.save_accounts(&storage).await?;
+    }
+    Ok(Some(storage))
+}
+
+// =============================================================================
+// Tests — ported from test/hydrate-emails.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+    use cma_core::schemas::token::TokenSuccess;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serde_json::json;
+    use serial_test::serial;
+    use std::collections::HashMap;
+
+    /// Minimal base64url (no padding) — no base64 dev-dependency here.
+    fn b64url(bytes: &[u8]) -> String {
+        const ALPHABET: &[u8; 64] =
+            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        let mut out = String::new();
+        for chunk in bytes.chunks(3) {
+            let b = [chunk[0], *chunk.get(1).unwrap_or(&0), *chunk.get(2).unwrap_or(&0)];
+            let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+            out.push(ALPHABET[(n >> 18) as usize & 63] as char);
+            out.push(ALPHABET[(n >> 12) as usize & 63] as char);
+            if chunk.len() > 1 {
+                out.push(ALPHABET[(n >> 6) as usize & 63] as char);
+            }
+            if chunk.len() > 2 {
+                out.push(ALPHABET[n as usize & 63] as char);
+            }
+        }
+        out
+    }
+
+    fn make_jwt(account_id: &str, email: &str) -> String {
+        let header = b64url(br#"{"alg":"none"}"#);
+        let payload = json!({
+            "https://api.openai.com/auth": {"chatgpt_account_id": account_id},
+            "email": email,
+        });
+        let body = b64url(&serde_json::to_vec(&payload).unwrap());
+        format!("{header}.{body}.sig")
+    }
+
+    #[derive(Default)]
+    struct FakeDeps {
+        refresh_by_token: HashMap<String, TokenResult>,
+        refresh_calls: Vec<String>,
+        saved: Option<AccountStorageV3>,
+        warnings: Vec<String>,
+    }
+
+    impl HydrateEmailsDeps for FakeDeps {
+        async fn queued_refresh(&mut self, refresh_token: &str) -> TokenResult {
+            self.refresh_calls.push(refresh_token.to_string());
+            self.refresh_by_token
+                .get(refresh_token)
+                .cloned()
+                .unwrap_or(TokenResult::Failed(Default::default()))
+        }
+        async fn save_accounts(&mut self, storage: &AccountStorageV3) -> Result<(), CodexError> {
+            self.saved = Some(storage.clone());
+            Ok(())
+        }
+        fn log_warn(&mut self, message: &str) {
+            self.warnings.push(message.to_string());
+        }
+        fn plugin_name(&self) -> &str {
+            "codex-multi-auth"
+        }
+    }
+
+    fn sandbox_without_skip() -> EnvSandbox {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var("VITEST_WORKER_ID");
+        sandbox.remove_var("NODE_ENV");
+        sandbox.remove_var("CODEX_SKIP_EMAIL_HYDRATE");
+        sandbox
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn null_storage_passes_through() {
+        let _sandbox = sandbox_without_skip();
+        let mut deps = FakeDeps::default();
+        assert_eq!(hydrate_runtime_emails(None, &mut deps).await.unwrap(), None);
+        assert!(deps.refresh_calls.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn skip_env_gate_returns_storage_untouched() {
+        let mut sandbox = sandbox_without_skip();
+        sandbox.set_var("CODEX_SKIP_EMAIL_HYDRATE", "1");
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("rt-1", 1, 1));
+        let mut deps = FakeDeps::default();
+        let result = hydrate_runtime_emails(Some(storage.clone()), &mut deps)
+            .await
+            .unwrap();
+        assert_eq!(result, Some(storage));
+        assert!(deps.refresh_calls.is_empty());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn hydrates_only_accounts_without_email_and_patches_by_index() {
+        let _sandbox = sandbox_without_skip();
+        let mut storage = AccountStorageV3::empty();
+        // Two accounts WITHOUT email sharing accountId=None, plus one with.
+        storage.accounts.push(AccountMetadataV3::new("rt-a", 1, 1));
+        storage.accounts.push(AccountMetadataV3::new("rt-b", 1, 1));
+        let mut with_email = AccountMetadataV3::new("rt-c", 1, 1);
+        with_email.email = Some("kept@example.com".to_string());
+        storage.accounts.push(with_email);
+
+        let mut deps = FakeDeps::default();
+        deps.refresh_by_token.insert(
+            "rt-a".to_string(),
+            TokenResult::Success(TokenSuccess {
+                access: make_jwt("acc_a", "a@example.com"),
+                refresh: "rt-a2".to_string(),
+                expires: 2_000,
+                id_token: None,
+                multi_account: None,
+            }),
+        );
+        deps.refresh_by_token.insert(
+            "rt-b".to_string(),
+            TokenResult::Success(TokenSuccess {
+                access: make_jwt("acc_b", "b@example.com"),
+                refresh: "rt-b".to_string(),
+                expires: 3_000,
+                id_token: None,
+                multi_account: None,
+            }),
+        );
+
+        let result = hydrate_runtime_emails(Some(storage), &mut deps)
+            .await
+            .unwrap()
+            .expect("storage");
+
+        // Only the two email-less accounts were refreshed.
+        assert_eq!(deps.refresh_calls, vec!["rt-a", "rt-b"]);
+        // Patched by index: each account received ITS OWN tokens.
+        assert_eq!(result.accounts[0].email.as_deref(), Some("a@example.com"));
+        assert_eq!(result.accounts[0].account_id.as_deref(), Some("acc_a"));
+        assert_eq!(result.accounts[0].refresh_token, "rt-a2");
+        assert_eq!(result.accounts[0].expires_at, Some(2_000));
+        assert_eq!(result.accounts[1].email.as_deref(), Some("b@example.com"));
+        assert_eq!(result.accounts[1].account_id.as_deref(), Some("acc_b"));
+        assert_eq!(result.accounts[1].refresh_token, "rt-b");
+        assert_eq!(result.accounts[2].email.as_deref(), Some("kept@example.com"));
+        // Saved once.
+        assert!(deps.saved.is_some());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn failed_refreshes_leave_storage_unsaved() {
+        let _sandbox = sandbox_without_skip();
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("rt-a", 1, 1));
+        let mut deps = FakeDeps::default();
+        let result = hydrate_runtime_emails(Some(storage.clone()), &mut deps)
+            .await
+            .unwrap();
+        assert_eq!(result, Some(storage));
+        assert!(deps.saved.is_none());
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn no_email_less_accounts_short_circuits() {
+        let _sandbox = sandbox_without_skip();
+        let mut storage = AccountStorageV3::empty();
+        let mut account = AccountMetadataV3::new("rt-a", 1, 1);
+        account.email = Some("x@example.com".to_string());
+        storage.accounts.push(account);
+        let mut deps = FakeDeps::default();
+        let result = hydrate_runtime_emails(Some(storage.clone()), &mut deps)
+            .await
+            .unwrap();
+        assert_eq!(result, Some(storage));
+        assert!(deps.refresh_calls.is_empty());
+    }
+}
diff --git a/crates/runtime/src/lib.rs b/crates/runtime/src/lib.rs
new file mode 100644
index 000000000..4b4e58ad2
--- /dev/null
+++ b/crates/runtime/src/lib.rs
@@ -0,0 +1,32 @@
+//! cma-runtime - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_check;
+pub mod account_pool;
+pub mod account_selection;
+pub mod account_state;
+pub mod account_status;
+pub mod app_bind;
+pub mod app_launcher;
+pub mod capability_boost;
+pub mod config_toml;
+pub mod current_account;
+pub mod event_handler;
+pub mod first_run;
+pub mod hydrate_emails;
+pub mod live_sync;
+pub mod loader_setup;
+pub mod login_menu_accounts;
+pub mod manager_cache;
+pub mod oauth_flows;
+pub mod observability;
+pub mod preemptive_quota;
+pub mod proactive_refresh;
+pub mod quota_probe;
+pub mod quota_settings;
+pub mod recovery;
+pub mod refresh_guardian;
+pub mod rotation;
+pub mod services;
+pub mod storage_scope;
+pub mod toast;
+pub mod ui_runtime;
+pub mod verify_flagged;
diff --git a/crates/runtime/src/live_sync.rs b/crates/runtime/src/live_sync.rs
new file mode 100644
index 000000000..2d327817f
--- /dev/null
+++ b/crates/runtime/src/live_sync.rs
@@ -0,0 +1,427 @@
+//! Port of `lib/runtime/live-sync.ts` — the fuller live-account-sync
+//! lifecycle variant with commit-callback state publication (spec 10 §21,
+//! ARCHITECTURE §6.12: "live-sync entry over cma-quota watcher"; the thin
+//! `live-sync-entry.ts` adapter is absorbed into
+//! [`crate::services::ensure_live_account_sync_entry`]).
+
+use crate::refresh_guardian::js_number_string;
+use crate::services::LiveAccountSyncLike;
+use cma_core::types::OAuthAuthDetails;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+/// The `createSync(onChange, options)` change callback: invoked by the
+/// watcher on relevant changes; the production wiring reloads the account
+/// manager from disk.
+pub type LiveSyncOnChange =
+    Arc<dyn Fn() -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync>;
+
+/// `createSync` options pair.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LiveSyncCreateOptions {
+    pub debounce_ms: f64,
+    pub poll_interval_ms: f64,
+}
+
+/// The published lifecycle state (TS `commitState` payload / return value).
+pub struct RuntimeLiveSyncState<TSync> {
+    pub sync: Option<Arc<TSync>>,
+    pub path: Option<String>,
+    pub config_key: Option<String>,
+    pub cleanup_registered: bool,
+}
+
+impl<TSync> Clone for RuntimeLiveSyncState<TSync> {
+    fn clone(&self) -> Self {
+        Self {
+            sync: self.sync.clone(),
+            path: self.path.clone(),
+            config_key: self.config_key.clone(),
+            cleanup_registered: self.cleanup_registered,
+        }
+    }
+}
+
+/// Shared shape of the injected manager-reload hook (production:
+/// `manager_cache::reload_account_manager_from_disk`).
+pub type ReloadAccountManagerFn =
+    Arc<dyn Fn(Option<OAuthAuthDetails>) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync>;
+
+/// TS `ensureRuntimeLiveAccountSync(deps)` deps.
+pub struct EnsureRuntimeLiveAccountSyncDeps<'a, TSync: LiveAccountSyncLike> {
+    /// `${debounceMs}:${pollIntervalMs}` inputs (TS read them from the
+    /// plugin config through injected getters).
+    pub enabled: bool,
+    pub debounce_ms: f64,
+    pub poll_interval_ms: f64,
+    pub target_path: String,
+    pub auth_fallback: Option<OAuthAuthDetails>,
+    pub current_sync: Option<Arc<TSync>>,
+    pub current_path: Option<String>,
+    pub current_config_key: Option<String>,
+    pub current_cleanup_registered: bool,
+    /// Cleanup resolves the CURRENT sync at shutdown time (TS
+    /// `getCurrentSync()?.stop()` — it always stops the latest).
+    pub get_current_sync: Arc<dyn Fn() -> Option<Arc<TSync>> + Send + Sync>,
+    pub create_sync: &'a mut dyn FnMut(LiveSyncOnChange, LiveSyncCreateOptions) -> Arc<TSync>,
+    /// Production: `manager_cache::reload_account_manager_from_disk`.
+    pub reload_account_manager_from_disk: ReloadAccountManagerFn,
+    pub commit_state: &'a mut dyn FnMut(RuntimeLiveSyncState<TSync>),
+    pub register_cleanup: &'a mut dyn FnMut(Box<dyn FnOnce() + Send>),
+    pub log_warn: &'a mut dyn FnMut(&str),
+    pub plugin_name: &'a str,
+}
+
+/// TS `ensureRuntimeLiveAccountSync(deps)` — configKey =
+/// `"${debounceMs}:${pollIntervalMs}"`. Disabled ⇒ stop + commit nulls
+/// (cleanup registration preserved). Key change ⇒ stop/null out. Creation
+/// wires `onChange` to the manager reload and commits state after create
+/// AND again after registering cleanup. Path switch retries 3× (25·2^n ms)
+/// on EBUSY/EPERM only, warns + keeps the previous watcher on exhaustion;
+/// other errors propagate.
+pub async fn ensure_runtime_live_account_sync<TSync>(
+    deps: EnsureRuntimeLiveAccountSyncDeps<'_, TSync>,
+) -> std::io::Result<RuntimeLiveSyncState<TSync>>
+where
+    TSync: LiveAccountSyncLike + Send + Sync + 'static,
+{
+    let EnsureRuntimeLiveAccountSyncDeps {
+        enabled,
+        debounce_ms,
+        poll_interval_ms,
+        target_path,
+        auth_fallback,
+        current_sync,
+        current_path,
+        current_config_key,
+        current_cleanup_registered,
+        get_current_sync,
+        create_sync,
+        reload_account_manager_from_disk,
+        commit_state,
+        register_cleanup,
+        log_warn,
+        plugin_name,
+    } = deps;
+
+    let next_config_key = format!(
+        "{}:{}",
+        js_number_string(debounce_ms),
+        js_number_string(poll_interval_ms)
+    );
+
+    if !enabled {
+        if let Some(sync) = current_sync.as_ref() {
+            sync.stop();
+        }
+        let state = RuntimeLiveSyncState {
+            sync: None,
+            path: None,
+            config_key: None,
+            cleanup_registered: current_cleanup_registered,
+        };
+        commit_state(state.clone());
+        return Ok(state);
+    }
+
+    let mut sync = current_sync;
+    let mut cleanup_registered = current_cleanup_registered;
+    let mut next_path = current_path;
+    let mut config_key = current_config_key;
+
+    if sync.is_some() && config_key.is_some() && config_key.as_deref() != Some(&next_config_key) {
+        if let Some(current) = sync.as_ref() {
+            current.stop();
+        }
+        sync = None;
+        next_path = None;
+        config_key = None;
+    }
+
+    if sync.is_none() {
+        let reload = reload_account_manager_from_disk.clone();
+        let auth = auth_fallback.clone();
+        let on_change: LiveSyncOnChange = Arc::new(move || {
+            let reload = reload.clone();
+            let auth = auth.clone();
+            Box::pin(async move {
+                reload(auth).await;
+            })
+        });
+        let created = create_sync(
+            on_change,
+            LiveSyncCreateOptions {
+                debounce_ms,
+                poll_interval_ms,
+            },
+        );
+        sync = Some(created);
+        config_key = Some(next_config_key.clone());
+        commit_state(RuntimeLiveSyncState {
+            sync: sync.clone(),
+            path: next_path.clone(),
+            config_key: config_key.clone(),
+            cleanup_registered,
+        });
+        if !cleanup_registered {
+            let get_current = get_current_sync.clone();
+            register_cleanup(Box::new(move || {
+                if let Some(current) = get_current() {
+                    current.stop();
+                }
+            }));
+            cleanup_registered = true;
+            commit_state(RuntimeLiveSyncState {
+                sync: sync.clone(),
+                path: next_path.clone(),
+                config_key: config_key.clone(),
+                cleanup_registered,
+            });
+        }
+    }
+
+    if next_path.as_deref() != Some(target_path.as_str()) {
+        let current = sync.as_ref().expect("sync exists here");
+        let mut switched = false;
+        for attempt in 0..3u32 {
+            match current.sync_to_path(&target_path).await {
+                Ok(()) => {
+                    next_path = Some(target_path.clone());
+                    commit_state(RuntimeLiveSyncState {
+                        sync: sync.clone(),
+                        path: next_path.clone(),
+                        config_key: config_key.clone(),
+                        cleanup_registered,
+                    });
+                    switched = true;
+                    break;
+                }
+                Err(error) => {
+                    let code = cma_core::fs_retry::code_of(&error);
+                    if code != Some("EBUSY") && code != Some("EPERM") {
+                        return Err(error);
+                    }
+                    cma_core::utils::sleep(25 * 2u64.pow(attempt)).await;
+                }
+            }
+        }
+        if !switched {
+            log_warn(&format!(
+                "[{plugin_name}] Live account sync path switch failed due to transient filesystem locks; keeping previous watcher."
+            ));
+        }
+    }
+
+    Ok(RuntimeLiveSyncState {
+        sync,
+        path: next_path,
+        config_key,
+        cleanup_registered,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Mutex as StdMutex;
+
+    struct FakeSync {
+        stopped: AtomicUsize,
+        sync_calls: StdMutex<Vec<String>>,
+    }
+
+    impl FakeSync {
+        fn new() -> Arc<Self> {
+            Arc::new(Self {
+                stopped: AtomicUsize::new(0),
+                sync_calls: StdMutex::new(Vec::new()),
+            })
+        }
+    }
+
+    impl LiveAccountSyncLike for FakeSync {
+        fn stop(&self) {
+            self.stopped.fetch_add(1, Ordering::SeqCst);
+        }
+        async fn sync_to_path(&self, path: &str) -> std::io::Result<()> {
+            self.sync_calls.lock().unwrap().push(path.to_string());
+            Ok(())
+        }
+    }
+
+    fn test_runtime() -> tokio::runtime::Runtime {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    fn creates_wires_on_change_to_the_reload_and_commits_state_twice() {
+        test_runtime().block_on(async {
+            let created = FakeSync::new();
+            let created_for_closure = created.clone();
+            let captured_on_change: Arc<StdMutex<Option<LiveSyncOnChange>>> =
+                Arc::new(StdMutex::new(None));
+            let captured_for_closure = captured_on_change.clone();
+            let mut create = move |on_change: LiveSyncOnChange, options: LiveSyncCreateOptions| {
+                assert_eq!(options.debounce_ms, 250.0);
+                assert_eq!(options.poll_interval_ms, 2_000.0);
+                *captured_for_closure.lock().unwrap() = Some(on_change);
+                created_for_closure.clone()
+            };
+            let reload_calls = Arc::new(AtomicUsize::new(0));
+            let reload_calls_inner = reload_calls.clone();
+            let reload: ReloadAccountManagerFn = Arc::new(move |_auth| {
+                let reload_calls = reload_calls_inner.clone();
+                Box::pin(async move {
+                    reload_calls.fetch_add(1, Ordering::SeqCst);
+                })
+            });
+            // (has_sync, config_key, cleanup_registered) per committed state.
+            type CommitLog = Vec<(bool, Option<String>, bool)>;
+            let commits: Arc<StdMutex<CommitLog>> = Arc::new(StdMutex::new(Vec::new()));
+            let commits_inner = commits.clone();
+            let mut commit = move |state: RuntimeLiveSyncState<FakeSync>| {
+                commits_inner.lock().unwrap().push((
+                    state.sync.is_some(),
+                    state.config_key.clone(),
+                    state.cleanup_registered,
+                ));
+            };
+            let mut cleanups = 0usize;
+            let mut register = |_c: Box<dyn FnOnce() + Send>| cleanups += 1;
+            let mut warn = |_m: &str| {};
+
+            let state = ensure_runtime_live_account_sync(EnsureRuntimeLiveAccountSyncDeps {
+                enabled: true,
+                debounce_ms: 250.0,
+                poll_interval_ms: 2_000.0,
+                target_path: "/tmp/accounts.json".to_string(),
+                auth_fallback: None,
+                current_sync: None,
+                current_path: None,
+                current_config_key: None,
+                current_cleanup_registered: false,
+                get_current_sync: Arc::new(|| None),
+                create_sync: &mut create,
+                reload_account_manager_from_disk: reload,
+                commit_state: &mut commit,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert!(Arc::ptr_eq(state.sync.as_ref().unwrap(), &created));
+            assert_eq!(state.config_key.as_deref(), Some("250:2000"));
+            assert_eq!(state.path.as_deref(), Some("/tmp/accounts.json"));
+            assert!(state.cleanup_registered);
+            assert_eq!(cleanups, 1);
+            // commit after create, after cleanup registration, after path
+            // switch.
+            let committed = commits.lock().unwrap().clone();
+            assert_eq!(committed.len(), 3);
+            assert_eq!(committed[0], (true, Some("250:2000".to_string()), false));
+            assert_eq!(committed[1], (true, Some("250:2000".to_string()), true));
+            assert_eq!(committed[2], (true, Some("250:2000".to_string()), true));
+
+            // The captured onChange drives the manager reload.
+            let on_change = captured_on_change.lock().unwrap().clone().unwrap();
+            on_change().await;
+            assert_eq!(reload_calls.load(Ordering::SeqCst), 1);
+        });
+    }
+
+    #[test]
+    fn disabled_stops_and_commits_nulls_preserving_cleanup_flag() {
+        test_runtime().block_on(async {
+            let current = FakeSync::new();
+            let mut create = |_on_change: LiveSyncOnChange, _o: LiveSyncCreateOptions| {
+                panic!("no create expected")
+            };
+            let reload: ReloadAccountManagerFn = Arc::new(|_auth| Box::pin(async {}));
+            let mut commits = 0usize;
+            let mut commit = |state: RuntimeLiveSyncState<FakeSync>| {
+                commits += 1;
+                assert!(state.sync.is_none());
+                assert!(state.cleanup_registered);
+            };
+            let mut register = |_c: Box<dyn FnOnce() + Send>| {};
+            let mut warn = |_m: &str| {};
+
+            let state = ensure_runtime_live_account_sync(EnsureRuntimeLiveAccountSyncDeps {
+                enabled: false,
+                debounce_ms: 250.0,
+                poll_interval_ms: 2_000.0,
+                target_path: "/tmp/accounts.json".to_string(),
+                auth_fallback: None,
+                current_sync: Some(current.clone()),
+                current_path: Some("/tmp/accounts.json".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                current_cleanup_registered: true,
+                get_current_sync: Arc::new(|| None),
+                create_sync: &mut create,
+                reload_account_manager_from_disk: reload,
+                commit_state: &mut commit,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert!(state.sync.is_none());
+            assert!(state.cleanup_registered);
+            assert_eq!(current.stopped.load(Ordering::SeqCst), 1);
+            assert_eq!(commits, 1);
+        });
+    }
+
+    #[test]
+    fn config_key_change_stops_and_recreates_without_duplicate_cleanup() {
+        test_runtime().block_on(async {
+            let previous = FakeSync::new();
+            let created = FakeSync::new();
+            let created_for_closure = created.clone();
+            let mut create = move |_on_change: LiveSyncOnChange, _o: LiveSyncCreateOptions| {
+                created_for_closure.clone()
+            };
+            let reload: ReloadAccountManagerFn = Arc::new(|_auth| Box::pin(async {}));
+            let mut commit = |_state: RuntimeLiveSyncState<FakeSync>| {};
+            let mut cleanups = 0usize;
+            let mut register = |_c: Box<dyn FnOnce() + Send>| cleanups += 1;
+            let mut warn = |_m: &str| {};
+
+            let state = ensure_runtime_live_account_sync(EnsureRuntimeLiveAccountSyncDeps {
+                enabled: true,
+                debounce_ms: 500.0,
+                poll_interval_ms: 1_000.0,
+                target_path: "/tmp/accounts.json".to_string(),
+                auth_fallback: None,
+                current_sync: Some(previous.clone()),
+                current_path: Some("/tmp/accounts.json".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                current_cleanup_registered: true,
+                get_current_sync: Arc::new(|| None),
+                create_sync: &mut create,
+                reload_account_manager_from_disk: reload,
+                commit_state: &mut commit,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert_eq!(previous.stopped.load(Ordering::SeqCst), 1);
+            assert!(Arc::ptr_eq(state.sync.as_ref().unwrap(), &created));
+            assert_eq!(state.config_key.as_deref(), Some("500:1000"));
+            // Cleanup was already registered: not registered again.
+            assert_eq!(cleanups, 0);
+        });
+    }
+}
diff --git a/crates/runtime/src/loader_setup.rs b/crates/runtime/src/loader_setup.rs
new file mode 100644
index 000000000..0e5a0ed91
--- /dev/null
+++ b/crates/runtime/src/loader_setup.rs
@@ -0,0 +1,56 @@
+//! Port of `lib/runtime/loader-setup.ts` — the fixed-order loader runtime
+//! setup (spec 10 §22, ARCHITECTURE §6.12).
+//!
+//! Order is CONTRACT: UI runtime → account-storage scope → session
+//! affinity → refresh guardian → preemptive-quota settings.
+
+use cma_core::schemas::plugin_config::PluginConfig;
+
+/// TS `applyLoaderRuntimeSetup(params)` — runs the five setup steps in the
+/// contractual order, passing each the same resolved plugin config.
+pub fn apply_loader_runtime_setup(
+    plugin_config: &PluginConfig,
+    apply_ui_runtime_from_config: impl FnOnce(&PluginConfig),
+    apply_account_storage_scope: impl FnOnce(&PluginConfig),
+    ensure_session_affinity: impl FnOnce(&PluginConfig),
+    ensure_refresh_guardian: impl FnOnce(&PluginConfig),
+    apply_preemptive_quota_settings: impl FnOnce(&PluginConfig),
+) {
+    apply_ui_runtime_from_config(plugin_config);
+    apply_account_storage_scope(plugin_config);
+    ensure_session_affinity(plugin_config);
+    ensure_refresh_guardian(plugin_config);
+    apply_preemptive_quota_settings(plugin_config);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::RefCell;
+
+    #[test]
+    fn runs_the_five_steps_in_the_contractual_order() {
+        let order: RefCell<Vec<&'static str>> = RefCell::new(Vec::new());
+        let config = PluginConfig::default();
+
+        apply_loader_runtime_setup(
+            &config,
+            |_c| order.borrow_mut().push("ui-runtime"),
+            |_c| order.borrow_mut().push("storage-scope"),
+            |_c| order.borrow_mut().push("session-affinity"),
+            |_c| order.borrow_mut().push("refresh-guardian"),
+            |_c| order.borrow_mut().push("preemptive-quota"),
+        );
+
+        assert_eq!(
+            order.into_inner(),
+            vec![
+                "ui-runtime",
+                "storage-scope",
+                "session-affinity",
+                "refresh-guardian",
+                "preemptive-quota",
+            ]
+        );
+    }
+}
diff --git a/crates/runtime/src/login_menu_accounts.rs b/crates/runtime/src/login_menu_accounts.rs
new file mode 100644
index 000000000..b513859bb
--- /dev/null
+++ b/crates/runtime/src/login_menu_accounts.rs
@@ -0,0 +1,231 @@
+//! Port of `lib/runtime/login-menu-accounts.ts` — login-dashboard account
+//! row assembly (spec 10 §22).
+//!
+//! Status priority (exact): `disabled` (`enabled === false`) > `cooldown`
+//! (`coolingDownUntil > now`) > `rate-limited` (`formatRateLimitEntry`
+//! non-null) > `active` (display-current) > `ok`.
+
+use cma_core::schemas::account_storage::RateLimitStateV3;
+
+use crate::current_account::{
+    AccountCurrentMarker, RuntimeCurrentAccountSelection, is_display_current_account,
+    resolve_account_current_markers,
+};
+
+/// Input row (the TS inline account shape).
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct LoginMenuAccountInput {
+    pub account_id: Option<String>,
+    pub account_label: Option<String>,
+    pub email: Option<String>,
+    pub added_at: Option<i64>,
+    pub last_used: Option<i64>,
+    /// TS `enabled?: boolean` — `Some(false)` means disabled.
+    pub enabled: Option<bool>,
+    pub cooling_down_until: Option<i64>,
+    pub rate_limit_reset_times: Option<RateLimitStateV3>,
+}
+
+/// TS `LoginMenuAccount["status"]`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LoginMenuAccountStatus {
+    Active,
+    Ok,
+    RateLimited,
+    Cooldown,
+    Disabled,
+}
+
+impl LoginMenuAccountStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Ok => "ok",
+            Self::RateLimited => "rate-limited",
+            Self::Cooldown => "cooldown",
+            Self::Disabled => "disabled",
+        }
+    }
+}
+
+/// TS `LoginMenuAccount`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct LoginMenuAccount {
+    pub account_id: Option<String>,
+    pub account_label: Option<String>,
+    pub email: Option<String>,
+    pub index: usize,
+    pub added_at: Option<i64>,
+    pub last_used: Option<i64>,
+    pub status: LoginMenuAccountStatus,
+    pub is_current_account: bool,
+    pub is_default_account: bool,
+    pub is_runtime_current_account: bool,
+    pub current_markers: Vec<AccountCurrentMarker>,
+    pub enabled: bool,
+}
+
+/// Dependencies of [`build_login_menu_accounts`] (TS `deps`).
+pub struct BuildLoginMenuAccountsDeps<'a> {
+    pub now: i64,
+    pub active_index: usize,
+    pub runtime_current: Option<&'a RuntimeCurrentAccountSelection>,
+    /// TS `formatRateLimitEntry(account, now)` — the caller binds the family
+    /// and wait-time formatter (see `crate::account_status`).
+    pub format_rate_limit_entry: &'a dyn Fn(&LoginMenuAccountInput, i64) -> Option<String>,
+}
+
+/// TS `buildLoginMenuAccounts(accounts, deps)`.
+pub fn build_login_menu_accounts(
+    accounts: &[LoginMenuAccountInput],
+    deps: &BuildLoginMenuAccountsDeps<'_>,
+) -> Vec<LoginMenuAccount> {
+    accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let is_current =
+                is_display_current_account(index, deps.active_index, deps.runtime_current);
+
+            let status = if account.enabled == Some(false) {
+                LoginMenuAccountStatus::Disabled
+            } else if account
+                .cooling_down_until
+                .is_some_and(|until| until > deps.now)
+            {
+                LoginMenuAccountStatus::Cooldown
+            } else if (deps.format_rate_limit_entry)(account, deps.now).is_some() {
+                LoginMenuAccountStatus::RateLimited
+            } else if is_current {
+                LoginMenuAccountStatus::Active
+            } else {
+                LoginMenuAccountStatus::Ok
+            };
+
+            LoginMenuAccount {
+                account_id: account.account_id.clone(),
+                account_label: account.account_label.clone(),
+                email: account.email.clone(),
+                index,
+                added_at: account.added_at,
+                last_used: account.last_used,
+                status,
+                is_current_account: is_current,
+                is_default_account: index == deps.active_index,
+                is_runtime_current_account: deps
+                    .runtime_current
+                    .is_some_and(|current| current.index == index),
+                current_markers: resolve_account_current_markers(
+                    index,
+                    deps.active_index,
+                    deps.runtime_current,
+                ),
+                enabled: account.enabled != Some(false),
+            }
+        })
+        .collect()
+}
+
+// =============================================================================
+// Tests — ported from test/login-menu-accounts.test.ts (status priority)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::ModelFamily;
+
+    fn default_format(account: &LoginMenuAccountInput, now: i64) -> Option<String> {
+        crate::account_status::format_rate_limit_entry(
+            account.rate_limit_reset_times.as_ref(),
+            now,
+            &|ms| format!("{}ms", ms),
+            ModelFamily::Codex,
+        )
+    }
+
+    #[test]
+    fn status_priority_disabled_cooldown_rate_limited_active_ok() {
+        let now = 1_000i64;
+        let accounts = vec![
+            // 0: disabled wins over cooldown/rate-limit.
+            LoginMenuAccountInput {
+                enabled: Some(false),
+                cooling_down_until: Some(now + 100),
+                rate_limit_reset_times: Some(
+                    [("codex".to_string(), now + 100)].into_iter().collect(),
+                ),
+                ..LoginMenuAccountInput::default()
+            },
+            // 1: cooldown beats rate-limit.
+            LoginMenuAccountInput {
+                cooling_down_until: Some(now + 100),
+                rate_limit_reset_times: Some(
+                    [("codex".to_string(), now + 100)].into_iter().collect(),
+                ),
+                ..LoginMenuAccountInput::default()
+            },
+            // 2: rate-limited (also the stored current index → beats active).
+            LoginMenuAccountInput {
+                rate_limit_reset_times: Some(
+                    [("codex".to_string(), now + 100)].into_iter().collect(),
+                ),
+                ..LoginMenuAccountInput::default()
+            },
+            // 3: plain ok.
+            LoginMenuAccountInput::default(),
+        ];
+
+        let rows = build_login_menu_accounts(
+            &accounts,
+            &BuildLoginMenuAccountsDeps {
+                now,
+                active_index: 2,
+                runtime_current: None,
+                format_rate_limit_entry: &default_format,
+            },
+        );
+
+        assert_eq!(rows[0].status, LoginMenuAccountStatus::Disabled);
+        assert!(!rows[0].enabled);
+        assert_eq!(rows[1].status, LoginMenuAccountStatus::Cooldown);
+        assert_eq!(rows[2].status, LoginMenuAccountStatus::RateLimited);
+        assert_eq!(rows[3].status, LoginMenuAccountStatus::Ok);
+
+        // Default-account flag follows the stored index.
+        assert!(rows[2].is_default_account);
+        assert!(!rows[3].is_default_account);
+        // With no runtime signal the stored index is the display-current.
+        assert!(rows[2].is_current_account);
+        assert!(!rows[3].is_runtime_current_account);
+    }
+
+    #[test]
+    fn active_status_for_current_account_without_limits() {
+        let rows = build_login_menu_accounts(
+            &[LoginMenuAccountInput::default(), LoginMenuAccountInput::default()],
+            &BuildLoginMenuAccountsDeps {
+                now: 0,
+                active_index: 0,
+                runtime_current: None,
+                format_rate_limit_entry: &default_format,
+            },
+        );
+        assert_eq!(rows[0].status, LoginMenuAccountStatus::Active);
+        assert_eq!(rows[1].status, LoginMenuAccountStatus::Ok);
+        // Expired cooldown does not force cooldown status.
+        let rows = build_login_menu_accounts(
+            &[LoginMenuAccountInput {
+                cooling_down_until: Some(5),
+                ..LoginMenuAccountInput::default()
+            }],
+            &BuildLoginMenuAccountsDeps {
+                now: 10,
+                active_index: 0,
+                runtime_current: None,
+                format_rate_limit_entry: &default_format,
+            },
+        );
+        assert_eq!(rows[0].status, LoginMenuAccountStatus::Active);
+    }
+}
diff --git a/crates/runtime/src/manager_cache.rs b/crates/runtime/src/manager_cache.rs
new file mode 100644
index 000000000..dfa85deaa
--- /dev/null
+++ b/crates/runtime/src/manager_cache.rs
@@ -0,0 +1,227 @@
+//! Port of `lib/runtime/account-manager-cache.ts` (+
+//! `account-manager-cache-entry.ts`) — the cached AccountManager singleton
+//! with reload dedupe (spec 10 §21, ARCHITECTURE §3 row "Loader mutex /
+//! account-manager cache / reload dedupe").
+//!
+//! The TS module was a set of dependency-injected helpers over three
+//! promise slots living in `index.ts` (`cachedAccountManager`,
+//! `accountManagerPromise`, `reloadInFlight`). In Rust those slots collapse
+//! into [`AccountManagerCache`]: `cached` (the resolved manager — the TS
+//! promise slot only existed for JS `await` semantics) and the in-flight
+//! reload dedupe. The dedupe contract is preserved: concurrent reload
+//! callers share ONE disk load; `invalidate` clears the cached manager but
+//! deliberately does NOT cancel an in-flight reload (TS parity — the
+//! reload's `finally` clears the in-flight slot itself).
+
+use cma_accounts::manager::AccountManager;
+use cma_accounts::manager_persistence::SharedAccountManager;
+use cma_core::types::OAuthAuthDetails;
+use std::sync::{LazyLock, Mutex as StdMutex};
+use tokio::sync::watch;
+
+type InFlight = watch::Receiver<Option<SharedAccountManager>>;
+
+#[derive(Default)]
+struct CacheInner {
+    cached: Option<SharedAccountManager>,
+    in_flight: Option<InFlight>,
+}
+
+/// The cached-manager singleton state (one per process in production; tests
+/// may construct their own).
+#[derive(Default)]
+pub struct AccountManagerCache {
+    inner: StdMutex<CacheInner>,
+}
+
+enum ReloadAction {
+    Wait(InFlight),
+    Load(watch::Sender<Option<SharedAccountManager>>),
+}
+
+impl AccountManagerCache {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// The currently cached manager, if any (TS `cachedAccountManager`).
+    pub fn cached(&self) -> Option<SharedAccountManager> {
+        self.inner.lock().expect("manager cache poisoned").cached.clone()
+    }
+
+    /// TS `invalidateRuntimeAccountManagerCache` /
+    /// `invalidateAccountManagerCacheState` — null out the cached manager
+    /// (and its resolved promise). An in-flight reload is NOT cancelled.
+    pub fn invalidate(&self) {
+        self.inner.lock().expect("manager cache poisoned").cached = None;
+    }
+
+    /// TS `reloadRuntimeAccountManager` — dedupes on the shared in-flight
+    /// reload: concurrent callers all receive the manager produced by the
+    /// single disk load. The check-and-claim runs under one lock
+    /// acquisition (the TS version relied on `setReloadInFlight` running
+    /// before any `await`).
+    pub async fn reload(&self, auth_fallback: Option<OAuthAuthDetails>) -> SharedAccountManager {
+        let action = {
+            let mut inner = self.inner.lock().expect("manager cache poisoned");
+            match &inner.in_flight {
+                Some(receiver) => ReloadAction::Wait(receiver.clone()),
+                None => {
+                    let (sender, receiver) = watch::channel(None);
+                    inner.in_flight = Some(receiver);
+                    ReloadAction::Load(sender)
+                }
+            }
+        };
+
+        match action {
+            ReloadAction::Wait(mut receiver) => {
+                loop {
+                    if let Some(manager) = receiver.borrow().clone() {
+                        return manager;
+                    }
+                    if receiver.changed().await.is_err() {
+                        // The loading task can only vanish after publishing
+                        // (the sender lives until this fn returns), but be
+                        // total: fall back to a fresh reload.
+                        break;
+                    }
+                }
+                Box::pin(self.reload(auth_fallback)).await
+            }
+            ReloadAction::Load(sender) => {
+                let manager = SharedAccountManager::new(
+                    AccountManager::load_from_disk(auth_fallback.as_ref()).await,
+                );
+                {
+                    let mut inner = self.inner.lock().expect("manager cache poisoned");
+                    inner.cached = Some(manager.clone());
+                    // TS `finally(() => setReloadInFlight(null))`.
+                    inner.in_flight = None;
+                }
+                let _ = sender.send(Some(manager.clone()));
+                manager
+            }
+        }
+    }
+
+    /// Loader semantics (TS `accountManagerPromise ?? load`): return the
+    /// cached manager or load one (sharing any in-flight reload).
+    pub async fn get_or_load(
+        &self,
+        auth_fallback: Option<OAuthAuthDetails>,
+    ) -> SharedAccountManager {
+        if let Some(cached) = self.cached() {
+            return cached;
+        }
+        self.reload(auth_fallback).await
+    }
+
+    /// Test-only: clear everything (cached AND in-flight bookkeeping).
+    pub fn reset_for_testing(&self) {
+        let mut inner = self.inner.lock().expect("manager cache poisoned");
+        inner.cached = None;
+        inner.in_flight = None;
+    }
+}
+
+static GLOBAL_CACHE: LazyLock<AccountManagerCache> = LazyLock::new(AccountManagerCache::new);
+
+/// The process-wide cache instance (the TS `index.ts` module slots).
+pub fn account_manager_cache() -> &'static AccountManagerCache {
+    &GLOBAL_CACHE
+}
+
+/// TS `invalidateAccountManagerCache()` convenience over the global cache.
+pub fn invalidate_account_manager_cache() {
+    GLOBAL_CACHE.invalidate();
+}
+
+/// TS `reloadAccountManagerFromDisk(authFallback?)` convenience over the
+/// global cache.
+pub async fn reload_account_manager_from_disk(
+    auth_fallback: Option<OAuthAuthDetails>,
+) -> SharedAccountManager {
+    GLOBAL_CACHE.reload(auth_fallback).await
+}
+
+/// Loader-side accessor over the global cache.
+pub async fn get_account_manager(auth_fallback: Option<OAuthAuthDetails>) -> SharedAccountManager {
+    GLOBAL_CACHE.get_or_load(auth_fallback).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::sync::Arc;
+
+    fn test_runtime() -> tokio::runtime::Runtime {
+        tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(2)
+            .enable_all()
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    #[serial(env)]
+    fn reload_caches_and_invalidate_clears() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let cache = AccountManagerCache::new();
+            assert!(cache.cached().is_none());
+
+            let manager = cache.reload(None).await;
+            let cached = cache.cached().expect("manager cached after reload");
+            assert!(Arc::ptr_eq(manager.manager(), cached.manager()));
+
+            cache.invalidate();
+            assert!(cache.cached().is_none());
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn get_or_load_reuses_the_cached_manager() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let cache = AccountManagerCache::new();
+            let first = cache.get_or_load(None).await;
+            let second = cache.get_or_load(None).await;
+            assert!(Arc::ptr_eq(first.manager(), second.manager()));
+
+            // After invalidation a fresh manager is loaded.
+            cache.invalidate();
+            let third = cache.get_or_load(None).await;
+            assert!(!Arc::ptr_eq(first.manager(), third.manager()));
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn concurrent_reloads_share_one_in_flight_load() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let cache = Arc::new(AccountManagerCache::new());
+            let a = {
+                let cache = cache.clone();
+                tokio::spawn(async move { cache.reload(None).await })
+            };
+            let b = {
+                let cache = cache.clone();
+                tokio::spawn(async move { cache.reload(None).await })
+            };
+            let (a, b) = (a.await.unwrap(), b.await.unwrap());
+            // Both callers may or may not have raced the same in-flight load
+            // (timing-dependent), but the cache must end consistent: the
+            // cached manager is one of the two returned handles.
+            let cached = cache.cached().expect("cached after concurrent reloads");
+            assert!(
+                Arc::ptr_eq(cached.manager(), a.manager())
+                    || Arc::ptr_eq(cached.manager(), b.manager())
+            );
+        });
+    }
+}
diff --git a/crates/runtime/src/oauth_flows/browser.rs b/crates/runtime/src/oauth_flows/browser.rs
new file mode 100644
index 000000000..c6fe53b43
--- /dev/null
+++ b/crates/runtime/src/oauth_flows/browser.rs
@@ -0,0 +1,391 @@
+//! Port of `lib/runtime/browser-oauth-flow.ts` — browser-based OAuth login
+//! orchestration (spec 10 §20).
+//!
+//! Flow: create authorization flow → log redacted URL → start the local
+//! callback server (start failures are debug-logged and treated as "not
+//! ready") → open the browser → wait for the code → exchange it. The
+//! callback server NEVER rejects by contract (cma-auth); a not-ready server
+//! warns and fails the flow with a bare `{type:"failed"}`.
+
+#![allow(clippy::result_large_err)] // CodexError is the crate-wide error vocabulary.
+
+use cma_core::errors::CodexError;
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult};
+use cma_core::types::AuthorizationFlow;
+
+/// Minimal callback-server surface the flow needs (implemented for
+/// `cma_auth::callback_server::LocalOAuthServer` below).
+#[allow(async_fn_in_trait)]
+pub trait OAuthCallbackServer {
+    fn ready(&self) -> bool;
+    fn close(&self);
+    /// Resolves with the captured code, or `None` on timeout/cancel.
+    async fn wait_for_code(&self, expected_state: &str) -> Option<String>;
+}
+
+impl OAuthCallbackServer for cma_auth::callback_server::LocalOAuthServer {
+    fn ready(&self) -> bool {
+        self.ready()
+    }
+    fn close(&self) {
+        self.close()
+    }
+    async fn wait_for_code(&self, expected_state: &str) -> Option<String> {
+        self.wait_for_code(expected_state)
+            .await
+            .map(|captured| captured.code)
+    }
+}
+
+/// I/O seams of [`run_browser_oauth_flow`] (the TS `params` object).
+#[allow(async_fn_in_trait)]
+pub trait BrowserOAuthFlowDeps {
+    type Server: OAuthCallbackServer;
+
+    /// TS `createAuthorizationFlow({forceNewLogin})`.
+    fn create_authorization_flow(
+        &mut self,
+        force_new_login: bool,
+    ) -> Result<AuthorizationFlow, CodexError>;
+    /// TS `startLocalOAuthServer({state})` — `Err` models the TS throw path
+    /// (debug-logged, treated as no server).
+    async fn start_local_oauth_server(&mut self, state: &str) -> Result<Self::Server, CodexError>;
+    fn open_browser_url(&mut self, url: &str);
+    async fn exchange_authorization_code(
+        &mut self,
+        code: &str,
+        verifier: &str,
+        redirect_uri: &str,
+    ) -> TokenResult;
+    fn redirect_uri(&self) -> String {
+        cma_auth::oauth::REDIRECT_URI.to_string()
+    }
+    fn redact_oauth_url_for_log(&self, url: &str) -> String {
+        cma_auth::oauth::redact_oauth_url_for_log(url)
+    }
+    fn plugin_name(&self) -> &str;
+    fn auth_manual_label(&self) -> &str;
+    fn log_info(&mut self, message: &str);
+    fn log_debug(&mut self, message: &str);
+    fn log_warn(&mut self, message: &str);
+}
+
+/// TS `runBrowserOAuthFlow(params)`.
+pub async fn run_browser_oauth_flow<D: BrowserOAuthFlowDeps>(
+    force_new_login: bool,
+    deps: &mut D,
+) -> Result<TokenResult, CodexError> {
+    let flow = deps.create_authorization_flow(force_new_login)?;
+    let redacted = deps.redact_oauth_url_for_log(&flow.url);
+    deps.log_info(&format!("OAuth URL: {redacted}"));
+
+    let server = match deps.start_local_oauth_server(&flow.state).await {
+        Ok(server) => Some(server),
+        Err(error) => {
+            deps.log_debug(&format!(
+                "[{}] Failed to start OAuth server: {}",
+                deps.plugin_name(),
+                error.message()
+            ));
+            None
+        }
+    };
+
+    let ready = server.as_ref().is_some_and(OAuthCallbackServer::ready);
+    if !ready {
+        if let Some(server) = server.as_ref() {
+            server.close();
+        }
+        deps.log_warn(&format!(
+            "\n[{}] OAuth callback server failed to start. Please retry with \"{}\".\n",
+            deps.plugin_name(),
+            deps.auth_manual_label()
+        ));
+        return Ok(TokenResult::Failed(TokenFailure::default()));
+    }
+    let server = server.expect("ready implies present");
+
+    deps.open_browser_url(&flow.url);
+    let result = server.wait_for_code(&flow.state).await;
+    server.close();
+
+    let Some(code) = result else {
+        return Ok(TokenResult::Failed(TokenFailure {
+            reason: Some(TokenFailureReason::Unknown),
+            status_code: None,
+            message: Some("OAuth callback timeout or cancelled".to_string()),
+        }));
+    };
+
+    let redirect_uri = deps.redirect_uri();
+    Ok(deps
+        .exchange_authorization_code(&code, &flow.pkce.verifier, &redirect_uri)
+        .await)
+}
+
+/// Production wiring over `cma_auth` (browser open, callback server on port
+/// 1455, code exchange). Logging closures come from the caller (the facade
+/// prefixes them — spec 10 §20).
+pub struct RuntimeBrowserOAuthFlowDeps<'a> {
+    pub plugin_name: &'a str,
+    pub auth_manual_label: &'a str,
+    pub log_info: &'a mut dyn FnMut(&str),
+    pub log_debug: &'a mut dyn FnMut(&str),
+    pub log_warn: &'a mut dyn FnMut(&str),
+}
+
+impl BrowserOAuthFlowDeps for RuntimeBrowserOAuthFlowDeps<'_> {
+    type Server = cma_auth::callback_server::LocalOAuthServer;
+
+    fn create_authorization_flow(
+        &mut self,
+        force_new_login: bool,
+    ) -> Result<AuthorizationFlow, CodexError> {
+        Ok(cma_auth::oauth::create_authorization_flow(
+            cma_auth::oauth::AuthorizationFlowOptions { force_new_login },
+        ))
+    }
+
+    async fn start_local_oauth_server(&mut self, state: &str) -> Result<Self::Server, CodexError> {
+        // Contract: never rejects — a bind failure yields ready:false.
+        Ok(cma_auth::callback_server::start_local_oauth_server(state).await)
+    }
+
+    fn open_browser_url(&mut self, url: &str) {
+        cma_auth::browser::open_browser_url(url);
+    }
+
+    async fn exchange_authorization_code(
+        &mut self,
+        code: &str,
+        verifier: &str,
+        redirect_uri: &str,
+    ) -> TokenResult {
+        cma_auth::oauth::exchange_authorization_code(code, verifier, Some(redirect_uri)).await
+    }
+
+    fn plugin_name(&self) -> &str {
+        self.plugin_name
+    }
+    fn auth_manual_label(&self) -> &str {
+        self.auth_manual_label
+    }
+    fn log_info(&mut self, message: &str) {
+        (self.log_info)(message);
+    }
+    fn log_debug(&mut self, message: &str) {
+        (self.log_debug)(message);
+    }
+    fn log_warn(&mut self, message: &str) {
+        (self.log_warn)(message);
+    }
+}
+
+// =============================================================================
+// Tests — ported from test/browser-oauth-flow.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenSuccess;
+    use cma_core::types::PKCEPair;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+
+    struct FakeServer {
+        ready: bool,
+        code: Option<String>,
+        closed: Arc<AtomicBool>,
+        wait_calls: Arc<AtomicU32>,
+    }
+
+    impl OAuthCallbackServer for FakeServer {
+        fn ready(&self) -> bool {
+            self.ready
+        }
+        fn close(&self) {
+            self.closed.store(true, Ordering::SeqCst);
+        }
+        async fn wait_for_code(&self, _expected_state: &str) -> Option<String> {
+            self.wait_calls.fetch_add(1, Ordering::SeqCst);
+            self.code.clone()
+        }
+    }
+
+    struct FakeDeps {
+        start_fails: bool,
+        server_ready: bool,
+        server_code: Option<String>,
+        closed: Arc<AtomicBool>,
+        wait_calls: Arc<AtomicU32>,
+        opened_urls: Vec<String>,
+        exchanged: Vec<(String, String, String)>,
+        infos: Vec<String>,
+        debugs: Vec<String>,
+        warns: Vec<String>,
+    }
+
+    impl FakeDeps {
+        fn new() -> Self {
+            Self {
+                start_fails: false,
+                server_ready: true,
+                server_code: Some("auth-code".to_string()),
+                closed: Arc::new(AtomicBool::new(false)),
+                wait_calls: Arc::new(AtomicU32::new(0)),
+                opened_urls: Vec::new(),
+                exchanged: Vec::new(),
+                infos: Vec::new(),
+                debugs: Vec::new(),
+                warns: Vec::new(),
+            }
+        }
+    }
+
+    impl BrowserOAuthFlowDeps for FakeDeps {
+        type Server = FakeServer;
+
+        fn create_authorization_flow(
+            &mut self,
+            force_new_login: bool,
+        ) -> Result<AuthorizationFlow, CodexError> {
+            let _ = force_new_login;
+            Ok(AuthorizationFlow {
+                pkce: PKCEPair {
+                    challenge: "challenge".to_string(),
+                    verifier: "verifier-1".to_string(),
+                },
+                state: "state-1".to_string(),
+                url: "https://auth.openai.com/oauth/authorize?client_id=x".to_string(),
+            })
+        }
+
+        async fn start_local_oauth_server(
+            &mut self,
+            _state: &str,
+        ) -> Result<Self::Server, CodexError> {
+            if self.start_fails {
+                return Err(CodexError::new("bind exploded"));
+            }
+            Ok(FakeServer {
+                ready: self.server_ready,
+                code: self.server_code.clone(),
+                closed: Arc::clone(&self.closed),
+                wait_calls: Arc::clone(&self.wait_calls),
+            })
+        }
+
+        fn open_browser_url(&mut self, url: &str) {
+            self.opened_urls.push(url.to_string());
+        }
+
+        async fn exchange_authorization_code(
+            &mut self,
+            code: &str,
+            verifier: &str,
+            redirect_uri: &str,
+        ) -> TokenResult {
+            self.exchanged
+                .push((code.to_string(), verifier.to_string(), redirect_uri.to_string()));
+            TokenResult::Success(TokenSuccess {
+                access: "at".to_string(),
+                refresh: "rt".to_string(),
+                expires: 9_999,
+                id_token: None,
+                multi_account: None,
+            })
+        }
+
+        fn redirect_uri(&self) -> String {
+            "http://localhost:1455/auth/callback".to_string()
+        }
+        fn redact_oauth_url_for_log(&self, url: &str) -> String {
+            format!("<redacted:{}>", url.len())
+        }
+        fn plugin_name(&self) -> &str {
+            "codex-multi-auth"
+        }
+        fn auth_manual_label(&self) -> &str {
+            "ChatGPT (manual)"
+        }
+        fn log_info(&mut self, message: &str) {
+            self.infos.push(message.to_string());
+        }
+        fn log_debug(&mut self, message: &str) {
+            self.debugs.push(message.to_string());
+        }
+        fn log_warn(&mut self, message: &str) {
+            self.warns.push(message.to_string());
+        }
+    }
+
+    #[tokio::test]
+    async fn happy_path_exchanges_captured_code() {
+        let mut deps = FakeDeps::new();
+        let result = run_browser_oauth_flow(false, &mut deps).await.unwrap();
+        assert!(result.is_success());
+        assert_eq!(deps.opened_urls.len(), 1);
+        assert_eq!(
+            deps.exchanged,
+            vec![(
+                "auth-code".to_string(),
+                "verifier-1".to_string(),
+                "http://localhost:1455/auth/callback".to_string()
+            )]
+        );
+        // Redacted URL logged.
+        assert!(deps.infos[0].starts_with("OAuth URL: <redacted:"));
+        // Server closed after the wait.
+        assert!(deps.closed.load(Ordering::SeqCst));
+    }
+
+    #[tokio::test]
+    async fn server_start_failure_warns_and_fails() {
+        let mut deps = FakeDeps::new();
+        deps.start_fails = true;
+        let result = run_browser_oauth_flow(false, &mut deps).await.unwrap();
+        assert!(!result.is_success());
+        let failure = result.as_failure().unwrap();
+        assert_eq!(failure.reason, None);
+        assert_eq!(failure.message, None);
+        assert_eq!(
+            deps.debugs,
+            vec!["[codex-multi-auth] Failed to start OAuth server: bind exploded"]
+        );
+        assert_eq!(
+            deps.warns,
+            vec![
+                "\n[codex-multi-auth] OAuth callback server failed to start. Please retry with \"ChatGPT (manual)\".\n"
+            ]
+        );
+        assert!(deps.opened_urls.is_empty());
+    }
+
+    #[tokio::test]
+    async fn not_ready_server_is_closed_and_fails() {
+        let mut deps = FakeDeps::new();
+        deps.server_ready = false;
+        let result = run_browser_oauth_flow(false, &mut deps).await.unwrap();
+        assert!(!result.is_success());
+        assert!(deps.closed.load(Ordering::SeqCst));
+        assert_eq!(deps.warns.len(), 1);
+        assert!(deps.opened_urls.is_empty());
+    }
+
+    #[tokio::test]
+    async fn wait_timeout_yields_unknown_failure_message() {
+        let mut deps = FakeDeps::new();
+        deps.server_code = None;
+        let result = run_browser_oauth_flow(true, &mut deps).await.unwrap();
+        let failure = result.as_failure().unwrap();
+        assert_eq!(failure.reason, Some(TokenFailureReason::Unknown));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("OAuth callback timeout or cancelled")
+        );
+        // Server still closed.
+        assert!(deps.closed.load(Ordering::SeqCst));
+        assert!(deps.exchanged.is_empty());
+    }
+}
diff --git a/crates/runtime/src/oauth_flows/facade.rs b/crates/runtime/src/oauth_flows/facade.rs
new file mode 100644
index 000000000..add3f8b54
--- /dev/null
+++ b/crates/runtime/src/oauth_flows/facade.rs
@@ -0,0 +1,204 @@
+//! Port of `lib/runtime/auth-facade.ts` — the runtime OAuth facade
+//! (spec 10 §20).
+//!
+//! - `run_runtime_oauth_flow` wraps the browser flow with the
+//!   prefix-normalizing log adapters (debug: `[{plugin}] ` unless already
+//!   prefixed, incl. after a leading `\n`; warn additionally gets a leading
+//!   newline).
+//! - TS `createPersistAccounts` returned a closure partially applying
+//!   `persistAccountPoolResults`; in Rust that shim is absorbed —
+//!   [`persist_accounts`] delegates directly.
+//! - TS `createAccountManagerReloader` was a DI forwarder over
+//!   `account-manager-cache.ts`; the dedupe lives in
+//!   `crate::manager_cache` (its owner), so no separate facade shim exists
+//!   here (architecture §4 shim-absorption rule).
+
+use cma_core::errors::CodexError;
+use cma_core::schemas::token::TokenResult;
+
+use crate::account_selection::TokenSuccessWithAccount;
+
+/// TS private `prefixLogMessage(message, {leadingNewline})`.
+fn prefix_log_message(plugin_prefix: &str, message: &str, leading_newline: bool) -> String {
+    if message.starts_with(plugin_prefix)
+        || message.starts_with(&format!("\n{plugin_prefix}"))
+    {
+        return message.to_string();
+    }
+    if leading_newline {
+        format!("\n{plugin_prefix} {message}")
+    } else {
+        format!("{plugin_prefix} {message}")
+    }
+}
+
+/// Collaborators of [`run_runtime_oauth_flow`] (TS `deps`).
+#[allow(async_fn_in_trait)]
+pub trait RuntimeOAuthFlowDeps {
+    /// The wrapped browser flow (TS `deps.runBrowserOAuthFlow`) — receives
+    /// the prefix-normalizing log adapters.
+    async fn run_browser_oauth_flow(
+        &mut self,
+        force_new_login: bool,
+        manual_mode_label: &str,
+        log_info: &mut dyn FnMut(&str),
+        log_debug: &mut dyn FnMut(&str),
+        log_warn: &mut dyn FnMut(&str),
+    ) -> Result<TokenResult, CodexError>;
+    fn manual_mode_label(&self) -> &str;
+    fn plugin_name(&self) -> &str;
+    fn log_info(&mut self, message: &str);
+    fn log_debug(&mut self, message: &str);
+    fn log_warn(&mut self, message: &str);
+}
+
+/// TS `runRuntimeOAuthFlow(forceNewLogin, deps)`.
+pub async fn run_runtime_oauth_flow<D: RuntimeOAuthFlowDeps>(
+    force_new_login: bool,
+    deps: &mut D,
+) -> Result<TokenResult, CodexError> {
+    let plugin_prefix = format!("[{}]", deps.plugin_name());
+    let manual_mode_label = deps.manual_mode_label().to_string();
+
+    // Collect adapter output, then flush through the deps sinks (Rust's
+    // borrow rules forbid re-borrowing `deps` inside the closures).
+    let mut info_lines: Vec<String> = Vec::new();
+    let mut debug_lines: Vec<String> = Vec::new();
+    let mut warn_lines: Vec<String> = Vec::new();
+    let result = {
+        let mut log_info = |message: &str| info_lines.push(message.to_string());
+        let mut log_debug =
+            |message: &str| debug_lines.push(prefix_log_message(&plugin_prefix, message, false));
+        let mut log_warn =
+            |message: &str| warn_lines.push(prefix_log_message(&plugin_prefix, message, true));
+        deps.run_browser_oauth_flow(
+            force_new_login,
+            &manual_mode_label,
+            &mut log_info,
+            &mut log_debug,
+            &mut log_warn,
+        )
+        .await
+    };
+    for line in info_lines {
+        deps.log_info(&line);
+    }
+    for line in debug_lines {
+        deps.log_debug(&line);
+    }
+    for line in warn_lines {
+        deps.log_warn(&line);
+    }
+    result
+}
+
+/// TS `createPersistAccounts(deps)(results, replaceAll)` — absorbed shim:
+/// delegates straight to `crate::account_pool::persist_account_pool_results`.
+pub async fn persist_accounts(
+    results: &[TokenSuccessWithAccount],
+    replace_all: bool,
+) -> Result<(), CodexError> {
+    crate::account_pool::persist_account_pool_results(results, replace_all).await
+}
+
+// =============================================================================
+// Tests — facade prefix normalization contract
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::TokenFailure;
+
+    #[test]
+    fn prefix_log_message_matches_ts() {
+        let prefix = "[codex-multi-auth]";
+        assert_eq!(
+            prefix_log_message(prefix, "hello", false),
+            "[codex-multi-auth] hello"
+        );
+        assert_eq!(
+            prefix_log_message(prefix, "hello", true),
+            "\n[codex-multi-auth] hello"
+        );
+        // Already prefixed → untouched.
+        assert_eq!(
+            prefix_log_message(prefix, "[codex-multi-auth] hi", true),
+            "[codex-multi-auth] hi"
+        );
+        // Prefixed after a leading newline → untouched.
+        assert_eq!(
+            prefix_log_message(prefix, "\n[codex-multi-auth] hi", false),
+            "\n[codex-multi-auth] hi"
+        );
+    }
+
+    struct FakeDeps {
+        infos: Vec<String>,
+        debugs: Vec<String>,
+        warns: Vec<String>,
+        seen_label: Option<String>,
+        seen_force: Option<bool>,
+    }
+
+    impl RuntimeOAuthFlowDeps for FakeDeps {
+        async fn run_browser_oauth_flow(
+            &mut self,
+            force_new_login: bool,
+            manual_mode_label: &str,
+            log_info: &mut dyn FnMut(&str),
+            log_debug: &mut dyn FnMut(&str),
+            log_warn: &mut dyn FnMut(&str),
+        ) -> Result<TokenResult, CodexError> {
+            self.seen_label = Some(manual_mode_label.to_string());
+            self.seen_force = Some(force_new_login);
+            log_info("OAuth URL: <redacted>");
+            log_debug("raw debug");
+            log_debug("[codex-multi-auth] already prefixed");
+            log_warn("server failed");
+            Ok(TokenResult::Failed(TokenFailure::default()))
+        }
+        fn manual_mode_label(&self) -> &str {
+            "ChatGPT (manual)"
+        }
+        fn plugin_name(&self) -> &str {
+            "codex-multi-auth"
+        }
+        fn log_info(&mut self, message: &str) {
+            self.infos.push(message.to_string());
+        }
+        fn log_debug(&mut self, message: &str) {
+            self.debugs.push(message.to_string());
+        }
+        fn log_warn(&mut self, message: &str) {
+            self.warns.push(message.to_string());
+        }
+    }
+
+    #[tokio::test]
+    async fn wraps_logs_with_plugin_prefix() {
+        let mut deps = FakeDeps {
+            infos: Vec::new(),
+            debugs: Vec::new(),
+            warns: Vec::new(),
+            seen_label: None,
+            seen_force: None,
+        };
+        let result = run_runtime_oauth_flow(true, &mut deps).await.unwrap();
+        assert!(!result.is_success());
+        assert_eq!(deps.seen_force, Some(true));
+        assert_eq!(deps.seen_label.as_deref(), Some("ChatGPT (manual)"));
+        // Info passes through unprefixed.
+        assert_eq!(deps.infos, vec!["OAuth URL: <redacted>"]);
+        // Debug prefixed once, never double-prefixed.
+        assert_eq!(
+            deps.debugs,
+            vec![
+                "[codex-multi-auth] raw debug",
+                "[codex-multi-auth] already prefixed"
+            ]
+        );
+        // Warn gets the leading newline.
+        assert_eq!(deps.warns, vec!["\n[codex-multi-auth] server failed"]);
+    }
+}
diff --git a/crates/runtime/src/oauth_flows/manual.rs b/crates/runtime/src/oauth_flows/manual.rs
new file mode 100644
index 000000000..3ed49751a
--- /dev/null
+++ b/crates/runtime/src/oauth_flows/manual.rs
@@ -0,0 +1,394 @@
+//! Port of `lib/runtime/manual-oauth-flow.ts` — manual paste-the-callback-URL
+//! OAuth flow (spec 10 §20).
+//!
+//! `validate` classifies the pasted input WITHOUT side effects (returns the
+//! exact operator-facing error strings); `callback` re-parses, exchanges the
+//! code, resolves the account selection and optionally persists via
+//! `on_success`.
+
+use cma_core::errors::CodexError;
+use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenResult, TokenSuccess};
+use cma_core::types::ParsedAuthInput;
+
+use crate::account_selection::TokenSuccessWithAccount;
+
+/// The `callback` outcome: either the resolved success (TS `TResolved`) or a
+/// pass-through token failure.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ManualFlowOutcome {
+    Resolved(TokenSuccessWithAccount),
+    Failed(TokenFailure),
+}
+
+impl ManualFlowOutcome {
+    pub fn is_success(&self) -> bool {
+        matches!(self, Self::Resolved(_))
+    }
+}
+
+/// Collaborators of the manual flow (TS `ManualOAuthFlowParams` behavior
+/// members).
+#[allow(async_fn_in_trait)]
+pub trait ManualOAuthFlowDeps {
+    fn parse_authorization_input(&self, input: &str) -> ParsedAuthInput {
+        cma_auth::oauth::parse_authorization_input(input)
+    }
+    async fn exchange_authorization_code(
+        &mut self,
+        code: &str,
+        verifier: &str,
+        redirect_uri: &str,
+    ) -> TokenResult;
+    /// TS `resolveTokenSuccess` (the runtime overload wires
+    /// `resolveAccountSelection` + `CODEX_AUTH_ACCOUNT_ID`).
+    fn resolve_token_success(&mut self, tokens: TokenSuccess) -> TokenSuccessWithAccount;
+    /// TS optional `onSuccess` — errors propagate (the TS callback awaits it
+    /// without a catch).
+    async fn on_success(&mut self, tokens: &TokenSuccessWithAccount) -> Result<(), CodexError> {
+        let _ = tokens;
+        Ok(())
+    }
+}
+
+/// TS `ManualOAuthFlow` — `{url, method: "code", instructions, validate,
+/// callback}` with the closures expressed as methods over stored state.
+pub struct ManualOAuthFlow<D: ManualOAuthFlowDeps> {
+    pub url: String,
+    /// Always `"code"`.
+    pub method: &'static str,
+    pub instructions: String,
+    pkce_verifier: String,
+    expected_state: String,
+    redirect_uri: String,
+    deps: D,
+}
+
+/// Data half of the TS `ManualOAuthFlowParams` object.
+pub struct ManualOAuthFlowParams {
+    pub pkce_verifier: String,
+    pub url: String,
+    pub expected_state: String,
+    pub redirect_uri: String,
+    pub instructions: String,
+}
+
+/// TS `buildManualOAuthFlow(params)` (generic overload).
+pub fn build_manual_oauth_flow<D: ManualOAuthFlowDeps>(
+    params: ManualOAuthFlowParams,
+    deps: D,
+) -> ManualOAuthFlow<D> {
+    ManualOAuthFlow {
+        url: params.url,
+        method: "code",
+        instructions: params.instructions,
+        pkce_verifier: params.pkce_verifier,
+        expected_state: params.expected_state,
+        redirect_uri: params.redirect_uri,
+        deps,
+    }
+}
+
+impl<D: ManualOAuthFlowDeps> ManualOAuthFlow<D> {
+    /// TS `flow.validate(input)` — `None` = valid; `Some(message)` = the
+    /// exact operator-facing error.
+    pub fn validate(&self, input: &str) -> Option<String> {
+        let parsed = self.deps.parse_authorization_input(input);
+        if parsed.code.is_none() {
+            return Some(format!(
+                "No authorization code found. Paste the full callback URL (e.g., {}?code=...)",
+                self.redirect_uri
+            ));
+        }
+        if parsed.state.is_none() {
+            return Some(
+                "Missing OAuth state. Paste the full callback URL including both code and state parameters."
+                    .to_string(),
+            );
+        }
+        if parsed.state.as_deref() != Some(self.expected_state.as_str()) {
+            return Some(
+                "OAuth state mismatch. Restart login and paste the callback URL generated for this login attempt."
+                    .to_string(),
+            );
+        }
+        None
+    }
+
+    /// TS `flow.callback(input)`.
+    pub async fn callback(&mut self, input: &str) -> Result<ManualFlowOutcome, CodexError> {
+        let parsed = self.deps.parse_authorization_input(input);
+        let (Some(code), Some(state)) = (parsed.code, parsed.state) else {
+            return Ok(ManualFlowOutcome::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::InvalidResponse),
+                status_code: None,
+                message: Some("Missing authorization code or OAuth state".to_string()),
+            }));
+        };
+        if state != self.expected_state {
+            return Ok(ManualFlowOutcome::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::InvalidResponse),
+                status_code: None,
+                message: Some("OAuth state mismatch. Restart login and try again.".to_string()),
+            }));
+        }
+        let tokens = self
+            .deps
+            .exchange_authorization_code(&code, &self.pkce_verifier, &self.redirect_uri)
+            .await;
+        match tokens {
+            TokenResult::Success(tokens) => {
+                let resolved = self.deps.resolve_token_success(tokens);
+                self.deps.on_success(&resolved).await?;
+                Ok(ManualFlowOutcome::Resolved(resolved))
+            }
+            TokenResult::Failed(failure) => Ok(ManualFlowOutcome::Failed(failure)),
+        }
+    }
+}
+
+// =============================================================================
+// Runtime overload wiring (TS `buildManualOAuthFlow(pkce, url, state, deps)`)
+// =============================================================================
+
+/// TS optional `onSuccess(resolved)` hook shape.
+pub type OnManualFlowSuccess<'a> =
+    &'a mut dyn FnMut(&TokenSuccessWithAccount) -> Result<(), CodexError>;
+
+/// Runtime deps: `cma_auth` parse/exchange + `resolveAccountSelection` over
+/// `CODEX_AUTH_ACCOUNT_ID`, with an optional persist hook.
+pub struct RuntimeManualOAuthFlowDeps<'a> {
+    pub log_info: &'a mut dyn FnMut(&str),
+    /// TS optional `onSuccess(resolved)`.
+    pub on_success: Option<OnManualFlowSuccess<'a>>,
+}
+
+impl ManualOAuthFlowDeps for RuntimeManualOAuthFlowDeps<'_> {
+    async fn exchange_authorization_code(
+        &mut self,
+        code: &str,
+        verifier: &str,
+        redirect_uri: &str,
+    ) -> TokenResult {
+        cma_auth::oauth::exchange_authorization_code(code, verifier, Some(redirect_uri)).await
+    }
+
+    fn resolve_token_success(&mut self, tokens: TokenSuccess) -> TokenSuccessWithAccount {
+        crate::account_selection::resolve_account_selection_runtime(tokens, self.log_info)
+    }
+
+    async fn on_success(&mut self, tokens: &TokenSuccessWithAccount) -> Result<(), CodexError> {
+        match self.on_success.as_mut() {
+            Some(on_success) => on_success(tokens),
+            None => Ok(()),
+        }
+    }
+}
+
+/// TS runtime overload — wires `REDIRECT_URI` and the runtime deps.
+pub fn build_runtime_manual_oauth_flow<'a>(
+    pkce_verifier: String,
+    url: String,
+    expected_state: String,
+    instructions: String,
+    deps: RuntimeManualOAuthFlowDeps<'a>,
+) -> ManualOAuthFlow<RuntimeManualOAuthFlowDeps<'a>> {
+    build_manual_oauth_flow(
+        ManualOAuthFlowParams {
+            pkce_verifier,
+            url,
+            expected_state,
+            redirect_uri: cma_auth::oauth::REDIRECT_URI.to_string(),
+            instructions,
+        },
+        deps,
+    )
+}
+
+// =============================================================================
+// Tests — ported from test/manual-oauth-flow.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct FakeDeps {
+        exchange_result: TokenResult,
+        exchanged: Vec<(String, String, String)>,
+        on_success_calls: u32,
+        on_success_fails: bool,
+    }
+
+    impl FakeDeps {
+        fn success() -> Self {
+            Self {
+                exchange_result: TokenResult::Success(TokenSuccess {
+                    access: "at".to_string(),
+                    refresh: "rt".to_string(),
+                    expires: 9_999,
+                    id_token: None,
+                    multi_account: None,
+                }),
+                exchanged: Vec::new(),
+                on_success_calls: 0,
+                on_success_fails: false,
+            }
+        }
+    }
+
+    impl ManualOAuthFlowDeps for FakeDeps {
+        async fn exchange_authorization_code(
+            &mut self,
+            code: &str,
+            verifier: &str,
+            redirect_uri: &str,
+        ) -> TokenResult {
+            self.exchanged
+                .push((code.to_string(), verifier.to_string(), redirect_uri.to_string()));
+            self.exchange_result.clone()
+        }
+        fn resolve_token_success(&mut self, tokens: TokenSuccess) -> TokenSuccessWithAccount {
+            let mut resolved = TokenSuccessWithAccount::plain(tokens);
+            resolved.account_label = Some("Resolved".to_string());
+            resolved
+        }
+        async fn on_success(
+            &mut self,
+            _tokens: &TokenSuccessWithAccount,
+        ) -> Result<(), CodexError> {
+            self.on_success_calls += 1;
+            if self.on_success_fails {
+                return Err(CodexError::new("persist failed"));
+            }
+            Ok(())
+        }
+    }
+
+    fn flow(deps: FakeDeps) -> ManualOAuthFlow<FakeDeps> {
+        build_manual_oauth_flow(
+            ManualOAuthFlowParams {
+                pkce_verifier: "verifier-1".to_string(),
+                url: "https://auth.openai.com/authorize?x=1".to_string(),
+                expected_state: "state-1".to_string(),
+                redirect_uri: "http://localhost:1455/auth/callback".to_string(),
+                instructions: "Paste the URL".to_string(),
+            },
+            deps,
+        )
+    }
+
+    #[test]
+    fn validate_error_strings_are_exact() {
+        let flow = flow(FakeDeps::success());
+        assert_eq!(flow.method, "code");
+        // Empty input parses to no code at all (bare strings are treated as
+        // raw codes by parseAuthorizationInput — same as TS).
+        assert_eq!(
+            flow.validate(""),
+            Some(
+                "No authorization code found. Paste the full callback URL (e.g., http://localhost:1455/auth/callback?code=...)"
+                    .to_string()
+            )
+        );
+        assert_eq!(
+            flow.validate("http://localhost:1455/auth/callback?code=abc"),
+            Some(
+                "Missing OAuth state. Paste the full callback URL including both code and state parameters."
+                    .to_string()
+            )
+        );
+        assert_eq!(
+            flow.validate("http://localhost:1455/auth/callback?code=abc&state=WRONG"),
+            Some(
+                "OAuth state mismatch. Restart login and paste the callback URL generated for this login attempt."
+                    .to_string()
+            )
+        );
+        assert_eq!(
+            flow.validate("http://localhost:1455/auth/callback?code=abc&state=state-1"),
+            None
+        );
+    }
+
+    #[tokio::test]
+    async fn callback_classifies_missing_and_mismatched_state() {
+        let mut flow = flow(FakeDeps::success());
+        let outcome = flow.callback("garbage").await.unwrap();
+        let ManualFlowOutcome::Failed(failure) = outcome else {
+            panic!("expected failure");
+        };
+        assert_eq!(failure.reason, Some(TokenFailureReason::InvalidResponse));
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("Missing authorization code or OAuth state")
+        );
+
+        let outcome = flow
+            .callback("http://localhost:1455/auth/callback?code=abc&state=WRONG")
+            .await
+            .unwrap();
+        let ManualFlowOutcome::Failed(failure) = outcome else {
+            panic!("expected failure");
+        };
+        assert_eq!(
+            failure.message.as_deref(),
+            Some("OAuth state mismatch. Restart login and try again.")
+        );
+        // Exchange never ran.
+        assert!(flow.deps.exchanged.is_empty());
+    }
+
+    #[tokio::test]
+    async fn callback_exchanges_resolves_and_fires_on_success() {
+        let mut flow = flow(FakeDeps::success());
+        let outcome = flow
+            .callback("http://localhost:1455/auth/callback?code=abc&state=state-1")
+            .await
+            .unwrap();
+        let ManualFlowOutcome::Resolved(resolved) = outcome else {
+            panic!("expected success");
+        };
+        assert_eq!(resolved.account_label.as_deref(), Some("Resolved"));
+        assert_eq!(
+            flow.deps.exchanged,
+            vec![(
+                "abc".to_string(),
+                "verifier-1".to_string(),
+                "http://localhost:1455/auth/callback".to_string()
+            )]
+        );
+        assert_eq!(flow.deps.on_success_calls, 1);
+    }
+
+    #[tokio::test]
+    async fn failed_exchange_passes_failure_through() {
+        let mut deps = FakeDeps::success();
+        deps.exchange_result = TokenResult::Failed(TokenFailure {
+            reason: Some(TokenFailureReason::HttpError),
+            status_code: Some(500),
+            message: Some("boom".to_string()),
+        });
+        let mut flow = flow(deps);
+        let outcome = flow
+            .callback("http://localhost:1455/auth/callback?code=abc&state=state-1")
+            .await
+            .unwrap();
+        let ManualFlowOutcome::Failed(failure) = outcome else {
+            panic!("expected failure");
+        };
+        assert_eq!(failure.status_code, Some(500));
+        assert_eq!(flow.deps.on_success_calls, 0);
+    }
+
+    #[tokio::test]
+    async fn on_success_errors_propagate() {
+        let mut deps = FakeDeps::success();
+        deps.on_success_fails = true;
+        let mut flow = flow(deps);
+        let error = flow
+            .callback("http://localhost:1455/auth/callback?code=abc&state=state-1")
+            .await
+            .unwrap_err();
+        assert_eq!(error.message(), "persist failed");
+    }
+}
diff --git a/crates/runtime/src/oauth_flows/mod.rs b/crates/runtime/src/oauth_flows/mod.rs
new file mode 100644
index 000000000..7da437b79
--- /dev/null
+++ b/crates/runtime/src/oauth_flows/mod.rs
@@ -0,0 +1,4 @@
+//! cma-runtime - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod browser;
+pub mod facade;
+pub mod manual;
diff --git a/crates/runtime/src/observability.rs b/crates/runtime/src/observability.rs
new file mode 100644
index 000000000..f843e3c9f
--- /dev/null
+++ b/crates/runtime/src/observability.rs
@@ -0,0 +1,698 @@
+//! Port of `lib/runtime/runtime-observability.ts` — process-wide singleton
+//! snapshot of proxy metrics, persisted to `<mad>/runtime-observability.json`.
+//!
+//! **In-memory state is the source of truth; disk is a write-behind mirror**
+//! loaded once lazily at first access. Persistence rules (spec 10 §5 / §12.5):
+//! `JSON.stringify(snapshot, null, 2)` with NO trailing newline, file mode
+//! 0o600, dir 0o700 (re-asserted via chmod on POSIX — non-ENOENT chmod errors
+//! THROW so a world-readable dir never silently holds account ids), temp+rename
+//! with 3 attempts retrying only EBUSY/EPERM. Writes are serialized and every
+//! write error is swallowed. Version-gated: a persisted numeric `version != 1`
+//! discards the file.
+//!
+//! Test-mode gate: the TS module skipped persistence entirely when
+//! `process.env.VITEST === "true"`; the Rust port keeps the same env var name
+//! but reads it live (per call) instead of once at module load, so test
+//! harnesses can flip it without ordering constraints (gotcha 23).
+
+use std::io;
+use std::path::PathBuf;
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use cma_core::json_io::{
+    read_text_file, stringify_pretty2, write_json_atomic_sync, TrailingNewline, WriteJsonOptions,
+};
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::now_ms;
+
+pub const RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION: i64 = 1;
+const SNAPSHOT_FILE_NAME: &str = "runtime-observability.json";
+
+/// Nested `runtimeMetrics` shape — all counters default 0. Field order is the
+/// TS declaration order (serialization order matters for byte parity).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeMetricsSnapshot {
+    pub started_at: i64,
+    pub total_requests: i64,
+    pub successful_requests: i64,
+    pub failed_requests: i64,
+    pub responses_requests: i64,
+    pub auth_refresh_requests: i64,
+    pub diagnostic_probe_requests: i64,
+    pub outbound_request_attempt_budget: Option<i64>,
+    pub outbound_request_attempts_consumed: i64,
+    pub request_attempt_budget_exhaustions: i64,
+    pub pool_exhaustion_fast_fails: i64,
+    pub server_burst_fast_fails: i64,
+    pub rate_limited_responses: i64,
+    pub server_errors: i64,
+    pub network_errors: i64,
+    pub user_aborts: i64,
+    pub auth_refresh_failures: i64,
+    pub empty_response_retries: i64,
+    pub account_rotations: i64,
+    pub same_account_retries: i64,
+    pub stream_failover_attempts: i64,
+    pub stream_failover_candidates_considered: i64,
+    pub last_stream_failover_candidate_count: i64,
+    pub stream_failover_recoveries: i64,
+    pub stream_failover_cross_account_recoveries: i64,
+    pub cumulative_latency_ms: i64,
+    pub last_request_at: Option<i64>,
+    pub last_error: Option<String>,
+    /// Unknown keys from a persisted file survive the merge (`{...base,
+    /// ...parsed.runtimeMetrics}` in TS) and re-serialize after the known set.
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, Value>,
+}
+
+/// Top-level persisted snapshot. Every field is populated by the default
+/// snapshot (TS `createDefaultSnapshot`), so `Option` fields serialize as
+/// explicit `null`, matching the TS output byte-for-byte.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeObservabilitySnapshot {
+    pub version: i64,
+    pub updated_at: i64,
+    pub current_request_id: Option<String>,
+    pub responses_requests: i64,
+    pub auth_refresh_requests: i64,
+    pub diagnostic_probe_requests: i64,
+    pub pool_exhaustion_cooldown_until: Option<i64>,
+    pub server_burst_cooldown_until: Option<i64>,
+    pub last_account_index: Option<i64>,
+    pub last_account_label: Option<String>,
+    pub last_account_email: Option<String>,
+    pub last_account_id: Option<String>,
+    pub last_account_updated_at: Option<i64>,
+    pub last_pool_exhaustion_reason: Option<String>,
+    pub last_pool_exhaustion_retry_after_ms: Option<i64>,
+    /// Keys are stringified account indexes.
+    pub last_pool_exhaustion_skip_reasons: serde_json::Map<String, Value>,
+    pub last_runtime_reset_at: Option<i64>,
+    pub last_runtime_reset_reason: Option<String>,
+    pub last_runtime_reload_at: Option<i64>,
+    pub last_runtime_reload_reason: Option<String>,
+    pub account_skip_reasons: serde_json::Map<String, Value>,
+    pub policy_blocked_indexes: Vec<i64>,
+    pub policy_blocked_reasons: serde_json::Map<String, Value>,
+    pub runtime_metrics: RuntimeMetricsSnapshot,
+    /// Unknown top-level keys from a persisted file (TS `{...base, ...parsed}`
+    /// spread keeps them); re-serialized after the known fields.
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, Value>,
+}
+
+fn create_default_metrics() -> RuntimeMetricsSnapshot {
+    RuntimeMetricsSnapshot {
+        started_at: 0,
+        total_requests: 0,
+        successful_requests: 0,
+        failed_requests: 0,
+        responses_requests: 0,
+        auth_refresh_requests: 0,
+        diagnostic_probe_requests: 0,
+        outbound_request_attempt_budget: None,
+        outbound_request_attempts_consumed: 0,
+        request_attempt_budget_exhaustions: 0,
+        pool_exhaustion_fast_fails: 0,
+        server_burst_fast_fails: 0,
+        rate_limited_responses: 0,
+        server_errors: 0,
+        network_errors: 0,
+        user_aborts: 0,
+        auth_refresh_failures: 0,
+        empty_response_retries: 0,
+        account_rotations: 0,
+        same_account_retries: 0,
+        stream_failover_attempts: 0,
+        stream_failover_candidates_considered: 0,
+        last_stream_failover_candidate_count: 0,
+        stream_failover_recoveries: 0,
+        stream_failover_cross_account_recoveries: 0,
+        cumulative_latency_ms: 0,
+        last_request_at: None,
+        last_error: None,
+        extra: serde_json::Map::new(),
+    }
+}
+
+pub fn create_default_snapshot() -> RuntimeObservabilitySnapshot {
+    RuntimeObservabilitySnapshot {
+        version: RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION,
+        updated_at: 0,
+        current_request_id: None,
+        responses_requests: 0,
+        auth_refresh_requests: 0,
+        diagnostic_probe_requests: 0,
+        pool_exhaustion_cooldown_until: None,
+        server_burst_cooldown_until: None,
+        last_account_index: None,
+        last_account_label: None,
+        last_account_email: None,
+        last_account_id: None,
+        last_account_updated_at: None,
+        last_pool_exhaustion_reason: None,
+        last_pool_exhaustion_retry_after_ms: None,
+        last_pool_exhaustion_skip_reasons: serde_json::Map::new(),
+        last_runtime_reset_at: None,
+        last_runtime_reset_reason: None,
+        last_runtime_reload_at: None,
+        last_runtime_reload_reason: None,
+        account_skip_reasons: serde_json::Map::new(),
+        policy_blocked_indexes: Vec::new(),
+        policy_blocked_reasons: serde_json::Map::new(),
+        runtime_metrics: create_default_metrics(),
+        extra: serde_json::Map::new(),
+    }
+}
+
+/// `PERSIST_RUNTIME_SNAPSHOT` — persistence disabled under the vitest-style
+/// test gate. Read live (see module docs).
+fn persist_runtime_snapshot() -> bool {
+    std::env::var("VITEST").ok().as_deref() != Some("true")
+}
+
+static SNAPSHOT_STATE: Mutex<Option<RuntimeObservabilitySnapshot>> = Mutex::new(None);
+/// Serializes persisted writes (the TS pending-write promise chain).
+static WRITE_QUEUE: Mutex<()> = Mutex::new(());
+
+fn get_snapshot_path() -> PathBuf {
+    get_codex_multi_auth_dir().join(SNAPSHOT_FILE_NAME)
+}
+
+/// Rebuild a string-valued overlay map (`{...(parsed.x ?? {})}` in TS —
+/// non-object values collapse to `{}`; non-string entry values are dropped so
+/// a corrupt file cannot poison the typed snapshot).
+fn rebuild_reason_map(value: Option<&Value>) -> serde_json::Map<String, Value> {
+    match value {
+        Some(Value::Object(map)) => map
+            .iter()
+            .filter(|(_, v)| v.is_string())
+            .map(|(k, v)| (k.clone(), v.clone()))
+            .collect(),
+        _ => serde_json::Map::new(),
+    }
+}
+
+/// `normalizePersistedSnapshot` — merge order: defaults ← parsed top-level ←
+/// forced `version:1`; `runtimeMetrics` deep-merged over defaults; the four
+/// map/array overlay fields rebuilt fresh. Returns `None` for non-objects and
+/// for numeric versions other than 1.
+fn normalize_persisted_snapshot(parsed: &Value) -> Option<RuntimeObservabilitySnapshot> {
+    let parsed_map = parsed.as_object()?;
+    if let Some(version) = parsed_map.get("version")
+        && version.is_number()
+        && version.as_i64() != Some(RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION)
+    {
+        return None;
+    }
+
+    let base = create_default_snapshot();
+    let mut merged = match serde_json::to_value(&base) {
+        Ok(Value::Object(map)) => map,
+        _ => return None,
+    };
+    for (key, value) in parsed_map {
+        merged.insert(key.clone(), value.clone());
+    }
+    merged.insert(
+        "version".to_string(),
+        Value::from(RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION),
+    );
+
+    // runtimeMetrics: defaults deep-merged with the parsed object (spread of a
+    // non-object contributes nothing).
+    let mut metrics = match serde_json::to_value(&base.runtime_metrics) {
+        Ok(Value::Object(map)) => map,
+        _ => return None,
+    };
+    if let Some(Value::Object(parsed_metrics)) = parsed_map.get("runtimeMetrics") {
+        for (key, value) in parsed_metrics {
+            metrics.insert(key.clone(), value.clone());
+        }
+    }
+    merged.insert("runtimeMetrics".to_string(), Value::Object(metrics));
+
+    merged.insert(
+        "lastPoolExhaustionSkipReasons".to_string(),
+        Value::Object(rebuild_reason_map(
+            parsed_map.get("lastPoolExhaustionSkipReasons"),
+        )),
+    );
+    merged.insert(
+        "accountSkipReasons".to_string(),
+        Value::Object(rebuild_reason_map(parsed_map.get("accountSkipReasons"))),
+    );
+    merged.insert(
+        "policyBlockedIndexes".to_string(),
+        Value::Array(match parsed_map.get("policyBlockedIndexes") {
+            Some(Value::Array(values)) => values
+                .iter()
+                .filter(|v| v.as_i64().is_some() || v.as_u64().is_some())
+                .cloned()
+                .collect(),
+            _ => Vec::new(),
+        }),
+    );
+    merged.insert(
+        "policyBlockedReasons".to_string(),
+        Value::Object(rebuild_reason_map(parsed_map.get("policyBlockedReasons"))),
+    );
+
+    // Deviation from TS (recorded): TS spread garbage-typed fields straight
+    // into the snapshot; the typed Rust struct cannot hold them, so a file
+    // whose known field has the wrong JSON type resets to fresh defaults.
+    serde_json::from_value(Value::Object(merged)).ok()
+}
+
+fn load_persisted_snapshot_from_disk() -> Option<RuntimeObservabilitySnapshot> {
+    let path = get_snapshot_path();
+    let raw = read_text_file(&path).ok()?;
+    let parsed: Value = serde_json::from_str(&raw).ok()?;
+    normalize_persisted_snapshot(&parsed)
+}
+
+fn ensure_snapshot_state<R>(f: impl FnOnce(&mut RuntimeObservabilitySnapshot) -> R) -> R {
+    let mut guard = SNAPSHOT_STATE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    if guard.is_none() {
+        let loaded = if persist_runtime_snapshot() {
+            load_persisted_snapshot_from_disk()
+        } else {
+            None
+        };
+        *guard = Some(loaded.unwrap_or_else(create_default_snapshot));
+    }
+    f(guard.as_mut().expect("snapshot state initialized"))
+}
+
+/// Persist a snapshot to disk. The snapshot holds account identifiers
+/// (`lastAccountId`/label/index), so the directory is kept owner-only on
+/// POSIX: `mkdir -p` with mode 0o700 plus an explicit re-`chmod 0o700` (mkdir
+/// mode only applies to freshly created dirs). Only ENOENT is swallowed on
+/// the chmod; any other failure is surfaced rather than silently leaving a
+/// world-readable dir. Win32: modes are a no-op (Node parity).
+fn write_snapshot(snapshot: &RuntimeObservabilitySnapshot) -> io::Result<()> {
+    let dir = get_codex_multi_auth_dir();
+    let path = get_snapshot_path();
+    create_dir_owner_only(&dir)?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        if let Err(error) =
+            std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700))
+            && error.kind() != io::ErrorKind::NotFound
+        {
+            return Err(error);
+        }
+    }
+    let content = stringify_pretty2(snapshot);
+    write_json_atomic_sync(
+        &path,
+        &content,
+        Some(0o600),
+        &WriteJsonOptions {
+            trailing_newline: TrailingNewline::None,
+            rename_max_attempts: 3,
+            ..WriteJsonOptions::default()
+        },
+    )
+}
+
+fn create_dir_owner_only(dir: &std::path::Path) -> io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        std::fs::DirBuilder::new()
+            .recursive(true)
+            .mode(0o700)
+            .create(dir)
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::create_dir_all(dir)
+    }
+}
+
+/// `getRuntimeObservabilitySnapshot` — a clone of the singleton (callers can't
+/// mutate the live state through it).
+pub fn get_runtime_observability_snapshot() -> RuntimeObservabilitySnapshot {
+    ensure_snapshot_state(|snapshot| snapshot.clone())
+}
+
+/// `mutateRuntimeObservabilitySnapshot` — applies the mutator, stamps
+/// `updatedAt = now`, and persists (skipped under the test gate). The write is
+/// serialized through [`WRITE_QUEUE`] and all write errors are swallowed,
+/// mirroring the TS pending-write promise chain with its `.catch(() =>
+/// undefined)` tail. (The TS write was queued asynchronously; the Rust port
+/// writes synchronously in mutation order — same ordering and error contract,
+/// with the file visible immediately after the call returns.)
+pub fn mutate_runtime_observability_snapshot(
+    mutator: impl FnOnce(&mut RuntimeObservabilitySnapshot),
+) {
+    let next_snapshot = ensure_snapshot_state(|snapshot| {
+        mutator(snapshot);
+        snapshot.updated_at = now_ms();
+        if persist_runtime_snapshot() {
+            Some(snapshot.clone())
+        } else {
+            None
+        }
+    });
+    if let Some(snapshot) = next_snapshot {
+        let _queue = WRITE_QUEUE
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        let _ = write_snapshot(&snapshot);
+    }
+}
+
+/// `recordRuntimePoolExhaustion` — sets the pool-exhaustion diagnostics and
+/// **copies** the skip reasons into both overlay maps.
+pub fn record_runtime_pool_exhaustion(
+    reason: &str,
+    retry_after_ms: i64,
+    account_skip_reasons: &serde_json::Map<String, Value>,
+) {
+    mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.last_pool_exhaustion_reason = Some(reason.to_string());
+        snapshot.last_pool_exhaustion_retry_after_ms = Some(retry_after_ms);
+        snapshot.last_pool_exhaustion_skip_reasons = account_skip_reasons.clone();
+        snapshot.account_skip_reasons = account_skip_reasons.clone();
+    });
+}
+
+/// `recordRuntimeReload` — stamps reload time + reason.
+pub fn record_runtime_reload(reason: &str) {
+    mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.last_runtime_reload_at = Some(now_ms());
+        snapshot.last_runtime_reload_reason = Some(reason.to_string());
+    });
+}
+
+/// `recordRuntimeReset` — stamps reset time + reason and clears both
+/// skip-reason maps, the pool-exhaustion fields, and the policy-block state.
+pub fn record_runtime_reset(reason: &str) {
+    mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.last_runtime_reset_at = Some(now_ms());
+        snapshot.last_runtime_reset_reason = Some(reason.to_string());
+        snapshot.last_pool_exhaustion_reason = None;
+        snapshot.last_pool_exhaustion_retry_after_ms = None;
+        snapshot.last_pool_exhaustion_skip_reasons = serde_json::Map::new();
+        snapshot.account_skip_reasons = serde_json::Map::new();
+        snapshot.policy_blocked_indexes = Vec::new();
+        snapshot.policy_blocked_reasons = serde_json::Map::new();
+    });
+}
+
+/// `recordRuntimeAccountRecovery` — clears a single account's persisted skip
+/// reason after a successful request. **No-op (no disk write) when the account
+/// has no recorded skip reason** in either map (spec 10 gotcha 16). Index must
+/// be an integer ≥ 0.
+pub fn record_runtime_account_recovery(index: i64) {
+    if index < 0 {
+        return;
+    }
+    let key = index.to_string();
+    let has_reason = ensure_snapshot_state(|snapshot| {
+        snapshot.account_skip_reasons.contains_key(&key)
+            || snapshot.last_pool_exhaustion_skip_reasons.contains_key(&key)
+    });
+    if !has_reason {
+        return;
+    }
+    mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.account_skip_reasons.shift_remove(&key);
+        snapshot.last_pool_exhaustion_skip_reasons.shift_remove(&key);
+    });
+}
+
+/// `loadPersistedRuntimeObservabilitySnapshot` — read-only variant of the
+/// loader; does NOT touch the singleton.
+pub fn load_persisted_runtime_observability_snapshot() -> Option<RuntimeObservabilitySnapshot> {
+    load_persisted_snapshot_from_disk()
+}
+
+/// Test hook: drop the singleton so the next access reloads from disk (or
+/// starts from defaults). Tests using this must be `#[serial(env)]` and pin
+/// `CODEX_MULTI_AUTH_DIR` via the testkit sandbox.
+pub fn reset_runtime_observability_for_tests() {
+    let mut guard = SNAPSHOT_STATE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    *guard = None;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn write_snapshot_file(sandbox: &EnvSandbox, contents: &str) {
+        let dir = sandbox.codex_multi_auth_dir();
+        std::fs::create_dir_all(&dir).expect("create multi-auth dir");
+        std::fs::write(dir.join(SNAPSHOT_FILE_NAME), contents).expect("seed snapshot file");
+    }
+
+    fn read_snapshot_file(sandbox: &EnvSandbox) -> String {
+        std::fs::read_to_string(sandbox.codex_multi_auth_dir().join(SNAPSHOT_FILE_NAME))
+            .expect("read snapshot file")
+    }
+
+    // runtime-observability.test.ts: "normalizes legacy unversioned snapshots"
+    #[test]
+    #[serial(env)]
+    fn normalizes_legacy_unversioned_snapshots() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        write_snapshot_file(
+            &sandbox,
+            "{\"responsesRequests\": 7, \"runtimeMetrics\": {\"totalRequests\": 9}}",
+        );
+        let snapshot = get_runtime_observability_snapshot();
+        assert_eq!(snapshot.version, 1);
+        assert_eq!(snapshot.responses_requests, 7);
+        assert_eq!(snapshot.runtime_metrics.total_requests, 9);
+        // Unset metrics fall back to defaults.
+        assert_eq!(snapshot.runtime_metrics.successful_requests, 0);
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts: "drops unknown future snapshot versions safely"
+    #[test]
+    #[serial(env)]
+    fn drops_unknown_future_snapshot_versions_safely() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        write_snapshot_file(&sandbox, "{\"version\": 2, \"responsesRequests\": 99}");
+        let snapshot = get_runtime_observability_snapshot();
+        assert_eq!(snapshot.version, 1);
+        assert_eq!(snapshot.responses_requests, 0);
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts: "seeds the first in-memory snapshot from
+    // disk before mutating"
+    #[test]
+    #[serial(env)]
+    fn seeds_the_first_in_memory_snapshot_from_disk_before_mutating() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        write_snapshot_file(
+            &sandbox,
+            "{\"version\": 1, \"responsesRequests\": 3, \"runtimeMetrics\": {\"totalRequests\": 3}}",
+        );
+        mutate_runtime_observability_snapshot(|snapshot| {
+            snapshot.responses_requests += 1;
+            snapshot.runtime_metrics.total_requests += 1;
+        });
+        let snapshot = get_runtime_observability_snapshot();
+        assert_eq!(snapshot.responses_requests, 4);
+        assert_eq!(snapshot.runtime_metrics.total_requests, 4);
+        assert!(snapshot.updated_at > 0);
+        // Persisted immediately (write-behind mirror).
+        let raw = read_snapshot_file(&sandbox);
+        assert!(raw.contains("\"responsesRequests\": 4"));
+        // NO trailing newline (spec 12.5).
+        assert!(!raw.ends_with('\n'));
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts: "normalizes and persists runtime pool
+    // exhaustion diagnostics"
+    #[test]
+    #[serial(env)]
+    fn normalizes_and_persists_runtime_pool_exhaustion_diagnostics() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        let mut reasons = serde_json::Map::new();
+        reasons.insert("0".to_string(), Value::from("rate-limited"));
+        reasons.insert("2".to_string(), Value::from("cooldown"));
+        record_runtime_pool_exhaustion("rate-limit", 45_000, &reasons);
+        let snapshot = get_runtime_observability_snapshot();
+        assert_eq!(
+            snapshot.last_pool_exhaustion_reason.as_deref(),
+            Some("rate-limit")
+        );
+        assert_eq!(snapshot.last_pool_exhaustion_retry_after_ms, Some(45_000));
+        assert_eq!(snapshot.last_pool_exhaustion_skip_reasons, reasons);
+        assert_eq!(snapshot.account_skip_reasons, reasons);
+        let raw = read_snapshot_file(&sandbox);
+        assert!(raw.contains("\"lastPoolExhaustionReason\": \"rate-limit\""));
+        assert!(raw.contains("\"rate-limited\""));
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts: "clears a single account's stale skip
+    // reason on recovery"
+    #[test]
+    #[serial(env)]
+    fn clears_a_single_accounts_stale_skip_reason_on_recovery() {
+        let _sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        let mut reasons = serde_json::Map::new();
+        reasons.insert("0".to_string(), Value::from("rate-limited"));
+        reasons.insert("1".to_string(), Value::from("cooldown"));
+        record_runtime_pool_exhaustion("rate-limit", 1_000, &reasons);
+        record_runtime_account_recovery(0);
+        let snapshot = get_runtime_observability_snapshot();
+        assert!(!snapshot.account_skip_reasons.contains_key("0"));
+        assert!(!snapshot.last_pool_exhaustion_skip_reasons.contains_key("0"));
+        assert!(snapshot.account_skip_reasons.contains_key("1"));
+        assert!(snapshot.last_pool_exhaustion_skip_reasons.contains_key("1"));
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts: "is a no-op when the recovered account
+    // has no recorded skip reason"
+    #[test]
+    #[serial(env)]
+    fn recovery_is_a_no_op_without_a_recorded_skip_reason() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        // Snapshot untouched, no file written for a clean account.
+        record_runtime_account_recovery(3);
+        record_runtime_account_recovery(-1);
+        assert!(!sandbox
+            .codex_multi_auth_dir()
+            .join(SNAPSHOT_FILE_NAME)
+            .exists());
+        reset_runtime_observability_for_tests();
+    }
+
+    // runtime-observability.test.ts (reset semantics used by #606 recovery).
+    #[test]
+    #[serial(env)]
+    fn reset_clears_skip_reasons_and_pool_exhaustion_fields() {
+        let _sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        let mut reasons = serde_json::Map::new();
+        reasons.insert("0".to_string(), Value::from("rate-limited"));
+        record_runtime_pool_exhaustion("rate-limit", 2_000, &reasons);
+        mutate_runtime_observability_snapshot(|snapshot| {
+            snapshot.policy_blocked_indexes = vec![1, 2];
+            snapshot
+                .policy_blocked_reasons
+                .insert("1".to_string(), Value::from("paused"));
+        });
+        record_runtime_reset("pool-exhausted-no-account");
+        let snapshot = get_runtime_observability_snapshot();
+        assert_eq!(
+            snapshot.last_runtime_reset_reason.as_deref(),
+            Some("pool-exhausted-no-account")
+        );
+        assert!(snapshot.last_runtime_reset_at.is_some());
+        assert!(snapshot.last_pool_exhaustion_reason.is_none());
+        assert!(snapshot.last_pool_exhaustion_retry_after_ms.is_none());
+        assert!(snapshot.last_pool_exhaustion_skip_reasons.is_empty());
+        assert!(snapshot.account_skip_reasons.is_empty());
+        assert!(snapshot.policy_blocked_indexes.is_empty());
+        assert!(snapshot.policy_blocked_reasons.is_empty());
+        reset_runtime_observability_for_tests();
+    }
+
+    // Version gate applies to the read-only loader too; policyBlockedIndexes
+    // filtered to integers.
+    #[test]
+    #[serial(env)]
+    fn read_only_loader_normalizes_without_touching_the_singleton() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        write_snapshot_file(
+            &sandbox,
+            "{\"version\": 1, \"policyBlockedIndexes\": [1, \"x\", 2.5, 3], \"accountSkipReasons\": {\"0\": \"rate-limited\", \"1\": 42}}",
+        );
+        let loaded =
+            load_persisted_runtime_observability_snapshot().expect("snapshot should normalize");
+        assert_eq!(loaded.policy_blocked_indexes, vec![1, 3]);
+        assert!(loaded.account_skip_reasons.contains_key("0"));
+        // Non-string reason values are dropped rather than poisoning the map.
+        assert!(!loaded.account_skip_reasons.contains_key("1"));
+        write_snapshot_file(&sandbox, "{\"version\": 7}");
+        assert!(load_persisted_runtime_observability_snapshot().is_none());
+        write_snapshot_file(&sandbox, "not json");
+        assert!(load_persisted_runtime_observability_snapshot().is_none());
+        write_snapshot_file(&sandbox, "[1,2,3]");
+        assert!(load_persisted_runtime_observability_snapshot().is_none());
+        reset_runtime_observability_for_tests();
+    }
+
+    // VITEST gate: persistence disabled entirely.
+    #[test]
+    #[serial(env)]
+    fn vitest_gate_disables_persistence() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var("VITEST", "true");
+        reset_runtime_observability_for_tests();
+        mutate_runtime_observability_snapshot(|snapshot| {
+            snapshot.responses_requests += 1;
+        });
+        assert!(!sandbox
+            .codex_multi_auth_dir()
+            .join(SNAPSHOT_FILE_NAME)
+            .exists());
+        reset_runtime_observability_for_tests();
+    }
+
+    // Serialization order + null fields match the TS JSON.stringify output.
+    #[test]
+    fn default_snapshot_serializes_in_ts_field_order() {
+        let raw = stringify_pretty2(&create_default_snapshot());
+        let version_idx = raw.find("\"version\"").unwrap();
+        let updated_idx = raw.find("\"updatedAt\"").unwrap();
+        let metrics_idx = raw.find("\"runtimeMetrics\"").unwrap();
+        assert!(version_idx < updated_idx);
+        assert!(updated_idx < metrics_idx);
+        assert!(raw.contains("\"currentRequestId\": null"));
+        assert!(raw.contains("\"lastAccountIndex\": null"));
+        assert!(raw.contains("\"outboundRequestAttemptBudget\": null"));
+        assert!(raw.contains("\"lastPoolExhaustionSkipReasons\": {}"));
+        assert!(raw.contains("\"policyBlockedIndexes\": []"));
+    }
+
+    // Unknown keys survive the merge and re-serialize (TS spread semantics).
+    #[test]
+    #[serial(env)]
+    fn unknown_keys_round_trip_through_the_merge() {
+        let sandbox = EnvSandbox::new();
+        reset_runtime_observability_for_tests();
+        write_snapshot_file(
+            &sandbox,
+            "{\"version\": 1, \"futureField\": \"kept\", \"runtimeMetrics\": {\"futureCounter\": 5}}",
+        );
+        let loaded = load_persisted_runtime_observability_snapshot().expect("normalizes");
+        assert_eq!(loaded.extra.get("futureField"), Some(&Value::from("kept")));
+        assert_eq!(
+            loaded.runtime_metrics.extra.get("futureCounter"),
+            Some(&Value::from(5))
+        );
+        reset_runtime_observability_for_tests();
+    }
+}
diff --git a/crates/runtime/src/preemptive_quota.rs b/crates/runtime/src/preemptive_quota.rs
new file mode 100644
index 000000000..fedcb3d95
--- /dev/null
+++ b/crates/runtime/src/preemptive_quota.rs
@@ -0,0 +1,69 @@
+//! Port of `lib/runtime/preemptive-quota.ts` — the generic
+//! (config-type-parametric) variant of the preemptive-quota settings
+//! plumb (spec 10 §22, ARCHITECTURE §6.12). The concrete variant lives in
+//! [`crate::quota_settings::apply_preemptive_quota_settings_from_config`].
+
+use crate::quota_settings::PreemptiveQuotaSettings;
+
+/// TS `applyRuntimePreemptiveQuotaSettings(pluginConfig, deps)`.
+pub fn apply_runtime_preemptive_quota_settings<TConfig>(
+    plugin_config: &TConfig,
+    get_preemptive_quota_enabled: impl FnOnce(&TConfig) -> bool,
+    get_preemptive_quota_remaining_percent_5h: impl FnOnce(&TConfig) -> f64,
+    get_preemptive_quota_remaining_percent_7d: impl FnOnce(&TConfig) -> f64,
+    get_preemptive_quota_max_deferral_ms: impl FnOnce(&TConfig) -> f64,
+    configure: impl FnOnce(PreemptiveQuotaSettings),
+) {
+    configure(PreemptiveQuotaSettings {
+        enabled: get_preemptive_quota_enabled(plugin_config),
+        remaining_percent_threshold_primary: get_preemptive_quota_remaining_percent_5h(
+            plugin_config,
+        ),
+        remaining_percent_threshold_secondary: get_preemptive_quota_remaining_percent_7d(
+            plugin_config,
+        ),
+        max_deferral_ms: get_preemptive_quota_max_deferral_ms(plugin_config),
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct TestConfig {
+        enabled: bool,
+        p5h: f64,
+        p7d: f64,
+        max_deferral: f64,
+    }
+
+    #[test]
+    fn maps_getters_positionally_into_the_configure_payload() {
+        let config = TestConfig {
+            enabled: true,
+            p5h: 12.0,
+            p7d: 7.5,
+            max_deferral: 45_000.0,
+        };
+        let mut captured: Option<PreemptiveQuotaSettings> = None;
+
+        apply_runtime_preemptive_quota_settings(
+            &config,
+            |c| c.enabled,
+            |c| c.p5h,
+            |c| c.p7d,
+            |c| c.max_deferral,
+            |settings| captured = Some(settings),
+        );
+
+        assert_eq!(
+            captured,
+            Some(PreemptiveQuotaSettings {
+                enabled: true,
+                remaining_percent_threshold_primary: 12.0,
+                remaining_percent_threshold_secondary: 7.5,
+                max_deferral_ms: 45_000.0,
+            })
+        );
+    }
+}
diff --git a/crates/runtime/src/proactive_refresh.rs b/crates/runtime/src/proactive_refresh.rs
new file mode 100644
index 000000000..cb5e956f6
--- /dev/null
+++ b/crates/runtime/src/proactive_refresh.rs
@@ -0,0 +1,373 @@
+//! Port of `lib/proactive-refresh.ts` — proactive token refresh: refreshes
+//! OAuth tokens before they expire to prevent auth failures mid-request
+//! (spec 10, ARCHITECTURE §6.12: 5-min buffer, 250 ms stagger, batch
+//! refresh).
+
+use cma_accounts::manager::ManagedAccount;
+use cma_auth::refresh_queue::queued_refresh;
+use cma_core::logger::{create_logger, mask_email, ScopedLogger};
+use cma_core::schemas::token::{TokenResult, TokenSuccess};
+use cma_core::token_utils::{
+    extract_account_email, extract_account_id, sanitize_email, should_update_account_id_from_token,
+};
+use cma_core::schemas::account_storage::AccountIdSource;
+use cma_core::utils::{now_ms, sleep};
+use serde_json::json;
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, LazyLock};
+
+fn log() -> &'static ScopedLogger {
+    static LOG: LazyLock<ScopedLogger> = LazyLock::new(|| create_logger("proactive-refresh"));
+    &LOG
+}
+
+/// Default buffer before expiry to trigger proactive refresh (5 minutes).
+pub const DEFAULT_PROACTIVE_BUFFER_MS: i64 = 5 * 60 * 1000;
+
+/// Minimum buffer to prevent unnecessary refreshes (30 seconds).
+pub const MIN_PROACTIVE_BUFFER_MS: i64 = 30 * 1000;
+
+const PROACTIVE_REFRESH_STAGGER_MS: u64 = 250;
+
+/// TS `ProactiveRefreshResult.reason` union.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProactiveRefreshReason {
+    NotNeeded,
+    NoRefreshToken,
+    Success,
+    Failed,
+}
+
+impl ProactiveRefreshReason {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ProactiveRefreshReason::NotNeeded => "not_needed",
+            ProactiveRefreshReason::NoRefreshToken => "no_refresh_token",
+            ProactiveRefreshReason::Success => "success",
+            ProactiveRefreshReason::Failed => "failed",
+        }
+    }
+}
+
+/// TS `ProactiveRefreshResult`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProactiveRefreshResult {
+    pub refreshed: bool,
+    pub token_result: Option<TokenResult>,
+    pub reason: ProactiveRefreshReason,
+}
+
+/// The injectable refresh seam (production: the global refresh queue; the
+/// TS tests replaced the module import with `vi.mock`).
+pub type RefreshFn =
+    Arc<dyn Fn(String) -> Pin<Box<dyn Future<Output = TokenResult> + Send>> + Send + Sync>;
+
+/// The production refresh function — `queuedRefresh` over the global
+/// cross-request refresh queue.
+pub fn queued_refresh_fn() -> RefreshFn {
+    Arc::new(|refresh_token| Box::pin(async move { queued_refresh(&refresh_token).await }))
+}
+
+/// Per-account result callback (TS `onResult`). Receives clones so the
+/// returned future is `'static` (the TS closure captured everything by
+/// reference on a single thread).
+pub type OnRefreshResult = Box<
+    dyn FnMut(ManagedAccount, ProactiveRefreshResult) -> Pin<Box<dyn Future<Output = ()> + Send>>
+        + Send,
+>;
+
+/// TS `shouldRefreshProactively(account, bufferMs)` — true if the token is
+/// approaching expiry and should be refreshed. No access token ⇒ true; no
+/// expiry ⇒ false (can't determine); otherwise `now >= expires -
+/// max(MIN_PROACTIVE_BUFFER_MS, bufferMs)`.
+pub fn should_refresh_proactively(account: &ManagedAccount, buffer_ms: i64) -> bool {
+    // TS `if (!account.access)` — undefined AND empty string are falsy.
+    match account.meta.access_token.as_deref() {
+        None | Some("") => return true,
+        Some(_) => {}
+    }
+    let Some(expires_at) = account.meta.expires_at else {
+        return false;
+    };
+    let safe_buffer_ms = buffer_ms.max(MIN_PROACTIVE_BUFFER_MS);
+    now_ms() >= expires_at - safe_buffer_ms
+}
+
+/// TS `getTimeUntilExpiry(account)` — ms until expiry (`>= 0`), or `None`
+/// for "no expiry set" (TS `Infinity`).
+pub fn get_time_until_expiry(account: &ManagedAccount) -> Option<i64> {
+    account
+        .meta
+        .expires_at
+        .map(|expires_at| (expires_at - now_ms()).max(0))
+}
+
+/// TS `proactiveRefreshAccount(account, bufferMs)` using the global refresh
+/// queue.
+pub async fn proactive_refresh_account(
+    account: &ManagedAccount,
+    buffer_ms: i64,
+) -> ProactiveRefreshResult {
+    proactive_refresh_account_with(account, buffer_ms, &queued_refresh_fn()).await
+}
+
+/// Seam variant of [`proactive_refresh_account`] (tests inject the refresh
+/// function).
+pub async fn proactive_refresh_account_with(
+    account: &ManagedAccount,
+    buffer_ms: i64,
+    refresh: &RefreshFn,
+) -> ProactiveRefreshResult {
+    if !should_refresh_proactively(account, buffer_ms) {
+        return ProactiveRefreshResult {
+            refreshed: false,
+            token_result: None,
+            reason: ProactiveRefreshReason::NotNeeded,
+        };
+    }
+
+    if account.meta.refresh_token.is_empty() {
+        log().warn(
+            "Cannot proactively refresh account without refresh token",
+            Some(&json!({ "accountIndex": account.index })),
+        );
+        return ProactiveRefreshResult {
+            refreshed: false,
+            token_result: None,
+            reason: ProactiveRefreshReason::NoRefreshToken,
+        };
+    }
+
+    let time_until_expiry = get_time_until_expiry(account);
+    let mut data = serde_json::Map::new();
+    data.insert("accountIndex".to_string(), json!(account.index));
+    if let Some(email) = account.meta.email.as_deref() {
+        data.insert("emailMasked".to_string(), json!(mask_email(email)));
+    }
+    // TS logs Infinity when no expiry is set; JSON.stringify(Infinity) is
+    // null, which `Value::Null` matches.
+    data.insert(
+        "expiresInMs".to_string(),
+        time_until_expiry.map_or(serde_json::Value::Null, |ms| json!(ms)),
+    );
+    data.insert(
+        "expiresInMinutes".to_string(),
+        time_until_expiry.map_or(serde_json::Value::Null, |ms| {
+            json!(((ms as f64) / 60_000.0).round() as i64)
+        }),
+    );
+    log().info(
+        "Proactively refreshing token",
+        Some(&serde_json::Value::Object(data)),
+    );
+
+    crate::observability::mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.auth_refresh_requests += 1;
+        snapshot.runtime_metrics.auth_refresh_requests += 1;
+    });
+    let result = refresh(account.meta.refresh_token.clone()).await;
+
+    let mut identity = serde_json::Map::new();
+    identity.insert("accountIndex".to_string(), json!(account.index));
+    if let Some(email) = account.meta.email.as_deref() {
+        identity.insert("emailMasked".to_string(), json!(mask_email(email)));
+    }
+
+    match &result {
+        TokenResult::Success(_) => {
+            log().info(
+                "Proactive refresh succeeded",
+                Some(&serde_json::Value::Object(identity)),
+            );
+            ProactiveRefreshResult {
+                refreshed: true,
+                token_result: Some(result),
+                reason: ProactiveRefreshReason::Success,
+            }
+        }
+        TokenResult::Failed(failure) => {
+            identity.insert(
+                "failureReason".to_string(),
+                failure
+                    .reason
+                    .as_ref()
+                    .map_or(serde_json::Value::Null, |reason| json!(reason.as_str())),
+            );
+            log().warn(
+                "Proactive refresh failed",
+                Some(&serde_json::Value::Object(identity)),
+            );
+            ProactiveRefreshResult {
+                refreshed: true,
+                token_result: Some(result),
+                reason: ProactiveRefreshReason::Failed,
+            }
+        }
+    }
+}
+
+/// TS `refreshExpiringAccounts(accounts, bufferMs, onResult?)` using the
+/// global refresh queue.
+pub async fn refresh_expiring_accounts(
+    accounts: &[ManagedAccount],
+    buffer_ms: i64,
+    on_result: Option<OnRefreshResult>,
+) -> HashMap<usize, ProactiveRefreshResult> {
+    refresh_expiring_accounts_with(accounts, buffer_ms, on_result, &queued_refresh_fn()).await
+}
+
+/// Seam variant of [`refresh_expiring_accounts`]. Refreshes sequentially
+/// with a 250 ms stagger between accounts; `on_result` runs per account as
+/// each refresh settles. Returns a map keyed by `account.index`.
+pub async fn refresh_expiring_accounts_with(
+    accounts: &[ManagedAccount],
+    buffer_ms: i64,
+    mut on_result: Option<OnRefreshResult>,
+    refresh: &RefreshFn,
+) -> HashMap<usize, ProactiveRefreshResult> {
+    let mut results: HashMap<usize, ProactiveRefreshResult> = HashMap::new();
+    let accounts_to_refresh: Vec<&ManagedAccount> = accounts
+        .iter()
+        .filter(|account| should_refresh_proactively(account, buffer_ms))
+        .collect();
+
+    if accounts_to_refresh.is_empty() {
+        log().debug("No accounts need proactive refresh", None);
+        return results;
+    }
+
+    log().info(
+        &format!(
+            "Proactively refreshing {} account(s)",
+            accounts_to_refresh.len()
+        ),
+        None,
+    );
+
+    let mut outcomes: Vec<(usize, ProactiveRefreshResult)> = Vec::new();
+    for (position, account) in accounts_to_refresh.iter().enumerate() {
+        if position > 0 {
+            sleep(PROACTIVE_REFRESH_STAGGER_MS).await;
+        }
+        let result = proactive_refresh_account_with(account, buffer_ms, refresh).await;
+        if let Some(on_result) = on_result.as_mut() {
+            on_result((*account).clone(), result.clone()).await;
+        }
+        outcomes.push((account.index, result));
+    }
+
+    for (index, result) in outcomes {
+        results.insert(index, result);
+    }
+
+    let succeeded = results
+        .values()
+        .filter(|r| r.reason == ProactiveRefreshReason::Success)
+        .count();
+    let failed = results
+        .values()
+        .filter(|r| r.reason == ProactiveRefreshReason::Failed)
+        .count();
+    if succeeded > 0 || failed > 0 {
+        log().info(
+            "Proactive refresh complete",
+            Some(&json!({
+                "total": accounts_to_refresh.len(),
+                "succeeded": succeeded,
+                "failed": failed,
+            })),
+        );
+    }
+
+    results
+}
+
+/// TS `applyRefreshResult(account, result)` — update a `ManagedAccount`
+/// with fresh token data from a successful refresh.
+pub fn apply_refresh_result(account: &mut ManagedAccount, result: &TokenSuccess) {
+    account.meta.access_token = Some(result.access.clone());
+    account.meta.expires_at = Some(result.expires);
+    if result.refresh != account.meta.refresh_token {
+        account.meta.refresh_token = result.refresh.clone();
+    }
+    let token_account_id = extract_account_id(Some(result.access.as_str()))
+        .map(|id| id.trim().to_string())
+        .filter(|id| !id.is_empty());
+    if let Some(token_account_id) = token_account_id
+        && should_update_account_id_from_token(
+            account.meta.account_id_source.as_ref(),
+            account.meta.account_id.as_deref(),
+        )
+    {
+        account.meta.account_id = Some(token_account_id);
+        account.meta.account_id_source = Some(AccountIdSource::Token);
+    }
+    account.meta.email =
+        sanitize_email(extract_account_email(Some(result.access.as_str()), None).as_deref())
+            .or(account.meta.email.take());
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+    use cma_accounts::manager::AccountManager;
+
+    fn account_with(access: Option<&str>, expires_at: Option<i64>) -> ManagedAccount {
+        let now = now_ms();
+        let mut meta = AccountMetadataV3::new("refresh-1", now, now);
+        meta.access_token = access.map(|s| s.to_string());
+        meta.expires_at = expires_at;
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![meta];
+        let manager = AccountManager::new(None, Some(&storage));
+        manager.get_account_by_index(0).cloned().unwrap()
+    }
+
+    #[test]
+    fn missing_or_empty_access_token_always_needs_refresh() {
+        let account = account_with(None, Some(now_ms() + 3_600_000));
+        assert!(should_refresh_proactively(&account, DEFAULT_PROACTIVE_BUFFER_MS));
+        let account = account_with(Some(""), Some(now_ms() + 3_600_000));
+        assert!(should_refresh_proactively(&account, DEFAULT_PROACTIVE_BUFFER_MS));
+    }
+
+    #[test]
+    fn missing_expiry_means_no_refresh() {
+        let account = account_with(Some("access"), None);
+        assert!(!should_refresh_proactively(&account, DEFAULT_PROACTIVE_BUFFER_MS));
+        assert_eq!(get_time_until_expiry(&account), None);
+    }
+
+    #[test]
+    fn buffer_is_clamped_to_the_minimum() {
+        // Expiry 60s out: a 1ms buffer clamps to 30s → not yet in window.
+        let account = account_with(Some("access"), Some(now_ms() + 60_000));
+        assert!(!should_refresh_proactively(&account, 1));
+        // Expiry 20s out: inside the clamped 30s window.
+        let account = account_with(Some("access"), Some(now_ms() + 20_000));
+        assert!(should_refresh_proactively(&account, 1));
+        // A large buffer widens the window.
+        let account = account_with(Some("access"), Some(now_ms() + 60_000));
+        assert!(should_refresh_proactively(&account, 120_000));
+    }
+
+    #[test]
+    fn time_until_expiry_clamps_at_zero() {
+        let account = account_with(Some("access"), Some(now_ms() - 5_000));
+        assert_eq!(get_time_until_expiry(&account), Some(0));
+    }
+
+    #[test]
+    fn reason_strings_are_frozen() {
+        assert_eq!(ProactiveRefreshReason::NotNeeded.as_str(), "not_needed");
+        assert_eq!(
+            ProactiveRefreshReason::NoRefreshToken.as_str(),
+            "no_refresh_token"
+        );
+        assert_eq!(ProactiveRefreshReason::Success.as_str(), "success");
+        assert_eq!(ProactiveRefreshReason::Failed.as_str(), "failed");
+    }
+}
diff --git a/crates/runtime/src/quota_probe.rs b/crates/runtime/src/quota_probe.rs
new file mode 100644
index 000000000..96fbbd42a
--- /dev/null
+++ b/crates/runtime/src/quota_probe.rs
@@ -0,0 +1,417 @@
+//! Port of `lib/runtime/quota-probe.ts` + `lib/runtime/quota-headers.ts` —
+//! runtime quota-probe adapters over `cma-quota` (spec 10 §16).
+//!
+//! The TS runtime cluster carries its own DI copy of the probe loop and the
+//! quota-header parsing; in Rust the probe loop lives once in
+//! `cma_quota::probe` (chain walk, 15 s timeout, unsupported-model
+//! traversal, `CodexUnavailableError` mapping) and this module provides:
+//! - the header-parsing pure functions (`parse_reset_at_ms`,
+//!   `parse_codex_quota_snapshot`) over any header source;
+//! - `format_codex_quota_line` (delegates to the quota crate — identical
+//!   output contract);
+//! - `fetch_runtime_codex_quota_snapshot`, the adapter the account-check
+//!   engine calls.
+
+use cma_core::errors::CodexError;
+use cma_core::utils::now_ms;
+use cma_quota::probe::{
+    CodexQuotaSnapshot, CodexQuotaWindow, ProbeCodexQuotaOptions, fetch_codex_quota_snapshot,
+    format_quota_snapshot_line,
+};
+
+/// TS `ParsedCodexQuotaSnapshot = Omit<CodexQuotaSnapshot, "model">`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ParsedCodexQuotaSnapshot {
+    pub status: u16,
+    pub plan_type: Option<String>,
+    pub active_limit: Option<i64>,
+    pub primary: CodexQuotaWindow,
+    pub secondary: CodexQuotaWindow,
+}
+
+impl ParsedCodexQuotaSnapshot {
+    /// TS `{ ...snapshot, model }`.
+    pub fn with_model(self, model: impl Into<String>) -> CodexQuotaSnapshot {
+        CodexQuotaSnapshot {
+            status: self.status,
+            plan_type: self.plan_type,
+            active_limit: self.active_limit,
+            primary: self.primary,
+            secondary: self.secondary,
+            model: model.into(),
+        }
+    }
+}
+
+/// Case-insensitive header lookup (the TS code reads WHATWG `Headers`).
+pub trait HeaderLookup {
+    /// The header value for `name` (lowercase), or `None` when absent.
+    fn get_header(&self, name: &str) -> Option<String>;
+}
+
+impl HeaderLookup for reqwest::header::HeaderMap {
+    fn get_header(&self, name: &str) -> Option<String> {
+        self.get(name)
+            .and_then(|v| v.to_str().ok())
+            .map(str::to_string)
+    }
+}
+
+impl HeaderLookup for std::collections::HashMap<String, String> {
+    fn get_header(&self, name: &str) -> Option<String> {
+        // Callers may use any casing; normalize both sides to lowercase.
+        let lowered = name.to_lowercase();
+        self.iter()
+            .find(|(k, _)| k.to_lowercase() == lowered)
+            .map(|(_, v)| v.clone())
+    }
+}
+
+impl HeaderLookup for Vec<(String, String)> {
+    fn get_header(&self, name: &str) -> Option<String> {
+        let lowered = name.to_lowercase();
+        self.iter()
+            .find(|(k, _)| k.to_lowercase() == lowered)
+            .map(|(_, v)| v.clone())
+    }
+}
+
+// =============================================================================
+// JS numeric semantics
+// =============================================================================
+
+/// JS `Number(raw)` over a header string (TS `parseFiniteNumberHeader`
+/// backing): trims; empty → 0; otherwise a full-string float parse
+/// (unparseable → `None`, i.e. NaN/non-finite).
+fn js_number(raw: &str) -> Option<f64> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return Some(0.0);
+    }
+    trimmed.parse::<f64>().ok().filter(|v| v.is_finite())
+}
+
+/// JS `Number.parseInt(raw, 10)`: skips leading whitespace, optional sign,
+/// then consumes leading decimal digits; NaN when none.
+fn js_parse_int(raw: &str) -> Option<i64> {
+    let trimmed = raw.trim_start();
+    let (negative, rest) = match trimmed.strip_prefix('-') {
+        Some(rest) => (true, rest),
+        None => (false, trimmed.strip_prefix('+').unwrap_or(trimmed)),
+    };
+    let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
+    if digits.is_empty() {
+        return None;
+    }
+    let value: i64 = digits.parse().ok()?;
+    Some(if negative { -value } else { value })
+}
+
+fn parse_finite_number_header(headers: &impl HeaderLookup, name: &str) -> Option<f64> {
+    let raw = headers.get_header(name)?;
+    if raw.is_empty() {
+        return None;
+    }
+    js_number(&raw)
+}
+
+fn parse_finite_int_header(headers: &impl HeaderLookup, name: &str) -> Option<i64> {
+    let raw = headers.get_header(name)?;
+    if raw.is_empty() {
+        return None;
+    }
+    js_parse_int(&raw)
+}
+
+// =============================================================================
+// Header parsing (TS quota-headers.ts)
+// =============================================================================
+
+/// TS `parseResetAtMs(headers, prefix)` — prefer
+/// `{prefix}-reset-after-seconds` (`> 0` → now + seconds); else
+/// `{prefix}-reset-at`: pure digits are epoch seconds when `< 1e10` (×1000)
+/// else already ms; otherwise an RFC date via `Date.parse`.
+///
+/// `now_override` is a Rust-only test seam for the `Date.now()` read.
+pub fn parse_reset_at_ms(
+    headers: &impl HeaderLookup,
+    prefix: &str,
+    now_override: Option<i64>,
+) -> Option<i64> {
+    if let Some(reset_after_seconds) =
+        parse_finite_int_header(headers, &format!("{prefix}-reset-after-seconds"))
+        && reset_after_seconds > 0
+    {
+        let now = now_override.unwrap_or_else(now_ms);
+        // f64 multiply mirrors JS semantics; the `as i64` cast saturates on
+        // overflow (hostile huge header → far-future resetAtMs, like TS).
+        return Some(now.saturating_add((reset_after_seconds as f64 * 1000.0) as i64));
+    }
+
+    let reset_at_raw = headers.get_header(&format!("{prefix}-reset-at"))?;
+    if reset_at_raw.is_empty() {
+        return None;
+    }
+
+    let trimmed = reset_at_raw.trim();
+    if !trimmed.is_empty()
+        && trimmed.chars().all(|c| c.is_ascii_digit())
+        && let Ok(parsed) = trimmed.parse::<i64>()
+        && parsed > 0
+    {
+        return Some(if parsed < 10_000_000_000 {
+            parsed * 1000
+        } else {
+            parsed
+        });
+    }
+
+    // Date.parse(trimmed): accept RFC 3339 / RFC 2822 forms (recorded
+    // deviation: JS Date.parse accepts more esoteric formats).
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc2822(trimmed) {
+        return Some(parsed.timestamp_millis());
+    }
+    None
+}
+
+const QUOTA_WINDOW_HEADER_KEYS: [&str; 8] = [
+    "x-codex-primary-used-percent",
+    "x-codex-primary-window-minutes",
+    "x-codex-primary-reset-at",
+    "x-codex-primary-reset-after-seconds",
+    "x-codex-secondary-used-percent",
+    "x-codex-secondary-window-minutes",
+    "x-codex-secondary-reset-at",
+    "x-codex-secondary-reset-after-seconds",
+];
+
+fn has_codex_quota_headers(headers: &impl HeaderLookup) -> bool {
+    QUOTA_WINDOW_HEADER_KEYS
+        .iter()
+        .any(|key| headers.get_header(key).is_some())
+}
+
+/// TS `parseCodexQuotaSnapshot(headers, status)` — `None` when none of the 8
+/// window headers are present.
+pub fn parse_codex_quota_snapshot(
+    headers: &impl HeaderLookup,
+    status: u16,
+) -> Option<ParsedCodexQuotaSnapshot> {
+    parse_codex_quota_snapshot_at(headers, status, None)
+}
+
+/// [`parse_codex_quota_snapshot`] with an injectable `Date.now()` for tests.
+pub fn parse_codex_quota_snapshot_at(
+    headers: &impl HeaderLookup,
+    status: u16,
+    now_override: Option<i64>,
+) -> Option<ParsedCodexQuotaSnapshot> {
+    if !has_codex_quota_headers(headers) {
+        return None;
+    }
+
+    let window = |prefix: &str| CodexQuotaWindow {
+        used_percent: parse_finite_number_header(headers, &format!("{prefix}-used-percent")),
+        window_minutes: parse_finite_int_header(headers, &format!("{prefix}-window-minutes")),
+        reset_at_ms: parse_reset_at_ms(headers, prefix, now_override),
+    };
+
+    let primary = window("x-codex-primary");
+    let secondary = window("x-codex-secondary");
+
+    let plan_type = headers
+        .get_header("x-codex-plan-type")
+        .map(|v| v.trim().to_string())
+        .filter(|v| !v.is_empty());
+    let active_limit = parse_finite_int_header(headers, "x-codex-active-limit");
+
+    Some(ParsedCodexQuotaSnapshot {
+        status,
+        plan_type,
+        active_limit,
+        primary,
+        secondary,
+    })
+}
+
+// =============================================================================
+// Formatting + the probe adapter
+// =============================================================================
+
+/// TS `formatCodexQuotaLine(snapshot)` — identical output contract to the
+/// quota crate's `formatQuotaSnapshotLine`; delegated so the string stays
+/// frozen in ONE place.
+pub fn format_codex_quota_line(snapshot: &CodexQuotaSnapshot) -> String {
+    format_quota_snapshot_line(snapshot)
+}
+
+/// TS `fetchRuntimeCodexQuotaSnapshot({accountId, accessToken, ...deps})` —
+/// the runtime adapter: walks `QUOTA_PROBE_MODEL_CHAIN` via the quota
+/// crate's probe (default chain, default 15 s per-model timeout).
+///
+/// `base_url_override` is the Rust test seam mirroring the TS `baseUrl`
+/// param (`None` in production → `CODEX_BASE_URL`).
+pub async fn fetch_runtime_codex_quota_snapshot(
+    account_id: &str,
+    access_token: &str,
+    base_url_override: Option<String>,
+) -> Result<CodexQuotaSnapshot, CodexError> {
+    let options = ProbeCodexQuotaOptions {
+        account_id: account_id.to_string(),
+        access_token: access_token.to_string(),
+        model: None,
+        fallback_models: None,
+        timeout_ms: None,
+        base_url: base_url_override,
+    };
+    fetch_codex_quota_snapshot(&options).await
+}
+
+// =============================================================================
+// Tests — ported from test/quota-headers.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    fn headers(pairs: &[(&str, &str)]) -> HashMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn returns_none_without_any_window_headers() {
+        let h = headers(&[("x-codex-plan-type", "pro")]);
+        assert!(parse_codex_quota_snapshot(&h, 200).is_none());
+        let empty = headers(&[]);
+        assert!(parse_codex_quota_snapshot(&empty, 200).is_none());
+    }
+
+    #[test]
+    fn parses_window_headers_and_plan_type() {
+        let h = headers(&[
+            ("x-codex-primary-used-percent", "25.5"),
+            ("x-codex-primary-window-minutes", "300"),
+            ("x-codex-secondary-used-percent", "80"),
+            ("x-codex-secondary-window-minutes", "10080"),
+            ("x-codex-plan-type", "  plus  "),
+            ("x-codex-active-limit", "5"),
+        ]);
+        let snapshot = parse_codex_quota_snapshot(&h, 200).expect("snapshot");
+        assert_eq!(snapshot.status, 200);
+        assert_eq!(snapshot.primary.used_percent, Some(25.5));
+        assert_eq!(snapshot.primary.window_minutes, Some(300));
+        assert_eq!(snapshot.secondary.used_percent, Some(80.0));
+        assert_eq!(snapshot.secondary.window_minutes, Some(10080));
+        assert_eq!(snapshot.plan_type.as_deref(), Some("plus"));
+        assert_eq!(snapshot.active_limit, Some(5));
+    }
+
+    #[test]
+    fn reset_after_seconds_wins_over_reset_at() {
+        let h = headers(&[
+            ("x-codex-primary-reset-after-seconds", "60"),
+            ("x-codex-primary-reset-at", "1000"),
+        ]);
+        let now = 1_000_000i64;
+        assert_eq!(
+            parse_reset_at_ms(&h, "x-codex-primary", Some(now)),
+            Some(now + 60_000)
+        );
+    }
+
+    #[test]
+    fn reset_at_seconds_vs_ms_heuristic() {
+        // Pure digits < 1e10 → epoch seconds (×1000).
+        let h = headers(&[("x-codex-primary-reset-at", "1753500000")]);
+        assert_eq!(
+            parse_reset_at_ms(&h, "x-codex-primary", Some(0)),
+            Some(1_753_500_000_000)
+        );
+        // Pure digits >= 1e10 → already ms.
+        let h = headers(&[("x-codex-primary-reset-at", "1753500000000")]);
+        assert_eq!(
+            parse_reset_at_ms(&h, "x-codex-primary", Some(0)),
+            Some(1_753_500_000_000)
+        );
+        // RFC date.
+        let h = headers(&[("x-codex-primary-reset-at", "2026-07-27T00:00:00Z")]);
+        let parsed = parse_reset_at_ms(&h, "x-codex-primary", Some(0)).expect("date");
+        let expected = chrono::DateTime::parse_from_rfc3339("2026-07-27T00:00:00Z")
+            .unwrap()
+            .timestamp_millis();
+        assert_eq!(parsed, expected);
+        // Garbage → None.
+        let h = headers(&[("x-codex-primary-reset-at", "not a date")]);
+        assert_eq!(parse_reset_at_ms(&h, "x-codex-primary", Some(0)), None);
+        // Zero / non-positive seconds fall through.
+        let h = headers(&[("x-codex-primary-reset-after-seconds", "0")]);
+        assert_eq!(parse_reset_at_ms(&h, "x-codex-primary", Some(0)), None);
+    }
+
+    #[test]
+    fn non_numeric_values_become_none() {
+        let h = headers(&[
+            ("x-codex-primary-used-percent", "abc"),
+            ("x-codex-primary-window-minutes", "12x"),
+        ]);
+        let snapshot = parse_codex_quota_snapshot(&h, 200).expect("snapshot");
+        assert_eq!(snapshot.primary.used_percent, None);
+        // parseInt takes leading digits ("12x" → 12).
+        assert_eq!(snapshot.primary.window_minutes, Some(12));
+    }
+
+    #[test]
+    fn format_line_contract_matches_quota_crate() {
+        let snapshot = ParsedCodexQuotaSnapshot {
+            status: 429,
+            plan_type: Some("plus".into()),
+            active_limit: Some(3),
+            primary: CodexQuotaWindow {
+                used_percent: Some(40.0),
+                window_minutes: Some(300),
+                reset_at_ms: None,
+            },
+            secondary: CodexQuotaWindow {
+                used_percent: Some(10.0),
+                window_minutes: Some(10080),
+                reset_at_ms: None,
+            },
+        }
+        .with_model("gpt-5.5");
+        let line = format_codex_quota_line(&snapshot);
+        assert_eq!(line, "5h 60% left, 7d 90% left, plan:plus, active:3, rate-limited");
+    }
+
+    #[test]
+    fn hostile_huge_reset_after_seconds_saturates_to_far_future() {
+        // Mirrors the quota-probe fix: i64 multiply must not wrap negative
+        // (release) or panic (overflow checks) — TS float math keeps a huge
+        // finite blocked-window resetAtMs.
+        let now = 1_753_500_000_000_i64;
+        let h = headers(&[("x-codex-primary-reset-after-seconds", "9300000000000000")]);
+        let parsed = parse_reset_at_ms(&h, "x-codex-primary", Some(now)).expect("resetAtMs");
+        assert!(parsed > now, "far-future, never wrapped: {parsed}");
+    }
+
+    #[test]
+    fn with_model_carries_all_fields() {
+        let parsed = ParsedCodexQuotaSnapshot {
+            status: 200,
+            plan_type: None,
+            active_limit: None,
+            primary: CodexQuotaWindow::default(),
+            secondary: CodexQuotaWindow::default(),
+        };
+        let snapshot = parsed.with_model("gpt-5.6-sol");
+        assert_eq!(snapshot.model, "gpt-5.6-sol");
+        assert_eq!(snapshot.status, 200);
+    }
+}
diff --git a/crates/runtime/src/quota_settings.rs b/crates/runtime/src/quota_settings.rs
new file mode 100644
index 000000000..eff6e702d
--- /dev/null
+++ b/crates/runtime/src/quota_settings.rs
@@ -0,0 +1,84 @@
+//! Port of `lib/runtime/quota-settings.ts` — pipes the four
+//! preemptive-quota config getters into a `configure` sink, plus the
+//! (misplaced-but-real, TS parity) `resolveUiRuntimeFromConfig`
+//! indirection (spec 10 §22, ARCHITECTURE §6.12).
+
+use cma_core::schemas::plugin_config::PluginConfig;
+
+/// The `configure(options)` payload (TS inline object type). The consumer
+/// bridges it into `cma_quota::preemptive_scheduler::QuotaSchedulerOptions`.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct PreemptiveQuotaSettings {
+    pub enabled: bool,
+    pub remaining_percent_threshold_primary: f64,
+    pub remaining_percent_threshold_secondary: f64,
+    pub max_deferral_ms: f64,
+}
+
+/// TS `applyPreemptiveQuotaSettingsFromConfig(pluginConfig, deps)` with the
+/// production getters (`cma-config`): `remainingPercent5h` → primary
+/// threshold, `remainingPercent7d` → secondary threshold.
+pub fn apply_preemptive_quota_settings_from_config(
+    plugin_config: &PluginConfig,
+    configure: impl FnOnce(PreemptiveQuotaSettings),
+) {
+    configure(PreemptiveQuotaSettings {
+        enabled: cma_config::getters::get_preemptive_quota_enabled(plugin_config),
+        remaining_percent_threshold_primary:
+            cma_config::getters::get_preemptive_quota_remaining_percent_5h(plugin_config),
+        remaining_percent_threshold_secondary:
+            cma_config::getters::get_preemptive_quota_remaining_percent_7d(plugin_config),
+        max_deferral_ms: cma_config::getters::get_preemptive_quota_max_deferral_ms(plugin_config),
+    });
+}
+
+/// TS `resolveUiRuntimeFromConfig(loadPluginConfig,
+/// applyUiRuntimeFromConfig)` — trivial load-then-apply indirection
+/// (lives here in the TS source; kept for parity).
+pub fn resolve_ui_runtime_from_config<TUi>(
+    load_plugin_config: impl FnOnce() -> PluginConfig,
+    apply_ui_runtime_from_config: impl FnOnce(&PluginConfig) -> TUi,
+) -> TUi {
+    apply_ui_runtime_from_config(&load_plugin_config())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pipes_the_four_getters_into_configure() {
+        let config = PluginConfig::default();
+        let mut captured: Option<PreemptiveQuotaSettings> = None;
+        apply_preemptive_quota_settings_from_config(&config, |settings| {
+            captured = Some(settings);
+        });
+        let settings = captured.expect("configure called exactly once");
+        // Values flow from the config getters (defaults on an empty config).
+        assert_eq!(
+            settings.enabled,
+            cma_config::getters::get_preemptive_quota_enabled(&config)
+        );
+        assert_eq!(
+            settings.remaining_percent_threshold_primary,
+            cma_config::getters::get_preemptive_quota_remaining_percent_5h(&config)
+        );
+        assert_eq!(
+            settings.remaining_percent_threshold_secondary,
+            cma_config::getters::get_preemptive_quota_remaining_percent_7d(&config)
+        );
+        assert_eq!(
+            settings.max_deferral_ms,
+            cma_config::getters::get_preemptive_quota_max_deferral_ms(&config)
+        );
+    }
+
+    #[test]
+    fn resolve_ui_runtime_loads_then_applies() {
+        let result = resolve_ui_runtime_from_config(
+            PluginConfig::default,
+            |_config| "applied",
+        );
+        assert_eq!(result, "applied");
+    }
+}
diff --git a/crates/runtime/src/recovery/constants.rs b/crates/runtime/src/recovery/constants.rs
new file mode 100644
index 000000000..1f5a8a3e0
--- /dev/null
+++ b/crates/runtime/src/recovery/constants.rs
@@ -0,0 +1,136 @@
+//! Port of `lib/recovery/constants.ts` — session-recovery storage paths and
+//! part-type classification sets (spec 11 §6.1).
+//!
+//! The host runtime's (opencode-style) session store lives under the XDG data
+//! directory, NOT the multi-auth dir. Gotcha 35: this module uses the raw
+//! home-directory / XDG resolution (`os.homedir()` in TS), not the
+//! runtime-paths home ladder — the two can disagree on Windows when
+//! `HOME != USERPROFILE`.
+//!
+//! Deviation from TS (recorded): the TS module computes `CODEX_STORAGE` once
+//! at module load; the Rust port re-resolves on every call so `EnvSandbox`
+//! tests can point the storage root at a tempdir. Production behavior is
+//! identical (the env does not change mid-process).
+
+use std::path::PathBuf;
+
+/// Part types that are "thinking" content (TS `THINKING_TYPES`).
+pub const THINKING_TYPES: [&str; 3] = ["thinking", "redacted_thinking", "reasoning"];
+
+/// Part types that are step meta markers (TS `META_TYPES`).
+pub const META_TYPES: [&str; 2] = ["step-start", "step-finish"];
+
+/// Part types that count as content (TS `CONTENT_TYPES` — exported but
+/// unused inside the cluster; kept for API parity).
+pub const CONTENT_TYPES: [&str; 4] = ["text", "tool", "tool_use", "tool_result"];
+
+/// True when `part_type` is one of [`THINKING_TYPES`].
+pub fn is_thinking_type(part_type: &str) -> bool {
+    THINKING_TYPES.contains(&part_type)
+}
+
+/// True when `part_type` is one of [`META_TYPES`].
+pub fn is_meta_type(part_type: &str) -> bool {
+    META_TYPES.contains(&part_type)
+}
+
+/// True when `part_type` is one of [`CONTENT_TYPES`].
+pub fn is_content_type(part_type: &str) -> bool {
+    CONTENT_TYPES.contains(&part_type)
+}
+
+/// Raw home directory (TS `os.homedir()`): deliberately NOT the
+/// runtime-paths resolution ladder (gotcha 35). The runtime crate has no
+/// `home` dependency, so this mirrors Node's env-first behavior directly
+/// (`USERPROFILE` / `HOMEDRIVE`+`HOMEPATH` on Windows, `HOME` elsewhere).
+fn raw_home_dir() -> PathBuf {
+    #[cfg(windows)]
+    {
+        if let Ok(profile) = std::env::var("USERPROFILE")
+            && !profile.is_empty()
+        {
+            return PathBuf::from(profile);
+        }
+        if let (Ok(drive), Ok(path)) = (std::env::var("HOMEDRIVE"), std::env::var("HOMEPATH"))
+            && !drive.is_empty()
+        {
+            return PathBuf::from(format!("{drive}{path}"));
+        }
+        PathBuf::from("")
+    }
+    #[cfg(not(windows))]
+    {
+        match std::env::var("HOME") {
+            Ok(home) if !home.is_empty() => PathBuf::from(home),
+            _ => PathBuf::from(""),
+        }
+    }
+}
+
+/// XDG-style data directory used for Codex storage (TS private `getXdgData`).
+///
+/// win32: `$APPDATA` or `<home>/AppData/Roaming`; other platforms:
+/// `$XDG_DATA_HOME` or `<home>/.local/share`.
+fn get_xdg_data() -> PathBuf {
+    #[cfg(windows)]
+    {
+        match std::env::var("APPDATA") {
+            Ok(value) if !value.is_empty() => PathBuf::from(value),
+            _ => raw_home_dir().join("AppData").join("Roaming"),
+        }
+    }
+    #[cfg(not(windows))]
+    {
+        match std::env::var("XDG_DATA_HOME") {
+            Ok(value) if !value.is_empty() => PathBuf::from(value),
+            _ => raw_home_dir().join(".local").join("share"),
+        }
+    }
+}
+
+/// TS `CODEX_STORAGE` — `<xdgData>/codex/storage`.
+pub fn codex_storage() -> PathBuf {
+    get_xdg_data().join("codex").join("storage")
+}
+
+/// TS `MESSAGE_STORAGE` — `<CODEX_STORAGE>/message`.
+pub fn message_storage() -> PathBuf {
+    codex_storage().join("message")
+}
+
+/// TS `PART_STORAGE` — `<CODEX_STORAGE>/part`.
+pub fn part_storage() -> PathBuf {
+    codex_storage().join("part")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn thinking_types_match_ts_set() {
+        assert!(is_thinking_type("thinking"));
+        assert!(is_thinking_type("redacted_thinking"));
+        assert!(is_thinking_type("reasoning"));
+        assert!(!is_thinking_type("text"));
+    }
+
+    #[test]
+    fn meta_and_content_types_match_ts_sets() {
+        assert!(is_meta_type("step-start"));
+        assert!(is_meta_type("step-finish"));
+        assert!(!is_meta_type("tool"));
+        for t in ["text", "tool", "tool_use", "tool_result"] {
+            assert!(is_content_type(t));
+        }
+        assert!(!is_content_type("thinking"));
+    }
+
+    #[test]
+    fn storage_paths_nest_under_codex_storage() {
+        let root = codex_storage();
+        assert_eq!(message_storage(), root.join("message"));
+        assert_eq!(part_storage(), root.join("part"));
+        assert!(root.ends_with(PathBuf::from("codex").join("storage")));
+    }
+}
diff --git a/crates/runtime/src/recovery/hashline.rs b/crates/runtime/src/recovery/hashline.rs
new file mode 100644
index 000000000..48ca64b47
--- /dev/null
+++ b/crates/runtime/src/recovery/hashline.rs
@@ -0,0 +1,872 @@
+//! Port of `lib/tools/hashline-tools.ts` — the PURE hashline edit engine
+//! (spec 11 §4, R2: library-only).
+//!
+//! The TS module also registers two host plugin tools
+//! (`createHashlineReadTool` / `createHashlineEditTool`); those wrap the pure
+//! engine with host permission prompts and file I/O and only make sense
+//! inside the JS host, so they are NOT ported (R2). Everything the tools
+//! compute — hashes, refs, window rendering, legacy + hashline edits,
+//! updated-ref blocks — lives here.
+//!
+//! Byte-exactness model (gotcha 26): hashes are the first 8 hex chars of
+//! sha1 over the LF-normalized line text; edits preserve the file's original
+//! CRLF/LF convention and trailing-newline state (mixed line endings collapse
+//! to CRLF if any CRLF is present); errors are returned as strings, never
+//! panics.
+
+use sha1::{Digest, Sha1};
+
+/// TS `DEFAULT_WINDOW_LINES`.
+pub const DEFAULT_WINDOW_LINES: i64 = 120;
+/// TS `MAX_WINDOW_LINES`.
+pub const MAX_WINDOW_LINES: i64 = 400;
+/// TS `LINE_PREVIEW_LIMIT` (clip >240 chars → 237 + `"..."`).
+pub const LINE_PREVIEW_LIMIT: usize = 240;
+
+/// TS `HashlineOperation`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum HashlineOperation {
+    Replace,
+    InsertBefore,
+    InsertAfter,
+    Delete,
+}
+
+impl HashlineOperation {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Replace => "replace",
+            Self::InsertBefore => "insert_before",
+            Self::InsertAfter => "insert_after",
+            Self::Delete => "delete",
+        }
+    }
+}
+
+/// TS `ParsedHashlineRef`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ParsedHashlineRef {
+    /// 1-based line number (regex `[1-9]\d*` — never 0).
+    pub line_number: usize,
+    /// Lowercased 8-hex hash.
+    pub hash: String,
+    /// The trimmed input as given.
+    pub raw: String,
+}
+
+/// Normalized file text (TS private `NormalizedFileText`).
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct NormalizedFileText {
+    lines: Vec<String>,
+    eol: &'static str,
+    had_trailing_newline: bool,
+}
+
+/// TS `HashlineEditSuccess` (the `ok: true` arm).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct HashlineEditSuccess {
+    pub updated_content: String,
+    pub operation: HashlineOperation,
+    /// 1-based changed range for updated-ref rendering.
+    pub changed_start_line: usize,
+    pub changed_end_line: usize,
+}
+
+/// TS `LegacyEditSuccess` (the `ok: true` arm).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct LegacyEditSuccess {
+    pub updated_content: String,
+    pub replacements: usize,
+}
+
+/// TS `HashlineEditArgs`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct HashlineEditArgs {
+    pub line_ref: Option<String>,
+    pub end_line_ref: Option<String>,
+    pub operation: Option<String>,
+    pub content: Option<String>,
+    pub new_string: Option<String>,
+}
+
+/// TS `LegacyEditArgs`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct LegacyEditArgs {
+    pub old_string: Option<String>,
+    pub new_string: Option<String>,
+    pub replace_all: bool,
+}
+
+// =============================================================================
+// Text normalization
+// =============================================================================
+
+fn normalize_file_text(content: &str) -> NormalizedFileText {
+    let normalized = content.replace("\r\n", "\n");
+    let eol = if content.contains("\r\n") { "\r\n" } else { "\n" };
+    if normalized.is_empty() {
+        return NormalizedFileText {
+            lines: Vec::new(),
+            eol,
+            had_trailing_newline: false,
+        };
+    }
+
+    let had_trailing_newline = normalized.ends_with('\n');
+    let mut lines: Vec<String> = normalized.split('\n').map(str::to_string).collect();
+    if had_trailing_newline {
+        lines.pop();
+    }
+
+    NormalizedFileText {
+        lines,
+        eol,
+        had_trailing_newline,
+    }
+}
+
+fn denormalize_file_text(value: &NormalizedFileText) -> String {
+    if value.lines.is_empty() {
+        return String::new();
+    }
+    let joined = value.lines.join(value.eol);
+    if value.had_trailing_newline {
+        format!("{joined}{}", value.eol)
+    } else {
+        joined
+    }
+}
+
+fn split_insert_text(value: &str) -> Vec<String> {
+    let normalized = value.replace("\r\n", "\n");
+    if normalized.is_empty() {
+        return Vec::new();
+    }
+    let trailing = normalized.ends_with('\n');
+    let mut lines: Vec<String> = normalized.split('\n').map(str::to_string).collect();
+    if trailing {
+        lines.pop();
+    }
+    lines
+}
+
+/// Clip a line for previews (TS `clipLine` — chars, JS UTF-16 semantics
+/// approximated with Unicode scalar values).
+fn clip_line(text: &str) -> String {
+    let count = text.chars().count();
+    if count <= LINE_PREVIEW_LIMIT {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(LINE_PREVIEW_LIMIT - 3).collect();
+    format!("{head}...")
+}
+
+// =============================================================================
+// Legacy placeholder detection
+// =============================================================================
+
+fn is_word_char(c: char) -> bool {
+    c.is_ascii_alphanumeric() || c == '_'
+}
+
+fn is_placeholder_class_char(c: char) -> bool {
+    c.is_ascii_uppercase() || c.is_ascii_digit() || c == '_'
+}
+
+/// Word-boundary token search inside a placeholder body (hand-rolled
+/// equivalent of `\b(?:TARGET_[A-Z0-9_]*|ORIGINAL_LINES|SNIPPET|START_LINE|END_LINE)\b`).
+fn contains_placeholder_token(inner: &str) -> bool {
+    let chars: Vec<char> = inner.chars().collect();
+    let candidates: [&str; 4] = ["ORIGINAL_LINES", "SNIPPET", "START_LINE", "END_LINE"];
+
+    for start in 0..chars.len() {
+        // \b before the token.
+        if start > 0 && is_word_char(chars[start - 1]) {
+            continue;
+        }
+        let rest: String = chars[start..].iter().collect();
+
+        // TARGET_[A-Z0-9_]* with \b after the maximal class run.
+        if rest.starts_with("TARGET_") {
+            let mut end = start + "TARGET_".len();
+            while end < chars.len() && is_placeholder_class_char(chars[end]) {
+                end += 1;
+            }
+            if end >= chars.len() || !is_word_char(chars[end]) {
+                return true;
+            }
+        }
+
+        for token in candidates {
+            if rest.starts_with(token) {
+                let end = start + token.chars().count();
+                if end >= chars.len() || !is_word_char(chars[end]) {
+                    return true;
+                }
+            }
+        }
+    }
+    false
+}
+
+/// TS `findUnresolvedLegacyPlaceholder` — the full `${...}` match, if any.
+fn find_unresolved_legacy_placeholder(value: &str) -> Option<String> {
+    let bytes: Vec<char> = value.chars().collect();
+    let mut i = 0usize;
+    while i + 1 < bytes.len() {
+        if bytes[i] == '$' && bytes[i + 1] == '{' {
+            // Regex `[^}]*\}`: the body runs to the next `}`.
+            if let Some(close_offset) = bytes[i + 2..].iter().position(|&c| c == '}') {
+                let inner: String = bytes[i + 2..i + 2 + close_offset].iter().collect();
+                if contains_placeholder_token(&inner) {
+                    let full: String = bytes[i..=i + 2 + close_offset].iter().collect();
+                    return Some(full);
+                }
+            }
+        }
+        i += 1;
+    }
+    None
+}
+
+// =============================================================================
+// Pure exports
+// =============================================================================
+
+/// TS `computeHashline(text)` — first 8 hex chars of sha1(utf8 text).
+pub fn compute_hashline(text: &str) -> String {
+    let mut hasher = Sha1::new();
+    hasher.update(text.as_bytes());
+    let digest = hasher.finalize();
+    let hex: String = digest.iter().map(|b| format!("{b:02x}")).collect();
+    hex[..8].to_string()
+}
+
+/// TS `formatHashlineRef(lineNumber, text)` — `L{n}#{hash}`.
+pub fn format_hashline_ref(line_number: usize, text: &str) -> String {
+    format!("L{line_number}#{}", compute_hashline(text))
+}
+
+/// TS `parseHashlineRef(value)` — `/^L([1-9]\d*)#([a-f0-9]{8})$/i`.
+pub fn parse_hashline_ref(value: &str) -> Option<ParsedHashlineRef> {
+    let raw = value.trim();
+    let mut chars = raw.chars();
+    match chars.next() {
+        Some('L') | Some('l') => {}
+        _ => return None,
+    }
+    let rest: &str = chars.as_str();
+    let hash_sep = rest.find('#')?;
+    let digits = &rest[..hash_sep];
+    let hash_part = &rest[hash_sep + 1..];
+
+    if digits.is_empty() || !digits.starts_with(|c: char| ('1'..='9').contains(&c)) {
+        return None;
+    }
+    if !digits.chars().all(|c| c.is_ascii_digit()) {
+        return None;
+    }
+    if hash_part.chars().count() != 8 || !hash_part.chars().all(|c| c.is_ascii_hexdigit()) {
+        return None;
+    }
+
+    // JS parseInt tolerates arbitrarily large values (as floats); a line
+    // number that overflows usize could never be in range anyway, so the
+    // Rust port treats overflow as unparseable (recorded deviation).
+    let line_number: usize = digits.parse().ok()?;
+    if line_number < 1 {
+        return None;
+    }
+
+    Some(ParsedHashlineRef {
+        line_number,
+        hash: hash_part.to_lowercase(),
+        raw: raw.to_string(),
+    })
+}
+
+/// TS `renderHashlineSlice(content, startLine = 1, maxLines = 120)`.
+pub fn render_hashline_slice(content: &str, start_line: i64, max_lines: i64) -> String {
+    let normalized = normalize_file_text(content);
+    if normalized.lines.is_empty() {
+        return "File is empty.".to_string();
+    }
+
+    let total = normalized.lines.len();
+    let safe_start_line = start_line.max(1) as usize;
+    let safe_max_lines = max_lines.clamp(1, MAX_WINDOW_LINES) as usize;
+    let start_index = (total - 1).min(safe_start_line - 1);
+    let end_index = (total - 1).min(start_index + safe_max_lines - 1);
+
+    let mut lines: Vec<String> = vec![
+        format!(
+            "Hashline window {}-{} of {}:",
+            start_index + 1,
+            end_index + 1,
+            total
+        ),
+        String::new(),
+    ];
+
+    for index in start_index..=end_index {
+        let line_text = &normalized.lines[index];
+        lines.push(format!(
+            "{} | {}",
+            format_hashline_ref(index + 1, line_text),
+            clip_line(line_text)
+        ));
+    }
+
+    if end_index < total - 1 {
+        lines.push(String::new());
+        lines.push(format!("... {} more line(s).", total - end_index - 1));
+    }
+
+    lines.join("\n")
+}
+
+/// TS `applyLegacyEdit(content, args)`.
+pub fn apply_legacy_edit(content: &str, args: &LegacyEditArgs) -> Result<LegacyEditSuccess, String> {
+    let Some(old_string) = args.old_string.as_deref().filter(|s| !s.is_empty()) else {
+        return Err(
+            "Legacy edit requires non-empty oldString. For hashline mode, use lineRef."
+                .to_string(),
+        );
+    };
+
+    if let Some(placeholder) = find_unresolved_legacy_placeholder(old_string) {
+        return Err(format!(
+            "oldString contains unresolved template placeholder {placeholder}. \
+Use literal file text for oldString, or prefer hashline_read + lineRef/endLineRef."
+        ));
+    }
+
+    let new_string = args.new_string.as_deref().unwrap_or("");
+    if args.replace_all {
+        let parts: Vec<&str> = content.split(old_string).collect();
+        let replacements = parts.len() - 1;
+        if replacements == 0 {
+            return Err("oldString not found.".to_string());
+        }
+        return Ok(LegacyEditSuccess {
+            updated_content: parts.join(new_string),
+            replacements,
+        });
+    }
+
+    let Some(first_index) = content.find(old_string) else {
+        return Err("oldString not found.".to_string());
+    };
+
+    if content[first_index + old_string.len()..].contains(old_string) {
+        return Err(
+            "oldString appears multiple times. Use replaceAll=true or hashline mode.".to_string(),
+        );
+    }
+
+    let updated_content = format!(
+        "{}{}{}",
+        &content[..first_index],
+        new_string,
+        &content[first_index + old_string.len()..]
+    );
+    Ok(LegacyEditSuccess {
+        updated_content,
+        replacements: 1,
+    })
+}
+
+fn parse_operation(value: Option<&str>) -> Option<HashlineOperation> {
+    let normalized = value.unwrap_or("replace").trim().to_lowercase();
+    match normalized.as_str() {
+        "replace" => Some(HashlineOperation::Replace),
+        "insert_before" => Some(HashlineOperation::InsertBefore),
+        "insert_after" => Some(HashlineOperation::InsertAfter),
+        "delete" => Some(HashlineOperation::Delete),
+        _ => None,
+    }
+}
+
+/// TS private `resolveHashlineRef` — 0-based index or the exact error text.
+fn resolve_hashline_ref(
+    lines: &[String],
+    r: &ParsedHashlineRef,
+    label: &str,
+) -> Result<usize, String> {
+    if r.line_number > lines.len() {
+        return Err(format!(
+            "{label} is out of range ({}). File has {} line(s).",
+            r.raw,
+            lines.len()
+        ));
+    }
+    let index = r.line_number - 1;
+    let line = &lines[index];
+    let current_hash = compute_hashline(line);
+    if current_hash != r.hash {
+        return Err(format!(
+            "{label} hash mismatch at line {}. Expected {}, found {current_hash}. Current ref: {}",
+            r.line_number,
+            r.hash,
+            format_hashline_ref(r.line_number, line)
+        ));
+    }
+    Ok(index)
+}
+
+/// TS `applyHashlineEdit(content, args)`.
+pub fn apply_hashline_edit(
+    content: &str,
+    args: &HashlineEditArgs,
+) -> Result<HashlineEditSuccess, String> {
+    let Some(line_ref_raw) = args.line_ref.as_deref() else {
+        return Err("lineRef is required for hashline edit mode.".to_string());
+    };
+
+    let Some(line_ref) = parse_hashline_ref(line_ref_raw) else {
+        return Err(format!(
+            "Invalid lineRef format: {line_ref_raw}. Expected L<line>#<hash>."
+        ));
+    };
+
+    let end_line_ref = match args.end_line_ref.as_deref() {
+        Some(raw) => match parse_hashline_ref(raw) {
+            Some(parsed) => parsed,
+            None => {
+                return Err(format!(
+                    "Invalid endLineRef format: {raw}. Expected L<line>#<hash>."
+                ));
+            }
+        },
+        None => line_ref.clone(),
+    };
+
+    if end_line_ref.line_number < line_ref.line_number {
+        return Err("endLineRef must be on or after lineRef.".to_string());
+    }
+
+    let Some(operation) = parse_operation(args.operation.as_deref()) else {
+        return Err(
+            "Invalid operation. Use one of: replace, insert_before, insert_after, delete."
+                .to_string(),
+        );
+    };
+
+    let normalized = normalize_file_text(content);
+    let mut lines = normalized.lines.clone();
+
+    let start_index = resolve_hashline_ref(&lines, &line_ref, "lineRef")?;
+    let end_index = resolve_hashline_ref(&lines, &end_line_ref, "endLineRef")?;
+
+    let range_length = end_index - start_index + 1;
+    let next_text = args
+        .content
+        .as_deref()
+        .or(args.new_string.as_deref())
+        .unwrap_or("");
+    let insert_lines = split_insert_text(next_text);
+
+    if matches!(
+        operation,
+        HashlineOperation::InsertBefore | HashlineOperation::InsertAfter
+    ) && insert_lines.is_empty()
+    {
+        return Err(format!("content is required for {}.", operation.as_str()));
+    }
+
+    let changed_start_line: usize;
+    let changed_end_line: usize;
+
+    match operation {
+        HashlineOperation::Replace => {
+            lines.splice(start_index..start_index + range_length, insert_lines.clone());
+            changed_start_line = line_ref.line_number;
+            changed_end_line = if !insert_lines.is_empty() {
+                line_ref.line_number + insert_lines.len() - 1
+            } else {
+                1.max(line_ref.line_number.saturating_sub(1))
+            };
+        }
+        HashlineOperation::Delete => {
+            lines.splice(start_index..start_index + range_length, Vec::new());
+            changed_start_line = 1.max(line_ref.line_number.saturating_sub(1));
+            changed_end_line = changed_start_line;
+        }
+        HashlineOperation::InsertBefore => {
+            lines.splice(start_index..start_index, insert_lines.clone());
+            changed_start_line = line_ref.line_number;
+            changed_end_line = line_ref.line_number + insert_lines.len() - 1;
+        }
+        HashlineOperation::InsertAfter => {
+            lines.splice(start_index + 1..start_index + 1, insert_lines.clone());
+            changed_start_line = line_ref.line_number + 1;
+            changed_end_line = line_ref.line_number + insert_lines.len();
+        }
+    }
+
+    let updated_content = denormalize_file_text(&NormalizedFileText {
+        had_trailing_newline: if lines.is_empty() {
+            false
+        } else {
+            normalized.had_trailing_newline
+        },
+        lines,
+        eol: normalized.eol,
+    });
+
+    Ok(HashlineEditSuccess {
+        updated_content,
+        operation,
+        changed_start_line,
+        changed_end_line,
+    })
+}
+
+/// TS private `buildUpdatedRefs` — `"{ref} | {clipped}"` lines for the
+/// changed range, clamped into the updated content. Public in Rust so a
+/// future host-tool layer can reproduce the edit-tool output verbatim.
+pub fn build_updated_refs(content: &str, start_line: usize, end_line: usize) -> Vec<String> {
+    let normalized = normalize_file_text(content);
+    if normalized.lines.is_empty() {
+        return Vec::new();
+    }
+    let total = normalized.lines.len();
+    let safe_start = start_line.clamp(1, total);
+    let safe_end = safe_start.max(end_line.min(total));
+
+    let mut refs = Vec::new();
+    for line_number in safe_start..=safe_end {
+        let line = &normalized.lines[line_number - 1];
+        refs.push(format!(
+            "{} | {}",
+            format_hashline_ref(line_number, line),
+            clip_line(line)
+        ));
+    }
+    refs
+}
+
+// =============================================================================
+// Tests — ported from test/hashline-tools.test.ts (pure-engine cases)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn computes_stable_8_char_hashes() {
+        let hash_a = compute_hashline("alpha");
+        let hash_b = compute_hashline("alpha");
+        let hash_c = compute_hashline("beta");
+        assert_eq!(hash_a.len(), 8);
+        assert_eq!(hash_a, hash_b);
+        assert_ne!(hash_a, hash_c);
+    }
+
+    #[test]
+    fn formats_and_parses_hashline_refs() {
+        let r = format_hashline_ref(7, "example line");
+        let parsed = parse_hashline_ref(&r).expect("parses");
+        assert_eq!(parsed.line_number, 7);
+        assert_eq!(parsed.hash, compute_hashline("example line"));
+    }
+
+    #[test]
+    fn rejects_malformed_refs() {
+        assert!(parse_hashline_ref("7#abcdef12").is_none());
+        assert!(parse_hashline_ref("L0#abcdef12").is_none());
+        assert!(parse_hashline_ref("L2#xyz").is_none());
+        // Case-insensitive hash + leading 'l' accepted; hash lowercased.
+        let parsed = parse_hashline_ref(" l3#ABCDEF12 ").expect("parses");
+        assert_eq!(parsed.line_number, 3);
+        assert_eq!(parsed.hash, "abcdef12");
+        assert_eq!(parsed.raw, "l3#ABCDEF12");
+    }
+
+    #[test]
+    fn renders_hashline_slices_with_refs() {
+        let content = "alpha\nbeta\ngamma\n";
+        let rendered = render_hashline_slice(content, 2, 2);
+        assert!(rendered.contains("Hashline window 2-3 of 3"));
+        assert!(rendered.contains(&format!("{} | beta", format_hashline_ref(2, "beta"))));
+        assert!(rendered.contains(&format!("{} | gamma", format_hashline_ref(3, "gamma"))));
+        assert_eq!(render_hashline_slice("", 1, 10), "File is empty.");
+
+        // Truncation trailer.
+        let long = "a\nb\nc\nd\n";
+        let rendered = render_hashline_slice(long, 1, 2);
+        assert!(rendered.ends_with("... 2 more line(s)."));
+    }
+
+    #[test]
+    fn applies_legacy_edit_replacement() {
+        let result = apply_legacy_edit(
+            "one two one",
+            &LegacyEditArgs {
+                old_string: Some("one".into()),
+                new_string: Some("ONE".into()),
+                replace_all: true,
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "ONE two ONE");
+        assert_eq!(result.replacements, 2);
+    }
+
+    #[test]
+    fn rejects_ambiguous_legacy_edits_without_replace_all() {
+        let err = apply_legacy_edit(
+            "one two one",
+            &LegacyEditArgs {
+                old_string: Some("one".into()),
+                new_string: Some("ONE".into()),
+                replace_all: false,
+            },
+        )
+        .unwrap_err();
+        assert!(err.contains("multiple"));
+    }
+
+    #[test]
+    fn legacy_edit_error_strings_are_exact() {
+        let err = apply_legacy_edit("x", &LegacyEditArgs::default()).unwrap_err();
+        assert_eq!(
+            err,
+            "Legacy edit requires non-empty oldString. For hashline mode, use lineRef."
+        );
+        let err = apply_legacy_edit(
+            "x",
+            &LegacyEditArgs {
+                old_string: Some("missing".into()),
+                ..LegacyEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(err, "oldString not found.");
+    }
+
+    #[test]
+    fn rejects_unresolved_template_placeholders() {
+        let err = apply_legacy_edit(
+            "alpha\nbeta\n",
+            &LegacyEditArgs {
+                old_string: Some("${TARGET_SNIPPET}".into()),
+                new_string: Some("beta".into()),
+                replace_all: false,
+            },
+        )
+        .unwrap_err();
+        assert!(err.contains("unresolved template placeholder"));
+        assert!(err.contains("hashline_read"));
+        assert!(err.contains("${TARGET_SNIPPET}"));
+    }
+
+    #[test]
+    fn allows_normal_template_literal_fragments() {
+        let result = apply_legacy_edit(
+            "const message = `hello ${name}`;\n",
+            &LegacyEditArgs {
+                old_string: Some("${name}".into()),
+                new_string: Some("${userName}".into()),
+                replace_all: false,
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "const message = `hello ${userName}`;\n");
+        assert_eq!(result.replacements, 1);
+    }
+
+    #[test]
+    fn applies_hashline_replace_with_hash_verification() {
+        let content = "alpha\nbeta\ngamma\n";
+        let line_ref = format_hashline_ref(2, "beta");
+        let result = apply_hashline_edit(
+            content,
+            &HashlineEditArgs {
+                line_ref: Some(line_ref),
+                operation: Some("replace".into()),
+                content: Some("BETA".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "alpha\nBETA\ngamma\n");
+        assert_eq!(result.operation, HashlineOperation::Replace);
+        assert_eq!((result.changed_start_line, result.changed_end_line), (2, 2));
+    }
+
+    #[test]
+    fn rejects_hash_mismatch() {
+        let err = apply_hashline_edit(
+            "alpha\nbeta\ngamma\n",
+            &HashlineEditArgs {
+                line_ref: Some("L2#00000000".into()),
+                operation: Some("replace".into()),
+                content: Some("BETA".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert!(err.contains("hash mismatch"));
+        assert!(err.contains("Current ref:"));
+    }
+
+    #[test]
+    fn hashline_validation_error_strings_are_exact() {
+        let err = apply_hashline_edit("x\n", &HashlineEditArgs::default()).unwrap_err();
+        assert_eq!(err, "lineRef is required for hashline edit mode.");
+
+        let err = apply_hashline_edit(
+            "x\n",
+            &HashlineEditArgs {
+                line_ref: Some("nope".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(err, "Invalid lineRef format: nope. Expected L<line>#<hash>.");
+
+        let err = apply_hashline_edit(
+            "a\nb\n",
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(2, "b")),
+                end_line_ref: Some(format_hashline_ref(1, "a")),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(err, "endLineRef must be on or after lineRef.");
+
+        let err = apply_hashline_edit(
+            "a\n",
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "a")),
+                operation: Some("smash".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(
+            err,
+            "Invalid operation. Use one of: replace, insert_before, insert_after, delete."
+        );
+
+        let err = apply_hashline_edit(
+            "a\n",
+            &HashlineEditArgs {
+                line_ref: Some("L5#abcdef01".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(err, "lineRef is out of range (L5#abcdef01). File has 1 line(s).");
+
+        let err = apply_hashline_edit(
+            "a\n",
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "a")),
+                operation: Some("insert_before".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .unwrap_err();
+        assert_eq!(err, "content is required for insert_before.");
+    }
+
+    #[test]
+    fn insert_delete_and_range_semantics() {
+        let content = "a\nb\nc\n";
+        // insert_after
+        let result = apply_hashline_edit(
+            content,
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "a")),
+                operation: Some("insert_after".into()),
+                content: Some("x\ny".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "a\nx\ny\nb\nc\n");
+        assert_eq!((result.changed_start_line, result.changed_end_line), (2, 3));
+
+        // insert_before
+        let result = apply_hashline_edit(
+            content,
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(2, "b")),
+                operation: Some("insert_before".into()),
+                content: Some("x".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "a\nx\nb\nc\n");
+        assert_eq!((result.changed_start_line, result.changed_end_line), (2, 2));
+
+        // delete range
+        let result = apply_hashline_edit(
+            content,
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "a")),
+                end_line_ref: Some(format_hashline_ref(2, "b")),
+                operation: Some("delete".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "c\n");
+        assert_eq!((result.changed_start_line, result.changed_end_line), (1, 1));
+
+        // delete everything → no trailing newline flag left.
+        let result = apply_hashline_edit(
+            "only\n",
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "only")),
+                operation: Some("delete".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "");
+    }
+
+    #[test]
+    fn preserves_crlf_and_trailing_newline_state() {
+        let content = "a\r\nb\r\nc";
+        let result = apply_hashline_edit(
+            content,
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(2, "b")),
+                operation: Some("replace".into()),
+                content: Some("B".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "a\r\nB\r\nc");
+
+        // newString works as the replacement body too.
+        let result = apply_hashline_edit(
+            "a\nb\n",
+            &HashlineEditArgs {
+                line_ref: Some(format_hashline_ref(1, "a")),
+                new_string: Some("A".into()),
+                operation: Some("replace".into()),
+                ..HashlineEditArgs::default()
+            },
+        )
+        .expect("ok");
+        assert_eq!(result.updated_content, "A\nb\n");
+    }
+
+    #[test]
+    fn build_updated_refs_clamps_range() {
+        let refs = build_updated_refs("a\nb\nc\n", 2, 9);
+        assert_eq!(refs.len(), 2);
+        assert!(refs[0].starts_with(&format_hashline_ref(2, "b")));
+        assert!(refs[1].starts_with(&format_hashline_ref(3, "c")));
+        assert!(build_updated_refs("", 1, 1).is_empty());
+    }
+}
diff --git a/crates/runtime/src/recovery/hook.rs b/crates/runtime/src/recovery/hook.rs
new file mode 100644
index 000000000..fb5cffe88
--- /dev/null
+++ b/crates/runtime/src/recovery/hook.rs
@@ -0,0 +1,831 @@
+//! Port of `lib/recovery.ts` (+ `lib/runtime/session-recovery.ts`) — the
+//! session-recovery hook: 3-error-class detection, repair dispatch, toasts
+//! (spec 11 §6.4).
+//!
+//! R2: library-only. The TS hook talks to the JS host's plugin client; the
+//! Rust port abstracts that behind [`SessionRecoveryClient`] and is not wired
+//! to any CLI/proxy surface.
+//!
+//! Frozen strings (spec 11 gotchas 32–33): the `"preceeding"` typo matches
+//! the upstream API's misspelled error text; the injected tool-result content
+//! is exactly `"Operation cancelled by user (ESC pressed)"`; the resume text
+//! is `"[session recovered - continuing previous task]"`.
+
+use std::collections::HashSet;
+use std::sync::Mutex;
+
+use cma_core::errors::CodexError;
+use serde_json::Value;
+
+use super::storage::{
+    find_message_by_index_needing_thinking, find_messages_with_orphan_thinking,
+    find_messages_with_thinking_blocks, prepend_thinking_part, read_parts, strip_thinking_parts,
+};
+use super::types::{
+    MessageData, MessageInfo, MessagePart, ModelRef, RecoveryErrorType, ResumeConfig,
+    ToolResultPart,
+};
+
+/// TS `RECOVERY_RESUME_TEXT`.
+pub const RECOVERY_RESUME_TEXT: &str = "[session recovered - continuing previous task]";
+
+/// The exact tool-result content injected for cancelled tools (gotcha 33).
+pub const TOOL_CANCELLED_CONTENT: &str = "Operation cancelled by user (ESC pressed)";
+
+// =============================================================================
+// Error classification (pure)
+// =============================================================================
+
+/// JS falsiness over a JSON value (`!error`).
+fn js_falsy(value: &Value) -> bool {
+    match value {
+        Value::Null => true,
+        Value::Bool(b) => !b,
+        Value::Number(n) => n.as_f64().is_none_or(|v| v == 0.0 || v.is_nan()),
+        Value::String(s) => s.is_empty(),
+        _ => false,
+    }
+}
+
+fn object_message(value: &Value) -> Option<String> {
+    let msg = value.as_object()?.get("message")?.as_str()?;
+    if msg.is_empty() {
+        return None;
+    }
+    Some(msg.to_lowercase())
+}
+
+/// TS private `getErrorMessage(error)` — lowercased message text probed from
+/// `error.data`, `error.error`, `error` itself, then `error.data.error`;
+/// falls back to the JSON serialization.
+fn get_error_message(error: &Value) -> String {
+    if js_falsy(error) {
+        return String::new();
+    }
+    if let Value::String(s) = error {
+        return s.to_lowercase();
+    }
+
+    let paths = [
+        error.get("data"),
+        error.get("error"),
+        Some(error),
+        error.get("data").and_then(|d| d.get("error")),
+    ];
+    for candidate in paths.into_iter().flatten() {
+        if let Some(message) = object_message(candidate) {
+            return message;
+        }
+    }
+
+    serde_json::to_string(error)
+        .map(|s| s.to_lowercase())
+        .unwrap_or_default()
+}
+
+/// TS private `extractMessageIndex(error)` — first `/messages\.(\d+)/` match.
+fn extract_message_index(error: &Value) -> Option<i64> {
+    let message = get_error_message(error);
+    let bytes = message.as_bytes();
+    let needle = b"messages.";
+    let mut start = 0usize;
+    while let Some(pos) = find_subslice(&bytes[start..], needle) {
+        let digits_start = start + pos + needle.len();
+        let digits: String = message[digits_start..]
+            .chars()
+            .take_while(|c| c.is_ascii_digit())
+            .collect();
+        if !digits.is_empty() {
+            return digits.parse::<i64>().ok();
+        }
+        start += pos + needle.len();
+    }
+    None
+}
+
+fn find_subslice(haystack: &[u8], needle: &[u8]) -> Option<usize> {
+    haystack
+        .windows(needle.len())
+        .position(|window| window == needle)
+}
+
+/// TS `detectErrorType(error)`.
+pub fn detect_error_type(error: &Value) -> Option<RecoveryErrorType> {
+    let message = get_error_message(error);
+
+    if message.contains("tool_use") && message.contains("tool_result") {
+        return Some(RecoveryErrorType::ToolResultMissing);
+    }
+
+    if message.contains("thinking")
+        && (message.contains("first block")
+            || message.contains("must start with")
+            || message.contains("preceeding")
+            || (message.contains("expected") && message.contains("found")))
+    {
+        return Some(RecoveryErrorType::ThinkingBlockOrder);
+    }
+
+    if message.contains("thinking is disabled") && message.contains("cannot contain") {
+        return Some(RecoveryErrorType::ThinkingDisabledViolation);
+    }
+
+    None
+}
+
+/// TS `isRecoverableError(error)`.
+pub fn is_recoverable_error(error: &Value) -> bool {
+    detect_error_type(error).is_some()
+}
+
+// =============================================================================
+// Toast content (pure)
+// =============================================================================
+
+/// `{title, message}` pair for toasts.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ToastContent {
+    pub title: String,
+    pub message: String,
+}
+
+/// TS `getRecoveryToastContent(errorType)`.
+pub fn get_recovery_toast_content(error_type: Option<RecoveryErrorType>) -> ToastContent {
+    let (title, message) = match error_type {
+        None => ("Session Recovery", "Attempting to recover session..."),
+        Some(RecoveryErrorType::ToolResultMissing) => {
+            ("Tool Crash Recovery", "Injecting cancelled tool results...")
+        }
+        Some(RecoveryErrorType::ThinkingBlockOrder) => {
+            ("Thinking Block Recovery", "Fixing message structure...")
+        }
+        Some(RecoveryErrorType::ThinkingDisabledViolation) => {
+            ("Thinking Strip Recovery", "Stripping thinking blocks...")
+        }
+    };
+    ToastContent {
+        title: title.to_string(),
+        message: message.to_string(),
+    }
+}
+
+/// TS `getRecoverySuccessToast()`.
+pub fn get_recovery_success_toast() -> ToastContent {
+    ToastContent {
+        title: "Session Recovered".to_string(),
+        message: "Continuing where you left off...".to_string(),
+    }
+}
+
+/// TS `getRecoveryFailureToast()`.
+pub fn get_recovery_failure_toast() -> ToastContent {
+    ToastContent {
+        title: "Recovery Failed".to_string(),
+        message: "Please retry or start a new session.".to_string(),
+    }
+}
+
+// =============================================================================
+// Client abstraction (the TS PluginClient surface used by the hook)
+// =============================================================================
+
+/// Prompt body for `session.prompt`.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct PromptBody {
+    pub parts: Vec<Value>,
+    pub agent: Option<String>,
+    pub model: Option<ModelRef>,
+}
+
+/// The host-client surface the recovery hook needs (TS `PluginInput["client"]`).
+#[allow(async_fn_in_trait)]
+pub trait SessionRecoveryClient {
+    async fn session_abort(&self, session_id: &str) -> Result<(), CodexError>;
+    async fn session_messages(
+        &self,
+        session_id: &str,
+        directory: &str,
+    ) -> Result<Vec<MessageData>, CodexError>;
+    /// `directory` is `Some` only for calls that pass `query: {directory}`
+    /// (the auto-resume path); tool-result injection passes `None`.
+    async fn session_prompt(
+        &self,
+        session_id: &str,
+        body: PromptBody,
+        directory: Option<&str>,
+    ) -> Result<(), CodexError>;
+    async fn show_toast(
+        &self,
+        title: &str,
+        message: &str,
+        variant: &str,
+    ) -> Result<(), CodexError>;
+}
+
+// =============================================================================
+// The hook
+// =============================================================================
+
+type SessionCallback = Box<dyn Fn(&str) + Send + Sync>;
+
+/// TS `SessionRecoveryHook` (created by [`create_session_recovery_hook`]).
+pub struct SessionRecoveryHook<C> {
+    client: C,
+    directory: String,
+    auto_resume: bool,
+    processing_errors: Mutex<HashSet<String>>,
+    on_abort: Mutex<Option<SessionCallback>>,
+    on_recovery_complete: Mutex<Option<SessionCallback>>,
+}
+
+/// Config slice the hook needs (TS reads `config.sessionRecovery` /
+/// `config.autoResume`; plugin defaults are `true` for both).
+#[derive(Clone, Copy, Debug)]
+pub struct SessionRecoveryConfig {
+    pub session_recovery: bool,
+    pub auto_resume: bool,
+}
+
+impl Default for SessionRecoveryConfig {
+    fn default() -> Self {
+        Self {
+            session_recovery: true,
+            auto_resume: true,
+        }
+    }
+}
+
+/// TS `createSessionRecoveryHook(ctx, config)` — `None` when
+/// `config.sessionRecovery` is falsy.
+pub fn create_session_recovery_hook<C: SessionRecoveryClient>(
+    client: C,
+    directory: impl Into<String>,
+    config: SessionRecoveryConfig,
+) -> Option<SessionRecoveryHook<C>> {
+    if !config.session_recovery {
+        return None;
+    }
+    Some(SessionRecoveryHook {
+        client,
+        directory: directory.into(),
+        auto_resume: config.auto_resume,
+        processing_errors: Mutex::new(HashSet::new()),
+        on_abort: Mutex::new(None),
+        on_recovery_complete: Mutex::new(None),
+    })
+}
+
+/// TS `createRuntimeSessionRecoveryHook({enabled, client, directory,
+/// autoResume})` — `None` unless enabled.
+pub fn create_runtime_session_recovery_hook<C: SessionRecoveryClient>(
+    enabled: bool,
+    auto_resume: bool,
+    client: C,
+    directory: impl Into<String>,
+) -> Option<SessionRecoveryHook<C>> {
+    if !enabled {
+        return None;
+    }
+    create_session_recovery_hook(
+        client,
+        directory,
+        SessionRecoveryConfig {
+            session_recovery: true,
+            auto_resume,
+        },
+    )
+}
+
+impl<C: SessionRecoveryClient> SessionRecoveryHook<C> {
+    /// TS `hook.isRecoverableError`.
+    pub fn is_recoverable_error(&self, error: &Value) -> bool {
+        is_recoverable_error(error)
+    }
+
+    /// TS `hook.setOnAbortCallback`.
+    pub fn set_on_abort_callback(&self, callback: impl Fn(&str) + Send + Sync + 'static) {
+        *self
+            .on_abort
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(Box::new(callback));
+    }
+
+    /// TS `hook.setOnRecoveryCompleteCallback`.
+    pub fn set_on_recovery_complete_callback(
+        &self,
+        callback: impl Fn(&str) + Send + Sync + 'static,
+    ) {
+        *self
+            .on_recovery_complete
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(Box::new(callback));
+    }
+
+    /// TS `hook.handleSessionRecovery(info)`.
+    ///
+    /// `Ok(bool)` mirrors the TS resolved boolean; `Err` mirrors the one TS
+    /// path that REJECTS (a `client.session.messages` failure, which happens
+    /// before the internal try/catch).
+    pub async fn handle_session_recovery(&self, info: &MessageInfo) -> Result<bool, CodexError> {
+        if info.role.as_deref() != Some("assistant") {
+            return Ok(false);
+        }
+        let Some(error) = info.error.as_ref().filter(|e| !js_falsy(e)) else {
+            return Ok(false);
+        };
+        let Some(error_type) = detect_error_type(error) else {
+            return Ok(false);
+        };
+        let Some(session_id) = info.session_id.as_deref().filter(|s| !s.is_empty()) else {
+            return Ok(false);
+        };
+
+        let log = cma_core::logger::create_logger("session-recovery");
+        log.debug(
+            "Recovery attempt started",
+            Some(&serde_json::json!({
+                "errorType": error_type.as_str(),
+                "sessionID": session_id,
+                "providedMsgID": info.id.clone().unwrap_or_else(|| "none".to_string()),
+            })),
+        );
+
+        {
+            let on_abort = self
+                .on_abort
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if let Some(callback) = on_abort.as_ref() {
+                callback(session_id);
+            }
+        }
+
+        let _ = self.client.session_abort(session_id).await;
+
+        // NOTE: propagates on failure (matches the TS rejection path).
+        let msgs = self
+            .client
+            .session_messages(session_id, &self.directory)
+            .await?;
+
+        let mut assistant_msg_id = info.id.clone();
+        if assistant_msg_id.is_none() {
+            for (i, m) in msgs.iter().enumerate().rev() {
+                if let Some(msg_info) = m.info.as_ref()
+                    && msg_info.role.as_deref() == Some("assistant")
+                    && let Some(id) = msg_info.id.as_ref()
+                {
+                    assistant_msg_id = Some(id.clone());
+                    log.debug(
+                        "Found assistant message ID from session messages",
+                        Some(&serde_json::json!({"msgID": id, "msgIndex": i})),
+                    );
+                    break;
+                }
+            }
+        }
+
+        let Some(assistant_msg_id) = assistant_msg_id else {
+            log.debug("No assistant message ID found, cannot recover", None);
+            return Ok(false);
+        };
+
+        // Reentrancy guard by message id.
+        {
+            let mut processing = self
+                .processing_errors
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if processing.contains(&assistant_msg_id) {
+                return Ok(false);
+            }
+            processing.insert(assistant_msg_id.clone());
+        }
+
+        let result = self
+            .run_recovery(error_type, error, session_id, &assistant_msg_id, &msgs)
+            .await;
+
+        // "finally": drop the guard + fire the completion callback.
+        {
+            let mut processing = self
+                .processing_errors
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            processing.remove(&assistant_msg_id);
+        }
+        {
+            let on_complete = self
+                .on_recovery_complete
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            if let Some(callback) = on_complete.as_ref() {
+                callback(session_id);
+            }
+        }
+
+        match result {
+            Ok(success) => Ok(success),
+            Err(err) => {
+                log.error(
+                    "Recovery failed",
+                    Some(&serde_json::json!({"error": err})),
+                );
+                Ok(false)
+            }
+        }
+    }
+
+    /// The TS try-block body; `Err(String)` models a caught exception.
+    async fn run_recovery(
+        &self,
+        error_type: RecoveryErrorType,
+        error: &Value,
+        session_id: &str,
+        assistant_msg_id: &str,
+        msgs: &[MessageData],
+    ) -> Result<bool, String> {
+        let failed_msg = msgs
+            .iter()
+            .find(|m| m.info.as_ref().and_then(|i| i.id.as_deref()) == Some(assistant_msg_id));
+        let Some(failed_msg) = failed_msg else {
+            return Ok(false);
+        };
+
+        let toast = get_recovery_toast_content(Some(error_type));
+        let _ = self
+            .client
+            .show_toast(&toast.title, &toast.message, "warning")
+            .await;
+
+        match error_type {
+            RecoveryErrorType::ToolResultMissing => {
+                self.recover_tool_result_missing(session_id, failed_msg)
+                    .await
+            }
+            RecoveryErrorType::ThinkingBlockOrder => {
+                let success = recover_thinking_block_order(session_id, error)?;
+                if success && self.auto_resume {
+                    let last_user = find_last_user_message(msgs);
+                    let resume = extract_resume_config(last_user, session_id);
+                    let _ = self.resume_session(&resume).await;
+                }
+                Ok(success)
+            }
+            RecoveryErrorType::ThinkingDisabledViolation => {
+                let success = recover_thinking_disabled_violation(session_id)?;
+                if success && self.auto_resume {
+                    let last_user = find_last_user_message(msgs);
+                    let resume = extract_resume_config(last_user, session_id);
+                    let _ = self.resume_session(&resume).await;
+                }
+                Ok(success)
+            }
+        }
+    }
+
+    async fn recover_tool_result_missing(
+        &self,
+        session_id: &str,
+        failed_msg: &MessageData,
+    ) -> Result<bool, String> {
+        let mut parts: Vec<MessagePart> = failed_msg.parts.clone().unwrap_or_default();
+        if parts.is_empty()
+            && let Some(msg_id) = failed_msg.info.as_ref().and_then(|i| i.id.as_deref())
+        {
+            // read_parts propagates an invalid-id error into the catch path.
+            let stored_parts = read_parts(msg_id)?;
+            parts = stored_parts
+                .iter()
+                .map(|p| MessagePart {
+                    part_type: if p.part_type == "tool" {
+                        "tool_use".to_string()
+                    } else {
+                        p.part_type.clone()
+                    },
+                    id: if p.has_call_id_key() {
+                        p.call_id().map(str::to_string)
+                    } else {
+                        Some(p.id.clone())
+                    },
+                    name: p.tool().map(str::to_string),
+                    input: p.state_input().cloned(),
+                    ..MessagePart::default()
+                })
+                .collect();
+        }
+
+        let tool_use_ids: Vec<String> = parts
+            .iter()
+            .filter(|p| p.part_type == "tool_use")
+            .filter_map(|p| p.id.clone())
+            .filter(|id| !id.is_empty())
+            .collect();
+
+        if tool_use_ids.is_empty() {
+            return Ok(false);
+        }
+
+        let tool_result_parts: Vec<Value> = tool_use_ids
+            .iter()
+            .map(|id| {
+                serde_json::to_value(ToolResultPart::new(id.clone(), TOOL_CANCELLED_CONTENT))
+                    .expect("ToolResultPart serializes")
+            })
+            .collect();
+
+        let body = PromptBody {
+            parts: tool_result_parts,
+            agent: None,
+            model: None,
+        };
+        Ok(self
+            .client
+            .session_prompt(session_id, body, None)
+            .await
+            .is_ok())
+    }
+
+    async fn resume_session(&self, config: &ResumeConfig) -> bool {
+        let body = PromptBody {
+            parts: vec![serde_json::json!({"type": "text", "text": RECOVERY_RESUME_TEXT})],
+            agent: config.agent.clone(),
+            model: config.model.clone(),
+        };
+        self.client
+            .session_prompt(&config.session_id, body, Some(&self.directory))
+            .await
+            .is_ok()
+    }
+}
+
+fn recover_thinking_block_order(session_id: &str, error: &Value) -> Result<bool, String> {
+    if let Some(target_index) = extract_message_index(error)
+        && let Some(target_message_id) =
+            find_message_by_index_needing_thinking(session_id, target_index)?
+    {
+        return Ok(prepend_thinking_part(session_id, &target_message_id));
+    }
+
+    let orphan_messages = find_messages_with_orphan_thinking(session_id)?;
+    if orphan_messages.is_empty() {
+        return Ok(false);
+    }
+
+    let mut any_success = false;
+    for message_id in &orphan_messages {
+        if prepend_thinking_part(session_id, message_id) {
+            any_success = true;
+        }
+    }
+    Ok(any_success)
+}
+
+fn recover_thinking_disabled_violation(session_id: &str) -> Result<bool, String> {
+    let messages_with_thinking = find_messages_with_thinking_blocks(session_id)?;
+    if messages_with_thinking.is_empty() {
+        return Ok(false);
+    }
+
+    let mut any_success = false;
+    for message_id in &messages_with_thinking {
+        if strip_thinking_parts(message_id) {
+            any_success = true;
+        }
+    }
+    Ok(any_success)
+}
+
+fn find_last_user_message(messages: &[MessageData]) -> Option<&MessageData> {
+    messages
+        .iter()
+        .rev()
+        .find(|m| m.info.as_ref().and_then(|i| i.role.as_deref()) == Some("user"))
+}
+
+fn extract_resume_config(user_message: Option<&MessageData>, session_id: &str) -> ResumeConfig {
+    ResumeConfig {
+        session_id: session_id.to_string(),
+        agent: user_message
+            .and_then(|m| m.info.as_ref())
+            .and_then(|i| i.agent.clone()),
+        model: user_message
+            .and_then(|m| m.info.as_ref())
+            .and_then(|i| i.model.clone()),
+    }
+}
+
+// =============================================================================
+// Tests — ported from test/recovery.test.ts (classification + toasts)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn detects_tool_result_missing() {
+        let error = json!({"message": "Each `tool_use` block must have a corresponding `tool_result`"});
+        assert_eq!(
+            detect_error_type(&error),
+            Some(RecoveryErrorType::ToolResultMissing)
+        );
+        assert!(is_recoverable_error(&error));
+    }
+
+    #[test]
+    fn detects_thinking_block_order_variants() {
+        for msg in [
+            "messages.3: thinking block must be the first block",
+            "thinking must start with a thinking block",
+            "thinking blocks: preceeding turn was cancelled",
+            "expected thinking but found text",
+        ] {
+            assert_eq!(
+                detect_error_type(&json!({"message": msg})),
+                Some(RecoveryErrorType::ThinkingBlockOrder),
+                "message: {msg}"
+            );
+        }
+    }
+
+    #[test]
+    fn detects_thinking_disabled_violation() {
+        let error =
+            json!({"message": "Thinking is disabled; messages cannot contain thinking blocks"});
+        assert_eq!(
+            detect_error_type(&error),
+            Some(RecoveryErrorType::ThinkingDisabledViolation)
+        );
+    }
+
+    #[test]
+    fn returns_none_for_unrelated_errors() {
+        assert_eq!(detect_error_type(&json!({"message": "rate limited"})), None);
+        assert_eq!(detect_error_type(&Value::Null), None);
+        assert_eq!(detect_error_type(&json!("")), None);
+        assert!(!is_recoverable_error(&json!({"message": "boom"})));
+    }
+
+    #[test]
+    fn probes_nested_error_shapes() {
+        // error.data.message
+        let e1 = json!({"data": {"message": "tool_use without tool_result"}});
+        assert_eq!(detect_error_type(&e1), Some(RecoveryErrorType::ToolResultMissing));
+        // error.error.message
+        let e2 = json!({"error": {"message": "tool_use without tool_result"}});
+        assert_eq!(detect_error_type(&e2), Some(RecoveryErrorType::ToolResultMissing));
+        // error.data.error.message
+        let e3 = json!({"data": {"error": {"message": "tool_use without tool_result"}}});
+        assert_eq!(detect_error_type(&e3), Some(RecoveryErrorType::ToolResultMissing));
+        // Plain string
+        let e4 = json!("TOOL_USE and TOOL_RESULT mismatch");
+        assert_eq!(detect_error_type(&e4), Some(RecoveryErrorType::ToolResultMissing));
+        // JSON.stringify fallback
+        let e5 = json!({"other": "tool_use ... tool_result"});
+        assert_eq!(detect_error_type(&e5), Some(RecoveryErrorType::ToolResultMissing));
+    }
+
+    #[test]
+    fn extract_message_index_parses_first_match() {
+        assert_eq!(
+            extract_message_index(&json!({"message": "messages.12: thinking block"})),
+            Some(12)
+        );
+        assert_eq!(
+            extract_message_index(&json!({"message": "no index here"})),
+            None
+        );
+        assert_eq!(
+            extract_message_index(&json!({"message": "messages.x then messages.7"})),
+            Some(7)
+        );
+    }
+
+    #[test]
+    fn toast_content_matches_ts_strings() {
+        assert_eq!(
+            get_recovery_toast_content(None),
+            ToastContent {
+                title: "Session Recovery".into(),
+                message: "Attempting to recover session...".into()
+            }
+        );
+        assert_eq!(
+            get_recovery_toast_content(Some(RecoveryErrorType::ToolResultMissing)),
+            ToastContent {
+                title: "Tool Crash Recovery".into(),
+                message: "Injecting cancelled tool results...".into()
+            }
+        );
+        assert_eq!(
+            get_recovery_toast_content(Some(RecoveryErrorType::ThinkingBlockOrder)),
+            ToastContent {
+                title: "Thinking Block Recovery".into(),
+                message: "Fixing message structure...".into()
+            }
+        );
+        assert_eq!(
+            get_recovery_toast_content(Some(RecoveryErrorType::ThinkingDisabledViolation)),
+            ToastContent {
+                title: "Thinking Strip Recovery".into(),
+                message: "Stripping thinking blocks...".into()
+            }
+        );
+        assert_eq!(get_recovery_success_toast().title, "Session Recovered");
+        assert_eq!(
+            get_recovery_failure_toast().message,
+            "Please retry or start a new session."
+        );
+    }
+
+    #[test]
+    fn create_hook_respects_session_recovery_flag() {
+        struct NullClient;
+        impl SessionRecoveryClient for NullClient {
+            async fn session_abort(&self, _: &str) -> Result<(), CodexError> {
+                Ok(())
+            }
+            async fn session_messages(
+                &self,
+                _: &str,
+                _: &str,
+            ) -> Result<Vec<MessageData>, CodexError> {
+                Ok(Vec::new())
+            }
+            async fn session_prompt(
+                &self,
+                _: &str,
+                _: PromptBody,
+                _: Option<&str>,
+            ) -> Result<(), CodexError> {
+                Ok(())
+            }
+            async fn show_toast(&self, _: &str, _: &str, _: &str) -> Result<(), CodexError> {
+                Ok(())
+            }
+        }
+
+        assert!(
+            create_session_recovery_hook(
+                NullClient,
+                "/dir",
+                SessionRecoveryConfig {
+                    session_recovery: false,
+                    auto_resume: true
+                }
+            )
+            .is_none()
+        );
+        assert!(create_runtime_session_recovery_hook(false, true, NullClient, "/dir").is_none());
+        assert!(create_runtime_session_recovery_hook(true, true, NullClient, "/dir").is_some());
+    }
+
+    #[tokio::test]
+    async fn handle_session_recovery_rejects_non_assistant_and_no_error() {
+        struct NullClient;
+        impl SessionRecoveryClient for NullClient {
+            async fn session_abort(&self, _: &str) -> Result<(), CodexError> {
+                Ok(())
+            }
+            async fn session_messages(
+                &self,
+                _: &str,
+                _: &str,
+            ) -> Result<Vec<MessageData>, CodexError> {
+                Ok(Vec::new())
+            }
+            async fn session_prompt(
+                &self,
+                _: &str,
+                _: PromptBody,
+                _: Option<&str>,
+            ) -> Result<(), CodexError> {
+                Ok(())
+            }
+            async fn show_toast(&self, _: &str, _: &str, _: &str) -> Result<(), CodexError> {
+                Ok(())
+            }
+        }
+        let hook = create_session_recovery_hook(NullClient, "/dir", SessionRecoveryConfig::default())
+            .unwrap();
+
+        let mut info = MessageInfo {
+            role: Some("user".to_string()),
+            error: Some(json!({"message": "tool_use tool_result"})),
+            session_id: Some("ses1".to_string()),
+            ..MessageInfo::default()
+        };
+        assert!(!hook.handle_session_recovery(&info).await.unwrap());
+
+        info.role = Some("assistant".to_string());
+        info.error = None;
+        assert!(!hook.handle_session_recovery(&info).await.unwrap());
+
+        // Recoverable error but no session id.
+        info.error = Some(json!({"message": "tool_use tool_result"}));
+        info.session_id = None;
+        assert!(!hook.handle_session_recovery(&info).await.unwrap());
+    }
+}
diff --git a/crates/runtime/src/recovery/mod.rs b/crates/runtime/src/recovery/mod.rs
new file mode 100644
index 000000000..7d98fffd8
--- /dev/null
+++ b/crates/runtime/src/recovery/mod.rs
@@ -0,0 +1,6 @@
+//! cma-runtime - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod constants;
+pub mod hashline;
+pub mod hook;
+pub mod storage;
+pub mod types;
diff --git a/crates/runtime/src/recovery/storage.rs b/crates/runtime/src/recovery/storage.rs
new file mode 100644
index 000000000..e41865da9
--- /dev/null
+++ b/crates/runtime/src/recovery/storage.rs
@@ -0,0 +1,1100 @@
+//! Port of `lib/recovery/storage.ts` — synchronous readers, corruption
+//! quarantine, and surgical repairs over the host runtime's session store
+//! (spec 11 §6.3).
+//!
+//! Key contracts (spec 11 §12 gotchas 28–31):
+//! - transient read errors (EBUSY/EPERM/EACCES/EAGAIN/ENOENT) are races, not
+//!   corruption: skip, never quarantine;
+//! - successful read + bad JSON/shape ⇒ quarantine rename `.corrupt-{ts}`;
+//!   the count increments even when the rename fails;
+//! - `SAFE_ID_PATTERN` gates every id before a path join (traversal defense);
+//!   readers propagate the error, repair fns catch and return `false`;
+//! - synthetic thinking ids sort before every real part id and are unique
+//!   per invocation (RPTU-001);
+//! - `strip_thinking_parts` only reports success when every targeted part
+//!   was removed (recovery-05).
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use cma_core::fs_retry::{Backoff, RetryOptions, with_retry_sync};
+use cma_core::temp_path::temp_file_nonce;
+use cma_core::utils::now_ms;
+use rand::RngCore;
+use serde_json::Value;
+
+use super::constants::{is_meta_type, is_thinking_type, message_storage, part_storage};
+use super::types::{StoredMessageMeta, StoredPart};
+
+// =============================================================================
+// Corruption quarantine (recovery-10)
+// =============================================================================
+
+static CORRUPTION_STATS: Mutex<(u64, Vec<String>)> = Mutex::new((0, Vec::new()));
+
+/// Transient read-side faults that are NOT corruption (spec 11 §6.3).
+const TRANSIENT_READ_CODES: [&str; 5] = ["EBUSY", "EPERM", "EACCES", "EAGAIN", "ENOENT"];
+
+/// Retry codes for rename/unlink (matches `lib/storage.ts` convention).
+const RETRYABLE_FS_CODES: [&str; 4] = ["EBUSY", "EPERM", "ENOTEMPTY", "EAGAIN"];
+
+/// Snapshot of corrupt-file quarantine activity for this process.
+pub fn get_recovery_corruption_stats() -> (u64, Vec<String>) {
+    let stats = CORRUPTION_STATS
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    (stats.0, stats.1.clone())
+}
+
+/// Test-only reset of the corruption counters (TS
+/// `__resetRecoveryCorruptionStats`).
+pub fn __reset_recovery_corruption_stats() {
+    let mut stats = CORRUPTION_STATS
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    stats.0 = 0;
+    stats.1.clear();
+}
+
+fn log() -> cma_core::logger::ScopedLogger {
+    cma_core::logger::create_logger("recovery-storage")
+}
+
+fn is_transient_read_error(error: &io::Error) -> bool {
+    match cma_core::fs_retry::code_of(error) {
+        Some(code) => TRANSIENT_READ_CODES.contains(&code),
+        None => false,
+    }
+}
+
+/// Read-failure classification: transient errors skip, everything else
+/// quarantines (spec 11 gotcha 28).
+enum ReadFailure {
+    /// Transient FS race (or genuine corruption pre-classified).
+    TransientIo(io::Error),
+    /// Successful read, but the payload failed parse/shape validation.
+    Corrupt(String),
+}
+
+fn handle_unreadable_file(file_path: &Path, failure: ReadFailure) {
+    match failure {
+        ReadFailure::TransientIo(error) if is_transient_read_error(&error) => {
+            log().debug(
+                "skipping recovery file on transient read error",
+                Some(&serde_json::json!({
+                    "path": file_path.display().to_string(),
+                    "reason": error.to_string(),
+                })),
+            );
+        }
+        ReadFailure::TransientIo(error) => {
+            quarantine_corrupt_file(file_path, &error.to_string());
+        }
+        ReadFailure::Corrupt(reason) => {
+            quarantine_corrupt_file(file_path, &reason);
+        }
+    }
+}
+
+fn quarantine_corrupt_file(file_path: &Path, reason: &str) {
+    {
+        let mut stats = CORRUPTION_STATS
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        stats.0 += 1;
+    }
+    let target = PathBuf::from(format!("{}.corrupt-{}", file_path.display(), now_ms()));
+    match rename_sync_with_retry(file_path, &target) {
+        Ok(()) => {
+            let mut stats = CORRUPTION_STATS
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            stats.1.push(target.display().to_string());
+            drop(stats);
+            log().warn(
+                "quarantined corrupt recovery file",
+                Some(&serde_json::json!({
+                    "path": target.display().to_string(),
+                    "reason": reason,
+                })),
+            );
+        }
+        Err(rename_error) => {
+            log().warn(
+                "failed to quarantine corrupt recovery file",
+                Some(&serde_json::json!({
+                    "path": file_path.display().to_string(),
+                    "reason": reason,
+                    "renameError": rename_error.to_string(),
+                })),
+            );
+        }
+    }
+}
+
+// =============================================================================
+// ID safety (recovery-02/03)
+// =============================================================================
+
+/// TS `SAFE_ID_PATTERN = /^[a-zA-Z0-9_-]+$/`.
+fn is_safe_id(id: &str) -> bool {
+    !id.is_empty()
+        && id
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+}
+
+/// TS `validatePathId(id, name)` — errors with the exact frozen message.
+/// Readers propagate this error; repair fns catch it and return `false`.
+pub fn validate_path_id(id: &str, name: &str) -> Result<(), String> {
+    if !is_safe_id(id) {
+        return Err(format!("Invalid {name}: contains unsafe characters"));
+    }
+    Ok(())
+}
+
+// =============================================================================
+// Record validation (recovery-02)
+// =============================================================================
+
+fn is_valid_stored_message(value: &Value) -> bool {
+    let Some(obj) = value.as_object() else {
+        return false;
+    };
+    let Some(id) = obj.get("id").and_then(Value::as_str) else {
+        return false;
+    };
+    if !is_safe_id(id) {
+        return false;
+    }
+    if let Some(time) = obj.get("time") {
+        let Some(time_obj) = time.as_object() else {
+            return false;
+        };
+        if let Some(created) = time_obj.get("created") {
+            match created.as_f64() {
+                Some(v) if v.is_finite() => {}
+                _ => return false,
+            }
+        }
+    }
+    true
+}
+
+fn is_valid_stored_part(value: &Value) -> bool {
+    let Some(obj) = value.as_object() else {
+        return false;
+    };
+    let id_ok = obj
+        .get("id")
+        .and_then(Value::as_str)
+        .is_some_and(is_safe_id);
+    id_ok && obj.get("type").is_some_and(Value::is_string)
+}
+
+// =============================================================================
+// FS helpers
+// =============================================================================
+
+fn rename_sync_with_retry(source: &Path, target: &Path) -> io::Result<()> {
+    with_retry_sync(
+        || fs::rename(source, target),
+        RetryOptions::new(4, Backoff::from_fn(|attempt| 10 * 2u64.pow(attempt - 1)))
+            .with_codes(&RETRYABLE_FS_CODES),
+    )
+}
+
+/// Atomic write: temp sibling `{path}.tmp.{nonce}` + rename-with-retry; the
+/// staged file is unlinked on failure.
+fn atomic_write_file_sync(path: &Path, data: &str) -> io::Result<()> {
+    let temp_path = PathBuf::from(format!("{}.tmp.{}", path.display(), temp_file_nonce()));
+    let result = (|| -> io::Result<()> {
+        fs::write(&temp_path, data)?;
+        set_file_mode_0600(&temp_path);
+        rename_sync_with_retry(&temp_path, path)
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(&temp_path);
+    }
+    result
+}
+
+#[cfg(unix)]
+fn set_file_mode_0600(path: &Path) {
+    use std::os::unix::fs::PermissionsExt;
+    let _ = fs::set_permissions(path, fs::Permissions::from_mode(0o600));
+}
+
+#[cfg(not(unix))]
+fn set_file_mode_0600(_path: &Path) {}
+
+/// Best-effort delete with bounded retry. Returns `true` on removal, `false`
+/// on missing file or exhausted retries; never errors.
+fn safe_unlink_with_retry(file_path: &Path, max_attempts: u32) -> bool {
+    with_retry_sync(
+        || fs::remove_file(file_path),
+        RetryOptions::new(
+            max_attempts,
+            Backoff::from_fn(|attempt| 2u64.pow(attempt - 1) * 5),
+        )
+        .with_codes(&RETRYABLE_FS_CODES),
+    )
+    .is_ok()
+}
+
+// =============================================================================
+// ID generation
+// =============================================================================
+
+/// TS `generatePartId()` — `prt_{hex ms}{8 hex random}`.
+pub fn generate_part_id() -> String {
+    let timestamp = format!("{:x}", now_ms());
+    let mut bytes = [0u8; 4];
+    rand::rng().fill_bytes(&mut bytes);
+    let random: String = bytes.iter().map(|b| format!("{b:02x}")).collect();
+    format!("prt_{timestamp}{random}")
+}
+
+static THINKING_PART_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+fn to_base36(mut value: u64) -> String {
+    const DIGITS: &[u8; 36] = b"0123456789abcdefghijklmnopqrstuvwxyz";
+    if value == 0 {
+        return "0".to_string();
+    }
+    let mut out = Vec::new();
+    while value > 0 {
+        out.push(DIGITS[(value % 36) as usize]);
+        value /= 36;
+    }
+    out.reverse();
+    String::from_utf8(out).expect("base36 digits are ASCII")
+}
+
+/// TS `generateThinkingPartId()` — unique per invocation (RPTU-001) and
+/// lexicographically BEFORE every [`generate_part_id`] output (the
+/// `prt_0000000000` prefix sorts before any non-zero hex timestamp).
+pub fn generate_thinking_part_id() -> String {
+    let timestamp = format!("{:x}", now_ms());
+    let counter = to_base36(THINKING_PART_COUNTER.fetch_add(1, Ordering::SeqCst));
+    let mut bytes = [0u8; 3];
+    rand::rng().fill_bytes(&mut bytes);
+    let random: String = bytes.iter().map(|b| format!("{b:02x}")).collect();
+    format!("prt_0000000000_thinking_{timestamp}_{counter}_{random}")
+}
+
+// =============================================================================
+// Directory helpers
+// =============================================================================
+
+/// TS `getMessageDir(sessionID)` — `""` (here: `None`) when not found.
+/// Propagates the invalid-id error (gotcha 29).
+pub fn get_message_dir(session_id: &str) -> Result<Option<PathBuf>, String> {
+    validate_path_id(session_id, "sessionID")?;
+    let root = message_storage();
+    if !root.exists() {
+        return Ok(None);
+    }
+
+    let direct = root.join(session_id);
+    if direct.exists() {
+        return Ok(Some(direct));
+    }
+
+    if let Ok(entries) = fs::read_dir(&root) {
+        for entry in entries.flatten() {
+            let session_path = entry.path().join(session_id);
+            if session_path.exists() {
+                return Ok(Some(session_path));
+            }
+        }
+    }
+
+    Ok(None)
+}
+
+// =============================================================================
+// Message / part reading
+// =============================================================================
+
+fn read_json_records<T, FValidate, FDetail>(
+    dir: &Path,
+    validate: FValidate,
+    invalid_detail: FDetail,
+) -> Vec<T>
+where
+    T: serde::de::DeserializeOwned,
+    FValidate: Fn(&Value) -> bool,
+    FDetail: Fn() -> &'static str,
+{
+    let mut records = Vec::new();
+    let entries = match fs::read_dir(dir) {
+        Ok(entries) => entries,
+        Err(_) => return Vec::new(),
+    };
+    for entry in entries.flatten() {
+        let file_name = entry.file_name();
+        let name = file_name.to_string_lossy();
+        if !name.ends_with(".json") {
+            continue;
+        }
+        let file_path = entry.path();
+        match fs::read_to_string(&file_path) {
+            Err(error) => {
+                handle_unreadable_file(&file_path, ReadFailure::TransientIo(error));
+            }
+            Ok(content) => match serde_json::from_str::<Value>(&content) {
+                Err(error) => {
+                    handle_unreadable_file(&file_path, ReadFailure::Corrupt(error.to_string()));
+                }
+                Ok(parsed) => {
+                    if !validate(&parsed) {
+                        handle_unreadable_file(
+                            &file_path,
+                            ReadFailure::Corrupt(format!(
+                                "invalid recovery record: {}",
+                                invalid_detail()
+                            )),
+                        );
+                        continue;
+                    }
+                    match serde_json::from_value::<T>(parsed) {
+                        Ok(record) => records.push(record),
+                        Err(error) => {
+                            // Shape passed the validator but the struct parse
+                            // failed (should not happen — permissive structs);
+                            // treat like corruption for safety.
+                            handle_unreadable_file(
+                                &file_path,
+                                ReadFailure::Corrupt(error.to_string()),
+                            );
+                        }
+                    }
+                }
+            },
+        }
+    }
+    records
+}
+
+/// TS `readMessages(sessionID)` — sorted by `time.created ?? 0` ascending,
+/// ties by id (lexicographic).
+pub fn read_messages(session_id: &str) -> Result<Vec<StoredMessageMeta>, String> {
+    let Some(message_dir) = get_message_dir(session_id)? else {
+        return Ok(Vec::new());
+    };
+    if !message_dir.exists() {
+        return Ok(Vec::new());
+    }
+
+    let mut messages: Vec<StoredMessageMeta> = read_json_records(
+        &message_dir,
+        is_valid_stored_message,
+        || "message missing string id",
+    );
+
+    messages.sort_by(|a, b| {
+        let a_time = a.created_sort_key();
+        let b_time = b.created_sort_key();
+        match a_time.partial_cmp(&b_time) {
+            Some(std::cmp::Ordering::Equal) | None => a.id.cmp(&b.id),
+            Some(order) => order,
+        }
+    });
+    Ok(messages)
+}
+
+/// TS `readParts(messageID)` — unsorted (directory order). Propagates the
+/// invalid-id error (gotcha 29).
+pub fn read_parts(message_id: &str) -> Result<Vec<StoredPart>, String> {
+    validate_path_id(message_id, "messageID")?;
+    let part_dir = part_storage().join(message_id);
+    if !part_dir.exists() {
+        return Ok(Vec::new());
+    }
+    Ok(read_json_records(
+        &part_dir,
+        is_valid_stored_part,
+        || "part missing string id/type",
+    ))
+}
+
+// =============================================================================
+// Content helpers
+// =============================================================================
+
+/// TS `hasContent(part)`.
+///
+/// Note: the TS cast `part as StoredTextPart` means a non-string `text`
+/// value would throw inside `hasContent`; the Rust port treats a non-string
+/// `text` as blank (recorded deviation — the TS behavior is an accidental
+/// crash on malformed data that validation already filters in practice).
+pub fn has_content(part: &StoredPart) -> bool {
+    let part_type = part.part_type.as_str();
+    if is_thinking_type(part_type) || is_meta_type(part_type) {
+        return false;
+    }
+    match part_type {
+        "text" => part.text().is_some_and(|t| !t.trim().is_empty()),
+        "tool" | "tool_use" | "tool_result" => true,
+        _ => false,
+    }
+}
+
+/// TS `messageHasContent(messageID)`.
+pub fn message_has_content(message_id: &str) -> Result<bool, String> {
+    Ok(read_parts(message_id)?.iter().any(has_content))
+}
+
+// =============================================================================
+// Part injection (for recovery)
+// =============================================================================
+
+/// TS `injectTextPart` — writes a synthetic text part; `false` on any error.
+pub fn inject_text_part(session_id: &str, message_id: &str, text: &str) -> bool {
+    if validate_path_id(message_id, "messageID").is_err() {
+        return false;
+    }
+    let part_dir = part_storage().join(message_id);
+    if !part_dir.exists() && fs::create_dir_all(&part_dir).is_err() {
+        return false;
+    }
+
+    let part_id = generate_part_id();
+    let part = serde_json::json!({
+        "id": part_id,
+        "sessionID": session_id,
+        "messageID": message_id,
+        "type": "text",
+        "text": text,
+        "synthetic": true,
+    });
+    atomic_write_file_sync(
+        &part_dir.join(format!("{part_id}.json")),
+        &cma_core::json_io::stringify_pretty2(&part),
+    )
+    .is_ok()
+}
+
+// =============================================================================
+// Thinking block recovery
+// =============================================================================
+
+/// TS `findMessagesWithThinkingBlocks`.
+pub fn find_messages_with_thinking_blocks(session_id: &str) -> Result<Vec<String>, String> {
+    let messages = read_messages(session_id)?;
+    let mut result = Vec::new();
+    for msg in &messages {
+        if !msg.is_assistant() {
+            continue;
+        }
+        let parts = read_parts(&msg.id)?;
+        if parts.iter().any(|p| is_thinking_type(&p.part_type)) {
+            result.push(msg.id.clone());
+        }
+    }
+    Ok(result)
+}
+
+/// TS `findMessagesWithThinkingOnly` — assistant messages with parts that
+/// have thinking but no content (orphan thinking).
+pub fn find_messages_with_thinking_only(session_id: &str) -> Result<Vec<String>, String> {
+    let messages = read_messages(session_id)?;
+    let mut result = Vec::new();
+    for msg in &messages {
+        if !msg.is_assistant() {
+            continue;
+        }
+        let parts = read_parts(&msg.id)?;
+        if parts.is_empty() {
+            continue;
+        }
+        let has_thinking = parts.iter().any(|p| is_thinking_type(&p.part_type));
+        let has_text_content = parts.iter().any(has_content);
+        if has_thinking && !has_text_content {
+            result.push(msg.id.clone());
+        }
+    }
+    Ok(result)
+}
+
+/// TS `findMessagesWithOrphanThinking` — assistant messages whose id-sorted
+/// FIRST part is not a thinking type (i.e. messages *missing* a leading
+/// thinking block; the TS name is historically confusing).
+pub fn find_messages_with_orphan_thinking(session_id: &str) -> Result<Vec<String>, String> {
+    let messages = read_messages(session_id)?;
+    let mut result = Vec::new();
+    for msg in &messages {
+        if !msg.is_assistant() {
+            continue;
+        }
+        let mut parts = read_parts(&msg.id)?;
+        if parts.is_empty() {
+            continue;
+        }
+        parts.sort_by(|a, b| a.id.cmp(&b.id));
+        let first = &parts[0];
+        if !is_thinking_type(&first.part_type) {
+            result.push(msg.id.clone());
+        }
+    }
+    Ok(result)
+}
+
+/// TS `prependThinkingPart` — writes a synthetic empty thinking part whose id
+/// sorts before every real part id; `false` on any error.
+pub fn prepend_thinking_part(session_id: &str, message_id: &str) -> bool {
+    if validate_path_id(message_id, "messageID").is_err() {
+        return false;
+    }
+    let part_dir = part_storage().join(message_id);
+    if !part_dir.exists() && fs::create_dir_all(&part_dir).is_err() {
+        return false;
+    }
+
+    let part_id = generate_thinking_part_id();
+    let part = serde_json::json!({
+        "id": part_id,
+        "sessionID": session_id,
+        "messageID": message_id,
+        "type": "thinking",
+        "thinking": "",
+        "synthetic": true,
+    });
+    atomic_write_file_sync(
+        &part_dir.join(format!("{part_id}.json")),
+        &cma_core::json_io::stringify_pretty2(&part),
+    )
+    .is_ok()
+}
+
+/// TS `stripThinkingParts` — removes every thinking-type part file. Reports
+/// success ONLY when at least one part was removed and no targeted part
+/// survived (recovery-05: a survivor would loop auto-resume forever).
+pub fn strip_thinking_parts(message_id: &str) -> bool {
+    if validate_path_id(message_id, "messageID").is_err() {
+        return false;
+    }
+    let part_dir = part_storage().join(message_id);
+    if !part_dir.exists() {
+        return false;
+    }
+
+    let mut any_removed = false;
+    let mut any_target_failed = false;
+    let entries = match fs::read_dir(&part_dir) {
+        Ok(entries) => entries,
+        Err(_) => return false,
+    };
+    for entry in entries.flatten() {
+        let file_name = entry.file_name();
+        let name = file_name.to_string_lossy();
+        if !name.ends_with(".json") {
+            continue;
+        }
+        let file_path = entry.path();
+        let Ok(content) = fs::read_to_string(&file_path) else {
+            continue;
+        };
+        let Ok(part) = serde_json::from_str::<Value>(&content) else {
+            continue;
+        };
+        let part_type = part.get("type").and_then(Value::as_str).unwrap_or("");
+        if is_thinking_type(part_type) {
+            if safe_unlink_with_retry(&file_path, 4) {
+                any_removed = true;
+            } else {
+                any_target_failed = true;
+            }
+        }
+    }
+
+    any_removed && !any_target_failed
+}
+
+// =============================================================================
+// Empty message recovery
+// =============================================================================
+
+/// TS `findEmptyMessages` — all messages (any role) with no content part.
+pub fn find_empty_messages(session_id: &str) -> Result<Vec<String>, String> {
+    let messages = read_messages(session_id)?;
+    let mut empty_ids = Vec::new();
+    for msg in &messages {
+        if !message_has_content(&msg.id)? {
+            empty_ids.push(msg.id.clone());
+        }
+    }
+    Ok(empty_ids)
+}
+
+/// TS `findEmptyMessageByIndex` — probes indexes `[i, i-1, i-2]` to bridge
+/// API-vs-storage index skew (gotcha 34).
+pub fn find_empty_message_by_index(
+    session_id: &str,
+    target_index: i64,
+) -> Result<Option<String>, String> {
+    let messages = read_messages(session_id)?;
+
+    for idx in [target_index, target_index - 1, target_index - 2] {
+        if idx < 0 || idx >= messages.len() as i64 {
+            continue;
+        }
+        let target = &messages[idx as usize];
+        if !target.is_assistant() {
+            continue;
+        }
+        if !message_has_content(&target.id)? {
+            return Ok(Some(target.id.clone()));
+        }
+    }
+    Ok(None)
+}
+
+/// TS `findMessageByIndexNeedingThinking` — exact index only (does NOT probe
+/// neighbors, gotcha 34).
+pub fn find_message_by_index_needing_thinking(
+    session_id: &str,
+    target_index: i64,
+) -> Result<Option<String>, String> {
+    let messages = read_messages(session_id)?;
+    if target_index < 0 || target_index >= messages.len() as i64 {
+        return Ok(None);
+    }
+    let target = &messages[target_index as usize];
+    if !target.is_assistant() {
+        return Ok(None);
+    }
+    let mut parts = read_parts(&target.id)?;
+    if parts.is_empty() {
+        return Ok(None);
+    }
+    parts.sort_by(|a, b| a.id.cmp(&b.id));
+    if !is_thinking_type(&parts[0].part_type) {
+        return Ok(Some(target.id.clone()));
+    }
+    Ok(None)
+}
+
+/// TS `replaceEmptyTextParts` — sets blank `text` parts to the replacement
+/// text (+ `synthetic: true`), pretty-JSON atomic rewrite preserving other
+/// fields and key order. `true` iff any part was replaced.
+pub fn replace_empty_text_parts(message_id: &str, replacement_text: &str) -> bool {
+    if validate_path_id(message_id, "messageID").is_err() {
+        return false;
+    }
+    let part_dir = part_storage().join(message_id);
+    if !part_dir.exists() {
+        return false;
+    }
+
+    let mut any_replaced = false;
+    let entries = match fs::read_dir(&part_dir) {
+        Ok(entries) => entries,
+        Err(_) => return false,
+    };
+    for entry in entries.flatten() {
+        let file_name = entry.file_name();
+        let name = file_name.to_string_lossy();
+        if !name.ends_with(".json") {
+            continue;
+        }
+        let file_path = entry.path();
+        let Ok(content) = fs::read_to_string(&file_path) else {
+            continue;
+        };
+        let Ok(mut part) = serde_json::from_str::<Value>(&content) else {
+            continue;
+        };
+        let is_text = part.get("type").and_then(Value::as_str) == Some("text");
+        if !is_text {
+            continue;
+        }
+        let blank = part
+            .get("text")
+            .and_then(Value::as_str)
+            .is_none_or(|t| t.trim().is_empty());
+        if !blank {
+            continue;
+        }
+        if let Some(obj) = part.as_object_mut() {
+            obj.insert("text".to_string(), Value::String(replacement_text.to_string()));
+            obj.insert("synthetic".to_string(), Value::Bool(true));
+        }
+        if atomic_write_file_sync(&file_path, &cma_core::json_io::stringify_pretty2(&part)).is_ok()
+        {
+            any_replaced = true;
+        }
+    }
+
+    any_replaced
+}
+
+/// TS `findMessagesWithEmptyTextParts`.
+pub fn find_messages_with_empty_text_parts(session_id: &str) -> Result<Vec<String>, String> {
+    let messages = read_messages(session_id)?;
+    let mut result = Vec::new();
+    for msg in &messages {
+        let parts = read_parts(&msg.id)?;
+        let has_empty_text = parts.iter().any(|p| {
+            p.part_type == "text" && p.text().is_none_or(|t| t.trim().is_empty())
+        });
+        if has_empty_text {
+            result.push(msg.id.clone());
+        }
+    }
+    Ok(result)
+}
+
+// =============================================================================
+// Tests — ported from test/recovery-storage.test.ts (P0)
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    /// Point the recovery storage root at the sandbox and return the
+    /// message/part dirs.
+    fn setup_storage(sandbox: &mut EnvSandbox) -> (PathBuf, PathBuf) {
+        let data_root = sandbox.root().join("xdg-data");
+        #[cfg(windows)]
+        sandbox.set_var("APPDATA", &data_root);
+        #[cfg(not(windows))]
+        sandbox.set_var("XDG_DATA_HOME", &data_root);
+        __reset_recovery_corruption_stats();
+        (message_storage(), part_storage())
+    }
+
+    fn write_json(path: &Path, value: &Value) {
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        fs::write(path, serde_json::to_string_pretty(value).unwrap()).unwrap();
+    }
+
+    #[test]
+    #[serial(env)]
+    fn generate_part_id_includes_prefix_timestamp_random() {
+        let id = generate_part_id();
+        assert!(id.starts_with("prt_"));
+        assert!(id.len() > "prt_".len() + 8);
+        assert_ne!(generate_part_id(), id);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn get_message_dir_missing_base_returns_none() {
+        let mut sandbox = EnvSandbox::new();
+        let _ = setup_storage(&mut sandbox);
+        assert_eq!(get_message_dir("ses1").unwrap(), None);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn get_message_dir_finds_direct_and_nested() {
+        let mut sandbox = EnvSandbox::new();
+        let (msg_root, _) = setup_storage(&mut sandbox);
+        fs::create_dir_all(msg_root.join("sesdirect")).unwrap();
+        assert_eq!(
+            get_message_dir("sesdirect").unwrap(),
+            Some(msg_root.join("sesdirect"))
+        );
+
+        fs::create_dir_all(msg_root.join("proj").join("sesnested")).unwrap();
+        assert_eq!(
+            get_message_dir("sesnested").unwrap(),
+            Some(msg_root.join("proj").join("sesnested"))
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn read_messages_sorts_and_skips_invalid() {
+        let mut sandbox = EnvSandbox::new();
+        let (msg_root, _) = setup_storage(&mut sandbox);
+        let dir = msg_root.join("ses1");
+        write_json(
+            &dir.join("b.json"),
+            &serde_json::json!({"id": "m2", "sessionID": "ses1", "role": "assistant", "time": {"created": 200}}),
+        );
+        write_json(
+            &dir.join("a.json"),
+            &serde_json::json!({"id": "m1", "sessionID": "ses1", "role": "user", "time": {"created": 100}}),
+        );
+        fs::write(dir.join("broken.json"), "{not json").unwrap();
+        fs::write(dir.join("ignored.txt"), "nope").unwrap();
+
+        let messages = read_messages("ses1").unwrap();
+        assert_eq!(
+            messages.iter().map(|m| m.id.as_str()).collect::<Vec<_>>(),
+            vec!["m1", "m2"]
+        );
+        // The broken file was quarantined.
+        let (count, paths) = get_recovery_corruption_stats();
+        assert_eq!(count, 1);
+        assert_eq!(paths.len(), 1);
+        assert!(paths[0].contains("broken.json.corrupt-"));
+        assert!(!dir.join("broken.json").exists());
+    }
+
+    #[test]
+    #[serial(env)]
+    fn read_messages_quarantines_invalid_shape_records() {
+        let mut sandbox = EnvSandbox::new();
+        let (msg_root, _) = setup_storage(&mut sandbox);
+        let dir = msg_root.join("ses2");
+        // Missing id.
+        write_json(&dir.join("noid.json"), &serde_json::json!({"role": "assistant"}));
+        // Path-unsafe id (recovery-02).
+        write_json(
+            &dir.join("evil.json"),
+            &serde_json::json!({"id": "../poison", "role": "assistant"}),
+        );
+        // Non-numeric time.created (recovery-02).
+        write_json(
+            &dir.join("badtime.json"),
+            &serde_json::json!({"id": "m3", "time": {"created": "oops"}}),
+        );
+        let messages = read_messages("ses2").unwrap();
+        assert!(messages.is_empty());
+        let (count, _) = get_recovery_corruption_stats();
+        assert_eq!(count, 3);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn read_parts_parses_and_quarantines() {
+        let mut sandbox = EnvSandbox::new();
+        let (_, part_root) = setup_storage(&mut sandbox);
+        assert!(read_parts("m1").unwrap().is_empty());
+
+        let dir = part_root.join("m1");
+        write_json(
+            &dir.join("p1.json"),
+            &serde_json::json!({"id": "p1", "sessionID": "s", "messageID": "m1", "type": "text", "text": "hi"}),
+        );
+        // Parseable but missing type (recovery-02).
+        write_json(&dir.join("p2.json"), &serde_json::json!({"id": "p2"}));
+        fs::write(dir.join("p3.json"), "{oops").unwrap();
+
+        let parts = read_parts("m1").unwrap();
+        assert_eq!(parts.len(), 1);
+        assert_eq!(parts[0].id, "p1");
+        let (count, _) = get_recovery_corruption_stats();
+        assert_eq!(count, 2);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn read_paths_reject_unsafe_ids() {
+        let mut sandbox = EnvSandbox::new();
+        let _ = setup_storage(&mut sandbox);
+        let err = read_parts("../evil").unwrap_err();
+        assert_eq!(err, "Invalid messageID: contains unsafe characters");
+        let err = get_message_dir("a/b").unwrap_err();
+        assert_eq!(err, "Invalid sessionID: contains unsafe characters");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn has_content_classification_matches_ts() {
+        let part = |t: &str, text: Option<&str>| -> StoredPart {
+            let mut value = serde_json::json!({"id": "p", "sessionID": "s", "messageID": "m", "type": t});
+            if let Some(text) = text {
+                value["text"] = Value::String(text.to_string());
+            }
+            serde_json::from_value(value).unwrap()
+        };
+        assert!(!has_content(&part("thinking", Some("x"))));
+        assert!(!has_content(&part("redacted_thinking", None)));
+        assert!(!has_content(&part("reasoning", None)));
+        assert!(!has_content(&part("step-start", None)));
+        assert!(!has_content(&part("step-finish", None)));
+        assert!(has_content(&part("text", Some("hello"))));
+        assert!(!has_content(&part("text", Some("   "))));
+        assert!(!has_content(&part("text", None)));
+        assert!(has_content(&part("tool", None)));
+        assert!(has_content(&part("tool_use", None)));
+        assert!(has_content(&part("tool_result", None)));
+        assert!(!has_content(&part("mystery", None)));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn inject_text_part_writes_synthetic_part() {
+        let mut sandbox = EnvSandbox::new();
+        let (_, part_root) = setup_storage(&mut sandbox);
+        assert!(inject_text_part("ses1", "m1", "recovered"));
+        let dir = part_root.join("m1");
+        let files: Vec<_> = fs::read_dir(&dir).unwrap().flatten().collect();
+        assert_eq!(files.len(), 1);
+        let written: Value =
+            serde_json::from_str(&fs::read_to_string(files[0].path()).unwrap()).unwrap();
+        assert_eq!(written["type"], "text");
+        assert_eq!(written["text"], "recovered");
+        assert_eq!(written["synthetic"], true);
+        assert_eq!(written["sessionID"], "ses1");
+        assert_eq!(written["messageID"], "m1");
+        // Rejects unsafe ids.
+        assert!(!inject_text_part("ses1", "../evil", "x"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn thinking_finders_match_ts_semantics() {
+        let mut sandbox = EnvSandbox::new();
+        let (msg_root, part_root) = setup_storage(&mut sandbox);
+        let dir = msg_root.join("ses1");
+        write_json(
+            &dir.join("m1.json"),
+            &serde_json::json!({"id": "m1", "role": "assistant", "time": {"created": 1}}),
+        );
+        write_json(
+            &dir.join("m2.json"),
+            &serde_json::json!({"id": "m2", "role": "assistant", "time": {"created": 2}}),
+        );
+        write_json(
+            &dir.join("m3.json"),
+            &serde_json::json!({"id": "m3", "role": "user", "time": {"created": 3}}),
+        );
+        // m1: thinking first + text content.
+        write_json(
+            &part_root.join("m1").join("a.json"),
+            &serde_json::json!({"id": "p0", "sessionID": "ses1", "messageID": "m1", "type": "thinking", "thinking": "t"}),
+        );
+        write_json(
+            &part_root.join("m1").join("b.json"),
+            &serde_json::json!({"id": "p1", "sessionID": "ses1", "messageID": "m1", "type": "text", "text": "content"}),
+        );
+        // m2: text only (first sorted part not thinking).
+        write_json(
+            &part_root.join("m2").join("a.json"),
+            &serde_json::json!({"id": "p2", "sessionID": "ses1", "messageID": "m2", "type": "text", "text": "content"}),
+        );
+
+        assert_eq!(find_messages_with_thinking_blocks("ses1").unwrap(), vec!["m1"]);
+        assert!(find_messages_with_thinking_only("ses1").unwrap().is_empty());
+        assert_eq!(find_messages_with_orphan_thinking("ses1").unwrap(), vec!["m2"]);
+
+        // Orphan thinking (thinking but no content) on m2 after adding
+        // thinking and removing text.
+        fs::remove_file(part_root.join("m2").join("a.json")).unwrap();
+        write_json(
+            &part_root.join("m2").join("t.json"),
+            &serde_json::json!({"id": "p3", "sessionID": "ses1", "messageID": "m2", "type": "thinking", "thinking": ""}),
+        );
+        assert_eq!(find_messages_with_thinking_only("ses1").unwrap(), vec!["m2"]);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn prepend_thinking_part_generates_unique_sorted_ids() {
+        let mut sandbox = EnvSandbox::new();
+        let (_, part_root) = setup_storage(&mut sandbox);
+        assert!(prepend_thinking_part("ses1", "m1"));
+        assert!(prepend_thinking_part("ses1", "m1"));
+        let files: Vec<_> = fs::read_dir(part_root.join("m1")).unwrap().flatten().collect();
+        // RPTU-001: repeat passes must not overwrite the prior synthetic part.
+        assert_eq!(files.len(), 2);
+
+        // Synthetic ids sort before real generate_part_id output.
+        let synthetic = generate_thinking_part_id();
+        let real = generate_part_id();
+        assert!(synthetic < real, "{synthetic} should sort before {real}");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn strip_thinking_parts_removes_only_thinking() {
+        let mut sandbox = EnvSandbox::new();
+        let (_, part_root) = setup_storage(&mut sandbox);
+        assert!(!strip_thinking_parts("mmissing"));
+
+        let dir = part_root.join("m1");
+        write_json(
+            &dir.join("think.json"),
+            &serde_json::json!({"id": "p1", "sessionID": "s", "messageID": "m1", "type": "thinking", "thinking": "x"}),
+        );
+        write_json(
+            &dir.join("text.json"),
+            &serde_json::json!({"id": "p2", "sessionID": "s", "messageID": "m1", "type": "text", "text": "keep"}),
+        );
+        assert!(strip_thinking_parts("m1"));
+        assert!(!dir.join("think.json").exists());
+        assert!(dir.join("text.json").exists());
+        // Nothing left to remove now.
+        assert!(!strip_thinking_parts("m1"));
+        // Unsafe id → false, not panic.
+        assert!(!strip_thinking_parts("../evil"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn empty_message_index_probing_matches_ts() {
+        let mut sandbox = EnvSandbox::new();
+        let (msg_root, part_root) = setup_storage(&mut sandbox);
+        let dir = msg_root.join("ses1");
+        for (i, id) in ["m1", "m2", "m3"].iter().enumerate() {
+            write_json(
+                &dir.join(format!("{id}.json")),
+                &serde_json::json!({"id": id, "role": "assistant", "time": {"created": i as i64 + 1}}),
+            );
+        }
+        // Only m2 has content.
+        write_json(
+            &part_root.join("m2").join("p.json"),
+            &serde_json::json!({"id": "p1", "sessionID": "ses1", "messageID": "m2", "type": "text", "text": "content"}),
+        );
+
+        assert_eq!(find_empty_messages("ses1").unwrap(), vec!["m1", "m3"]);
+        // Exact index empty → hit.
+        assert_eq!(find_empty_message_by_index("ses1", 0).unwrap(), Some("m1".into()));
+        // Index 1 has content → fallback probes index 0 (i-1).
+        assert_eq!(find_empty_message_by_index("ses1", 1).unwrap(), Some("m1".into()));
+        // Out of range probes fall back into range.
+        assert_eq!(find_empty_message_by_index("ses1", 4).unwrap(), Some("m3".into()));
+
+        // findMessageByIndexNeedingThinking: exact index only.
+        assert_eq!(
+            find_message_by_index_needing_thinking("ses1", 5).unwrap(),
+            None
+        );
+        assert_eq!(
+            find_message_by_index_needing_thinking("ses1", 1).unwrap(),
+            Some("m2".into())
+        );
+        // m1 has no parts → null.
+        assert_eq!(find_message_by_index_needing_thinking("ses1", 0).unwrap(), None);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn replace_empty_text_parts_rewrites_blank_text() {
+        let mut sandbox = EnvSandbox::new();
+        let (_, part_root) = setup_storage(&mut sandbox);
+        let dir = part_root.join("m1");
+        write_json(
+            &dir.join("blank.json"),
+            &serde_json::json!({"id": "p1", "sessionID": "s", "messageID": "m1", "type": "text", "text": "  "}),
+        );
+        write_json(
+            &dir.join("full.json"),
+            &serde_json::json!({"id": "p2", "sessionID": "s", "messageID": "m1", "type": "text", "text": "keep"}),
+        );
+        assert!(replace_empty_text_parts("m1", "[recovered]"));
+        let blank: Value =
+            serde_json::from_str(&fs::read_to_string(dir.join("blank.json")).unwrap()).unwrap();
+        assert_eq!(blank["text"], "[recovered]");
+        assert_eq!(blank["synthetic"], true);
+        let full: Value =
+            serde_json::from_str(&fs::read_to_string(dir.join("full.json")).unwrap()).unwrap();
+        assert_eq!(full["text"], "keep");
+        assert!(full.get("synthetic").is_none());
+
+        assert_eq!(find_messages_with_empty_text_parts("ses-none").unwrap(), Vec::<String>::new());
+    }
+}
diff --git a/crates/runtime/src/recovery/types.rs b/crates/runtime/src/recovery/types.rs
new file mode 100644
index 000000000..902ce2171
--- /dev/null
+++ b/crates/runtime/src/recovery/types.rs
@@ -0,0 +1,282 @@
+//! Port of `lib/recovery/types.ts` — session-recovery record shapes
+//! (spec 11 §6.2).
+//!
+//! Storage records are read tolerantly: the TS validators only require a
+//! SAFE string `id` (+ string `type` for parts, and a finite numeric
+//! `time.created` when `time` is present). Everything else is permissive, so
+//! the Rust structs model non-guaranteed fields as `Option`/`Value` and keep
+//! unknown keys in `extra` (round-trip safe: the repair paths rewrite files).
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// TS `StoredMessageMeta` — message metadata on disk. Only `id` is
+/// guaranteed by validation; `role`/`time` may be missing or partial.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct StoredMessageMeta {
+    pub id: String,
+    #[serde(rename = "sessionID", default, skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<String>,
+    #[serde(rename = "parentID", default, skip_serializing_if = "Option::is_none")]
+    pub parent_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub time: Option<StoredMessageTime>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<Value>,
+    /// Unknown keys survive (tolerant read).
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, Value>,
+}
+
+impl StoredMessageMeta {
+    /// TS `msg.role === "assistant"` check.
+    pub fn is_assistant(&self) -> bool {
+        self.role.as_deref() == Some("assistant")
+    }
+
+    /// TS `msg.role === "user"` check.
+    pub fn is_user(&self) -> bool {
+        self.role.as_deref() == Some("user")
+    }
+
+    /// TS `a?.time?.created ?? 0` sort key (float-preserving).
+    pub fn created_sort_key(&self) -> f64 {
+        self.time
+            .as_ref()
+            .and_then(|t| t.created.as_ref())
+            .and_then(Value::as_f64)
+            .unwrap_or(0.0)
+    }
+}
+
+/// The `time` object of a stored message. `created` is kept as a raw
+/// [`Value`] because validation only constrains it *when present*.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct StoredMessageTime {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub completed: Option<Value>,
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, Value>,
+}
+
+/// TS `StoredPart` — the open union of stored part shapes. Only `id` and
+/// `type` are validated; the typed accessors below expose the fields the
+/// recovery paths need (`text`, `callID`, `tool`, `state.input`).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct StoredPart {
+    pub id: String,
+    #[serde(rename = "sessionID", default, skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+    #[serde(rename = "messageID", default, skip_serializing_if = "Option::is_none")]
+    pub message_id: Option<String>,
+    #[serde(rename = "type")]
+    pub part_type: String,
+    /// Unknown/typed-variant keys (text, callID, tool, state, thinking,
+    /// synthetic, ignored, ...) kept raw for tolerant round-trips.
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, Value>,
+}
+
+impl StoredPart {
+    /// The `text` field when it is a string (non-string values behave as
+    /// missing — see storage.rs `has_content` note).
+    pub fn text(&self) -> Option<&str> {
+        self.extra.get("text").and_then(Value::as_str)
+    }
+
+    /// Whether the raw record carries a `callID` key at all (TS `"callID" in p`).
+    pub fn has_call_id_key(&self) -> bool {
+        self.extra.contains_key("callID")
+    }
+
+    /// The `callID` value when it is a string.
+    pub fn call_id(&self) -> Option<&str> {
+        self.extra.get("callID").and_then(Value::as_str)
+    }
+
+    /// The `tool` name when it is a string.
+    pub fn tool(&self) -> Option<&str> {
+        self.extra.get("tool").and_then(Value::as_str)
+    }
+
+    /// `state.input` when present.
+    pub fn state_input(&self) -> Option<&Value> {
+        self.extra.get("state").and_then(|s| s.get("input"))
+    }
+}
+
+// =============================================================================
+// API types (host SDK responses)
+// =============================================================================
+
+/// TS `MessagePart` (API shape).
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct MessagePart {
+    #[serde(rename = "type")]
+    pub part_type: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub thinking: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input: Option<Value>,
+    #[serde(rename = "callID", default, skip_serializing_if = "Option::is_none")]
+    pub call_id: Option<String>,
+}
+
+/// Model reference (`{providerID, modelID}`).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModelRef {
+    #[serde(rename = "providerID")]
+    pub provider_id: String,
+    #[serde(rename = "modelID")]
+    pub model_id: String,
+}
+
+/// TS `MessageData.info`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct MessageDataInfo {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<String>,
+    #[serde(rename = "sessionID", default, skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+    #[serde(rename = "parentID", default, skip_serializing_if = "Option::is_none")]
+    pub parent_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<ModelRef>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub system: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tools: Option<Value>,
+}
+
+/// TS `MessageData` (API message).
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct MessageData {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub info: Option<MessageDataInfo>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parts: Option<Vec<MessagePart>>,
+}
+
+/// TS `MessageInfo` — the hook input.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct MessageInfo {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<String>,
+    #[serde(rename = "sessionID", default, skip_serializing_if = "Option::is_none")]
+    pub session_id: Option<String>,
+    #[serde(rename = "parentID", default, skip_serializing_if = "Option::is_none")]
+    pub parent_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<Value>,
+}
+
+/// TS `ResumeConfig`.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ResumeConfig {
+    #[serde(rename = "sessionID")]
+    pub session_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<ModelRef>,
+}
+
+/// TS `RecoveryErrorType` (non-null variants; the TS `null` is
+/// `Option::<RecoveryErrorType>::None`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum RecoveryErrorType {
+    #[serde(rename = "tool_result_missing")]
+    ToolResultMissing,
+    #[serde(rename = "thinking_block_order")]
+    ThinkingBlockOrder,
+    #[serde(rename = "thinking_disabled_violation")]
+    ThinkingDisabledViolation,
+}
+
+impl RecoveryErrorType {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ToolResultMissing => "tool_result_missing",
+            Self::ThinkingBlockOrder => "thinking_block_order",
+            Self::ThinkingDisabledViolation => "thinking_disabled_violation",
+        }
+    }
+}
+
+/// TS `ToolResultPart`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ToolResultPart {
+    /// Always `"tool_result"`.
+    #[serde(rename = "type")]
+    pub part_type: String,
+    pub tool_use_id: String,
+    pub content: String,
+}
+
+impl ToolResultPart {
+    pub fn new(tool_use_id: impl Into<String>, content: impl Into<String>) -> Self {
+        Self {
+            part_type: "tool_result".to_string(),
+            tool_use_id: tool_use_id.into(),
+            content: content.into(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn stored_part_accessors_read_variant_fields() {
+        let part: StoredPart = serde_json::from_value(json!({
+            "id": "prt_1", "sessionID": "s", "messageID": "m",
+            "type": "tool", "callID": "call_9", "tool": "bash",
+            "state": {"status": "running", "input": {"cmd": "ls"}}
+        }))
+        .unwrap();
+        assert!(part.has_call_id_key());
+        assert_eq!(part.call_id(), Some("call_9"));
+        assert_eq!(part.tool(), Some("bash"));
+        assert_eq!(part.state_input().unwrap()["cmd"], json!("ls"));
+        assert_eq!(part.text(), None);
+    }
+
+    #[test]
+    fn stored_message_sort_key_defaults_to_zero() {
+        let msg: StoredMessageMeta =
+            serde_json::from_value(json!({"id": "m1", "role": "assistant"})).unwrap();
+        assert_eq!(msg.created_sort_key(), 0.0);
+        assert!(msg.is_assistant());
+        let with_time: StoredMessageMeta =
+            serde_json::from_value(json!({"id": "m2", "time": {"created": 5.5}})).unwrap();
+        assert_eq!(with_time.created_sort_key(), 5.5);
+    }
+
+    #[test]
+    fn stored_records_round_trip_unknown_keys() {
+        let raw = json!({"id": "m1", "custom": {"a": 1}, "role": "user"});
+        let msg: StoredMessageMeta = serde_json::from_value(raw.clone()).unwrap();
+        let back = serde_json::to_value(&msg).unwrap();
+        assert_eq!(back["custom"], raw["custom"]);
+    }
+}
diff --git a/crates/runtime/src/refresh_guardian.rs b/crates/runtime/src/refresh_guardian.rs
new file mode 100644
index 000000000..e0d59eaff
--- /dev/null
+++ b/crates/runtime/src/refresh_guardian.rs
@@ -0,0 +1,1139 @@
+//! Port of `lib/refresh-guardian.ts` (the `RefreshGuardian` background
+//! loop) + `lib/runtime/refresh-guardian.ts` (the
+//! `ensureRuntimeRefreshGuardian` lifecycle helper, absorbed entry:
+//! `refresh-guardian-entry.ts`). Spec 10 §21, ARCHITECTURE §6.12: 60 s
+//! loop, family `"codex"` bookkeeping, disable-on-no-refresh-token.
+//!
+//! The interval task is spawned on the ambient tokio runtime (the TS timer
+//! was `unref()`'d — tokio tasks likewise never keep a process alive on
+//! their own); lifecycle owners register a stop cleanup with
+//! `cma_core::shutdown` through [`ensure_runtime_refresh_guardian`]'s
+//! `register_cleanup` seam.
+
+use crate::proactive_refresh::{
+    refresh_expiring_accounts_with, queued_refresh_fn, ProactiveRefreshReason,
+    ProactiveRefreshResult, RefreshFn,
+};
+use cma_accounts::manager::{AccountIdentityCandidate, ManagedAccount};
+use cma_accounts::manager_persistence::{SharedAccountManager, SAVE_DEBOUNCE_DEFAULT_MS};
+use cma_core::constants::ACCOUNT_LIMITS;
+use cma_core::errors::CodexError;
+use cma_core::logger::{create_logger, ScopedLogger};
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::CooldownReason;
+use cma_core::schemas::token::TokenResult;
+use cma_core::types::OAuthAuthDetails;
+use cma_core::utils::now_ms;
+use serde_json::json;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, LazyLock, Mutex as StdMutex};
+
+fn log() -> &'static ScopedLogger {
+    static LOG: LazyLock<ScopedLogger> = LazyLock::new(|| create_logger("refresh-guardian"));
+    &LOG
+}
+
+const REFRESH_HEALTH_FAMILY: ModelFamily = ModelFamily::Codex;
+const DEFAULT_INTERVAL_MS: i64 = 60_000;
+const NETWORK_FAILURE_COOLDOWN_MS: i64 = 6_000;
+
+/// TS `RefreshGuardianOptions`.
+#[derive(Default, Clone)]
+pub struct RefreshGuardianOptions {
+    pub interval_ms: Option<f64>,
+    pub buffer_ms: Option<f64>,
+    /// Test seam replacing the TS `vi.mock` of `queuedRefresh`. `None` uses
+    /// the global refresh queue.
+    pub refresh_fn: Option<RefreshFn>,
+}
+
+/// TS `RefreshGuardianStats`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct RefreshGuardianStats {
+    pub runs: i64,
+    pub refreshed: i64,
+    pub failed: i64,
+    pub not_needed: i64,
+    pub no_refresh_token: i64,
+    pub rate_limited: i64,
+    pub network_failed: i64,
+    pub auth_failed: i64,
+    pub last_run_at: Option<i64>,
+}
+
+/// The manager accessor (TS `getAccountManager: () => AccountManager |
+/// null`).
+pub type GetAccountManagerFn = Arc<dyn Fn() -> Option<SharedAccountManager> + Send + Sync>;
+
+struct GuardianInner {
+    get_account_manager: GetAccountManagerFn,
+    interval_ms: i64,
+    buffer_ms: i64,
+    refresh_fn: RefreshFn,
+    running: AtomicBool,
+    stats: StdMutex<RefreshGuardianStats>,
+    timer: StdMutex<Option<tokio::task::JoinHandle<()>>>,
+}
+
+/// TS `class RefreshGuardian` — cheaply clonable handle (the interval task
+/// holds one).
+#[derive(Clone)]
+pub struct RefreshGuardian {
+    inner: Arc<GuardianInner>,
+}
+
+impl RefreshGuardian {
+    /// TS `constructor(getAccountManager, options)` — interval floor 5 s,
+    /// buffer floor 30 s.
+    pub fn new(get_account_manager: GetAccountManagerFn, options: RefreshGuardianOptions) -> Self {
+        let interval_ms = options
+            .interval_ms
+            .unwrap_or(DEFAULT_INTERVAL_MS as f64)
+            .floor()
+            .max(5_000.0) as i64;
+        let buffer_ms = options
+            .buffer_ms
+            .unwrap_or((5 * 60_000) as f64)
+            .floor()
+            .max(30_000.0) as i64;
+        Self {
+            inner: Arc::new(GuardianInner {
+                get_account_manager,
+                interval_ms,
+                buffer_ms,
+                refresh_fn: options.refresh_fn.unwrap_or_else(queued_refresh_fn),
+                running: AtomicBool::new(false),
+                stats: StdMutex::new(RefreshGuardianStats::default()),
+                timer: StdMutex::new(None),
+            }),
+        }
+    }
+
+    pub fn interval_ms(&self) -> i64 {
+        self.inner.interval_ms
+    }
+
+    pub fn buffer_ms(&self) -> i64 {
+        self.inner.buffer_ms
+    }
+
+    /// TS `start()` — idempotent; spawns the interval loop (first tick
+    /// after one interval, `setInterval` parity). Must be called from
+    /// within a tokio runtime.
+    pub fn start(&self) {
+        let mut timer = self.inner.timer.lock().expect("guardian timer poisoned");
+        if timer.is_some() {
+            return;
+        }
+        let guardian = self.clone();
+        *timer = Some(tokio::spawn(async move {
+            loop {
+                cma_core::utils::sleep(guardian.inner.interval_ms as u64).await;
+                guardian.tick().await;
+            }
+        }));
+        log().debug(
+            "Refresh guardian started",
+            Some(&json!({
+                "intervalMs": self.inner.interval_ms,
+                "bufferMs": self.inner.buffer_ms,
+            })),
+        );
+    }
+
+    /// TS `stop()` — idempotent.
+    pub fn stop(&self) {
+        let mut timer = self.inner.timer.lock().expect("guardian timer poisoned");
+        if let Some(handle) = timer.take() {
+            handle.abort();
+        }
+    }
+
+    /// TS `getStats()` — a copy.
+    pub fn get_stats(&self) -> RefreshGuardianStats {
+        self.inner.stats.lock().expect("guardian stats poisoned").clone()
+    }
+
+    /// TS `async tick()` — one guardian pass; re-entrancy-guarded.
+    pub async fn tick(&self) {
+        // TS: `if (this.running) return;` then manager lookup, then
+        // `running = true`.
+        if self.inner.running.load(Ordering::SeqCst) {
+            return;
+        }
+        let Some(manager) = (self.inner.get_account_manager)() else {
+            return;
+        };
+        if self.inner.running.swap(true, Ordering::SeqCst) {
+            return;
+        }
+        self.run_tick(&manager).await;
+        self.inner.running.store(false, Ordering::SeqCst);
+    }
+
+    async fn run_tick(&self, manager: &SharedAccountManager) {
+        let snapshot: Vec<ManagedAccount> = {
+            let mut pool = manager.lock().await;
+            pool.get_accounts_snapshot()
+                .into_iter()
+                .filter(|account| account.is_enabled())
+                .collect()
+        };
+        if snapshot.is_empty() {
+            return;
+        }
+
+        let eligible: Vec<ManagedAccount> = {
+            let mut pool = manager.lock().await;
+            snapshot
+                .into_iter()
+                .filter(|account| !pool.is_account_cooling_down(account.index as i64))
+                .collect()
+        };
+        if eligible.is_empty() {
+            let mut stats = self.inner.stats.lock().expect("guardian stats poisoned");
+            stats.runs += 1;
+            stats.last_run_at = Some(now_ms());
+            return;
+        }
+
+        let requires_save = Arc::new(AtomicBool::new(false));
+        let on_result = {
+            let inner = self.inner.clone();
+            let manager = manager.clone();
+            let requires_save = requires_save.clone();
+            Box::new(
+                move |account: ManagedAccount, result: ProactiveRefreshResult| {
+                    let inner = inner.clone();
+                    let manager = manager.clone();
+                    let requires_save = requires_save.clone();
+                    Box::pin(async move {
+                        let save_needed =
+                            apply_refresh_outcome(&inner, &manager, &account, &result).await;
+                        if save_needed {
+                            requires_save.store(true, Ordering::SeqCst);
+                        }
+                    }) as std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>>
+                },
+            )
+        };
+
+        let refresh_results = refresh_expiring_accounts_with(
+            &eligible,
+            self.inner.buffer_ms,
+            Some(on_result),
+            &self.inner.refresh_fn,
+        )
+        .await;
+
+        if refresh_results.is_empty() {
+            let mut stats = self.inner.stats.lock().expect("guardian stats poisoned");
+            stats.runs += 1;
+            stats.last_run_at = Some(now_ms());
+            return;
+        }
+
+        if requires_save.load(Ordering::SeqCst) {
+            manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+        }
+        let mut stats = self.inner.stats.lock().expect("guardian stats poisoned");
+        stats.runs += 1;
+        stats.last_run_at = Some(now_ms());
+    }
+}
+
+fn identity_candidate(account: &ManagedAccount) -> AccountIdentityCandidate {
+    AccountIdentityCandidate {
+        account_id: account.meta.account_id.clone(),
+        email: account.meta.email.clone(),
+        refresh_token: Some(account.meta.refresh_token.clone()),
+        index: Some(account.index as i64),
+    }
+}
+
+/// TS private `classifyFailureReason(tokenResult)`.
+fn classify_failure_reason(token_result: Option<&TokenResult>) -> CooldownReason {
+    let Some(TokenResult::Failed(failure)) = token_result else {
+        return CooldownReason::NetworkError;
+    };
+    use cma_core::schemas::token::TokenFailureReason as Reason;
+    if failure.status_code == Some(429) {
+        return CooldownReason::RateLimit;
+    }
+    match failure.reason {
+        Some(Reason::NetworkError) => CooldownReason::NetworkError,
+        Some(Reason::MissingRefresh) | Some(Reason::InvalidResponse) => CooldownReason::AuthFailure,
+        Some(Reason::HttpError)
+            if matches!(failure.status_code, Some(400) | Some(401) | Some(403)) =>
+        {
+            CooldownReason::AuthFailure
+        }
+        _ => CooldownReason::NetworkError,
+    }
+}
+
+fn network_failure_cooldown_ms(buffer_ms: i64) -> i64 {
+    buffer_ms.min(NETWORK_FAILURE_COOLDOWN_MS)
+}
+
+fn auth_failure_cooldown_ms(buffer_ms: i64, failure_count: u32) -> i64 {
+    let streak = i64::from(failure_count).max(1);
+    buffer_ms.min(ACCOUNT_LIMITS.auth_failure_cooldown_ms * streak)
+}
+
+/// Locate the live account by identity and apply the network-failure
+/// treatment (clear auth failures, short network cooldown, health failure).
+/// Returns whether an account was found (⇒ save needed).
+async fn apply_network_failure(
+    inner: &GuardianInner,
+    manager: &SharedAccountManager,
+    candidate: &AccountIdentityCandidate,
+    auth: Option<&OAuthAuthDetails>,
+) -> bool {
+    let mut pool = manager.lock().await;
+    let account_index = pool
+        .get_account_by_identity(candidate, auth)
+        .map(|account| account.index as i64)
+        .or_else(|| {
+            auth.and_then(|_| {
+                pool.get_account_by_identity(candidate, None)
+                    .map(|account| account.index as i64)
+            })
+        });
+    let Some(index) = account_index else {
+        return false;
+    };
+    if let Some(live) = pool.get_account_by_index_mut(index) {
+        live.clear_auth_failures();
+    }
+    pool.mark_account_cooling_down(
+        index,
+        network_failure_cooldown_ms(inner.buffer_ms),
+        CooldownReason::NetworkError,
+    );
+    pool.record_failure(index, REFRESH_HEALTH_FAMILY, None);
+    true
+}
+
+/// TS private `applyRefreshOutcome(manager, sourceAccount, result)` —
+/// returns `true` when the caller must schedule a debounced save.
+async fn apply_refresh_outcome(
+    inner: &GuardianInner,
+    manager: &SharedAccountManager,
+    source_account: &ManagedAccount,
+    result: &ProactiveRefreshResult,
+) -> bool {
+    let candidate = identity_candidate(source_account);
+    match result.reason {
+        ProactiveRefreshReason::Success => {
+            let Some(TokenResult::Success(token)) = result.token_result.as_ref() else {
+                // Defensive TS branch: a "success" result without a success
+                // token is treated as a network failure.
+                let found = apply_network_failure(inner, manager, &candidate, None).await;
+                let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+                stats.failed += 1;
+                stats.network_failed += 1;
+                return found;
+            };
+
+            let refreshed_auth = OAuthAuthDetails {
+                access: token.access.clone(),
+                refresh: token.refresh.clone(),
+                expires: token.expires,
+            };
+            let commit_result: Result<Option<usize>, CodexError> = {
+                let mut pool = manager.lock().await;
+                pool.commit_refreshed_auth(&candidate, &refreshed_auth).await
+            };
+            match commit_result {
+                Ok(Some(committed_index)) => {
+                    // recordSuccess schedules its own debounced save when it
+                    // heals state (SharedAccountManager wrapper parity).
+                    manager
+                        .record_success(committed_index as i64, REFRESH_HEALTH_FAMILY, None)
+                        .await;
+                    let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+                    stats.refreshed += 1;
+                    false
+                }
+                Ok(None) => {
+                    let found =
+                        apply_network_failure(inner, manager, &candidate, Some(&refreshed_auth))
+                            .await;
+                    let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+                    stats.failed += 1;
+                    stats.network_failed += 1;
+                    found
+                }
+                Err(error) => {
+                    log().warn(
+                        "Refresh guardian commit failed",
+                        Some(&json!({
+                            "sourceIndex": source_account.index,
+                            "error": error.to_string(),
+                        })),
+                    );
+                    let cooldown_reason = match &error {
+                        CodexError::Auth { retryable, .. } if !*retryable => {
+                            CooldownReason::AuthFailure
+                        }
+                        _ => CooldownReason::NetworkError,
+                    };
+                    let found = {
+                        let mut pool = manager.lock().await;
+                        let account_index = pool
+                            .get_account_by_identity(&candidate, Some(&refreshed_auth))
+                            .map(|account| account.index as i64)
+                            .or_else(|| {
+                                pool.get_account_by_identity(&candidate, None)
+                                    .map(|account| account.index as i64)
+                            });
+                        if let Some(index) = account_index {
+                            if cooldown_reason == CooldownReason::AuthFailure {
+                                let failure_count = pool
+                                    .get_account_by_index_mut(index)
+                                    .map(|live| live.increment_auth_failures())
+                                    .unwrap_or(1);
+                                pool.mark_account_cooling_down(
+                                    index,
+                                    auth_failure_cooldown_ms(inner.buffer_ms, failure_count),
+                                    cooldown_reason,
+                                );
+                            } else {
+                                if let Some(live) = pool.get_account_by_index_mut(index) {
+                                    live.clear_auth_failures();
+                                }
+                                pool.mark_account_cooling_down(
+                                    index,
+                                    network_failure_cooldown_ms(inner.buffer_ms),
+                                    cooldown_reason,
+                                );
+                            }
+                            pool.record_failure(index, REFRESH_HEALTH_FAMILY, None);
+                            true
+                        } else {
+                            false
+                        }
+                    };
+                    let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+                    stats.failed += 1;
+                    if cooldown_reason == CooldownReason::AuthFailure {
+                        stats.auth_failed += 1;
+                    } else {
+                        stats.network_failed += 1;
+                    }
+                    found
+                }
+            }
+        }
+        ProactiveRefreshReason::Failed => {
+            let mut pool = manager.lock().await;
+            let Some(index) = pool
+                .get_account_by_identity(&candidate, None)
+                .map(|account| account.index as i64)
+            else {
+                return false;
+            };
+            let cooldown_reason = classify_failure_reason(result.token_result.as_ref());
+            match cooldown_reason {
+                CooldownReason::RateLimit => {
+                    if let Some(live) = pool.get_account_by_index_mut(index) {
+                        live.clear_auth_failures();
+                    }
+                    pool.mark_rate_limited(index, inner.buffer_ms, ModelFamily::Codex, None);
+                    pool.record_rate_limit(index, REFRESH_HEALTH_FAMILY, None);
+                }
+                CooldownReason::AuthFailure => {
+                    let failure_count = pool
+                        .get_account_by_index_mut(index)
+                        .map(|live| live.increment_auth_failures())
+                        .unwrap_or(1);
+                    pool.mark_account_cooling_down(
+                        index,
+                        auth_failure_cooldown_ms(inner.buffer_ms, failure_count),
+                        cooldown_reason,
+                    );
+                    pool.record_failure(index, REFRESH_HEALTH_FAMILY, None);
+                }
+                _ => {
+                    if let Some(live) = pool.get_account_by_index_mut(index) {
+                        live.clear_auth_failures();
+                    }
+                    pool.mark_account_cooling_down(
+                        index,
+                        network_failure_cooldown_ms(inner.buffer_ms),
+                        cooldown_reason,
+                    );
+                    pool.record_failure(index, REFRESH_HEALTH_FAMILY, None);
+                }
+            }
+            drop(pool);
+            let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+            stats.failed += 1;
+            match cooldown_reason {
+                CooldownReason::RateLimit => stats.rate_limited += 1,
+                CooldownReason::AuthFailure => stats.auth_failed += 1,
+                _ => stats.network_failed += 1,
+            }
+            true
+        }
+        ProactiveRefreshReason::NotNeeded => {
+            let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+            stats.not_needed += 1;
+            false
+        }
+        ProactiveRefreshReason::NoRefreshToken => {
+            let mut pool = manager.lock().await;
+            let Some(index) = pool
+                .get_account_by_identity(&candidate, None)
+                .map(|account| account.index as i64)
+            else {
+                return false;
+            };
+            let failure_count = pool
+                .get_account_by_index_mut(index)
+                .map(|live| live.increment_auth_failures())
+                .unwrap_or(1);
+            pool.mark_account_cooling_down(
+                index,
+                auth_failure_cooldown_ms(inner.buffer_ms, failure_count),
+                CooldownReason::AuthFailure,
+            );
+            pool.record_failure(index, REFRESH_HEALTH_FAMILY, None);
+            pool.set_account_enabled(index, false);
+            drop(pool);
+            let mut stats = inner.stats.lock().expect("guardian stats poisoned");
+            stats.no_refresh_token += 1;
+            stats.failed += 1;
+            stats.auth_failed += 1;
+            true
+        }
+    }
+}
+
+// ============================================================================
+// `lib/runtime/refresh-guardian.ts` — ensureRuntimeRefreshGuardian
+// ============================================================================
+
+/// TS `RefreshGuardianController` (start/stop lifecycle).
+pub trait RefreshGuardianLike {
+    fn start(&self);
+    fn stop(&self);
+}
+
+impl RefreshGuardianLike for RefreshGuardian {
+    fn start(&self) {
+        RefreshGuardian::start(self)
+    }
+    fn stop(&self) {
+        RefreshGuardian::stop(self)
+    }
+}
+
+/// TS `ensureRuntimeRefreshGuardian(deps)` params — config values are
+/// precomputed by the caller (the entry shim derived them from
+/// `PluginConfig` getters; see
+/// [`crate::services::ensure_refresh_guardian_entry`]).
+pub struct EnsureRuntimeRefreshGuardianParams<'a, TGuardian: RefreshGuardianLike> {
+    pub enabled: bool,
+    pub interval_ms: f64,
+    pub buffer_ms: f64,
+    pub current_guardian: Option<Arc<TGuardian>>,
+    pub current_config_key: Option<String>,
+    pub current_cleanup_registered: bool,
+    /// Cleanup closures resolve the CURRENT guardian at shutdown time (TS
+    /// `getCurrentGuardian()?.stop()`).
+    pub get_current_guardian: Arc<dyn Fn() -> Option<Arc<TGuardian>> + Send + Sync>,
+    pub create_guardian: &'a mut dyn FnMut(f64, f64) -> Arc<TGuardian>,
+    pub register_cleanup: &'a mut dyn FnMut(Box<dyn FnOnce() + Send>),
+}
+
+/// TS `ensureRuntimeRefreshGuardian` result.
+pub struct EnsureRuntimeRefreshGuardianResult<TGuardian: RefreshGuardianLike> {
+    pub guardian: Option<Arc<TGuardian>>,
+    pub config_key: Option<String>,
+    pub cleanup_registered: bool,
+}
+
+/// JS template-literal number formatting for config keys
+/// (`${intervalMs}:${bufferMs}` — integers print without a decimal point).
+pub(crate) fn js_number_string(value: f64) -> String {
+    if value.is_finite() && value.fract() == 0.0 && value.abs() < 1e21 {
+        format!("{}", value as i64)
+    } else {
+        format!("{value}")
+    }
+}
+
+/// TS `ensureRuntimeRefreshGuardian(deps)` — disabled ⇒ stop current;
+/// matching config key ⇒ reuse; otherwise stop old, create + START a new
+/// guardian and register the stop-cleanup exactly once per process slot.
+pub fn ensure_runtime_refresh_guardian<TGuardian>(
+    params: EnsureRuntimeRefreshGuardianParams<'_, TGuardian>,
+) -> EnsureRuntimeRefreshGuardianResult<TGuardian>
+where
+    TGuardian: RefreshGuardianLike + Send + Sync + 'static,
+{
+    let EnsureRuntimeRefreshGuardianParams {
+        enabled,
+        interval_ms,
+        buffer_ms,
+        current_guardian,
+        current_config_key,
+        current_cleanup_registered,
+        get_current_guardian,
+        create_guardian,
+        register_cleanup,
+    } = params;
+
+    if !enabled {
+        if let Some(current) = current_guardian.as_ref() {
+            current.stop();
+        }
+        return EnsureRuntimeRefreshGuardianResult {
+            guardian: None,
+            config_key: None,
+            cleanup_registered: current_cleanup_registered,
+        };
+    }
+
+    let config_key = format!(
+        "{}:{}",
+        js_number_string(interval_ms),
+        js_number_string(buffer_ms)
+    );
+    if let Some(current) = current_guardian.as_ref()
+        && current_config_key.as_deref() == Some(config_key.as_str())
+    {
+        return EnsureRuntimeRefreshGuardianResult {
+            guardian: Some(current.clone()),
+            config_key: current_config_key,
+            cleanup_registered: current_cleanup_registered,
+        };
+    }
+
+    if let Some(current) = current_guardian.as_ref() {
+        current.stop();
+    }
+    let guardian = create_guardian(interval_ms, buffer_ms);
+    guardian.start();
+    let mut cleanup_registered = current_cleanup_registered;
+    if !cleanup_registered {
+        let get_current = get_current_guardian.clone();
+        register_cleanup(Box::new(move || {
+            if let Some(current) = get_current() {
+                current.stop();
+            }
+        }));
+        cleanup_registered = true;
+    }
+    EnsureRuntimeRefreshGuardianResult {
+        guardian: Some(guardian),
+        config_key: Some(config_key),
+        cleanup_registered,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_accounts::manager::AccountManager;
+    use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenSuccess};
+    use cma_core::schemas::account_storage::{
+        AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily,
+    };
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+    use std::sync::atomic::AtomicUsize;
+
+    // ---- classifyFailureReason matrix ----
+
+    fn failed(reason: Option<TokenFailureReason>, status_code: Option<i64>) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason,
+            status_code,
+            message: None,
+        })
+    }
+
+    #[test]
+    fn classify_failure_reason_matrix() {
+        use TokenFailureReason as R;
+        assert_eq!(classify_failure_reason(None), CooldownReason::NetworkError);
+        assert_eq!(
+            classify_failure_reason(Some(&failed(Some(R::HttpError), Some(429)))),
+            CooldownReason::RateLimit
+        );
+        assert_eq!(
+            classify_failure_reason(Some(&failed(Some(R::NetworkError), None))),
+            CooldownReason::NetworkError
+        );
+        assert_eq!(
+            classify_failure_reason(Some(&failed(Some(R::MissingRefresh), None))),
+            CooldownReason::AuthFailure
+        );
+        assert_eq!(
+            classify_failure_reason(Some(&failed(Some(R::InvalidResponse), None))),
+            CooldownReason::AuthFailure
+        );
+        for status in [400, 401, 403] {
+            assert_eq!(
+                classify_failure_reason(Some(&failed(Some(R::HttpError), Some(status)))),
+                CooldownReason::AuthFailure
+            );
+        }
+        assert_eq!(
+            classify_failure_reason(Some(&failed(Some(R::HttpError), Some(500)))),
+            CooldownReason::NetworkError
+        );
+        assert_eq!(
+            classify_failure_reason(Some(&failed(None, None))),
+            CooldownReason::NetworkError
+        );
+    }
+
+    #[test]
+    fn cooldown_budgets_are_clamped_by_the_buffer() {
+        assert_eq!(network_failure_cooldown_ms(300_000), 6_000);
+        assert_eq!(network_failure_cooldown_ms(4_000), 4_000);
+        // 30s * streak, capped at buffer.
+        assert_eq!(auth_failure_cooldown_ms(300_000, 1), 30_000);
+        assert_eq!(auth_failure_cooldown_ms(300_000, 3), 90_000);
+        assert_eq!(auth_failure_cooldown_ms(50_000, 3), 50_000);
+        assert_eq!(auth_failure_cooldown_ms(300_000, 0), 30_000);
+    }
+
+    #[test]
+    fn constructor_clamps_interval_and_buffer() {
+        let guardian = RefreshGuardian::new(
+            Arc::new(|| None),
+            RefreshGuardianOptions {
+                interval_ms: Some(1.0),
+                buffer_ms: Some(1.0),
+                refresh_fn: None,
+            },
+        );
+        assert_eq!(guardian.interval_ms(), 5_000);
+        assert_eq!(guardian.buffer_ms(), 30_000);
+
+        let guardian = RefreshGuardian::new(Arc::new(|| None), RefreshGuardianOptions::default());
+        assert_eq!(guardian.interval_ms(), 60_000);
+        assert_eq!(guardian.buffer_ms(), 300_000);
+    }
+
+    // ---- tick behavior against a real pool ----
+
+    fn storage_with_expiring_account(expires_at: i64) -> AccountStorageV3 {
+        let now = now_ms();
+        let mut meta = AccountMetadataV3::new("refresh-1", now - 60_000, now - 60_000);
+        meta.email = Some("account-1@example.com".to_string());
+        meta.account_id = Some("acc_1".to_string());
+        meta.access_token = Some("access-1".to_string());
+        meta.expires_at = Some(expires_at);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![meta];
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(ModelFamily::Codex, Some(0));
+        storage.active_index_by_family = Some(by_family);
+        storage
+    }
+
+    fn static_refresh(result: TokenResult, calls: Arc<AtomicUsize>) -> RefreshFn {
+        Arc::new(move |_token| {
+            calls.fetch_add(1, Ordering::SeqCst);
+            let result = result.clone();
+            Box::pin(async move { result })
+        })
+    }
+
+    fn guardian_for(manager: SharedAccountManager, refresh_fn: RefreshFn) -> RefreshGuardian {
+        RefreshGuardian::new(
+            Arc::new(move || Some(manager.clone())),
+            RefreshGuardianOptions {
+                interval_ms: Some(60_000.0),
+                buffer_ms: Some(300_000.0),
+                refresh_fn: Some(refresh_fn),
+            },
+        )
+    }
+
+    fn test_runtime() -> tokio::runtime::Runtime {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    #[serial(env)]
+    fn tick_counts_a_run_without_refreshing_fresh_tokens() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            AccountManager::reset_volatile_runtime_state();
+            let manager = SharedAccountManager::new(AccountManager::new(
+                None,
+                Some(&storage_with_expiring_account(now_ms() + 3_600_000)),
+            ));
+            let calls = Arc::new(AtomicUsize::new(0));
+            let guardian = guardian_for(
+                manager.clone(),
+                static_refresh(
+                    TokenResult::Failed(TokenFailure {
+                        reason: None,
+                        status_code: None,
+                        message: None,
+                    }),
+                    calls.clone(),
+                ),
+            );
+
+            guardian.tick().await;
+
+            // Fresh token: nothing to refresh, no refresh call, one run.
+            assert_eq!(calls.load(Ordering::SeqCst), 0);
+            let stats = guardian.get_stats();
+            assert_eq!(stats.runs, 1);
+            assert_eq!(stats.refreshed, 0);
+            assert!(stats.last_run_at.is_some());
+            manager.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn tick_commits_a_successful_refresh_and_counts_it() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            AccountManager::reset_volatile_runtime_state();
+            // Expiring inside the 5-minute buffer.
+            let manager = SharedAccountManager::new(AccountManager::new(
+                None,
+                Some(&storage_with_expiring_account(now_ms() + 60_000)),
+            ));
+            let calls = Arc::new(AtomicUsize::new(0));
+            let guardian = guardian_for(
+                manager.clone(),
+                static_refresh(
+                    TokenResult::Success(TokenSuccess {
+                        access: "access-new".to_string(),
+                        refresh: "refresh-new".to_string(),
+                        expires: now_ms() + 7_200_000,
+                        id_token: None,
+                        multi_account: None,
+                    }),
+                    calls.clone(),
+                ),
+            );
+
+            guardian.tick().await;
+
+            assert_eq!(calls.load(Ordering::SeqCst), 1);
+            let stats = guardian.get_stats();
+            assert_eq!(stats.runs, 1);
+            assert_eq!(stats.refreshed, 1);
+            assert_eq!(stats.failed, 0);
+            let live = manager.lock().await.get_account_by_index(0).cloned().unwrap();
+            assert_eq!(live.meta.access_token.as_deref(), Some("access-new"));
+            assert_eq!(live.meta.refresh_token, "refresh-new");
+            manager.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn tick_rate_limits_the_account_on_a_429_refresh_failure() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            AccountManager::reset_volatile_runtime_state();
+            let manager = SharedAccountManager::new(AccountManager::new(
+                None,
+                Some(&storage_with_expiring_account(now_ms() + 60_000)),
+            ));
+            let calls = Arc::new(AtomicUsize::new(0));
+            let guardian = guardian_for(
+                manager.clone(),
+                static_refresh(
+                    failed(Some(TokenFailureReason::HttpError), Some(429)),
+                    calls.clone(),
+                ),
+            );
+
+            guardian.tick().await;
+
+            let stats = guardian.get_stats();
+            assert_eq!(stats.failed, 1);
+            assert_eq!(stats.rate_limited, 1);
+            assert_eq!(stats.auth_failed, 0);
+            let live = manager.lock().await.get_account_by_index(0).cloned().unwrap();
+            assert!(live.rate_limit_reset_times.get("codex").is_some());
+            manager.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn tick_cools_down_the_account_on_an_auth_refresh_failure() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            AccountManager::reset_volatile_runtime_state();
+            let manager = SharedAccountManager::new(AccountManager::new(
+                None,
+                Some(&storage_with_expiring_account(now_ms() + 60_000)),
+            ));
+            let calls = Arc::new(AtomicUsize::new(0));
+            let guardian = guardian_for(
+                manager.clone(),
+                static_refresh(failed(Some(TokenFailureReason::MissingRefresh), None), calls),
+            );
+
+            guardian.tick().await;
+
+            let stats = guardian.get_stats();
+            assert_eq!(stats.failed, 1);
+            assert_eq!(stats.auth_failed, 1);
+            let live = manager.lock().await.get_account_by_index(0).cloned().unwrap();
+            assert!(live.meta.cooling_down_until.unwrap_or(0) > now_ms() - 1_000);
+            assert_eq!(
+                live.meta.cooldown_reason,
+                Some(CooldownReason::AuthFailure)
+            );
+            manager.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn tick_skips_cooling_down_accounts_but_still_counts_the_run() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            AccountManager::reset_volatile_runtime_state();
+            let manager = SharedAccountManager::new(AccountManager::new(
+                None,
+                Some(&storage_with_expiring_account(now_ms() + 60_000)),
+            ));
+            manager.lock().await.mark_account_cooling_down(
+                0,
+                60_000,
+                CooldownReason::NetworkError,
+            );
+            let calls = Arc::new(AtomicUsize::new(0));
+            let guardian = guardian_for(
+                manager.clone(),
+                static_refresh(failed(None, None), calls.clone()),
+            );
+
+            guardian.tick().await;
+
+            assert_eq!(calls.load(Ordering::SeqCst), 0);
+            let stats = guardian.get_stats();
+            assert_eq!(stats.runs, 1);
+            manager.flush_pending_save().await.ok();
+        });
+    }
+
+    // ---- ensureRuntimeRefreshGuardian (runtime-refresh-guardian.test.ts) ----
+
+    struct FakeGuardian {
+        started: AtomicUsize,
+        stopped: AtomicUsize,
+        interval_ms: f64,
+        buffer_ms: f64,
+    }
+
+    impl FakeGuardian {
+        fn new(interval_ms: f64, buffer_ms: f64) -> Arc<Self> {
+            Arc::new(Self {
+                started: AtomicUsize::new(0),
+                stopped: AtomicUsize::new(0),
+                interval_ms,
+                buffer_ms,
+            })
+        }
+    }
+
+    impl RefreshGuardianLike for FakeGuardian {
+        fn start(&self) {
+            self.started.fetch_add(1, Ordering::SeqCst);
+        }
+        fn stop(&self) {
+            self.stopped.fetch_add(1, Ordering::SeqCst);
+        }
+    }
+
+    #[test]
+    fn stops_and_clears_the_current_guardian_when_disabled() {
+        let current = FakeGuardian::new(60_000.0, 300_000.0);
+        let current_for_getter = current.clone();
+        let mut create_calls = 0usize;
+        let mut cleanup_calls = 0usize;
+        let mut create = |interval: f64, buffer: f64| {
+            create_calls += 1;
+            FakeGuardian::new(interval, buffer)
+        };
+        let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+
+        let result = ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+            enabled: false,
+            interval_ms: 60_000.0,
+            buffer_ms: 300_000.0,
+            current_guardian: Some(current.clone()),
+            current_config_key: Some("60000:300000".to_string()),
+            current_cleanup_registered: true,
+            get_current_guardian: Arc::new(move || Some(current_for_getter.clone())),
+            create_guardian: &mut create,
+            register_cleanup: &mut register,
+        });
+
+        assert!(result.guardian.is_none());
+        assert_eq!(result.config_key, None);
+        assert!(result.cleanup_registered);
+        assert_eq!(current.stopped.load(Ordering::SeqCst), 1);
+        assert_eq!(create_calls, 0);
+        assert_eq!(cleanup_calls, 0);
+    }
+
+    #[test]
+    fn returns_the_existing_guardian_when_the_config_is_unchanged() {
+        let current = FakeGuardian::new(60_000.0, 300_000.0);
+        let current_for_getter = current.clone();
+        let mut create_calls = 0usize;
+        let mut cleanup_calls = 0usize;
+        let mut create = |interval: f64, buffer: f64| {
+            create_calls += 1;
+            FakeGuardian::new(interval, buffer)
+        };
+        let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+
+        let result = ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+            enabled: true,
+            interval_ms: 60_000.0,
+            buffer_ms: 300_000.0,
+            current_guardian: Some(current.clone()),
+            current_config_key: Some("60000:300000".to_string()),
+            current_cleanup_registered: true,
+            get_current_guardian: Arc::new(move || Some(current_for_getter.clone())),
+            create_guardian: &mut create,
+            register_cleanup: &mut register,
+        });
+
+        assert!(Arc::ptr_eq(result.guardian.as_ref().unwrap(), &current));
+        assert_eq!(result.config_key.as_deref(), Some("60000:300000"));
+        assert!(result.cleanup_registered);
+        assert_eq!(create_calls, 0);
+        assert_eq!(cleanup_calls, 0);
+        assert_eq!(current.stopped.load(Ordering::SeqCst), 0);
+    }
+
+    #[test]
+    fn creates_starts_and_registers_cleanup_on_first_creation() {
+        let mut created: Vec<Arc<FakeGuardian>> = Vec::new();
+        let mut cleanup_calls = 0usize;
+        let mut create = |interval: f64, buffer: f64| {
+            let guardian = FakeGuardian::new(interval, buffer);
+            created.push(guardian.clone());
+            guardian
+        };
+        let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+
+        let result = ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+            enabled: true,
+            interval_ms: 60_000.0,
+            buffer_ms: 300_000.0,
+            current_guardian: None::<Arc<FakeGuardian>>,
+            current_config_key: None,
+            current_cleanup_registered: false,
+            get_current_guardian: Arc::new(|| None),
+            create_guardian: &mut create,
+            register_cleanup: &mut register,
+        });
+
+        let guardian = result.guardian.expect("created");
+        assert_eq!(guardian.interval_ms, 60_000.0);
+        assert_eq!(guardian.buffer_ms, 300_000.0);
+        assert_eq!(guardian.started.load(Ordering::SeqCst), 1);
+        assert_eq!(result.config_key.as_deref(), Some("60000:300000"));
+        assert!(result.cleanup_registered);
+        assert_eq!(cleanup_calls, 1);
+    }
+
+    #[test]
+    fn replaces_the_guardian_without_registering_duplicate_cleanup() {
+        let previous = FakeGuardian::new(60_000.0, 300_000.0);
+        let mut cleanup_calls = 0usize;
+        let mut create = |interval: f64, buffer: f64| FakeGuardian::new(interval, buffer);
+        let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+
+        let result = ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+            enabled: true,
+            interval_ms: 120_000.0,
+            buffer_ms: 600_000.0,
+            current_guardian: Some(previous.clone()),
+            current_config_key: Some("60000:300000".to_string()),
+            current_cleanup_registered: true,
+            get_current_guardian: Arc::new(|| None),
+            create_guardian: &mut create,
+            register_cleanup: &mut register,
+        });
+
+        assert_eq!(previous.stopped.load(Ordering::SeqCst), 1);
+        let replacement = result.guardian.expect("replacement created");
+        assert!(!Arc::ptr_eq(&replacement, &previous));
+        assert_eq!(replacement.started.load(Ordering::SeqCst), 1);
+        assert_eq!(result.config_key.as_deref(), Some("120000:600000"));
+        assert_eq!(cleanup_calls, 0);
+    }
+
+    #[test]
+    fn does_not_accumulate_cleanup_handlers_across_disable_reenable_cycles() {
+        let mut cleanup_calls = 0usize;
+        let mut create = |interval: f64, buffer: f64| FakeGuardian::new(interval, buffer);
+
+        let first = {
+            let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+            ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+                enabled: true,
+                interval_ms: 60_000.0,
+                buffer_ms: 300_000.0,
+                current_guardian: None::<Arc<FakeGuardian>>,
+                current_config_key: None,
+                current_cleanup_registered: false,
+                get_current_guardian: Arc::new(|| None),
+                create_guardian: &mut create,
+                register_cleanup: &mut register,
+            })
+        };
+        assert_eq!(cleanup_calls, 1);
+
+        let disabled = {
+            let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+            ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+                enabled: false,
+                interval_ms: 60_000.0,
+                buffer_ms: 300_000.0,
+                current_guardian: first.guardian,
+                current_config_key: first.config_key,
+                current_cleanup_registered: first.cleanup_registered,
+                get_current_guardian: Arc::new(|| None),
+                create_guardian: &mut create,
+                register_cleanup: &mut register,
+            })
+        };
+
+        {
+            let mut register = |_cleanup: Box<dyn FnOnce() + Send>| cleanup_calls += 1;
+            ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+                enabled: true,
+                interval_ms: 60_000.0,
+                buffer_ms: 300_000.0,
+                current_guardian: disabled.guardian,
+                current_config_key: disabled.config_key,
+                current_cleanup_registered: disabled.cleanup_registered,
+                get_current_guardian: Arc::new(|| None),
+                create_guardian: &mut create,
+                register_cleanup: &mut register,
+            })
+        };
+
+        assert_eq!(cleanup_calls, 1);
+    }
+}
diff --git a/crates/runtime/src/rotation/account_selection.rs b/crates/runtime/src/rotation/account_selection.rs
new file mode 100644
index 000000000..86739e7ae
--- /dev/null
+++ b/crates/runtime/src/rotation/account_selection.rs
@@ -0,0 +1,725 @@
+//! Port of `lib/runtime/rotation-account-selection.ts` — the SYNC account
+//! selector for the proxy hot path (spec 10 §8, spec 04 §339, ARCHITECTURE
+//! §6.12) — plus `normalizeForcedAccountIndex` (issue #623) from
+//! `lib/runtime-rotation-proxy.ts`.
+//!
+//! Selection precedence (exact): manual pin (#474 — fail-hard, NEVER
+//! `mark_switched`) > sequential drain-first (#509 — fallback never
+//! advances the active pointer) > session affinity (hybrid only) > hybrid
+//! selector > linear scan fallback.
+//!
+//! `choose_account` mutates the rotation cursor internally
+//! (`mark_switched`) and does NOT take the routing mutex itself — the
+//! caller wraps selection + commit in one routing-mutex acquisition when
+//! `routingMutex == "enabled"`.
+
+use crate::rotation::server_types::{skip_reason, SchedulingStrategy};
+use cma_accounts::manager::{AccountManager, ManagedAccount};
+use cma_accounts::session_affinity::SessionAffinityStore;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::SwitchReason;
+use cma_quota::runtime_policy::RuntimePolicyDecision;
+use cma_rotation::selector::HybridSelectionOptions;
+use std::collections::{HashMap, HashSet};
+
+/// Named-parameter bundle for [`choose_account`] (TS single object param).
+pub struct ChooseAccountParams<'a> {
+    pub account_manager: &'a mut AccountManager,
+    pub session_affinity_store: Option<&'a mut SessionAffinityStore>,
+    pub session_key: Option<&'a str>,
+    pub family: ModelFamily,
+    pub model: Option<&'a str>,
+    pub attempted_indexes: &'a HashSet<i64>,
+    pub now: i64,
+    pub policy: Option<&'a RuntimePolicyDecision>,
+    /// Manual pin: `switch <n>` from disk or the ephemeral forced index
+    /// (#623). `Some` = fail-hard pinned selection.
+    pub pinned_index: Option<i64>,
+    /// Rejected-candidate reasons, keyed by account index (the pinned index
+    /// may be out of range).
+    pub skip_reasons: Option<&'a mut HashMap<i64, String>>,
+    /// Sticky per-account score boosts (override policy boosts key-wise).
+    pub sticky_boost_by_account: Option<&'a HashMap<i64, f64>>,
+    pub pid_offset_enabled: bool,
+    pub scheduling_strategy: SchedulingStrategy,
+}
+
+fn record_skip(skip_reasons: &mut Option<&mut HashMap<i64, String>>, index: i64, reason: &str) {
+    if let Some(map) = skip_reasons.as_deref_mut() {
+        map.insert(index, reason.to_string());
+    }
+}
+
+fn blocked_contains(policy: Option<&RuntimePolicyDecision>, index: i64) -> bool {
+    policy.is_some_and(|policy| policy.blocked_account_indexes.contains(&index))
+}
+
+/// TS `chooseAccount(params)` — returns a CLONE of the selected account
+/// (the TS function returned the live object; callers re-fetch by index
+/// when they need to observe later mutations) or `None` when no eligible
+/// account remains.
+pub fn choose_account(params: ChooseAccountParams<'_>) -> Option<ManagedAccount> {
+    let ChooseAccountParams {
+        account_manager,
+        session_affinity_store,
+        session_key,
+        family,
+        model,
+        attempted_indexes,
+        now,
+        policy,
+        pinned_index,
+        mut skip_reasons,
+        sticky_boost_by_account,
+        pid_offset_enabled,
+        scheduling_strategy,
+    } = params;
+
+    // Manual pin (from `codex-multi-auth switch <n>`) overrides every other
+    // selection signal. We do NOT call mark_switched here — the proxy must
+    // not clobber the pin set by the CLI. See issue #474.
+    if let Some(pinned_index) = pinned_index {
+        if attempted_indexes.contains(&pinned_index) {
+            record_skip(&mut skip_reasons, pinned_index, skip_reason::ALREADY_ATTEMPTED);
+            return None;
+        }
+        if pinned_index < 0 || pinned_index >= account_manager.get_account_count() as i64 {
+            record_skip(&mut skip_reasons, pinned_index, skip_reason::MISSING);
+            return None;
+        }
+        if blocked_contains(policy, pinned_index) {
+            record_skip(&mut skip_reasons, pinned_index, skip_reason::POLICY_BLOCKED);
+            return None;
+        }
+        let pinned = account_manager.get_account_by_index(pinned_index).cloned();
+        let Some(pinned) = pinned.filter(|account| account.is_enabled()) else {
+            record_skip(&mut skip_reasons, pinned_index, skip_reason::DISABLED);
+            return None;
+        };
+        if let Some(reason) =
+            account_manager.get_account_runtime_skip_reason(pinned_index, family, model)
+        {
+            record_skip(&mut skip_reasons, pinned_index, &reason);
+            return None;
+        }
+        return Some(pinned);
+    }
+
+    // Sequential / drain-first mode (issue #509): the active account governs
+    // ALL new requests, so we deliberately SKIP the per-session affinity
+    // tier — there is no per-chat stickiness. The manual pin above still
+    // wins (handled first).
+    if scheduling_strategy == SchedulingStrategy::Sequential {
+        let blocked_usize: Option<HashSet<usize>> = policy.map(|policy| {
+            policy
+                .blocked_account_indexes
+                .iter()
+                .filter(|index| **index >= 0)
+                .map(|index| *index as usize)
+                .collect()
+        });
+        let selected = account_manager
+            .get_current_or_next_for_family_sequential(family, model, blocked_usize.as_ref())
+            .cloned();
+        if let Some(selected) = selected {
+            let selected_index = selected.index as i64;
+            if !attempted_indexes.contains(&selected_index)
+                && !blocked_contains(policy, selected_index)
+            {
+                match account_manager.get_account_runtime_skip_reason(selected_index, family, model)
+                {
+                    None => return Some(selected),
+                    Some(reason) => record_skip(&mut skip_reasons, selected_index, &reason),
+                }
+            }
+        }
+
+        // Active account was attempted/blocked/skipped this request: fall
+        // through to the shared linear scan with advance_active_pointer =
+        // false — a transient, non-exhausting failure on the active account
+        // must NOT permanently move the drain-first primary. Only
+        // get_current_or_next_for_family_sequential may advance it, and only
+        // on true exhaustion.
+        return choose_linear_scan_fallback(
+            account_manager,
+            family,
+            model,
+            attempted_indexes,
+            policy,
+            &mut skip_reasons,
+            false,
+        );
+    }
+
+    // Session-affinity tier (hybrid only).
+    let preferred_index = session_affinity_store
+        .and_then(|store| store.get_preferred_account_index(session_key, now));
+    if let Some(preferred_index) = preferred_index
+        && !attempted_indexes.contains(&preferred_index)
+        && !blocked_contains(policy, preferred_index)
+    {
+        let preferred = account_manager.get_account_by_index(preferred_index).cloned();
+        if let Some(preferred) = preferred {
+            match account_manager.get_account_runtime_skip_reason(
+                preferred.index as i64,
+                family,
+                model,
+            ) {
+                Some(reason) => {
+                    record_skip(&mut skip_reasons, preferred.index as i64, &reason);
+                }
+                None => {
+                    // L4 (deferred): unlocked cursor mutation — see module
+                    // docs.
+                    account_manager.mark_switched(
+                        preferred.index as i64,
+                        SwitchReason::Rotation,
+                        family,
+                    );
+                    // Return the post-mark state (TS returned the live
+                    // object that markSwitched just mutated).
+                    return account_manager
+                        .get_account_by_index(preferred.index as i64)
+                        .cloned()
+                        .or(Some(preferred));
+                }
+            }
+        }
+    }
+
+    // Hybrid selector tier. Sticky boosts override policy boosts key-wise;
+    // pid_offset_enabled carries the PID-offset distribution into the proxy
+    // path (accounts-05).
+    let mut score_boost_by_account: HashMap<usize, f64> = HashMap::new();
+    if let Some(policy) = policy {
+        for (index, boost) in policy.score_boost_by_account.iter() {
+            if *index >= 0 {
+                score_boost_by_account.insert(*index as usize, *boost);
+            }
+        }
+    }
+    if let Some(sticky) = sticky_boost_by_account {
+        for (index, boost) in sticky.iter() {
+            if *index >= 0 {
+                score_boost_by_account.insert(*index as usize, *boost);
+            }
+        }
+    }
+    let selected = account_manager
+        .get_current_or_next_for_family_hybrid(
+            family,
+            model,
+            Some(HybridSelectionOptions {
+                pid_offset_enabled,
+                score_boost_by_account,
+            }),
+        )
+        .cloned();
+    if let Some(selected) = selected {
+        let selected_index = selected.index as i64;
+        if !attempted_indexes.contains(&selected_index) && !blocked_contains(policy, selected_index)
+        {
+            match account_manager.get_account_runtime_skip_reason(selected_index, family, model) {
+                None => return Some(selected),
+                Some(reason) => record_skip(&mut skip_reasons, selected_index, &reason),
+            }
+        }
+    }
+
+    choose_linear_scan_fallback(
+        account_manager,
+        family,
+        model,
+        attempted_indexes,
+        policy,
+        &mut skip_reasons,
+        true,
+    )
+}
+
+/// TS `chooseLinearScanFallback` — shared linear-scan fallback used by both
+/// the hybrid and sequential selection paths. Walks every account in pool
+/// order and returns the first one that is not already attempted, not
+/// policy-blocked, and has no runtime skip reason, recording a skip reason
+/// for each rejected candidate.
+///
+/// `advance_active_pointer` (hybrid: `true`) controls whether the winner is
+/// committed as the new active/cursor position via `mark_switched`. The
+/// sequential path passes `false`: its within-request fallback only needs
+/// an account to TRY this request, and must NOT move the drain-first
+/// primary (issue #509 regression caught in review).
+fn choose_linear_scan_fallback(
+    account_manager: &mut AccountManager,
+    family: ModelFamily,
+    model: Option<&str>,
+    attempted_indexes: &HashSet<i64>,
+    policy: Option<&RuntimePolicyDecision>,
+    skip_reasons: &mut Option<&mut HashMap<i64, String>>,
+    advance_active_pointer: bool,
+) -> Option<ManagedAccount> {
+    let snapshot = account_manager.get_accounts_snapshot();
+    for account in snapshot {
+        let index = account.index as i64;
+        if attempted_indexes.contains(&index) {
+            record_skip(skip_reasons, index, skip_reason::ALREADY_ATTEMPTED);
+            continue;
+        }
+        if blocked_contains(policy, index) {
+            record_skip(skip_reasons, index, skip_reason::POLICY_BLOCKED);
+            continue;
+        }
+        match account_manager.get_account_runtime_skip_reason(index, family, model) {
+            None => {
+                let live = account_manager.get_account_by_index(index).cloned();
+                let Some(live) = live else { continue };
+                // L4 (deferred): unlocked cursor mutation. Skipped in
+                // sequential mode (advance_active_pointer=false) so a
+                // within-request retry never reassigns the drain-first
+                // primary.
+                if advance_active_pointer {
+                    account_manager.mark_switched(index, SwitchReason::Rotation, family);
+                    return account_manager.get_account_by_index(index).cloned().or(Some(live));
+                }
+                return Some(live);
+            }
+            Some(reason) => record_skip(skip_reasons, index, &reason),
+        }
+    }
+    None
+}
+
+/// TS `normalizeForcedAccountIndex(value)` (issue #623, `@internal` in
+/// `lib/runtime-rotation-proxy.ts`) — string form. `None`/blank-parse ⇒
+/// `None`; strings go through JS `Number.parseInt(trim, 10)` semantics
+/// (leading sign, leading digit prefix, e.g. `"3.5"` parses to `3`);
+/// non-integer or `< 0` ⇒ `None`. Never fails — an out-of-range env pin
+/// must not crash proxy startup; `choose_account` reports it per-request
+/// instead ("missing").
+pub fn normalize_forced_account_index(value: Option<&str>) -> Option<i64> {
+    let value = value?;
+    js_parse_int_base10(value.trim()).and_then(|parsed| if parsed < 0 { None } else { Some(parsed) })
+}
+
+/// TS `normalizeForcedAccountIndex(value)` — number form: numbers are used
+/// as-is; non-integer or `< 0` ⇒ `None`.
+pub fn normalize_forced_account_index_number(value: Option<f64>) -> Option<i64> {
+    let value = value?;
+    if !value.is_finite() || value.fract() != 0.0 || value < 0.0 {
+        return None;
+    }
+    // Values beyond i64 range saturate — they behave as "missing" (out of
+    // pool range) downstream exactly like any other huge pin.
+    if value >= i64::MAX as f64 {
+        return Some(i64::MAX);
+    }
+    Some(value as i64)
+}
+
+/// JS `Number.parseInt(s, 10)`: optional sign, then the longest leading run
+/// of ASCII digits; empty run ⇒ NaN (`None` here). Trailing garbage is
+/// ignored (`"3.5"` ⇒ 3).
+fn js_parse_int_base10(s: &str) -> Option<i64> {
+    let bytes = s.as_bytes();
+    let mut pos = 0usize;
+    let mut negative = false;
+    if pos < bytes.len() && (bytes[pos] == b'+' || bytes[pos] == b'-') {
+        negative = bytes[pos] == b'-';
+        pos += 1;
+    }
+    let digits_start = pos;
+    let mut value: i128 = 0;
+    let mut saturated = false;
+    while pos < bytes.len() && bytes[pos].is_ascii_digit() {
+        if !saturated {
+            value = value * 10 + i128::from(bytes[pos] - b'0');
+            if value > i64::MAX as i128 {
+                saturated = true;
+            }
+        }
+        pos += 1;
+    }
+    if pos == digits_start {
+        return None;
+    }
+    let magnitude = if saturated { i64::MAX } else { value as i64 };
+    Some(if negative { -magnitude } else { magnitude })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{
+        AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily, CooldownReason, RateLimitStateV3,
+    };
+    use cma_core::utils::now_ms;
+    use serial_test::serial;
+
+    const FAMILY: ModelFamily = ModelFamily::Gpt5Codex;
+
+    fn storage_with(count: usize) -> AccountStorageV3 {
+        let now = now_ms();
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = (0..count)
+            .map(|index| {
+                let mut meta = AccountMetadataV3::new(
+                    format!("refresh-{}", index + 1),
+                    now - 60_000,
+                    // Account 0 is the least recently used → deterministic
+                    // hybrid pick under equal tracker metrics.
+                    now - ((count - index) as i64) * 60_000,
+                );
+                meta.email = Some(format!("account-{}@example.com", index + 1));
+                meta.account_id = Some(format!("acc_{}", index + 1));
+                meta.access_token = Some(format!("access-{}", index + 1));
+                meta.expires_at = Some(now + 3_600_000);
+                meta
+            })
+            .collect();
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(FAMILY, Some(0));
+        storage.active_index_by_family = Some(by_family);
+        storage
+    }
+
+    fn manager_with(count: usize) -> AccountManager {
+        AccountManager::reset_volatile_runtime_state();
+        AccountManager::new(None, Some(&storage_with(count)))
+    }
+
+    fn policy_with(blocked: &[i64]) -> RuntimePolicyDecision {
+        RuntimePolicyDecision {
+            allowed: true,
+            status_code: 200,
+            error_code: None,
+            reasons: Vec::new(),
+            project_key: None,
+            blocked_account_indexes: blocked.iter().copied().collect(),
+            score_boost_by_account: HashMap::new(),
+            budget_evaluations: Vec::new(),
+        }
+    }
+
+    struct Fixture {
+        manager: AccountManager,
+        attempted: HashSet<i64>,
+        skip_reasons: HashMap<i64, String>,
+    }
+
+    impl Fixture {
+        fn new(count: usize) -> Self {
+            Self {
+                manager: manager_with(count),
+                attempted: HashSet::new(),
+                skip_reasons: HashMap::new(),
+            }
+        }
+
+        fn choose(
+            &mut self,
+            pinned_index: Option<i64>,
+            policy: Option<&RuntimePolicyDecision>,
+            strategy: SchedulingStrategy,
+            store: Option<&mut SessionAffinityStore>,
+            session_key: Option<&str>,
+        ) -> Option<ManagedAccount> {
+            choose_account(ChooseAccountParams {
+                account_manager: &mut self.manager,
+                session_affinity_store: store,
+                session_key,
+                family: FAMILY,
+                model: None,
+                attempted_indexes: &self.attempted,
+                now: now_ms(),
+                policy,
+                pinned_index,
+                skip_reasons: Some(&mut self.skip_reasons),
+                sticky_boost_by_account: None,
+                pid_offset_enabled: false,
+                scheduling_strategy: strategy,
+            })
+        }
+    }
+
+    // ---- pinned selection (issue #474) ----
+
+    #[test]
+    #[serial(env)]
+    fn returns_the_pinned_account_without_advancing_any_cursor() {
+        let mut fx = Fixture::new(3);
+        let active_before = fx.manager.get_active_index_for_family(FAMILY);
+
+        let selected = fx.choose(Some(1), None, SchedulingStrategy::Hybrid, None, None);
+
+        assert_eq!(selected.map(|a| a.index), Some(1));
+        // The proxy must not clobber the pin set by the CLI: no cursor moved.
+        assert_eq!(fx.manager.get_active_index_for_family(FAMILY), active_before);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refuses_the_pin_instead_of_falling_back() {
+        // already-attempted
+        let mut fx = Fixture::new(3);
+        fx.attempted.insert(1);
+        assert!(fx
+            .choose(Some(1), None, SchedulingStrategy::Hybrid, None, None)
+            .is_none());
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("already-attempted"));
+
+        // missing (out of range)
+        let mut fx = Fixture::new(3);
+        assert!(fx
+            .choose(Some(7), None, SchedulingStrategy::Hybrid, None, None)
+            .is_none());
+        assert_eq!(fx.skip_reasons.get(&7).map(String::as_str), Some("missing"));
+
+        // policy-blocked
+        let mut fx = Fixture::new(3);
+        let policy = policy_with(&[1]);
+        assert!(fx
+            .choose(Some(1), Some(&policy), SchedulingStrategy::Hybrid, None, None)
+            .is_none());
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("policy-blocked"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refuses_a_disabled_pinned_account() {
+        let mut fx = Fixture::new(3);
+        fx.manager.set_account_enabled(1, false);
+
+        let selected = fx.choose(Some(1), None, SchedulingStrategy::Hybrid, None, None);
+
+        assert!(selected.is_none());
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("disabled"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refuses_a_rate_limited_pinned_account_with_the_runtime_reason() {
+        let mut fx = Fixture::new(3);
+        {
+            let account = fx.manager.get_account_by_index_mut(1).unwrap();
+            let mut windows = RateLimitStateV3::default();
+            windows.insert(FAMILY.as_str().to_string(), now_ms() + 600_000);
+            account.rate_limit_reset_times = windows;
+        }
+
+        let selected = fx.choose(Some(1), None, SchedulingStrategy::Hybrid, None, None);
+
+        assert!(selected.is_none());
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("rate-limited"));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refuses_a_cooling_down_pinned_account_with_the_tagged_reason() {
+        let mut fx = Fixture::new(3);
+        fx.manager
+            .mark_account_cooling_down(1, 60_000, CooldownReason::AuthFailure);
+
+        let selected = fx.choose(Some(1), None, SchedulingStrategy::Hybrid, None, None);
+
+        assert!(selected.is_none());
+        assert_eq!(
+            fx.skip_reasons.get(&1).map(String::as_str),
+            Some("cooling-down:auth-failure")
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refuses_a_pinned_account_whose_circuit_breaker_is_open() {
+        let mut fx = Fixture::new(3);
+        // Trip the breaker (threshold is 3 failures).
+        for _ in 0..3 {
+            fx.manager.record_failure(1, FAMILY, None);
+        }
+
+        let selected = fx.choose(Some(1), None, SchedulingStrategy::Hybrid, None, None);
+
+        assert!(selected.is_none());
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("circuit-open"));
+    }
+
+    // ---- session affinity tier ----
+
+    #[test]
+    #[serial(env)]
+    fn prefers_the_remembered_account_and_commits_the_cursor() {
+        let mut fx = Fixture::new(3);
+        let mut store = SessionAffinityStore::new(Default::default());
+        store.remember(Some("sess-1"), 2, now_ms());
+
+        let selected = fx.choose(
+            None,
+            None,
+            SchedulingStrategy::Hybrid,
+            Some(&mut store),
+            Some("sess-1"),
+        );
+
+        assert_eq!(selected.map(|a| a.index), Some(2));
+        // mark_switched committed the cursor to the sticky account.
+        assert_eq!(fx.manager.get_active_index_for_family(FAMILY), 2);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn records_the_skip_reason_and_falls_through_when_the_sticky_account_is_unusable() {
+        let mut fx = Fixture::new(3);
+        {
+            let account = fx.manager.get_account_by_index_mut(2).unwrap();
+            let mut windows = RateLimitStateV3::default();
+            windows.insert(FAMILY.as_str().to_string(), now_ms() + 600_000);
+            account.rate_limit_reset_times = windows;
+        }
+        let mut store = SessionAffinityStore::new(Default::default());
+        store.remember(Some("sess-1"), 2, now_ms());
+
+        let selected = fx.choose(
+            None,
+            None,
+            SchedulingStrategy::Hybrid,
+            Some(&mut store),
+            Some("sess-1"),
+        );
+
+        assert_eq!(fx.skip_reasons.get(&2).map(String::as_str), Some("rate-limited"));
+        // Falls through to the hybrid tier, which picks a usable account.
+        let selected_index = selected.map(|a| a.index).expect("an account is selected");
+        assert_ne!(selected_index, 2);
+    }
+
+    // ---- hybrid tier + linear fallback ----
+
+    #[test]
+    #[serial(env)]
+    fn falls_back_to_a_linear_scan_that_commits_the_cursor_when_the_hybrid_pick_was_attempted() {
+        let mut fx = Fixture::new(3);
+        // Account 0 is the deterministic hybrid pick under fresh trackers
+        // (longest idle); marking it attempted forces the linear fallback.
+        fx.attempted.insert(0);
+        let policy = policy_with(&[1]);
+
+        let selected = fx.choose(None, Some(&policy), SchedulingStrategy::Hybrid, None, None);
+
+        // 0 was attempted, 1 is policy-blocked, 2 wins and becomes the cursor.
+        assert_eq!(selected.map(|a| a.index), Some(2));
+        assert_eq!(fx.skip_reasons.get(&0).map(String::as_str), Some("already-attempted"));
+        assert_eq!(fx.skip_reasons.get(&1).map(String::as_str), Some("policy-blocked"));
+        assert_eq!(fx.manager.get_active_index_for_family(FAMILY), 2);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn returns_null_with_a_reason_per_account_when_the_pool_is_exhausted() {
+        let mut fx = Fixture::new(3);
+        fx.attempted.extend([0, 1, 2]);
+
+        let selected = fx.choose(None, None, SchedulingStrategy::Hybrid, None, None);
+
+        assert!(selected.is_none());
+        let mut entries: Vec<(i64, &str)> = fx
+            .skip_reasons
+            .iter()
+            .map(|(index, reason)| (*index, reason.as_str()))
+            .collect();
+        entries.sort();
+        assert_eq!(
+            entries,
+            vec![
+                (0, "already-attempted"),
+                (1, "already-attempted"),
+                (2, "already-attempted"),
+            ]
+        );
+    }
+
+    // ---- sequential mode (issue #509) ----
+
+    #[test]
+    #[serial(env)]
+    fn follows_the_drain_first_selector_and_skips_the_affinity_tier() {
+        let mut fx = Fixture::new(3);
+        let mut store = SessionAffinityStore::new(Default::default());
+        store.remember(Some("sess-1"), 2, now_ms());
+
+        let selected = fx.choose(
+            None,
+            None,
+            SchedulingStrategy::Sequential,
+            Some(&mut store),
+            Some("sess-1"),
+        );
+
+        // Every request follows the single active account (0): no per-chat
+        // stickiness consulted (the remembered account 2 is NOT selected).
+        assert_eq!(selected.map(|a| a.index), Some(0));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn routes_around_a_policy_blocked_primary() {
+        let mut fx = Fixture::new(3);
+        let policy = policy_with(&[0]);
+
+        let selected = fx.choose(None, Some(&policy), SchedulingStrategy::Sequential, None, None);
+
+        // The blocked set is threaded into the drain-first selector, which
+        // advances to the next eligible account (true exhaustion of the
+        // primary for this policy).
+        assert_eq!(selected.map(|a| a.index), Some(1));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn retries_another_account_without_moving_the_drain_first_primary() {
+        let mut fx = Fixture::new(3);
+        fx.attempted.insert(0);
+
+        let selected = fx.choose(None, None, SchedulingStrategy::Sequential, None, None);
+
+        // The transiently failed active account stays primary: the fallback
+        // only finds an account to TRY, it must not commit the cursor.
+        assert_eq!(selected.map(|a| a.index), Some(1));
+        assert_eq!(fx.skip_reasons.get(&0).map(String::as_str), Some("already-attempted"));
+        assert_eq!(fx.manager.get_active_index_for_family(FAMILY), 0);
+    }
+
+    // ---- normalize_forced_account_index (issue #623) ----
+
+    #[test]
+    #[serial(env)]
+    fn normalize_forced_account_index_string_semantics() {
+        assert_eq!(normalize_forced_account_index(None), None);
+        assert_eq!(normalize_forced_account_index(Some("")), None);
+        assert_eq!(normalize_forced_account_index(Some("   ")), None);
+        assert_eq!(normalize_forced_account_index(Some("0")), Some(0));
+        assert_eq!(normalize_forced_account_index(Some(" 2 ")), Some(2));
+        assert_eq!(normalize_forced_account_index(Some("13")), Some(13));
+        // JS parseInt: leading digit prefix wins, trailing garbage ignored.
+        assert_eq!(normalize_forced_account_index(Some("3.5")), Some(3));
+        assert_eq!(normalize_forced_account_index(Some("7abc")), Some(7));
+        // Negative or non-numeric → null (never throws).
+        assert_eq!(normalize_forced_account_index(Some("-1")), None);
+        assert_eq!(normalize_forced_account_index(Some("abc")), None);
+        assert_eq!(normalize_forced_account_index(Some("+4")), Some(4));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn normalize_forced_account_index_number_semantics() {
+        assert_eq!(normalize_forced_account_index_number(None), None);
+        assert_eq!(normalize_forced_account_index_number(Some(0.0)), Some(0));
+        assert_eq!(normalize_forced_account_index_number(Some(5.0)), Some(5));
+        // Numbers are used as-is: non-integers are rejected, not truncated.
+        assert_eq!(normalize_forced_account_index_number(Some(3.5)), None);
+        assert_eq!(normalize_forced_account_index_number(Some(-1.0)), None);
+        assert_eq!(normalize_forced_account_index_number(Some(f64::NAN)), None);
+        assert_eq!(
+            normalize_forced_account_index_number(Some(f64::INFINITY)),
+            None
+        );
+    }
+}
diff --git a/crates/runtime/src/rotation/mod.rs b/crates/runtime/src/rotation/mod.rs
new file mode 100644
index 000000000..c498c7f96
--- /dev/null
+++ b/crates/runtime/src/rotation/mod.rs
@@ -0,0 +1,7 @@
+//! cma-runtime - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_selection;
+pub mod proxy_state;
+pub mod request_init;
+pub mod server_types;
+pub mod storage_meta;
+pub mod token_refresh;
diff --git a/crates/runtime/src/rotation/proxy_state.rs b/crates/runtime/src/rotation/proxy_state.rs
new file mode 100644
index 000000000..84e0568cc
--- /dev/null
+++ b/crates/runtime/src/rotation/proxy_state.rs
@@ -0,0 +1,429 @@
+//! Port of `lib/runtime/rotation-proxy-state.ts` — the per-instance state
+//! container of the runtime rotation proxy plus the full-pool-exhaustion
+//! recovery (issue #606). Spec 10 §6, spec 04 (proxy state recovery),
+//! ARCHITECTURE §6.12.
+
+use crate::observability::{record_runtime_reload, record_runtime_reset};
+use crate::rotation::server_types::{NowFn, RuntimeRotationProxyStatus, SchedulingStrategy};
+use cma_accounts::manager::AccountManager;
+use cma_accounts::manager_persistence::SharedAccountManager;
+use cma_accounts::session_affinity::SessionAffinityStore;
+use cma_core::utils::now_ms;
+use cma_rotation::routing_mutex::RoutingMutexMode;
+use std::sync::{Arc, Mutex as StdMutex};
+
+/// TS `STALE_RUNTIME_RELOAD_DEDUPE_MS` — recovery re-probing is bounded to
+/// ~1/second.
+pub const STALE_RUNTIME_RELOAD_DEDUPE_MS: i64 = 1_000;
+
+/// TS `RotationProxyStateInit` — per-instance configuration resolved once in
+/// `startRuntimeRotationProxy`, captured as explicit fields instead of
+/// closure variables so the request handler and the stale-reload recovery
+/// can be plain functions.
+///
+/// All millisecond values are epoch/duration ms as TS numbers.
+/// `forced_account_index` is the ephemeral per-invocation pin (issue #623 —
+/// NEVER persisted; see `rotation-server-types`).
+#[derive(Clone)]
+pub struct RotationProxyStateInit {
+    pub active_account_manager: SharedAccountManager,
+    pub routing_mutex_mode: RoutingMutexMode,
+    pub scheduling_strategy: SchedulingStrategy,
+    /// Replaces the TS `fetchImpl` seam (injected undici fetch) — the
+    /// pipeline's outbound HTTP client.
+    pub fetch_client: reqwest::Client,
+    pub upstream_base_url: String,
+    pub client_api_key: String,
+    pub now: NowFn,
+    pub token_refresh_skew_ms: i64,
+    pub network_error_cooldown_ms: i64,
+    pub server_error_cooldown_ms: i64,
+    pub token_invalidation_cooldown_ms: i64,
+    pub min_rotation_interval_ms: i64,
+    pub pid_offset_enabled: bool,
+    pub fetch_timeout_ms: i64,
+    pub stream_stall_timeout_ms: i64,
+    pub max_runtime_account_attempts: i64,
+    pub max_request_body_bytes: usize,
+    pub quota_remaining_percent_threshold: f64,
+    /// Shared mutable store (the TS object was mutated in place by the
+    /// single-threaded event loop; Rust callers lock it around each use).
+    pub session_affinity_store: Option<Arc<StdMutex<SessionAffinityStore>>>,
+    pub last_observed_affinity_generation: i64,
+    /// Ephemeral per-invocation account pin (0-based) or `None` — issue
+    /// #623. Never written to disk.
+    pub forced_account_index: Option<i64>,
+}
+
+/// TS `RotationProxyState` — mutable rotation-loop state shared by every
+/// request of one proxy instance. `active_account_manager` and
+/// `last_observed_affinity_generation` are reassigned at runtime
+/// (stale-state recovery and affinity-generation tracking), so the whole
+/// container is passed by reference and never copied.
+pub struct RotationProxyState {
+    // ---- init fields (TS `extends RotationProxyStateInit`) ----
+    pub active_account_manager: SharedAccountManager,
+    pub routing_mutex_mode: RoutingMutexMode,
+    pub scheduling_strategy: SchedulingStrategy,
+    pub fetch_client: reqwest::Client,
+    pub upstream_base_url: String,
+    pub client_api_key: String,
+    pub now: NowFn,
+    pub token_refresh_skew_ms: i64,
+    pub network_error_cooldown_ms: i64,
+    pub server_error_cooldown_ms: i64,
+    pub token_invalidation_cooldown_ms: i64,
+    pub min_rotation_interval_ms: i64,
+    pub pid_offset_enabled: bool,
+    pub fetch_timeout_ms: i64,
+    pub stream_stall_timeout_ms: i64,
+    pub max_runtime_account_attempts: i64,
+    pub max_request_body_bytes: usize,
+    pub quota_remaining_percent_threshold: f64,
+    pub session_affinity_store: Option<Arc<StdMutex<SessionAffinityStore>>>,
+    pub last_observed_affinity_generation: i64,
+    pub forced_account_index: Option<i64>,
+    // ---- runtime fields ----
+    /// TS `Set<AccountManager>` — identity set of every manager this
+    /// instance has ever served (previous managers stay known so in-flight
+    /// requests can finish against them). Identity = the shared handle's
+    /// inner `Arc` pointer.
+    pub known_account_managers: Vec<SharedAccountManager>,
+    pub status: RuntimeRotationProxyStatus,
+    pub thread_goal_fallbacks: std::collections::HashMap<String, Option<String>>,
+    pub last_global_account_index: Option<i64>,
+    pub last_global_switch_at: i64,
+    pub last_stale_runtime_reload_at: i64,
+}
+
+fn same_manager(a: &SharedAccountManager, b: &SharedAccountManager) -> bool {
+    Arc::ptr_eq(a.manager(), b.manager())
+}
+
+impl RotationProxyState {
+    /// TS `state.knownAccountManagers.add(manager)` (Set semantics).
+    pub fn add_known_account_manager(&mut self, manager: SharedAccountManager) {
+        if !self
+            .known_account_managers
+            .iter()
+            .any(|known| same_manager(known, &manager))
+        {
+            self.known_account_managers.push(manager);
+        }
+    }
+
+    /// TS `state.knownAccountManagers.has(manager)`.
+    pub fn knows_account_manager(&self, manager: &SharedAccountManager) -> bool {
+        self.known_account_managers
+            .iter()
+            .any(|known| same_manager(known, manager))
+    }
+}
+
+/// TS `createRotationProxyState(init)`.
+pub fn create_rotation_proxy_state(init: RotationProxyStateInit) -> RotationProxyState {
+    let started_at = (init.now)();
+    RotationProxyState {
+        known_account_managers: vec![init.active_account_manager.clone()],
+        status: RuntimeRotationProxyStatus {
+            started_at,
+            total_requests: 0,
+            upstream_requests: 0,
+            retries: 0,
+            rotations: 0,
+            streams_started: 0,
+            last_error: None,
+            last_account_index: None,
+            last_account_label: None,
+            last_account_id: None,
+            last_account_updated_at: None,
+        },
+        thread_goal_fallbacks: std::collections::HashMap::new(),
+        last_global_account_index: None,
+        last_global_switch_at: 0,
+        last_stale_runtime_reload_at: 0,
+        active_account_manager: init.active_account_manager,
+        routing_mutex_mode: init.routing_mutex_mode,
+        scheduling_strategy: init.scheduling_strategy,
+        fetch_client: init.fetch_client,
+        upstream_base_url: init.upstream_base_url,
+        client_api_key: init.client_api_key,
+        now: init.now,
+        token_refresh_skew_ms: init.token_refresh_skew_ms,
+        network_error_cooldown_ms: init.network_error_cooldown_ms,
+        server_error_cooldown_ms: init.server_error_cooldown_ms,
+        token_invalidation_cooldown_ms: init.token_invalidation_cooldown_ms,
+        min_rotation_interval_ms: init.min_rotation_interval_ms,
+        pid_offset_enabled: init.pid_offset_enabled,
+        fetch_timeout_ms: init.fetch_timeout_ms,
+        stream_stall_timeout_ms: init.stream_stall_timeout_ms,
+        max_runtime_account_attempts: init.max_runtime_account_attempts,
+        max_request_body_bytes: init.max_request_body_bytes,
+        quota_remaining_percent_threshold: init.quota_remaining_percent_threshold,
+        session_affinity_store: init.session_affinity_store,
+        last_observed_affinity_generation: init.last_observed_affinity_generation,
+        forced_account_index: init.forced_account_index,
+    }
+}
+
+/// TS `recoverStaleRuntimeState(state)` — full-pool-exhaustion recovery
+/// (issue #606).
+///
+/// 1. If a recovery completed within the last second (REAL wall clock, not
+///    the injected `now()`) → return the current manager (dedupe re-probing
+///    to ~1/sec).
+/// 2. Otherwise: reset the global volatile singletons (trackers, circuit
+///    breakers), record the observability reset, reload the pool from disk,
+///    restore the configured routing-mutex mode, then clear the per-account
+///    transient state **after** the reload — cooldowns and rate-limit
+///    windows are serialized to disk, so a reload alone restores the same
+///    wedged state. This also drops still-future rate-limit windows from
+///    genuine upstream 429s; that is the intended trade-off (availability
+///    over honoring backoff in an already-degraded state, bounded by the 1s
+///    dedupe). Then `flush_pending_save()` forces the cleared snapshot to
+///    disk immediately (a debounced save could lose the clean state on
+///    process exit), and only after all of that is the reloaded manager
+///    published as `state.active_account_manager` — no concurrent request
+///    can observe it with stale state.
+///
+/// Errors set `status.last_error` and resolve `None`; a failure does NOT
+/// arm the dedupe window, so the next call retries.
+///
+/// Concurrency note (deviation from TS): the TS version shared one
+/// in-flight promise among concurrent callers. In Rust the caller holds the
+/// proxy-state lock (`&mut state`), so concurrent callers serialize on that
+/// lock instead and the second caller lands in the 1-second dedupe
+/// fast-path — the observable outcome (single reload, both callers get the
+/// reloaded manager) is identical.
+pub async fn recover_stale_runtime_state(
+    state: &mut RotationProxyState,
+) -> Option<SharedAccountManager> {
+    if now_ms() - state.last_stale_runtime_reload_at <= STALE_RUNTIME_RELOAD_DEDUPE_MS {
+        return Some(state.active_account_manager.clone());
+    }
+
+    AccountManager::reset_volatile_runtime_state();
+    record_runtime_reset("pool-exhausted-no-account");
+    let reloaded = SharedAccountManager::new(AccountManager::load_from_disk(None).await);
+    {
+        let mut manager = reloaded.lock().await;
+        manager.set_routing_mutex_mode(state.routing_mutex_mode);
+    }
+    // Wipe per-account cooldowns and rate-limit windows on the freshly
+    // reloaded pool BEFORE publishing it (issue #606; see fn docs).
+    reloaded.clear_account_transient_state().await;
+    // Force the cleared snapshot to disk now rather than waiting out the
+    // debounce window; makes the "next reload starts clean" guarantee
+    // durable across a restart.
+    if let Err(error) = reloaded.flush_pending_save().await {
+        state.status.last_error = Some(error.to_string());
+        return None;
+    }
+    state.active_account_manager = reloaded.clone();
+    state.add_known_account_manager(reloaded.clone());
+    state.last_stale_runtime_reload_at = now_ms();
+    record_runtime_reload("pool-exhausted-no-account");
+    Some(reloaded)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::json_io;
+    use cma_core::schemas::account_storage::{AccountMetadataV3, AccountStorageV3};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn account_meta(index: usize, now: i64) -> AccountMetadataV3 {
+        let mut meta =
+            AccountMetadataV3::new(format!("refresh-{}", index + 1), now - 60_000, now - 60_000);
+        meta.email = Some(format!("account-{}@example.com", index + 1));
+        meta.account_id = Some(format!("acc_{}", index + 1));
+        meta.access_token = Some(format!("access-{}", index + 1));
+        meta.expires_at = Some(now + 3_600_000);
+        meta
+    }
+
+    fn storage_with(count: usize) -> AccountStorageV3 {
+        let now = now_ms();
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = (0..count).map(|index| account_meta(index, now)).collect();
+        storage
+    }
+
+    fn write_storage_to_disk(storage: &AccountStorageV3) {
+        let path = cma_storage::facade::get_storage_path();
+        let value = serde_json::to_value(storage).expect("serialize storage");
+        std::fs::create_dir_all(std::path::Path::new(&path).parent().unwrap()).unwrap();
+        std::fs::write(&path, format!("{}\n", json_io::stringify_pretty2(&value))).unwrap();
+    }
+
+    fn state_init(manager: SharedAccountManager) -> RotationProxyStateInit {
+        let now = now_ms();
+        RotationProxyStateInit {
+            active_account_manager: manager,
+            routing_mutex_mode: RoutingMutexMode::Enabled,
+            scheduling_strategy: SchedulingStrategy::Hybrid,
+            fetch_client: reqwest::Client::new(),
+            upstream_base_url: "https://upstream.example".to_string(),
+            client_api_key: "key".to_string(),
+            now: Arc::new(move || now),
+            token_refresh_skew_ms: 30_000,
+            network_error_cooldown_ms: 10_000,
+            server_error_cooldown_ms: 10_000,
+            token_invalidation_cooldown_ms: 300_000,
+            min_rotation_interval_ms: 0,
+            pid_offset_enabled: false,
+            fetch_timeout_ms: 30_000,
+            stream_stall_timeout_ms: 30_000,
+            max_runtime_account_attempts: 3,
+            max_request_body_bytes: 1024,
+            quota_remaining_percent_threshold: 0.0,
+            session_affinity_store: None,
+            last_observed_affinity_generation: 0,
+            forced_account_index: None,
+        }
+    }
+
+    #[test]
+    #[serial(env)]
+    fn create_seeds_known_managers_and_zeroed_status() {
+        let _sandbox = EnvSandbox::new();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            let manager =
+                SharedAccountManager::new(AccountManager::new(None, Some(&storage_with(1))));
+            let init = state_init(manager.clone());
+            let started_at = (init.now)();
+
+            let state = create_rotation_proxy_state(init);
+
+            assert_eq!(state.known_account_managers.len(), 1);
+            assert!(state.knows_account_manager(&manager));
+            assert_eq!(
+                state.status,
+                RuntimeRotationProxyStatus {
+                    started_at,
+                    total_requests: 0,
+                    upstream_requests: 0,
+                    retries: 0,
+                    rotations: 0,
+                    streams_started: 0,
+                    last_error: None,
+                    last_account_index: None,
+                    last_account_label: None,
+                    last_account_id: None,
+                    last_account_updated_at: None,
+                }
+            );
+            assert_eq!(state.last_global_account_index, None);
+            assert_eq!(state.last_stale_runtime_reload_at, 0);
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn recover_reloads_from_disk_swaps_manager_and_clears_transient_state() {
+        let _sandbox = EnvSandbox::new();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            // On-disk pool: 2 accounts, both wedged with future rate-limit
+            // windows and cooldowns (the #606 scenario — a reload alone
+            // would restore this state).
+            let mut wedged = storage_with(2);
+            let far_future = now_ms() + 3_600_000;
+            for account in wedged.accounts.iter_mut() {
+                let mut windows = cma_core::schemas::account_storage::RateLimitStateV3::default();
+                windows.insert("codex".to_string(), far_future);
+                account.rate_limit_reset_times = Some(windows);
+                account.cooling_down_until = Some(far_future);
+                account.cooldown_reason =
+                    Some(cma_core::schemas::account_storage::CooldownReason::AuthFailure);
+            }
+            write_storage_to_disk(&wedged);
+
+            let previous =
+                SharedAccountManager::new(AccountManager::new(None, Some(&storage_with(1))));
+            let mut state = create_rotation_proxy_state(state_init(previous.clone()));
+
+            let result = recover_stale_runtime_state(&mut state).await;
+            let reloaded = result.expect("recovery returns the reloaded manager");
+
+            // The active manager was swapped and both managers stay known.
+            assert!(same_manager(&state.active_account_manager, &reloaded));
+            assert!(!same_manager(&reloaded, &previous));
+            assert!(state.knows_account_manager(&previous));
+            assert!(state.knows_account_manager(&reloaded));
+            assert!(state.last_stale_runtime_reload_at > 0);
+
+            {
+                let mut manager = reloaded.lock().await;
+                assert_eq!(manager.get_account_count(), 2);
+                // The configured mutex mode carries over to the reloaded pool.
+                assert_eq!(manager.get_routing_mutex_mode(), RoutingMutexMode::Enabled);
+                // Transient state was cleared AFTER the reload: no wedged
+                // windows or cooldowns survive.
+                for index in 0..2 {
+                    let account = manager.get_account_by_index(index).unwrap().clone();
+                    assert!(account.rate_limit_reset_times.is_empty());
+                    assert_eq!(account.meta.cooling_down_until, None);
+                    let reason = manager.get_account_runtime_skip_reason(
+                        index,
+                        cma_core::model_family::ModelFamily::Codex,
+                        None,
+                    );
+                    assert_eq!(reason, None);
+                }
+            }
+
+            // The cleared snapshot was flushed to disk synchronously: the
+            // next startup must not reload the wedged state.
+            let on_disk = std::fs::read_to_string(cma_storage::facade::get_storage_path()).unwrap();
+            let parsed: serde_json::Value = serde_json::from_str(&on_disk).unwrap();
+            for account in parsed["accounts"].as_array().unwrap() {
+                assert!(account.get("coolingDownUntil").is_none());
+                let windows = account.get("rateLimitResetTimes");
+                assert!(
+                    windows.is_none()
+                        || windows.unwrap().as_object().map(|m| m.is_empty()) == Some(true)
+                );
+            }
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn recover_dedupes_within_the_one_second_window() {
+        let _sandbox = EnvSandbox::new();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            write_storage_to_disk(&storage_with(2));
+            let previous =
+                SharedAccountManager::new(AccountManager::new(None, Some(&storage_with(1))));
+            let mut state = create_rotation_proxy_state(state_init(previous));
+
+            let first = recover_stale_runtime_state(&mut state)
+                .await
+                .expect("first recovery succeeds");
+            assert_eq!(first.lock().await.get_account_count(), 2);
+
+            // Mutate the disk; the second call inside the dedupe window must
+            // NOT re-read it.
+            write_storage_to_disk(&storage_with(3));
+            let second = recover_stale_runtime_state(&mut state)
+                .await
+                .expect("deduped recovery returns the current manager");
+            assert!(same_manager(&first, &second));
+            assert_eq!(second.lock().await.get_account_count(), 2);
+        });
+    }
+}
diff --git a/crates/runtime/src/rotation/request_init.rs b/crates/runtime/src/rotation/request_init.rs
new file mode 100644
index 000000000..18268cfba
--- /dev/null
+++ b/crates/runtime/src/rotation/request_init.rs
@@ -0,0 +1,147 @@
+//! Port of `lib/runtime/request-init.ts` — proxy-side request-init helpers
+//! (spec 10 §11, ARCHITECTURE §6.12).
+//!
+//! The TS `normalizeRuntimeRequestInit` reconstructed a fetch `RequestInit`
+//! from a WHATWG `Request` object; in Rust the proxy already receives the
+//! method/headers/body as plain values, so the same normalization is
+//! expressed over those (default method `GET`, body attached only for
+//! non-GET/HEAD when readable as non-empty UTF-8; an unreadable body means
+//! "proceed without it", mirroring the TS clone/read failure path).
+
+use reqwest::header::HeaderMap;
+
+/// The normalized shape (TS `RequestInit` subset the runtime produced).
+#[derive(Debug, Clone, PartialEq)]
+pub struct NormalizedRequestInit {
+    pub method: String,
+    pub headers: HeaderMap,
+    pub body: Option<String>,
+}
+
+/// TS `normalizeRuntimeRequestInit(requestInput, requestInit)` — the
+/// Request-object reconstruction half. `method` `None`/empty defaults to
+/// `"GET"`; the body is attached only for non-GET/HEAD methods when it
+/// decodes to non-empty UTF-8 text (TS read the cloned body as text; a
+/// failed read proceeds bodyless).
+pub fn normalize_runtime_request_init(
+    method: Option<&str>,
+    headers: &HeaderMap,
+    body: Option<&[u8]>,
+) -> NormalizedRequestInit {
+    let method = match method {
+        Some(method) if !method.is_empty() => method.to_string(),
+        _ => "GET".to_string(),
+    };
+    let mut normalized = NormalizedRequestInit {
+        method: method.clone(),
+        headers: headers.clone(),
+        body: None,
+    };
+    if method != "GET"
+        && method != "HEAD"
+        && let Some(bytes) = body
+    {
+        match std::str::from_utf8(bytes) {
+            Ok(text) if !text.is_empty() => normalized.body = Some(text.to_string()),
+            // Unreadable/empty body: proceed without it (TS parity).
+            _ => {}
+        }
+    }
+    normalized
+}
+
+/// TS `parseRuntimeRequestBody(body, {logWarn})` — JSON-parses the request
+/// body. A falsy body (`None`/empty) returns `{}` with NO warning; a parse
+/// failure logs exactly `"Failed to parse request body, using empty
+/// object"` and returns `{}`.
+///
+/// Type note (TS parity): the TS function cast `JSON.parse`'s result to a
+/// record without checking it, so non-object JSON (e.g. `42`) passed
+/// through as-is — the Rust port returns `serde_json::Value` for the same
+/// reason.
+pub fn parse_runtime_request_body(
+    body: Option<&[u8]>,
+    log_warn: impl FnOnce(&str),
+) -> serde_json::Value {
+    let Some(bytes) = body else {
+        return serde_json::Value::Object(serde_json::Map::new());
+    };
+    if bytes.is_empty() {
+        // Falsy body (TS `if (!body) return {}`) — no warning.
+        return serde_json::Value::Object(serde_json::Map::new());
+    }
+    match serde_json::from_slice::<serde_json::Value>(bytes) {
+        Ok(value) => value,
+        Err(_) => {
+            log_warn("Failed to parse request body, using empty object");
+            serde_json::Value::Object(serde_json::Map::new())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn normalize_defaults_to_get_and_omits_the_body_for_get_and_head() {
+        let headers = HeaderMap::new();
+        let normalized = normalize_runtime_request_init(None, &headers, Some(b"{\"a\":1}"));
+        assert_eq!(normalized.method, "GET");
+        assert_eq!(normalized.body, None);
+
+        let normalized = normalize_runtime_request_init(Some("HEAD"), &headers, Some(b"body"));
+        assert_eq!(normalized.body, None);
+    }
+
+    #[test]
+    fn normalize_attaches_a_non_empty_post_body() {
+        let headers = HeaderMap::new();
+        let normalized = normalize_runtime_request_init(Some("POST"), &headers, Some(b"{\"a\":1}"));
+        assert_eq!(normalized.method, "POST");
+        assert_eq!(normalized.body.as_deref(), Some("{\"a\":1}"));
+
+        // Empty or unreadable bodies proceed bodyless.
+        let normalized = normalize_runtime_request_init(Some("POST"), &headers, Some(b""));
+        assert_eq!(normalized.body, None);
+        let normalized =
+            normalize_runtime_request_init(Some("POST"), &headers, Some(&[0xff, 0xfe]));
+        assert_eq!(normalized.body, None);
+    }
+
+    #[test]
+    fn parse_returns_empty_object_for_falsy_bodies_without_warning() {
+        let mut warned = false;
+        let value = parse_runtime_request_body(None, |_| warned = true);
+        assert_eq!(value, json!({}));
+        assert!(!warned);
+
+        let mut warned = false;
+        let value = parse_runtime_request_body(Some(b""), |_| warned = true);
+        assert_eq!(value, json!({}));
+        assert!(!warned);
+    }
+
+    #[test]
+    fn parse_returns_the_parsed_json_value() {
+        let value = parse_runtime_request_body(Some(br#"{"model":"gpt-5.5"}"#), |_| {
+            panic!("no warning expected")
+        });
+        assert_eq!(value, json!({"model": "gpt-5.5"}));
+
+        // Non-object JSON passes through (TS unchecked-cast parity).
+        let value = parse_runtime_request_body(Some(b"42"), |_| panic!("no warning expected"));
+        assert_eq!(value, json!(42));
+    }
+
+    #[test]
+    fn parse_failures_warn_with_the_frozen_message_and_return_empty_object() {
+        let mut message = String::new();
+        let value = parse_runtime_request_body(Some(b"{ not json"), |warning| {
+            message = warning.to_string();
+        });
+        assert_eq!(value, json!({}));
+        assert_eq!(message, "Failed to parse request body, using empty object");
+    }
+}
diff --git a/crates/runtime/src/rotation/server_types.rs b/crates/runtime/src/rotation/server_types.rs
new file mode 100644
index 000000000..ff99387b5
--- /dev/null
+++ b/crates/runtime/src/rotation/server_types.rs
@@ -0,0 +1,290 @@
+//! Port of `lib/runtime/rotation-server-types.ts` — shared types for the
+//! runtime rotation proxy (spec 10 §7, ARCHITECTURE §6.12).
+//!
+//! These are the CONTRACT types between `cma-runtime::rotation` and the
+//! `cma-proxy` HTTP surface. String values (skip reasons, exhaustion
+//! reasons) are frozen — observability snapshots and the proxy error
+//! payloads embed them verbatim.
+
+use cma_accounts::manager_persistence::SharedAccountManager;
+use cma_core::model_family::ModelFamily;
+use serde::Serialize;
+use std::sync::Arc;
+
+/// TS `"hybrid" | "sequential"` scheduling-strategy union
+/// (`rotation-proxy-state.ts` / config getter `getSchedulingStrategy`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SchedulingStrategy {
+    #[default]
+    Hybrid,
+    Sequential,
+}
+
+impl SchedulingStrategy {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            SchedulingStrategy::Hybrid => "hybrid",
+            SchedulingStrategy::Sequential => "sequential",
+        }
+    }
+}
+
+/// Selection-layer skip-reason strings recorded by
+/// [`crate::rotation::account_selection::choose_account`]. The
+/// account-manager runtime reasons (`"rate-limited"`,
+/// `"cooling-down:<reason>"`, `"circuit-open"`, `"workspace-disabled"`,
+/// `"disabled"`, `"missing"`) come from
+/// `AccountManager::get_account_runtime_skip_reason` and share this
+/// contract space.
+pub mod skip_reason {
+    /// The account was already tried during this request.
+    pub const ALREADY_ATTEMPTED: &str = "already-attempted";
+    /// The (pinned) index is out of the pool range.
+    pub const MISSING: &str = "missing";
+    /// Blocked by the runtime policy decision.
+    pub const POLICY_BLOCKED: &str = "policy-blocked";
+    /// Account missing from the pool or `enabled === false`.
+    pub const DISABLED: &str = "disabled";
+}
+
+/// TS `RuntimeRotationProxyStatus` — the live status snapshot returned by
+/// the proxy's `getStatus()`. Field order mirrors the TS object literal in
+/// `createRotationProxyState` (serialization key order matters for the
+/// status JSON surfaces).
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeRotationProxyStatus {
+    pub started_at: i64,
+    pub total_requests: i64,
+    pub upstream_requests: i64,
+    pub retries: i64,
+    pub rotations: i64,
+    pub streams_started: i64,
+    pub last_error: Option<String>,
+    pub last_account_index: Option<i64>,
+    pub last_account_label: Option<String>,
+    pub last_account_id: Option<String>,
+    pub last_account_updated_at: Option<i64>,
+}
+
+/// Injected clock (`now: () => number`).
+pub type NowFn = Arc<dyn Fn() -> i64 + Send + Sync>;
+
+/// TS `RuntimeRotationProxyOptions` — options accepted by
+/// `startRuntimeRotationProxy` (implemented in `cma-proxy`).
+///
+/// `forced_account_index` is the ephemeral, per-invocation account pin
+/// (0-based) for a single invocation (issue #623:
+/// `codex-multi-auth-codex --account`). When set, the proxy routes every
+/// request to exactly this account and never rotates, without touching the
+/// persisted `switch` pin on disk. `None` defers to
+/// `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX` in the environment (resolved by
+/// the proxy caller via
+/// [`crate::rotation::account_selection::normalize_forced_account_index`])
+/// so the value survives the launcher -> detached app-helper process
+/// boundary. The TS `??` fallback semantics are preserved: an explicit
+/// `Some(0)` is honored and wins over the environment.
+#[derive(Clone, Default)]
+pub struct RuntimeRotationProxyOptions {
+    pub host: Option<String>,
+    pub port: Option<u16>,
+    pub upstream_base_url: Option<String>,
+    /// Required (validated by the proxy server, not here).
+    pub client_api_key: String,
+    pub account_manager: Option<SharedAccountManager>,
+    /// Replaces the TS `fetchImpl` seam: an injected reqwest client.
+    pub fetch_client: Option<reqwest::Client>,
+    pub now: Option<NowFn>,
+    pub quota_remaining_percent_threshold: Option<f64>,
+    pub max_request_body_bytes: Option<usize>,
+    pub fetch_timeout_ms: Option<i64>,
+    pub stream_stall_timeout_ms: Option<i64>,
+    /// See the struct docs — `None` defers to the environment.
+    pub forced_account_index: Option<i64>,
+    /// When the launcher explicitly resolved "no pin" (no `--account`), set
+    /// this so the proxy NEVER falls back to a stray/inherited
+    /// `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX` (TS deletes the var from
+    /// `process.env` in that case: a request without `--account` can never
+    /// inherit an unintended pin from a parent forced run or a leftover
+    /// export). Default `false` preserves the env fallback for callers that
+    /// never resolved the pin themselves.
+    pub suppress_env_forced_account_index: bool,
+}
+
+impl std::fmt::Debug for RuntimeRotationProxyOptions {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RuntimeRotationProxyOptions")
+            .field("host", &self.host)
+            .field("port", &self.port)
+            .field("upstream_base_url", &self.upstream_base_url)
+            .field("client_api_key", &"<redacted>")
+            .field("has_account_manager", &self.account_manager.is_some())
+            .field("has_fetch_client", &self.fetch_client.is_some())
+            .field("has_now", &self.now.is_some())
+            .field(
+                "quota_remaining_percent_threshold",
+                &self.quota_remaining_percent_threshold,
+            )
+            .field("max_request_body_bytes", &self.max_request_body_bytes)
+            .field("fetch_timeout_ms", &self.fetch_timeout_ms)
+            .field("stream_stall_timeout_ms", &self.stream_stall_timeout_ms)
+            .field("forced_account_index", &self.forced_account_index)
+            .field(
+                "suppress_env_forced_account_index",
+                &self.suppress_env_forced_account_index,
+            )
+            .finish()
+    }
+}
+
+/// TS `RequestContext.method` — the proxy only serves GET and POST.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RequestMethod {
+    Get,
+    Post,
+}
+
+impl RequestMethod {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            RequestMethod::Get => "GET",
+            RequestMethod::Post => "POST",
+        }
+    }
+}
+
+/// TS `RequestContext` — the parsed inbound request handed to the rotation
+/// pipeline.
+#[derive(Debug, Clone)]
+pub struct RequestContext {
+    /// Raw request body bytes (TS `Buffer`).
+    pub body: Vec<u8>,
+    pub headers: reqwest::header::HeaderMap,
+    pub method: RequestMethod,
+    pub upstream_path: String,
+    pub model: Option<String>,
+    pub family: ModelFamily,
+    pub stream: bool,
+    pub session_key: Option<String>,
+}
+
+/// TS `ExhaustionReason` — why the pool ran out of candidates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+pub enum ExhaustionReason {
+    #[serde(rename = "rate-limit")]
+    RateLimit,
+    #[serde(rename = "server-error")]
+    ServerError,
+    #[serde(rename = "network-error")]
+    NetworkError,
+    #[serde(rename = "auth-failure")]
+    AuthFailure,
+    #[serde(rename = "budget")]
+    Budget,
+    #[serde(rename = "deactivated")]
+    Deactivated,
+    #[serde(rename = "no-account")]
+    NoAccount,
+}
+
+impl ExhaustionReason {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            ExhaustionReason::RateLimit => "rate-limit",
+            ExhaustionReason::ServerError => "server-error",
+            ExhaustionReason::NetworkError => "network-error",
+            ExhaustionReason::AuthFailure => "auth-failure",
+            ExhaustionReason::Budget => "budget",
+            ExhaustionReason::Deactivated => "deactivated",
+            ExhaustionReason::NoAccount => "no-account",
+        }
+    }
+}
+
+/// TS `RuntimeProxyHttpError` — an error carrying the HTTP status and one
+/// of the proxy's stable error codes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RuntimeProxyHttpError {
+    pub message: String,
+    pub status_code: u16,
+    pub code: String,
+}
+
+impl RuntimeProxyHttpError {
+    pub fn new(message: impl Into<String>, status_code: u16, code: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+            status_code,
+            code: code.into(),
+        }
+    }
+}
+
+impl std::fmt::Display for RuntimeProxyHttpError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message)
+    }
+}
+
+impl std::error::Error for RuntimeProxyHttpError {}
+
+/// TS `RuntimeRotationAccountIdentity` — the last-served account identity
+/// reported through status snapshots.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeRotationAccountIdentity {
+    pub index: i64,
+    pub label: String,
+    pub account_id: Option<String>,
+    pub updated_at: i64,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn exhaustion_reason_strings_are_frozen() {
+        assert_eq!(ExhaustionReason::RateLimit.as_str(), "rate-limit");
+        assert_eq!(ExhaustionReason::ServerError.as_str(), "server-error");
+        assert_eq!(ExhaustionReason::NetworkError.as_str(), "network-error");
+        assert_eq!(ExhaustionReason::AuthFailure.as_str(), "auth-failure");
+        assert_eq!(ExhaustionReason::Budget.as_str(), "budget");
+        assert_eq!(ExhaustionReason::Deactivated.as_str(), "deactivated");
+        assert_eq!(ExhaustionReason::NoAccount.as_str(), "no-account");
+        // Serde renames must match as_str (both feed persisted skip maps).
+        assert_eq!(
+            serde_json::to_string(&ExhaustionReason::NoAccount).unwrap(),
+            "\"no-account\""
+        );
+    }
+
+    #[test]
+    fn skip_reason_strings_are_frozen() {
+        assert_eq!(skip_reason::ALREADY_ATTEMPTED, "already-attempted");
+        assert_eq!(skip_reason::MISSING, "missing");
+        assert_eq!(skip_reason::POLICY_BLOCKED, "policy-blocked");
+        assert_eq!(skip_reason::DISABLED, "disabled");
+    }
+
+    #[test]
+    fn status_serializes_with_camel_case_keys() {
+        let status = RuntimeRotationProxyStatus {
+            started_at: 1,
+            total_requests: 0,
+            upstream_requests: 0,
+            retries: 0,
+            rotations: 0,
+            streams_started: 0,
+            last_error: None,
+            last_account_index: None,
+            last_account_label: None,
+            last_account_id: None,
+            last_account_updated_at: None,
+        };
+        let value = serde_json::to_value(&status).unwrap();
+        assert!(value.get("startedAt").is_some());
+        assert!(value.get("lastAccountUpdatedAt").is_some());
+        assert!(value.get("started_at").is_none());
+    }
+}
diff --git a/crates/runtime/src/rotation/storage_meta.rs b/crates/runtime/src/rotation/storage_meta.rs
new file mode 100644
index 000000000..d30799086
--- /dev/null
+++ b/crates/runtime/src/rotation/storage_meta.rs
@@ -0,0 +1,404 @@
+//! Port of `lib/runtime/rotation-storage-meta.ts` — content-hash-keyed
+//! snapshot of on-disk storage metadata (spec 10 §10, issue #474).
+//!
+//! The proxy is a long-running process; the `switch`/`unpin`/`best` CLI
+//! runs in a different process and mutates the storage file. We re-read
+//! only the top-level `pinnedAccountIndex` and `affinityGeneration` fields
+//! on each request so manual changes are honored without a full
+//! AccountManager reload (which would lose in-memory cooldown state).
+//!
+//! The cache is keyed on a sha1 of the file bytes rather than mtime because
+//! coarse mtime granularity (FAT 2s, some Windows/network volumes ~1s) can
+//! let two atomic-rename writes share an mtime tick. The mtime+size
+//! short-circuit is only trusted once the cached mtime has settled past
+//! [`MTIME_SHORTCIRCUIT_SETTLE_MS`]; within the settle window we always
+//! fall through to the read + sha1 path (the source of truth).
+//!
+//! Error paths return the LAST CACHED value for the path ("better stale
+//! than wrong"); defaults are only returned when the file was never
+//! successfully read. There is deliberately NO retry/busy-wait (an earlier
+//! TS version blocked the event loop on the request hot path).
+
+use cma_accounts::session_affinity::SessionAffinityStore;
+use cma_core::utils::now_ms;
+use sha1::{Digest, Sha1};
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::{LazyLock, Mutex as StdMutex};
+
+/// TS `MTIME_SHORTCIRCUIT_SETTLE_MS` — 2s comfortably exceeds the coarsest
+/// mtime granularity expected in practice.
+pub const MTIME_SHORTCIRCUIT_SETTLE_MS: i64 = 2_000;
+
+/// TS `StorageMeta` — the two hot-path fields.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StorageMeta {
+    pub pinned_account_index: Option<i64>,
+    pub affinity_generation: i64,
+}
+
+const DEFAULT_META: StorageMeta = StorageMeta {
+    pinned_account_index: None,
+    affinity_generation: 0,
+};
+
+/// TS private `StorageMetaSnapshot`.
+#[derive(Debug, Clone, PartialEq)]
+struct StorageMetaSnapshot {
+    /// Node `stats.mtimeMs` (float ms) — modeled as nanoseconds since epoch
+    /// so sub-millisecond precision survives.
+    mtime_ns: u128,
+    size: u64,
+    content_hash: String,
+    pinned_account_index: Option<i64>,
+    affinity_generation: i64,
+}
+
+impl StorageMetaSnapshot {
+    fn meta(&self) -> StorageMeta {
+        StorageMeta {
+            pinned_account_index: self.pinned_account_index,
+            affinity_generation: self.affinity_generation,
+        }
+    }
+}
+
+// Keyed by storage path so multiple proxy instances and concurrent test
+// workers (each pointing at their own temp storage file) cannot corrupt
+// each other's snapshots. See issue #474.
+static STORAGE_META_CACHE: LazyLock<StdMutex<HashMap<String, StorageMetaSnapshot>>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+
+fn hash_storage_bytes(bytes: &[u8]) -> String {
+    let mut hasher = Sha1::new();
+    hasher.update(bytes);
+    let digest = hasher.finalize();
+    let mut hex = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        hex.push_str(&format!("{byte:02x}"));
+    }
+    hex
+}
+
+fn stat_file(path: &str) -> std::io::Result<(u128, u64)> {
+    let metadata = std::fs::metadata(path)?;
+    let mtime_ns = metadata
+        .modified()?
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|duration| duration.as_nanos())
+        .unwrap_or(0);
+    Ok((mtime_ns, metadata.len()))
+}
+
+/// Validate exactly like the zod schema / `readPinAndGenFromDisk`: a
+/// non-integer or negative pin is REJECTED (`None`), never truncated — this
+/// is the value the proxy routes on, and a negative index reaching
+/// `choose_account` would wedge the pool. JSON `3.0` counts as an integer
+/// (JS `Number.isInteger` semantics).
+fn non_negative_int(value: Option<&serde_json::Value>) -> Option<i64> {
+    let number = value?.as_f64()?;
+    if !number.is_finite() || number.fract() != 0.0 || number < 0.0 || number > i64::MAX as f64 {
+        return None;
+    }
+    Some(number as i64)
+}
+
+/// TS `readStorageMetaFromDisk(storagePath = getStoragePath())`. Pass
+/// `None` to read the active storage path.
+pub fn read_storage_meta_from_disk(storage_path: Option<&str>) -> StorageMeta {
+    let storage_path = match storage_path {
+        Some(path) => path.to_string(),
+        None => cma_storage::facade::get_storage_path(),
+    };
+
+    if !Path::new(&storage_path).exists() {
+        STORAGE_META_CACHE
+            .lock()
+            .expect("storage meta cache poisoned")
+            .remove(&storage_path);
+        return DEFAULT_META;
+    }
+
+    match read_meta_uncached(&storage_path) {
+        Ok(meta) => meta,
+        Err(_) => {
+            // On any failure, prefer the last good snapshot for this path so
+            // we don't blow away affinity unnecessarily. Defaults are only
+            // returned when this file has never been read successfully.
+            let cache = STORAGE_META_CACHE
+                .lock()
+                .expect("storage meta cache poisoned");
+            match cache.get(&storage_path) {
+                Some(cached) => cached.meta(),
+                None => DEFAULT_META,
+            }
+        }
+    }
+}
+
+fn read_meta_uncached(storage_path: &str) -> Result<StorageMeta, ()> {
+    // mtime+size short-circuit (L3): when neither changed since the last
+    // successful read AND the cached mtime has settled, return the cached
+    // snapshot without reading or hashing the file.
+    let (mtime_ns, size) = stat_file(storage_path).map_err(|_| ())?;
+    {
+        let cache = STORAGE_META_CACHE
+            .lock()
+            .expect("storage meta cache poisoned");
+        if let Some(cached) = cache.get(storage_path) {
+            let mtime_ms = (mtime_ns / 1_000_000) as i64;
+            if cached.mtime_ns == mtime_ns
+                && cached.size == size
+                && now_ms() - mtime_ms > MTIME_SHORTCIRCUIT_SETTLE_MS
+            {
+                return Ok(cached.meta());
+            }
+        }
+    }
+
+    let bytes = std::fs::read(storage_path).map_err(|_| ())?;
+    let content_hash = hash_storage_bytes(&bytes);
+    {
+        let mut cache = STORAGE_META_CACHE
+            .lock()
+            .expect("storage meta cache poisoned");
+        if let Some(cached) = cache.get_mut(storage_path)
+            && cached.content_hash == content_hash
+        {
+            // Content is byte-identical despite the mtime/size change
+            // (e.g. an atomic-rename rewrite of the same bytes). Refresh
+            // the stat fields so the next request takes the fast path,
+            // but skip the JSON parse.
+            cached.mtime_ns = mtime_ns;
+            cached.size = size;
+            return Ok(cached.meta());
+        }
+    }
+
+    let parsed: serde_json::Value = serde_json::from_slice(&bytes).map_err(|_| ())?;
+    let pinned_account_index = non_negative_int(parsed.get("pinnedAccountIndex"));
+    let affinity_generation = non_negative_int(parsed.get("affinityGeneration")).unwrap_or(0);
+
+    let snapshot = StorageMetaSnapshot {
+        mtime_ns,
+        size,
+        content_hash,
+        pinned_account_index,
+        affinity_generation,
+    };
+    let meta = snapshot.meta();
+    STORAGE_META_CACHE
+        .lock()
+        .expect("storage meta cache poisoned")
+        .insert(storage_path.to_string(), snapshot);
+    Ok(meta)
+}
+
+/// TS `readPinnedAccountIndexFromDisk` — backwards-compatible helper
+/// retained for tests. Prefer [`read_storage_meta_from_disk`] for new
+/// callers that also need the affinity generation.
+pub fn read_pinned_account_index_from_disk(storage_path: Option<&str>) -> Option<i64> {
+    read_storage_meta_from_disk(storage_path).pinned_account_index
+}
+
+/// TS `resetPinCacheForTesting()` — clears the content-hash cache so each
+/// test starts from a clean read-from-disk state.
+pub fn reset_pin_cache_for_testing() {
+    STORAGE_META_CACHE
+        .lock()
+        .expect("storage meta cache poisoned")
+        .clear();
+}
+
+/// TS `maybeInvalidateAffinityFromDisk(store, lastObservedGeneration,
+/// storagePath?)` — if the on-disk `affinityGeneration` is greater than
+/// `last_observed_generation`, drop every entry in the store and return the
+/// new generation; otherwise return `last_observed_generation` unchanged.
+/// The CLI bumps the generation via `switch|unpin|best`; the proxy itself
+/// NEVER bumps it. See issue #474.
+pub fn maybe_invalidate_affinity_from_disk(
+    session_affinity_store: Option<&mut SessionAffinityStore>,
+    last_observed_generation: i64,
+    storage_path: Option<&str>,
+) -> i64 {
+    let meta = read_storage_meta_from_disk(storage_path);
+    if meta.affinity_generation > last_observed_generation {
+        if let Some(store) = session_affinity_store {
+            store.clear_all();
+        }
+        return meta.affinity_generation;
+    }
+    last_observed_generation
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_accounts::session_affinity::SessionAffinityStore;
+    use serial_test::serial;
+
+    fn temp_storage_file(dir: &tempfile::TempDir, contents: &str) -> String {
+        let path = dir.path().join("accounts.json");
+        std::fs::write(&path, contents).unwrap();
+        path.to_string_lossy().into_owned()
+    }
+
+    #[test]
+    #[serial(env)]
+    fn reads_pin_and_generation_from_disk() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let path = temp_storage_file(
+            &dir,
+            r#"{"version":3,"accounts":[],"activeIndex":0,"pinnedAccountIndex":2,"affinityGeneration":7}"#,
+        );
+
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, Some(2));
+        assert_eq!(meta.affinity_generation, 7);
+        assert_eq!(read_pinned_account_index_from_disk(Some(&path)), Some(2));
+    }
+
+    #[test]
+    #[serial(env)]
+    fn missing_file_clears_the_cache_entry_and_returns_defaults() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let path = temp_storage_file(&dir, r#"{"pinnedAccountIndex":1}"#);
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)).pinned_account_index,
+            Some(1)
+        );
+
+        std::fs::remove_file(&path).unwrap();
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, None);
+        assert_eq!(meta.affinity_generation, 0);
+
+        // The cache entry is gone: a later parse failure has nothing to
+        // fall back to.
+        std::fs::write(&path, "{ not json").unwrap();
+        assert_eq!(read_storage_meta_from_disk(Some(&path)), DEFAULT_META);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn malformed_pin_is_rejected_never_truncated() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        // Negative pin (a negative index would wedge the pool).
+        let path = temp_storage_file(&dir, r#"{"pinnedAccountIndex":-1,"affinityGeneration":3}"#);
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, None);
+        assert_eq!(meta.affinity_generation, 3);
+
+        // Non-integer pin is rejected; JSON 3.0 counts as an integer
+        // (Number.isInteger semantics).
+        std::fs::write(&path, r#"{"pinnedAccountIndex":1.5,"affinityGeneration":2.0}"#).unwrap();
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, None);
+        assert_eq!(meta.affinity_generation, 2);
+
+        // Non-numeric values collapse to the defaults.
+        std::fs::write(
+            &path,
+            r#"{"pinnedAccountIndex":"2","affinityGeneration":"5"}"#,
+        )
+        .unwrap();
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, None);
+        assert_eq!(meta.affinity_generation, 0);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn parse_errors_fall_back_to_the_last_cached_value() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let path = temp_storage_file(
+            &dir,
+            r#"{"pinnedAccountIndex":4,"affinityGeneration":9}"#,
+        );
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)),
+            StorageMeta {
+                pinned_account_index: Some(4),
+                affinity_generation: 9
+            }
+        );
+
+        // A partial write (torn JSON) must serve the last good snapshot.
+        std::fs::write(&path, r#"{"pinnedAccountIndex":"#).unwrap();
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)),
+            StorageMeta {
+                pinned_account_index: Some(4),
+                affinity_generation: 9
+            }
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn rewrites_with_identical_content_keep_the_cached_meta() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let contents = r#"{"pinnedAccountIndex":1,"affinityGeneration":2}"#;
+        let path = temp_storage_file(&dir, contents);
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)).pinned_account_index,
+            Some(1)
+        );
+
+        // Atomic-rename style rewrite of the same bytes (mtime changes,
+        // content hash does not).
+        std::fs::write(&path, contents).unwrap();
+        let meta = read_storage_meta_from_disk(Some(&path));
+        assert_eq!(meta.pinned_account_index, Some(1));
+        assert_eq!(meta.affinity_generation, 2);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn fresh_content_changes_are_seen_within_the_settle_window() {
+        // Within 2s of the write, mtime equality is NOT trusted: a changed
+        // file must be re-read + re-hashed immediately.
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let path = temp_storage_file(&dir, r#"{"pinnedAccountIndex":0}"#);
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)).pinned_account_index,
+            Some(0)
+        );
+
+        std::fs::write(&path, r#"{"pinnedAccountIndex":2}"#).unwrap();
+        assert_eq!(
+            read_storage_meta_from_disk(Some(&path)).pinned_account_index,
+            Some(2)
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn maybe_invalidate_affinity_clears_the_store_on_a_newer_generation() {
+        reset_pin_cache_for_testing();
+        let dir = tempfile::tempdir().unwrap();
+        let path = temp_storage_file(&dir, r#"{"affinityGeneration":5}"#);
+        let now = now_ms();
+        let mut store = SessionAffinityStore::new(Default::default());
+        store.remember(Some("sess-1"), 1, now);
+        assert_eq!(store.size(), 1);
+
+        // On-disk generation (5) > observed (3): store dropped, new
+        // generation returned.
+        let next = maybe_invalidate_affinity_from_disk(Some(&mut store), 3, Some(&path));
+        assert_eq!(next, 5);
+        assert_eq!(store.size(), 0);
+
+        // Observed already current: unchanged, store untouched.
+        store.remember(Some("sess-2"), 0, now);
+        let unchanged = maybe_invalidate_affinity_from_disk(Some(&mut store), 5, Some(&path));
+        assert_eq!(unchanged, 5);
+        assert_eq!(store.size(), 1);
+    }
+}
diff --git a/crates/runtime/src/rotation/token_refresh.rs b/crates/runtime/src/rotation/token_refresh.rs
new file mode 100644
index 000000000..c0ddf5199
--- /dev/null
+++ b/crates/runtime/src/rotation/token_refresh.rs
@@ -0,0 +1,626 @@
+//! Port of `lib/runtime/rotation-token-refresh.ts` — per-request token
+//! freshness for the proxy hot path (spec 10 §9, ARCHITECTURE §6.12).
+//!
+//! Key contracts:
+//! - `apply_monotonic_auth_cooldown` — cooldowns only EXTEND, never
+//!   shorten, and the comparison runs on the REAL wall clock
+//!   (`cma_core::utils::now_ms`), never an injected clock: `coolingDownUntil`
+//!   is written with real wall-clock time, so comparing an injected clock
+//!   against it would silently defeat the guard.
+//! - `ensure_fresh_access_token` — queued refresh + commit dedupe, 30s
+//!   default auth-failure cooldown, 5-minute (configured) invalidation
+//!   cooldown, `invalidated: true` tells the caller to STOP rotating (don't
+//!   present other accounts' tokens from the same IP).
+
+use cma_accounts::manager::{AccountIdentityCandidate, AccountManager, ManagedAccount};
+use cma_accounts::manager_persistence::{SharedAccountManager, SAVE_DEBOUNCE_DEFAULT_MS};
+use cma_auth::refresh_queue::queued_refresh;
+use cma_core::model_family::ModelFamily;
+use cma_core::schemas::account_storage::CooldownReason;
+use cma_core::schemas::token::TokenResult;
+use cma_core::types::OAuthAuthDetails;
+use cma_core::utils::now_ms;
+use cma_request::rate_limit_decision::{is_token_invalidation_error, is_token_refresh_retryable};
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, LazyLock, Mutex as StdMutex};
+
+/// TS `DEFAULT_AUTH_FAILURE_COOLDOWN_MS` (`@internal`, exported).
+pub const DEFAULT_AUTH_FAILURE_COOLDOWN_MS: i64 = 30_000;
+
+/// TS `applyMonotonicAuthCooldown(accountManager, account, cooldownMs)`.
+///
+/// Monotonic auth-failure cooldown: only extend, never shorten. Two
+/// concurrent requests on the same account can race so that an invalidation
+/// path sets a long cooldown (5 min) and a subsequent generic 401 truncates
+/// it (30 s). Reading the live `cooling_down_until` before writing prevents
+/// that race.
+///
+/// Intentionally `now_ms()` (== `Date.now()`), not any injected clock:
+/// `cooling_down_until` is written by `mark_account_cooling_down` via the
+/// real wall clock, so both sides of this comparison must live in the same
+/// real-wall-clock domain.
+pub fn apply_monotonic_auth_cooldown(
+    account_manager: &mut AccountManager,
+    account: &ManagedAccount,
+    cooldown_ms: i64,
+) {
+    let existing = account_manager
+        .get_account_by_index(account.index as i64)
+        .and_then(|live| live.meta.cooling_down_until)
+        .unwrap_or(0);
+    if now_ms() + cooldown_ms > existing {
+        account_manager.mark_account_cooling_down(
+            account.index as i64,
+            cooldown_ms,
+            CooldownReason::AuthFailure,
+        );
+    }
+}
+
+/// TS private `hasUsableAccessToken(account, now, skewMs)`.
+fn has_usable_access_token(account: &ManagedAccount, now: i64, skew_ms: i64) -> bool {
+    let access_ok = account
+        .meta
+        .access_token
+        .as_deref()
+        .is_some_and(|access| !access.trim().is_empty());
+    let expires_ok = account
+        .meta
+        .expires_at
+        .is_some_and(|expires| expires > now + skew_ms.max(0));
+    access_ok && expires_ok
+}
+
+/// The injectable refresh seam (TS module import `queuedRefresh`; the TS
+/// tests replace it with `vi.mock`).
+pub type RefreshTokenFn<'a> =
+    &'a (dyn Fn(String) -> Pin<Box<dyn Future<Output = TokenResult> + Send>> + Sync);
+
+/// TS `ensureFreshAccessToken` params object.
+pub struct EnsureFreshAccessTokenParams<'a> {
+    pub account_manager: &'a SharedAccountManager,
+    /// Snapshot of the selected account (TS passed the live object).
+    pub account: &'a ManagedAccount,
+    pub family: ModelFamily,
+    pub model: Option<&'a str>,
+    pub now: i64,
+    pub token_refresh_skew_ms: i64,
+    pub token_invalidation_cooldown_ms: i64,
+}
+
+/// TS return union of `ensureFreshAccessToken`.
+///
+/// The `Ok` arm intentionally carries the full [`ManagedAccount`] inline
+/// (TS returned the live account object); boxing it would push the cost
+/// onto every success-path caller to shave bytes off the rare failure arm.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug, Clone, PartialEq)]
+pub enum EnsureFreshAccessTokenResult {
+    Ok {
+        access_token: String,
+        account: ManagedAccount,
+    },
+    Failed {
+        retryable: bool,
+        /// `true` = server-side refresh-token revocation: stop rotating.
+        invalidated: bool,
+    },
+}
+
+impl EnsureFreshAccessTokenResult {
+    pub fn is_ok(&self) -> bool {
+        matches!(self, EnsureFreshAccessTokenResult::Ok { .. })
+    }
+}
+
+// TS `runtimeRefreshCommitQueues: WeakMap<AccountManager, Map<key, Promise>>`
+// — per-(manager, account-key) in-flight commit dedup. Keyed by the shared
+// handle's inner Arc pointer; entries are removed when the commit settles,
+// so a dead manager leaves nothing behind (WeakMap parity in practice).
+type CommitOutcome = Result<Option<usize>, String>;
+type CommitCell = tokio::sync::OnceCell<CommitOutcome>;
+type CommitQueueMap = HashMap<(usize, String), Arc<CommitCell>>;
+static RUNTIME_REFRESH_COMMIT_QUEUES: LazyLock<StdMutex<CommitQueueMap>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+
+fn commit_dedupe_key(account: &ManagedAccount) -> String {
+    [
+        account.index.to_string(),
+        account.meta.account_id.clone().unwrap_or_default(),
+        account.meta.email.clone().unwrap_or_default(),
+        account.meta.refresh_token.clone(),
+    ]
+    .join("\0")
+}
+
+/// TS `commitRefreshedAuthOnce` — concurrent callers for the same
+/// (manager, account) share one in-flight `commit_refreshed_auth` call.
+async fn commit_refreshed_auth_once(
+    account_manager: &SharedAccountManager,
+    account: &ManagedAccount,
+    auth: &OAuthAuthDetails,
+) -> CommitOutcome {
+    let map_key = (
+        Arc::as_ptr(account_manager.manager()) as usize,
+        commit_dedupe_key(account),
+    );
+    let (cell, inserted) = {
+        let mut queues = RUNTIME_REFRESH_COMMIT_QUEUES
+            .lock()
+            .expect("commit queue poisoned");
+        match queues.get(&map_key) {
+            Some(existing) => (existing.clone(), false),
+            None => {
+                let cell = Arc::new(CommitCell::new());
+                queues.insert(map_key.clone(), cell.clone());
+                (cell, true)
+            }
+        }
+    };
+
+    let candidate = AccountIdentityCandidate {
+        account_id: account.meta.account_id.clone(),
+        email: account.meta.email.clone(),
+        refresh_token: Some(account.meta.refresh_token.clone()),
+        index: Some(account.index as i64),
+    };
+    let outcome = cell
+        .get_or_init(|| async {
+            let mut manager = account_manager.lock().await;
+            manager
+                .commit_refreshed_auth(&candidate, auth)
+                .await
+                .map_err(|error| error.to_string())
+        })
+        .await
+        .clone();
+
+    // TS `.finally(() => queue?.delete(key))` — the inserting caller removes
+    // the entry once the shared commit settles; late waiters still hold the
+    // Arc, new callers start a fresh commit.
+    if inserted {
+        RUNTIME_REFRESH_COMMIT_QUEUES
+            .lock()
+            .expect("commit queue poisoned")
+            .remove(&map_key);
+    }
+    outcome
+}
+
+/// TS `ensureFreshAccessToken(params)` using the real global refresh queue.
+pub async fn ensure_fresh_access_token(
+    params: EnsureFreshAccessTokenParams<'_>,
+) -> EnsureFreshAccessTokenResult {
+    ensure_fresh_access_token_with(params, &|refresh_token| {
+        Box::pin(async move { queued_refresh(&refresh_token).await })
+    })
+    .await
+}
+
+/// Seam variant used by tests (TS `vi.mock` of `queuedRefresh`). Behavior
+/// is otherwise identical to [`ensure_fresh_access_token`].
+pub async fn ensure_fresh_access_token_with(
+    params: EnsureFreshAccessTokenParams<'_>,
+    refresh: RefreshTokenFn<'_>,
+) -> EnsureFreshAccessTokenResult {
+    let EnsureFreshAccessTokenParams {
+        account_manager,
+        account,
+        family,
+        model,
+        now,
+        token_refresh_skew_ms,
+        token_invalidation_cooldown_ms,
+    } = params;
+
+    if has_usable_access_token(account, now, token_refresh_skew_ms) {
+        return EnsureFreshAccessTokenResult::Ok {
+            access_token: account.meta.access_token.clone().unwrap_or_default(),
+            account: account.clone(),
+        };
+    }
+
+    let refresh_result = refresh(account.meta.refresh_token.clone()).await;
+    let success = match refresh_result {
+        TokenResult::Failed(failure) => {
+            {
+                let mut manager = account_manager.lock().await;
+                manager.record_failure(account.index as i64, family, model);
+                if let Some(live) = manager.get_account_by_index_mut(account.index as i64) {
+                    live.increment_auth_failures();
+                }
+                // If the refresh endpoint itself returns an explicit
+                // invalidation message (e.g. SSO revokes the refresh token
+                // server-side), apply the long cooldown and signal the caller
+                // to stop rotating.
+                let invalidated =
+                    is_token_invalidation_error(failure.message.as_deref().unwrap_or(""));
+                apply_monotonic_auth_cooldown(
+                    &mut manager,
+                    account,
+                    if invalidated {
+                        token_invalidation_cooldown_ms
+                    } else {
+                        DEFAULT_AUTH_FAILURE_COOLDOWN_MS
+                    },
+                );
+                account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+                return EnsureFreshAccessTokenResult::Failed {
+                    retryable: is_token_refresh_retryable(&failure),
+                    invalidated,
+                };
+            }
+        }
+        TokenResult::Success(success) => success,
+    };
+
+    let auth = OAuthAuthDetails {
+        access: success.access.clone(),
+        refresh: success.refresh.clone(),
+        expires: success.expires,
+    };
+    match commit_refreshed_auth_once(account_manager, account, &auth).await {
+        Ok(committed_index) => {
+            // If commit succeeded, use the stored access token from the
+            // committed account (also covers the dedup case — both callers
+            // end up with the same committed token). If commit returned None
+            // (account missing from storage after persist), fall back to the
+            // original account object but ALWAYS use the refresh result's
+            // access token: the original account may carry an expired token,
+            // and using that would 401 downstream and mis-trigger the
+            // invalidation-cooldown logic.
+            match committed_index {
+                Some(index) => {
+                    let updated = {
+                        let manager = account_manager.lock().await;
+                        manager.get_account_by_index(index as i64).cloned()
+                    };
+                    match updated {
+                        Some(updated) => EnsureFreshAccessTokenResult::Ok {
+                            access_token: updated
+                                .meta
+                                .access_token
+                                .clone()
+                                .unwrap_or_else(|| success.access.clone()),
+                            account: updated,
+                        },
+                        None => EnsureFreshAccessTokenResult::Ok {
+                            access_token: success.access.clone(),
+                            account: account.clone(),
+                        },
+                    }
+                }
+                None => EnsureFreshAccessTokenResult::Ok {
+                    access_token: success.access.clone(),
+                    account: account.clone(),
+                },
+            }
+        }
+        Err(_) => {
+            // TS catch branch: record failure, fixed 30s cooldown (direct,
+            // not monotonic — TS parity), debounced save, retryable.
+            let mut manager = account_manager.lock().await;
+            manager.record_failure(account.index as i64, family, model);
+            manager.mark_account_cooling_down(
+                account.index as i64,
+                DEFAULT_AUTH_FAILURE_COOLDOWN_MS,
+                CooldownReason::AuthFailure,
+            );
+            drop(manager);
+            account_manager.save_to_disk_debounced(SAVE_DEBOUNCE_DEFAULT_MS);
+            EnsureFreshAccessTokenResult::Failed {
+                retryable: true,
+                invalidated: false,
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{
+        AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily,
+    };
+    use cma_core::schemas::token::{TokenFailure, TokenFailureReason, TokenSuccess};
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    const FAMILY: ModelFamily = ModelFamily::Gpt5Codex;
+    const SKEW_MS: i64 = 30_000;
+    const INVALIDATION_COOLDOWN_MS: i64 = 300_000;
+
+    fn storage_with(expires_at: i64) -> AccountStorageV3 {
+        let now = now_ms();
+        let mut meta = AccountMetadataV3::new("refresh-1", now - 60_000, now - 60_000);
+        meta.email = Some("account-1@example.com".to_string());
+        meta.account_id = Some("acc_1".to_string());
+        meta.access_token = Some("access-1".to_string());
+        meta.expires_at = Some(expires_at);
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts = vec![meta];
+        let mut by_family = ActiveIndexByFamily::default();
+        by_family.set(FAMILY, Some(0));
+        storage.active_index_by_family = Some(by_family);
+        storage
+    }
+
+    fn shared_manager_with(expires_at: i64) -> SharedAccountManager {
+        AccountManager::reset_volatile_runtime_state();
+        SharedAccountManager::new(AccountManager::new(None, Some(&storage_with(expires_at))))
+    }
+
+    fn refresh_success() -> TokenResult {
+        TokenResult::Success(TokenSuccess {
+            access: "access-new".to_string(),
+            refresh: "refresh-new".to_string(),
+            expires: now_ms() + 7_200_000,
+            id_token: None,
+            multi_account: None,
+        })
+    }
+
+    fn refresh_failure(
+        reason: TokenFailureReason,
+        status_code: Option<i64>,
+        message: &str,
+    ) -> TokenResult {
+        TokenResult::Failed(TokenFailure {
+            reason: Some(reason),
+            status_code,
+            message: Some(message.to_string()),
+        })
+    }
+
+    async fn run_ensure(
+        shared: &SharedAccountManager,
+        result: TokenResult,
+    ) -> (EnsureFreshAccessTokenResult, usize) {
+        let account = shared.lock().await.get_account_by_index(0).cloned().unwrap();
+        let call_count = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+        let call_count_inner = call_count.clone();
+        let refresh = move |_token: String| {
+            call_count_inner.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            let result = result.clone();
+            Box::pin(async move { result }) as Pin<Box<dyn Future<Output = TokenResult> + Send>>
+        };
+        let outcome = ensure_fresh_access_token_with(
+            EnsureFreshAccessTokenParams {
+                account_manager: shared,
+                account: &account,
+                family: FAMILY,
+                model: None,
+                now: now_ms(),
+                token_refresh_skew_ms: SKEW_MS,
+                token_invalidation_cooldown_ms: INVALIDATION_COOLDOWN_MS,
+            },
+            &refresh,
+        )
+        .await;
+        let calls = call_count.load(std::sync::atomic::Ordering::SeqCst);
+        (outcome, calls)
+    }
+
+    fn test_runtime() -> tokio::runtime::Runtime {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    #[serial(env)]
+    fn uses_a_fresh_token_as_is_without_touching_the_refresh_queue() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let shared = shared_manager_with(now_ms() + 3_600_000);
+
+            let (result, refresh_calls) = run_ensure(&shared, refresh_success()).await;
+
+            assert_eq!(refresh_calls, 0);
+            match result {
+                EnsureFreshAccessTokenResult::Ok { access_token, .. } => {
+                    assert_eq!(access_token, "access-1");
+                }
+                other => panic!("expected ok, got {other:?}"),
+            }
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn refreshes_a_stale_token_and_commits_the_rotated_credentials() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            // Inside the refresh skew window: must refresh before use.
+            let shared = shared_manager_with(now_ms() + 10_000);
+
+            let (result, refresh_calls) = run_ensure(&shared, refresh_success()).await;
+
+            assert_eq!(refresh_calls, 1);
+            match result {
+                EnsureFreshAccessTokenResult::Ok {
+                    access_token,
+                    account,
+                } => {
+                    assert_eq!(access_token, "access-new");
+                    assert_eq!(account.meta.access_token.as_deref(), Some("access-new"));
+                }
+                other => panic!("expected ok, got {other:?}"),
+            }
+            // The in-memory pool now carries the rotated credentials.
+            let live = shared.lock().await.get_account_by_index(0).cloned().unwrap();
+            assert_eq!(live.meta.access_token.as_deref(), Some("access-new"));
+            assert_eq!(live.meta.refresh_token, "refresh-new");
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn applies_the_short_cooldown_on_a_non_retryable_auth_failure() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let now = now_ms();
+            let shared = shared_manager_with(now + 10_000);
+
+            let (result, _) = run_ensure(
+                &shared,
+                refresh_failure(TokenFailureReason::HttpError, Some(401), "token expired"),
+            )
+            .await;
+
+            assert_eq!(
+                result,
+                EnsureFreshAccessTokenResult::Failed {
+                    retryable: false,
+                    invalidated: false,
+                }
+            );
+            let cooling_down_until = shared
+                .lock()
+                .await
+                .get_account_by_index(0)
+                .and_then(|a| a.meta.cooling_down_until)
+                .unwrap_or(0);
+            assert!(cooling_down_until > now);
+            assert!(cooling_down_until <= now_ms() + DEFAULT_AUTH_FAILURE_COOLDOWN_MS);
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn marks_transient_refresh_failures_retryable() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let shared = shared_manager_with(now_ms() + 10_000);
+
+            let (result, _) = run_ensure(
+                &shared,
+                refresh_failure(TokenFailureReason::NetworkError, None, "fetch failed"),
+            )
+            .await;
+
+            match result {
+                EnsureFreshAccessTokenResult::Failed { retryable, .. } => assert!(retryable),
+                other => panic!("expected failed, got {other:?}"),
+            }
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn applies_the_long_cooldown_and_signals_invalidation_on_a_revoked_token() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let now = now_ms();
+            let shared = shared_manager_with(now + 10_000);
+
+            let (result, _) = run_ensure(
+                &shared,
+                refresh_failure(
+                    TokenFailureReason::HttpError,
+                    Some(401),
+                    "OAuth token has been invalidated",
+                ),
+            )
+            .await;
+
+            match result {
+                EnsureFreshAccessTokenResult::Failed { invalidated, .. } => assert!(invalidated),
+                other => panic!("expected failed, got {other:?}"),
+            }
+            let cooling_down_until = shared
+                .lock()
+                .await
+                .get_account_by_index(0)
+                .and_then(|a| a.meta.cooling_down_until)
+                .unwrap_or(0);
+            // The invalidation cooldown is the long one, far beyond 30s.
+            assert!(cooling_down_until > now + INVALIDATION_COOLDOWN_MS - 10_000);
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn never_lets_a_later_generic_failure_truncate_an_invalidation_cooldown() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let shared = shared_manager_with(now_ms() + 10_000);
+            let long_deadline = {
+                let mut manager = shared.lock().await;
+                manager.mark_account_cooling_down(
+                    0,
+                    INVALIDATION_COOLDOWN_MS,
+                    CooldownReason::AuthFailure,
+                );
+                manager
+                    .get_account_by_index(0)
+                    .and_then(|a| a.meta.cooling_down_until)
+                    .unwrap()
+            };
+
+            // Refresh path skips the cooldown check itself (that lives in
+            // selection); a generic 401 arrives while the long cooldown is
+            // live.
+            let (_result, _) = run_ensure(
+                &shared,
+                refresh_failure(TokenFailureReason::HttpError, Some(401), "token expired"),
+            )
+            .await;
+
+            // Monotonic guard: the 30s generic cooldown must not shorten the
+            // 5-minute invalidation cooldown set by a concurrent request.
+            let after = shared
+                .lock()
+                .await
+                .get_account_by_index(0)
+                .and_then(|a| a.meta.cooling_down_until)
+                .unwrap();
+            assert_eq!(after, long_deadline);
+            shared.flush_pending_save().await.ok();
+        });
+    }
+
+    #[test]
+    #[serial(env)]
+    fn apply_monotonic_extends_but_never_shortens() {
+        let _sandbox = EnvSandbox::new();
+        test_runtime().block_on(async {
+            let shared = shared_manager_with(now_ms() + 3_600_000);
+            let mut manager = shared.lock().await;
+            let account = manager.get_account_by_index(0).cloned().unwrap();
+
+            apply_monotonic_auth_cooldown(&mut manager, &account, 60_000);
+            let first_deadline = manager
+                .get_account_by_index(0)
+                .and_then(|a| a.meta.cooling_down_until)
+                .unwrap();
+            assert!(first_deadline > now_ms() - 1_000);
+
+            apply_monotonic_auth_cooldown(&mut manager, &account, 1_000);
+            assert_eq!(
+                manager
+                    .get_account_by_index(0)
+                    .and_then(|a| a.meta.cooling_down_until)
+                    .unwrap(),
+                first_deadline
+            );
+
+            apply_monotonic_auth_cooldown(&mut manager, &account, 600_000);
+            assert!(
+                manager
+                    .get_account_by_index(0)
+                    .and_then(|a| a.meta.cooling_down_until)
+                    .unwrap()
+                    > first_deadline
+            );
+        });
+    }
+}
diff --git a/crates/runtime/src/services.rs b/crates/runtime/src/services.rs
new file mode 100644
index 000000000..8a8d790a7
--- /dev/null
+++ b/crates/runtime/src/services.rs
@@ -0,0 +1,598 @@
+//! Port of `lib/runtime/runtime-services.ts` — long-lived service
+//! lifecycle helpers (spec 10 §21) — plus the absorbed DI entry shims
+//! (`live-sync-entry.ts`, `refresh-guardian-entry.ts`,
+//! `session-affinity-entry.ts`, `ui-runtime-entry.ts`;
+//! `account-manager-cache-entry.ts` collapsed into
+//! [`crate::manager_cache`], `account-storage-scope-entry.ts` into
+//! [`crate::storage_scope`]). ARCHITECTURE §6.12 / §4 item 10.
+//!
+//! These manage singletons owned by the proxy/pipeline entry: compare a
+//! config key, stop/recreate on change, register cleanup exactly once.
+
+use crate::refresh_guardian::{
+    ensure_runtime_refresh_guardian, js_number_string, EnsureRuntimeRefreshGuardianParams,
+    RefreshGuardianLike,
+};
+use cma_core::schemas::plugin_config::PluginConfig;
+use cma_core::types::OAuthAuthDetails;
+use std::future::Future;
+use std::sync::Arc;
+
+/// TS `LiveAccountSyncLike` / `LiveSyncController` — the watcher lifecycle
+/// surface (implemented for `cma_quota::live_account_sync::LiveAccountSync`
+/// below).
+pub trait LiveAccountSyncLike {
+    fn stop(&self);
+    fn sync_to_path(&self, path: &str) -> impl Future<Output = std::io::Result<()>> + Send;
+}
+
+impl LiveAccountSyncLike for cma_quota::live_account_sync::LiveAccountSync {
+    fn stop(&self) {
+        cma_quota::live_account_sync::LiveAccountSync::stop(self)
+    }
+    async fn sync_to_path(&self, path: &str) -> std::io::Result<()> {
+        cma_quota::live_account_sync::LiveAccountSync::sync_to_path(self, std::path::Path::new(path))
+            .await
+    }
+}
+
+/// Resulting live-sync state triple (TS return object).
+pub struct LiveAccountSyncState<TSync> {
+    pub live_account_sync: Option<Arc<TSync>>,
+    pub live_account_sync_path: Option<String>,
+    pub live_account_sync_config_key: Option<String>,
+}
+
+/// TS `ensureLiveAccountSyncState(params)` params.
+pub struct EnsureLiveAccountSyncStateParams<'a, TSync: LiveAccountSyncLike> {
+    pub enabled: bool,
+    pub target_path: String,
+    pub current_sync: Option<Arc<TSync>>,
+    pub current_path: Option<String>,
+    pub current_config_key: Option<String>,
+    pub config_key: Option<String>,
+    pub auth_fallback: Option<OAuthAuthDetails>,
+    pub create_sync: &'a mut dyn FnMut(Option<OAuthAuthDetails>) -> Arc<TSync>,
+    pub register_cleanup: &'a mut dyn FnMut(Box<dyn FnOnce() + Send>),
+    pub log_warn: &'a mut dyn FnMut(&str),
+    pub plugin_name: &'a str,
+}
+
+/// TS `ensureLiveAccountSyncState` — disabled ⇒ stop + all-null; config-key
+/// change ⇒ stop + recreate; path switch with 3 attempts (25·2^n ms backoff)
+/// retrying only EBUSY/EPERM, warning + keeping the previous watcher on
+/// exhaustion. Non-transient sync errors propagate (TS rethrow).
+pub async fn ensure_live_account_sync_state<TSync>(
+    params: EnsureLiveAccountSyncStateParams<'_, TSync>,
+) -> std::io::Result<LiveAccountSyncState<TSync>>
+where
+    TSync: LiveAccountSyncLike + Send + Sync + 'static,
+{
+    let EnsureLiveAccountSyncStateParams {
+        enabled,
+        target_path,
+        current_sync,
+        current_path,
+        current_config_key,
+        config_key,
+        auth_fallback,
+        create_sync,
+        register_cleanup,
+        log_warn,
+        plugin_name,
+    } = params;
+
+    let mut live_account_sync = current_sync;
+    let mut live_account_sync_path = current_path;
+    let mut live_account_sync_config_key = current_config_key;
+
+    if !enabled {
+        if let Some(sync) = live_account_sync.as_ref() {
+            sync.stop();
+        }
+        return Ok(LiveAccountSyncState {
+            live_account_sync: None,
+            live_account_sync_path: None,
+            live_account_sync_config_key: None,
+        });
+    }
+
+    let next_config_key = config_key;
+    if live_account_sync.is_some()
+        && next_config_key.is_some()
+        && (live_account_sync_config_key.is_none()
+            || live_account_sync_config_key != next_config_key)
+    {
+        if let Some(sync) = live_account_sync.as_ref() {
+            sync.stop();
+        }
+        live_account_sync = None;
+        live_account_sync_path = None;
+        live_account_sync_config_key = None;
+    }
+
+    if live_account_sync.is_none() {
+        let created = create_sync(auth_fallback);
+        live_account_sync_config_key = next_config_key;
+        let for_cleanup = created.clone();
+        register_cleanup(Box::new(move || {
+            for_cleanup.stop();
+        }));
+        live_account_sync = Some(created);
+    }
+
+    if live_account_sync_path.as_deref() != Some(target_path.as_str()) {
+        let sync = live_account_sync.as_ref().expect("sync exists here");
+        let mut switched = false;
+        for attempt in 0..3u32 {
+            match sync.sync_to_path(&target_path).await {
+                Ok(()) => {
+                    live_account_sync_path = Some(target_path.clone());
+                    switched = true;
+                    break;
+                }
+                Err(error) => {
+                    let code = cma_core::fs_retry::code_of(&error);
+                    if code != Some("EBUSY") && code != Some("EPERM") {
+                        return Err(error);
+                    }
+                    cma_core::utils::sleep(25 * 2u64.pow(attempt)).await;
+                }
+            }
+        }
+        if !switched {
+            log_warn(&format!(
+                "[{plugin_name}] Live account sync path switch failed due to transient filesystem locks; keeping previous watcher."
+            ));
+        }
+    }
+
+    Ok(LiveAccountSyncState {
+        live_account_sync,
+        live_account_sync_path,
+        live_account_sync_config_key,
+    })
+}
+
+/// TS `ensureLiveAccountSyncEntry(params)` (absorbed `live-sync-entry.ts`)
+/// — derives enabled/target/config-key from the plugin config via
+/// `cma-config` getters, then delegates to
+/// [`ensure_live_account_sync_state`].
+// The parameter list mirrors the TS `ensureLiveAccountSyncEntry(params)`
+// object one-to-one; collapsing it into a struct would just rename the shape.
+#[allow(clippy::too_many_arguments)]
+pub async fn ensure_live_account_sync_entry<TSync>(
+    plugin_config: &PluginConfig,
+    auth_fallback: Option<OAuthAuthDetails>,
+    current_sync: Option<Arc<TSync>>,
+    current_path: Option<String>,
+    current_config_key: Option<String>,
+    create_sync: &mut dyn FnMut(Option<OAuthAuthDetails>) -> Arc<TSync>,
+    register_cleanup: &mut dyn FnMut(Box<dyn FnOnce() + Send>),
+    log_warn: &mut dyn FnMut(&str),
+) -> std::io::Result<LiveAccountSyncState<TSync>>
+where
+    TSync: LiveAccountSyncLike + Send + Sync + 'static,
+{
+    let debounce_ms = cma_config::getters::get_live_account_sync_debounce_ms(plugin_config);
+    let poll_interval_ms = cma_config::getters::get_live_account_sync_poll_ms(plugin_config);
+    ensure_live_account_sync_state(EnsureLiveAccountSyncStateParams {
+        enabled: cma_config::getters::get_live_account_sync(plugin_config),
+        target_path: cma_storage::facade::get_storage_path(),
+        current_sync,
+        current_path,
+        current_config_key,
+        config_key: Some(format!(
+            "{}:{}",
+            js_number_string(debounce_ms),
+            js_number_string(poll_interval_ms)
+        )),
+        auth_fallback,
+        create_sync,
+        register_cleanup,
+        log_warn,
+        plugin_name: cma_core::constants::PLUGIN_NAME,
+    })
+    .await
+}
+
+/// Resulting refresh-guardian state triple (TS return object).
+pub struct RefreshGuardianState<TGuardian: RefreshGuardianLike> {
+    pub refresh_guardian: Option<Arc<TGuardian>>,
+    pub refresh_guardian_config_key: Option<String>,
+    pub refresh_guardian_cleanup_registered: bool,
+}
+
+/// TS `ensureRefreshGuardianState(params)` params.
+pub struct EnsureRefreshGuardianStateParams<'a, TGuardian: RefreshGuardianLike> {
+    pub enabled: bool,
+    pub interval_ms: f64,
+    pub buffer_ms: f64,
+    pub current_guardian: Option<Arc<TGuardian>>,
+    pub current_config_key: Option<String>,
+    pub current_cleanup_registered: bool,
+    pub get_current_guardian: Arc<dyn Fn() -> Option<Arc<TGuardian>> + Send + Sync>,
+    pub create_guardian: &'a mut dyn FnMut(f64, f64) -> Arc<TGuardian>,
+    pub register_cleanup: &'a mut dyn FnMut(Box<dyn FnOnce() + Send>),
+}
+
+/// TS `ensureRefreshGuardianState` — adapter over
+/// [`ensure_runtime_refresh_guardian`] with a synthetic config (the TS
+/// version built `{enabled, intervalMs, bufferMs}` and trivial getters).
+pub fn ensure_refresh_guardian_state<TGuardian>(
+    params: EnsureRefreshGuardianStateParams<'_, TGuardian>,
+) -> RefreshGuardianState<TGuardian>
+where
+    TGuardian: RefreshGuardianLike + Send + Sync + 'static,
+{
+    let ensured = ensure_runtime_refresh_guardian(EnsureRuntimeRefreshGuardianParams {
+        enabled: params.enabled,
+        interval_ms: params.interval_ms,
+        buffer_ms: params.buffer_ms,
+        current_guardian: params.current_guardian,
+        current_config_key: params.current_config_key,
+        current_cleanup_registered: params.current_cleanup_registered,
+        get_current_guardian: params.get_current_guardian,
+        create_guardian: params.create_guardian,
+        register_cleanup: params.register_cleanup,
+    });
+    RefreshGuardianState {
+        refresh_guardian: ensured.guardian,
+        refresh_guardian_config_key: ensured.config_key,
+        refresh_guardian_cleanup_registered: ensured.cleanup_registered,
+    }
+}
+
+/// TS `ensureRefreshGuardianEntry(params)` (absorbed
+/// `refresh-guardian-entry.ts`) — derives the three config values from the
+/// plugin config via `cma-config` getters.
+pub fn ensure_refresh_guardian_entry<TGuardian>(
+    plugin_config: &PluginConfig,
+    current_guardian: Option<Arc<TGuardian>>,
+    current_config_key: Option<String>,
+    current_cleanup_registered: bool,
+    get_current_guardian: Arc<dyn Fn() -> Option<Arc<TGuardian>> + Send + Sync>,
+    create_guardian: &mut dyn FnMut(f64, f64) -> Arc<TGuardian>,
+    register_cleanup: &mut dyn FnMut(Box<dyn FnOnce() + Send>),
+) -> RefreshGuardianState<TGuardian>
+where
+    TGuardian: RefreshGuardianLike + Send + Sync + 'static,
+{
+    ensure_refresh_guardian_state(EnsureRefreshGuardianStateParams {
+        enabled: cma_config::getters::get_proactive_refresh_guardian(plugin_config),
+        interval_ms: cma_config::getters::get_proactive_refresh_interval_ms(plugin_config),
+        buffer_ms: cma_config::getters::get_proactive_refresh_buffer_ms(plugin_config),
+        current_guardian,
+        current_config_key,
+        current_cleanup_registered,
+        get_current_guardian,
+        create_guardian,
+        register_cleanup,
+    })
+}
+
+/// Resulting session-affinity state pair (TS return object).
+pub struct SessionAffinityState<TStore> {
+    pub session_affinity_store: Option<TStore>,
+    pub session_affinity_config_key: Option<String>,
+}
+
+/// TS `ensureSessionAffinityState(params)` — disabled ⇒ `{null, null}`
+/// (deliberately does NOT stop/free the old store — stores are passive);
+/// matching `"${ttlMs}:${maxEntries}"` key ⇒ reuse; otherwise create.
+pub fn ensure_session_affinity_state<TStore>(
+    enabled: bool,
+    ttl_ms: f64,
+    max_entries: f64,
+    current_store: Option<TStore>,
+    current_config_key: Option<String>,
+    create_store: &mut dyn FnMut(f64, f64) -> TStore,
+) -> SessionAffinityState<TStore> {
+    if !enabled {
+        return SessionAffinityState {
+            session_affinity_store: None,
+            session_affinity_config_key: None,
+        };
+    }
+
+    let config_key = format!(
+        "{}:{}",
+        js_number_string(ttl_ms),
+        js_number_string(max_entries)
+    );
+    if let Some(store) = current_store
+        && current_config_key.as_deref() == Some(config_key.as_str())
+    {
+        return SessionAffinityState {
+            session_affinity_store: Some(store),
+            session_affinity_config_key: current_config_key,
+        };
+    }
+
+    SessionAffinityState {
+        session_affinity_store: Some(create_store(ttl_ms, max_entries)),
+        session_affinity_config_key: Some(config_key),
+    }
+}
+
+/// TS `ensureSessionAffinityEntry(params)` (absorbed
+/// `session-affinity-entry.ts`).
+pub fn ensure_session_affinity_entry<TStore>(
+    plugin_config: &PluginConfig,
+    current_store: Option<TStore>,
+    current_config_key: Option<String>,
+    create_store: &mut dyn FnMut(f64, f64) -> TStore,
+) -> SessionAffinityState<TStore> {
+    ensure_session_affinity_state(
+        cma_config::getters::get_session_affinity(plugin_config),
+        cma_config::getters::get_session_affinity_ttl_ms(plugin_config),
+        cma_config::getters::get_session_affinity_max_entries(plugin_config),
+        current_store,
+        current_config_key,
+        create_store,
+    )
+}
+
+/// TS `resolveUiRuntimeEntry(params)` (absorbed `ui-runtime-entry.ts`) —
+/// trivial `resolve(load, apply)` indirection; see
+/// [`crate::quota_settings::resolve_ui_runtime_from_config`].
+pub fn resolve_ui_runtime_entry<TUi>(
+    load_plugin_config: impl FnOnce() -> PluginConfig,
+    apply_ui_runtime_from_config: impl FnOnce(&PluginConfig) -> TUi,
+) -> TUi {
+    crate::quota_settings::resolve_ui_runtime_from_config(
+        load_plugin_config,
+        apply_ui_runtime_from_config,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Mutex as StdMutex;
+
+    // ---- fake sync ----
+
+    struct FakeSync {
+        stopped: AtomicUsize,
+        sync_calls: StdMutex<Vec<String>>,
+        /// io error codes to fail with, consumed per call (raw OS errors so
+        /// `code_of` maps them; 0 = success).
+        failures: StdMutex<Vec<Option<std::io::ErrorKind>>>,
+    }
+
+    impl FakeSync {
+        fn new() -> Arc<Self> {
+            Self::failing(Vec::new())
+        }
+
+        fn failing(failures: Vec<Option<std::io::ErrorKind>>) -> Arc<Self> {
+            Arc::new(Self {
+                stopped: AtomicUsize::new(0),
+                sync_calls: StdMutex::new(Vec::new()),
+                failures: StdMutex::new(failures),
+            })
+        }
+    }
+
+    impl LiveAccountSyncLike for FakeSync {
+        fn stop(&self) {
+            self.stopped.fetch_add(1, Ordering::SeqCst);
+        }
+        async fn sync_to_path(&self, path: &str) -> std::io::Result<()> {
+            self.sync_calls.lock().unwrap().push(path.to_string());
+            let next = self.failures.lock().unwrap().pop();
+            match next.flatten() {
+                Some(kind) => Err(std::io::Error::new(kind, "boom")),
+                None => Ok(()),
+            }
+        }
+    }
+
+    fn test_runtime() -> tokio::runtime::Runtime {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+    }
+
+    #[test]
+    fn disabled_live_sync_stops_and_nulls_everything() {
+        test_runtime().block_on(async {
+            let current = FakeSync::new();
+            let mut create = |_auth: Option<OAuthAuthDetails>| FakeSync::new();
+            let mut register = |_c: Box<dyn FnOnce() + Send>| {};
+            let mut warn = |_m: &str| {};
+
+            let state = ensure_live_account_sync_state(EnsureLiveAccountSyncStateParams {
+                enabled: false,
+                target_path: "/tmp/accounts.json".to_string(),
+                current_sync: Some(current.clone()),
+                current_path: Some("/old".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                config_key: Some("250:2000".to_string()),
+                auth_fallback: None,
+                create_sync: &mut create,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert!(state.live_account_sync.is_none());
+            assert!(state.live_account_sync_path.is_none());
+            assert!(state.live_account_sync_config_key.is_none());
+            assert_eq!(current.stopped.load(Ordering::SeqCst), 1);
+        });
+    }
+
+    #[test]
+    fn config_key_change_recreates_the_sync_and_registers_cleanup_per_creation() {
+        test_runtime().block_on(async {
+            let current = FakeSync::new();
+            let created = FakeSync::new();
+            let created_for_closure = created.clone();
+            let mut create = move |_auth: Option<OAuthAuthDetails>| created_for_closure.clone();
+            let mut cleanups: Vec<Box<dyn FnOnce() + Send>> = Vec::new();
+            let mut register = |cleanup: Box<dyn FnOnce() + Send>| cleanups.push(cleanup);
+            let mut warn = |_m: &str| {};
+
+            let state = ensure_live_account_sync_state(EnsureLiveAccountSyncStateParams {
+                enabled: true,
+                target_path: "/tmp/accounts.json".to_string(),
+                current_sync: Some(current.clone()),
+                current_path: Some("/tmp/accounts.json".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                config_key: Some("500:1000".to_string()),
+                auth_fallback: None,
+                create_sync: &mut create,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert_eq!(current.stopped.load(Ordering::SeqCst), 1);
+            assert!(Arc::ptr_eq(state.live_account_sync.as_ref().unwrap(), &created));
+            assert_eq!(
+                state.live_account_sync_config_key.as_deref(),
+                Some("500:1000")
+            );
+            // The recreated sync had no path yet: it was switched.
+            assert_eq!(
+                state.live_account_sync_path.as_deref(),
+                Some("/tmp/accounts.json")
+            );
+            assert_eq!(cleanups.len(), 1);
+            // The registered cleanup stops the created sync.
+            cleanups.pop().unwrap()();
+            assert_eq!(created.stopped.load(Ordering::SeqCst), 1);
+        });
+    }
+
+    #[test]
+    fn path_switch_retries_transient_locks_and_keeps_the_previous_watcher() {
+        test_runtime().block_on(async {
+            // Three EBUSY failures (ResourceBusy maps to "EBUSY" in
+            // fs_retry::code_of) — the retryable set is EBUSY/EPERM only.
+            let sync = FakeSync::failing(vec![
+                Some(std::io::ErrorKind::ResourceBusy),
+                Some(std::io::ErrorKind::ResourceBusy),
+                Some(std::io::ErrorKind::ResourceBusy),
+            ]);
+            let mut create = |_auth: Option<OAuthAuthDetails>| panic!("no create expected");
+            let mut register = |_c: Box<dyn FnOnce() + Send>| {};
+            let mut warnings: Vec<String> = Vec::new();
+            let mut warn = |m: &str| warnings.push(m.to_string());
+
+            let state = ensure_live_account_sync_state(EnsureLiveAccountSyncStateParams {
+                enabled: true,
+                target_path: "/tmp/next.json".to_string(),
+                current_sync: Some(sync.clone()),
+                current_path: Some("/tmp/prev.json".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                config_key: Some("250:2000".to_string()),
+                auth_fallback: None,
+                create_sync: &mut create,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await
+            .unwrap();
+
+            assert_eq!(sync.sync_calls.lock().unwrap().len(), 3);
+            // Path stays on the previous watcher.
+            assert_eq!(state.live_account_sync_path.as_deref(), Some("/tmp/prev.json"));
+            assert_eq!(warnings.len(), 1);
+            assert_eq!(
+                warnings[0],
+                "[codex-multi-auth] Live account sync path switch failed due to transient filesystem locks; keeping previous watcher."
+            );
+        });
+    }
+
+    #[test]
+    fn non_transient_path_switch_errors_propagate() {
+        test_runtime().block_on(async {
+            let sync = FakeSync::failing(vec![Some(std::io::ErrorKind::NotFound)]);
+            let mut create = |_auth: Option<OAuthAuthDetails>| panic!("no create expected");
+            let mut register = |_c: Box<dyn FnOnce() + Send>| {};
+            let mut warn = |_m: &str| {};
+
+            let result = ensure_live_account_sync_state(EnsureLiveAccountSyncStateParams {
+                enabled: true,
+                target_path: "/tmp/next.json".to_string(),
+                current_sync: Some(sync),
+                current_path: Some("/tmp/prev.json".to_string()),
+                current_config_key: Some("250:2000".to_string()),
+                config_key: Some("250:2000".to_string()),
+                auth_fallback: None,
+                create_sync: &mut create,
+                register_cleanup: &mut register,
+                log_warn: &mut warn,
+                plugin_name: "codex-multi-auth",
+            })
+            .await;
+
+            assert!(result.is_err());
+        });
+    }
+
+    // ---- session affinity ----
+
+    #[test]
+    fn session_affinity_state_lifecycle() {
+        #[derive(Clone, PartialEq, Debug)]
+        struct FakeStore(u32);
+        let mut created = 0u32;
+        let mut create = |_ttl: f64, _max: f64| {
+            created += 1;
+            FakeStore(created)
+        };
+
+        // Disabled: all null (old store not freed — passive).
+        let state = ensure_session_affinity_state(
+            false,
+            1_000.0,
+            512.0,
+            Some(FakeStore(9)),
+            Some("1000:512".to_string()),
+            &mut create,
+        );
+        assert!(state.session_affinity_store.is_none());
+        assert!(state.session_affinity_config_key.is_none());
+
+        // Enabled, no current: creates.
+        let state =
+            ensure_session_affinity_state(true, 1_000.0, 512.0, None, None, &mut create);
+        assert_eq!(state.session_affinity_store, Some(FakeStore(1)));
+        assert_eq!(state.session_affinity_config_key.as_deref(), Some("1000:512"));
+
+        // Matching key: reuse.
+        let state = ensure_session_affinity_state(
+            true,
+            1_000.0,
+            512.0,
+            state.session_affinity_store,
+            state.session_affinity_config_key,
+            &mut create,
+        );
+        assert_eq!(state.session_affinity_store, Some(FakeStore(1)));
+
+        // Key change: recreate.
+        let state = ensure_session_affinity_state(
+            true,
+            2_000.0,
+            512.0,
+            state.session_affinity_store,
+            state.session_affinity_config_key,
+            &mut create,
+        );
+        assert_eq!(state.session_affinity_store, Some(FakeStore(2)));
+        assert_eq!(state.session_affinity_config_key.as_deref(), Some("2000:512"));
+    }
+}
diff --git a/crates/runtime/src/storage_scope.rs b/crates/runtime/src/storage_scope.rs
new file mode 100644
index 000000000..9de3c323b
--- /dev/null
+++ b/crates/runtime/src/storage_scope.rs
@@ -0,0 +1,212 @@
+//! Port of `lib/runtime/storage-scope.ts` + `lib/runtime/account-scope.ts`
+//! (+ `account-storage-scope-entry.ts`) — account-storage scope resolution
+//! from config (spec 10 §22, ARCHITECTURE §6.12).
+//!
+//! When Codex CLI sync is enabled, per-project accounts are IGNORED
+//! (collapsed to the global pool); the conflict is surfaced ONCE per
+//! process as a loud, actionable warning (AUDIT-M09 / D-06).
+
+use cma_core::constants::PLUGIN_NAME;
+use cma_core::schemas::plugin_config::PluginConfig;
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// TS `account-scope.ts` `applyAccountStorageScope` deps — the generic,
+/// fully injected variant (used by tests and alternate wirings).
+pub struct AccountStorageScopeDeps<'a, TConfig> {
+    pub get_per_project_accounts: &'a dyn Fn(&TConfig) -> bool,
+    pub get_storage_backup_enabled: &'a dyn Fn(&TConfig) -> bool,
+    pub is_codex_cli_sync_enabled: &'a dyn Fn() -> bool,
+    pub set_storage_backup_enabled: &'a mut dyn FnMut(bool),
+    /// `None` = global default path; `Some(cwd)` = per-project scope.
+    pub set_storage_path: &'a mut dyn FnMut(Option<&str>),
+    pub get_cwd: &'a dyn Fn() -> String,
+    pub warn_per_project_sync_conflict: &'a mut dyn FnMut(),
+}
+
+/// TS `applyAccountStorageScope(pluginConfig, deps)` (generic variant).
+pub fn apply_account_storage_scope<TConfig>(
+    plugin_config: &TConfig,
+    deps: &mut AccountStorageScopeDeps<'_, TConfig>,
+) {
+    let per_project_accounts = (deps.get_per_project_accounts)(plugin_config);
+    (deps.set_storage_backup_enabled)((deps.get_storage_backup_enabled)(plugin_config));
+    if (deps.is_codex_cli_sync_enabled)() {
+        if per_project_accounts {
+            (deps.warn_per_project_sync_conflict)();
+        }
+        (deps.set_storage_path)(None);
+        return;
+    }
+
+    if per_project_accounts {
+        let cwd = (deps.get_cwd)();
+        (deps.set_storage_path)(Some(&cwd));
+    } else {
+        (deps.set_storage_path)(None);
+    }
+}
+
+// TS `index.ts` module state `perProjectSyncWarningShown` — once per
+// process.
+static PER_PROJECT_SYNC_WARNING_SHOWN: AtomicBool = AtomicBool::new(false);
+
+/// Test-only: reset the once-per-process warning gate.
+pub fn reset_per_project_sync_warning_for_testing() {
+    PER_PROJECT_SYNC_WARNING_SHOWN.store(false, Ordering::SeqCst);
+}
+
+/// The exact conflict warning text (storage-scope.ts, AUDIT-M09 / D-06).
+fn per_project_sync_conflict_warning() -> String {
+    format!(
+        "[{PLUGIN_NAME}] Config conflict: perProjectAccounts = true \
+is ignored while Codex CLI sync is enabled, because Codex CLI \
+maintains a single shared account set. All multi-auth accounts \
+are collapsed to the GLOBAL pool (credentials are NOT isolated \
+per project/worktree). \
+To restore per-project isolation, either (a) disable Codex CLI \
+sync via 'codex-multi-auth config set codexCliSync false', or \
+(b) disable perProjectAccounts via \
+'codex-multi-auth config set perProjectAccounts false' (acknowledges \
+the global scope). This warning is emitted once per process."
+    )
+}
+
+/// TS `applyAccountStorageScopeFromConfig(pluginConfig, deps)` with the
+/// production wiring (the `account-storage-scope-entry.ts` composition):
+/// config getters from `cma-config`, storage setters from `cma-storage`,
+/// CLI-sync probe from `cma-cli-mirror`, warn-once via the process-global
+/// gate, warning through the logger.
+pub fn apply_account_storage_scope_from_config(plugin_config: &PluginConfig) {
+    let per_project_accounts = cma_config::getters::get_per_project_accounts(plugin_config);
+    cma_storage::facade::set_storage_backup_enabled(
+        cma_config::getters::get_storage_backup_enabled(plugin_config),
+    );
+    if cma_cli_mirror::state::is_codex_cli_sync_enabled() {
+        if per_project_accounts && !PER_PROJECT_SYNC_WARNING_SHOWN.swap(true, Ordering::SeqCst) {
+            // AUDIT-M09 / D-06: a hard config conflict that silently
+            // collapses per-project isolation to global storage. Loud,
+            // actionable, once per process — the signal is that the user
+            // sees it, not its repetition.
+            cma_core::logger::log_warn(&per_project_sync_conflict_warning(), None);
+        }
+        cma_storage::facade::set_storage_path(None);
+        return;
+    }
+
+    if per_project_accounts {
+        let cwd = std::env::current_dir().unwrap_or_default();
+        cma_storage::facade::set_storage_path(Some(Path::new(&cwd)));
+    } else {
+        cma_storage::facade::set_storage_path(None);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct TestConfig {
+        per_project: bool,
+        backups: bool,
+    }
+
+    struct Recorded {
+        backup_calls: Vec<bool>,
+        path_calls: Vec<Option<String>>,
+        warnings: usize,
+    }
+
+    fn run_scope(config: &TestConfig, cli_sync: bool) -> Recorded {
+        let mut backup_calls: Vec<bool> = Vec::new();
+        let mut path_calls: Vec<Option<String>> = Vec::new();
+        let mut warnings = 0usize;
+        {
+            let mut set_backup = |enabled: bool| backup_calls.push(enabled);
+            let mut set_path =
+                |path: Option<&str>| path_calls.push(path.map(|p| p.to_string()));
+            let mut warn = || warnings += 1;
+            let mut deps = AccountStorageScopeDeps {
+                get_per_project_accounts: &|c: &TestConfig| c.per_project,
+                get_storage_backup_enabled: &|c: &TestConfig| c.backups,
+                is_codex_cli_sync_enabled: &move || cli_sync,
+                set_storage_backup_enabled: &mut set_backup,
+                set_storage_path: &mut set_path,
+                get_cwd: &|| "/work/project".to_string(),
+                warn_per_project_sync_conflict: &mut warn,
+            };
+            apply_account_storage_scope(config, &mut deps);
+        }
+        Recorded {
+            backup_calls,
+            path_calls,
+            warnings,
+        }
+    }
+
+    #[test]
+    fn cli_sync_collapses_per_project_to_global_and_warns() {
+        let recorded = run_scope(
+            &TestConfig {
+                per_project: true,
+                backups: true,
+            },
+            true,
+        );
+        assert_eq!(recorded.backup_calls, vec![true]);
+        assert_eq!(recorded.path_calls, vec![None]);
+        assert_eq!(recorded.warnings, 1);
+    }
+
+    #[test]
+    fn cli_sync_without_per_project_does_not_warn() {
+        let recorded = run_scope(
+            &TestConfig {
+                per_project: false,
+                backups: false,
+            },
+            true,
+        );
+        assert_eq!(recorded.backup_calls, vec![false]);
+        assert_eq!(recorded.path_calls, vec![None]);
+        assert_eq!(recorded.warnings, 0);
+    }
+
+    #[test]
+    fn per_project_without_cli_sync_scopes_to_cwd() {
+        let recorded = run_scope(
+            &TestConfig {
+                per_project: true,
+                backups: true,
+            },
+            false,
+        );
+        assert_eq!(
+            recorded.path_calls,
+            vec![Some("/work/project".to_string())]
+        );
+        assert_eq!(recorded.warnings, 0);
+    }
+
+    #[test]
+    fn global_scope_without_cli_sync_sets_null_path() {
+        let recorded = run_scope(
+            &TestConfig {
+                per_project: false,
+                backups: true,
+            },
+            false,
+        );
+        assert_eq!(recorded.path_calls, vec![None]);
+        assert_eq!(recorded.warnings, 0);
+    }
+
+    #[test]
+    fn warning_text_is_frozen() {
+        let text = per_project_sync_conflict_warning();
+        assert!(text.starts_with("[codex-multi-auth] Config conflict: perProjectAccounts = true"));
+        assert!(text.contains("'codex-multi-auth config set codexCliSync false'"));
+        assert!(text.contains("'codex-multi-auth config set perProjectAccounts false'"));
+        assert!(text.ends_with("This warning is emitted once per process."));
+    }
+}
diff --git a/crates/runtime/src/toast.rs b/crates/runtime/src/toast.rs
new file mode 100644
index 000000000..4eb37fe86
--- /dev/null
+++ b/crates/runtime/src/toast.rs
@@ -0,0 +1,199 @@
+//! Port of `lib/runtime/toast.ts` — `showRuntimeToast`.
+//!
+//! The TS implementation forwarded toasts to the JS host's TUI
+//! (`client.tui.showToast`), swallowing every error. The Rust CLI has no host
+//! UI (ARCHITECTURE §3: "toasts become stderr notices via
+//! `cma-runtime/src/toast.rs`"), so a toast becomes a one-line stderr notice.
+//! To keep long-running processes (proxy/router) from spamming stderr with
+//! repeated notices, identical messages are debounced: a message that was
+//! already shown within the last 60 seconds is suppressed (rate-limit
+//! debounce, ARCHITECTURE §6.12). Errors writing to stderr are ignored,
+//! matching the TS "ignore when TUI is not available" contract.
+
+use std::collections::HashMap;
+use std::io::Write;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use cma_core::constants::PLUGIN_NAME;
+
+/// Toast variants (TS union `"info" | "success" | "warning" | "error"`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub enum ToastVariant {
+    Info,
+    #[default]
+    Success,
+    Warning,
+    Error,
+}
+
+impl ToastVariant {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ToastVariant::Info => "info",
+            ToastVariant::Success => "success",
+            ToastVariant::Warning => "warning",
+            ToastVariant::Error => "error",
+        }
+    }
+}
+
+/// Optional toast options (TS `{ title?, duration? }`). `duration` has no
+/// stderr equivalent and is accepted for signature parity only.
+#[derive(Debug, Clone, Default)]
+pub struct ToastOptions {
+    pub title: Option<String>,
+    pub duration: Option<u64>,
+}
+
+/// Identical-message debounce window.
+const TOAST_DEBOUNCE_MS: u64 = 60_000;
+
+/// Message → last-emitted instant. Capped opportunistically: expired entries
+/// are pruned on every emit, so the map only grows with concurrently-live
+/// distinct messages.
+static TOAST_HISTORY: Mutex<Option<HashMap<String, Instant>>> = Mutex::new(None);
+
+/// Test capture sink: when armed, emitted toasts are recorded here (and NOT
+/// written to stderr). The identical-message debounce still applies first,
+/// so captures reflect exactly what a user would have seen.
+static TOAST_CAPTURE: Mutex<Option<Vec<(String, String)>>> = Mutex::new(None);
+
+/// Show a runtime toast as a stderr notice.
+///
+/// Returns `true` when the notice was emitted, `false` when it was suppressed
+/// by the 60 s identical-message debounce. All I/O errors are swallowed.
+pub fn show_runtime_toast(message: &str, variant: ToastVariant) -> bool {
+    show_runtime_toast_with(message, variant, &ToastOptions::default())
+}
+
+/// [`show_runtime_toast`] with options. `title`, when present and non-empty,
+/// is prefixed onto the notice (`title: message`); `duration` is ignored.
+pub fn show_runtime_toast_with(
+    message: &str,
+    variant: ToastVariant,
+    options: &ToastOptions,
+) -> bool {
+    let body = match options.title.as_deref() {
+        // TS spreads `...(options?.title && { title })` — only truthy titles.
+        Some(title) if !title.is_empty() => format!("{title}: {message}"),
+        _ => message.to_string(),
+    };
+    let key = format!("{}\u{0}{}", variant.as_str(), body);
+    let now = Instant::now();
+    {
+        let mut guard = TOAST_HISTORY
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        let history = guard.get_or_insert_with(HashMap::new);
+        let window = Duration::from_millis(TOAST_DEBOUNCE_MS);
+        if let Some(last) = history.get(&key)
+            && now.duration_since(*last) < window
+        {
+            return false;
+        }
+        history.retain(|_, last| now.duration_since(*last) < window);
+        history.insert(key, now);
+    }
+    {
+        let mut capture = TOAST_CAPTURE
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        if let Some(captured) = capture.as_mut() {
+            captured.push((variant.as_str().to_string(), body));
+            return true;
+        }
+    }
+    let line = match variant {
+        ToastVariant::Success => format!("[{PLUGIN_NAME}] {body}"),
+        _ => format!("[{PLUGIN_NAME}] {}: {body}", variant.as_str()),
+    };
+    // Swallow write errors (TS swallowed every showToast failure).
+    let _ = writeln!(std::io::stderr(), "{line}");
+    true
+}
+
+/// Test hook: arm the capture sink (also clears the debounce history so the
+/// capture starts from a clean slate).
+pub fn start_toast_capture_for_tests() {
+    reset_toast_debounce_for_tests();
+    let mut capture = TOAST_CAPTURE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    *capture = Some(Vec::new());
+}
+
+/// Test hook: disarm the capture sink and return the `(variant, message)`
+/// pairs emitted while it was armed.
+pub fn take_captured_toasts_for_tests() -> Vec<(String, String)> {
+    let mut capture = TOAST_CAPTURE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    capture.take().unwrap_or_default()
+}
+
+/// Test hook: clear the debounce history so tests observe fresh behavior.
+pub fn reset_toast_debounce_for_tests() {
+    let mut guard = TOAST_HISTORY
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    *guard = None;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    #[serial(toast)]
+    fn emits_then_debounces_identical_messages() {
+        reset_toast_debounce_for_tests();
+        assert!(show_runtime_toast("Switched to account 2", ToastVariant::Info));
+        // Identical message+variant within the window: suppressed.
+        assert!(!show_runtime_toast("Switched to account 2", ToastVariant::Info));
+        // Different message: emitted.
+        assert!(show_runtime_toast("Switched to account 3", ToastVariant::Info));
+        // Different variant of the same message: distinct key, emitted.
+        assert!(show_runtime_toast("Switched to account 2", ToastVariant::Warning));
+        reset_toast_debounce_for_tests();
+    }
+
+    #[test]
+    #[serial(toast)]
+    fn title_is_folded_into_the_debounce_key() {
+        reset_toast_debounce_for_tests();
+        let with_title = ToastOptions {
+            title: Some("Update".to_string()),
+            duration: None,
+        };
+        assert!(show_runtime_toast_with("ready", ToastVariant::Success, &with_title));
+        assert!(!show_runtime_toast_with("ready", ToastVariant::Success, &with_title));
+        // Bare message is a different key.
+        assert!(show_runtime_toast("ready", ToastVariant::Success));
+        reset_toast_debounce_for_tests();
+    }
+
+    #[test]
+    #[serial(toast)]
+    fn empty_title_is_ignored_like_ts_falsy_title() {
+        reset_toast_debounce_for_tests();
+        let empty_title = ToastOptions {
+            title: Some(String::new()),
+            duration: None,
+        };
+        assert!(show_runtime_toast_with("msg", ToastVariant::Error, &empty_title));
+        // Same key as a bare message → debounced.
+        assert!(!show_runtime_toast("msg", ToastVariant::Error));
+        reset_toast_debounce_for_tests();
+    }
+
+    #[test]
+    fn variant_strings_are_frozen() {
+        assert_eq!(ToastVariant::Info.as_str(), "info");
+        assert_eq!(ToastVariant::Success.as_str(), "success");
+        assert_eq!(ToastVariant::Warning.as_str(), "warning");
+        assert_eq!(ToastVariant::Error.as_str(), "error");
+        assert_eq!(ToastVariant::default(), ToastVariant::Success);
+    }
+}
diff --git a/crates/runtime/src/ui_runtime.rs b/crates/runtime/src/ui_runtime.rs
new file mode 100644
index 000000000..447e8d122
--- /dev/null
+++ b/crates/runtime/src/ui_runtime.rs
@@ -0,0 +1,145 @@
+//! Port of `lib/runtime/ui-runtime.ts` — applies plugin-config UI settings to
+//! the process-global UI runtime options, plus the shared `getStatusMarker`
+//! (duplicated in TS by `status-marker.ts`; the duplicate lives in
+//! [`crate::current_account::get_runtime_status_marker`]).
+//!
+//! Dependency note: `cma-runtime` does not depend on `cma-tui` (ARCHITECTURE
+//! §4 DAG — the manager links both). The TS function already took
+//! `setUiRuntimeOptions` as an injected parameter, so the Rust port keeps the
+//! same DI shape: this module extracts the config values and hands them to
+//! the injected setter; `cma-manager` wires in
+//! `cma_tui::runtime_options::set_ui_runtime_options`.
+
+use cma_config::getters::{get_codex_tui_color_profile, get_codex_tui_glyph_mode, get_codex_tui_v2};
+use cma_config::load::load_plugin_config;
+use cma_core::schemas::plugin_config::{CodexTuiColorProfile, CodexTuiGlyphMode, PluginConfig};
+
+/// Status kinds accepted by the status-marker helpers
+/// (TS `"ok" | "warning" | "error"`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RuntimeStatus {
+    Ok,
+    Warning,
+    Error,
+}
+
+/// The `{v2Enabled, colorProfile, glyphMode}` object literal the TS passed to
+/// `setUiRuntimeOptions`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UiRuntimeConfigValues {
+    pub v2_enabled: bool,
+    pub color_profile: CodexTuiColorProfile,
+    pub glyph_mode: CodexTuiGlyphMode,
+}
+
+/// Pure extraction of the UI runtime settings from the plugin config (the
+/// argument the TS built inline; also `resolveUiRuntimeFromConfig`).
+pub fn resolve_ui_runtime_from_config(plugin_config: &PluginConfig) -> UiRuntimeConfigValues {
+    UiRuntimeConfigValues {
+        v2_enabled: get_codex_tui_v2(plugin_config),
+        color_profile: get_codex_tui_color_profile(plugin_config),
+        glyph_mode: get_codex_tui_glyph_mode(plugin_config),
+    }
+}
+
+/// `applyUiRuntimeFromConfig(pluginConfig, setUiRuntimeOptions)` — pushes the
+/// extracted values through the injected setter and returns its result (the
+/// resolved `UiRuntimeOptions` when wired to the cma-tui global).
+pub fn apply_ui_runtime_from_config<R>(
+    plugin_config: &PluginConfig,
+    set_ui_runtime_options: impl FnOnce(UiRuntimeConfigValues) -> R,
+) -> R {
+    set_ui_runtime_options(resolve_ui_runtime_from_config(plugin_config))
+}
+
+/// `resolveUiRuntimeEntry` — trivial
+/// `applyUiRuntimeFromConfig(loadPluginConfig())` indirection.
+pub fn resolve_ui_runtime_entry<R>(
+    set_ui_runtime_options: impl FnOnce(UiRuntimeConfigValues) -> R,
+) -> R {
+    apply_ui_runtime_from_config(&load_plugin_config(), set_ui_runtime_options)
+}
+
+/// The slice of the TS `UiRuntimeOptions` the status marker reads:
+/// `v2Enabled` + `theme.glyphs.check` / `theme.glyphs.cross`. The manager
+/// builds this from the live `cma_tui` runtime options.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StatusMarkerTheme {
+    pub v2_enabled: bool,
+    /// `ui.theme.glyphs.check` (unicode `✓` or ascii `+`).
+    pub check: String,
+    /// `ui.theme.glyphs.cross` (unicode `✗` or ascii `x`).
+    pub cross: String,
+}
+
+/// `getStatusMarker` — v2 disabled: `✓` / `!` / `✗`; v2 enabled: the theme's
+/// check/cross glyphs (warning stays `"!"`).
+pub fn get_status_marker(ui: &StatusMarkerTheme, status: RuntimeStatus) -> String {
+    if !ui.v2_enabled {
+        return match status {
+            RuntimeStatus::Ok => "\u{2713}".to_string(),
+            RuntimeStatus::Warning => "!".to_string(),
+            RuntimeStatus::Error => "\u{2717}".to_string(),
+        };
+    }
+    match status {
+        RuntimeStatus::Ok => ui.check.clone(),
+        RuntimeStatus::Warning => "!".to_string(),
+        RuntimeStatus::Error => ui.cross.clone(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ui-runtime.test.ts: marker fallback matrix.
+    #[test]
+    fn status_marker_uses_legacy_glyphs_when_v2_disabled() {
+        let ui = StatusMarkerTheme {
+            v2_enabled: false,
+            check: "+".to_string(),
+            cross: "x".to_string(),
+        };
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Ok), "\u{2713}");
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Warning), "!");
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Error), "\u{2717}");
+    }
+
+    #[test]
+    fn status_marker_uses_theme_glyphs_when_v2_enabled() {
+        let ui = StatusMarkerTheme {
+            v2_enabled: true,
+            check: "+".to_string(),
+            cross: "x".to_string(),
+        };
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Ok), "+");
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Warning), "!");
+        assert_eq!(get_status_marker(&ui, RuntimeStatus::Error), "x");
+    }
+
+    // ui-runtime-entry.test.ts: config values are pushed into the injected
+    // setter.
+    #[test]
+    fn apply_ui_runtime_from_config_pushes_config_values() {
+        let config = PluginConfig {
+            codex_tui_v2: Some(false),
+            codex_tui_color_profile: Some(CodexTuiColorProfile::Ansi16),
+            codex_tui_glyph_mode: Some(CodexTuiGlyphMode::Unicode),
+            ..PluginConfig::default()
+        };
+        let applied = apply_ui_runtime_from_config(&config, |values| values);
+        assert!(!applied.v2_enabled);
+        assert_eq!(applied.color_profile, CodexTuiColorProfile::Ansi16);
+        assert_eq!(applied.glyph_mode, CodexTuiGlyphMode::Unicode);
+    }
+
+    #[test]
+    fn resolve_defaults_follow_config_getters() {
+        let values = resolve_ui_runtime_from_config(&PluginConfig::default());
+        // Getter defaults: v2 on, truecolor, ascii (spec 01 §5.4).
+        assert!(values.v2_enabled);
+        assert_eq!(values.color_profile, CodexTuiColorProfile::Truecolor);
+        assert_eq!(values.glyph_mode, CodexTuiGlyphMode::Ascii);
+    }
+}
diff --git a/crates/runtime/src/verify_flagged.rs b/crates/runtime/src/verify_flagged.rs
new file mode 100644
index 000000000..6ac0df650
--- /dev/null
+++ b/crates/runtime/src/verify_flagged.rs
@@ -0,0 +1,479 @@
+//! Port of `lib/runtime/verify-flagged.ts` (+ `flagged-verify-types.ts`) —
+//! the CLI `verify-flagged` engine (spec 10 §14).
+//!
+//! Restoration ladder per flagged account: Codex CLI token cache first
+//! (needs a finite future `expiresAt` AND a non-blank refresh token), else a
+//! queued refresh. Restored accounts flow through the login-time account
+//! resolver (`resolveTokenSuccessAccount`) with accountId/label backfill
+//! from the flagged record.
+
+#![allow(clippy::result_large_err)] // CodexError is the crate-wide error vocabulary.
+
+use cma_core::errors::CodexError;
+use cma_core::logger::mask_email;
+use cma_core::schemas::account_storage::AccountIdSource;
+use cma_core::schemas::flagged::{FlaggedAccountMetadataV1, FlaggedAccountStorageV1};
+use cma_core::schemas::token::{TokenResult, TokenSuccess};
+
+use crate::account_check::CliCachedTokens;
+use crate::account_selection::TokenSuccessWithAccount;
+
+/// TS `FlaggedVerificationState` (flagged-verify-types.ts).
+#[derive(Debug, Default)]
+pub struct FlaggedVerificationState {
+    pub remaining: Vec<FlaggedAccountMetadataV1>,
+    pub restored: Vec<TokenSuccessWithAccount>,
+}
+
+/// TS `createFlaggedVerificationState()`.
+pub fn create_flagged_verification_state() -> FlaggedVerificationState {
+    FlaggedVerificationState::default()
+}
+
+/// I/O seams of [`verify_runtime_flagged_accounts`].
+#[allow(async_fn_in_trait)]
+pub trait VerifyFlaggedDeps {
+    async fn load_flagged_accounts(&mut self) -> Result<FlaggedAccountStorageV1, CodexError>;
+    /// Errors swallowed at the call site in TS (`.catch(() => null)`).
+    async fn lookup_codex_cli_tokens_by_email(
+        &mut self,
+        email: Option<&str>,
+    ) -> Option<CliCachedTokens>;
+    async fn queued_refresh(&mut self, refresh_token: &str) -> TokenResult;
+    /// TS `resolveTokenSuccessAccount` — may fail (routed into the
+    /// per-account catch: `ERROR (...)`, account kept with updated
+    /// `lastError`).
+    fn resolve_token_success_account(
+        &mut self,
+        tokens: TokenSuccess,
+    ) -> Result<TokenSuccessWithAccount, CodexError>;
+    async fn persist_accounts(
+        &mut self,
+        results: &[TokenSuccessWithAccount],
+        replace_all: bool,
+    ) -> Result<(), CodexError>;
+    /// TS optional `persistAccountsAndFlagged` — override BOTH methods to
+    /// enable the combined write.
+    fn supports_combined_persist(&self) -> bool {
+        false
+    }
+    async fn persist_accounts_and_flagged(
+        &mut self,
+        results: &[TokenSuccessWithAccount],
+        flagged: &FlaggedAccountStorageV1,
+        replace_all: bool,
+    ) -> Result<(), CodexError> {
+        let _ = (results, flagged, replace_all);
+        Ok(())
+    }
+    fn invalidate_account_manager_cache(&mut self);
+    async fn save_flagged_accounts(
+        &mut self,
+        storage: &FlaggedAccountStorageV1,
+    ) -> Result<(), CodexError>;
+    fn log_error(&mut self, message: &str) {
+        let _ = message;
+    }
+    fn now_ms(&mut self) -> i64 {
+        cma_core::utils::now_ms()
+    }
+    fn show_line(&mut self, message: &str);
+}
+
+/// Backfill accountId/label from the flagged record when the resolver did
+/// not set them (TS inline logic, shared by both restoration paths).
+fn backfill_from_flagged(
+    mut resolved: TokenSuccessWithAccount,
+    flagged: &FlaggedAccountMetadataV1,
+) -> TokenSuccessWithAccount {
+    if resolved.account_id_override.is_none()
+        && let Some(account_id) = flagged.account_id.clone()
+    {
+        resolved.account_id_override = Some(account_id);
+        resolved.account_id_source =
+            Some(flagged.account_id_source.unwrap_or(AccountIdSource::Manual));
+    }
+    if resolved.account_label.is_none()
+        && let Some(label) = flagged.account_label.clone()
+    {
+        resolved.account_label = Some(label);
+    }
+    resolved
+}
+
+fn truncate_chars(message: &str, limit: usize) -> String {
+    message.chars().take(limit).collect()
+}
+
+/// TS `verifyRuntimeFlaggedAccounts(deps)`.
+pub async fn verify_runtime_flagged_accounts<D: VerifyFlaggedDeps>(
+    deps: &mut D,
+) -> Result<(), CodexError> {
+    let flagged_storage = deps.load_flagged_accounts().await?;
+    if flagged_storage.accounts.is_empty() {
+        deps.show_line("\nNo flagged accounts to verify.\n");
+        return Ok(());
+    }
+
+    deps.show_line("\nVerifying flagged accounts...\n");
+    let mut state = create_flagged_verification_state();
+    let total = flagged_storage.accounts.len();
+
+    for (i, flagged) in flagged_storage.accounts.iter().enumerate() {
+        let masked_email = flagged.email.as_deref().map(mask_email);
+        let label = flagged
+            .account_label
+            .clone()
+            .or(masked_email)
+            .unwrap_or_else(|| format!("Flagged {}", i + 1));
+
+        // The TS try-block; Err = a caught exception.
+        let item_result: Result<(), CodexError> = async {
+            let cached = deps
+                .lookup_codex_cli_tokens_by_email(flagged.email.as_deref())
+                .await;
+            let now = deps.now_ms();
+            if let Some(cached) = cached
+                && cached
+                    .expires_at
+                    .is_some_and(|v| v.is_finite() && v > now as f64)
+            {
+                let refresh_token = cached
+                    .refresh_token
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|t| !t.is_empty())
+                    .map(str::to_string);
+                if let Some(refresh_token) = refresh_token {
+                    let resolved = deps.resolve_token_success_account(TokenSuccess {
+                        access: cached.access_token.clone(),
+                        refresh: refresh_token,
+                        expires: cached.expires_at.map(|v| v as i64).unwrap_or_default(),
+                        id_token: None,
+                        multi_account: Some(true),
+                    })?;
+                    let resolved = backfill_from_flagged(resolved, flagged);
+                    state.restored.push(resolved);
+                    deps.show_line(&format!(
+                        "[{}/{total}] {label}: RESTORED (Codex CLI cache)",
+                        i + 1
+                    ));
+                    return Ok(());
+                }
+            }
+
+            let refresh_result = deps.queued_refresh(&flagged.refresh_token).await;
+            match refresh_result {
+                TokenResult::Failed(failure) => {
+                    let message = failure
+                        .message
+                        .clone()
+                        .or_else(|| failure.reason.map(|r| r.as_str().to_string()))
+                        .unwrap_or_else(|| "refresh failed".to_string());
+                    deps.show_line(&format!(
+                        "[{}/{total}] {label}: STILL FLAGGED ({message})",
+                        i + 1
+                    ));
+                    state.remaining.push(flagged.clone());
+                    Ok(())
+                }
+                TokenResult::Success(refreshed) => {
+                    let resolved = deps.resolve_token_success_account(refreshed)?;
+                    let resolved = backfill_from_flagged(resolved, flagged);
+                    state.restored.push(resolved);
+                    deps.show_line(&format!("[{}/{total}] {label}: RESTORED", i + 1));
+                    Ok(())
+                }
+            }
+        }
+        .await;
+
+        if let Err(error) = item_result {
+            let message = error.message().to_string();
+            deps.log_error(&format!(
+                "Failed to verify flagged account {label}: {message}"
+            ));
+            deps.show_line(&format!(
+                "[{}/{total}] {label}: ERROR ({})",
+                i + 1,
+                truncate_chars(&message, 120)
+            ));
+            let mut kept = flagged.clone();
+            kept.last_error = Some(message);
+            state.remaining.push(kept);
+        }
+    }
+
+    let next_flagged_storage = FlaggedAccountStorageV1 {
+        version: Default::default(),
+        accounts: state.remaining.clone(),
+    };
+
+    if !state.restored.is_empty() && deps.supports_combined_persist() {
+        deps.persist_accounts_and_flagged(&state.restored, &next_flagged_storage, false)
+            .await?;
+        deps.invalidate_account_manager_cache();
+    } else {
+        if !state.restored.is_empty() {
+            deps.persist_accounts(&state.restored, false).await?;
+            deps.invalidate_account_manager_cache();
+        }
+        deps.save_flagged_accounts(&next_flagged_storage).await?;
+    }
+
+    deps.show_line("");
+    deps.show_line(&format!(
+        "Results: {} restored, {} still flagged",
+        state.restored.len(),
+        state.remaining.len()
+    ));
+    deps.show_line("");
+    Ok(())
+}
+
+// =============================================================================
+// Tests — ported from test/runtime-verify-flagged.test.ts
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::token::{TokenFailure, TokenFailureReason};
+
+    fn flagged_account(refresh: &str, email: Option<&str>) -> FlaggedAccountMetadataV1 {
+        let mut account =
+            cma_core::schemas::account_storage::AccountMetadataV3::new(refresh, 1, 1);
+        account.email = email.map(str::to_string);
+        FlaggedAccountMetadataV1::from_account(
+            account,
+            500,
+            Some("token-invalid".to_string()),
+            Some("old error".to_string()),
+        )
+    }
+
+    struct FakeDeps {
+        flagged: FlaggedAccountStorageV1,
+        cli_cache: Option<CliCachedTokens>,
+        refresh_result: Option<TokenResult>,
+        resolver_fails: bool,
+        lines: Vec<String>,
+        errors: Vec<String>,
+        persisted: Option<(Vec<TokenSuccessWithAccount>, bool)>,
+        combined: Option<(Vec<TokenSuccessWithAccount>, FlaggedAccountStorageV1, bool)>,
+        combined_supported: bool,
+        saved_flagged: Option<FlaggedAccountStorageV1>,
+        invalidations: u32,
+    }
+
+    impl Default for FakeDeps {
+        fn default() -> Self {
+            Self {
+                flagged: FlaggedAccountStorageV1::empty(),
+                cli_cache: None,
+                refresh_result: None,
+                resolver_fails: false,
+                lines: Vec::new(),
+                errors: Vec::new(),
+                persisted: None,
+                combined: None,
+                combined_supported: false,
+                saved_flagged: None,
+                invalidations: 0,
+            }
+        }
+    }
+
+    impl VerifyFlaggedDeps for FakeDeps {
+        async fn load_flagged_accounts(&mut self) -> Result<FlaggedAccountStorageV1, CodexError> {
+            Ok(self.flagged.clone())
+        }
+        async fn lookup_codex_cli_tokens_by_email(
+            &mut self,
+            _email: Option<&str>,
+        ) -> Option<CliCachedTokens> {
+            self.cli_cache.clone()
+        }
+        async fn queued_refresh(&mut self, _refresh_token: &str) -> TokenResult {
+            self.refresh_result
+                .clone()
+                .unwrap_or(TokenResult::Failed(TokenFailure::default()))
+        }
+        fn resolve_token_success_account(
+            &mut self,
+            tokens: TokenSuccess,
+        ) -> Result<TokenSuccessWithAccount, CodexError> {
+            if self.resolver_fails {
+                return Err(CodexError::new("resolver exploded"));
+            }
+            Ok(TokenSuccessWithAccount::plain(tokens))
+        }
+        async fn persist_accounts(
+            &mut self,
+            results: &[TokenSuccessWithAccount],
+            replace_all: bool,
+        ) -> Result<(), CodexError> {
+            self.persisted = Some((results.to_vec(), replace_all));
+            Ok(())
+        }
+        fn supports_combined_persist(&self) -> bool {
+            self.combined_supported
+        }
+        async fn persist_accounts_and_flagged(
+            &mut self,
+            results: &[TokenSuccessWithAccount],
+            flagged: &FlaggedAccountStorageV1,
+            replace_all: bool,
+        ) -> Result<(), CodexError> {
+            self.combined = Some((results.to_vec(), flagged.clone(), replace_all));
+            Ok(())
+        }
+        fn invalidate_account_manager_cache(&mut self) {
+            self.invalidations += 1;
+        }
+        async fn save_flagged_accounts(
+            &mut self,
+            storage: &FlaggedAccountStorageV1,
+        ) -> Result<(), CodexError> {
+            self.saved_flagged = Some(storage.clone());
+            Ok(())
+        }
+        fn log_error(&mut self, message: &str) {
+            self.errors.push(message.to_string());
+        }
+        fn now_ms(&mut self) -> i64 {
+            1_000
+        }
+        fn show_line(&mut self, message: &str) {
+            self.lines.push(message.to_string());
+        }
+    }
+
+    #[tokio::test]
+    async fn empty_pool_prints_nothing_to_verify() {
+        let mut deps = FakeDeps::default();
+        verify_runtime_flagged_accounts(&mut deps).await.unwrap();
+        assert_eq!(deps.lines, vec!["\nNo flagged accounts to verify.\n"]);
+        assert!(deps.saved_flagged.is_none());
+    }
+
+    #[tokio::test]
+    async fn restores_via_cli_cache_with_backfill() {
+        let mut flagged = flagged_account("rt-flagged", Some("f@example.com"));
+        flagged.account_id = Some("acc_prev".to_string());
+        flagged.account_label = Some("Prev label".to_string());
+        let mut deps = FakeDeps {
+            flagged: FlaggedAccountStorageV1 {
+                version: Default::default(),
+                accounts: vec![flagged],
+            },
+            cli_cache: Some(CliCachedTokens {
+                access_token: "at-cli".to_string(),
+                refresh_token: Some("  rt-cli  ".to_string()),
+                expires_at: Some(2_000.0),
+            }),
+            ..FakeDeps::default()
+        };
+        verify_runtime_flagged_accounts(&mut deps).await.unwrap();
+
+        assert_eq!(deps.lines[1], "[1/1] Prev label: RESTORED (Codex CLI cache)");
+        let (persisted, replace_all) = deps.persisted.expect("persisted");
+        assert!(!replace_all);
+        assert_eq!(persisted.len(), 1);
+        assert_eq!(persisted[0].tokens.refresh, "rt-cli");
+        assert_eq!(persisted[0].tokens.multi_account, Some(true));
+        // Backfill from the flagged record (resolver returned plain tokens).
+        assert_eq!(persisted[0].account_id_override.as_deref(), Some("acc_prev"));
+        assert_eq!(persisted[0].account_id_source, Some(AccountIdSource::Manual));
+        assert_eq!(persisted[0].account_label.as_deref(), Some("Prev label"));
+        // Flagged pool emptied.
+        assert!(deps.saved_flagged.expect("flagged saved").accounts.is_empty());
+        assert_eq!(deps.invalidations, 1);
+        assert_eq!(deps.lines[3], "Results: 1 restored, 0 still flagged");
+    }
+
+    #[tokio::test]
+    async fn cli_cache_without_refresh_token_falls_through_to_refresh() {
+        let mut deps = FakeDeps {
+            flagged: FlaggedAccountStorageV1 {
+                version: Default::default(),
+                accounts: vec![flagged_account("rt-flagged", Some("f@example.com"))],
+            },
+            cli_cache: Some(CliCachedTokens {
+                access_token: "at-cli".to_string(),
+                refresh_token: Some("   ".to_string()),
+                expires_at: Some(2_000.0),
+            }),
+            refresh_result: Some(TokenResult::Failed(TokenFailure {
+                reason: Some(TokenFailureReason::Unknown),
+                status_code: None,
+                message: None,
+            })),
+            ..FakeDeps::default()
+        };
+        verify_runtime_flagged_accounts(&mut deps).await.unwrap();
+        assert_eq!(deps.lines[1], "[1/1] f***@***.com: STILL FLAGGED (unknown)");
+        assert!(deps.persisted.is_none());
+        let saved = deps.saved_flagged.expect("flagged saved");
+        assert_eq!(saved.accounts.len(), 1);
+        assert_eq!(deps.lines[3], "Results: 0 restored, 1 still flagged");
+    }
+
+    #[tokio::test]
+    async fn refresh_success_restores_and_uses_combined_persist_when_available() {
+        let mut deps = FakeDeps {
+            flagged: FlaggedAccountStorageV1 {
+                version: Default::default(),
+                accounts: vec![flagged_account("rt-flagged", None)],
+            },
+            refresh_result: Some(TokenResult::Success(TokenSuccess {
+                access: "at-new".to_string(),
+                refresh: "rt-new".to_string(),
+                expires: 9_999,
+                id_token: None,
+                multi_account: None,
+            })),
+            combined_supported: true,
+            ..FakeDeps::default()
+        };
+        verify_runtime_flagged_accounts(&mut deps).await.unwrap();
+        assert_eq!(deps.lines[1], "[1/1] Flagged 1: RESTORED");
+        let (results, flagged, replace_all) = deps.combined.expect("combined persist");
+        assert_eq!(results.len(), 1);
+        assert!(flagged.accounts.is_empty());
+        assert!(!replace_all);
+        // Combined path does NOT also call the split writers.
+        assert!(deps.persisted.is_none());
+        assert!(deps.saved_flagged.is_none());
+        assert_eq!(deps.invalidations, 1);
+    }
+
+    #[tokio::test]
+    async fn resolver_error_keeps_account_with_updated_last_error() {
+        let mut deps = FakeDeps {
+            flagged: FlaggedAccountStorageV1 {
+                version: Default::default(),
+                accounts: vec![flagged_account("rt-flagged", Some("x@example.com"))],
+            },
+            refresh_result: Some(TokenResult::Success(TokenSuccess {
+                access: "at".to_string(),
+                refresh: "rt".to_string(),
+                expires: 9_999,
+                id_token: None,
+                multi_account: None,
+            })),
+            resolver_fails: true,
+            ..FakeDeps::default()
+        };
+        verify_runtime_flagged_accounts(&mut deps).await.unwrap();
+        assert_eq!(deps.lines[1], "[1/1] x***@***.com: ERROR (resolver exploded)");
+        assert_eq!(
+            deps.errors,
+            vec!["Failed to verify flagged account x***@***.com: resolver exploded"]
+        );
+        let saved = deps.saved_flagged.expect("flagged saved");
+        assert_eq!(saved.accounts.len(), 1);
+        assert_eq!(saved.accounts[0].last_error.as_deref(), Some("resolver exploded"));
+        assert_eq!(deps.lines[3], "Results: 0 restored, 1 still flagged");
+    }
+}
diff --git a/crates/storage/Cargo.toml b/crates/storage/Cargo.toml
new file mode 100644
index 000000000..5ea7e1812
--- /dev/null
+++ b/crates/storage/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "cma-storage"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+tokio.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/storage/src/backup_metadata.rs b/crates/storage/src/backup_metadata.rs
new file mode 100644
index 000000000..a668d7f76
--- /dev/null
+++ b/crates/storage/src/backup_metadata.rs
@@ -0,0 +1,581 @@
+//! Port of `lib/storage/backup-metadata.ts` + `backup-metadata-builder.ts`
+//! (+ the storage.ts WAL/flagged snapshot describers; the dead
+//! `metadata-section.ts` / `snapshot-inspectors.ts` duplicates are
+//! consolidated here ONCE — spec gotcha 35) — spec 02 §13.1.
+//!
+//! For the ACCOUNTS section, `latestValidPath` is overridden by a
+//! kind-priority pick: valid snapshots among {discovered-backup(4) >
+//! backup-history(3) > backup(2)}, then WAL(1), then anything (primary=0);
+//! ties broken by mtime DESC.
+
+use serde::{Serialize, Serializer};
+use serde_json::{Value, json};
+
+use cma_core::logger::create_logger;
+use cma_core::schemas::journal::AccountsJournalEntry;
+use cma_core::schemas::parse::safe_parse_json_with_context;
+
+use crate::snapshot::{describe_account_snapshot, stat_snapshot};
+
+/// TS `BackupSnapshotKind`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
+pub enum BackupSnapshotKind {
+    #[default]
+    #[serde(rename = "accounts-primary")]
+    AccountsPrimary,
+    #[serde(rename = "accounts-wal")]
+    AccountsWal,
+    #[serde(rename = "accounts-backup")]
+    AccountsBackup,
+    #[serde(rename = "accounts-backup-history")]
+    AccountsBackupHistory,
+    #[serde(rename = "accounts-discovered-backup")]
+    AccountsDiscoveredBackup,
+    #[serde(rename = "flagged-primary")]
+    FlaggedPrimary,
+    #[serde(rename = "flagged-backup")]
+    FlaggedBackup,
+    #[serde(rename = "flagged-backup-history")]
+    FlaggedBackupHistory,
+    #[serde(rename = "flagged-discovered-backup")]
+    FlaggedDiscoveredBackup,
+}
+
+impl BackupSnapshotKind {
+    /// Kind priority for the accounts `latestValidPath` selection (TS
+    /// `ACCOUNT_SNAPSHOT_PRIORITY`; unlisted kinds default to 0).
+    fn account_priority(self) -> i32 {
+        match self {
+            Self::AccountsDiscoveredBackup => 4,
+            Self::AccountsBackupHistory => 3,
+            Self::AccountsBackup => 2,
+            Self::AccountsWal => 1,
+            _ => 0,
+        }
+    }
+}
+
+/// Serialize an epoch-ms float the way V8 prints it: integral values without
+/// the trailing `.0` (`1753500000000`, not `1753500000000.0`).
+fn serialize_opt_js_number<S: Serializer>(
+    value: &Option<f64>,
+    serializer: S,
+) -> Result<S::Ok, S::Error> {
+    match value {
+        Some(v) if v.fract() == 0.0 && v.abs() <= 9_007_199_254_740_991.0 => {
+            serializer.serialize_i64(*v as i64)
+        }
+        Some(v) => serializer.serialize_f64(*v),
+        None => serializer.serialize_none(),
+    }
+}
+
+/// TS `BackupSnapshotMetadata`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct BackupSnapshotMetadata {
+    pub kind: BackupSnapshotKind,
+    pub path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub index: Option<usize>,
+    pub exists: bool,
+    pub valid: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub bytes: Option<u64>,
+    #[serde(
+        rename = "mtimeMs",
+        skip_serializing_if = "Option::is_none",
+        serialize_with = "serialize_opt_js_number"
+    )]
+    pub mtime_ms: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub version: Option<i64>,
+    #[serde(rename = "accountCount", skip_serializing_if = "Option::is_none")]
+    pub account_count: Option<usize>,
+    #[serde(rename = "flaggedCount", skip_serializing_if = "Option::is_none")]
+    pub flagged_count: Option<usize>,
+    #[serde(rename = "schemaErrors", skip_serializing_if = "Option::is_none")]
+    pub schema_errors: Option<Vec<String>>,
+}
+
+/// TS `BackupMetadataSection`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct BackupMetadataSection {
+    #[serde(rename = "storagePath")]
+    pub storage_path: String,
+    #[serde(rename = "latestValidPath", skip_serializing_if = "Option::is_none")]
+    pub latest_valid_path: Option<String>,
+    #[serde(rename = "snapshotCount")]
+    pub snapshot_count: usize,
+    #[serde(rename = "validSnapshotCount")]
+    pub valid_snapshot_count: usize,
+    pub snapshots: Vec<BackupSnapshotMetadata>,
+}
+
+/// TS `BackupMetadata`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct BackupMetadata {
+    pub accounts: BackupMetadataSection,
+    #[serde(rename = "flaggedAccounts")]
+    pub flagged_accounts: BackupMetadataSection,
+}
+
+/// TS `RestoreAssessment` (declared in backup-metadata.ts; built by
+/// `crate::restore`).
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct RestoreAssessment {
+    #[serde(rename = "storagePath")]
+    pub storage_path: String,
+    #[serde(rename = "restoreEligible")]
+    pub restore_eligible: bool,
+    #[serde(rename = "restoreReason", skip_serializing_if = "Option::is_none")]
+    pub restore_reason: Option<crate::restore::RestoreReason>,
+    #[serde(rename = "latestSnapshot", skip_serializing_if = "Option::is_none")]
+    pub latest_snapshot: Option<BackupSnapshotMetadata>,
+    #[serde(rename = "backupMetadata")]
+    pub backup_metadata: BackupMetadata,
+}
+
+/// TS `latestValidSnapshot` — newest valid snapshot by `mtimeMs ?? 0`
+/// (stable: first of a tie group wins).
+pub fn latest_valid_snapshot(
+    snapshots: &[BackupSnapshotMetadata],
+) -> Option<&BackupSnapshotMetadata> {
+    let mut best: Option<&BackupSnapshotMetadata> = None;
+    for snapshot in snapshots {
+        if !snapshot.valid {
+            continue;
+        }
+        match best {
+            None => best = Some(snapshot),
+            Some(current) => {
+                if snapshot.mtime_ms.unwrap_or(0.0) > current.mtime_ms.unwrap_or(0.0) {
+                    best = Some(snapshot);
+                }
+            }
+        }
+    }
+    best
+}
+
+/// TS `buildMetadataSection`.
+pub fn build_metadata_section(
+    storage_path: &str,
+    snapshots: Vec<BackupSnapshotMetadata>,
+) -> BackupMetadataSection {
+    let latest_valid_path = latest_valid_snapshot(&snapshots).map(|s| s.path.clone());
+    BackupMetadataSection {
+        storage_path: storage_path.to_string(),
+        latest_valid_path,
+        snapshot_count: snapshots.len(),
+        valid_snapshot_count: snapshots.iter().filter(|s| s.valid).count(),
+        snapshots,
+    }
+}
+
+fn newest_valid_snapshot<'a>(
+    snapshots: &'a [BackupSnapshotMetadata],
+    kinds: Option<&[BackupSnapshotKind]>,
+) -> Option<&'a BackupSnapshotMetadata> {
+    let mut best: Option<&BackupSnapshotMetadata> = None;
+    for snapshot in snapshots {
+        if !snapshot.valid {
+            continue;
+        }
+        if let Some(kinds) = kinds
+            && !kinds.contains(&snapshot.kind)
+        {
+            continue;
+        }
+        match best {
+            None => best = Some(snapshot),
+            Some(current) => {
+                let candidate_priority = snapshot.kind.account_priority();
+                let current_priority = current.kind.account_priority();
+                if candidate_priority > current_priority
+                    || (candidate_priority == current_priority
+                        && snapshot.mtime_ms.unwrap_or(0.0) > current.mtime_ms.unwrap_or(0.0))
+                {
+                    best = Some(snapshot);
+                }
+            }
+        }
+    }
+    best
+}
+
+/// TS `selectLatestValidAccountPath` — kind-priority pick with WAL and
+/// anything-valid fallbacks.
+fn select_latest_valid_account_path(snapshots: &[BackupSnapshotMetadata]) -> Option<String> {
+    const PREFERRED: [BackupSnapshotKind; 3] = [
+        BackupSnapshotKind::AccountsDiscoveredBackup,
+        BackupSnapshotKind::AccountsBackupHistory,
+        BackupSnapshotKind::AccountsBackup,
+    ];
+    const WAL_ONLY: [BackupSnapshotKind; 1] = [BackupSnapshotKind::AccountsWal];
+    newest_valid_snapshot(snapshots, Some(&PREFERRED))
+        .or_else(|| newest_valid_snapshot(snapshots, Some(&WAL_ONLY)))
+        .or_else(|| newest_valid_snapshot(snapshots, None))
+        .map(|snapshot| snapshot.path.clone())
+}
+
+// ============================================================================
+// WAL / flagged describers (storage.ts privates, canonical here)
+// ============================================================================
+
+fn invalid_wal_snapshot(
+    path: &str,
+    stats: crate::snapshot::SnapshotStats,
+) -> BackupSnapshotMetadata {
+    BackupSnapshotMetadata {
+        kind: BackupSnapshotKind::AccountsWal,
+        path: path.to_string(),
+        exists: true,
+        valid: false,
+        bytes: stats.bytes,
+        mtime_ms: stats.mtime_ms,
+        ..Default::default()
+    }
+}
+
+/// TS `describeAccountsWalSnapshot` — WAL parse + checksum + inner
+/// normalization (non-throwing).
+pub async fn describe_accounts_wal_snapshot(path: &str) -> BackupSnapshotMetadata {
+    let stats = stat_snapshot(path).await;
+    if !stats.exists {
+        return BackupSnapshotMetadata {
+            kind: BackupSnapshotKind::AccountsWal,
+            path: path.to_string(),
+            exists: false,
+            valid: false,
+            ..Default::default()
+        };
+    }
+    let raw = match tokio::fs::read_to_string(path).await {
+        Ok(raw) => raw,
+        Err(_) => return invalid_wal_snapshot(path, stats),
+    };
+    let Some(entry) = safe_parse_json_with_context::<AccountsJournalEntry>(
+        &raw,
+        "storage.describeAccountsWalSnapshot",
+    ) else {
+        return invalid_wal_snapshot(path, stats);
+    };
+    if crate::misc::compute_sha256(&entry.content) != entry.checksum {
+        return invalid_wal_snapshot(path, stats);
+    }
+    // Schema-invalid inner payloads still flow through the normalizer so
+    // schemaErrors stay populated for observability; fail-closed on JSON
+    // syntax errors only.
+    let inner_data: Value = match serde_json::from_str(&entry.content) {
+        Ok(inner_data) => inner_data,
+        Err(_) => return invalid_wal_snapshot(path, stats),
+    };
+    let parsed = crate::parser::parse_and_normalize_storage(&inner_data);
+    BackupSnapshotMetadata {
+        kind: BackupSnapshotKind::AccountsWal,
+        path: path.to_string(),
+        index: None,
+        exists: true,
+        valid: parsed.normalized.is_some(),
+        bytes: stats.bytes,
+        mtime_ms: stats.mtime_ms,
+        version: parsed.stored_version,
+        account_count: parsed
+            .normalized
+            .as_ref()
+            .map(|normalized| normalized.accounts.len()),
+        flagged_count: None,
+        schema_errors: if parsed.schema_errors.is_empty() {
+            None
+        } else {
+            Some(parsed.schema_errors)
+        },
+    }
+}
+
+/// TS `describeFlaggedSnapshot`.
+pub async fn describe_flagged_snapshot(
+    path: &str,
+    kind: BackupSnapshotKind,
+    index: Option<usize>,
+) -> BackupSnapshotMetadata {
+    let log = create_logger("storage");
+    let stats = stat_snapshot(path).await;
+    if !stats.exists {
+        return BackupSnapshotMetadata {
+            kind,
+            path: path.to_string(),
+            index,
+            exists: false,
+            valid: false,
+            ..Default::default()
+        };
+    }
+    match crate::flagged::load_flagged_accounts_from_file(path).await {
+        Ok(storage) => BackupSnapshotMetadata {
+            kind,
+            path: path.to_string(),
+            index,
+            exists: true,
+            valid: true,
+            bytes: stats.bytes,
+            mtime_ms: stats.mtime_ms,
+            version: Some(1),
+            account_count: None,
+            flagged_count: Some(storage.accounts.len()),
+            schema_errors: None,
+        },
+        Err(error) => {
+            let is_enoent = error.kind() == std::io::ErrorKind::NotFound
+                || cma_core::fs_retry::code_of(&error) == Some("ENOENT");
+            if !is_enoent {
+                log.warn(
+                    "Failed to inspect flagged snapshot",
+                    Some(&json!({ "path": path, "error": error.to_string() })),
+                );
+            }
+            BackupSnapshotMetadata {
+                kind,
+                path: path.to_string(),
+                index,
+                exists: true,
+                valid: false,
+                bytes: stats.bytes,
+                mtime_ms: stats.mtime_ms,
+                ..Default::default()
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Builder (backup-metadata-builder.ts + storage.ts getBackupMetadata)
+// ============================================================================
+
+fn account_candidate_kind(candidate: &str, storage_path: &str) -> BackupSnapshotKind {
+    if candidate == format!("{storage_path}.bak") {
+        BackupSnapshotKind::AccountsBackup
+    } else if candidate.starts_with(&format!("{storage_path}.bak.")) {
+        BackupSnapshotKind::AccountsBackupHistory
+    } else {
+        BackupSnapshotKind::AccountsDiscoveredBackup
+    }
+}
+
+fn flagged_candidate_kind(candidate: &str, flagged_path: &str) -> BackupSnapshotKind {
+    if candidate == format!("{flagged_path}.bak") {
+        BackupSnapshotKind::FlaggedBackup
+    } else if candidate.starts_with(&format!("{flagged_path}.bak.")) {
+        BackupSnapshotKind::FlaggedBackupHistory
+    } else {
+        BackupSnapshotKind::FlaggedDiscoveredBackup
+    }
+}
+
+/// TS `getBackupMetadata()` — enumerate primary/WAL/backup/discovered
+/// snapshots for accounts + flagged storage.
+pub async fn get_backup_metadata() -> BackupMetadata {
+    let storage_path = std::path::PathBuf::from(crate::facade::get_storage_path())
+        .to_string_lossy()
+        .into_owned();
+    let flagged_path = crate::flagged::get_flagged_accounts_path();
+    let wal_path = crate::backup_paths::get_accounts_wal_path(&storage_path);
+
+    let account_candidates =
+        crate::backups::get_accounts_backup_recovery_candidates_with_discovery(&storage_path)
+            .await;
+    let mut account_snapshots: Vec<BackupSnapshotMetadata> = vec![
+        describe_account_snapshot(&storage_path, BackupSnapshotKind::AccountsPrimary, None).await,
+        describe_accounts_wal_snapshot(&wal_path).await,
+    ];
+    for (index, candidate) in account_candidates.iter().enumerate() {
+        let kind = account_candidate_kind(candidate, &storage_path);
+        account_snapshots.push(describe_account_snapshot(candidate, kind, Some(index)).await);
+    }
+
+    let flagged_candidates =
+        crate::backups::get_accounts_backup_recovery_candidates_with_discovery(&flagged_path)
+            .await;
+    let mut flagged_snapshots: Vec<BackupSnapshotMetadata> =
+        vec![describe_flagged_snapshot(&flagged_path, BackupSnapshotKind::FlaggedPrimary, None).await];
+    for (index, candidate) in flagged_candidates.iter().enumerate() {
+        let kind = flagged_candidate_kind(candidate, &flagged_path);
+        flagged_snapshots.push(describe_flagged_snapshot(candidate, kind, Some(index)).await);
+    }
+
+    let mut accounts_metadata = build_metadata_section(&storage_path, account_snapshots);
+    let flagged_metadata = build_metadata_section(&flagged_path, flagged_snapshots);
+
+    accounts_metadata.latest_valid_path =
+        select_latest_valid_account_path(&accounts_metadata.snapshots)
+            .or(accounts_metadata.latest_valid_path);
+
+    BackupMetadata {
+        accounts: accounts_metadata,
+        flagged_accounts: flagged_metadata,
+    }
+}
+
+// ============================================================================
+// Tests (ported from test/backup-metadata.test.ts / -builder.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn snap(
+        kind: BackupSnapshotKind,
+        path: &str,
+        valid: bool,
+        mtime_ms: Option<f64>,
+    ) -> BackupSnapshotMetadata {
+        BackupSnapshotMetadata {
+            kind,
+            path: path.to_string(),
+            valid,
+            exists: true,
+            mtime_ms,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn latest_valid_snapshot_prefers_newest_mtime() {
+        let snapshots = vec![
+            snap(BackupSnapshotKind::AccountsPrimary, "p", true, Some(10.0)),
+            snap(BackupSnapshotKind::AccountsBackup, "b", true, Some(30.0)),
+            snap(BackupSnapshotKind::AccountsWal, "w", false, Some(99.0)),
+        ];
+        assert_eq!(latest_valid_snapshot(&snapshots).unwrap().path, "b");
+    }
+
+    #[test]
+    fn latest_valid_snapshot_missing_mtime_counts_as_zero() {
+        let snapshots = vec![
+            snap(BackupSnapshotKind::AccountsPrimary, "p", true, None),
+            snap(BackupSnapshotKind::AccountsBackup, "b", true, Some(1.0)),
+        ];
+        assert_eq!(latest_valid_snapshot(&snapshots).unwrap().path, "b");
+    }
+
+    #[test]
+    fn build_metadata_section_counts() {
+        let snapshots = vec![
+            snap(BackupSnapshotKind::AccountsPrimary, "p", true, Some(5.0)),
+            snap(BackupSnapshotKind::AccountsBackup, "b", false, Some(9.0)),
+        ];
+        let section = build_metadata_section("p", snapshots);
+        assert_eq!(section.snapshot_count, 2);
+        assert_eq!(section.valid_snapshot_count, 1);
+        assert_eq!(section.latest_valid_path.as_deref(), Some("p"));
+    }
+
+    #[test]
+    fn account_selection_prefers_kind_priority_over_mtime() {
+        // A valid discovered backup beats a NEWER plain backup (priority 4 >
+        // 2), which beats WAL, which beats primary.
+        let snapshots = vec![
+            snap(BackupSnapshotKind::AccountsPrimary, "primary", true, Some(100.0)),
+            snap(BackupSnapshotKind::AccountsWal, "wal", true, Some(90.0)),
+            snap(BackupSnapshotKind::AccountsBackup, "bak", true, Some(80.0)),
+            snap(
+                BackupSnapshotKind::AccountsDiscoveredBackup,
+                "disc",
+                true,
+                Some(1.0),
+            ),
+        ];
+        assert_eq!(
+            select_latest_valid_account_path(&snapshots).as_deref(),
+            Some("disc")
+        );
+    }
+
+    #[test]
+    fn account_selection_falls_back_to_wal_then_primary() {
+        let wal_only = vec![
+            snap(BackupSnapshotKind::AccountsPrimary, "primary", true, Some(5.0)),
+            snap(BackupSnapshotKind::AccountsWal, "wal", true, Some(1.0)),
+        ];
+        assert_eq!(
+            select_latest_valid_account_path(&wal_only).as_deref(),
+            Some("wal")
+        );
+        let primary_only = vec![snap(
+            BackupSnapshotKind::AccountsPrimary,
+            "primary",
+            true,
+            Some(5.0),
+        )];
+        assert_eq!(
+            select_latest_valid_account_path(&primary_only).as_deref(),
+            Some("primary")
+        );
+        let none_valid = vec![snap(
+            BackupSnapshotKind::AccountsBackup,
+            "bak",
+            false,
+            Some(5.0),
+        )];
+        assert_eq!(select_latest_valid_account_path(&none_valid), None);
+    }
+
+    #[test]
+    fn account_selection_ties_break_by_mtime_within_priority() {
+        let snapshots = vec![
+            snap(
+                BackupSnapshotKind::AccountsBackupHistory,
+                "old-history",
+                true,
+                Some(10.0),
+            ),
+            snap(
+                BackupSnapshotKind::AccountsBackupHistory,
+                "new-history",
+                true,
+                Some(20.0),
+            ),
+        ];
+        assert_eq!(
+            select_latest_valid_account_path(&snapshots).as_deref(),
+            Some("new-history")
+        );
+    }
+
+    #[test]
+    fn candidate_kind_classification() {
+        let p = "/x/openai-codex-accounts.json";
+        assert_eq!(
+            account_candidate_kind(&format!("{p}.bak"), p),
+            BackupSnapshotKind::AccountsBackup
+        );
+        assert_eq!(
+            account_candidate_kind(&format!("{p}.bak.2"), p),
+            BackupSnapshotKind::AccountsBackupHistory
+        );
+        assert_eq!(
+            account_candidate_kind(&format!("{p}.2024"), p),
+            BackupSnapshotKind::AccountsDiscoveredBackup
+        );
+        assert_eq!(
+            flagged_candidate_kind(&format!("{p}.bak"), p),
+            BackupSnapshotKind::FlaggedBackup
+        );
+    }
+
+    #[test]
+    fn mtime_serializes_without_trailing_zero_for_integral_values() {
+        let snapshot = snap(
+            BackupSnapshotKind::AccountsPrimary,
+            "p",
+            true,
+            Some(1_753_500_000_000.0),
+        );
+        let serialized = serde_json::to_string(&snapshot).unwrap();
+        assert!(serialized.contains("\"mtimeMs\":1753500000000"));
+        assert!(!serialized.contains("1753500000000.0"));
+        let fractional = snap(BackupSnapshotKind::AccountsPrimary, "p", true, Some(1.5));
+        assert!(serde_json::to_string(&fractional).unwrap().contains("\"mtimeMs\":1.5"));
+    }
+}
diff --git a/crates/storage/src/backup_paths.rs b/crates/storage/src/backup_paths.rs
new file mode 100644
index 000000000..54675d39b
--- /dev/null
+++ b/crates/storage/src/backup_paths.rs
@@ -0,0 +1,166 @@
+//! Port of `lib/storage/backup-paths.ts` + `lib/storage/file-paths.ts` —
+//! suffix constants and sibling-path builders for the accounts backup index,
+//! WAL journal, intentional-reset marker, and flagged files.
+//!
+//! Behavior source: spec 02 §3.2–§3.5, §14 (export inventory).
+//!
+//! All builders are pure string suffix appends on the FULL path (the TS code
+//! did `` `${path}${suffix}` `` — the suffix goes after the `.json`
+//! extension, e.g. `openai-codex-accounts.json.bak`). Mirroring the TS
+//! string-path model, inputs are `impl AsRef<Path>` (so `&str`, `&String`,
+//! `&Path` and `&PathBuf` all work) and outputs are `String`.
+
+use std::path::Path;
+
+/// `.bak` — latest rotating backup suffix.
+pub const ACCOUNTS_BACKUP_SUFFIX: &str = ".bak";
+/// `.wal` — write-ahead journal suffix.
+pub const ACCOUNTS_WAL_SUFFIX: &str = ".wal";
+/// `.reset-intent` — intentional-reset marker suffix.
+pub const RESET_MARKER_SUFFIX: &str = ".reset-intent";
+/// Rotation history depth (`.bak`, `.bak.1`, `.bak.2`) — file-paths.ts.
+pub const ACCOUNTS_BACKUP_HISTORY_DEPTH: usize = 3;
+
+/// Append a raw string suffix to a full path (TS template-string concat).
+pub(crate) fn append_suffix(path: impl AsRef<Path>, suffix: &str) -> String {
+    format!("{}{}", path.as_ref().to_string_lossy(), suffix)
+}
+
+/// `getAccountsBackupPath(path)` = `<path>.bak`.
+pub fn get_accounts_backup_path(path: impl AsRef<Path>) -> String {
+    append_suffix(path, ACCOUNTS_BACKUP_SUFFIX)
+}
+
+/// `getAccountsBackupPathAtIndex(path, i)`: `i == 0` ⇒ `<path>.bak`, else
+/// `<path>.bak.<i>` (the TS `index <= 0` branch collapses to `== 0` for an
+/// unsigned index).
+pub fn get_accounts_backup_path_at_index(path: impl AsRef<Path>, index: usize) -> String {
+    if index == 0 {
+        get_accounts_backup_path(path)
+    } else {
+        append_suffix(path, &format!("{ACCOUNTS_BACKUP_SUFFIX}.{index}"))
+    }
+}
+
+/// `getAccountsBackupRecoveryCandidates(path, depth)` — the ordered rotation
+/// candidates `[.bak, .bak.1, …]`.
+pub fn get_accounts_backup_recovery_candidates(
+    path: impl AsRef<Path>,
+    depth: usize,
+) -> Vec<String> {
+    let path = path.as_ref();
+    (0..depth)
+        .map(|i| get_accounts_backup_path_at_index(path, i))
+        .collect()
+}
+
+/// file-paths.ts wrapper: fixed depth [`ACCOUNTS_BACKUP_HISTORY_DEPTH`] (3).
+pub fn get_accounts_backup_recovery_candidates_default(path: impl AsRef<Path>) -> Vec<String> {
+    get_accounts_backup_recovery_candidates(path, ACCOUNTS_BACKUP_HISTORY_DEPTH)
+}
+
+/// `getAccountsWalPath(path)` = `<path>.wal`.
+pub fn get_accounts_wal_path(path: impl AsRef<Path>) -> String {
+    append_suffix(path, ACCOUNTS_WAL_SUFFIX)
+}
+
+/// `getIntentionalResetMarkerPath(path)` = `<path>.reset-intent`. Shared by
+/// the accounts marker AND the flagged marker (each computed on its own file
+/// path — spec 02 §3.4).
+pub fn get_intentional_reset_marker_path(path: impl AsRef<Path>) -> String {
+    append_suffix(path, RESET_MARKER_SUFFIX)
+}
+
+/// `getFlaggedAccountsPath(storagePath, fileName)` =
+/// `dirname(storagePath)/<fileName>` (sibling of the accounts file).
+pub fn get_flagged_accounts_path(storage_path: impl AsRef<Path>, file_name: &str) -> String {
+    build_sibling_storage_path(storage_path, file_name)
+}
+
+/// `getLegacyFlaggedAccountsPath(storagePath, legacyFileName)` — same sibling
+/// builder with the legacy (`openai-codex-blocked-accounts.json`) name.
+pub fn get_legacy_flagged_accounts_path(
+    storage_path: impl AsRef<Path>,
+    legacy_file_name: &str,
+) -> String {
+    build_sibling_storage_path(storage_path, legacy_file_name)
+}
+
+fn build_sibling_storage_path(storage_path: impl AsRef<Path>, file_name: &str) -> String {
+    storage_path
+        .as_ref()
+        .parent()
+        .unwrap_or_else(|| Path::new(""))
+        .join(file_name)
+        .to_string_lossy()
+        .into_owned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn suffix_builders_append_after_the_json_extension() {
+        let path = "/x/openai-codex-accounts.json";
+        assert_eq!(
+            get_accounts_backup_path(path),
+            "/x/openai-codex-accounts.json.bak"
+        );
+        assert_eq!(
+            get_accounts_wal_path(path),
+            "/x/openai-codex-accounts.json.wal"
+        );
+        assert_eq!(
+            get_intentional_reset_marker_path(path),
+            "/x/openai-codex-accounts.json.reset-intent"
+        );
+    }
+
+    #[test]
+    fn backup_index_zero_is_bare_bak_and_positive_indices_are_numbered() {
+        assert_eq!(get_accounts_backup_path_at_index("/x/a.json", 0), "/x/a.json.bak");
+        assert_eq!(get_accounts_backup_path_at_index("/x/a.json", 1), "/x/a.json.bak.1");
+        assert_eq!(get_accounts_backup_path_at_index("/x/a.json", 2), "/x/a.json.bak.2");
+    }
+
+    #[test]
+    fn recovery_candidates_are_ordered_and_default_depth_is_three() {
+        let candidates = get_accounts_backup_recovery_candidates_default("/x/a.json");
+        assert_eq!(
+            candidates,
+            vec![
+                "/x/a.json.bak".to_string(),
+                "/x/a.json.bak.1".to_string(),
+                "/x/a.json.bak.2".to_string(),
+            ]
+        );
+        assert_eq!(get_accounts_backup_recovery_candidates("/x/a.json", 1).len(), 1);
+        assert!(get_accounts_backup_recovery_candidates("/x/a.json", 0).is_empty());
+    }
+
+    #[test]
+    fn flagged_paths_are_siblings_of_the_storage_path() {
+        let storage = std::path::MAIN_SEPARATOR_STR.to_string() + "dir";
+        let storage = format!("{storage}{}sub{}openai-codex-accounts.json",
+            std::path::MAIN_SEPARATOR, std::path::MAIN_SEPARATOR);
+        let flagged = get_flagged_accounts_path(&storage, "openai-codex-flagged-accounts.json");
+        assert!(flagged.ends_with("openai-codex-flagged-accounts.json"));
+        assert!(flagged.contains("sub"));
+        let legacy =
+            get_legacy_flagged_accounts_path(&storage, "openai-codex-blocked-accounts.json");
+        assert!(legacy.ends_with("openai-codex-blocked-accounts.json"));
+    }
+
+    #[test]
+    fn builders_accept_str_string_path_and_pathbuf() {
+        let owned = String::from("/x/a.json");
+        let pathbuf = std::path::PathBuf::from("/x/a.json");
+        assert_eq!(get_accounts_wal_path(&owned), "/x/a.json.wal");
+        assert_eq!(get_accounts_wal_path(&pathbuf), "/x/a.json.wal");
+        assert_eq!(
+            get_accounts_wal_path(std::path::Path::new("/x/a.json")),
+            "/x/a.json.wal"
+        );
+    }
+}
diff --git a/crates/storage/src/backup_restore.rs b/crates/storage/src/backup_restore.rs
new file mode 100644
index 000000000..ff994e8ae
--- /dev/null
+++ b/crates/storage/src/backup_restore.rs
@@ -0,0 +1,225 @@
+//! Port of `lib/storage/backup-restore.ts` + `restore-backup-entry.ts`
+//! wiring from `lib/storage.ts` (spec 02 §12.3 `restoreAccountsFromBackup`).
+//!
+//! Realpath-based containment inside the named-backup root, frozen error
+//! strings, empty-backup rejection, optional persist via the locked
+//! `save_accounts`.
+
+use std::io;
+use std::path::Path;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::code_of;
+use cma_core::schemas::account_storage::AccountStorageV3;
+
+use crate::named_backups::{is_absolute_path, path_relative, realpath_compat};
+
+fn io_to_codex(error: io::Error) -> CodexError {
+    let mapped = CodexError::new(error.to_string());
+    match code_of(&error) {
+        Some(code) => mapped.with_code(code).with_cause(error),
+        None => mapped.with_cause(error),
+    }
+}
+
+fn is_enoent(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::NotFound || code_of(error) == Some("ENOENT")
+}
+
+/// TS `restoreAccountsFromBackupPath` with an explicit backup root and
+/// persist toggle.
+pub async fn restore_accounts_from_backup_path(
+    path: &str,
+    backup_root: &str,
+    persist: bool,
+) -> Result<AccountStorageV3, CodexError> {
+    let resolved_backup_root = match realpath_compat(backup_root) {
+        Ok(resolved) => resolved,
+        Err(error) if is_enoent(&error) => {
+            return Err(CodexError::new(format!(
+                "Backup root does not exist: {backup_root}"
+            )));
+        }
+        Err(error) => return Err(io_to_codex(error)),
+    };
+
+    let resolved_backup_path = match realpath_compat(path) {
+        Ok(resolved) => resolved,
+        Err(error) if is_enoent(&error) => {
+            return Err(CodexError::new(format!(
+                "Backup file no longer exists: {path}"
+            )));
+        }
+        Err(error) => return Err(io_to_codex(error)),
+    };
+
+    let relative_path = path_relative(&resolved_backup_root, &resolved_backup_path);
+    let is_inside_backup_root = !relative_path.is_empty()
+        && !relative_path.starts_with("..")
+        && !is_absolute_path(&relative_path);
+    if !is_inside_backup_root {
+        return Err(CodexError::new(format!(
+            "Backup path must stay inside {resolved_backup_root}: {path}"
+        )));
+    }
+
+    let parsed =
+        match crate::parser::load_accounts_from_path(Path::new(&resolved_backup_path)).await {
+            Ok(parsed) => parsed,
+            // ENOENT during the load ⇒ the "no longer exists" error (TOCTOU).
+            Err(error) if is_enoent(&error) => {
+                return Err(CodexError::new(format!(
+                    "Backup file no longer exists: {path}"
+                )));
+            }
+            // Other read failures (including the propagating JSON
+            // SyntaxError, ErrorKind::InvalidData) surface unchanged.
+            Err(error) => return Err(io_to_codex(error)),
+        };
+
+    let normalized = match parsed.normalized {
+        Some(normalized) if !normalized.accounts.is_empty() => normalized,
+        _ => {
+            return Err(CodexError::new(format!(
+                "Backup does not contain any accounts: {resolved_backup_path}"
+            )));
+        }
+    };
+
+    if persist {
+        crate::save::save_accounts(&normalized).await?;
+    }
+    Ok(normalized)
+}
+
+/// TS `restoreAccountsFromBackup(path, {persist})` (storage.ts export) —
+/// backup root derived from the CURRENT storage path's named-backup root.
+/// `persist` defaults to true (`persist !== false`).
+pub async fn restore_accounts_from_backup(
+    path: &str,
+    persist: Option<bool>,
+) -> Result<AccountStorageV3, CodexError> {
+    let storage_path = std::path::PathBuf::from(crate::facade::get_storage_path())
+        .to_string_lossy()
+        .into_owned();
+    let backup_root = crate::named_backups::get_named_backup_root(&storage_path)?;
+    restore_accounts_from_backup_path(path, &backup_root, persist != Some(false)).await
+}
+
+// ============================================================================
+// Tests (ported from the restore-backup suites; persist:false paths only so
+// no global storage state is touched)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn valid_storage_json() -> String {
+        serde_json::to_string(&json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": 0,
+        }))
+        .unwrap()
+    }
+
+    #[tokio::test]
+    async fn missing_backup_root_uses_frozen_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("backups");
+        let root_str = root.to_string_lossy().into_owned();
+        let error = restore_accounts_from_backup_path("whatever.json", &root_str, false)
+            .await
+            .expect_err("missing root");
+        assert_eq!(
+            error.message(),
+            format!("Backup root does not exist: {root_str}")
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_backup_file_uses_frozen_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("backups");
+        std::fs::create_dir_all(&root).unwrap();
+        let missing = root.join("gone.json");
+        let missing_str = missing.to_string_lossy().into_owned();
+        let error =
+            restore_accounts_from_backup_path(&missing_str, &root.to_string_lossy(), false)
+                .await
+                .expect_err("missing file");
+        assert_eq!(
+            error.message(),
+            format!("Backup file no longer exists: {missing_str}")
+        );
+    }
+
+    #[tokio::test]
+    async fn backup_outside_root_is_rejected() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("backups");
+        std::fs::create_dir_all(&root).unwrap();
+        let outside = dir.path().join("outside.json");
+        std::fs::write(&outside, valid_storage_json()).unwrap();
+        let error = restore_accounts_from_backup_path(
+            &outside.to_string_lossy(),
+            &root.to_string_lossy(),
+            false,
+        )
+        .await
+        .expect_err("outside root");
+        assert!(
+            error.message().starts_with("Backup path must stay inside "),
+            "unexpected message: {}",
+            error.message()
+        );
+    }
+
+    #[tokio::test]
+    async fn empty_backup_is_rejected() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("backups");
+        std::fs::create_dir_all(&root).unwrap();
+        let backup = root.join("empty.json");
+        std::fs::write(
+            &backup,
+            serde_json::to_string(&json!({ "version": 3, "accounts": [], "activeIndex": 0 }))
+                .unwrap(),
+        )
+        .unwrap();
+        let error = restore_accounts_from_backup_path(
+            &backup.to_string_lossy(),
+            &root.to_string_lossy(),
+            false,
+        )
+        .await
+        .expect_err("empty backup");
+        assert!(
+            error
+                .message()
+                .starts_with("Backup does not contain any accounts: "),
+            "unexpected message: {}",
+            error.message()
+        );
+    }
+
+    #[tokio::test]
+    async fn valid_backup_restores_without_persist() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("backups");
+        std::fs::create_dir_all(&root).unwrap();
+        let backup = root.join("daily.json");
+        std::fs::write(&backup, valid_storage_json()).unwrap();
+        let restored = restore_accounts_from_backup_path(
+            &backup.to_string_lossy(),
+            &root.to_string_lossy(),
+            false,
+        )
+        .await
+        .expect("restores");
+        assert_eq!(restored.accounts.len(), 1);
+        assert_eq!(restored.accounts[0].refresh_token, "rt");
+    }
+}
diff --git a/crates/storage/src/backups.rs b/crates/storage/src/backups.rs
new file mode 100644
index 000000000..8c4bd9f6f
--- /dev/null
+++ b/crates/storage/src/backups.rs
@@ -0,0 +1,405 @@
+//! Port of the rotating-backup + discovery privates of `lib/storage.ts`:
+//! `createRotatingAccountsBackup`, `cleanupStaleRotatingBackupArtifacts`,
+//! `isRotatingBackupTempArtifact`,
+//! `getAccountsBackupRecoveryCandidatesWithDiscovery`, plus the shared
+//! copy/rename retry helpers.
+//!
+//! Behavior source: spec 02 §7.3–§7.5, gotchas 14 & 33.
+//!
+//! Exact timing: copy/rename retries are 5 attempts on a `10·2^(n-1)` ms
+//! schedule (`BACKUP_COPY_MAX_ATTEMPTS` / `BACKUP_COPY_BASE_DELAY_MS`);
+//! renames add 0–10 ms jitter; both use the DEFAULT transient-code set
+//! (EBUSY/EPERM/EAGAIN/ENOTEMPTY/EACCES).
+
+use std::fs;
+use std::io;
+use std::path::Path;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, code_of, with_retry};
+use cma_core::logger::create_logger;
+use cma_core::temp_path::temp_file_nonce;
+use serde_json::json;
+
+use crate::backup_paths::{
+    ACCOUNTS_BACKUP_HISTORY_DEPTH, ACCOUNTS_BACKUP_SUFFIX, ACCOUNTS_WAL_SUFFIX,
+    RESET_MARKER_SUFFIX, get_accounts_backup_recovery_candidates,
+};
+use crate::misc::is_cache_like_backup_artifact_name;
+
+const BACKUP_COPY_MAX_ATTEMPTS: u32 = 5;
+const BACKUP_COPY_BASE_DELAY_MS: u64 = 10;
+
+fn backup_backoff() -> Backoff {
+    Backoff::from_fn(|attempt| {
+        BACKUP_COPY_BASE_DELAY_MS.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+    })
+}
+
+/// `copyFileWithRetry(source, destination, {allowMissingSource})`.
+pub(crate) async fn copy_file_with_retry(
+    source_path: &Path,
+    destination_path: &Path,
+    allow_missing_source: bool,
+) -> io::Result<()> {
+    let result = with_retry(
+        || {
+            let source = source_path.to_path_buf();
+            let destination = destination_path.to_path_buf();
+            async move { fs::copy(&source, &destination).map(|_| ()) }
+        },
+        RetryOptions::<io::Error>::new(BACKUP_COPY_MAX_ATTEMPTS, backup_backoff()),
+    )
+    .await;
+    match result {
+        Err(error) if allow_missing_source && code_of(&error) == Some("ENOENT") => Ok(()),
+        other => other,
+    }
+}
+
+/// `renameFileWithRetry(source, destination)` — same schedule + 0–10 ms
+/// jitter.
+pub(crate) async fn rename_file_with_retry(
+    source_path: &Path,
+    destination_path: &Path,
+) -> io::Result<()> {
+    with_retry(
+        || {
+            let source = source_path.to_path_buf();
+            let destination = destination_path.to_path_buf();
+            async move { fs::rename(&source, &destination) }
+        },
+        RetryOptions::<io::Error>::new(BACKUP_COPY_MAX_ATTEMPTS, backup_backoff())
+            .with_jitter(BACKUP_COPY_BASE_DELAY_MS),
+    )
+    .await
+}
+
+/// `createRotatingAccountsBackup(path)` — stage-then-rename rotation of
+/// `.bak` → `.bak.1` → `.bak.2` (spec 02 §7.3). The `latest` copy of the
+/// LIVE file does NOT allow a missing source (throws); slot shifts do.
+/// Staged files are best-effort cleaned in all cases.
+pub async fn create_rotating_accounts_backup(path: impl AsRef<Path>) -> io::Result<()> {
+    let path = path.as_ref();
+    let candidates = get_accounts_backup_recovery_candidates(path, ACCOUNTS_BACKUP_HISTORY_DEPTH);
+    let rotation_nonce = temp_file_nonce();
+    let mut staged_writes: Vec<(String, String)> = Vec::new(); // (target, staged)
+    let build_staged_path =
+        |target_path: &str, label: &str| format!("{target_path}.rotate.{rotation_nonce}.{label}.tmp");
+
+    let result: io::Result<()> = async {
+        for i in (1..candidates.len()).rev() {
+            let previous_path = &candidates[i - 1];
+            let current_path = &candidates[i];
+            if !Path::new(previous_path).exists() {
+                continue;
+            }
+            let staged_path = build_staged_path(current_path, &format!("slot-{i}"));
+            copy_file_with_retry(Path::new(previous_path), Path::new(&staged_path), true).await?;
+            if Path::new(&staged_path).exists() {
+                staged_writes.push((current_path.clone(), staged_path));
+            }
+        }
+
+        let Some(latest_backup_path) = candidates.first() else {
+            return Ok(());
+        };
+        let latest_staged_path = build_staged_path(latest_backup_path, "latest");
+        // Missing live source is NOT allowed here — it throws.
+        copy_file_with_retry(path, Path::new(&latest_staged_path), false).await?;
+        if Path::new(&latest_staged_path).exists() {
+            staged_writes.push((latest_backup_path.clone(), latest_staged_path));
+        }
+
+        for (target_path, staged_path) in &staged_writes {
+            rename_file_with_retry(Path::new(staged_path), Path::new(target_path)).await?;
+        }
+        Ok(())
+    }
+    .await;
+
+    // `finally`: unlink any staged file that still exists (best effort).
+    for (_, staged_path) in &staged_writes {
+        if Path::new(staged_path).exists() {
+            let _ = fs::remove_file(staged_path);
+        }
+    }
+    result
+}
+
+/// `isRotatingBackupTempArtifact(storagePath, candidatePath)` — name starts
+/// with `<path>.bak`, ends `.tmp`, contains `.rotate.`, and the segment
+/// between `.bak` and `.rotate.` is empty or `^\.\d+$`.
+pub(crate) fn is_rotating_backup_temp_artifact(
+    storage_path: impl AsRef<Path>,
+    candidate_path: &str,
+) -> bool {
+    let backup_prefix = format!(
+        "{}{}",
+        storage_path.as_ref().to_string_lossy(),
+        ACCOUNTS_BACKUP_SUFFIX
+    );
+    if !candidate_path.starts_with(&backup_prefix) || !candidate_path.ends_with(".tmp") {
+        return false;
+    }
+    let suffix = &candidate_path[backup_prefix.len()..];
+    let Some(rotate_separator_index) = suffix.find(".rotate.") else {
+        return false;
+    };
+    let backup_index_suffix = &suffix[..rotate_separator_index];
+    if backup_index_suffix.is_empty() {
+        return true;
+    }
+    // `^\.\d+$`
+    let Some(digits) = backup_index_suffix.strip_prefix('.') else {
+        return false;
+    };
+    !digits.is_empty() && digits.chars().all(|c| c.is_ascii_digit())
+}
+
+/// `cleanupStaleRotatingBackupArtifacts(path)` — runs at the START of every
+/// `loadAccountsInternal`; deletes crashed-rotation staging files (gotcha 33:
+/// they carry secrets). Failures are logged as warnings.
+pub async fn cleanup_stale_rotating_backup_artifacts(path: impl AsRef<Path>) {
+    let path = path.as_ref();
+    let log = create_logger("storage");
+    let directory_path = path.parent().unwrap_or_else(|| Path::new(""));
+    let entries = match fs::read_dir(directory_path) {
+        Ok(entries) => entries,
+        Err(error) => {
+            if code_of(&error) != Some("ENOENT") {
+                log.warn(
+                    "Failed to scan for stale rotating backup artifacts",
+                    Some(&json!({
+                        "path": path.to_string_lossy(),
+                        "error": error.to_string(),
+                    })),
+                );
+            }
+            return;
+        }
+    };
+
+    for entry in entries.flatten() {
+        let is_file = entry.file_type().map(|t| t.is_file()).unwrap_or(false);
+        if !is_file {
+            continue;
+        }
+        let entry_path = directory_path
+            .join(entry.file_name())
+            .to_string_lossy()
+            .into_owned();
+        if !is_rotating_backup_temp_artifact(path, &entry_path) {
+            continue;
+        }
+        if let Err(error) = fs::remove_file(&entry_path)
+            && code_of(&error) != Some("ENOENT")
+        {
+            log.warn(
+                "Failed to remove stale rotating backup artifact",
+                Some(&json!({
+                    "path": entry_path,
+                    "error": error.to_string(),
+                })),
+            );
+        }
+    }
+}
+
+/// `getAccountsBackupRecoveryCandidatesWithDiscovery(path)` — the 3 known
+/// rotation paths first, then discovered `basename(path).`-prefixed files
+/// (excluding cache-like, `.reset-intent`, `.tmp`, `.rotate.`, `.wal`, and
+/// already-known paths) sorted case-insensitively (gotcha 14).
+pub async fn get_accounts_backup_recovery_candidates_with_discovery(
+    path: impl AsRef<Path>,
+) -> Vec<String> {
+    let path = path.as_ref();
+    let log = create_logger("storage");
+    let known_candidates =
+        get_accounts_backup_recovery_candidates(path, ACCOUNTS_BACKUP_HISTORY_DEPTH);
+    let candidate_prefix = format!(
+        "{}.",
+        path.file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_default()
+    );
+    let directory_path = path.parent().unwrap_or_else(|| Path::new(""));
+    let mut discovered: Vec<String> = Vec::new();
+
+    match fs::read_dir(directory_path) {
+        Ok(entries) => {
+            for entry in entries.flatten() {
+                let is_file = entry.file_type().map(|t| t.is_file()).unwrap_or(false);
+                if !is_file {
+                    continue;
+                }
+                let name = entry.file_name().to_string_lossy().into_owned();
+                if !name.starts_with(&candidate_prefix) {
+                    continue;
+                }
+                if is_cache_like_backup_artifact_name(&name) {
+                    continue;
+                }
+                if name.ends_with(RESET_MARKER_SUFFIX) {
+                    continue;
+                }
+                if name.ends_with(".tmp") {
+                    continue;
+                }
+                if name.contains(".rotate.") {
+                    continue;
+                }
+                if name.ends_with(ACCOUNTS_WAL_SUFFIX) {
+                    continue;
+                }
+                let candidate_path = directory_path
+                    .join(&name)
+                    .to_string_lossy()
+                    .into_owned();
+                if known_candidates.contains(&candidate_path) {
+                    continue;
+                }
+                if !discovered.contains(&candidate_path) {
+                    discovered.push(candidate_path);
+                }
+            }
+        }
+        Err(error) => {
+            if code_of(&error) != Some("ENOENT") {
+                log.warn(
+                    "Failed to discover account backup candidates",
+                    Some(&json!({
+                        "path": path.to_string_lossy(),
+                        "error": error.to_string(),
+                    })),
+                );
+            }
+        }
+    }
+
+    // `localeCompare(..., { sensitivity: "base" })` — case-insensitive
+    // ordering; stable sort preserves insertion order for case-variant ties.
+    discovered.sort_by_key(|p| p.to_lowercase());
+
+    let mut result = known_candidates;
+    result.extend(discovered);
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rotating_artifact_matcher_accepts_bak_and_indexed_bak_staging_names() {
+        let storage = "/x/a.json";
+        assert!(is_rotating_backup_temp_artifact(
+            storage,
+            "/x/a.json.bak.rotate.123.4.abcd1234.latest.tmp"
+        ));
+        assert!(is_rotating_backup_temp_artifact(
+            storage,
+            "/x/a.json.bak.2.rotate.123.4.abcd1234.slot-2.tmp"
+        ));
+        // No .rotate. segment.
+        assert!(!is_rotating_backup_temp_artifact(storage, "/x/a.json.bak.tmp"));
+        // Non-numeric index segment between .bak and .rotate.
+        assert!(!is_rotating_backup_temp_artifact(
+            storage,
+            "/x/a.json.bak.evil.rotate.1.tmp"
+        ));
+        // Wrong extension.
+        assert!(!is_rotating_backup_temp_artifact(
+            storage,
+            "/x/a.json.bak.rotate.1.json"
+        ));
+        // Different file entirely.
+        assert!(!is_rotating_backup_temp_artifact(
+            storage,
+            "/x/b.json.bak.rotate.1.tmp"
+        ));
+    }
+
+    #[tokio::test]
+    async fn rotation_shifts_history_and_copies_the_live_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let bak = dir.path().join("a.json.bak");
+        let bak1 = dir.path().join("a.json.bak.1");
+        let bak2 = dir.path().join("a.json.bak.2");
+        fs::write(&path, "live-v3").unwrap();
+        fs::write(&bak, "old-v2").unwrap();
+        fs::write(&bak1, "old-v1").unwrap();
+        create_rotating_accounts_backup(&path).await.unwrap();
+        assert_eq!(fs::read_to_string(&bak).unwrap(), "live-v3");
+        assert_eq!(fs::read_to_string(&bak1).unwrap(), "old-v2");
+        assert_eq!(fs::read_to_string(&bak2).unwrap(), "old-v1");
+        // No staging leftovers.
+        let leftovers: Vec<_> = fs::read_dir(dir.path())
+            .unwrap()
+            .filter_map(|e| e.ok())
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|n| n.contains(".rotate."))
+            .collect();
+        assert!(leftovers.is_empty(), "{leftovers:?}");
+    }
+
+    #[tokio::test]
+    async fn rotation_fails_when_the_live_file_is_missing() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let error = create_rotating_accounts_backup(&path).await.unwrap_err();
+        assert_eq!(code_of(&error), Some("ENOENT"));
+    }
+
+    #[tokio::test]
+    async fn stale_artifact_cleanup_removes_only_matching_staging_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let stale = dir.path().join("a.json.bak.rotate.1.2.abcd.latest.tmp");
+        let stale_indexed = dir.path().join("a.json.bak.1.rotate.9.9.beef.slot-1.tmp");
+        let unrelated = dir.path().join("a.json.bak");
+        fs::write(&stale, "x").unwrap();
+        fs::write(&stale_indexed, "x").unwrap();
+        fs::write(&unrelated, "x").unwrap();
+        cleanup_stale_rotating_backup_artifacts(&path).await;
+        assert!(!stale.exists());
+        assert!(!stale_indexed.exists());
+        assert!(unrelated.exists());
+    }
+
+    #[tokio::test]
+    async fn discovery_appends_filtered_candidates_after_the_known_three() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        fs::write(dir.path().join("a.json.bak"), "x").unwrap(); // known
+        fs::write(dir.path().join("a.json.Backup"), "x").unwrap(); // discovered
+        fs::write(dir.path().join("a.json.2024"), "x").unwrap(); // discovered
+        fs::write(dir.path().join("a.json.cache.old"), "x").unwrap(); // cache-like
+        fs::write(dir.path().join("a.json.reset-intent"), "x").unwrap(); // marker
+        fs::write(dir.path().join("a.json.save.tmp"), "x").unwrap(); // tmp
+        fs::write(dir.path().join("a.json.bak.rotate.1.tmp"), "x").unwrap(); // rotate+tmp
+        fs::write(dir.path().join("a.json.wal"), "x").unwrap(); // wal
+        fs::write(dir.path().join("other.json.bak"), "x").unwrap(); // different prefix
+        let candidates = get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+        let to_s = |p: std::path::PathBuf| p.to_string_lossy().into_owned();
+        assert_eq!(
+            candidates,
+            vec![
+                format!("{}.bak", path.to_string_lossy()),
+                format!("{}.bak.1", path.to_string_lossy()),
+                format!("{}.bak.2", path.to_string_lossy()),
+                // discovered, case-insensitive sort: "2024" < "backup"
+                to_s(dir.path().join("a.json.2024")),
+                to_s(dir.path().join("a.json.Backup")),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn discovery_of_a_missing_directory_is_silent_and_returns_known_only() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("nope").join("a.json");
+        let candidates = get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+        assert_eq!(candidates.len(), 3);
+    }
+}
diff --git a/crates/storage/src/clear.rs b/crates/storage/src/clear.rs
new file mode 100644
index 000000000..f54cb1dfc
--- /dev/null
+++ b/crates/storage/src/clear.rs
@@ -0,0 +1,190 @@
+//! Port of `lib/storage/account-clear.ts` (`clearAccountStorageArtifacts`) +
+//! `account-clear-entry.ts` + the `clearAccounts` wiring from
+//! `lib/storage.ts`.
+//!
+//! Behavior source: spec 02 §10, gotcha 3 (AUDIT-M04/E-07):
+//! - The intentional-reset marker (`{"version":1,"createdAt":<ms>}`, compact,
+//!   0600) is written FIRST — a crash mid-clear must look intentional, not
+//!   corrupt.
+//! - Primary and WAL unlinks are REQUIRED (log + throw on failure); backup
+//!   unlinks are best-effort (log only).
+//! - Unlink retry: 5 attempts, `10·2^attempt` ms (0-based ⇒ 10/20/40/80),
+//!   shared FILE_RETRY_CODES; ENOENT counts as success.
+//! - The accounts clear NEVER removes its reset marker — the next successful
+//!   save's marker unlink does.
+
+use std::fs;
+use std::io;
+use std::path::Path;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, code_of, with_retry};
+use cma_core::logger::create_logger;
+use cma_core::utils::now_ms;
+use serde_json::json;
+
+use crate::backup_paths::{get_accounts_wal_path, get_intentional_reset_marker_path};
+use crate::backups::get_accounts_backup_recovery_candidates_with_discovery;
+use crate::facade;
+use crate::save::write_file_with_mode;
+
+/// Unlink with the clear-path retry schedule; ENOENT ⇒ Ok.
+async fn unlink_with_retry(target_path: &Path) -> io::Result<()> {
+    let result = with_retry(
+        || {
+            let target = target_path.to_path_buf();
+            async move {
+                match fs::remove_file(&target) {
+                    Ok(()) => Ok(()),
+                    Err(error) if code_of(&error) == Some("ENOENT") => Ok(()),
+                    Err(error) => Err(error),
+                }
+            }
+        },
+        // TS loop: catch at attempt n (0-based) sleeps 10·2^n; with_retry's
+        // backoff receives the 1-based failed attempt ⇒ 10·2^(n-1).
+        RetryOptions::<io::Error>::new(
+            5,
+            Backoff::from_fn(|attempt| {
+                10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))
+            }),
+        ),
+    )
+    .await;
+    match result {
+        Ok(()) => Ok(()),
+        Err(error) if code_of(&error) == Some("ENOENT") => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+/// `clearAccountStorageArtifacts(params)` — marker-first deletion of
+/// primary/WAL/backups with retry.
+pub async fn clear_account_storage_artifacts(
+    path: impl AsRef<Path>,
+    reset_marker_path: impl AsRef<Path>,
+    wal_path: impl AsRef<Path>,
+    backup_paths: &[String],
+) -> io::Result<()> {
+    let log = create_logger("storage");
+
+    // Marker FIRST (spec 02 §10 step 1).
+    let marker_content = cma_core::json_io::stringify_compact(&json!({
+        "version": 1,
+        "createdAt": now_ms(),
+    }));
+    write_file_with_mode(reset_marker_path.as_ref(), &marker_content, 0o600)?;
+
+    let clear_required = |target: &Path| {
+        let target = target.to_path_buf();
+        let log = create_logger("storage");
+        async move {
+            match unlink_with_retry(&target).await {
+                Ok(()) => Ok(()),
+                Err(error) => {
+                    log.error(
+                        "Failed to clear account storage artifact",
+                        Some(&json!({
+                            "path": target.to_string_lossy(),
+                            "error": error.to_string(),
+                        })),
+                    );
+                    Err(error)
+                }
+            }
+        }
+    };
+
+    clear_required(path.as_ref()).await?;
+    clear_required(wal_path.as_ref()).await?;
+
+    for backup_path in backup_paths {
+        if let Err(error) = unlink_with_retry(Path::new(backup_path)).await {
+            // Non-critical artifacts: log only, keep going.
+            log.error(
+                "Failed to clear account storage artifact",
+                Some(&json!({
+                    "path": backup_path,
+                    "error": error.to_string(),
+                })),
+            );
+        }
+    }
+    // NOTE: the accounts clear never removes its reset marker.
+    Ok(())
+}
+
+/// `clearAccounts()` — lock + artifacts with discovered backup paths.
+pub async fn clear_accounts() -> io::Result<()> {
+    let path = facade::get_storage_path();
+    crate::transactions::with_storage_lock(|| async {
+        let backup_paths = get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+        clear_account_storage_artifacts(
+            &path,
+            &get_intentional_reset_marker_path(&path),
+            &get_accounts_wal_path(&path),
+            &backup_paths,
+        )
+        .await
+    })
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn clear_writes_marker_first_and_removes_artifacts_but_not_marker() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let marker = dir.path().join("a.json.reset-intent");
+        let wal = dir.path().join("a.json.wal");
+        let bak = dir.path().join("a.json.bak");
+        fs::write(&path, "{}").unwrap();
+        fs::write(&wal, "{}").unwrap();
+        fs::write(&bak, "{}").unwrap();
+
+        clear_account_storage_artifacts(
+            &path,
+            &marker,
+            &wal,
+            &[bak.to_string_lossy().into_owned()],
+        )
+        .await
+        .unwrap();
+
+        assert!(!path.exists());
+        assert!(!wal.exists());
+        assert!(!bak.exists());
+        // Marker persists until the next successful save.
+        assert!(marker.exists());
+        let content = fs::read_to_string(&marker).unwrap();
+        // Compact JSON with the exact key order {"version":1,"createdAt":N}.
+        assert!(content.starts_with(r#"{"version":1,"createdAt":"#), "{content}");
+        assert!(content.ends_with('}'));
+        assert!(!content.contains(' '));
+    }
+
+    #[tokio::test]
+    async fn clearing_missing_artifacts_is_a_no_op_success() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let marker = dir.path().join("a.json.reset-intent");
+        let wal = dir.path().join("a.json.wal");
+        clear_account_storage_artifacts(
+            &path,
+            &marker,
+            &wal,
+            &[dir.path().join("a.json.bak").to_string_lossy().into_owned()],
+        )
+        .await
+        .unwrap();
+        assert!(marker.exists());
+    }
+
+    #[tokio::test]
+    async fn unlink_with_retry_treats_enoent_as_success() {
+        let dir = tempfile::tempdir().unwrap();
+        assert!(unlink_with_retry(&dir.path().join("missing.json")).await.is_ok());
+    }
+}
diff --git a/crates/storage/src/facade.rs b/crates/storage/src/facade.rs
new file mode 100644
index 000000000..45a86bd5c
--- /dev/null
+++ b/crates/storage/src/facade.rs
@@ -0,0 +1,257 @@
+//! Port of the glue/state half of `lib/storage.ts` — the facade other crates
+//! import.
+//!
+//! Owns the module state (`storageBackupEnabled` default true,
+//! `lastAccountsSaveTimestamp` default 0), the file-name constants, and the
+//! storage-path configuration (`setStoragePath` / `setStoragePathDirect` /
+//! `getStoragePath` / flagged path getters). The load/save/clear/transaction
+//! entry points live in their own modules and are re-exported here so
+//! `cma_storage::facade` mirrors the TS `lib/storage.ts` export list
+//! (spec 02 §14).
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
+
+use crate::path_state::StoragePathState;
+use crate::paths::{
+    find_project_root, get_config_dir, get_project_config_dir, get_project_global_config_dir,
+    resolve_project_storage_identity_root,
+};
+
+/// `openai-codex-accounts.json`.
+pub const ACCOUNTS_FILE_NAME: &str = "openai-codex-accounts.json";
+/// `openai-codex-flagged-accounts.json`.
+pub const FLAGGED_ACCOUNTS_FILE_NAME: &str = "openai-codex-flagged-accounts.json";
+/// Legacy `openai-codex-blocked-accounts.json` (migrated on load).
+pub const LEGACY_FLAGGED_ACCOUNTS_FILE_NAME: &str = "openai-codex-blocked-accounts.json";
+
+static STORAGE_BACKUP_ENABLED: AtomicBool = AtomicBool::new(true);
+static LAST_ACCOUNTS_SAVE_TIMESTAMP: AtomicI64 = AtomicI64::new(0);
+
+/// `setStorageBackupEnabled(enabled)`.
+pub fn set_storage_backup_enabled(enabled: bool) {
+    STORAGE_BACKUP_ENABLED.store(enabled, Ordering::SeqCst);
+}
+
+/// Module flag read by the save/load pipelines.
+pub(crate) fn storage_backup_enabled() -> bool {
+    STORAGE_BACKUP_ENABLED.load(Ordering::SeqCst)
+}
+
+/// `getLastAccountsSaveTimestamp()`.
+pub fn get_last_accounts_save_timestamp() -> i64 {
+    LAST_ACCOUNTS_SAVE_TIMESTAMP.load(Ordering::SeqCst)
+}
+
+pub(crate) fn set_last_accounts_save_timestamp(timestamp_ms: i64) {
+    LAST_ACCOUNTS_SAVE_TIMESTAMP.store(timestamp_ms, Ordering::SeqCst);
+}
+
+/// `setStoragePath(projectPath | null)` — spec 02 §2.8. `None` (or a path
+/// with no detectable project root) resets to global storage mode; otherwise
+/// the state points at the identity-root-scoped per-project file with both
+/// legacy candidates recorded for migration.
+pub fn set_storage_path(project_path: Option<&Path>) {
+    let Some(project_path) = project_path else {
+        set_storage_path_state(StoragePathState::empty());
+        return;
+    };
+
+    let Some(project_root) = find_project_root(project_path) else {
+        set_storage_path_state(StoragePathState::empty());
+        return;
+    };
+
+    let identity_root = resolve_project_storage_identity_root(&project_root);
+    let current_storage_path =
+        get_project_global_config_dir(&identity_root).join(ACCOUNTS_FILE_NAME);
+    let current_legacy_project_storage_path =
+        get_project_config_dir(&project_root).join(ACCOUNTS_FILE_NAME);
+    let previous_worktree_scoped_path =
+        get_project_global_config_dir(&project_root).join(ACCOUNTS_FILE_NAME);
+    let current_legacy_worktree_storage_path =
+        if previous_worktree_scoped_path != current_storage_path {
+            Some(previous_worktree_scoped_path)
+        } else {
+            None
+        };
+
+    set_storage_path_state(StoragePathState {
+        current_storage_path: Some(current_storage_path.to_string_lossy().into_owned()),
+        current_legacy_project_storage_path: Some(
+            current_legacy_project_storage_path
+                .to_string_lossy()
+                .into_owned(),
+        ),
+        current_legacy_worktree_storage_path: current_legacy_worktree_storage_path
+            .map(|p| p.to_string_lossy().into_owned()),
+        current_project_root: Some(project_root.to_string_lossy().into_owned()),
+    });
+}
+
+/// `setStoragePathDirect(path | null)` — sets `currentStoragePath` only, all
+/// other fields null (tests/tools).
+pub fn set_storage_path_direct(path: Option<&Path>) {
+    set_storage_path_state(StoragePathState {
+        current_storage_path: path.map(|p| p.to_string_lossy().into_owned()),
+        ..StoragePathState::empty()
+    });
+}
+
+/// `getStoragePath()` — the scoped path when set, else
+/// `<configDir>/openai-codex-accounts.json`. (String path — the TS module
+/// worked in path strings; sibling modules build suffix paths off it.)
+pub fn get_storage_path() -> String {
+    let state = crate::path_state::get_storage_path_state();
+    if let Some(current) = state.current_storage_path {
+        return current;
+    }
+    get_config_dir()
+        .join(ACCOUNTS_FILE_NAME)
+        .to_string_lossy()
+        .into_owned()
+}
+
+/// `getFlaggedAccountsPath()` = sibling
+/// `openai-codex-flagged-accounts.json` of the current storage path.
+pub fn get_flagged_accounts_path() -> String {
+    crate::backup_paths::get_flagged_accounts_path(get_storage_path(), FLAGGED_ACCOUNTS_FILE_NAME)
+}
+
+/// The legacy flagged path (`openai-codex-blocked-accounts.json`); private in
+/// TS but needed by the flagged load ladder.
+pub fn get_legacy_flagged_accounts_path() -> String {
+    crate::backup_paths::get_legacy_flagged_accounts_path(
+        get_storage_path(),
+        LEGACY_FLAGGED_ACCOUNTS_FILE_NAME,
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Facade re-exports (spec 02 §14 export inventory — items owned by this
+// agent's modules; sibling-module items are re-exported from their own
+// modules and finalized at crate integration)
+// ---------------------------------------------------------------------------
+
+pub use crate::backup_paths::{
+    ACCOUNTS_BACKUP_SUFFIX, ACCOUNTS_WAL_SUFFIX, RESET_MARKER_SUFFIX, get_accounts_backup_path,
+    get_accounts_backup_path_at_index, get_accounts_backup_recovery_candidates,
+    get_accounts_backup_recovery_candidates_default, get_accounts_wal_path,
+    get_intentional_reset_marker_path,
+};
+pub use crate::clear::clear_accounts;
+pub use crate::load::{
+    LoadedAccountStorage, PersistMigration, PinAndGen, RestoreMetadata, load_accounts,
+    load_accounts_for_export, load_accounts_from_journal, load_accounts_internal,
+    load_accounts_unlocked, read_affinity_generation_from_disk, read_pin_and_gen_from_disk,
+};
+pub use crate::misc::{
+    clone_account_storage_for_persistence, compute_sha256, format_storage_error_hint,
+    format_storage_error_hint_for_code, to_storage_error,
+};
+pub use crate::normalize::normalize_account_storage;
+pub use crate::parser::{ParsedStorage, load_accounts_from_path, parse_and_normalize_storage};
+pub use crate::path_state::{
+    get_storage_path_state, run_with_storage_path_state, run_with_storage_path_state_sync,
+    set_storage_path_state,
+};
+pub use crate::paths::{
+    PathError, find_project_root as find_project_root_export, get_config_dir as config_dir,
+    get_project_storage_key, is_project_directory, resolve_path,
+};
+pub use crate::save::{save_accounts, save_accounts_unlocked};
+pub use crate::save_retry::{
+    is_retryable_storage_write_code, is_retryable_storage_write_error, save_accounts_with_retry,
+    save_accounts_with_retry_via,
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn backup_flag_and_save_timestamp_round_trip() {
+        assert!(storage_backup_enabled());
+        set_storage_backup_enabled(false);
+        assert!(!storage_backup_enabled());
+        set_storage_backup_enabled(true);
+
+        assert_eq!(get_last_accounts_save_timestamp(), 0);
+        set_last_accounts_save_timestamp(42);
+        assert_eq!(get_last_accounts_save_timestamp(), 42);
+        set_last_accounts_save_timestamp(0);
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn direct_path_overrides_and_null_resets() {
+        let dir = tempfile::tempdir().unwrap();
+        let direct = dir.path().join("custom-accounts.json");
+        set_storage_path_direct(Some(&direct));
+        assert_eq!(get_storage_path(), direct.to_string_lossy());
+        assert_eq!(
+            get_flagged_accounts_path(),
+            dir.path()
+                .join(FLAGGED_ACCOUNTS_FILE_NAME)
+                .to_string_lossy()
+        );
+        assert_eq!(
+            get_legacy_flagged_accounts_path(),
+            dir.path()
+                .join(LEGACY_FLAGGED_ACCOUNTS_FILE_NAME)
+                .to_string_lossy()
+        );
+        set_storage_path_direct(None);
+        assert!(
+            get_storage_path().ends_with(ACCOUNTS_FILE_NAME),
+            "global mode falls back to <configDir>/{ACCOUNTS_FILE_NAME}"
+        );
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn set_storage_path_without_project_root_resets_state() {
+        let dir = tempfile::tempdir().unwrap();
+        let plain = dir.path().join("plain");
+        // NOTE (known clone-state trap): an ANCESTOR of the temp dir may
+        // carry a project marker (e.g. `~/.codex` on a dev machine), in which
+        // case findProjectRoot legitimately resolves — assert the branch that
+        // actually applies on this machine rather than assuming a marker-free
+        // ancestry.
+        set_storage_path(Some(&plain));
+        let state = get_storage_path_state();
+        match find_project_root(&plain) {
+            None => assert_eq!(state, crate::path_state::StoragePathState::empty()),
+            Some(_) => assert!(state.current_storage_path.is_some()),
+        }
+        // `None` always resets to global storage mode.
+        set_storage_path(None);
+        assert_eq!(
+            get_storage_path_state(),
+            crate::path_state::StoragePathState::empty()
+        );
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn set_storage_path_scopes_to_the_project_key_and_records_legacy_paths() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("myproj");
+        std::fs::create_dir_all(project.join(".git")).unwrap();
+        set_storage_path(Some(&project));
+        let state = get_storage_path_state();
+        let current = state.current_storage_path.expect("scoped path set");
+        assert!(current.ends_with(ACCOUNTS_FILE_NAME));
+        assert!(current.contains("projects"));
+        let legacy = state
+            .current_legacy_project_storage_path
+            .expect("legacy project path set");
+        assert!(legacy.contains(".codex"));
+        // Same root as identity root ⇒ no separate worktree legacy path.
+        assert_eq!(state.current_legacy_worktree_storage_path, None);
+        assert!(state.current_project_root.is_some());
+        set_storage_path(None);
+    }
+}
diff --git a/crates/storage/src/fixture_guards.rs b/crates/storage/src/fixture_guards.rs
new file mode 100644
index 000000000..fb40b9c1e
--- /dev/null
+++ b/crates/storage/src/fixture_guards.rs
@@ -0,0 +1,168 @@
+//! Port of `lib/storage/fixture-guards.ts` — synthetic test-fixture detection
+//! guarding against fixture data clobbering real accounts (spec 02 §8.4,
+//! gotcha 13).
+//!
+//! The TS regexes are hand-rolled here (the storage crate has no `regex`
+//! dependency); each helper documents the exact pattern it reproduces.
+
+use crate::public_types::{AccountMetadataV3, AccountStorageV3};
+
+/// `^account\d+@example\.com$` on the trimmed, lowercased email.
+fn is_synthetic_email(email: &str) -> bool {
+    let Some(rest) = email.strip_prefix("account") else {
+        return false;
+    };
+    let Some(digits) = rest.strip_suffix("@example.com") else {
+        return false;
+    };
+    !digits.is_empty() && digits.chars().all(|c| c.is_ascii_digit())
+}
+
+/// `^fake_refresh_token_\d+(_for_testing_only)?$`.
+fn matches_fake_refresh_token_pattern(token: &str) -> bool {
+    let Some(rest) = token.strip_prefix("fake_refresh_token_") else {
+        return false;
+    };
+    let digits = rest.strip_suffix("_for_testing_only").unwrap_or(rest);
+    !digits.is_empty() && digits.chars().all(|c| c.is_ascii_digit())
+}
+
+/// `^acc(_|-)?\d+$`.
+fn is_synthetic_account_id(account_id: &str) -> bool {
+    let Some(rest) = account_id.strip_prefix("acc") else {
+        return false;
+    };
+    let digits = rest
+        .strip_prefix('_')
+        .or_else(|| rest.strip_prefix('-'))
+        .unwrap_or(rest);
+    !digits.is_empty() && digits.chars().all(|c| c.is_ascii_digit())
+}
+
+/// `looksLikeSyntheticFixtureAccount(account)`:
+/// - email (trimmed/lowercased) matches `^account\d+@example\.com$`, AND
+/// - refreshToken (trimmed/lowercased) starts with `fake_refresh` or matches
+///   `^fake_refresh_token_\d+(_for_testing_only)?$`, AND
+/// - accountId is empty or matches `^acc(_|-)?\d+$`.
+pub fn looks_like_synthetic_fixture_account(account: &AccountMetadataV3) -> bool {
+    let email = account
+        .email
+        .as_deref()
+        .unwrap_or("")
+        .trim()
+        .to_lowercase();
+    let refresh_token = account.refresh_token.trim().to_lowercase();
+    let account_id = account
+        .account_id
+        .as_deref()
+        .unwrap_or("")
+        .trim()
+        .to_lowercase();
+
+    if !is_synthetic_email(&email) {
+        return false;
+    }
+    let has_synthetic_refresh_token = refresh_token.starts_with("fake_refresh")
+        || matches_fake_refresh_token_pattern(&refresh_token);
+    if !has_synthetic_refresh_token {
+        return false;
+    }
+    if account_id.is_empty() {
+        return true;
+    }
+    is_synthetic_account_id(&account_id)
+}
+
+/// `looksLikeSyntheticFixtureStorage(storage)`: non-null, at least one
+/// account, EVERY account synthetic.
+pub fn looks_like_synthetic_fixture_storage(storage: Option<&AccountStorageV3>) -> bool {
+    let Some(storage) = storage else {
+        return false;
+    };
+    if storage.accounts.is_empty() {
+        return false;
+    }
+    storage
+        .accounts
+        .iter()
+        .all(looks_like_synthetic_fixture_account)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn account(email: &str, refresh_token: &str, account_id: Option<&str>) -> AccountMetadataV3 {
+        let mut account = AccountMetadataV3::new(refresh_token, 1, 2);
+        account.email = Some(email.to_string());
+        account.account_id = account_id.map(str::to_string);
+        account
+    }
+
+    #[test]
+    fn detects_canonical_fixture_accounts() {
+        assert!(looks_like_synthetic_fixture_account(&account(
+            "account1@example.com",
+            "fake_refresh_token_1",
+            None
+        )));
+        assert!(looks_like_synthetic_fixture_account(&account(
+            "account42@example.com",
+            "fake_refresh_token_42_for_testing_only",
+            Some("acc_42")
+        )));
+        assert!(looks_like_synthetic_fixture_account(&account(
+            "ACCOUNT2@EXAMPLE.COM ",
+            " FAKE_REFRESH_anything",
+            Some("acc-7")
+        )));
+        assert!(looks_like_synthetic_fixture_account(&account(
+            "account3@example.com",
+            "fake_refresh",
+            Some("acc3")
+        )));
+    }
+
+    #[test]
+    fn rejects_real_looking_accounts() {
+        // Real email domain.
+        assert!(!looks_like_synthetic_fixture_account(&account(
+            "user@gmail.com",
+            "fake_refresh_token_1",
+            None
+        )));
+        // Real refresh token.
+        assert!(!looks_like_synthetic_fixture_account(&account(
+            "account1@example.com",
+            "rt_real_token",
+            None
+        )));
+        // Real accountId shape.
+        assert!(!looks_like_synthetic_fixture_account(&account(
+            "account1@example.com",
+            "fake_refresh_token_1",
+            Some("acct-user-one")
+        )));
+        // Email without digits.
+        assert!(!looks_like_synthetic_fixture_account(&account(
+            "account@example.com",
+            "fake_refresh_token_1",
+            None
+        )));
+    }
+
+    #[test]
+    fn storage_is_synthetic_only_when_every_account_is() {
+        assert!(!looks_like_synthetic_fixture_storage(None));
+        let mut storage = AccountStorageV3::empty();
+        assert!(!looks_like_synthetic_fixture_storage(Some(&storage)));
+        storage
+            .accounts
+            .push(account("account1@example.com", "fake_refresh_token_1", None));
+        assert!(looks_like_synthetic_fixture_storage(Some(&storage)));
+        storage
+            .accounts
+            .push(account("real.user@gmail.com", "rt_real", Some("acct-x")));
+        assert!(!looks_like_synthetic_fixture_storage(Some(&storage)));
+    }
+}
diff --git a/crates/storage/src/flagged.rs b/crates/storage/src/flagged.rs
new file mode 100644
index 000000000..0b5cfbb2e
--- /dev/null
+++ b/crates/storage/src/flagged.rs
@@ -0,0 +1,984 @@
+//! Port of `lib/storage/flagged-storage.ts`, `flagged-storage-file.ts`,
+//! `flagged-storage-io.ts` and the flagged wiring/entries from
+//! `lib/storage.ts` (spec 02 §3.5, §9).
+//!
+//! Key contracts:
+//! - Every write goes through [`normalize_flagged_storage`]; the persisted
+//!   field set is the normalizer's whitelist in EXACT insertion order
+//!   (`refreshToken, addedAt, lastUsed, accountId, accountIdSource,
+//!   accountLabel, email, accessToken, expiresAt, enabled, lastSwitchReason,
+//!   rateLimitResetTimes, coolingDownUntil, cooldownReason, workspaces,
+//!   currentWorkspaceIndex, flaggedAt, flaggedReason, lastError`) — NOT the
+//!   schema declaration order (golden `flagged-v1.json`).
+//! - Dedupe by trimmed `refreshToken`, **last occurrence wins** but the FIRST
+//!   occurrence's position is kept (JS `Map.set` semantics).
+//! - Load ladder: reset marker → primary (validity-checked) → `.bak`/`.bak.1`
+//!   /`.bak.2` recovery (persisted via the UNLOCKED save when the storage
+//!   lock is already held — deadlock avoidance) → legacy
+//!   `openai-codex-blocked-accounts.json` migration.
+//! - Save: single `.bak` snapshot, atomic temp+rename, marker unlink;
+//!   errors are RAW (not `StorageError`) — code preserved on the
+//!   [`CodexError`].
+//! - Clear: `"reset"` marker FIRST; marker removed only when every deletion
+//!   succeeded.
+
+use std::io;
+use std::path::Path;
+
+use serde_json::{Map, Value, json};
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{Backoff, FILE_RETRY_CODES, RetryOptions, code_of, with_retry};
+use cma_core::logger::create_logger;
+use cma_core::schemas::account_storage::{
+    AccountIdSource, CooldownReason, RateLimitStateV3, SwitchReason, Workspace,
+};
+use cma_core::schemas::flagged::{FlaggedAccountMetadataV1, FlaggedAccountStorageV1};
+use cma_core::schemas::parse::number_to_i64_lossy;
+use cma_core::temp_path::temp_path_for_str;
+use cma_core::utils::{is_record, now_ms};
+
+const FLAGGED_ACCOUNTS_FILE_NAME: &str = "openai-codex-flagged-accounts.json";
+const LEGACY_FLAGGED_ACCOUNTS_FILE_NAME: &str = "openai-codex-blocked-accounts.json";
+
+/// TS `getFlaggedAccountsPath()` — sibling of the accounts file.
+pub fn get_flagged_accounts_path() -> String {
+    crate::backup_paths::get_flagged_accounts_path(
+        crate::facade::get_storage_path(),
+        FLAGGED_ACCOUNTS_FILE_NAME,
+    )
+}
+
+fn get_legacy_flagged_accounts_path() -> String {
+    crate::backup_paths::get_legacy_flagged_accounts_path(
+        crate::facade::get_storage_path(),
+        LEGACY_FLAGGED_ACCOUNTS_FILE_NAME,
+    )
+}
+
+fn io_to_codex(error: io::Error) -> CodexError {
+    let mapped = CodexError::new(error.to_string());
+    match code_of(&error) {
+        Some(code) => mapped.with_code(code).with_cause(error),
+        None => mapped.with_cause(error),
+    }
+}
+
+// ============================================================================
+// normalizeFlaggedStorage (flagged-storage.ts)
+// ============================================================================
+
+fn value_as_number(value: Option<&Value>) -> Option<i64> {
+    match value {
+        Some(Value::Number(n)) => Some(number_to_i64_lossy(n)),
+        _ => None,
+    }
+}
+
+fn value_as_string(value: Option<&Value>) -> Option<String> {
+    match value {
+        Some(Value::String(s)) => Some(s.clone()),
+        _ => None,
+    }
+}
+
+/// TS `normalizeFlaggedStorage(data, {isRecord, now})` with an injectable
+/// clock (called once per account whose `flaggedAt` is missing).
+pub fn normalize_flagged_storage_with(
+    data: &Value,
+    now: &mut dyn FnMut() -> i64,
+) -> FlaggedAccountStorageV1 {
+    let is_version_1 = data
+        .get("version")
+        .and_then(Value::as_f64)
+        .is_some_and(|version| version == 1.0);
+    let accounts = data.get("accounts").and_then(Value::as_array);
+    let (true, Some(raw_accounts)) = (is_record(data) && is_version_1, accounts) else {
+        return FlaggedAccountStorageV1::empty();
+    };
+
+    // Keyed by refreshToken; last occurrence wins but the FIRST occurrence's
+    // position is preserved (JS `Map.set`).
+    let mut by_refresh_token: Vec<(String, FlaggedAccountMetadataV1)> = Vec::new();
+    for raw_account in raw_accounts {
+        if !is_record(raw_account) {
+            continue;
+        }
+        let refresh_token = match raw_account.get("refreshToken") {
+            Some(Value::String(s)) => s.trim().to_string(),
+            _ => String::new(),
+        };
+        if refresh_token.is_empty() {
+            continue;
+        }
+
+        let flagged_at = value_as_number(raw_account.get("flaggedAt")).unwrap_or_else(&mut *now);
+
+        let rate_limit_reset_times: Option<RateLimitStateV3> = match raw_account
+            .get("rateLimitResetTimes")
+        {
+            Some(map_value) if is_record(map_value) => {
+                let mut normalized = RateLimitStateV3::new();
+                if let Some(object) = map_value.as_object() {
+                    for (key, value) in object {
+                        if let Value::Number(n) = value {
+                            normalized.insert(key.clone(), number_to_i64_lossy(n));
+                        }
+                    }
+                }
+                if normalized.is_empty() {
+                    None
+                } else {
+                    Some(normalized)
+                }
+            }
+            _ => None,
+        };
+
+        let account_id_source = raw_account
+            .get("accountIdSource")
+            .and_then(Value::as_str)
+            .and_then(AccountIdSource::parse);
+        let last_switch_reason = raw_account
+            .get("lastSwitchReason")
+            .and_then(Value::as_str)
+            .and_then(SwitchReason::parse);
+        let cooldown_reason = raw_account
+            .get("cooldownReason")
+            .and_then(Value::as_str)
+            .and_then(CooldownReason::parse);
+
+        // TS keeps any array verbatim (contents NOT validated); the typed
+        // Rust struct requires parseable workspace entries — a malformed
+        // array is dropped instead of passed through (recorded deviation).
+        let workspaces: Option<Vec<Workspace>> = match raw_account.get("workspaces") {
+            Some(Value::Array(_)) => {
+                serde_json::from_value(raw_account.get("workspaces").unwrap().clone()).ok()
+            }
+            _ => None,
+        };
+
+        let normalized = FlaggedAccountMetadataV1 {
+            account_id: value_as_string(raw_account.get("accountId")),
+            account_id_source,
+            account_label: value_as_string(raw_account.get("accountLabel")),
+            email: value_as_string(raw_account.get("email")),
+            refresh_token: refresh_token.clone(),
+            access_token: value_as_string(raw_account.get("accessToken")),
+            expires_at: value_as_number(raw_account.get("expiresAt")),
+            enabled: match raw_account.get("enabled") {
+                Some(Value::Bool(b)) => Some(*b),
+                _ => None,
+            },
+            added_at: value_as_number(raw_account.get("addedAt")).unwrap_or(flagged_at),
+            last_used: value_as_number(raw_account.get("lastUsed")).unwrap_or(flagged_at),
+            last_switch_reason,
+            rate_limit_reset_times,
+            cooling_down_until: value_as_number(raw_account.get("coolingDownUntil")),
+            cooldown_reason,
+            workspaces,
+            current_workspace_index: value_as_number(raw_account.get("currentWorkspaceIndex")),
+            flagged_at,
+            flagged_reason: value_as_string(raw_account.get("flaggedReason")),
+            last_error: value_as_string(raw_account.get("lastError")),
+            extra: Map::new(),
+        };
+        match by_refresh_token
+            .iter_mut()
+            .find(|(key, _)| *key == refresh_token)
+        {
+            Some(entry) => entry.1 = normalized,
+            None => by_refresh_token.push((refresh_token, normalized)),
+        }
+    }
+
+    FlaggedAccountStorageV1 {
+        version: Default::default(),
+        accounts: by_refresh_token
+            .into_iter()
+            .map(|(_, account)| account)
+            .collect(),
+    }
+}
+
+/// [`normalize_flagged_storage_with`] using the wall clock.
+pub fn normalize_flagged_storage(data: &Value) -> FlaggedAccountStorageV1 {
+    normalize_flagged_storage_with(data, &mut now_ms)
+}
+
+// ============================================================================
+// Byte-compatible persist serialization (whitelist insertion order, §3.5)
+// ============================================================================
+
+fn push_opt_string(object: &mut Map<String, Value>, key: &str, value: Option<&String>) {
+    if let Some(value) = value {
+        object.insert(key.to_string(), Value::String(value.clone()));
+    }
+}
+
+fn push_opt_number(object: &mut Map<String, Value>, key: &str, value: Option<i64>) {
+    if let Some(value) = value {
+        object.insert(key.to_string(), Value::from(value));
+    }
+}
+
+/// Serialize one normalized flagged account in the normalizer's insertion
+/// order (spec 02 §3.5; golden `flagged-v1.json`).
+fn flagged_account_to_persist_value(account: &FlaggedAccountMetadataV1) -> Value {
+    let mut object = Map::new();
+    object.insert(
+        "refreshToken".to_string(),
+        Value::String(account.refresh_token.clone()),
+    );
+    object.insert("addedAt".to_string(), Value::from(account.added_at));
+    object.insert("lastUsed".to_string(), Value::from(account.last_used));
+    push_opt_string(&mut object, "accountId", account.account_id.as_ref());
+    if let Some(source) = account.account_id_source {
+        object.insert(
+            "accountIdSource".to_string(),
+            Value::String(source.as_str().to_string()),
+        );
+    }
+    push_opt_string(&mut object, "accountLabel", account.account_label.as_ref());
+    push_opt_string(&mut object, "email", account.email.as_ref());
+    push_opt_string(&mut object, "accessToken", account.access_token.as_ref());
+    push_opt_number(&mut object, "expiresAt", account.expires_at);
+    if let Some(enabled) = account.enabled {
+        object.insert("enabled".to_string(), Value::Bool(enabled));
+    }
+    if let Some(reason) = account.last_switch_reason {
+        object.insert(
+            "lastSwitchReason".to_string(),
+            Value::String(reason.as_str().to_string()),
+        );
+    }
+    if let Some(resets) = &account.rate_limit_reset_times {
+        let mut map = Map::new();
+        for (key, value) in resets.iter() {
+            map.insert(key.to_string(), Value::from(value));
+        }
+        object.insert("rateLimitResetTimes".to_string(), Value::Object(map));
+    }
+    push_opt_number(&mut object, "coolingDownUntil", account.cooling_down_until);
+    if let Some(reason) = account.cooldown_reason {
+        object.insert(
+            "cooldownReason".to_string(),
+            Value::String(reason.as_str().to_string()),
+        );
+    }
+    if let Some(workspaces) = &account.workspaces {
+        object.insert(
+            "workspaces".to_string(),
+            serde_json::to_value(workspaces).unwrap_or(Value::Array(Vec::new())),
+        );
+    }
+    push_opt_number(
+        &mut object,
+        "currentWorkspaceIndex",
+        account.current_workspace_index,
+    );
+    object.insert("flaggedAt".to_string(), Value::from(account.flagged_at));
+    push_opt_string(&mut object, "flaggedReason", account.flagged_reason.as_ref());
+    push_opt_string(&mut object, "lastError", account.last_error.as_ref());
+    Value::Object(object)
+}
+
+/// Serialize normalized flagged storage for persistence (byte-compatible
+/// with `JSON.stringify(normalizeFlaggedStorage(storage), null, 2)`).
+fn flagged_storage_to_persist_value(storage: &FlaggedAccountStorageV1) -> Value {
+    let mut object = Map::new();
+    object.insert("version".to_string(), Value::from(1));
+    object.insert(
+        "accounts".to_string(),
+        Value::Array(
+            storage
+                .accounts
+                .iter()
+                .map(flagged_account_to_persist_value)
+                .collect(),
+        ),
+    );
+    Value::Object(object)
+}
+
+// ============================================================================
+// File primitives (flagged-storage-file.ts)
+// ============================================================================
+
+/// TS `readFileWithRetry` — 4 total attempts, retry {EBUSY, EPERM, EAGAIN}
+/// (Windows AV/indexer briefly locks recently-written files — AUDIT-M05 /
+/// E-08), delays 10·2^(n-1) ms.
+pub async fn read_file_with_retry(path: &str) -> io::Result<String> {
+    let path = path.to_string();
+    with_retry(
+        || tokio::fs::read_to_string(&path),
+        RetryOptions::new(4, Backoff::from_fn(|n| 10 * 2u64.pow(n - 1)))
+            .with_codes(&["EBUSY", "EPERM", "EAGAIN"]),
+    )
+    .await
+}
+
+fn json_syntax_error(error: serde_json::Error) -> io::Error {
+    io::Error::new(io::ErrorKind::InvalidData, error)
+}
+
+/// Parse flagged storage content. Zod-first in TS; behaviorally the Zod-valid
+/// and raw-JSON paths both feed the same normalizer, so a single raw parse is
+/// equivalent. JSON syntax errors propagate (callers fall back to backups).
+fn parse_flagged_storage_content(content: &str) -> io::Result<Value> {
+    serde_json::from_str::<Value>(content).map_err(json_syntax_error)
+}
+
+/// TS `loadFlaggedAccountsFromFile` — read with retry, parse, normalize.
+pub async fn load_flagged_accounts_from_file(path: &str) -> io::Result<FlaggedAccountStorageV1> {
+    let content = read_file_with_retry(path).await?;
+    let data = parse_flagged_storage_content(&content)?;
+    Ok(normalize_flagged_storage(&data))
+}
+
+/// TS `isValidFlaggedStorageCandidate` — raw data must own `version` and
+/// `accounts`, `version === 1`, accounts an array, and (raw accounts empty OR
+/// normalized accounts non-empty). A file of 100% invalid accounts is
+/// treated as corrupt, not empty (gotcha 18).
+fn is_valid_flagged_storage_candidate(data: &Value, storage: &FlaggedAccountStorageV1) -> bool {
+    let Some(object) = data.as_object() else {
+        return false;
+    };
+    if !object.contains_key("version") || !object.contains_key("accounts") {
+        return false;
+    }
+    let version_is_1 = object
+        .get("version")
+        .and_then(Value::as_f64)
+        .is_some_and(|version| version == 1.0);
+    let Some(accounts) = object.get("accounts").and_then(Value::as_array) else {
+        return false;
+    };
+    if !version_is_1 {
+        return false;
+    }
+    accounts.is_empty() || !storage.accounts.is_empty()
+}
+
+fn get_flagged_backup_paths(path: &str) -> Vec<String> {
+    vec![
+        format!("{path}.bak"),
+        format!("{path}.bak.1"),
+        format!("{path}.bak.2"),
+    ]
+}
+
+async fn unlink_with_retry(candidate_path: &str) -> io::Result<()> {
+    let candidate = candidate_path.to_string();
+    let result = with_retry(
+        || tokio::fs::remove_file(&candidate),
+        RetryOptions::new(5, Backoff::from_fn(|n| 10 * 2u64.pow(n - 1)))
+            .with_codes(FILE_RETRY_CODES),
+    )
+    .await;
+    match result {
+        Ok(()) => Ok(()),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+async fn copy_file_with_retry(
+    source_path: &str,
+    destination_path: &str,
+    allow_missing_source: bool,
+) -> io::Result<()> {
+    let source = source_path.to_string();
+    let destination = destination_path.to_string();
+    let result = with_retry(
+        || async {
+            tokio::fs::copy(&source, &destination).await?;
+            Ok::<(), io::Error>(())
+        },
+        RetryOptions::new(5, Backoff::from_fn(|n| 10 * 2u64.pow(n - 1))),
+    )
+    .await;
+    match result {
+        Ok(()) => Ok(()),
+        Err(error) if allow_missing_source && error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+async fn rename_file_with_retry(source_path: &str, destination_path: &str) -> io::Result<()> {
+    let source = source_path.to_string();
+    let destination = destination_path.to_string();
+    with_retry(
+        || tokio::fs::rename(&source, &destination),
+        RetryOptions::new(5, Backoff::from_fn(|n| 10 * 2u64.pow(n - 1))).with_jitter(10),
+    )
+    .await
+}
+
+/// Node `fs.writeFile(..., { mode: 0o600 })` parity: mode applied atomically
+/// at open(2) on unix so the flagged temp file (refresh-token material) never
+/// exists with broader permissions — no write-then-chmod window.
+async fn write_file_mode_600(path: &str, content: &str) -> io::Result<()> {
+    let mut options = tokio::fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    options.mode(0o600);
+    let mut file = options.open(path).await?;
+    use tokio::io::AsyncWriteExt;
+    file.write_all(content.as_bytes()).await?;
+    file.flush().await?;
+    Ok(())
+}
+
+fn is_enoent(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::NotFound || code_of(error) == Some("ENOENT")
+}
+
+// ============================================================================
+// Load ladder (flagged-storage-io.ts loadFlaggedAccountsState)
+// ============================================================================
+
+/// Persist a recovered backup while respecting the reset marker and the
+/// non-reentrant storage lock (unlocked save when the lock is already held).
+async fn persist_recovered_backup(
+    storage: &FlaggedAccountStorageV1,
+    reset_marker_path: &str,
+) -> Result<bool, CodexError> {
+    let recover = |storage: FlaggedAccountStorageV1, marker: String| async move {
+        if Path::new(&marker).exists() {
+            return Ok(false);
+        }
+        save_flagged_accounts_unlocked(&storage).await?;
+        Ok(true)
+    };
+    if crate::transactions::is_storage_lock_held() {
+        recover(storage.clone(), reset_marker_path.to_string()).await
+    } else {
+        let storage = storage.clone();
+        let marker = reset_marker_path.to_string();
+        crate::transactions::with_storage_lock(move || recover(storage, marker)).await
+    }
+}
+
+/// Persist used by the legacy migration: unlocked when the lock is held,
+/// locked otherwise (same deadlock-avoidance as `persist_recovered_backup`).
+async fn save_flagged_for_migration(storage: &FlaggedAccountStorageV1) -> Result<(), CodexError> {
+    if crate::transactions::is_storage_lock_held() {
+        save_flagged_accounts_unlocked(storage).await
+    } else {
+        save_flagged_accounts(storage).await
+    }
+}
+
+async fn load_flagged_backup(
+    path: &str,
+    reset_marker_path: &str,
+) -> Option<FlaggedAccountStorageV1> {
+    let log = create_logger("storage");
+    for backup_path in get_flagged_backup_paths(path) {
+        if !Path::new(&backup_path).exists() {
+            continue;
+        }
+        let attempt = async {
+            let backup_content = read_file_with_retry(&backup_path).await?;
+            let backup_data = parse_flagged_storage_content(&backup_content)?;
+            Ok::<(Value, FlaggedAccountStorageV1), io::Error>((
+                backup_data.clone(),
+                normalize_flagged_storage(&backup_data),
+            ))
+        }
+        .await;
+        match attempt {
+            Ok((backup_data, recovered)) => {
+                if !is_valid_flagged_storage_candidate(&backup_data, &recovered) {
+                    log.error(
+                        "Skipping invalid flagged account backup payload",
+                        Some(&json!({ "from": backup_path, "to": path })),
+                    );
+                    continue;
+                }
+                if Path::new(reset_marker_path).exists() {
+                    return Some(FlaggedAccountStorageV1::empty());
+                }
+                if !recovered.accounts.is_empty() {
+                    match persist_recovered_backup(&recovered, reset_marker_path).await {
+                        Ok(false) => return Some(FlaggedAccountStorageV1::empty()),
+                        Ok(true) => {}
+                        Err(persist_error) => {
+                            log.error(
+                                "Failed to persist recovered flagged account storage",
+                                Some(&json!({
+                                    "from": backup_path,
+                                    "to": path,
+                                    "error": persist_error.to_string(),
+                                })),
+                            );
+                            return Some(recovered);
+                        }
+                    }
+                }
+                log.info(
+                    "Recovered flagged account storage from backup",
+                    Some(&json!({
+                        "from": backup_path,
+                        "to": path,
+                        "accounts": recovered.accounts.len(),
+                    })),
+                );
+                return Some(recovered);
+            }
+            Err(backup_error) => {
+                log.error(
+                    "Failed to recover flagged account storage from backup",
+                    Some(&json!({
+                        "from": backup_path,
+                        "to": path,
+                        "error": backup_error.to_string(),
+                    })),
+                );
+            }
+        }
+    }
+    None
+}
+
+/// TS `loadFlaggedAccounts()` — never throws; ladder per spec 02 §9.1.
+pub async fn load_flagged_accounts() -> FlaggedAccountStorageV1 {
+    let log = create_logger("storage");
+    let path = get_flagged_accounts_path();
+    let legacy_path = get_legacy_flagged_accounts_path();
+    let reset_marker_path = crate::backup_paths::get_intentional_reset_marker_path(&path);
+
+    if Path::new(&reset_marker_path).exists() {
+        return FlaggedAccountStorageV1::empty();
+    }
+
+    let primary_attempt = async {
+        let content = read_file_with_retry(&path).await?;
+        let data = parse_flagged_storage_content(&content)?;
+        let loaded = normalize_flagged_storage(&data);
+        if !is_valid_flagged_storage_candidate(&data, &loaded) {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "Invalid flagged account storage payload",
+            ));
+        }
+        Ok::<FlaggedAccountStorageV1, io::Error>(loaded)
+    }
+    .await;
+
+    match primary_attempt {
+        Ok(loaded) => {
+            if Path::new(&reset_marker_path).exists() {
+                return FlaggedAccountStorageV1::empty();
+            }
+            return loaded;
+        }
+        Err(error) if !is_enoent(&error) => {
+            log.error(
+                "Failed to load flagged account storage",
+                Some(&json!({ "path": path, "error": error.to_string() })),
+            );
+            return load_flagged_backup(&path, &reset_marker_path)
+                .await
+                .unwrap_or_else(FlaggedAccountStorageV1::empty);
+        }
+        Err(_enoent) => {}
+    }
+
+    if let Some(recovered_backup) = load_flagged_backup(&path, &reset_marker_path).await {
+        return recovered_backup;
+    }
+
+    if !Path::new(&legacy_path).exists() {
+        return FlaggedAccountStorageV1::empty();
+    }
+
+    let migration_attempt = async {
+        let legacy_content = read_file_with_retry(&legacy_path)
+            .await
+            .map_err(io_to_codex)?;
+        let legacy_data =
+            parse_flagged_storage_content(&legacy_content).map_err(io_to_codex)?;
+        let migrated = normalize_flagged_storage(&legacy_data);
+        if !migrated.accounts.is_empty() {
+            save_flagged_for_migration(&migrated).await?;
+        }
+        Ok::<FlaggedAccountStorageV1, CodexError>(migrated)
+    }
+    .await;
+
+    match migration_attempt {
+        Ok(migrated) => {
+            // Best-effort legacy cleanup.
+            let _ = tokio::fs::remove_file(&legacy_path).await;
+            log.info(
+                "Migrated legacy flagged account storage",
+                Some(&json!({
+                    "from": legacy_path,
+                    "to": path,
+                    "accounts": migrated.accounts.len(),
+                })),
+            );
+            migrated
+        }
+        Err(error) => {
+            log.error(
+                "Failed to migrate legacy flagged account storage",
+                Some(&json!({
+                    "from": legacy_path,
+                    "to": path,
+                    "error": error.to_string(),
+                })),
+            );
+            FlaggedAccountStorageV1::empty()
+        }
+    }
+}
+
+// ============================================================================
+// Save (flagged-storage-io.ts saveFlaggedAccountsUnlockedToDisk)
+// ============================================================================
+
+/// TS `saveFlaggedAccountsUnlocked` — callers must already hold the storage
+/// lock (or be on a deliberate unlocked path).
+pub async fn save_flagged_accounts_unlocked(
+    storage: &FlaggedAccountStorageV1,
+) -> Result<(), CodexError> {
+    let log = create_logger("storage");
+    let path = get_flagged_accounts_path();
+    let marker_path = crate::backup_paths::get_intentional_reset_marker_path(&path);
+    let temp_path = temp_path_for_str(&path);
+
+    let attempt = async {
+        if let Some(parent) = Path::new(&path).parent() {
+            // Default directory mode here — deliberately NOT 0700 (spec §9.2).
+            tokio::fs::create_dir_all(parent).await?;
+        }
+        if Path::new(&path).exists()
+            && let Err(backup_error) =
+                copy_file_with_retry(&path, &format!("{path}.bak"), true).await
+        {
+            log.warn(
+                "Failed to create flagged backup snapshot",
+                Some(&json!({ "path": path, "error": backup_error.to_string() })),
+            );
+        }
+        let normalized =
+            normalize_flagged_storage(&serde_json::to_value(storage).unwrap_or(Value::Null));
+        let content = cma_core::json_io::stringify_pretty2(&flagged_storage_to_persist_value(
+            &normalized,
+        ));
+        write_file_mode_600(&temp_path, &content).await?;
+        rename_file_with_retry(&temp_path, &path).await?;
+        // Best-effort marker cleanup.
+        let _ = tokio::fs::remove_file(&marker_path).await;
+        Ok::<(), io::Error>(())
+    }
+    .await;
+
+    match attempt {
+        Ok(()) => Ok(()),
+        Err(error) => {
+            // Best-effort temp cleanup.
+            let _ = tokio::fs::remove_file(&temp_path).await;
+            log.error(
+                "Failed to save flagged account storage",
+                Some(&json!({ "path": path, "error": error.to_string() })),
+            );
+            // RAW error contract: rethrown unwrapped (code preserved).
+            Err(io_to_codex(error))
+        }
+    }
+}
+
+/// TS `saveFlaggedAccounts(storage)` — lock + unlocked save.
+pub async fn save_flagged_accounts(storage: &FlaggedAccountStorageV1) -> Result<(), CodexError> {
+    let storage = storage.clone();
+    crate::transactions::with_storage_lock(move || async move {
+        save_flagged_accounts_unlocked(&storage).await
+    })
+    .await
+}
+
+// ============================================================================
+// Clear (flagged-storage-io.ts clearFlaggedAccountsOnDisk)
+// ============================================================================
+
+async fn clear_flagged_accounts_on_disk(
+    path: &str,
+    marker_path: &str,
+    backup_paths: &[String],
+) -> Result<(), CodexError> {
+    let log = create_logger("storage");
+    let mut keep_reset_marker = false;
+    if let Err(error) = write_file_mode_600(marker_path, "reset").await {
+        log.error(
+            "Failed to write flagged reset marker",
+            Some(&json!({
+                "path": path,
+                "markerPath": marker_path,
+                "error": error.to_string(),
+            })),
+        );
+        return Err(io_to_codex(error));
+    }
+    let mut candidates: Vec<&str> = vec![path];
+    candidates.extend(backup_paths.iter().map(String::as_str));
+    for candidate in candidates {
+        if let Err(error) = unlink_with_retry(candidate).await
+            && !is_enoent(&error)
+        {
+            log.error(
+                "Failed to clear flagged account storage",
+                Some(&json!({ "path": candidate, "error": error.to_string() })),
+            );
+            if candidate == path {
+                return Err(io_to_codex(error));
+            }
+            keep_reset_marker = true;
+        }
+    }
+    if !keep_reset_marker
+        && let Err(error) = unlink_with_retry(marker_path).await
+        && !is_enoent(&error)
+    {
+        log.error(
+            "Failed to clear flagged account storage",
+            Some(&json!({ "path": marker_path, "error": error.to_string() })),
+        );
+        return Err(io_to_codex(error));
+    }
+    Ok(())
+}
+
+/// TS `clearFlaggedAccounts()` — lock + marker-first artifact clear.
+pub async fn clear_flagged_accounts() -> Result<(), CodexError> {
+    let path = get_flagged_accounts_path();
+    let marker_path = crate::backup_paths::get_intentional_reset_marker_path(&path);
+    crate::transactions::with_storage_lock(move || async move {
+        let backup_paths =
+            crate::backups::get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+        clear_flagged_accounts_on_disk(&path, &marker_path, &backup_paths).await
+    })
+    .await
+}
+
+// ============================================================================
+// Tests (ported from test/flagged-storage.test.ts + persist-order golden)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalize_returns_empty_for_invalid_shapes() {
+        for value in [
+            json!(null),
+            json!([]),
+            json!("nope"),
+            json!({ "version": 2, "accounts": [] }),
+            json!({ "version": 1, "accounts": "not-array" }),
+            json!({ "version": 1 }),
+        ] {
+            let normalized = normalize_flagged_storage(&value);
+            assert!(normalized.accounts.is_empty(), "value: {value}");
+        }
+    }
+
+    #[test]
+    fn normalize_skips_accounts_without_refresh_token() {
+        let data = json!({
+            "version": 1,
+            "accounts": [
+                { "flaggedAt": 5 },
+                { "refreshToken": "   ", "flaggedAt": 5 },
+                { "refreshToken": "rt_ok", "flaggedAt": 5 },
+                "not-a-record",
+            ],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        assert_eq!(normalized.accounts.len(), 1);
+        assert_eq!(normalized.accounts[0].refresh_token, "rt_ok");
+    }
+
+    #[test]
+    fn normalize_dedupes_by_refresh_token_last_wins_first_position() {
+        let data = json!({
+            "version": 1,
+            "accounts": [
+                { "refreshToken": "rt_a", "flaggedAt": 1, "flaggedReason": "first" },
+                { "refreshToken": "rt_b", "flaggedAt": 2 },
+                { "refreshToken": "rt_a", "flaggedAt": 3, "flaggedReason": "second" },
+            ],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        assert_eq!(normalized.accounts.len(), 2);
+        // rt_a keeps its FIRST position, with the LAST occurrence's content.
+        assert_eq!(normalized.accounts[0].refresh_token, "rt_a");
+        assert_eq!(normalized.accounts[0].flagged_reason.as_deref(), Some("second"));
+        assert_eq!(normalized.accounts[0].flagged_at, 3);
+        assert_eq!(normalized.accounts[1].refresh_token, "rt_b");
+    }
+
+    #[test]
+    fn normalize_defaults_added_at_and_last_used_to_flagged_at() {
+        let data = json!({
+            "version": 1,
+            "accounts": [{ "refreshToken": "rt", "flaggedAt": 777 }],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        assert_eq!(normalized.accounts[0].added_at, 777);
+        assert_eq!(normalized.accounts[0].last_used, 777);
+    }
+
+    #[test]
+    fn normalize_uses_injected_now_when_flagged_at_missing() {
+        let data = json!({
+            "version": 1,
+            "accounts": [{ "refreshToken": "rt" }],
+        });
+        let mut now = || 12_345_i64;
+        let normalized = normalize_flagged_storage_with(&data, &mut now);
+        assert_eq!(normalized.accounts[0].flagged_at, 12_345);
+        assert_eq!(normalized.accounts[0].added_at, 12_345);
+        assert_eq!(normalized.accounts[0].last_used, 12_345);
+    }
+
+    #[test]
+    fn normalize_validates_enum_fields_by_value() {
+        let data = json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "flaggedAt": 1,
+                "accountIdSource": "bogus",
+                "lastSwitchReason": "rotation",
+                "cooldownReason": "nope",
+            }],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        let account = &normalized.accounts[0];
+        assert_eq!(account.account_id_source, None);
+        assert_eq!(account.last_switch_reason, Some(SwitchReason::Rotation));
+        assert_eq!(account.cooldown_reason, None);
+    }
+
+    #[test]
+    fn normalize_filters_rate_limit_reset_times_to_numbers() {
+        let data = json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "flaggedAt": 1,
+                "rateLimitResetTimes": { "codex": 5, "gpt-5.2": "soon", "codex-max": 7 },
+            }],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        let resets = normalized.accounts[0]
+            .rate_limit_reset_times
+            .as_ref()
+            .expect("kept");
+        assert_eq!(resets.get("codex"), Some(5));
+        assert_eq!(resets.get("codex-max"), Some(7));
+        assert!(!resets.contains_key("gpt-5.2"));
+        // All-invalid map collapses to None.
+        let all_invalid = json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "flaggedAt": 1,
+                "rateLimitResetTimes": { "codex": "soon" },
+            }],
+        });
+        assert!(
+            normalize_flagged_storage(&all_invalid).accounts[0]
+                .rate_limit_reset_times
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn normalize_drops_unknown_fields() {
+        let data = json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt",
+                "flaggedAt": 1,
+                "someFutureField": { "nested": true },
+            }],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        assert!(normalized.accounts[0].extra.is_empty());
+        let persisted = flagged_storage_to_persist_value(&normalized);
+        assert!(persisted["accounts"][0].get("someFutureField").is_none());
+    }
+
+    #[test]
+    fn persist_value_matches_golden_byte_layout() {
+        // Mirrors crates/testkit/goldens/flagged-v1.json exactly (whitelist
+        // insertion order, not schema order).
+        let data = json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt-fixture-flagged-0000000003",
+                "addedAt": 1_749_800_000_000_i64,
+                "lastUsed": 1_749_990_000_000_i64,
+                "accountId": "acct-user-three",
+                "accountIdSource": "id_token",
+                "accountLabel": "Flagged Account",
+                "email": "user.three@example.com",
+                "accessToken": "at-fixture-flagged-0000000003",
+                "expiresAt": 1_750_003_600_000_i64,
+                "enabled": false,
+                "lastSwitchReason": "rate-limit",
+                "rateLimitResetTimes": { "codex": 1_750_000_900_000_i64 },
+                "coolingDownUntil": 1_750_003_600_000_i64,
+                "cooldownReason": "auth-failure",
+                "workspaces": [{
+                    "id": "ws-three-1",
+                    "name": "Personal",
+                    "enabled": true,
+                    "isDefault": true,
+                }],
+                "currentWorkspaceIndex": 0,
+                "flaggedAt": 1_750_000_000_000_i64,
+                "flaggedReason": "invalid_grant on refresh",
+                "lastError": "401 Unauthorized: invalid_grant",
+            }],
+        });
+        let normalized = normalize_flagged_storage(&data);
+        let content =
+            cma_core::json_io::stringify_pretty2(&flagged_storage_to_persist_value(&normalized));
+        let golden = cma_testkit::goldens::read_golden_string("flagged-v1.json");
+        assert_eq!(content, golden);
+    }
+
+    #[test]
+    fn valid_candidate_rules() {
+        let empty_storage = FlaggedAccountStorageV1::empty();
+        // Missing own keys.
+        assert!(!is_valid_flagged_storage_candidate(&json!({}), &empty_storage));
+        assert!(!is_valid_flagged_storage_candidate(
+            &json!({ "version": 1 }),
+            &empty_storage
+        ));
+        // version !== 1.
+        assert!(!is_valid_flagged_storage_candidate(
+            &json!({ "version": 2, "accounts": [] }),
+            &empty_storage
+        ));
+        // Raw accounts empty ⇒ valid even with empty normalized storage.
+        assert!(is_valid_flagged_storage_candidate(
+            &json!({ "version": 1, "accounts": [] }),
+            &empty_storage
+        ));
+        // Raw accounts present but normalized empty (100% invalid rows) ⇒
+        // corrupt, NOT empty (gotcha 18).
+        assert!(!is_valid_flagged_storage_candidate(
+            &json!({ "version": 1, "accounts": [{ "bad": true }] }),
+            &empty_storage
+        ));
+    }
+}
diff --git a/crates/storage/src/health.rs b/crates/storage/src/health.rs
new file mode 100644
index 000000000..856fb8eaa
--- /dev/null
+++ b/crates/storage/src/health.rs
@@ -0,0 +1,305 @@
+//! Port of `lib/storage/health.ts` + the `inspectStorageHealth` wiring from
+//! `lib/storage.ts` (spec 02 §13.3).
+//!
+//! 5-state summary: `healthy | empty | intentional-reset | corrupt |
+//! recoverable`, with the frozen `details` strings and the silent WAL probe
+//! on missing/invalid/throwing primaries.
+
+use std::path::Path;
+
+use serde::Serialize;
+
+/// TS `StorageHealthState`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+pub enum StorageHealthState {
+    #[serde(rename = "healthy")]
+    Healthy,
+    #[serde(rename = "empty")]
+    Empty,
+    #[serde(rename = "intentional-reset")]
+    IntentionalReset,
+    #[serde(rename = "corrupt")]
+    Corrupt,
+    #[serde(rename = "recoverable")]
+    Recoverable,
+}
+
+impl StorageHealthState {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Healthy => "healthy",
+            Self::Empty => "empty",
+            Self::IntentionalReset => "intentional-reset",
+            Self::Corrupt => "corrupt",
+            Self::Recoverable => "recoverable",
+        }
+    }
+}
+
+/// The only recovery source surfaced by the health probe.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+pub enum RecoverySource {
+    #[serde(rename = "wal")]
+    Wal,
+}
+
+/// TS `StorageHealthSummary`.
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct StorageHealthSummary {
+    pub state: StorageHealthState,
+    pub path: String,
+    #[serde(rename = "resetMarkerPath")]
+    pub reset_marker_path: String,
+    #[serde(rename = "walPath")]
+    pub wal_path: String,
+    #[serde(rename = "hasResetMarker")]
+    pub has_reset_marker: bool,
+    #[serde(rename = "hasWal")]
+    pub has_wal: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub details: Option<String>,
+    #[serde(rename = "schemaErrors", skip_serializing_if = "Option::is_none")]
+    pub schema_errors: Option<Vec<String>>,
+    #[serde(rename = "recoverySource", skip_serializing_if = "Option::is_none")]
+    pub recovery_source: Option<RecoverySource>,
+}
+
+/// Parameters for [`create_storage_health_summary`].
+#[derive(Clone, Debug, Default)]
+pub struct StorageHealthParams {
+    pub details: Option<String>,
+    pub schema_errors: Option<Vec<String>>,
+    pub recovery_source: Option<RecoverySource>,
+}
+
+/// TS `createStorageHealthSummary` — `hasResetMarker`/`hasWal` are re-stat'd
+/// at construction time.
+pub fn create_storage_health_summary(
+    state: StorageHealthState,
+    path: &Path,
+    reset_marker_path: &str,
+    wal_path: &str,
+    params: StorageHealthParams,
+) -> StorageHealthSummary {
+    StorageHealthSummary {
+        state,
+        path: path.to_string_lossy().into_owned(),
+        reset_marker_path: reset_marker_path.to_string(),
+        wal_path: wal_path.to_string(),
+        has_reset_marker: Path::new(reset_marker_path).exists(),
+        has_wal: Path::new(wal_path).exists(),
+        details: params.details,
+        schema_errors: params.schema_errors,
+        recovery_source: params.recovery_source,
+    }
+}
+
+/// TS `inspectStorageHealth()` (storage.ts export).
+pub async fn inspect_storage_health() -> StorageHealthSummary {
+    let path = std::path::PathBuf::from(crate::facade::get_storage_path());
+    let wal_path = crate::backup_paths::get_accounts_wal_path(&path);
+    let reset_marker_path = crate::backup_paths::get_intentional_reset_marker_path(&path);
+
+    if Path::new(&reset_marker_path).exists() {
+        return create_storage_health_summary(
+            StorageHealthState::IntentionalReset,
+            &path,
+            &reset_marker_path,
+            &wal_path,
+            StorageHealthParams {
+                details: Some("intentional reset marker present".to_string()),
+                ..Default::default()
+            },
+        );
+    }
+
+    if !Path::new(&path).exists() {
+        let wal_recovered = crate::load::load_accounts_from_journal(&path, true).await;
+        if wal_recovered
+            .as_ref()
+            .is_some_and(|storage| !storage.accounts.is_empty())
+        {
+            return create_storage_health_summary(
+                StorageHealthState::Recoverable,
+                &path,
+                &reset_marker_path,
+                &wal_path,
+                StorageHealthParams {
+                    details: Some(
+                        "primary storage missing but WAL recovery is available".to_string(),
+                    ),
+                    recovery_source: Some(RecoverySource::Wal),
+                    ..Default::default()
+                },
+            );
+        }
+        return create_storage_health_summary(
+            StorageHealthState::Empty,
+            &path,
+            &reset_marker_path,
+            &wal_path,
+            StorageHealthParams {
+                details: Some("storage file is missing".to_string()),
+                ..Default::default()
+            },
+        );
+    }
+
+    match crate::parser::load_accounts_from_path(&path).await {
+        Ok(parsed) => {
+            // TS passes the raw (possibly empty) array on EVERY
+            // parse-succeeded branch, so `report --json` always contains
+            // `"schemaErrors": []` in the healthy case. Only the
+            // intentional-reset / missing-file / parse-Err branches leave the
+            // key undefined (None).
+            let schema_errors = Some(parsed.schema_errors.clone());
+            if let Some(normalized) = &parsed.normalized {
+                if !normalized.accounts.is_empty() {
+                    return create_storage_health_summary(
+                        StorageHealthState::Healthy,
+                        &path,
+                        &reset_marker_path,
+                        &wal_path,
+                        StorageHealthParams {
+                            schema_errors,
+                            ..Default::default()
+                        },
+                    );
+                }
+                return create_storage_health_summary(
+                    StorageHealthState::Empty,
+                    &path,
+                    &reset_marker_path,
+                    &wal_path,
+                    StorageHealthParams {
+                        schema_errors,
+                        details: Some("storage parsed but contains no accounts".to_string()),
+                        ..Default::default()
+                    },
+                );
+            }
+            let wal_recovered = crate::load::load_accounts_from_journal(&path, true).await;
+            if wal_recovered
+                .as_ref()
+                .is_some_and(|storage| !storage.accounts.is_empty())
+            {
+                return create_storage_health_summary(
+                    StorageHealthState::Recoverable,
+                    &path,
+                    &reset_marker_path,
+                    &wal_path,
+                    StorageHealthParams {
+                        schema_errors,
+                        details: Some(
+                            "primary storage is invalid but WAL recovery is available".to_string(),
+                        ),
+                        recovery_source: Some(RecoverySource::Wal),
+                    },
+                );
+            }
+            create_storage_health_summary(
+                StorageHealthState::Corrupt,
+                &path,
+                &reset_marker_path,
+                &wal_path,
+                StorageHealthParams {
+                    schema_errors,
+                    details: Some("storage could not be normalized".to_string()),
+                    ..Default::default()
+                },
+            )
+        }
+        Err(error) => {
+            let wal_recovered = crate::load::load_accounts_from_journal(&path, true).await;
+            if wal_recovered
+                .as_ref()
+                .is_some_and(|storage| !storage.accounts.is_empty())
+            {
+                return create_storage_health_summary(
+                    StorageHealthState::Recoverable,
+                    &path,
+                    &reset_marker_path,
+                    &wal_path,
+                    StorageHealthParams {
+                        details: Some(error.to_string()),
+                        recovery_source: Some(RecoverySource::Wal),
+                        ..Default::default()
+                    },
+                );
+            }
+            create_storage_health_summary(
+                StorageHealthState::Corrupt,
+                &path,
+                &reset_marker_path,
+                &wal_path,
+                StorageHealthParams {
+                    details: Some(error.to_string()),
+                    ..Default::default()
+                },
+            )
+        }
+    }
+}
+
+// ============================================================================
+// Tests (pure summary construction; the on-disk state matrix lives in the
+// storage-health integration suite once the load/parser siblings land)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn summary_serializes_kebab_states_and_camel_keys() {
+        let summary = create_storage_health_summary(
+            StorageHealthState::IntentionalReset,
+            Path::new("/x/a.json"),
+            "/x/a.json.reset-intent",
+            "/x/a.json.wal",
+            StorageHealthParams {
+                details: Some("intentional reset marker present".to_string()),
+                recovery_source: Some(RecoverySource::Wal),
+                ..Default::default()
+            },
+        );
+        let value = serde_json::to_value(&summary).unwrap();
+        assert_eq!(value["state"], "intentional-reset");
+        assert_eq!(value["resetMarkerPath"], "/x/a.json.reset-intent");
+        assert_eq!(value["walPath"], "/x/a.json.wal");
+        assert_eq!(value["hasResetMarker"], false);
+        assert_eq!(value["hasWal"], false);
+        assert_eq!(value["recoverySource"], "wal");
+        assert!(value.get("schemaErrors").is_none());
+    }
+
+    #[test]
+    fn empty_schema_errors_serialize_as_an_empty_array_when_present() {
+        // TS emits `"schemaErrors": []` on every parse-succeeded branch;
+        // Some(vec![]) must serialize as [] (None still omits the key).
+        let summary = create_storage_health_summary(
+            StorageHealthState::Healthy,
+            Path::new("/x/a.json"),
+            "/x/a.json.reset-intent",
+            "/x/a.json.wal",
+            StorageHealthParams {
+                schema_errors: Some(Vec::new()),
+                ..Default::default()
+            },
+        );
+        let value = serde_json::to_value(&summary).unwrap();
+        assert_eq!(value["schemaErrors"], serde_json::json!([]));
+    }
+
+    #[test]
+    fn state_as_str_matches_ts_labels() {
+        assert_eq!(StorageHealthState::Healthy.as_str(), "healthy");
+        assert_eq!(StorageHealthState::Empty.as_str(), "empty");
+        assert_eq!(
+            StorageHealthState::IntentionalReset.as_str(),
+            "intentional-reset"
+        );
+        assert_eq!(StorageHealthState::Corrupt.as_str(), "corrupt");
+        assert_eq!(StorageHealthState::Recoverable.as_str(), "recoverable");
+    }
+}
diff --git a/crates/storage/src/identity.rs b/crates/storage/src/identity.rs
new file mode 100644
index 000000000..f3143de99
--- /dev/null
+++ b/crates/storage/src/identity.rs
@@ -0,0 +1,318 @@
+//! Port of `lib/storage/identity.ts` (spec 02 §6.1).
+//!
+//! Identity normalization and identity keys for account matching:
+//! - [`normalize_email_key`]: trim + lowercase, empty ⇒ `None`.
+//! - [`to_account_identity_ref`] / [`AccountIdentityRef::from_parts`]: build a
+//!   normalized identity reference (`accountId` trimmed, `emailKey`
+//!   trimmed+lowercased, `refreshToken` trimmed; blanks ⇒ `None`).
+//! - [`get_account_identity_key`]: `"account:<id>::email:<key>"` |
+//!   `"account:<id>"` | `"email:<key>"` | `"refresh:<sha256hex(token)>"` |
+//!   `None` — the refresh fallback hashes the token so key material never
+//!   reaches logs.
+//! - [`get_runtime_account_identity_key`]: same WITHOUT the refresh fallback;
+//!   falls back to the numeric account index instead.
+
+use sha2::{Digest, Sha256};
+
+use cma_core::schemas::account_storage::{AccountMetadataV1, AccountMetadataV3};
+use cma_core::schemas::flagged::FlaggedAccountMetadataV1;
+
+/// Anything that can expose the three identity fields used by the matcher.
+/// (TS `AccountLike = { accountId?, email?, refreshToken? }`.)
+pub trait AccountIdentityLike {
+    fn identity_account_id(&self) -> Option<&str>;
+    fn identity_email(&self) -> Option<&str>;
+    fn identity_refresh_token(&self) -> Option<&str>;
+}
+
+impl AccountIdentityLike for AccountMetadataV3 {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.refresh_token.as_str())
+    }
+}
+
+impl AccountIdentityLike for AccountMetadataV1 {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.refresh_token.as_str())
+    }
+}
+
+impl AccountIdentityLike for FlaggedAccountMetadataV1 {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        Some(self.refresh_token.as_str())
+    }
+}
+
+impl<T: AccountIdentityLike> AccountIdentityLike for &T {
+    fn identity_account_id(&self) -> Option<&str> {
+        (*self).identity_account_id()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        (*self).identity_email()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        (*self).identity_refresh_token()
+    }
+}
+
+/// Normalized identity reference (TS `AccountIdentityRef`).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AccountIdentityRef {
+    /// Trimmed accountId (blank ⇒ `None`).
+    pub account_id: Option<String>,
+    /// Trimmed + lowercased email (blank ⇒ `None`).
+    pub email_key: Option<String>,
+    /// Trimmed refresh token (blank ⇒ `None`).
+    pub refresh_token: Option<String>,
+}
+
+impl AccountIdentityRef {
+    /// Build a normalized ref from raw parts (candidate shape used by
+    /// `normalizeAccountStorage` / `resolveAccountSelectionIndex` callers).
+    pub fn from_parts(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        refresh_token: Option<&str>,
+    ) -> Self {
+        Self {
+            account_id: normalize_account_id_key(account_id),
+            email_key: normalize_email_key(email),
+            refresh_token: normalize_refresh_token_key(refresh_token),
+        }
+    }
+}
+
+/// The ref itself is account-like (all fields already normalized;
+/// re-normalizing is idempotent).
+impl AccountIdentityLike for AccountIdentityRef {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email_key.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        self.refresh_token.as_deref()
+    }
+}
+
+fn normalize_account_id_key(account_id: Option<&str>) -> Option<String> {
+    let trimmed = account_id?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `normalizeEmailKey`: trim then lowercase; empty ⇒ `None`.
+pub fn normalize_email_key(email: Option<&str>) -> Option<String> {
+    let trimmed = email?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_lowercase())
+    }
+}
+
+fn normalize_refresh_token_key(refresh_token: Option<&str>) -> Option<String> {
+    let trimmed = refresh_token?.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn hash_refresh_token_key(refresh_token: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(refresh_token.as_bytes());
+    let digest = hasher.finalize();
+    let mut hex = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(hex, "{byte:02x}");
+    }
+    hex
+}
+
+/// TS `toAccountIdentityRef` — normalized identity ref for an account.
+pub fn to_account_identity_ref(account: &impl AccountIdentityLike) -> AccountIdentityRef {
+    AccountIdentityRef::from_parts(
+        account.identity_account_id(),
+        account.identity_email(),
+        account.identity_refresh_token(),
+    )
+}
+
+fn identity_key_from_ref(
+    ref_: &AccountIdentityRef,
+    allow_refresh_fallback: bool,
+) -> Option<String> {
+    match (&ref_.account_id, &ref_.email_key) {
+        (Some(account_id), Some(email_key)) => {
+            return Some(format!("account:{account_id}::email:{email_key}"));
+        }
+        (Some(account_id), None) => return Some(format!("account:{account_id}")),
+        (None, Some(email_key)) => return Some(format!("email:{email_key}")),
+        (None, None) => {}
+    }
+    if allow_refresh_fallback
+        && let Some(refresh_token) = &ref_.refresh_token
+    {
+        // Legacy refresh-only identity keys embedded raw tokens. Hashing
+        // preserves deterministic fallback matching without exposing token
+        // material in logs.
+        return Some(format!(
+            "refresh:{}",
+            hash_refresh_token_key(refresh_token)
+        ));
+    }
+    None
+}
+
+/// TS `getAccountIdentityKey` — persistent identity key with refresh-token
+/// hash fallback.
+pub fn get_account_identity_key(account: &impl AccountIdentityLike) -> Option<String> {
+    let ref_ = to_account_identity_ref(account);
+    identity_key_from_ref(&ref_, true)
+}
+
+/// Runtime identity key: string key or numeric fallback index (TS returned
+/// `string | number | undefined`).
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub enum RuntimeAccountIdentityKey {
+    Key(String),
+    Index(i64),
+}
+
+impl std::fmt::Display for RuntimeAccountIdentityKey {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Key(key) => f.write_str(key),
+            Self::Index(index) => write!(f, "{index}"),
+        }
+    }
+}
+
+/// TS `getRuntimeAccountIdentityKey` — like [`get_account_identity_key`] but
+/// with NO refresh-token fallback; falls back to the numeric `index` when
+/// neither accountId nor email is present.
+pub fn get_runtime_account_identity_key(
+    account_id: Option<&str>,
+    email: Option<&str>,
+    index: Option<i64>,
+) -> Option<RuntimeAccountIdentityKey> {
+    let ref_ = AccountIdentityRef::from_parts(account_id, email, None);
+    if let Some(key) = identity_key_from_ref(&ref_, false) {
+        return Some(RuntimeAccountIdentityKey::Key(key));
+    }
+    index.map(RuntimeAccountIdentityKey::Index)
+}
+
+// ============================================================================
+// Tests (identity assertions from the storage matching suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalize_email_key_trims_and_lowercases() {
+        assert_eq!(
+            normalize_email_key(Some("  User@Example.COM  ")),
+            Some("user@example.com".to_string())
+        );
+        assert_eq!(normalize_email_key(Some("   ")), None);
+        assert_eq!(normalize_email_key(Some("")), None);
+        assert_eq!(normalize_email_key(None), None);
+    }
+
+    #[test]
+    fn to_account_identity_ref_normalizes_all_fields() {
+        let ref_ = AccountIdentityRef::from_parts(
+            Some("  acc_1  "),
+            Some(" A@B.com "),
+            Some("  rt_x  "),
+        );
+        assert_eq!(ref_.account_id.as_deref(), Some("acc_1"));
+        assert_eq!(ref_.email_key.as_deref(), Some("a@b.com"));
+        assert_eq!(ref_.refresh_token.as_deref(), Some("rt_x"));
+        let blank = AccountIdentityRef::from_parts(Some(" "), Some(""), None);
+        assert_eq!(blank, AccountIdentityRef::default());
+    }
+
+    #[test]
+    fn identity_key_preference_order() {
+        // composite
+        let both = AccountIdentityRef::from_parts(Some("acc"), Some("A@B.com"), Some("rt"));
+        assert_eq!(
+            identity_key_from_ref(&both, true).as_deref(),
+            Some("account:acc::email:a@b.com")
+        );
+        // account only
+        let id_only = AccountIdentityRef::from_parts(Some("acc"), None, Some("rt"));
+        assert_eq!(
+            identity_key_from_ref(&id_only, true).as_deref(),
+            Some("account:acc")
+        );
+        // email only
+        let email_only = AccountIdentityRef::from_parts(None, Some("x@y.z"), Some("rt"));
+        assert_eq!(
+            identity_key_from_ref(&email_only, true).as_deref(),
+            Some("email:x@y.z")
+        );
+        // refresh fallback is hashed, never the raw token
+        let refresh_only = AccountIdentityRef::from_parts(None, None, Some("rt_secret"));
+        let key = identity_key_from_ref(&refresh_only, true).expect("refresh key");
+        assert!(key.starts_with("refresh:"));
+        assert!(!key.contains("rt_secret"));
+        assert_eq!(key.len(), "refresh:".len() + 64);
+        // nothing
+        let none = AccountIdentityRef::default();
+        assert_eq!(identity_key_from_ref(&none, true), None);
+    }
+
+    #[test]
+    fn runtime_identity_key_has_no_refresh_fallback() {
+        assert_eq!(
+            get_runtime_account_identity_key(Some("acc"), Some("a@b.c"), Some(4)),
+            Some(RuntimeAccountIdentityKey::Key(
+                "account:acc::email:a@b.c".to_string()
+            ))
+        );
+        assert_eq!(
+            get_runtime_account_identity_key(None, None, Some(2)),
+            Some(RuntimeAccountIdentityKey::Index(2))
+        );
+        assert_eq!(get_runtime_account_identity_key(None, None, None), None);
+    }
+
+    #[test]
+    fn account_metadata_impls_expose_identity_fields() {
+        let mut account = AccountMetadataV3::new("rt", 1, 2);
+        account.account_id = Some("acc_9".into());
+        account.email = Some("Person@Example.com".into());
+        let key = get_account_identity_key(&account).expect("key");
+        assert_eq!(key, "account:acc_9::email:person@example.com");
+    }
+}
diff --git a/crates/storage/src/import_export.rs b/crates/storage/src/import_export.rs
new file mode 100644
index 000000000..c6200ca49
--- /dev/null
+++ b/crates/storage/src/import_export.rs
@@ -0,0 +1,518 @@
+//! Port of `lib/storage/import-export.ts` + `lib/storage/account-port.ts`
+//! and the `exportAccounts` / `importAccounts` wiring from `lib/storage.ts`
+//! (spec 02 §12.1–§12.2).
+//!
+//! - Export payload (§3.7): `{version, accounts, activeIndex,
+//!   activeIndexByFamily}` — **deliberately omits `pinnedAccountIndex` and
+//!   `affinityGeneration`** (gotcha 1): exports are portable snapshots, pins
+//!   are machine-local.
+//! - Export source selection is transaction-aware (gotcha 11): an active
+//!   transaction on the SAME path uses the in-memory snapshot; a transaction
+//!   on a DIFFERENT path uses the unlocked read; otherwise a locked read.
+//! - Import: 4 MiB cap, 20-account cap (dedupe first), pin re-resolved BY
+//!   IDENTITY against the deduplicated list (#474), count arithmetic
+//!   verbatim (gotcha 29 — do not clamp).
+
+// `CodexError` is core's frozen error shape (192 bytes); the sibling-crate API
+// contract pins these `Result<_, CodexError>` signatures, so boxing is not an
+// option here.
+#![allow(clippy::result_large_err)]
+
+use std::io;
+use std::path::Path;
+
+use serde_json::{Map, Value, json};
+
+use cma_core::constants::ACCOUNT_LIMITS;
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{code_of, should_retry_file_operation};
+use cma_core::logger::create_logger;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::temp_path::temp_path_for_str;
+use cma_core::utils::sleep;
+
+use crate::matching::{AccountMatchOptions, deduplicate_accounts, find_matching_account_index};
+
+const EXPORT_RENAME_MAX_ATTEMPTS: u32 = 4;
+const EXPORT_RENAME_BASE_DELAY_MS: u64 = 25;
+const MAX_IMPORT_BYTES: u64 = 4 * 1024 * 1024;
+
+/// Hook invoked right before the final export rename (named-backup
+/// containment re-check). Synchronous in the Rust port.
+pub type BeforeCommitHook<'a> = &'a (dyn Fn(&str) -> Result<(), CodexError> + Send + Sync);
+
+fn io_to_codex(error: io::Error) -> CodexError {
+    let mapped = CodexError::new(error.to_string());
+    match code_of(&error) {
+        Some(code) => mapped.with_code(code).with_cause(error),
+        None => mapped.with_cause(error),
+    }
+}
+
+fn read_json_to_codex(error: cma_core::json_io::ReadJsonError) -> CodexError {
+    match error {
+        cma_core::json_io::ReadJsonError::Io(io_error) => io_to_codex(io_error),
+        cma_core::json_io::ReadJsonError::Parse(parse_error) => {
+            CodexError::new(parse_error.to_string())
+        }
+    }
+}
+
+/// `resolvePath` boundary with its frozen `Error` messages surfaced as plain
+/// `CodexError`s (TS throws bare `Error`s the CLI matches on).
+fn resolve_path_string(file_path: &str) -> Result<String, CodexError> {
+    match crate::paths::resolve_path(file_path) {
+        Ok(path) => Ok(path.to_string_lossy().into_owned()),
+        Err(error) => Err(CodexError::new(error.0)),
+    }
+}
+
+async fn rename_export_file_with_retry(
+    source_path: &str,
+    destination_path: &str,
+) -> io::Result<()> {
+    for attempt in 0..EXPORT_RENAME_MAX_ATTEMPTS {
+        match tokio::fs::rename(source_path, destination_path).await {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                // storage-07: shared retryable-code set (adds
+                // ENOTEMPTY/EACCES) rather than a local subset.
+                let can_retry = should_retry_file_operation(&error)
+                    && attempt + 1 < EXPORT_RENAME_MAX_ATTEMPTS;
+                if !can_retry {
+                    return Err(error);
+                }
+                sleep(EXPORT_RENAME_BASE_DELAY_MS * 2u64.pow(attempt)).await;
+            }
+        }
+    }
+    unreachable!("loop returns before exhausting attempts");
+}
+
+/// Best-effort removal of the staged export temp file, retried on transient
+/// Windows locks. The temp file briefly holds the full account export
+/// (refresh tokens) — a single-shot unlink losing to a transient lock would
+/// strand a secret-bearing `.tmp` next to the destination. Never fails.
+async fn unlink_export_file_best_effort(temp_path: &str) {
+    for attempt in 0..EXPORT_RENAME_MAX_ATTEMPTS {
+        match tokio::fs::remove_file(temp_path).await {
+            Ok(()) => return,
+            Err(error) => {
+                if error.kind() == io::ErrorKind::NotFound {
+                    return; // already gone (e.g. rename consumed it)
+                }
+                let can_retry = should_retry_file_operation(&error)
+                    && attempt + 1 < EXPORT_RENAME_MAX_ATTEMPTS;
+                if !can_retry {
+                    return; // give up silently; cleanup is best-effort
+                }
+                sleep(EXPORT_RENAME_BASE_DELAY_MS * 2u64.pow(attempt)).await;
+            }
+        }
+    }
+}
+
+/// Build the §3.7 export payload: `version, accounts, activeIndex,
+/// activeIndexByFamily` — pin/generation omitted on purpose.
+fn build_export_payload(storage: &AccountStorageV3) -> Value {
+    let mut object = Map::new();
+    object.insert("version".to_string(), Value::from(3));
+    object.insert(
+        "accounts".to_string(),
+        serde_json::to_value(&storage.accounts).unwrap_or(Value::Array(Vec::new())),
+    );
+    object.insert("activeIndex".to_string(), Value::from(storage.active_index));
+    if let Some(by_family) = &storage.active_index_by_family {
+        object.insert(
+            "activeIndexByFamily".to_string(),
+            serde_json::to_value(by_family).unwrap_or(Value::Object(Map::new())),
+        );
+    }
+    Value::Object(object)
+}
+
+/// Node `fs.writeFile(..., { mode: 0o600 })` parity: mode applied atomically
+/// at open(2) on unix so the export temp file (refresh-token material) never
+/// exists with broader permissions — no write-then-chmod window.
+async fn write_file_mode_600(path: &str, content: &str) -> io::Result<()> {
+    let mut options = tokio::fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    options.mode(0o600);
+    let mut file = options.open(path).await?;
+    use tokio::io::AsyncWriteExt;
+    file.write_all(content.as_bytes()).await?;
+    file.flush().await?;
+    Ok(())
+}
+
+/// TS `exportAccountsToFile` — atomic export with the frozen error strings.
+pub async fn export_accounts_to_file(
+    resolved_path: &str,
+    force: bool,
+    storage: Option<&AccountStorageV3>,
+    before_commit: Option<BeforeCommitHook<'_>>,
+) -> Result<(), CodexError> {
+    let log = create_logger("storage");
+    if !force && Path::new(resolved_path).exists() {
+        return Err(CodexError::new(format!(
+            "File already exists: {resolved_path}"
+        )));
+    }
+    let storage = match storage {
+        Some(storage) if !storage.accounts.is_empty() => storage,
+        _ => return Err(CodexError::new("No accounts to export")),
+    };
+
+    if let Some(parent) = Path::new(resolved_path).parent() {
+        tokio::fs::create_dir_all(parent).await.map_err(io_to_codex)?;
+    }
+    if let Some(before_commit) = before_commit {
+        before_commit(resolved_path)?;
+    }
+    // TOCTOU narrowing: re-check after mkdir + beforeCommit.
+    if !force && Path::new(resolved_path).exists() {
+        return Err(CodexError::new(format!(
+            "File already exists: {resolved_path}"
+        )));
+    }
+
+    let content = cma_core::json_io::stringify_pretty2(&build_export_payload(storage));
+    let temp_path = temp_path_for_str(resolved_path);
+    let write_attempt = async {
+        write_file_mode_600(&temp_path, &content).await?;
+        rename_export_file_with_retry(&temp_path, resolved_path).await
+    }
+    .await;
+    if let Err(error) = write_attempt {
+        unlink_export_file_best_effort(&temp_path).await;
+        return Err(io_to_codex(error));
+    }
+    log.info(
+        "Exported accounts",
+        Some(&json!({ "path": resolved_path, "count": storage.accounts.len() })),
+    );
+    Ok(())
+}
+
+/// TS `readImportFile` — size-capped, JSON-boundary-guarded import read.
+pub async fn read_import_file(resolved_path: &str) -> Result<AccountStorageV3, CodexError> {
+    if !Path::new(resolved_path).exists() {
+        return Err(CodexError::new(format!(
+            "Import file not found: {resolved_path}"
+        )));
+    }
+
+    let metadata = tokio::fs::metadata(resolved_path)
+        .await
+        .map_err(io_to_codex)?;
+    if metadata.len() > MAX_IMPORT_BYTES {
+        return Err(CodexError::new(format!(
+            "Import file exceeds maximum size of {MAX_IMPORT_BYTES} bytes: {resolved_path}"
+        )));
+    }
+    let content = tokio::fs::read_to_string(resolved_path)
+        .await
+        .map_err(io_to_codex)?;
+
+    // Zod-first in TS; both the validated and the raw path feed the same
+    // normalizer, so a single parse is behaviorally equivalent. Syntax errors
+    // map to the frozen "Invalid JSON" message; structurally-unknown payloads
+    // flow to the normalizer (legacy shapes).
+    let imported: Value = serde_json::from_str(&content).map_err(|_| {
+        CodexError::new(format!("Invalid JSON in import file: {resolved_path}"))
+    })?;
+
+    crate::normalize::normalize_account_storage(&imported)
+        .ok_or_else(|| CodexError::new("Invalid account storage format"))
+}
+
+/// Result of [`merge_imported_accounts`]. Counts reproduce the TS arithmetic
+/// verbatim — they can go negative in edge cases (gotcha 29); do not clamp.
+#[derive(Clone, Debug)]
+pub struct MergedImport {
+    pub new_storage: AccountStorageV3,
+    pub imported: i64,
+    pub total: i64,
+    pub skipped: i64,
+}
+
+/// TS `mergeImportedAccounts`.
+pub fn merge_imported_accounts(
+    existing: Option<&AccountStorageV3>,
+    imported: &AccountStorageV3,
+    max_accounts: usize,
+) -> Result<MergedImport, CodexError> {
+    let existing_accounts = existing.map(|s| s.accounts.clone()).unwrap_or_default();
+    let existing_active_index = existing.map(|s| s.active_index).unwrap_or(0);
+    // Resolve the pinned account by IDENTITY before merging — dedupe below
+    // can move accounts to different positions (#474).
+    let pinned_account = existing
+        .and_then(|s| s.pinned_account_index)
+        .and_then(|index| usize::try_from(index).ok())
+        .and_then(|index| existing_accounts.get(index).cloned());
+
+    let mut merged = existing_accounts.clone();
+    merged.extend(imported.accounts.iter().cloned());
+
+    if merged.len() > max_accounts {
+        let deduped = deduplicate_accounts(&merged);
+        if deduped.len() > max_accounts {
+            return Err(CodexError::new(format!(
+                "Import would exceed maximum of {max_accounts} accounts (would have {})",
+                deduped.len()
+            )));
+        }
+    }
+
+    let deduplicated_accounts = deduplicate_accounts(&merged);
+    let deduplicated_existing_accounts = deduplicate_accounts(&existing_accounts);
+    let mut new_storage = AccountStorageV3 {
+        version: Default::default(),
+        accounts: deduplicated_accounts,
+        active_index: existing_active_index,
+        active_index_by_family: existing.and_then(|s| s.active_index_by_family.clone()),
+        pinned_account_index: None,
+        affinity_generation: None,
+    };
+    // Preserve the manual pin (#474) by re-resolving it against the deduped
+    // list; drop it when the pinned account no longer resolves.
+    if let Some(pinned_account) = &pinned_account
+        && let Some(remapped_index) = find_matching_account_index(
+            &new_storage.accounts,
+            pinned_account,
+            AccountMatchOptions::default(),
+        )
+    {
+        new_storage.pinned_account_index = Some(remapped_index as i64);
+    }
+    if let Some(affinity_generation) = existing.and_then(|s| s.affinity_generation) {
+        new_storage.affinity_generation = Some(affinity_generation);
+    }
+    let imported_count =
+        new_storage.accounts.len() as i64 - deduplicated_existing_accounts.len() as i64;
+    let skipped_count = imported.accounts.len() as i64 - imported_count;
+    Ok(MergedImport {
+        total: new_storage.accounts.len() as i64,
+        imported: imported_count,
+        skipped: skipped_count,
+        new_storage,
+    })
+}
+
+/// TS `exportAccounts(filePath, force = true, beforeCommit?)` — resolves the
+/// destination through the `resolvePath` security boundary and selects the
+/// storage source transaction-awareness first (spec §11).
+pub async fn export_accounts(
+    file_path: &str,
+    force: bool,
+    before_commit: Option<BeforeCommitHook<'_>>,
+) -> Result<(), CodexError> {
+    let resolved_path = resolve_path_string(file_path)?;
+    let current_storage_path = std::path::PathBuf::from(crate::facade::get_storage_path());
+    let transaction_state = crate::transactions::get_transaction_snapshot_state();
+
+    let storage: Option<AccountStorageV3> = match &transaction_state {
+        Some(state) if state.active && state.storage_path == current_storage_path => {
+            state.snapshot()
+        }
+        Some(state) if state.active => crate::load::load_accounts_for_export()
+            .await
+            .map_err(read_json_to_codex)?
+            .map(|loaded| loaded.storage),
+        _ => crate::transactions::with_storage_lock(crate::load::load_accounts_for_export)
+            .await
+            .map_err(read_json_to_codex)?
+            .map(|loaded| loaded.storage),
+    };
+
+    export_accounts_to_file(&resolved_path, force, storage.as_ref(), before_commit).await
+}
+
+/// Import summary returned by [`import_accounts`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ImportSummary {
+    pub imported: i64,
+    pub total: i64,
+    pub skipped: i64,
+}
+
+/// TS `importAccounts(filePath)` — merge under the account-storage
+/// transaction.
+pub async fn import_accounts(file_path: &str) -> Result<ImportSummary, CodexError> {
+    let log = create_logger("storage");
+    let resolved_path = resolve_path_string(file_path)?;
+    let normalized = read_import_file(&resolved_path).await?;
+
+    let result = crate::transactions::with_account_storage_transaction(
+        move |existing, persist| async move {
+            let merged = merge_imported_accounts(
+                existing.as_ref(),
+                &normalized,
+                ACCOUNT_LIMITS.max_accounts,
+            )?;
+            persist.persist(&merged.new_storage).await?;
+            Ok(ImportSummary {
+                imported: merged.imported,
+                total: merged.total,
+                skipped: merged.skipped,
+            })
+        },
+    )
+    .await?;
+
+    log.info(
+        "Imported accounts",
+        Some(&json!({
+            "path": resolved_path,
+            "imported": result.imported,
+            "skipped": result.skipped,
+            "total": result.total,
+        })),
+    );
+    Ok(result)
+}
+
+// ============================================================================
+// Tests (ported from test/import-export.test.ts merge/count suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::{ActiveIndexByFamily, AccountMetadataV3};
+
+    fn account(id: &str, rt: &str, last_used: i64) -> AccountMetadataV3 {
+        let mut a = AccountMetadataV3::new(rt, 1, last_used);
+        a.account_id = Some(id.to_string());
+        a.email = Some(format!("{id}@example.com"));
+        a
+    }
+
+    fn storage(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut s = AccountStorageV3::empty();
+        s.accounts = accounts;
+        s
+    }
+
+    #[test]
+    fn merge_appends_new_accounts_and_counts() {
+        let existing = storage(vec![account("a", "rt_a", 10)]);
+        let imported = storage(vec![account("b", "rt_b", 10)]);
+        let merged = merge_imported_accounts(Some(&existing), &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.accounts.len(), 2);
+        assert_eq!(merged.imported, 1);
+        assert_eq!(merged.total, 2);
+        assert_eq!(merged.skipped, 0);
+    }
+
+    #[test]
+    fn merge_dedupes_and_reports_skipped() {
+        let existing = storage(vec![account("a", "rt_a", 10)]);
+        let imported = storage(vec![account("a", "rt_a2", 20), account("b", "rt_b", 5)]);
+        let merged = merge_imported_accounts(Some(&existing), &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.accounts.len(), 2);
+        // Newest content for the duplicate identity survives.
+        assert_eq!(merged.new_storage.accounts[0].refresh_token, "rt_a2");
+        assert_eq!(merged.imported, 1);
+        assert_eq!(merged.skipped, 1);
+    }
+
+    #[test]
+    fn merge_keeps_existing_active_index_verbatim() {
+        let mut existing = storage(vec![account("a", "rt_a", 10)]);
+        existing.active_index = 7; // NOT re-resolved / clamped here (gotcha 30)
+        existing.active_index_by_family = Some(ActiveIndexByFamily {
+            codex: Some(1),
+            ..Default::default()
+        });
+        let imported = storage(vec![account("b", "rt_b", 10)]);
+        let merged = merge_imported_accounts(Some(&existing), &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.active_index, 7);
+        assert_eq!(
+            merged
+                .new_storage
+                .active_index_by_family
+                .as_ref()
+                .and_then(|f| f.codex),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn merge_enforces_max_after_dedupe() {
+        let existing = storage(vec![account("a", "rt_a", 10), account("b", "rt_b", 10)]);
+        let imported = storage(vec![
+            account("c", "rt_c", 10),
+            account("d", "rt_d", 10),
+        ]);
+        let error =
+            merge_imported_accounts(Some(&existing), &imported, 3).expect_err("over cap");
+        assert_eq!(
+            error.message(),
+            "Import would exceed maximum of 3 accounts (would have 4)"
+        );
+        // Duplicates shrink below the cap ⇒ allowed.
+        let duplicate_import = storage(vec![account("a", "rt_a", 20), account("c", "rt_c", 10)]);
+        let merged =
+            merge_imported_accounts(Some(&existing), &duplicate_import, 3).expect("fits");
+        assert_eq!(merged.new_storage.accounts.len(), 3);
+    }
+
+    #[test]
+    fn merge_reresolves_pin_by_identity_and_preserves_generation() {
+        let mut existing = storage(vec![account("a", "rt_a", 10), account("b", "rt_b", 30)]);
+        existing.pinned_account_index = Some(1); // pins "b"
+        existing.affinity_generation = Some(6);
+        // Import a newer copy of "b" that dedupes into position 1 anyway,
+        // plus an "a" duplicate whose newest content wins slot 0.
+        let imported = storage(vec![account("b", "rt_b_new", 40)]);
+        let merged = merge_imported_accounts(Some(&existing), &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.pinned_account_index, Some(1));
+        assert_eq!(merged.new_storage.affinity_generation, Some(6));
+        assert_eq!(merged.new_storage.accounts[1].refresh_token, "rt_b_new");
+    }
+
+    #[test]
+    fn merge_drops_unresolvable_pin() {
+        let mut existing = storage(vec![account("a", "rt_a", 10)]);
+        existing.pinned_account_index = Some(5); // out of range ⇒ no pinned account
+        let imported = storage(vec![account("b", "rt_b", 10)]);
+        let merged = merge_imported_accounts(Some(&existing), &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.pinned_account_index, None);
+    }
+
+    #[test]
+    fn merge_with_no_existing_storage() {
+        let imported = storage(vec![account("a", "rt_a", 10)]);
+        let merged = merge_imported_accounts(None, &imported, 20).expect("merges");
+        assert_eq!(merged.new_storage.active_index, 0);
+        assert_eq!(merged.imported, 1);
+        assert_eq!(merged.total, 1);
+        assert_eq!(merged.skipped, 0);
+    }
+
+    #[test]
+    fn export_payload_omits_pin_and_generation() {
+        let mut s = storage(vec![account("a", "rt_a", 10)]);
+        s.pinned_account_index = Some(0);
+        s.affinity_generation = Some(9);
+        s.active_index_by_family = Some(ActiveIndexByFamily {
+            gpt5_codex: Some(0),
+            ..Default::default()
+        });
+        let payload = build_export_payload(&s);
+        let object = payload.as_object().expect("object");
+        let keys: Vec<&String> = object.keys().collect();
+        assert_eq!(keys, ["version", "accounts", "activeIndex", "activeIndexByFamily"]);
+        assert!(object.get("pinnedAccountIndex").is_none());
+        assert!(object.get("affinityGeneration").is_none());
+    }
+
+    #[test]
+    fn export_payload_omits_missing_active_index_by_family() {
+        let s = storage(vec![account("a", "rt_a", 10)]);
+        let payload = build_export_payload(&s);
+        assert!(payload.get("activeIndexByFamily").is_none());
+    }
+}
diff --git a/crates/storage/src/lib.rs b/crates/storage/src/lib.rs
new file mode 100644
index 000000000..1d08f1a16
--- /dev/null
+++ b/crates/storage/src/lib.rs
@@ -0,0 +1,29 @@
+//! cma-storage - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod backup_metadata;
+pub mod backup_paths;
+pub mod backup_restore;
+pub mod backups;
+pub mod clear;
+pub mod facade;
+pub mod fixture_guards;
+pub mod flagged;
+pub mod health;
+pub mod identity;
+pub mod import_export;
+pub mod load;
+pub mod match_utils;
+pub mod matching;
+pub mod migrations;
+pub mod misc;
+pub mod named_backups;
+pub mod normalize;
+pub mod parser;
+pub mod path_state;
+pub mod paths;
+pub mod project_migration;
+pub mod public_types;
+pub mod restore;
+pub mod save;
+pub mod save_retry;
+pub mod snapshot;
+pub mod transactions;
diff --git a/crates/storage/src/load.rs b/crates/storage/src/load.rs
new file mode 100644
index 000000000..c8779e78f
--- /dev/null
+++ b/crates/storage/src/load.rs
@@ -0,0 +1,709 @@
+//! Port of the accounts load pipeline from `lib/storage.ts`:
+//! `loadAccounts`, `loadAccountsInternal` (the recovery ladder),
+//! `loadAccountsFromJournal` (WAL replay), `loadAccountsForExport`
+//! (side-effect-free), and the sync single-field readers
+//! `readAffinityGenerationFromDisk` / `readPinAndGenFromDisk` (#474).
+//!
+//! Behavior source: spec 02 §5.4, §8, gotchas 2, 9, 12, 20, 26.
+//!
+//! Recovery ladder on a failed primary read: reset-marker → (ENOENT) legacy
+//! project migration result → WAL (sha256 checksum) → discovered backups →
+//! ENOENT ⇒ empty/missing-storage, else `None`. The happy path additionally
+//! runs v1→v3 migration persists and synthetic-primary backup promotion.
+//! All load-side persists are warn-only on failure.
+//!
+//! The legacy project-storage migration itself lives in
+//! `crate::project_migration` (spec 02 §5.4–§5.5); this module wires it into
+//! the load ladder with the right persist mode.
+//!
+//! R6 (ratified): `restoreEligible`/`restoreReason` stay OUT of the
+//! serializable `AccountStorageV3` — they ride side-band on
+//! [`LoadedAccountStorage`].
+
+use std::fs;
+use std::io;
+use std::path::Path;
+
+use cma_core::fs_retry::code_of;
+use cma_core::json_io::ReadJsonError;
+use cma_core::logger::create_logger;
+use cma_core::schemas::journal::AccountsJournalEntry;
+use cma_core::schemas::parse::safe_parse_json_with_context;
+use serde_json::{Value, json};
+
+use crate::backup_paths::{get_accounts_wal_path, get_intentional_reset_marker_path};
+use crate::backups::{
+    cleanup_stale_rotating_backup_artifacts,
+    get_accounts_backup_recovery_candidates_with_discovery,
+};
+use crate::facade;
+use crate::fixture_guards::looks_like_synthetic_fixture_storage;
+use crate::misc::compute_sha256;
+use crate::parser::{load_accounts_from_path, parse_storage_content};
+use crate::project_migration::{MigrationPersist, migrate_legacy_project_storage_if_needed};
+use crate::public_types::AccountStorageV3;
+
+/// Restore-reason strings (in-memory only — never persisted).
+pub const RESTORE_REASON_INTENTIONAL_RESET: &str = "intentional-reset";
+pub const RESTORE_REASON_EMPTY_STORAGE: &str = "empty-storage";
+pub const RESTORE_REASON_MISSING_STORAGE: &str = "missing-storage";
+
+/// Side-band restore metadata (TS spliced `restoreEligible`/`restoreReason`
+/// onto returned storage objects; R6 keeps them out of the serde struct).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RestoreMetadata {
+    pub restore_eligible: bool,
+    pub restore_reason: &'static str,
+}
+
+/// A loaded storage plus optional restore metadata.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LoadedAccountStorage {
+    pub storage: AccountStorageV3,
+    pub restore: Option<RestoreMetadata>,
+}
+
+impl LoadedAccountStorage {
+    fn plain(storage: AccountStorageV3) -> Self {
+        Self {
+            storage,
+            restore: None,
+        }
+    }
+
+    fn empty_with_metadata(restore_eligible: bool, restore_reason: &'static str) -> Self {
+        Self {
+            storage: AccountStorageV3::empty(),
+            restore: Some(RestoreMetadata {
+                restore_eligible,
+                restore_reason,
+            }),
+        }
+    }
+
+    fn with_metadata(
+        storage: AccountStorageV3,
+        restore_eligible: bool,
+        restore_reason: &'static str,
+    ) -> Self {
+        Self {
+            storage,
+            restore: Some(RestoreMetadata {
+                restore_eligible,
+                restore_reason,
+            }),
+        }
+    }
+}
+
+/// Which persist function migrations/recovery use — `loadAccounts` persists
+/// through the locked `saveAccounts`; transactions (which already hold the
+/// storage lock) use the unlocked variant; `None` disables persists.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PersistMigration {
+    None,
+    Locked,
+    Unlocked,
+}
+
+impl PersistMigration {
+    fn is_enabled(self) -> bool {
+        self != PersistMigration::None
+    }
+
+    fn as_migration_persist(self) -> MigrationPersist {
+        match self {
+            PersistMigration::None => MigrationPersist::None,
+            PersistMigration::Locked => MigrationPersist::Locked,
+            PersistMigration::Unlocked => MigrationPersist::Unlocked,
+        }
+    }
+
+    async fn persist(self, storage: &AccountStorageV3) -> Result<(), cma_core::errors::CodexError> {
+        match self {
+            PersistMigration::None => Ok(()),
+            PersistMigration::Locked => crate::save::save_accounts(storage).await,
+            PersistMigration::Unlocked => crate::save::save_accounts_unlocked(storage).await,
+        }
+    }
+}
+
+/// `loadAccounts()` = `loadAccountsInternal(saveAccounts)`.
+pub async fn load_accounts() -> Option<LoadedAccountStorage> {
+    load_accounts_internal(PersistMigration::Locked).await
+}
+
+/// `loadAccountsInternal(saveAccountsUnlocked)` — the transaction-side load:
+/// the storage lock is already held, so migration/recovery persists go through
+/// the UNLOCKED save. Returns the plain storage (restore metadata is
+/// in-memory-only and not part of the transaction snapshot).
+pub async fn load_accounts_unlocked() -> Option<AccountStorageV3> {
+    load_accounts_internal(PersistMigration::Unlocked)
+        .await
+        .map(|loaded| loaded.storage)
+}
+
+fn is_enoent(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::NotFound || code_of(error) == Some("ENOENT")
+}
+
+fn marker_exists(reset_marker_path: &str) -> bool {
+    Path::new(reset_marker_path).exists()
+}
+
+/// `loadAccountsInternal(persistMigration)` — the full ladder (spec 02 §8.1).
+pub async fn load_accounts_internal(persist: PersistMigration) -> Option<LoadedAccountStorage> {
+    let log = create_logger("storage");
+    let path = facade::get_storage_path();
+    let reset_marker_path = get_intentional_reset_marker_path(&path);
+    cleanup_stale_rotating_backup_artifacts(&path).await;
+    let migrated_legacy_storage: Option<AccountStorageV3> = if persist.is_enabled() {
+        // Commit mode never errors (persist failures are warn-only inside).
+        migrate_legacy_project_storage_if_needed(persist.as_migration_persist())
+            .await
+            .unwrap_or(None)
+    } else {
+        None
+    };
+
+    match load_accounts_from_path(&path).await {
+        Ok(parsed) => {
+            if !parsed.schema_errors.is_empty() {
+                log.warn(
+                    "Account storage schema validation warnings",
+                    Some(&json!({
+                        "errors": parsed.schema_errors.iter().take(5).collect::<Vec<_>>(),
+                    })),
+                );
+            }
+            let normalized = parsed.normalized.clone();
+            if let Some(normalized_storage) = &normalized
+                && parsed.needs_version_migration()
+            {
+                log.info(
+                    "Migrating account storage to v3",
+                    Some(&json!({
+                        "from": parsed.stored_version,
+                        "to": 3,
+                    })),
+                );
+                if persist.is_enabled()
+                    && let Err(save_error) = persist.persist(normalized_storage).await
+                {
+                    log.warn(
+                        "Failed to persist migrated storage",
+                        Some(&json!({ "error": save_error.to_string() })),
+                    );
+                }
+            }
+
+            if marker_exists(&reset_marker_path) {
+                return Some(LoadedAccountStorage::empty_with_metadata(
+                    false,
+                    RESTORE_REASON_INTENTIONAL_RESET,
+                ));
+            }
+
+            if let Some(normalized_storage) = &normalized
+                && normalized_storage.accounts.is_empty()
+            {
+                return Some(LoadedAccountStorage::with_metadata(
+                    normalized_storage.clone(),
+                    true,
+                    RESTORE_REASON_EMPTY_STORAGE,
+                ));
+            }
+
+            // Synthetic-primary promotion (gotcha 13, load side).
+            let primary_looks_synthetic =
+                looks_like_synthetic_fixture_storage(normalized.as_ref());
+            if facade::storage_backup_enabled()
+                && let Some(normalized_storage) = &normalized
+                && primary_looks_synthetic
+            {
+                let backup_candidates =
+                    get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+                for backup_path in backup_candidates {
+                    if backup_path == path {
+                        continue;
+                    }
+                    match load_accounts_from_path(&backup_path).await {
+                        Ok(backup) => {
+                            let Some(backup_normalized) = backup.normalized else {
+                                continue;
+                            };
+                            if looks_like_synthetic_fixture_storage(Some(&backup_normalized)) {
+                                continue;
+                            }
+                            if backup_normalized.accounts.is_empty() {
+                                continue;
+                            }
+                            log.warn(
+                                "Detected synthetic primary account storage; promoting backup",
+                                Some(&json!({
+                                    "path": path,
+                                    "backupPath": backup_path,
+                                    "primaryAccounts": normalized_storage.accounts.len(),
+                                    "backupAccounts": backup_normalized.accounts.len(),
+                                })),
+                            );
+                            if persist.is_enabled()
+                                && let Err(persist_error) =
+                                    persist.persist(&backup_normalized).await
+                            {
+                                log.warn(
+                                    "Failed to persist promoted backup storage",
+                                    Some(&json!({
+                                        "path": path,
+                                        "error": persist_error.to_string(),
+                                    })),
+                                );
+                            }
+                            return Some(LoadedAccountStorage::plain(backup_normalized));
+                        }
+                        Err(backup_error) => {
+                            if !is_enoent(&backup_error) {
+                                log.warn(
+                                    "Failed to load candidate backup for synthetic-primary promotion",
+                                    Some(&json!({
+                                        "path": backup_path,
+                                        "error": backup_error.to_string(),
+                                    })),
+                                );
+                            }
+                        }
+                    }
+                }
+            }
+
+            normalized.map(LoadedAccountStorage::plain)
+        }
+        Err(error) => {
+            let enoent = is_enoent(&error);
+            if marker_exists(&reset_marker_path) {
+                return Some(LoadedAccountStorage::empty_with_metadata(
+                    false,
+                    RESTORE_REASON_INTENTIONAL_RESET,
+                ));
+            }
+            if enoent && let Some(migrated) = migrated_legacy_storage {
+                return Some(LoadedAccountStorage::plain(migrated));
+            }
+
+            if let Some(recovered) = load_accounts_from_journal(&path, false).await {
+                if persist.is_enabled()
+                    && let Err(persist_error) = persist.persist(&recovered).await
+                {
+                    log.warn(
+                        "Failed to persist WAL-recovered storage",
+                        Some(&json!({
+                            "path": path,
+                            "error": persist_error.to_string(),
+                        })),
+                    );
+                }
+                return Some(LoadedAccountStorage::plain(recovered));
+            }
+            if marker_exists(&reset_marker_path) {
+                return Some(LoadedAccountStorage::empty_with_metadata(
+                    false,
+                    RESTORE_REASON_INTENTIONAL_RESET,
+                ));
+            }
+
+            if facade::storage_backup_enabled() {
+                let backup_candidates =
+                    get_accounts_backup_recovery_candidates_with_discovery(&path).await;
+                for backup_path in backup_candidates {
+                    match load_accounts_from_path(&backup_path).await {
+                        Ok(backup) => {
+                            if !backup.schema_errors.is_empty() {
+                                log.warn(
+                                    "Backup account storage schema validation warnings",
+                                    Some(&json!({
+                                        "path": backup_path,
+                                        "errors":
+                                            backup.schema_errors.iter().take(5).collect::<Vec<_>>(),
+                                    })),
+                                );
+                            }
+                            if let Some(backup_normalized) = backup.normalized {
+                                log.warn(
+                                    "Recovered account storage from backup file",
+                                    Some(&json!({
+                                        "path": path,
+                                        "backupPath": backup_path,
+                                    })),
+                                );
+                                if persist.is_enabled()
+                                    && let Err(persist_error) =
+                                        persist.persist(&backup_normalized).await
+                                {
+                                    log.warn(
+                                        "Failed to persist recovered backup storage",
+                                        Some(&json!({
+                                            "path": path,
+                                            "error": persist_error.to_string(),
+                                        })),
+                                    );
+                                }
+                                return Some(LoadedAccountStorage::plain(backup_normalized));
+                            }
+                        }
+                        Err(backup_error) => {
+                            if !is_enoent(&backup_error) {
+                                log.warn(
+                                    "Failed to load backup account storage",
+                                    Some(&json!({
+                                        "path": backup_path,
+                                        "error": backup_error.to_string(),
+                                    })),
+                                );
+                            }
+                        }
+                    }
+                }
+            }
+
+            if !enoent {
+                log.error(
+                    "Failed to load account storage",
+                    Some(&json!({ "error": error.to_string() })),
+                );
+            }
+            if enoent {
+                return Some(LoadedAccountStorage::empty_with_metadata(
+                    true,
+                    RESTORE_REASON_MISSING_STORAGE,
+                ));
+            }
+            None
+        }
+    }
+}
+
+/// `loadAccountsFromJournal(path, {silent})` — WAL replay (spec 02 §8.3):
+/// reset-marker check before AND after the read; schema-guarded entry parse;
+/// sha256 checksum; schema-invalid inner payloads still flow to the
+/// normalizer (fail-closed on JSON syntax only).
+pub async fn load_accounts_from_journal(
+    path: impl AsRef<Path>,
+    silent: bool,
+) -> Option<AccountStorageV3> {
+    let log = create_logger("storage");
+    let path = path.as_ref();
+    let wal_path = get_accounts_wal_path(path);
+    let reset_marker_path = get_intentional_reset_marker_path(path);
+    if marker_exists(&reset_marker_path) {
+        return None;
+    }
+
+    let raw = match fs::read(&wal_path) {
+        Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
+        Err(error) => {
+            if !is_enoent(&error) && !silent {
+                log.warn(
+                    "Failed to load account WAL journal",
+                    Some(&json!({
+                        "path": wal_path,
+                        "error": error.to_string(),
+                    })),
+                );
+            }
+            return None;
+        }
+    };
+    if marker_exists(&reset_marker_path) {
+        return None;
+    }
+
+    let entry: AccountsJournalEntry =
+        safe_parse_json_with_context(&raw, "storage.loadAccountsFromJournal")?;
+    let computed = compute_sha256(&entry.content);
+    if computed != entry.checksum {
+        if !silent {
+            log.warn(
+                "Account journal checksum mismatch",
+                Some(&json!({ "path": wal_path })),
+            );
+        }
+        return None;
+    }
+
+    // Inner content: schema-guarded first; schema-invalid payloads fall to
+    // the raw parse so schemaErrors semantics stay observable; a syntax
+    // error here is fail-closed (None), unlike the primary read.
+    let parsed = match parse_storage_content(&entry.content) {
+        Ok(parsed) => parsed,
+        Err(_) => return None,
+    };
+    let normalized = parsed.normalized?;
+    if !silent {
+        log.warn(
+            "Recovered account storage from WAL journal",
+            Some(&json!({
+                "path": path.to_string_lossy(),
+                "walPath": wal_path,
+            })),
+        );
+    }
+    Some(normalized)
+}
+
+/// `loadAccountsForExport()` — side-effect-free read for exports (spec 02
+/// §8.6): marker check before AND after; ENOENT runs the legacy migration
+/// with `commit:false` (no writes/unlinks); non-ENOENT errors PROPAGATE.
+pub async fn load_accounts_for_export()
+-> Result<Option<LoadedAccountStorage>, ReadJsonError> {
+    let log = create_logger("storage");
+    let path = facade::get_storage_path();
+    let reset_marker_path = get_intentional_reset_marker_path(&path);
+
+    if marker_exists(&reset_marker_path) {
+        return Ok(Some(LoadedAccountStorage::empty_with_metadata(
+            false,
+            RESTORE_REASON_INTENTIONAL_RESET,
+        )));
+    }
+
+    match load_accounts_from_path(&path).await {
+        Ok(parsed) => {
+            if !parsed.schema_errors.is_empty() {
+                log.warn(
+                    "Account storage schema validation warnings",
+                    Some(&json!({
+                        "errors": parsed.schema_errors.iter().take(5).collect::<Vec<_>>(),
+                    })),
+                );
+            }
+            if marker_exists(&reset_marker_path) {
+                return Ok(Some(LoadedAccountStorage::empty_with_metadata(
+                    false,
+                    RESTORE_REASON_INTENTIONAL_RESET,
+                )));
+            }
+            Ok(parsed.normalized.map(LoadedAccountStorage::plain))
+        }
+        Err(error) => {
+            if marker_exists(&reset_marker_path) {
+                return Ok(Some(LoadedAccountStorage::empty_with_metadata(
+                    false,
+                    RESTORE_REASON_INTENTIONAL_RESET,
+                )));
+            }
+            if is_enoent(&error) {
+                // Export-mode migration (`commit:false`) is side-effect-free;
+                // its propagating (non-ENOENT) live re-read failures surface
+                // through the same error channel as the primary read.
+                let migrated = migrate_legacy_project_storage_if_needed(MigrationPersist::None)
+                    .await
+                    .map_err(|migration_error| {
+                        ReadJsonError::Io(io::Error::other(migration_error))
+                    })?;
+                if marker_exists(&reset_marker_path) {
+                    return Ok(Some(LoadedAccountStorage::empty_with_metadata(
+                        false,
+                        RESTORE_REASON_INTENTIONAL_RESET,
+                    )));
+                }
+                return Ok(migrated.map(LoadedAccountStorage::plain));
+            }
+            Err(ReadJsonError::Io(error))
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Sync single-field readers (#474 — spec 02 §8.5)
+// ---------------------------------------------------------------------------
+
+fn read_non_negative_int_field(parsed: &Value, key: &str) -> Option<i64> {
+    let raw = parsed.get(key)?.as_f64()?;
+    if raw.is_finite() && raw.fract() == 0.0 && raw >= 0.0 {
+        Some(raw as i64)
+    } else {
+        None
+    }
+}
+
+/// `readAffinityGenerationFromDisk(path)` — 0 on ANY failure (missing file,
+/// malformed JSON, transient I/O error). Callers apply
+/// `max(inMemory, disk) + 1` before saving.
+pub fn read_affinity_generation_from_disk(path: impl AsRef<Path>) -> i64 {
+    let path = path.as_ref();
+    if !path.exists() {
+        return 0;
+    }
+    let Ok(bytes) = fs::read(path) else {
+        return 0;
+    };
+    let Ok(parsed) =
+        serde_json::from_str::<Value>(&String::from_utf8_lossy(&bytes)) else {
+        return 0;
+    };
+    read_non_negative_int_field(&parsed, "affinityGeneration").unwrap_or(0)
+}
+
+/// Result of [`read_pin_and_gen_from_disk`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PinAndGen {
+    pub pinned_account_index: Option<i64>,
+    pub affinity_generation: i64,
+}
+
+/// `readPinAndGenFromDisk(path)` — `{pinnedAccountIndex: undefined,
+/// affinityGeneration: 0}` on any failure.
+pub fn read_pin_and_gen_from_disk(path: impl AsRef<Path>) -> PinAndGen {
+    let path = path.as_ref();
+    let failure = PinAndGen {
+        pinned_account_index: None,
+        affinity_generation: 0,
+    };
+    if !path.exists() {
+        return failure;
+    }
+    let Ok(bytes) = fs::read(path) else {
+        return failure;
+    };
+    let Ok(parsed) =
+        serde_json::from_str::<Value>(&String::from_utf8_lossy(&bytes)) else {
+        return failure;
+    };
+    PinAndGen {
+        pinned_account_index: read_non_negative_int_field(&parsed, "pinnedAccountIndex"),
+        affinity_generation: read_non_negative_int_field(&parsed, "affinityGeneration")
+            .unwrap_or(0),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn affinity_generation_reader_validates_and_defaults_to_zero() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        // Missing file.
+        assert_eq!(read_affinity_generation_from_disk(&path), 0);
+        // Valid value.
+        fs::write(&path, r#"{"version":3,"accounts":[],"activeIndex":0,"affinityGeneration":7}"#)
+            .unwrap();
+        assert_eq!(read_affinity_generation_from_disk(&path), 7);
+        // Invalid values.
+        fs::write(&path, r#"{"affinityGeneration":-1}"#).unwrap();
+        assert_eq!(read_affinity_generation_from_disk(&path), 0);
+        fs::write(&path, r#"{"affinityGeneration":1.5}"#).unwrap();
+        assert_eq!(read_affinity_generation_from_disk(&path), 0);
+        fs::write(&path, r#"{"affinityGeneration":"9"}"#).unwrap();
+        assert_eq!(read_affinity_generation_from_disk(&path), 0);
+        // Malformed JSON.
+        fs::write(&path, "{oops").unwrap();
+        assert_eq!(read_affinity_generation_from_disk(&path), 0);
+    }
+
+    #[test]
+    fn pin_and_gen_reader_validates_both_fields_independently() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        assert_eq!(
+            read_pin_and_gen_from_disk(&path),
+            PinAndGen {
+                pinned_account_index: None,
+                affinity_generation: 0
+            }
+        );
+        fs::write(
+            &path,
+            r#"{"pinnedAccountIndex":2,"affinityGeneration":5}"#,
+        )
+        .unwrap();
+        assert_eq!(
+            read_pin_and_gen_from_disk(&path),
+            PinAndGen {
+                pinned_account_index: Some(2),
+                affinity_generation: 5
+            }
+        );
+        // Invalid pin, valid gen.
+        fs::write(
+            &path,
+            r#"{"pinnedAccountIndex":-3,"affinityGeneration":5}"#,
+        )
+        .unwrap();
+        assert_eq!(
+            read_pin_and_gen_from_disk(&path),
+            PinAndGen {
+                pinned_account_index: None,
+                affinity_generation: 5
+            }
+        );
+        // Malformed JSON drops both.
+        fs::write(&path, "not-json").unwrap();
+        assert_eq!(
+            read_pin_and_gen_from_disk(&path),
+            PinAndGen {
+                pinned_account_index: None,
+                affinity_generation: 0
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn journal_replay_rejects_checksum_mismatch_and_marker() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let wal = dir.path().join("a.json.wal");
+        let content = r#"{"version":3,"accounts":[{"refreshToken":"rt","addedAt":1,"lastUsed":2}],"activeIndex":0}"#;
+        // Valid WAL replays.
+        let entry = json!({
+            "version": 1,
+            "createdAt": 1,
+            "path": path.to_string_lossy(),
+            "checksum": compute_sha256(content),
+            "content": content,
+        });
+        fs::write(&wal, serde_json::to_string(&entry).unwrap()).unwrap();
+        let recovered = load_accounts_from_journal(&path, true).await.expect("replays");
+        assert_eq!(recovered.accounts.len(), 1);
+
+        // Checksum mismatch invalidates.
+        let bad = json!({
+            "version": 1,
+            "checksum": "deadbeef",
+            "content": content,
+        });
+        fs::write(&wal, serde_json::to_string(&bad).unwrap()).unwrap();
+        assert!(load_accounts_from_journal(&path, true).await.is_none());
+
+        // Reset marker blocks replay entirely.
+        fs::write(&wal, serde_json::to_string(&entry).unwrap()).unwrap();
+        fs::write(dir.path().join("a.json.reset-intent"), "x").unwrap();
+        assert!(load_accounts_from_journal(&path, true).await.is_none());
+    }
+
+    #[tokio::test]
+    async fn journal_replay_is_fail_closed_on_inner_syntax_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a.json");
+        let wal = dir.path().join("a.json.wal");
+        let content = "{not json";
+        let entry = json!({
+            "version": 1,
+            "checksum": compute_sha256(content),
+            "content": content,
+        });
+        fs::write(&wal, serde_json::to_string(&entry).unwrap()).unwrap();
+        assert!(load_accounts_from_journal(&path, true).await.is_none());
+    }
+
+    #[tokio::test]
+    async fn journal_missing_wal_returns_none_silently() {
+        let dir = tempfile::tempdir().unwrap();
+        assert!(
+            load_accounts_from_journal(&dir.path().join("a.json"), false)
+                .await
+                .is_none()
+        );
+    }
+}
diff --git a/crates/storage/src/match_utils.rs b/crates/storage/src/match_utils.rs
new file mode 100644
index 000000000..420f44d89
--- /dev/null
+++ b/crates/storage/src/match_utils.rs
@@ -0,0 +1,222 @@
+//! Port of `lib/storage/account-match-utils.ts` (spec 02 §6).
+//!
+//! - [`select_newest_account`] / [`newest_prefers_candidate`]: higher
+//!   `lastUsed || 0` wins; tie ⇒ higher-or-equal `addedAt || 0` wins, i.e.
+//!   the CANDIDATE wins exact ties (`>=`).
+//! - [`collect_distinct_identity_values`]: distinct non-empty values.
+//! - [`find_newest_matching_index`]: generic newest-match scan.
+
+use std::collections::HashSet;
+
+use cma_core::schemas::account_storage::{AccountMetadataV1, AccountMetadataV3};
+use cma_core::schemas::flagged::FlaggedAccountMetadataV1;
+
+/// Recency fields used by newest-wins selection (TS
+/// `AccountLike = { addedAt?, lastUsed? }`; missing values count as 0).
+pub trait AccountRecency {
+    fn recency_last_used(&self) -> i64;
+    fn recency_added_at(&self) -> i64;
+}
+
+impl AccountRecency for AccountMetadataV3 {
+    fn recency_last_used(&self) -> i64 {
+        self.last_used
+    }
+    fn recency_added_at(&self) -> i64 {
+        self.added_at
+    }
+}
+
+impl AccountRecency for AccountMetadataV1 {
+    fn recency_last_used(&self) -> i64 {
+        self.last_used
+    }
+    fn recency_added_at(&self) -> i64 {
+        self.added_at
+    }
+}
+
+impl AccountRecency for FlaggedAccountMetadataV1 {
+    fn recency_last_used(&self) -> i64 {
+        self.last_used
+    }
+    fn recency_added_at(&self) -> i64 {
+        self.added_at
+    }
+}
+
+impl<T: AccountRecency> AccountRecency for &T {
+    fn recency_last_used(&self) -> i64 {
+        (*self).recency_last_used()
+    }
+    fn recency_added_at(&self) -> i64 {
+        (*self).recency_added_at()
+    }
+}
+
+/// Core of `selectNewestAccount`: does `candidate` win over `current`?
+/// (TS returns the winning object; identity comparison `newest === account`
+/// maps to this boolean.) Candidate wins strict `lastUsed` and wins
+/// `addedAt` ties (`>=`).
+pub fn newest_prefers_candidate<T: AccountRecency>(current: &T, candidate: &T) -> bool {
+    let current_last_used = current.recency_last_used();
+    let candidate_last_used = candidate.recency_last_used();
+    if candidate_last_used > current_last_used {
+        return true;
+    }
+    if candidate_last_used < current_last_used {
+        return false;
+    }
+    candidate.recency_added_at() >= current.recency_added_at()
+}
+
+/// TS `selectNewestAccount(current, candidate)` — returns the newest of the
+/// two (candidate when `current` is absent or on exact ties).
+pub fn select_newest_account<'a, T: AccountRecency>(
+    current: Option<&'a T>,
+    candidate: &'a T,
+) -> &'a T {
+    match current {
+        None => candidate,
+        Some(current) => {
+            if newest_prefers_candidate(current, candidate) {
+                candidate
+            } else {
+                current
+            }
+        }
+    }
+}
+
+/// TS `collectDistinctIdentityValues` — distinct set of the non-empty values.
+pub fn collect_distinct_identity_values<'a>(
+    values: impl IntoIterator<Item = Option<&'a str>>,
+) -> HashSet<String> {
+    let mut distinct = HashSet::new();
+    for value in values.into_iter().flatten() {
+        if !value.is_empty() {
+            distinct.insert(value.to_string());
+        }
+    }
+    distinct
+}
+
+/// TS `findNewestMatchingIndex` — scan `accounts`, keep the newest entry
+/// whose ref satisfies `predicate`. `select_newest_is_candidate(current,
+/// candidate)` decides whether a later match replaces the current one
+/// (candidate-wins-ties semantics live in the injected comparator).
+pub fn find_newest_matching_index<T, R>(
+    accounts: &[T],
+    to_ref: impl Fn(&T) -> R,
+    predicate: impl Fn(&R) -> bool,
+    select_newest_is_candidate: impl Fn(&T, &T) -> bool,
+) -> Option<usize> {
+    let mut match_index: Option<usize> = None;
+    for (i, account) in accounts.iter().enumerate() {
+        let ref_ = to_ref(account);
+        if !predicate(&ref_) {
+            continue;
+        }
+        match match_index {
+            None => match_index = Some(i),
+            Some(current_index) => {
+                if select_newest_is_candidate(&accounts[current_index], account) {
+                    match_index = Some(i);
+                }
+            }
+        }
+    }
+    match_index
+}
+
+// ============================================================================
+// Tests (ported from the account-match-utils assertions)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn account(last_used: i64, added_at: i64) -> AccountMetadataV3 {
+        AccountMetadataV3::new("rt", added_at, last_used)
+    }
+
+    #[test]
+    fn newest_higher_last_used_wins() {
+        let older = account(10, 1);
+        let newer = account(20, 1);
+        assert!(newest_prefers_candidate(&older, &newer));
+        assert!(!newest_prefers_candidate(&newer, &older));
+    }
+
+    #[test]
+    fn newest_tie_goes_to_candidate_on_added_at_gte() {
+        let current = account(10, 5);
+        let candidate_equal = account(10, 5);
+        let candidate_newer = account(10, 6);
+        let candidate_older = account(10, 4);
+        assert!(newest_prefers_candidate(&current, &candidate_equal));
+        assert!(newest_prefers_candidate(&current, &candidate_newer));
+        assert!(!newest_prefers_candidate(&current, &candidate_older));
+    }
+
+    #[test]
+    fn select_newest_account_returns_candidate_when_current_missing() {
+        let candidate = account(1, 1);
+        let selected = select_newest_account(None, &candidate);
+        assert!(std::ptr::eq(selected, &candidate));
+    }
+
+    #[test]
+    fn collect_distinct_skips_missing_and_empty() {
+        let distinct = collect_distinct_identity_values([
+            Some("a"),
+            None,
+            Some(""),
+            Some("b"),
+            Some("a"),
+        ]);
+        assert_eq!(distinct.len(), 2);
+        assert!(distinct.contains("a"));
+        assert!(distinct.contains("b"));
+    }
+
+    #[test]
+    fn find_newest_matching_index_keeps_newest_match() {
+        let accounts = vec![account(10, 1), account(30, 1), account(20, 1)];
+        let index = find_newest_matching_index(
+            &accounts,
+            |a| a.recency_last_used(),
+            |_| true,
+            newest_prefers_candidate,
+        );
+        assert_eq!(index, Some(1));
+    }
+
+    #[test]
+    fn find_newest_matching_index_none_when_no_match() {
+        let accounts = vec![account(10, 1)];
+        let index = find_newest_matching_index(
+            &accounts,
+            |a| a.recency_last_used(),
+            |_| false,
+            newest_prefers_candidate,
+        );
+        assert_eq!(index, None);
+    }
+
+    #[test]
+    fn find_newest_matching_index_first_of_equal_ties_is_replaced_by_candidate() {
+        // Candidate-wins-ties: a later exact tie replaces the earlier match,
+        // mirroring `selectNewestAccount(current, candidate)` returning the
+        // candidate on `addedAt >=`.
+        let accounts = vec![account(10, 5), account(10, 5)];
+        let index = find_newest_matching_index(
+            &accounts,
+            |a| a.recency_last_used(),
+            |_| true,
+            newest_prefers_candidate,
+        );
+        assert_eq!(index, Some(1));
+    }
+}
diff --git a/crates/storage/src/matching.rs b/crates/storage/src/matching.rs
new file mode 100644
index 000000000..f4e598709
--- /dev/null
+++ b/crates/storage/src/matching.rs
@@ -0,0 +1,675 @@
+//! Port of the account-matching functions from `lib/storage.ts`
+//! (spec 02 §6.2–§6.3): the 4-tier identity matcher, pin reconciliation,
+//! selection-index resolution, fixpoint deduplication and `clampIndex`.
+//!
+//! Tier order (each tier picks the "newest matching index"):
+//! 1. **Composite** — candidate has BOTH accountId and emailKey.
+//! 2. **Safe email** — candidate emailKey; ambiguous (2+ distinct accountIds
+//!    among candidate + matches) ⇒ tier yields nothing (falls through).
+//! 3. **Refresh token** — FAIL-CLOSED: a token match whose accountId/emailKey
+//!    conflicts with the candidate poisons the tier (never merge two
+//!    identities across a shared token); 2+ token matches with an anonymous
+//!    candidate ⇒ ambiguous.
+//! 4. **Unique accountId** — exactly one account with that id; without a
+//!    candidate emailKey this tier only runs when
+//!    `allow_unique_account_id_fallback_without_email` is set.
+//!
+//! Deduplication runs to FIXPOINT (gotcha 6): a newest-wins merge can install
+//! an account that duplicates an earlier survivor through a different tier.
+
+use crate::identity::{AccountIdentityLike, AccountIdentityRef, to_account_identity_ref};
+use crate::match_utils::{
+    AccountRecency, collect_distinct_identity_values, find_newest_matching_index,
+    newest_prefers_candidate,
+};
+
+/// Options for [`find_matching_account_index`] (TS `AccountMatchOptions`).
+#[derive(Clone, Copy, Debug, Default)]
+pub struct AccountMatchOptions {
+    pub allow_unique_account_id_fallback_without_email: bool,
+}
+
+/// Candidate shape for [`resolve_account_selection_index`] and the matcher —
+/// the TS inline `{accountId?, email?, refreshToken?}` object built by
+/// `normalizeAccountStorage` from raw (pre-validation) account values.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AccountSelectionCandidate {
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub refresh_token: Option<String>,
+}
+
+impl AccountIdentityLike for AccountSelectionCandidate {
+    fn identity_account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+    fn identity_email(&self) -> Option<&str> {
+        self.email.as_deref()
+    }
+    fn identity_refresh_token(&self) -> Option<&str> {
+        self.refresh_token.as_deref()
+    }
+}
+
+fn find_newest_ref_matching_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    predicate: impl Fn(&AccountIdentityRef) -> bool,
+) -> Option<usize> {
+    find_newest_matching_index(
+        accounts,
+        |account| to_account_identity_ref(account),
+        predicate,
+        |current, candidate| newest_prefers_candidate(current, candidate),
+    )
+}
+
+fn find_composite_account_match_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate_ref: &AccountIdentityRef,
+) -> Option<usize> {
+    let (Some(account_id), Some(email_key)) =
+        (&candidate_ref.account_id, &candidate_ref.email_key)
+    else {
+        return None;
+    };
+    find_newest_ref_matching_index(accounts, |ref_| {
+        ref_.account_id.as_deref() == Some(account_id.as_str())
+            && ref_.email_key.as_deref() == Some(email_key.as_str())
+    })
+}
+
+fn find_safe_email_match_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate_ref: &AccountIdentityRef,
+) -> Option<usize> {
+    let email_key = candidate_ref.email_key.as_deref()?;
+
+    let mut email_account_ids: Vec<Option<String>> = vec![candidate_ref.account_id.clone()];
+    let mut found_any = false;
+    for account in accounts {
+        let ref_ = to_account_identity_ref(account);
+        if ref_.email_key.as_deref() != Some(email_key) {
+            continue;
+        }
+        found_any = true;
+        email_account_ids.push(ref_.account_id);
+    }
+
+    if !found_any {
+        return None;
+    }
+    let distinct =
+        collect_distinct_identity_values(email_account_ids.iter().map(|value| value.as_deref()));
+    if distinct.len() > 1 {
+        return None;
+    }
+
+    find_newest_ref_matching_index(accounts, |ref_| {
+        ref_.email_key.as_deref() == Some(email_key)
+    })
+}
+
+fn find_compatible_refresh_token_match_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate_ref: &AccountIdentityRef,
+) -> Option<usize> {
+    let refresh_token = candidate_ref.refresh_token.as_deref()?;
+    let mut matching_index: Option<usize> = None;
+
+    for (i, account) in accounts.iter().enumerate() {
+        let ref_ = to_account_identity_ref(account);
+        if ref_.refresh_token.as_deref() != Some(refresh_token) {
+            continue;
+        }
+        // FAIL-CLOSED: both sides carry an accountId (or emailKey) and they
+        // differ ⇒ never merge two identities across a shared token.
+        let account_id_conflict = matches!(
+            (&candidate_ref.account_id, &ref_.account_id),
+            (Some(candidate_id), Some(account_id)) if candidate_id != account_id
+        );
+        let email_conflict = matches!(
+            (&candidate_ref.email_key, &ref_.email_key),
+            (Some(candidate_email), Some(account_email)) if candidate_email != account_email
+        );
+        if account_id_conflict || email_conflict {
+            return None;
+        }
+        // Anonymous candidate (no id, no email) with 2+ token matches ⇒
+        // ambiguous.
+        if matching_index.is_some()
+            && candidate_ref.account_id.is_none()
+            && candidate_ref.email_key.is_none()
+        {
+            return None;
+        }
+        match matching_index {
+            None => matching_index = Some(i),
+            Some(current_index) => {
+                if newest_prefers_candidate(&accounts[current_index], account) {
+                    matching_index = Some(i);
+                }
+            }
+        }
+    }
+
+    matching_index
+}
+
+fn find_unique_account_id_match_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate_ref: &AccountIdentityRef,
+    options: AccountMatchOptions,
+) -> Option<usize> {
+    let account_id = candidate_ref.account_id.as_deref()?;
+    if candidate_ref.email_key.is_none()
+        && !options.allow_unique_account_id_fallback_without_email
+    {
+        return None;
+    }
+    let mut matching_index: Option<usize> = None;
+    let mut matching_email_key: Option<String> = None;
+
+    for (i, account) in accounts.iter().enumerate() {
+        let ref_ = to_account_identity_ref(account);
+        if ref_.account_id.as_deref() != Some(account_id) {
+            continue;
+        }
+        if matching_index.is_some() {
+            return None;
+        }
+        matching_index = Some(i);
+        matching_email_key = ref_.email_key;
+    }
+
+    if matching_index.is_some()
+        && let (Some(matching_email), Some(candidate_email)) =
+            (&matching_email_key, &candidate_ref.email_key)
+        && matching_email != candidate_email
+    {
+        return None;
+    }
+
+    matching_index
+}
+
+/// TS `findMatchingAccountIndex(accounts, candidate, options)` with the
+/// candidate expressed as a pre-normalized [`AccountIdentityRef`].
+pub fn find_matching_account_index_by_ref<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate_ref: &AccountIdentityRef,
+    options: AccountMatchOptions,
+) -> Option<usize> {
+    if let Some(by_composite) = find_composite_account_match_index(accounts, candidate_ref) {
+        return Some(by_composite);
+    }
+
+    if let Some(by_email) = find_safe_email_match_index(accounts, candidate_ref) {
+        return Some(by_email);
+    }
+
+    if candidate_ref.refresh_token.is_some()
+        && let Some(by_refresh) = find_compatible_refresh_token_match_index(accounts, candidate_ref)
+    {
+        return Some(by_refresh);
+    }
+
+    find_unique_account_id_match_index(accounts, candidate_ref, options)
+}
+
+/// TS `findMatchingAccountIndex` — candidate as an account-like value.
+pub fn find_matching_account_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate: &impl AccountIdentityLike,
+    options: AccountMatchOptions,
+) -> Option<usize> {
+    let candidate_ref = to_account_identity_ref(candidate);
+    find_matching_account_index_by_ref(accounts, &candidate_ref, options)
+}
+
+/// TS `reconcilePinnedAccountIndex` (#474) — re-resolve a manual pin after
+/// the account list changes. Returns the pinned account's new index, or
+/// `None` when it no longer resolves (pin cleared, never left dangling).
+pub fn reconcile_pinned_account_index<T: AccountIdentityLike + AccountRecency>(
+    pinned_account: Option<&impl AccountIdentityLike>,
+    next_accounts: &[T],
+) -> Option<usize> {
+    let pinned_account = pinned_account?;
+    find_matching_account_index(next_accounts, pinned_account, AccountMatchOptions::default())
+}
+
+/// Numeric types accepted as the `resolveAccountSelectionIndex` fallback —
+/// the TS `fallbackIndex` is a JS number; both integer and float call sites
+/// clamp with the exact `clampIndex` semantics (NaN ⇒ 0, trunc, bounds).
+pub trait SelectionFallbackIndex {
+    fn clamp_to(self, length: usize) -> usize;
+}
+
+impl SelectionFallbackIndex for f64 {
+    fn clamp_to(self, length: usize) -> usize {
+        clamp_index(self, length)
+    }
+}
+
+impl SelectionFallbackIndex for i64 {
+    fn clamp_to(self, length: usize) -> usize {
+        clamp_index_i64(self, length)
+    }
+}
+
+impl SelectionFallbackIndex for i32 {
+    fn clamp_to(self, length: usize) -> usize {
+        clamp_index_i64(i64::from(self), length)
+    }
+}
+
+impl SelectionFallbackIndex for usize {
+    fn clamp_to(self, length: usize) -> usize {
+        clamp_index_i64(i64::try_from(self).unwrap_or(i64::MAX), length)
+    }
+}
+
+/// TS `resolveAccountSelectionIndex` — follow a previously-selected account
+/// by identity (unique-accountId fallback enabled), else clamp the fallback
+/// index.
+pub fn resolve_account_selection_index<T: AccountIdentityLike + AccountRecency>(
+    accounts: &[T],
+    candidate: &impl AccountIdentityLike,
+    fallback_index: impl SelectionFallbackIndex,
+) -> usize {
+    if accounts.is_empty() {
+        return 0;
+    }
+    if let Some(matched_index) = find_matching_account_index(
+        accounts,
+        candidate,
+        AccountMatchOptions {
+            allow_unique_account_id_fallback_without_email: true,
+        },
+    ) {
+        return matched_index;
+    }
+    fallback_index.clamp_to(accounts.len())
+}
+
+fn deduplicate_accounts_by_identity_pass<T>(accounts: &[T]) -> Vec<T>
+where
+    T: Clone + AccountIdentityLike + AccountRecency,
+{
+    let mut deduplicated: Vec<T> = Vec::new();
+    for account in accounts {
+        match find_matching_account_index(&deduplicated, account, AccountMatchOptions::default())
+        {
+            None => deduplicated.push(account.clone()),
+            Some(existing_index) => {
+                // Position preserved; newest content wins (candidate wins
+                // exact ties).
+                if newest_prefers_candidate(&deduplicated[existing_index], account) {
+                    deduplicated[existing_index] = account.clone();
+                }
+            }
+        }
+    }
+    deduplicated
+}
+
+fn deduplicate_accounts_by_identity<T>(accounts: &[T]) -> Vec<T>
+where
+    T: Clone + AccountIdentityLike + AccountRecency,
+{
+    // A single pass is not a fixpoint: a newest-wins merge can replace a kept
+    // entry with an account that itself duplicates an earlier survivor
+    // through a different matching tier. Re-run until stable; every merge
+    // strictly shrinks the array, so this terminates after at most
+    // `accounts.len()` passes.
+    let mut current = deduplicate_accounts_by_identity_pass(accounts);
+    loop {
+        let next = deduplicate_accounts_by_identity_pass(&current);
+        if next.len() == current.len() {
+            return next;
+        }
+        current = next;
+    }
+}
+
+/// TS `deduplicateAccounts` — removes duplicate accounts, keeping the most
+/// recently used entry for each safely matched identity. Runs to fixpoint.
+pub fn deduplicate_accounts<T>(accounts: &[T]) -> Vec<T>
+where
+    T: Clone + AccountIdentityLike + AccountRecency,
+{
+    deduplicate_accounts_by_identity(accounts)
+}
+
+/// TS `deduplicateAccountsByEmail` — alias of [`deduplicate_accounts`].
+pub fn deduplicate_accounts_by_email<T>(accounts: &[T]) -> Vec<T>
+where
+    T: Clone + AccountIdentityLike + AccountRecency,
+{
+    deduplicate_accounts_by_identity(accounts)
+}
+
+/// TS `clampIndex` (record-utils) over a float index: `length <= 0` ⇒ 0;
+/// `NaN` ⇒ 0 (corrupt `activeIndex` must not propagate — gotcha 32); else
+/// `max(0, min(trunc(index), length - 1))`. ±Infinity clamp correctly.
+pub fn clamp_index(index: f64, length: usize) -> usize {
+    if length == 0 {
+        return 0;
+    }
+    if index.is_nan() {
+        return 0;
+    }
+    let truncated = index.trunc();
+    let max_index = (length - 1) as f64;
+    let clamped = truncated.max(0.0).min(max_index);
+    clamped as usize
+}
+
+/// [`clamp_index`] for integer inputs.
+pub fn clamp_index_i64(index: i64, length: usize) -> usize {
+    if length == 0 {
+        return 0;
+    }
+    let max_index = (length - 1) as i64;
+    index.clamp(0, max_index) as usize
+}
+
+// ============================================================================
+// Tests (ported from the matching/dedup suites of test/storage.test.ts)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+
+    fn account(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        refresh_token: &str,
+        last_used: i64,
+        added_at: i64,
+    ) -> AccountMetadataV3 {
+        let mut a = AccountMetadataV3::new(refresh_token, added_at, last_used);
+        a.account_id = account_id.map(str::to_string);
+        a.email = email.map(str::to_string);
+        a
+    }
+
+    fn candidate(
+        account_id: Option<&str>,
+        email: Option<&str>,
+        refresh_token: Option<&str>,
+    ) -> AccountIdentityRef {
+        AccountIdentityRef::from_parts(account_id, email, refresh_token)
+    }
+
+    #[test]
+    fn composite_tier_requires_both_id_and_email() {
+        let accounts = vec![
+            account(Some("acc_1"), Some("a@b.com"), "rt_1", 10, 1),
+            account(Some("acc_2"), Some("a@b.com"), "rt_2", 99, 1),
+        ];
+        // Composite match beats the (ambiguous) email tier.
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(Some("acc_1"), Some("A@B.com"), None),
+            AccountMatchOptions::default(),
+        );
+        assert_eq!(index, Some(0));
+    }
+
+    #[test]
+    fn safe_email_tier_matches_when_account_ids_agree() {
+        let accounts = vec![
+            account(None, Some("a@b.com"), "rt_1", 10, 1),
+            account(Some("acc_1"), Some("a@b.com"), "rt_2", 20, 1),
+        ];
+        // candidate id acc_1; distinct set {acc_1} => safe; newest wins.
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(Some("acc_1"), Some("a@b.com"), None),
+            AccountMatchOptions::default(),
+        );
+        assert_eq!(index, Some(1));
+    }
+
+    #[test]
+    fn safe_email_tier_is_ambiguous_with_two_distinct_account_ids() {
+        let accounts = vec![
+            account(Some("acc_1"), Some("a@b.com"), "rt_1", 10, 1),
+            account(Some("acc_2"), Some("a@b.com"), "rt_2", 20, 1),
+        ];
+        // Ambiguous email + no other tier applies (unique-id tier: candidate
+        // has emailKey, id acc_3 matches nothing) ⇒ None.
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(Some("acc_3"), Some("a@b.com"), None),
+            AccountMatchOptions::default(),
+        );
+        assert_eq!(index, None);
+    }
+
+    #[test]
+    fn refresh_tier_is_fail_closed_on_conflicting_identity() {
+        let accounts = vec![account(Some("acc_1"), Some("a@b.com"), "rt_shared", 10, 1)];
+        // Same token, DIFFERENT accountId — must not merge; the unique-id
+        // tier also finds nothing (acc_2 not present) ⇒ None.
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(Some("acc_2"), None, Some("rt_shared")),
+            AccountMatchOptions {
+                allow_unique_account_id_fallback_without_email: true,
+            },
+        );
+        assert_eq!(index, None);
+    }
+
+    #[test]
+    fn refresh_tier_ambiguous_for_anonymous_candidate_with_two_matches() {
+        let accounts = vec![
+            account(Some("acc_1"), None, "rt_shared", 10, 1),
+            account(Some("acc_2"), None, "rt_shared", 20, 1),
+        ];
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(None, None, Some("rt_shared")),
+            AccountMatchOptions::default(),
+        );
+        assert_eq!(index, None);
+    }
+
+    #[test]
+    fn refresh_tier_matches_newest_compatible_account() {
+        let accounts = vec![
+            account(None, None, "rt_shared", 10, 1),
+            account(Some("acc_1"), None, "rt_shared", 20, 1),
+        ];
+        let index = find_matching_account_index_by_ref(
+            &accounts,
+            &candidate(Some("acc_1"), None, Some("rt_shared")),
+            AccountMatchOptions::default(),
+        );
+        assert_eq!(index, Some(1));
+    }
+
+    #[test]
+    fn unique_account_id_tier_requires_opt_in_without_email() {
+        let accounts = vec![account(Some("acc_1"), None, "rt_1", 10, 1)];
+        let c = candidate(Some("acc_1"), None, None);
+        assert_eq!(
+            find_matching_account_index_by_ref(&accounts, &c, AccountMatchOptions::default()),
+            None
+        );
+        assert_eq!(
+            find_matching_account_index_by_ref(
+                &accounts,
+                &c,
+                AccountMatchOptions {
+                    allow_unique_account_id_fallback_without_email: true,
+                },
+            ),
+            Some(0)
+        );
+    }
+
+    #[test]
+    fn unique_account_id_tier_rejects_duplicates_and_email_mismatch() {
+        let duplicated = vec![
+            account(Some("acc_1"), None, "rt_1", 10, 1),
+            account(Some("acc_1"), None, "rt_2", 20, 1),
+        ];
+        assert_eq!(
+            find_matching_account_index_by_ref(
+                &duplicated,
+                &candidate(Some("acc_1"), None, None),
+                AccountMatchOptions {
+                    allow_unique_account_id_fallback_without_email: true,
+                },
+            ),
+            None
+        );
+        let mismatch = vec![account(Some("acc_1"), Some("x@y.z"), "rt_1", 10, 1)];
+        assert_eq!(
+            find_matching_account_index_by_ref(
+                &mismatch,
+                &candidate(Some("acc_1"), Some("other@y.z"), None),
+                AccountMatchOptions::default(),
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn resolve_selection_index_clamps_fallback() {
+        let accounts = vec![
+            account(Some("acc_1"), None, "rt_1", 10, 1),
+            account(Some("acc_2"), None, "rt_2", 10, 1),
+        ];
+        // No match ⇒ clamp fallback.
+        assert_eq!(
+            resolve_account_selection_index(&accounts, &candidate(None, None, None), 99),
+            1
+        );
+        assert_eq!(
+            resolve_account_selection_index(&accounts, &candidate(None, None, None), -3),
+            0
+        );
+        // Empty ⇒ 0.
+        let empty: Vec<AccountMetadataV3> = Vec::new();
+        assert_eq!(
+            resolve_account_selection_index(&empty, &candidate(Some("acc_1"), None, None), 5),
+            0
+        );
+        // Identity match wins over fallback (unique-id fallback enabled).
+        assert_eq!(
+            resolve_account_selection_index(&accounts, &candidate(Some("acc_2"), None, None), 0),
+            1
+        );
+    }
+
+    #[test]
+    fn reconcile_pinned_account_index_follows_identity_or_clears() {
+        let accounts = vec![
+            account(Some("acc_1"), Some("a@b.com"), "rt_1", 10, 1),
+            account(Some("acc_2"), Some("c@d.com"), "rt_2", 10, 1),
+        ];
+        let pinned = account(Some("acc_2"), Some("c@d.com"), "rt_2", 10, 1);
+        assert_eq!(
+            reconcile_pinned_account_index(Some(&pinned), &accounts),
+            Some(1)
+        );
+        let gone = account(Some("acc_9"), Some("z@z.com"), "rt_9", 10, 1);
+        assert_eq!(reconcile_pinned_account_index(Some(&gone), &accounts), None);
+        assert_eq!(
+            reconcile_pinned_account_index(None::<&AccountMetadataV3>, &accounts),
+            None
+        );
+    }
+
+    #[test]
+    fn dedupe_keeps_position_and_newest_content() {
+        let accounts = vec![
+            account(Some("acc_1"), Some("a@b.com"), "rt_old", 10, 1),
+            account(Some("acc_2"), Some("c@d.com"), "rt_2", 10, 1),
+            account(Some("acc_1"), Some("a@b.com"), "rt_new", 20, 2),
+        ];
+        let deduped = deduplicate_accounts(&accounts);
+        assert_eq!(deduped.len(), 2);
+        // Slot 0 keeps the FIRST match's position but the newest content.
+        assert_eq!(deduped[0].refresh_token, "rt_new");
+        assert_eq!(deduped[1].account_id.as_deref(), Some("acc_2"));
+    }
+
+    #[test]
+    fn dedupe_ties_prefer_the_later_candidate() {
+        // Same identity via the shared refresh token; identical timestamps —
+        // `selectNewestAccount` ties go to the candidate (>=), so the LATER
+        // entry's content wins the slot.
+        let mut first = account(Some("acc_1"), None, "rt_shared", 10, 5);
+        first.account_label = Some("first".to_string());
+        let mut second = account(Some("acc_1"), None, "rt_shared", 10, 5);
+        second.account_label = Some("second".to_string());
+        let deduped = deduplicate_accounts(&[first, second]);
+        assert_eq!(deduped.len(), 1);
+        assert_eq!(deduped[0].account_label.as_deref(), Some("second"));
+    }
+
+    #[test]
+    fn dedupe_does_not_merge_bare_account_ids_without_email() {
+        // Default options: the unique-accountId tier requires the opt-in when
+        // the candidate has no email — dedupe never merges on id alone.
+        let accounts = vec![
+            account(Some("acc_1"), None, "rt_a", 10, 5),
+            account(Some("acc_1"), None, "rt_b", 10, 5),
+        ];
+        assert_eq!(deduplicate_accounts(&accounts).len(), 2);
+    }
+
+    #[test]
+    fn dedupe_merges_chained_identities_via_shared_token() {
+        let a = account(None, Some("a@b.com"), "rt_1", 10, 1);
+        let b = account(Some("acc_1"), None, "rt_1", 15, 1);
+        let c = account(Some("acc_1"), Some("a@b.com"), "rt_1", 20, 2);
+        let deduped = deduplicate_accounts(&[a, b, c]);
+        assert_eq!(deduped.len(), 1);
+        assert_eq!(deduped[0].last_used, 20);
+        assert_eq!(deduped[0].email.as_deref(), Some("a@b.com"));
+    }
+
+    #[test]
+    fn dedupe_runs_to_fixpoint_across_tiers() {
+        // Pass 1: Z merges into Y's slot via the safe-email tier, installing
+        // an account (acc_1 + email) that now duplicates the earlier survivor
+        // X (acc_1, no email) through the unique-accountId tier. Only the
+        // SECOND pass collapses them — a single pass would return 2 entries.
+        let x = account(Some("acc_1"), None, "rt_x", 30, 1);
+        let y = account(None, Some("e@f.com"), "rt_y", 10, 1);
+        let z = account(Some("acc_1"), Some("e@f.com"), "rt_z", 20, 2);
+        let deduped = deduplicate_accounts(&[x, y, z]);
+        assert_eq!(deduped.len(), 1);
+        // X is the newest (lastUsed 30) so its content survives the final
+        // merge.
+        assert_eq!(deduped[0].refresh_token, "rt_x");
+        assert_eq!(deduped[0].last_used, 30);
+    }
+
+    #[test]
+    fn dedupe_alias_matches() {
+        let accounts = vec![account(Some("acc_1"), None, "rt_1", 10, 1)];
+        assert_eq!(deduplicate_accounts_by_email(&accounts).len(), 1);
+    }
+
+    #[test]
+    fn clamp_index_handles_nan_and_bounds() {
+        assert_eq!(clamp_index(f64::NAN, 5), 0);
+        assert_eq!(clamp_index(3.9, 5), 3);
+        assert_eq!(clamp_index(-2.0, 5), 0);
+        assert_eq!(clamp_index(99.0, 5), 4);
+        assert_eq!(clamp_index(f64::INFINITY, 5), 4);
+        assert_eq!(clamp_index(f64::NEG_INFINITY, 5), 0);
+        assert_eq!(clamp_index(2.0, 0), 0);
+        assert_eq!(clamp_index_i64(99, 3), 2);
+        assert_eq!(clamp_index_i64(-1, 3), 0);
+        assert_eq!(clamp_index_i64(1, 0), 0);
+    }
+}
diff --git a/crates/storage/src/migrations.rs b/crates/storage/src/migrations.rs
new file mode 100644
index 000000000..f70cdbb84
--- /dev/null
+++ b/crates/storage/src/migrations.rs
@@ -0,0 +1,167 @@
+//! Port of `lib/storage/migrations.ts` — V1 → V3 account-storage migration.
+//!
+//! Behavior source: spec 02 §5.2 / gotchas 4–5:
+//! - The scalar `rateLimitResetTime` converts into the per-family map ONLY
+//!   when it is a number strictly greater than `now` — expired reset times
+//!   are dropped; a future value fans out to ALL 5 model families with the
+//!   SAME timestamp.
+//! - `activeIndexByFamily` is initialized to the V1 `activeIndex` for every
+//!   family.
+
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::utils::now_ms;
+
+use crate::public_types::{
+    AccountMetadataV3, AccountStorageV1, AccountStorageV3, ActiveIndexByFamily, RateLimitStateV3,
+};
+
+/// Fan a V1 scalar reset time out to all 5 model families — `None` when the
+/// value is absent or not in the future (expired values are dropped).
+/// Shared with the value-based legacy normalizer in `crate::normalize`.
+pub(crate) fn fan_out_reset_time(reset_time: Option<i64>, now: i64) -> Option<RateLimitStateV3> {
+    let reset_time = reset_time?;
+    if reset_time <= now {
+        return None;
+    }
+    let mut map = RateLimitStateV3::new();
+    for family in MODEL_FAMILIES {
+        map.insert(family.as_str(), reset_time);
+    }
+    Some(map)
+}
+
+/// `migrateV1ToV3(v1)` with an injectable `now` (the TS helper reads
+/// `Date.now()` internally — see [`migrate_v1_to_v3`]).
+pub fn migrate_v1_to_v3_at(v1: &AccountStorageV1, now: i64) -> AccountStorageV3 {
+    let accounts: Vec<AccountMetadataV3> = v1
+        .accounts
+        .iter()
+        .map(|account| AccountMetadataV3 {
+            account_id: account.account_id.clone(),
+            account_id_source: account.account_id_source,
+            account_label: account.account_label.clone(),
+            email: account.email.clone(),
+            refresh_token: account.refresh_token.clone(),
+            access_token: account.access_token.clone(),
+            expires_at: account.expires_at,
+            enabled: account.enabled,
+            added_at: account.added_at,
+            last_used: account.last_used,
+            last_switch_reason: account.last_switch_reason,
+            rate_limit_reset_times: fan_out_reset_time(account.rate_limit_reset_time, now),
+            cooling_down_until: account.cooling_down_until,
+            cooldown_reason: account.cooldown_reason,
+            workspaces: None,
+            current_workspace_index: None,
+        })
+        .collect();
+
+    let mut by_family = ActiveIndexByFamily::default();
+    for family in MODEL_FAMILIES {
+        by_family.set(family, Some(v1.active_index));
+    }
+
+    AccountStorageV3 {
+        version: Default::default(),
+        accounts,
+        active_index: v1.active_index,
+        active_index_by_family: Some(by_family),
+        pinned_account_index: None,
+        affinity_generation: None,
+    }
+}
+
+/// `migrateV1ToV3(v1)` — wall-clock variant (`Date.now()` parity).
+pub fn migrate_v1_to_v3(v1: &AccountStorageV1) -> AccountStorageV3 {
+    migrate_v1_to_v3_at(v1, now_ms())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::ModelFamily;
+    use serde_json::json;
+
+    fn v1_with_reset(reset_time: Option<i64>) -> AccountStorageV1 {
+        let mut value = json!({
+            "version": 1,
+            "accounts": [{
+                "accountId": "acc_1",
+                "email": "a@b.com",
+                "refreshToken": "rt_1",
+                "addedAt": 100,
+                "lastUsed": 200,
+            }],
+            "activeIndex": 0,
+        });
+        if let Some(reset) = reset_time {
+            value["accounts"][0]["rateLimitResetTime"] = json!(reset);
+        }
+        serde_json::from_value(value).expect("valid v1 storage")
+    }
+
+    #[test]
+    fn fans_a_future_reset_time_to_all_five_families() {
+        let now = 1_000_000;
+        let migrated = migrate_v1_to_v3_at(&v1_with_reset(Some(now + 60_000)), now);
+        let map = migrated.accounts[0]
+            .rate_limit_reset_times
+            .as_ref()
+            .expect("map present");
+        assert_eq!(map.len(), 5);
+        for family in MODEL_FAMILIES {
+            assert_eq!(map.get(family.as_str()), Some(now + 60_000), "{family:?}");
+        }
+        // Key order = MODEL_FAMILIES order.
+        let keys: Vec<&str> = map.keys().collect();
+        assert_eq!(
+            keys,
+            vec!["gpt-5-codex", "codex-max", "codex", "gpt-5.2", "gpt-5.1"]
+        );
+    }
+
+    #[test]
+    fn drops_expired_or_exactly_now_reset_times() {
+        let now = 1_000_000;
+        let expired = migrate_v1_to_v3_at(&v1_with_reset(Some(now - 1)), now);
+        assert!(expired.accounts[0].rate_limit_reset_times.is_none());
+        // `> now` is strict: a value equal to now is dropped too.
+        let boundary = migrate_v1_to_v3_at(&v1_with_reset(Some(now)), now);
+        assert!(boundary.accounts[0].rate_limit_reset_times.is_none());
+        let missing = migrate_v1_to_v3_at(&v1_with_reset(None), now);
+        assert!(missing.accounts[0].rate_limit_reset_times.is_none());
+    }
+
+    #[test]
+    fn initializes_every_family_index_to_the_v1_active_index() {
+        let mut v1 = v1_with_reset(None);
+        v1.active_index = 3;
+        let migrated = migrate_v1_to_v3_at(&v1, 0);
+        assert_eq!(migrated.active_index, 3);
+        let by_family = migrated.active_index_by_family.expect("map present");
+        for family in [
+            ModelFamily::Gpt5Codex,
+            ModelFamily::CodexMax,
+            ModelFamily::Codex,
+            ModelFamily::Gpt5_2,
+            ModelFamily::Gpt5_1,
+        ] {
+            assert_eq!(by_family.get(family), Some(3));
+        }
+    }
+
+    #[test]
+    fn copies_all_metadata_fields_without_workspaces() {
+        let migrated = migrate_v1_to_v3_at(&v1_with_reset(None), 0);
+        let account = &migrated.accounts[0];
+        assert_eq!(account.account_id.as_deref(), Some("acc_1"));
+        assert_eq!(account.email.as_deref(), Some("a@b.com"));
+        assert_eq!(account.refresh_token, "rt_1");
+        assert_eq!(account.added_at, 100);
+        assert_eq!(account.last_used, 200);
+        assert!(account.workspaces.is_none());
+        assert!(account.current_workspace_index.is_none());
+        assert_eq!(migrated.pinned_account_index, None);
+        assert_eq!(migrated.affinity_generation, None);
+    }
+}
diff --git a/crates/storage/src/misc.rs b/crates/storage/src/misc.rs
new file mode 100644
index 000000000..7450f011e
--- /dev/null
+++ b/crates/storage/src/misc.rs
@@ -0,0 +1,319 @@
+//! Port of the small storage utility modules:
+//! `lib/storage/record-utils.ts` (`isRecord`), `lib/storage/hash.ts`
+//! (`computeSha256`), `lib/storage/cache-artifacts.ts`
+//! (`isCacheLikeBackupArtifactName`), `lib/storage/gitignore.ts`
+//! (`ensureCodexGitignoreEntry`), `lib/storage/error-hints.ts`
+//! (`formatStorageErrorHint`, `toStorageError`) and
+//! `lib/storage/account-persistence.ts` (`cloneAccountStorageForPersistence`).
+//!
+//! Behavior source: spec 02 §3.9, §17; hint strings are FROZEN.
+//!
+//! (`clampIndex` from record-utils.ts lives in `crate::matching` per the
+//! ARCHITECTURE §6.3 surface split.)
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::code_of;
+use cma_core::logger::create_logger;
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+
+use crate::public_types::{AccountStorageV3, ActiveIndexByFamily};
+
+/// `isRecord(value)` — true for a JSON object (not array, not null).
+pub fn is_record(value: &Value) -> bool {
+    cma_core::utils::is_record(value)
+}
+
+/// `computeSha256(value)` — lowercase sha256 hex of the UTF-8 bytes.
+pub fn compute_sha256(value: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(value.as_bytes());
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        use std::fmt::Write;
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+/// `isCacheLikeBackupArtifactName(name)` — lowercased name contains
+/// `".cache"`.
+pub fn is_cache_like_backup_artifact_name(entry_name: &str) -> bool {
+    entry_name.to_lowercase().contains(".cache")
+}
+
+// ---------------------------------------------------------------------------
+// .gitignore side-effect (spec 02 §3.9)
+// ---------------------------------------------------------------------------
+
+/// `ensureCodexGitignoreEntry` — when a candidate project root (the explicit
+/// `currentProjectRoot`, else the storage dir's grandparent) contains `.git`,
+/// append `".codex/\n"` to its `.gitignore` unless one of the four accepted
+/// forms is already present. Failures are logged as warnings, never fatal.
+pub async fn ensure_codex_gitignore_entry(storage_path: &Path, current_project_root: Option<&Path>) {
+    let log = create_logger("storage");
+    let config_dir = storage_path.parent().map(Path::to_path_buf);
+    let inferred_project_root = config_dir.as_deref().and_then(Path::parent).map(Path::to_path_buf);
+
+    let candidate_roots: Vec<PathBuf> = [
+        current_project_root.map(Path::to_path_buf),
+        inferred_project_root,
+    ]
+    .into_iter()
+    .flatten()
+    .filter(|root| !root.as_os_str().is_empty())
+    .collect();
+
+    let Some(project_root) = candidate_roots
+        .into_iter()
+        .find(|root| root.join(".git").exists())
+    else {
+        return;
+    };
+
+    let gitignore_path = project_root.join(".gitignore");
+    let result: io::Result<()> = (|| {
+        let mut content = String::new();
+        if gitignore_path.exists() {
+            let bytes = std::fs::read(&gitignore_path)?;
+            content = String::from_utf8_lossy(&bytes).into_owned();
+            let has_entry = content.split('\n').map(str::trim).any(|line| {
+                line == ".codex" || line == ".codex/" || line == "/.codex" || line == "/.codex/"
+            });
+            if has_entry {
+                return Ok(());
+            }
+        }
+        let new_content = if content.ends_with('\n') || content.is_empty() {
+            content
+        } else {
+            format!("{content}\n")
+        };
+        std::fs::write(&gitignore_path, format!("{new_content}.codex/\n"))?;
+        log.debug(
+            "Added .codex to .gitignore",
+            Some(&json!({ "path": gitignore_path.to_string_lossy() })),
+        );
+        Ok(())
+    })();
+    if let Err(error) = result {
+        log.warn(
+            "Failed to update .gitignore",
+            Some(&json!({ "error": error.to_string() })),
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Error hints (spec 02 §17 — strings FROZEN)
+// ---------------------------------------------------------------------------
+
+/// The errno-code half of `formatStorageErrorHint` — the TS helper switches
+/// on `error.code || "UNKNOWN"`.
+pub fn format_storage_error_hint_for_code(code: Option<&str>, path: &str) -> String {
+    let is_windows = cfg!(windows);
+    match code.unwrap_or("UNKNOWN") {
+        "EACCES" | "EPERM" => {
+            if is_windows {
+                format!(
+                    "Permission denied writing to {path}. Check antivirus exclusions for this folder. Ensure you have write permissions."
+                )
+            } else {
+                format!(
+                    "Permission denied writing to {path}. Check folder permissions. Try: chmod 755 ~/.codex"
+                )
+            }
+        }
+        "EBUSY" => format!(
+            "File is locked at {path}. The file may be open in another program. Close any editors or processes accessing it."
+        ),
+        "ENOENT" => format!("Path does not exist: {path}. Create the parent folder and try again."),
+        "ENOSPC" => format!("Disk is full. Free up space and try again. Path: {path}"),
+        _ => {
+            if is_windows {
+                format!(
+                    "Failed to write to {path}. Check folder permissions and ensure path contains no special characters."
+                )
+            } else {
+                format!("Failed to write to {path}. Check folder permissions and disk space.")
+            }
+        }
+    }
+}
+
+/// `formatStorageErrorHint(error, path)` for `io::Error`s (code extracted via
+/// the shared errno shim).
+pub fn format_storage_error_hint(error: &io::Error, path: &str) -> String {
+    format_storage_error_hint_for_code(code_of(error), path)
+}
+
+/// `toStorageError(message, error, path)` — wrap an arbitrary storage failure
+/// in a `StorageError` with a derived hint (`code = error.code || "UNKNOWN"`).
+pub fn to_storage_error(message: impl Into<String>, error: io::Error, path: &str) -> CodexError {
+    let code = code_of(&error).unwrap_or("UNKNOWN").to_string();
+    let hint = format_storage_error_hint(&error, path);
+    CodexError::storage(message, code, path, hint, Some(Box::new(error)))
+}
+
+// ---------------------------------------------------------------------------
+// Persistence clone (account-persistence.ts)
+// ---------------------------------------------------------------------------
+
+/// `cloneAccountStorageForPersistence(storage)` — deep clone used by the
+/// combined account+flagged transaction rollback path. Always yields
+/// `version: 3`, cloned accounts, a finite `activeIndex` (else 0), an
+/// `activeIndexByFamily` object (empty when missing — the TS built `{}`), and
+/// preserves the manual pin (#474) / affinity generation when numeric.
+pub fn clone_account_storage_for_persistence(
+    storage: Option<&AccountStorageV3>,
+) -> AccountStorageV3 {
+    let mut cloned = AccountStorageV3::empty();
+    if let Some(storage) = storage {
+        cloned.accounts = storage.accounts.clone();
+        // i64 is always finite; the TS finite check only guarded NaN floats.
+        cloned.active_index = storage.active_index;
+        cloned.active_index_by_family = Some(
+            storage
+                .active_index_by_family
+                .clone()
+                .unwrap_or_else(ActiveIndexByFamily::default),
+        );
+        cloned.pinned_account_index = storage.pinned_account_index;
+        cloned.affinity_generation = storage.affinity_generation;
+    } else {
+        cloned.active_index_by_family = Some(ActiveIndexByFamily::default());
+    }
+    cloned
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::public_types::AccountMetadataV3;
+
+    #[test]
+    fn compute_sha256_matches_known_vector() {
+        // echo -n "hello" | sha256sum
+        assert_eq!(
+            compute_sha256("hello"),
+            "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+        );
+        assert_eq!(
+            compute_sha256(""),
+            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        );
+    }
+
+    #[test]
+    fn cache_like_names_are_detected_case_insensitively() {
+        assert!(is_cache_like_backup_artifact_name("a.json.CACHE.bak".to_lowercase().as_str()));
+        assert!(is_cache_like_backup_artifact_name("accounts.json.Cache"));
+        assert!(is_cache_like_backup_artifact_name("x.cache.1"));
+        assert!(!is_cache_like_backup_artifact_name("accounts.json.bak"));
+        assert!(!is_cache_like_backup_artifact_name("cachefile.json"));
+    }
+
+    #[test]
+    fn is_record_only_accepts_objects() {
+        assert!(is_record(&json!({})));
+        assert!(!is_record(&json!([])));
+        assert!(!is_record(&json!(null)));
+        assert!(!is_record(&json!("x")));
+    }
+
+    #[test]
+    fn hint_strings_are_frozen_per_code() {
+        let p = "/x/accounts.json";
+        let perm = format_storage_error_hint_for_code(Some("EPERM"), p);
+        if cfg!(windows) {
+            assert_eq!(
+                perm,
+                format!(
+                    "Permission denied writing to {p}. Check antivirus exclusions for this folder. Ensure you have write permissions."
+                )
+            );
+        } else {
+            assert_eq!(
+                perm,
+                format!(
+                    "Permission denied writing to {p}. Check folder permissions. Try: chmod 755 ~/.codex"
+                )
+            );
+        }
+        assert_eq!(
+            format_storage_error_hint_for_code(Some("EACCES"), p),
+            perm,
+            "EACCES and EPERM share the hint"
+        );
+        assert_eq!(
+            format_storage_error_hint_for_code(Some("EBUSY"), p),
+            format!(
+                "File is locked at {p}. The file may be open in another program. Close any editors or processes accessing it."
+            )
+        );
+        assert_eq!(
+            format_storage_error_hint_for_code(Some("ENOENT"), p),
+            format!("Path does not exist: {p}. Create the parent folder and try again.")
+        );
+        assert_eq!(
+            format_storage_error_hint_for_code(Some("ENOSPC"), p),
+            format!("Disk is full. Free up space and try again. Path: {p}")
+        );
+        let fallback = format_storage_error_hint_for_code(None, p);
+        if cfg!(windows) {
+            assert_eq!(
+                fallback,
+                format!(
+                    "Failed to write to {p}. Check folder permissions and ensure path contains no special characters."
+                )
+            );
+        } else {
+            assert_eq!(
+                fallback,
+                format!("Failed to write to {p}. Check folder permissions and disk space.")
+            );
+        }
+        // Unrecognized codes fall through to the default branch too.
+        assert_eq!(format_storage_error_hint_for_code(Some("EINVALID"), p), fallback);
+    }
+
+    #[test]
+    fn to_storage_error_extracts_code_and_hint() {
+        let error = cma_core::fs_retry::io_error_with_code("EBUSY", "locked");
+        let wrapped = to_storage_error("Failed to save accounts: locked", error, "/x/a.json");
+        assert_eq!(wrapped.code(), "EBUSY");
+        assert_eq!(wrapped.message(), "Failed to save accounts: locked");
+        assert_eq!(wrapped.path(), Some("/x/a.json"));
+        assert!(wrapped.hint().unwrap().contains("File is locked at /x/a.json"));
+    }
+
+    #[test]
+    fn clone_for_persistence_preserves_pin_and_generation() {
+        let mut storage = AccountStorageV3::empty();
+        storage.accounts.push(AccountMetadataV3::new("rt", 1, 2));
+        storage.active_index = 1;
+        storage.pinned_account_index = Some(1);
+        storage.affinity_generation = Some(7);
+        let cloned = clone_account_storage_for_persistence(Some(&storage));
+        assert_eq!(cloned.accounts.len(), 1);
+        assert_eq!(cloned.active_index, 1);
+        assert_eq!(cloned.pinned_account_index, Some(1));
+        assert_eq!(cloned.affinity_generation, Some(7));
+        // Missing family map becomes an (empty) object — TS built `{}`.
+        assert!(cloned.active_index_by_family.is_some());
+    }
+
+    #[test]
+    fn clone_for_persistence_defaults_on_none() {
+        let cloned = clone_account_storage_for_persistence(None);
+        assert!(cloned.accounts.is_empty());
+        assert_eq!(cloned.active_index, 0);
+        assert_eq!(cloned.pinned_account_index, None);
+        assert_eq!(cloned.affinity_generation, None);
+        assert!(cloned.active_index_by_family.is_some());
+    }
+}
diff --git a/crates/storage/src/named_backups.rs b/crates/storage/src/named_backups.rs
new file mode 100644
index 000000000..8510ac911
--- /dev/null
+++ b/crates/storage/src/named_backups.rs
@@ -0,0 +1,672 @@
+//! Port of `lib/named-backup-export.ts` + `lib/storage/named-backups.ts`
+//! (+ the `named-backup-entry` / `named-backups-entry` wiring from
+//! `lib/storage.ts`) — spec 02 §12.3.
+//!
+//! - [`normalize_named_backup_file_name`]: exact frozen error strings.
+//! - Root containment via realpath ([`assert_within_directory`]): the backup
+//!   root must not be a symlink and its realpath must equal its resolved
+//!   path; candidates are compared through realpath-of-parent + basename.
+//!   Windows comparisons are lowercase/case-insensitive.
+//! - Per-process in-flight export set keyed by the realpath-normalized
+//!   destination; collisions raise the same "File already exists" string as
+//!   the on-disk case (gotcha 34).
+//! - [`get_named_backups`]: mtime DESC, tie by fileName ASC; empty/invalid
+//!   backups skipped silently (debug log only) — gotcha 28.
+
+// `CodexError` is core's frozen error shape (192 bytes); the sibling-crate API
+// contract pins these `Result<_, CodexError>` signatures, so boxing is not an
+// option here.
+#![allow(clippy::result_large_err)]
+
+use std::collections::HashSet;
+use std::io;
+use std::path::{Component, Path, PathBuf};
+use std::sync::Mutex as StdMutex;
+use std::time::UNIX_EPOCH;
+
+use serde_json::json;
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::code_of;
+use cma_core::logger::create_logger;
+
+const BACKUP_EXPORT_DIR_NAME: &str = "backups";
+const BACKUP_FILE_EXTENSION: &str = ".json";
+const BACKUP_INVALID_SUFFIXES: [&str; 2] = [".tmp", ".wal"];
+const BACKUP_PROHIBITED_SUBSTRINGS: [&str; 1] = [".rotate."];
+
+static IN_FLIGHT_NAMED_BACKUP_EXPORTS: StdMutex<Option<HashSet<String>>> = StdMutex::new(None);
+
+fn io_to_codex(error: io::Error) -> CodexError {
+    let mapped = CodexError::new(error.to_string());
+    match code_of(&error) {
+        Some(code) => mapped.with_code(code).with_cause(error),
+        None => mapped.with_cause(error),
+    }
+}
+
+/// `resolvePath` boundary with its frozen `Error` messages surfaced as plain
+/// `CodexError`s, path returned as a String (TS works in strings throughout).
+fn resolve_path_string(path: &str) -> Result<String, CodexError> {
+    match crate::paths::resolve_path(path) {
+        Ok(resolved) => Ok(resolved.to_string_lossy().into_owned()),
+        Err(error) => Err(CodexError::new(error.0)),
+    }
+}
+
+fn storage_path_string() -> String {
+    // PathBuf::from accepts both String and PathBuf — resilient to the
+    // facade's concrete return type while the crate is co-authored.
+    PathBuf::from(crate::facade::get_storage_path())
+        .to_string_lossy()
+        .into_owned()
+}
+
+// ============================================================================
+// Node-flavored path helpers (shared with backup_restore via pub(crate))
+// ============================================================================
+
+/// `path.resolve` analogue: absolute-ize against cwd, then lexically
+/// normalize (collapse `.`/`..`, native separators). No filesystem access.
+pub(crate) fn node_resolve(path: &str) -> String {
+    let p = Path::new(path);
+    let joined: PathBuf = if p.is_absolute() {
+        p.to_path_buf()
+    } else {
+        let cwd = std::env::current_dir().unwrap_or_default();
+        if cfg!(windows) && p.has_root() {
+            // win32 `\foo` resolves onto the cwd's drive.
+            let mut prefixed = PathBuf::new();
+            if let Some(Component::Prefix(prefix)) = cwd.components().next() {
+                prefixed.push(prefix.as_os_str());
+            }
+            prefixed.push(p);
+            prefixed
+        } else {
+            cwd.join(p)
+        }
+    };
+    let mut normalized = PathBuf::new();
+    for component in joined.components() {
+        match component {
+            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
+            Component::RootDir => normalized.push(std::path::MAIN_SEPARATOR_STR),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !matches!(
+                    normalized.components().next_back(),
+                    None | Some(Component::Prefix(_)) | Some(Component::RootDir)
+                ) {
+                    normalized.pop();
+                }
+            }
+            Component::Normal(part) => normalized.push(part),
+        }
+    }
+    normalized.to_string_lossy().into_owned()
+}
+
+/// `path.isAbsolute` analogue.
+pub(crate) fn is_absolute_path(path: &str) -> bool {
+    if cfg!(windows) {
+        Path::new(path).is_absolute() || Path::new(path).has_root()
+    } else {
+        Path::new(path).is_absolute()
+    }
+}
+
+fn comparable_component(component: &str) -> String {
+    if cfg!(windows) {
+        component.to_lowercase()
+    } else {
+        component.to_string()
+    }
+}
+
+fn split_for_relative(path: &str) -> (String, Vec<String>) {
+    let mut prefix = String::new();
+    let mut parts = Vec::new();
+    for component in Path::new(path).components() {
+        match component {
+            Component::Prefix(p) => prefix = p.as_os_str().to_string_lossy().into_owned(),
+            Component::RootDir | Component::CurDir => {}
+            Component::ParentDir => parts.push("..".to_string()),
+            Component::Normal(part) => parts.push(part.to_string_lossy().into_owned()),
+        }
+    }
+    (prefix, parts)
+}
+
+/// `path.relative` analogue (win32 comparison is case-insensitive, like
+/// Node). Different Windows drives return `to` unchanged (absolute — fails
+/// containment, matching Node).
+pub(crate) fn path_relative(from: &str, to: &str) -> String {
+    let from_resolved = node_resolve(from);
+    let to_resolved = node_resolve(to);
+    let (from_prefix, from_parts) = split_for_relative(&from_resolved);
+    let (to_prefix, to_parts) = split_for_relative(&to_resolved);
+    if comparable_component(&from_prefix) != comparable_component(&to_prefix) {
+        return to_resolved;
+    }
+    let mut common = 0usize;
+    while common < from_parts.len()
+        && common < to_parts.len()
+        && comparable_component(&from_parts[common]) == comparable_component(&to_parts[common])
+    {
+        common += 1;
+    }
+    let mut pieces: Vec<String> = Vec::new();
+    for _ in common..from_parts.len() {
+        pieces.push("..".to_string());
+    }
+    pieces.extend(to_parts[common..].iter().cloned());
+    pieces.join(std::path::MAIN_SEPARATOR_STR)
+}
+
+/// Strip Windows verbatim prefixes (`\\?\`, `\\?\UNC\`) so canonicalized
+/// paths compare like Node `realpathSync` output.
+fn strip_verbatim(path: &Path) -> String {
+    let raw = path.to_string_lossy();
+    if let Some(rest) = raw.strip_prefix(r"\\?\UNC\") {
+        format!(r"\\{rest}")
+    } else if let Some(rest) = raw.strip_prefix(r"\\?\") {
+        rest.to_string()
+    } else {
+        raw.into_owned()
+    }
+}
+
+/// `realpathSync` analogue.
+pub(crate) fn realpath_compat(path: &str) -> io::Result<String> {
+    std::fs::canonicalize(path).map(|canonical| strip_verbatim(&canonical))
+}
+
+/// TS `normalizePathForComparison` — resolve, realpath when the path exists,
+/// lowercase on Windows.
+fn normalize_path_for_comparison(path_value: &str) -> Result<String, CodexError> {
+    let resolved_path = node_resolve(path_value);
+    let canonical_path = if Path::new(&resolved_path).exists() {
+        realpath_compat(&resolved_path).map_err(io_to_codex)?
+    } else {
+        resolved_path
+    };
+    Ok(if cfg!(windows) {
+        canonical_path.to_lowercase()
+    } else {
+        canonical_path
+    })
+}
+
+fn dirname(path: &str) -> String {
+    Path::new(path)
+        .parent()
+        .map(|parent| parent.to_string_lossy().into_owned())
+        .unwrap_or_else(|| path.to_string())
+}
+
+fn basename(path: &str) -> String {
+    Path::new(path)
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default()
+}
+
+/// TS `assertWithinDirectory` — the containment guard for named backups.
+/// Frozen error string: "Named backup path escapes the backup root".
+pub(crate) fn assert_within_directory(base_dir: &str, target_path: &str) -> Result<(), CodexError> {
+    const ESCAPE: &str = "Named backup path escapes the backup root";
+    let resolved_base = node_resolve(base_dir);
+    let base_stat = match std::fs::symlink_metadata(&resolved_base) {
+        Ok(metadata) => Some(metadata),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => None,
+        Err(error) => return Err(io_to_codex(error)),
+    };
+    if let Some(base_stat) = base_stat {
+        if base_stat.file_type().is_symlink() {
+            return Err(CodexError::new(ESCAPE));
+        }
+        let canonical_base = realpath_compat(&resolved_base).map_err(io_to_codex)?;
+        let comparable_canonical_base = if cfg!(windows) {
+            canonical_base.to_lowercase()
+        } else {
+            canonical_base
+        };
+        let comparable_resolved_base = if cfg!(windows) {
+            resolved_base.to_lowercase()
+        } else {
+            resolved_base.clone()
+        };
+        if comparable_canonical_base != comparable_resolved_base {
+            return Err(CodexError::new(ESCAPE));
+        }
+    }
+    let normalized_base = normalize_path_for_comparison(base_dir)?;
+    let target_parent = dirname(target_path);
+    let normalized_target_parent = normalize_path_for_comparison(&target_parent)?;
+    let normalized_target = format!(
+        "{normalized_target_parent}{}{}",
+        std::path::MAIN_SEPARATOR,
+        basename(target_path)
+    );
+    let rel = path_relative(&normalized_base, &normalized_target);
+    if rel.is_empty() || (!rel.starts_with("..") && !is_absolute_path(&rel)) {
+        return Ok(());
+    }
+    Err(CodexError::new(ESCAPE))
+}
+
+// ============================================================================
+// Name validation (frozen error strings)
+// ============================================================================
+
+fn is_windows_reserved_name(base_name: &str) -> bool {
+    let lower = base_name.to_lowercase();
+    if matches!(lower.as_str(), "con" | "prn" | "aux" | "nul") {
+        return true;
+    }
+    if lower.len() == 4 && (lower.starts_with("com") || lower.starts_with("lpt")) {
+        return lower.as_bytes()[3].is_ascii_digit() && lower.as_bytes()[3] != b'0';
+    }
+    false
+}
+
+/// TS `normalizeNamedBackupFileName` — validate + normalize into
+/// `<name>.json`. Every error string is FROZEN (CLI matches on them).
+pub fn normalize_named_backup_file_name(name: &str) -> Result<String, CodexError> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err(CodexError::new("Named backup requires a non-empty filename"));
+    }
+    if trimmed.contains('/') || trimmed.contains('\\') {
+        return Err(CodexError::new(
+            "Backup filename must not contain path separators",
+        ));
+    }
+    if trimmed.contains("..") {
+        return Err(CodexError::new(
+            "Backup filename must not contain traversal tokens",
+        ));
+    }
+
+    let lower = trimmed.to_lowercase();
+    if BACKUP_PROHIBITED_SUBSTRINGS
+        .iter()
+        .any(|value| lower.contains(value))
+    {
+        return Err(CodexError::new(
+            "Backup filename may not contain rotation-style sequences",
+        ));
+    }
+
+    let base_name = if lower.ends_with(BACKUP_FILE_EXTENSION) {
+        &trimmed[..trimmed.len() - BACKUP_FILE_EXTENSION.len()]
+    } else {
+        trimmed
+    };
+    if base_name.is_empty() {
+        return Err(CodexError::new("Backup filename cannot be just an extension"));
+    }
+    let base_lower = base_name.to_lowercase();
+    if BACKUP_INVALID_SUFFIXES
+        .iter()
+        .any(|value| base_lower.ends_with(value))
+    {
+        return Err(CodexError::new(
+            "Backup filename may not end with temporary suffixes",
+        ));
+    }
+    if is_windows_reserved_name(base_name) {
+        return Err(CodexError::new(
+            "Backup filename may not use a reserved Windows device name",
+        ));
+    }
+    let is_safe = !base_name.is_empty()
+        && base_name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_');
+    if !is_safe {
+        return Err(CodexError::new(
+            "Backup filename may only contain letters, numbers, hyphens, and underscores; dots (.) are not allowed",
+        ));
+    }
+
+    Ok(format!("{base_name}{BACKUP_FILE_EXTENSION}"))
+}
+
+// ============================================================================
+// Root / path resolution
+// ============================================================================
+
+/// TS `getNamedBackupRoot(storagePath)` = resolvePath(dirname(resolvePath(
+/// storagePath)) + "/backups").
+pub fn get_named_backup_root(storage_path: &str) -> Result<String, CodexError> {
+    let resolved_storage_path = resolve_path_string(storage_path)?;
+    let joined = format!(
+        "{}{}{}",
+        dirname(&resolved_storage_path),
+        std::path::MAIN_SEPARATOR,
+        BACKUP_EXPORT_DIR_NAME
+    );
+    resolve_path_string(&joined)
+}
+
+/// TS `resolveNamedBackupPath(name, storagePath)`.
+pub fn resolve_named_backup_path(name: &str, storage_path: &str) -> Result<String, CodexError> {
+    let file_name = normalize_named_backup_file_name(name)?;
+    let backup_root = get_named_backup_root(storage_path)?;
+    let candidate_input =
+        format!("{backup_root}{}{file_name}", std::path::MAIN_SEPARATOR);
+    let candidate = resolve_path_string(&candidate_input)?;
+    assert_within_directory(&backup_root, &candidate)?;
+    Ok(candidate)
+}
+
+/// TS `buildNamedBackupPath(name)` (storage.ts export).
+pub fn build_named_backup_path(name: &str) -> Result<String, CodexError> {
+    resolve_named_backup_path(name, &storage_path_string())
+}
+
+// ============================================================================
+// Export (named-backup-export.ts exportNamedBackupFile + entry wiring)
+// ============================================================================
+
+fn in_flight_contains_or_insert(key: &str) -> bool {
+    let mut guard = IN_FLIGHT_NAMED_BACKUP_EXPORTS
+        .lock()
+        .expect("in-flight set poisoned");
+    let set = guard.get_or_insert_with(HashSet::new);
+    if set.contains(key) {
+        return true;
+    }
+    set.insert(key.to_string());
+    false
+}
+
+fn in_flight_remove(key: &str) {
+    let mut guard = IN_FLIGHT_NAMED_BACKUP_EXPORTS
+        .lock()
+        .expect("in-flight set poisoned");
+    if let Some(set) = guard.as_mut() {
+        set.remove(key);
+    }
+}
+
+/// TS `exportNamedBackup(name, {force})` — validate, guard, export through
+/// [`crate::import_export::export_accounts`] with a beforeCommit containment
+/// re-assert. Returns the destination path.
+pub async fn export_named_backup(name: &str, force: bool) -> Result<String, CodexError> {
+    let storage_path = storage_path_string();
+    let destination = resolve_named_backup_path(name, &storage_path)?;
+    let backup_root = get_named_backup_root(&storage_path)?;
+    let export_key = normalize_path_for_comparison(&destination)?;
+    if in_flight_contains_or_insert(&export_key) {
+        return Err(CodexError::new(format!(
+            "File already exists: {destination}"
+        )));
+    }
+    // TS ordering preserved: the containment assert + mkdir run AFTER the
+    // in-flight key is added but OUTSIDE the try/finally — a failure there
+    // leaves the key registered for the process lifetime (bug-compatible).
+    assert_within_directory(&dirname(&backup_root), &backup_root)?;
+    tokio::fs::create_dir_all(&backup_root)
+        .await
+        .map_err(io_to_codex)?;
+    let before_commit =
+        |resolved_path: &str| assert_within_directory(&backup_root, resolved_path);
+    let result =
+        crate::import_export::export_accounts(&destination, force, Some(&before_commit)).await;
+    in_flight_remove(&export_key);
+    result.map(|()| destination)
+}
+
+// ============================================================================
+// Listing (named-backups.ts collectNamedBackups + entry wiring)
+// ============================================================================
+
+/// TS `NamedBackupSummary`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct NamedBackupSummary {
+    pub path: String,
+    pub file_name: String,
+    pub account_count: usize,
+    pub mtime_ms: f64,
+}
+
+fn mtime_ms_of(metadata: &std::fs::Metadata) -> f64 {
+    metadata
+        .modified()
+        .ok()
+        .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok())
+        .map(|duration| duration.as_secs_f64() * 1000.0)
+        .unwrap_or(0.0)
+}
+
+/// TS `getNamedBackups()` — list `<root>/*.json` backups with account
+/// counts, mtime DESC / fileName ASC.
+pub async fn get_named_backups() -> Result<Vec<NamedBackupSummary>, CodexError> {
+    let log = create_logger("storage");
+    let backup_root = get_named_backup_root(&storage_path_string())?;
+    let mut read_dir = match tokio::fs::read_dir(&backup_root).await {
+        Ok(read_dir) => read_dir,
+        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
+        Err(error) => return Err(io_to_codex(error)),
+    };
+
+    let mut candidates: Vec<NamedBackupSummary> = Vec::new();
+    loop {
+        let entry = match read_dir.next_entry().await {
+            Ok(Some(entry)) => entry,
+            Ok(None) => break,
+            // readdir iteration failures behave like the TS readdir throw.
+            Err(error) => return Err(io_to_codex(error)),
+        };
+        let file_name = entry.file_name().to_string_lossy().into_owned();
+        let is_file = entry
+            .file_type()
+            .await
+            .map(|file_type| file_type.is_file())
+            .unwrap_or(false);
+        if !is_file || !file_name.to_lowercase().ends_with(".json") {
+            continue;
+        }
+        let candidate_path = format!(
+            "{backup_root}{}{file_name}",
+            std::path::MAIN_SEPARATOR
+        );
+        let attempt: Result<(std::fs::Metadata, crate::parser::ParsedStorage), String> = async {
+            let stats_before = tokio::fs::metadata(&candidate_path)
+                .await
+                .map_err(|error| error.to_string())?;
+            let parsed = crate::parser::load_accounts_from_path(Path::new(&candidate_path))
+                .await
+                .map_err(|error| error.to_string())?;
+            Ok((stats_before, parsed))
+        }
+        .await;
+        match attempt {
+            Ok((stats_before, parsed)) => {
+                let Some(normalized) = parsed.normalized else {
+                    continue;
+                };
+                if normalized.accounts.is_empty() {
+                    continue;
+                }
+                if let Ok(stats_after) = tokio::fs::metadata(&candidate_path).await {
+                    let before_ms = mtime_ms_of(&stats_before);
+                    let after_ms = mtime_ms_of(&stats_after);
+                    if after_ms != before_ms {
+                        log.debug(
+                            "backup file changed between stat and load, mtime may be stale",
+                            Some(&json!({
+                                "candidatePath": candidate_path,
+                                "fileName": file_name,
+                                "beforeMtimeMs": before_ms,
+                                "afterMtimeMs": after_ms,
+                            })),
+                        );
+                    }
+                }
+                candidates.push(NamedBackupSummary {
+                    path: candidate_path,
+                    file_name,
+                    account_count: normalized.accounts.len(),
+                    mtime_ms: mtime_ms_of(&stats_before),
+                });
+            }
+            Err(error) => {
+                log.debug(
+                    "Skipping named backup candidate after loadAccountsFromPath/fs.stat failure",
+                    Some(&json!({
+                        "candidatePath": candidate_path,
+                        "fileName": file_name,
+                        "error": error.to_string(),
+                    })),
+                );
+            }
+        }
+    }
+
+    candidates.sort_by(|left, right| {
+        right
+            .mtime_ms
+            .partial_cmp(&left.mtime_ms)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then_with(|| left.file_name.cmp(&right.file_name))
+    });
+    Ok(candidates)
+}
+
+// ============================================================================
+// Tests (ported from test/named-backup-export.test.ts name validation)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn error_of(name: &str) -> String {
+        normalize_named_backup_file_name(name)
+            .expect_err("should reject")
+            .message()
+            .to_string()
+    }
+
+    #[test]
+    fn accepts_safe_names_and_appends_extension() {
+        assert_eq!(normalize_named_backup_file_name("daily").unwrap(), "daily.json");
+        assert_eq!(
+            normalize_named_backup_file_name("  daily  ").unwrap(),
+            "daily.json"
+        );
+        assert_eq!(
+            normalize_named_backup_file_name("My_Backup-2").unwrap(),
+            "My_Backup-2.json"
+        );
+        // One trailing .json (case-insensitive) is stripped, then re-added.
+        assert_eq!(
+            normalize_named_backup_file_name("daily.JSON").unwrap(),
+            "daily.json"
+        );
+    }
+
+    #[test]
+    fn rejects_with_exact_error_strings() {
+        assert_eq!(error_of(""), "Named backup requires a non-empty filename");
+        assert_eq!(error_of("   "), "Named backup requires a non-empty filename");
+        assert_eq!(
+            error_of("a/b"),
+            "Backup filename must not contain path separators"
+        );
+        assert_eq!(
+            error_of("a\\b"),
+            "Backup filename must not contain path separators"
+        );
+        assert_eq!(
+            error_of("a..b"),
+            "Backup filename must not contain traversal tokens"
+        );
+        assert_eq!(
+            error_of("a.ROTATE.b"),
+            "Backup filename may not contain rotation-style sequences"
+        );
+        assert_eq!(
+            error_of(".json"),
+            "Backup filename cannot be just an extension"
+        );
+        assert_eq!(
+            error_of("a.tmp"),
+            "Backup filename may not end with temporary suffixes"
+        );
+        assert_eq!(
+            error_of("a.wal.json"),
+            "Backup filename may not end with temporary suffixes"
+        );
+        assert_eq!(
+            error_of("CON"),
+            "Backup filename may not use a reserved Windows device name"
+        );
+        assert_eq!(
+            error_of("com7"),
+            "Backup filename may not use a reserved Windows device name"
+        );
+        assert_eq!(
+            error_of("lpt1.json"),
+            "Backup filename may not use a reserved Windows device name"
+        );
+        assert_eq!(
+            error_of("has space"),
+            "Backup filename may only contain letters, numbers, hyphens, and underscores; dots (.) are not allowed"
+        );
+        assert_eq!(
+            error_of("dot.name"),
+            "Backup filename may only contain letters, numbers, hyphens, and underscores; dots (.) are not allowed"
+        );
+    }
+
+    #[test]
+    fn com0_and_lpt0_are_not_reserved() {
+        assert_eq!(normalize_named_backup_file_name("com0").unwrap(), "com0.json");
+        assert_eq!(normalize_named_backup_file_name("lpt0").unwrap(), "lpt0.json");
+        // com10 is not reserved either (regex is com[1-9] exactly).
+        assert_eq!(
+            normalize_named_backup_file_name("com10").unwrap(),
+            "com10.json"
+        );
+    }
+
+    #[test]
+    fn path_relative_basics() {
+        if cfg!(windows) {
+            assert_eq!(path_relative("C:\\a\\b", "C:\\a\\b"), "");
+            assert_eq!(path_relative("C:\\a", "C:\\a\\b\\c"), "b\\c");
+            assert_eq!(path_relative("C:\\a\\b", "C:\\a"), "..");
+            assert!(path_relative("C:\\a", "C:\\x\\y").starts_with(".."));
+            // Case-insensitive comparison on Windows.
+            assert_eq!(path_relative("C:\\A", "c:\\a\\b"), "b");
+        } else {
+            assert_eq!(path_relative("/a/b", "/a/b"), "");
+            assert_eq!(path_relative("/a", "/a/b/c"), "b/c");
+            assert_eq!(path_relative("/a/b", "/a"), "..");
+            assert_eq!(path_relative("/a", "/x/y"), "../x/y");
+        }
+    }
+
+    #[test]
+    fn node_resolve_collapses_dots() {
+        if cfg!(windows) {
+            assert_eq!(node_resolve("C:\\a\\.\\b\\..\\c"), "C:\\a\\c");
+        } else {
+            assert_eq!(node_resolve("/a/./b/../c"), "/a/c");
+        }
+    }
+
+    #[test]
+    fn in_flight_set_round_trip() {
+        let key = "test-key-in-flight";
+        assert!(!in_flight_contains_or_insert(key));
+        assert!(in_flight_contains_or_insert(key));
+        in_flight_remove(key);
+        assert!(!in_flight_contains_or_insert(key));
+        in_flight_remove(key);
+    }
+}
diff --git a/crates/storage/src/normalize.rs b/crates/storage/src/normalize.rs
new file mode 100644
index 000000000..4ffafc28d
--- /dev/null
+++ b/crates/storage/src/normalize.rs
@@ -0,0 +1,527 @@
+//! Port of `normalizeAccountStorage` (lib/storage.ts) — spec 02 §5.1 EXACTLY.
+//!
+//! Pipeline: shape/version/accounts checks → raw active-index clamp +
+//! identity capture → V1→V3 migration (accounts taken from the MIGRATED
+//! shape, stress-audit M3) → refresh-token filter → fixpoint dedupe →
+//! identity-following active-index re-resolution (overall + per-family) →
+//! pin RANGE-only validation → affinityGeneration validation → output in
+//! schema key order.
+//!
+//! Input is a raw `serde_json::Value`: both the Zod-validated path (the
+//! parser round-trips the typed storage back to a Value, reproducing zod's
+//! strip+reorder) and the legacy unknown-shape path flow through here.
+//!
+//! Lenient typing note (documented deviation): the TS legacy path passed
+//! account objects through BY REFERENCE, so garbage-typed fields (e.g. a
+//! numeric `accountId`) and unknown keys survived to the next save. The Rust
+//! port converts each account into the typed `AccountMetadataV3` with
+//! per-field type guards (wrong-typed optionals drop; missing required
+//! `addedAt`/`lastUsed` default to 0, matching the `?? 0` arithmetic the
+//! matcher applied). Well-formed files are byte-identical; only
+//! schema-invalid legacy files differ (spec 02 gotcha 19 sanctions the
+//! schema-order rewrite).
+
+use cma_core::logger::create_logger;
+use cma_core::model_family::MODEL_FAMILIES;
+use cma_core::schemas::parse::number_to_i64_lossy;
+use cma_core::utils::now_ms;
+use serde_json::{Value, json};
+
+use crate::identity::AccountIdentityRef;
+use crate::matching::{
+    AccountMatchOptions, clamp_index, deduplicate_accounts, find_matching_account_index,
+};
+use crate::migrations::fan_out_reset_time;
+use crate::misc::is_record;
+use crate::public_types::{
+    AccountIdSource, AccountMetadataV3, AccountStorageV3, ActiveIndexByFamily, CooldownReason,
+    RateLimitStateV3, SwitchReason, Workspace,
+};
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum RawVersion {
+    V1,
+    V3,
+}
+
+fn opt_str<'a>(record: &'a Value, key: &str) -> Option<&'a str> {
+    record.get(key).and_then(Value::as_str)
+}
+
+fn opt_number(record: &Value, key: &str) -> Option<f64> {
+    record.get(key).and_then(Value::as_f64)
+}
+
+fn opt_number_i64(record: &Value, key: &str) -> Option<i64> {
+    record
+        .get(key)
+        .and_then(Value::as_number)
+        .map(number_to_i64_lossy)
+}
+
+fn opt_bool(record: &Value, key: &str) -> Option<bool> {
+    record.get(key).and_then(Value::as_bool)
+}
+
+/// Lenient per-account conversion (see module docs). Returns `None` for
+/// accounts failing the `validAccounts` filter (non-record or blank/missing
+/// `refreshToken`).
+fn account_from_value(raw: &Value, version: RawVersion, now: i64) -> Option<AccountMetadataV3> {
+    if !is_record(raw) {
+        return None;
+    }
+    let refresh_token = opt_str(raw, "refreshToken")?;
+    if refresh_token.trim().is_empty() {
+        return None;
+    }
+
+    let rate_limit_reset_times = match version {
+        RawVersion::V1 => fan_out_reset_time(opt_number_i64(raw, "rateLimitResetTime"), now),
+        RawVersion::V3 => raw
+            .get("rateLimitResetTimes")
+            .and_then(Value::as_object)
+            .map(|map| {
+                let mut state = RateLimitStateV3::new();
+                for (key, value) in map {
+                    if let Some(number) = value.as_number() {
+                        state.insert(key.clone(), number_to_i64_lossy(number));
+                    }
+                }
+                state
+            }),
+    };
+
+    let workspaces: Option<Vec<Workspace>> = match version {
+        // V1 accounts have no workspace fields (migrateV1ToV3 drops them).
+        RawVersion::V1 => None,
+        RawVersion::V3 => raw.get("workspaces").and_then(Value::as_array).map(|items| {
+            items
+                .iter()
+                .filter_map(|item| serde_json::from_value::<Workspace>(item.clone()).ok())
+                .collect()
+        }),
+    };
+    let current_workspace_index = match version {
+        RawVersion::V1 => None,
+        RawVersion::V3 => opt_number_i64(raw, "currentWorkspaceIndex"),
+    };
+
+    Some(AccountMetadataV3 {
+        account_id: opt_str(raw, "accountId").map(str::to_string),
+        account_id_source: opt_str(raw, "accountIdSource").and_then(AccountIdSource::parse),
+        account_label: opt_str(raw, "accountLabel").map(str::to_string),
+        email: opt_str(raw, "email").map(str::to_string),
+        refresh_token: refresh_token.to_string(),
+        access_token: opt_str(raw, "accessToken").map(str::to_string),
+        expires_at: opt_number_i64(raw, "expiresAt"),
+        enabled: opt_bool(raw, "enabled"),
+        added_at: opt_number_i64(raw, "addedAt").unwrap_or(0),
+        last_used: opt_number_i64(raw, "lastUsed").unwrap_or(0),
+        last_switch_reason: opt_str(raw, "lastSwitchReason").and_then(SwitchReason::parse),
+        rate_limit_reset_times,
+        cooling_down_until: opt_number_i64(raw, "coolingDownUntil"),
+        cooldown_reason: opt_str(raw, "cooldownReason").and_then(CooldownReason::parse),
+        workspaces,
+        current_workspace_index,
+    })
+}
+
+/// `extractActiveAccountRef` — identity ref of the RAW account at `index`
+/// (string-typed fields only; `toAccountIdentityRef` trimming: id/token
+/// trimmed, email trimmed+lowercased, empties dropped).
+fn extract_active_account_ref(raw_accounts: &[Value], index: usize) -> AccountIdentityRef {
+    let Some(raw) = raw_accounts.get(index) else {
+        return AccountIdentityRef::default();
+    };
+    if !is_record(raw) {
+        return AccountIdentityRef::default();
+    }
+    AccountIdentityRef::from_parts(
+        opt_str(raw, "accountId"),
+        opt_str(raw, "email"),
+        opt_str(raw, "refreshToken"),
+    )
+}
+
+/// TS `resolveAccountSelectionIndex(accounts, candidate, fallbackIndex)`
+/// with the float fallback the normalizer feeds it: 0 for an empty list;
+/// identity match (unique-accountId fallback enabled); else
+/// `clampIndex(fallback, len)`. Inlined here (rather than calling the
+/// matching module's integer-typed variant) because the normalizer's
+/// fallback is a raw float per spec §5.1 step 9.
+fn resolve_selection_index(
+    accounts: &[AccountMetadataV3],
+    candidate: &AccountIdentityRef,
+    fallback_index: f64,
+) -> usize {
+    if accounts.is_empty() {
+        return 0;
+    }
+    if let Some(matched_index) = find_matching_account_index(
+        accounts,
+        candidate,
+        AccountMatchOptions {
+            allow_unique_account_id_fallback_without_email: true,
+        },
+    ) {
+        return matched_index;
+    }
+    clamp_index(fallback_index, accounts.len())
+}
+
+/// `normalizeAccountStorage(data)` — spec 02 §5.1. Returns `None` for
+/// unrecognized shapes (warned), the normalized V3 storage otherwise.
+pub fn normalize_account_storage(data: &Value) -> Option<AccountStorageV3> {
+    let log = create_logger("storage");
+
+    if !is_record(data) {
+        log.warn("Invalid storage format, ignoring", None);
+        return None;
+    }
+
+    let version_value = data.get("version").and_then(Value::as_f64);
+    let version = match version_value {
+        Some(1.0) => RawVersion::V1,
+        Some(3.0) => RawVersion::V3,
+        _ => {
+            log.warn(
+                "Unknown storage version, ignoring",
+                Some(&json!({ "version": data.get("version").cloned() })),
+            );
+            return None;
+        }
+    };
+
+    let Some(raw_accounts) = data.get("accounts").and_then(Value::as_array) else {
+        log.warn("Invalid storage format, ignoring", None);
+        return None;
+    };
+
+    let active_index_value = opt_number(data, "activeIndex").unwrap_or(0.0);
+    let raw_active_index = clamp_index(active_index_value, raw_accounts.len());
+    let active_ref = extract_active_account_ref(raw_accounts, raw_active_index);
+
+    // Accounts come from the MIGRATED shape for v1 files (stress-audit M3):
+    // the scalar rateLimitResetTime → per-family map conversion must survive.
+    let now = now_ms();
+    let valid_accounts: Vec<AccountMetadataV3> = raw_accounts
+        .iter()
+        .filter_map(|raw| account_from_value(raw, version, now))
+        .collect();
+
+    let deduplicated_accounts = deduplicate_accounts(&valid_accounts);
+
+    let active_index = if deduplicated_accounts.is_empty() {
+        0
+    } else {
+        resolve_selection_index(&deduplicated_accounts, &active_ref, raw_active_index as f64)
+    };
+
+    // Per-family indices: raw per-family value (finite number else the
+    // clamped raw active index); for v1 files the migrated map fans the V1
+    // activeIndex to every family (spec 02 §5.2).
+    let raw_family_indices: Option<&serde_json::Map<String, Value>> = match version {
+        RawVersion::V1 => None,
+        RawVersion::V3 => data.get("activeIndexByFamily").and_then(Value::as_object),
+    };
+    let v1_family_index: Option<f64> = match version {
+        RawVersion::V1 => Some(opt_number(data, "activeIndex").unwrap_or(f64::NAN)),
+        RawVersion::V3 => None,
+    };
+
+    let mut active_index_by_family = ActiveIndexByFamily::default();
+    for family in MODEL_FAMILIES {
+        let raw_index_value: Option<f64> = match version {
+            RawVersion::V1 => v1_family_index.filter(|v| v.is_finite()),
+            RawVersion::V3 => raw_family_indices
+                .and_then(|map| map.get(family.as_str()))
+                .and_then(Value::as_f64),
+        };
+        let raw_index = raw_index_value.unwrap_or(raw_active_index as f64);
+        let clamped_raw_index = clamp_index(raw_index, raw_accounts.len());
+        let family_ref = extract_active_account_ref(raw_accounts, clamped_raw_index);
+        // The RAW (unclamped) index is the fallback (spec §5.1 step 9) —
+        // `resolveAccountSelectionIndex` clamps it itself.
+        let resolved = resolve_selection_index(&deduplicated_accounts, &family_ref, raw_index);
+        active_index_by_family.set(family, Some(resolved as i64));
+    }
+
+    let pinned_account_index: Option<i64> = (|| {
+        let raw = data.get("pinnedAccountIndex")?.as_f64()?;
+        let truncated = raw.trunc();
+        if truncated < 0.0
+            || truncated >= deduplicated_accounts.len() as f64
+            || deduplicated_accounts.is_empty()
+        {
+            log.warn(
+                "Dropping invalid pinnedAccountIndex from storage",
+                Some(&json!({
+                    "value": raw,
+                    "accountCount": deduplicated_accounts.len(),
+                })),
+            );
+            return None;
+        }
+        Some(truncated as i64)
+    })();
+
+    let affinity_generation: Option<i64> = match data.get("affinityGeneration") {
+        None => None,
+        Some(raw) => match raw.as_f64() {
+            Some(value) if value.is_finite() && value.fract() == 0.0 && value >= 0.0 => {
+                Some(value as i64)
+            }
+            _ => {
+                log.warn(
+                    "Dropping invalid affinityGeneration from storage",
+                    Some(&json!({ "value": raw.clone() })),
+                );
+                None
+            }
+        },
+    };
+
+    Some(AccountStorageV3 {
+        version: Default::default(),
+        accounts: deduplicated_accounts,
+        active_index: active_index as i64,
+        active_index_by_family: Some(active_index_by_family),
+        pinned_account_index,
+        affinity_generation,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::model_family::ModelFamily;
+
+    fn account_value(id: &str, email: &str, token: &str) -> Value {
+        json!({
+            "accountId": id,
+            "email": email,
+            "refreshToken": token,
+            "addedAt": 100,
+            "lastUsed": 200,
+        })
+    }
+
+    #[test]
+    fn rejects_non_record_unknown_version_and_bad_accounts() {
+        assert!(normalize_account_storage(&json!("nope")).is_none());
+        assert!(normalize_account_storage(&json!(null)).is_none());
+        assert!(
+            normalize_account_storage(&json!({ "version": 2, "accounts": [], "activeIndex": 0 }))
+                .is_none()
+        );
+        // Version must be a NUMBER 1|3 (strict equality in TS).
+        assert!(
+            normalize_account_storage(&json!({ "version": "3", "accounts": [], "activeIndex": 0 }))
+                .is_none()
+        );
+        assert!(
+            normalize_account_storage(&json!({ "version": 3, "accounts": {}, "activeIndex": 0 }))
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn drops_accounts_with_blank_refresh_tokens() {
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [
+                account_value("a", "a@x.com", "rt_a"),
+                { "refreshToken": "   ", "addedAt": 1, "lastUsed": 1 },
+                { "addedAt": 1, "lastUsed": 1 },
+                "not-a-record",
+            ],
+            "activeIndex": 0,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.accounts.len(), 1);
+        assert_eq!(storage.accounts[0].refresh_token, "rt_a");
+    }
+
+    #[test]
+    fn nan_like_and_out_of_range_active_index_clamps_to_zero() {
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": 99,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.active_index, 0);
+        // Non-numeric activeIndex defaults to 0 before the clamp.
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": "corrupt",
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.active_index, 0);
+    }
+
+    #[test]
+    fn active_index_follows_the_active_account_identity_through_dedupe() {
+        // Two duplicates of account A ahead of B; the raw active index points
+        // at the SECOND copy of A (index 1). After dedupe [A, B], the active
+        // index must follow A → 0 (not stay clamped at 1 = B).
+        let mut newer_a = account_value("acc-a", "a@x.com", "rt_a");
+        newer_a["lastUsed"] = json!(999);
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [
+                account_value("acc-a", "a@x.com", "rt_a"),
+                newer_a,
+                account_value("acc-b", "b@x.com", "rt_b"),
+            ],
+            "activeIndex": 1,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.accounts.len(), 2);
+        assert_eq!(storage.active_index, 0);
+        // The merged survivor keeps the newest content.
+        assert_eq!(storage.accounts[0].last_used, 999);
+    }
+
+    #[test]
+    fn v1_storage_migrates_with_future_reset_fanned_to_all_families() {
+        let future = now_ms() + 3_600_000;
+        let storage = normalize_account_storage(&json!({
+            "version": 1,
+            "accounts": [{
+                "accountId": "acc-a",
+                "email": "a@x.com",
+                "refreshToken": "rt_a",
+                "addedAt": 1,
+                "lastUsed": 2,
+                "rateLimitResetTime": future,
+            }],
+            "activeIndex": 0,
+        }))
+        .expect("normalizes");
+        let map = storage.accounts[0]
+            .rate_limit_reset_times
+            .as_ref()
+            .expect("map fanned out (stress-audit M3)");
+        assert_eq!(map.len(), 5);
+        for family in MODEL_FAMILIES {
+            assert_eq!(map.get(family.as_str()), Some(future));
+        }
+        // Per-family indices fan the v1 activeIndex out too.
+        let by_family = storage.active_index_by_family.expect("family map");
+        assert_eq!(by_family.get(ModelFamily::Gpt5Codex), Some(0));
+    }
+
+    #[test]
+    fn v1_expired_reset_time_is_dropped() {
+        let storage = normalize_account_storage(&json!({
+            "version": 1,
+            "accounts": [{
+                "refreshToken": "rt_a",
+                "addedAt": 1,
+                "lastUsed": 2,
+                "rateLimitResetTime": 12345,
+            }],
+            "activeIndex": 0,
+        }))
+        .expect("normalizes");
+        assert!(storage.accounts[0].rate_limit_reset_times.is_none());
+    }
+
+    #[test]
+    fn pin_is_range_validated_only() {
+        // Valid pin survives untouched (RANGE-only validation, gotcha 8).
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a"), account_value("b", "b@x.com", "rt_b")],
+            "activeIndex": 0,
+            "pinnedAccountIndex": 1,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.pinned_account_index, Some(1));
+        // Out-of-range pin dropped.
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": 0,
+            "pinnedAccountIndex": 7,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.pinned_account_index, None);
+        // Fractional pins truncate before the range check.
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a"), account_value("b", "b@x.com", "rt_b")],
+            "activeIndex": 0,
+            "pinnedAccountIndex": 1.9,
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.pinned_account_index, Some(1));
+        // Non-numeric pin silently omitted (no warn branch).
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": 0,
+            "pinnedAccountIndex": "one",
+        }))
+        .expect("normalizes");
+        assert_eq!(storage.pinned_account_index, None);
+    }
+
+    #[test]
+    fn affinity_generation_validation() {
+        let base = json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": 0,
+        });
+        let mut with_gen = base.clone();
+        with_gen["affinityGeneration"] = json!(5);
+        assert_eq!(
+            normalize_account_storage(&with_gen).unwrap().affinity_generation,
+            Some(5)
+        );
+        // Absent ⇒ omitted.
+        assert_eq!(normalize_account_storage(&base).unwrap().affinity_generation, None);
+        // Invalid values dropped.
+        for bad in [json!(-1), json!(1.5), json!("3")] {
+            let mut invalid = base.clone();
+            invalid["affinityGeneration"] = bad;
+            assert_eq!(
+                normalize_account_storage(&invalid).unwrap().affinity_generation,
+                None
+            );
+        }
+    }
+
+    #[test]
+    fn output_serializes_in_schema_key_order() {
+        let storage = normalize_account_storage(&json!({
+            "version": 3,
+            "accounts": [account_value("a", "a@x.com", "rt_a")],
+            "activeIndex": 0,
+            "affinityGeneration": 2,
+            "pinnedAccountIndex": 0,
+        }))
+        .expect("normalizes");
+        let compact = cma_core::json_io::stringify_compact(&storage);
+        // Top-level order: version, accounts, activeIndex, activeIndexByFamily,
+        // pinnedAccountIndex, affinityGeneration.
+        let version_pos = compact.find("\"version\"").unwrap();
+        let accounts_pos = compact.find("\"accounts\"").unwrap();
+        let active_pos = compact.find("\"activeIndex\"").unwrap();
+        let family_pos = compact.find("\"activeIndexByFamily\"").unwrap();
+        let pin_pos = compact.find("\"pinnedAccountIndex\"").unwrap();
+        let gen_pos = compact.find("\"affinityGeneration\"").unwrap();
+        assert!(version_pos < accounts_pos);
+        assert!(accounts_pos < active_pos);
+        assert!(active_pos < family_pos);
+        assert!(family_pos < pin_pos);
+        assert!(pin_pos < gen_pos);
+        // All five families are present in declaration order.
+        assert!(compact.contains(
+            r#""activeIndexByFamily":{"gpt-5-codex":0,"codex-max":0,"codex":0,"gpt-5.2":0,"gpt-5.1":0}"#
+        ));
+    }
+}
diff --git a/crates/storage/src/parser.rs b/crates/storage/src/parser.rs
new file mode 100644
index 000000000..bd1062cfb
--- /dev/null
+++ b/crates/storage/src/parser.rs
@@ -0,0 +1,258 @@
+//! Port of `lib/storage/storage-parser.ts` — the Zod-guarded JSON load
+//! boundary for account storage.
+//!
+//! Behavior source: spec 02 §8.2 / gotcha 5 (§17 SyntaxError contract):
+//! - The primary read retries transient lock codes
+//!   (`withFileOperationRetry`) so a momentary Windows lock doesn't trigger
+//!   WAL/backup recovery (storage-01). ENOENT is not retryable and
+//!   propagates.
+//! - JSON **SyntaxError propagates unchanged** — recovery paths key off it.
+//!   Rust surface: the error type is `io::Error` (crate-wide convention with
+//!   the sibling modules); a syntax error is minted as
+//!   `ErrorKind::InvalidData` with the `serde_json::Error` as source, so it
+//!   is never mistaken for ENOENT by the recovery ladder.
+//! - Schema mismatches do NOT throw: the raw value falls through to the
+//!   legacy normalizer with non-empty `schema_errors`.
+//! - On the schema-valid path, the typed storage round-trips back through a
+//!   `Value` before normalization, reproducing zod's strip+reorder.
+
+use std::io;
+use std::path::Path;
+
+use cma_core::fs_retry::with_file_operation_retry;
+use cma_core::json_io::read_text_file;
+use cma_core::schemas::parse::safe_parse_json_with_context;
+use serde_json::Value;
+
+use crate::normalize::normalize_account_storage;
+use crate::public_types::{AccountStorageV3, AnyAccountStorage};
+
+/// Result triple of `parseAndNormalizeStorage`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ParsedStorage {
+    /// `normalizeAccountStorage(data)` — `None` for unrecognized shapes.
+    pub normalized: Option<AccountStorageV3>,
+    /// The raw `version` value when `data` is a record AND the value is a
+    /// JSON number with an integral value (TS carried the raw `unknown` and
+    /// compared with JS number equality, so a float-formatted `3.0` equals 3;
+    /// non-numeric and fractional versions surface as `None`, which the
+    /// strict `!==` comparison treats the same — `3.5` still migrates).
+    pub stored_version: Option<i64>,
+    /// `getValidationErrors(AnyAccountStorageSchema, data)` — empty on the
+    /// schema-valid path. (serde reports the first failing field, so the
+    /// legacy path yields a single-entry list; the strings are log-only.)
+    pub schema_errors: Vec<String>,
+}
+
+impl ParsedStorage {
+    /// True when the on-disk `version` differs from the normalized version
+    /// (i.e. a v1 file that needs a migration persist). JS strict-compare
+    /// analogue: `storedVersion !== normalized.version` with
+    /// `normalized.version === 3`.
+    pub fn needs_version_migration(&self) -> bool {
+        self.normalized.is_some() && self.stored_version != Some(3)
+    }
+}
+
+/// `getValidationErrors(AnyAccountStorageSchema, data)` analogue.
+fn any_account_storage_schema_errors(data: &Value) -> Vec<String> {
+    match serde_json::from_value::<AnyAccountStorage>(data.clone()) {
+        Ok(_) => Vec::new(),
+        Err(error) => vec![error.to_string()],
+    }
+}
+
+/// `parseAndNormalizeStorage(data, …)` — schema errors + normalizer + stored
+/// version, computed even on the validated path (they'll be `[]`).
+pub fn parse_and_normalize_storage(data: &Value) -> ParsedStorage {
+    let schema_errors = any_account_storage_schema_errors(data);
+    let normalized = normalize_account_storage(data);
+    // JS number-equality semantics: JSON.parse('3.0') === 3, so a
+    // float-formatted integral version must NOT read as "different from 3"
+    // (that would trigger a spurious migration rewrite TS never performs).
+    let stored_version = if cma_core::utils::is_record(data) {
+        data.get("version").and_then(|value| {
+            value.as_i64().or_else(|| {
+                value
+                    .as_f64()
+                    .filter(|f| f.fract() == 0.0)
+                    .map(|f| f as i64)
+            })
+        })
+    } else {
+        None
+    };
+    ParsedStorage {
+        normalized,
+        stored_version,
+        schema_errors,
+    }
+}
+
+/// `loadAccountsFromPath(path, deps)` — see module docs for the error
+/// contract. ENOENT propagates with `ErrorKind::NotFound`; a JSON syntax
+/// error propagates as `ErrorKind::InvalidData` (the TS SyntaxError).
+pub async fn load_accounts_from_path(
+    path: impl AsRef<Path>,
+) -> Result<ParsedStorage, io::Error> {
+    let path = path.as_ref();
+    // Retry only transient FS lock codes on the primary read (storage-01).
+    let content: String = with_file_operation_retry(|| {
+        let path = path.to_path_buf();
+        async move { read_text_file(&path) }
+    })
+    .await?;
+    parse_storage_content(&content)
+}
+
+/// Shared content half of the boundary (also used by the WAL replay in
+/// `crate::load`, which parses `entry.content` with the same semantics but a
+/// fail-closed error path).
+pub(crate) fn parse_storage_content(content: &str) -> Result<ParsedStorage, io::Error> {
+    // Zod-guarded boundary first: fail-closed on syntax OR schema mismatch.
+    let validated: Option<AnyAccountStorage> =
+        safe_parse_json_with_context(content, "storage-parser.loadAccountsFromPath");
+    if let Some(validated) = validated {
+        let value = serde_json::to_value(&validated).map_err(io::Error::other)?;
+        return Ok(parse_and_normalize_storage(&value));
+    }
+
+    // Disambiguate: SyntaxError propagates (recovery contract); schema
+    // mismatches fall through to the legacy normalizer path.
+    let data: Value = serde_json::from_str(content)
+        .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
+    Ok(parse_and_normalize_storage(&data))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[tokio::test]
+    async fn missing_file_propagates_enoent_io_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let error = load_accounts_from_path(dir.path().join("missing.json"))
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), io::ErrorKind::NotFound);
+    }
+
+    #[tokio::test]
+    async fn json_syntax_error_propagates_unchanged() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("broken.json");
+        std::fs::write(&path, "{ this is not json").unwrap();
+        let error = load_accounts_from_path(&path).await.unwrap_err();
+        assert_eq!(error.kind(), io::ErrorKind::InvalidData);
+        assert!(
+            error
+                .get_ref()
+                .is_some_and(|source| source.is::<serde_json::Error>()),
+            "SyntaxError propagates as the source"
+        );
+    }
+
+    #[tokio::test]
+    async fn schema_valid_file_normalizes_with_no_schema_errors() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        std::fs::write(
+            &path,
+            serde_json::to_string(&json!({
+                "version": 3,
+                "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+                "activeIndex": 0,
+            }))
+            .unwrap(),
+        )
+        .unwrap();
+        let parsed = load_accounts_from_path(&path).await.unwrap();
+        assert!(parsed.schema_errors.is_empty());
+        assert!(!parsed.needs_version_migration());
+        let normalized = parsed.normalized.expect("normalizes");
+        assert_eq!(normalized.accounts.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn schema_invalid_json_falls_to_legacy_path_with_schema_errors() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        // activeIndex: -1 violates the schema (min 0) but the legacy
+        // normalizer still recognizes the record shape.
+        std::fs::write(
+            &path,
+            serde_json::to_string(&json!({
+                "version": 3,
+                "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+                "activeIndex": -1,
+            }))
+            .unwrap(),
+        )
+        .unwrap();
+        let parsed = load_accounts_from_path(&path).await.unwrap();
+        assert!(!parsed.schema_errors.is_empty());
+        let normalized = parsed.normalized.expect("legacy path normalizes");
+        assert_eq!(normalized.active_index, 0);
+    }
+
+    #[tokio::test]
+    async fn v1_file_reports_stored_version_1_and_needs_migration() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        std::fs::write(
+            &path,
+            serde_json::to_string(&json!({
+                "version": 1,
+                "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+                "activeIndex": 0,
+            }))
+            .unwrap(),
+        )
+        .unwrap();
+        let parsed = load_accounts_from_path(&path).await.unwrap();
+        assert!(parsed.schema_errors.is_empty());
+        assert_eq!(parsed.stored_version, Some(1));
+        assert!(parsed.needs_version_migration());
+    }
+
+    #[test]
+    fn float_formatted_version_3_does_not_trigger_a_spurious_migration() {
+        // Schema-invalid file (activeIndex out of range fails the zod/serde
+        // schema) whose hand-edited version is float-formatted. TS compares
+        // `storedVersion !== 3` with JS number equality (3.0 === 3), so no
+        // migration persist happens; the file must be left untouched.
+        let parsed = parse_and_normalize_storage(&json!({
+            "version": 3.0,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": -1,
+        }));
+        assert!(!parsed.schema_errors.is_empty(), "schema-invalid input");
+        assert!(parsed.normalized.is_some(), "still normalizes");
+        assert_eq!(parsed.stored_version, Some(3));
+        assert!(!parsed.needs_version_migration(), "3.0 === 3 in JS");
+
+        // Fractional versions still migrate (3.5 !== 3).
+        let parsed = parse_and_normalize_storage(&json!({
+            "version": 3.5,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": 0,
+        }));
+        assert_eq!(parsed.stored_version, None);
+        if parsed.normalized.is_some() {
+            assert!(parsed.needs_version_migration());
+        }
+    }
+
+    #[test]
+    fn parse_and_normalize_reports_unrecognized_shapes() {
+        let parsed = parse_and_normalize_storage(&json!({ "version": 42 }));
+        assert!(parsed.normalized.is_none());
+        assert!(!parsed.schema_errors.is_empty());
+        assert_eq!(parsed.stored_version, Some(42));
+        // Non-record data has no stored version.
+        let parsed = parse_and_normalize_storage(&json!([1, 2, 3]));
+        assert!(parsed.normalized.is_none());
+        assert_eq!(parsed.stored_version, None);
+    }
+}
diff --git a/crates/storage/src/path_state.rs b/crates/storage/src/path_state.rs
new file mode 100644
index 000000000..fed065e5c
--- /dev/null
+++ b/crates/storage/src/path_state.rs
@@ -0,0 +1,159 @@
+//! Port of `lib/storage/path-state.ts` — storage-path state held in a
+//! process-global with a task-local override (the TS module used a module
+//! global bridged through `AsyncLocalStorage.enterWith`).
+//!
+//! Behavior source: spec 02 §2.7 / gotcha 25.
+//!
+//! Semantics preserved:
+//! - [`get_storage_path_state`] prefers the task-local store and falls back to
+//!   the global.
+//! - [`set_storage_path_state`] assigns the global fallback AND (when called
+//!   inside a [`run_with_storage_path_state`] scope) the current task-local
+//!   store — mirroring `enterWith` propagating through the current async
+//!   chain while the module global keeps serving synchronous readers.
+//! - [`run_with_storage_path_state`] scopes a state for the duration of a
+//!   future (used by concurrent `AccountManager`s to isolate their storage
+//!   paths). Values do NOT cross `tokio::spawn` — spawned work must re-wrap
+//!   explicitly (ARCHITECTURE §5.4).
+
+use std::cell::RefCell;
+use std::sync::Mutex;
+
+/// `StoragePathState` — all four fields `string | null` in TS.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct StoragePathState {
+    pub current_storage_path: Option<String>,
+    pub current_legacy_project_storage_path: Option<String>,
+    pub current_legacy_worktree_storage_path: Option<String>,
+    pub current_project_root: Option<String>,
+}
+
+impl StoragePathState {
+    /// The all-`null` reset state (global storage mode).
+    pub const fn empty() -> Self {
+        Self {
+            current_storage_path: None,
+            current_legacy_project_storage_path: None,
+            current_legacy_worktree_storage_path: None,
+            current_project_root: None,
+        }
+    }
+}
+
+static GLOBAL_STATE: Mutex<StoragePathState> = Mutex::new(StoragePathState::empty());
+
+tokio::task_local! {
+    static TASK_STATE: RefCell<StoragePathState>;
+}
+
+/// `getStoragePathState()` — task-local store if inside a scope, else the
+/// last synchronously assigned global.
+pub fn get_storage_path_state() -> StoragePathState {
+    TASK_STATE
+        .try_with(|cell| cell.borrow().clone())
+        .unwrap_or_else(|_| {
+            GLOBAL_STATE
+                .lock()
+                .expect("storage path state poisoned")
+                .clone()
+        })
+}
+
+/// `setStoragePathState(state)` — assigns the global fallback and, when
+/// called inside a task-local scope, the scope's store too (the `enterWith`
+/// analogue).
+pub fn set_storage_path_state(state: StoragePathState) {
+    *GLOBAL_STATE.lock().expect("storage path state poisoned") = state.clone();
+    let _ = TASK_STATE.try_with(|cell| {
+        *cell.borrow_mut() = state.clone();
+    });
+}
+
+/// `runWithStoragePathState(state, fn)` — run `future` with a task-scoped
+/// state override.
+pub async fn run_with_storage_path_state<T>(
+    state: StoragePathState,
+    future: impl Future<Output = T>,
+) -> T {
+    TASK_STATE.scope(RefCell::new(state), future).await
+}
+
+/// Synchronous variant of [`run_with_storage_path_state`] for sync call
+/// trees.
+pub fn run_with_storage_path_state_sync<T>(state: StoragePathState, f: impl FnOnce() -> T) -> T {
+    TASK_STATE.sync_scope(RefCell::new(state), f)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    fn state_with_path(path: &str) -> StoragePathState {
+        StoragePathState {
+            current_storage_path: Some(path.to_string()),
+            ..StoragePathState::empty()
+        }
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn global_set_and_get_round_trip() {
+        set_storage_path_state(state_with_path("/tmp/a.json"));
+        assert_eq!(
+            get_storage_path_state().current_storage_path.as_deref(),
+            Some("/tmp/a.json")
+        );
+        set_storage_path_state(StoragePathState::empty());
+        assert_eq!(get_storage_path_state(), StoragePathState::empty());
+    }
+
+    #[tokio::test]
+    #[serial(storage_path_state)]
+    async fn task_scope_overrides_global_and_restores_after() {
+        set_storage_path_state(state_with_path("/global.json"));
+        let inner = run_with_storage_path_state(state_with_path("/scoped.json"), async {
+            get_storage_path_state()
+        })
+        .await;
+        assert_eq!(inner.current_storage_path.as_deref(), Some("/scoped.json"));
+        // Outside the scope the global is visible again.
+        assert_eq!(
+            get_storage_path_state().current_storage_path.as_deref(),
+            Some("/global.json")
+        );
+        set_storage_path_state(StoragePathState::empty());
+    }
+
+    #[tokio::test]
+    #[serial(storage_path_state)]
+    async fn set_inside_scope_updates_both_scope_and_global() {
+        set_storage_path_state(StoragePathState::empty());
+        run_with_storage_path_state(state_with_path("/scoped.json"), async {
+            set_storage_path_state(state_with_path("/updated.json"));
+            assert_eq!(
+                get_storage_path_state().current_storage_path.as_deref(),
+                Some("/updated.json")
+            );
+        })
+        .await;
+        // The global fallback was assigned too (TS parity: module global +
+        // enterWith).
+        assert_eq!(
+            get_storage_path_state().current_storage_path.as_deref(),
+            Some("/updated.json")
+        );
+        set_storage_path_state(StoragePathState::empty());
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn sync_scope_works_like_async_scope() {
+        set_storage_path_state(StoragePathState::empty());
+        let seen = run_with_storage_path_state_sync(state_with_path("/sync.json"), || {
+            get_storage_path_state()
+        });
+        assert_eq!(seen.current_storage_path.as_deref(), Some("/sync.json"));
+        assert_eq!(get_storage_path_state(), StoragePathState::empty());
+    }
+}
diff --git a/crates/storage/src/paths.rs b/crates/storage/src/paths.rs
new file mode 100644
index 000000000..743b27079
--- /dev/null
+++ b/crates/storage/src/paths.rs
@@ -0,0 +1,919 @@
+//! Port of `lib/storage/paths.ts` — project-root detection, git-worktree
+//! identity resolution, per-project storage keying, and `resolvePath`, the
+//! security boundary for all user-supplied file paths.
+//!
+//! Behavior source: spec 02 §2.5–§2.6, gotchas 21–24.
+//!
+//! Frozen error strings (`resolvePath`):
+//! - `"Invalid path: contains a NUL byte"`
+//! - `"Access denied: path must be within home directory, project directory, or temp directory"`
+//! - `"Access denied: path resolves (via symlink) outside the home, project, or temp directory"`
+//! - worktree/backup-root messages live in their owning modules.
+
+use std::fs;
+use std::path::{Component, Path, PathBuf};
+
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+
+use crate::misc::compute_sha256;
+use crate::path_state::get_storage_path_state;
+
+/// `PROJECT_MARKERS` — a directory containing any of these is a project.
+pub const PROJECT_MARKERS: &[&str] = &[
+    ".git",
+    "package.json",
+    "Cargo.toml",
+    "go.mod",
+    "pyproject.toml",
+    ".codex",
+];
+
+const PROJECTS_DIR: &str = "projects";
+const PROJECT_KEY_HASH_LENGTH: usize = 12;
+const CANONICALIZE_WALK_CAP: usize = 4096;
+
+/// Plain-`Error` analogue for the frozen `resolvePath` messages (the TS code
+/// threw bare `Error`s; CLI callers match on the message text).
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+#[error("{0}")]
+pub struct PathError(pub String);
+
+// ---------------------------------------------------------------------------
+// Lexical path plumbing (Node path.resolve / path.relative analogues)
+// ---------------------------------------------------------------------------
+
+/// Node `os.homedir()` analogue: env first (`USERPROFILE` on Windows, `HOME`
+/// on POSIX — libuv reads the env var on every call, which is what lets the
+/// test sandbox pin it), falling back to the resolved user home via the
+/// runtime-paths ladder (`get_legacy_codex_dir()`'s parent).
+fn os_home_dir() -> PathBuf {
+    let env_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
+    if let Ok(value) = std::env::var(env_key)
+        && !value.trim().is_empty()
+    {
+        return PathBuf::from(value);
+    }
+    cma_core::runtime_paths::get_legacy_codex_dir()
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_default()
+}
+
+/// Lexical normalization of an absolute path: collapse `.`/`..`, drop
+/// duplicate separators. Never touches the filesystem (Node `path.resolve`
+/// semantics).
+fn normalize_lexical(path: &Path) -> PathBuf {
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::Prefix(prefix) => out.push(prefix.as_os_str()),
+            Component::RootDir => out.push(std::path::MAIN_SEPARATOR_STR),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                // `..` above the root is dropped for absolute paths.
+                out.pop();
+            }
+            Component::Normal(part) => out.push(part),
+        }
+    }
+    out
+}
+
+/// Node `path.resolve(p)` analogue: absolutize against the cwd, then
+/// lexically normalize.
+fn resolve_lexical(path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        normalize_lexical(path)
+    } else {
+        let cwd = std::env::current_dir().unwrap_or_default();
+        normalize_lexical(&cwd.join(path))
+    }
+}
+
+/// `normalizePathForComparison`: resolve, lowercase on win32.
+fn normalize_for_comparison(path: &Path) -> String {
+    let resolved = resolve_lexical(path);
+    let s = resolved.to_string_lossy().into_owned();
+    if cfg!(windows) { s.to_lowercase() } else { s }
+}
+
+/// `isWithinDirectory(baseDir, targetPath)` — `relative()` empty or neither
+/// `..`-prefixed nor absolute. Implemented as a normalized component-prefix
+/// check (equivalent for two absolute, normalized inputs; different Windows
+/// drives yield an absolute relative() in Node and a failed prefix here).
+fn is_within_directory(base_dir: &Path, target_path: &Path) -> bool {
+    let base = normalize_for_comparison(base_dir);
+    let target = normalize_for_comparison(target_path);
+    let base_trimmed = base.trim_end_matches(['\\', '/']);
+    if target == base || target == base_trimmed {
+        return true;
+    }
+    if !target.starts_with(base_trimmed) {
+        return false;
+    }
+    matches!(target.as_bytes().get(base_trimmed.len()), Some(b'/') | Some(b'\\'))
+}
+
+/// `isLookalikeSibling(baseDir, targetPath)` — detects lookalike-prefix
+/// siblings such as `<parent-of-home>/<basename(home)>-outside/file.json`
+/// (spec 02 §2.6 step 4). Filesystem roots have no siblings.
+fn is_lookalike_sibling(base_dir: &Path, target_path: &Path) -> bool {
+    let base = normalize_for_comparison(base_dir);
+    let target = normalize_for_comparison(target_path);
+    let base_without_trailing = base.trim_end_matches(['\\', '/']);
+    if base_without_trailing.is_empty() || is_bare_drive(base_without_trailing) {
+        return false;
+    }
+    if target.len() <= base_without_trailing.len() {
+        return false;
+    }
+    if !target.starts_with(base_without_trailing) {
+        return false;
+    }
+    let boundary = target.as_bytes()[base_without_trailing.len()];
+    boundary != b'/' && boundary != b'\\'
+}
+
+/// `^[a-z]:$` (the comparison string is already lowercased on win32).
+fn is_bare_drive(s: &str) -> bool {
+    let bytes = s.as_bytes();
+    bytes.len() == 2 && bytes[0].is_ascii_lowercase() && bytes[1] == b':'
+}
+
+/// `fs::canonicalize` returns `\\?\`-prefixed extended-length paths on
+/// Windows; Node `realpathSync` does not — strip the prefix so string
+/// comparisons keep working.
+fn simplify_canonical(path: PathBuf) -> PathBuf {
+    let s = path.to_string_lossy();
+    if let Some(rest) = s.strip_prefix(r"\\?\UNC\") {
+        PathBuf::from(format!(r"\\{rest}"))
+    } else if let Some(rest) = s.strip_prefix(r"\\?\") {
+        PathBuf::from(rest.to_string())
+    } else {
+        path
+    }
+}
+
+/// `canonicalizeExistingPrefix(targetPath)` — realpath the deepest existing
+/// ancestor and re-join the non-existent tail; failures return the input so
+/// behavior degrades to the lexical guard (spec 02 §2.6 step 6).
+fn canonicalize_existing_prefix(target_path: &Path) -> PathBuf {
+    let mut current = target_path.to_path_buf();
+    let mut trailing: Vec<std::ffi::OsString> = Vec::new();
+    for _ in 0..CANONICALIZE_WALK_CAP {
+        if current.exists() {
+            break;
+        }
+        let Some(parent) = current.parent().map(Path::to_path_buf) else {
+            // Reached the filesystem root without an existing ancestor.
+            return target_path.to_path_buf();
+        };
+        if parent == current {
+            return target_path.to_path_buf();
+        }
+        if let Some(name) = current.file_name() {
+            trailing.insert(0, name.to_os_string());
+        }
+        current = parent;
+    }
+    match fs::canonicalize(&current) {
+        Ok(real_base) => {
+            let mut out = simplify_canonical(real_base);
+            for part in trailing {
+                out.push(part);
+            }
+            out
+        }
+        Err(_) => target_path.to_path_buf(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// resolvePath — the security boundary (spec 02 §2.6)
+// ---------------------------------------------------------------------------
+
+const ACCESS_DENIED: &str =
+    "Access denied: path must be within home directory, project directory, or temp directory";
+const ACCESS_DENIED_SYMLINK: &str =
+    "Access denied: path resolves (via symlink) outside the home, project, or temp directory";
+
+fn escapes_root_set(roots: &[&Path], candidate: &Path) -> bool {
+    roots.iter().any(|root| is_lookalike_sibling(root, candidate))
+        || !roots.iter().any(|root| is_within_directory(root, candidate))
+}
+
+/// `resolvePath(filePath)` — NUL rejection, `~` expansion (slices only the
+/// tilde), home/project/tmp containment, lookalike-sibling rejection, and the
+/// canonical (realpath) symlink-escape check evaluated against BOTH the raw
+/// and canonicalized root sets. Returns the RESOLVED (non-canonical) path.
+pub fn resolve_path(file_path: &str) -> Result<PathBuf, PathError> {
+    if file_path.contains('\0') {
+        return Err(PathError("Invalid path: contains a NUL byte".to_string()));
+    }
+
+    let resolved: PathBuf = if let Some(rest) = file_path.strip_prefix('~') {
+        // `join(homedir(), filePath.slice(1))`: Node join concatenates (an
+        // absolute-looking segment does NOT re-root), so strip leading
+        // separators before the Rust join and normalize afterwards.
+        let stripped = rest.trim_start_matches(['/', '\\']);
+        normalize_lexical(&os_home_dir().join(stripped))
+    } else {
+        resolve_lexical(Path::new(file_path))
+    };
+
+    let home = os_home_dir();
+    let state = get_storage_path_state();
+    let project_root = state
+        .current_project_root
+        .map(PathBuf::from)
+        .unwrap_or_else(|| std::env::current_dir().unwrap_or_default());
+    let tmp = std::env::temp_dir();
+
+    if is_lookalike_sibling(&home, &resolved)
+        || is_lookalike_sibling(&project_root, &resolved)
+        || is_lookalike_sibling(&tmp, &resolved)
+    {
+        return Err(PathError(ACCESS_DENIED.to_string()));
+    }
+
+    if !is_within_directory(&home, &resolved)
+        && !is_within_directory(&project_root, &resolved)
+        && !is_within_directory(&tmp, &resolved)
+    {
+        return Err(PathError(ACCESS_DENIED.to_string()));
+    }
+
+    // storage-02: re-verify containment against the realpath-canonicalized
+    // path. Deny only when the canonical target escapes BOTH the raw and the
+    // canonical root sets (a root itself reached via a symlink, e.g. macOS
+    // /var → /private/var, must not falsely deny).
+    let canonical = canonicalize_existing_prefix(&resolved);
+    if canonical != resolved {
+        let raw_roots: [&Path; 3] = [&home, &project_root, &tmp];
+        let canonical_home = canonicalize_existing_prefix(&home);
+        let canonical_project_root = canonicalize_existing_prefix(&project_root);
+        let canonical_tmp = canonicalize_existing_prefix(&tmp);
+        let canonical_roots: [&Path; 3] =
+            [&canonical_home, &canonical_project_root, &canonical_tmp];
+        if escapes_root_set(&raw_roots, &canonical)
+            && escapes_root_set(&canonical_roots, &canonical)
+        {
+            return Err(PathError(ACCESS_DENIED_SYMLINK.to_string()));
+        }
+    }
+
+    Ok(resolved)
+}
+
+// ---------------------------------------------------------------------------
+// Config dirs & project keys
+// ---------------------------------------------------------------------------
+
+/// `getConfigDir()` = `getCodexMultiAuthDir()`.
+pub fn get_config_dir() -> PathBuf {
+    get_codex_multi_auth_dir()
+}
+
+/// `getProjectConfigDir(projectPath)` = `<projectPath>/.codex` (legacy
+/// per-project location).
+pub fn get_project_config_dir(project_path: &Path) -> PathBuf {
+    project_path.join(".codex")
+}
+
+/// `normalizeProjectPath`: resolve, `\` → `/`, lowercase on win32.
+fn normalize_project_path(project_path: &Path) -> String {
+    let resolved = resolve_lexical(project_path);
+    let with_forward = resolved.to_string_lossy().replace('\\', "/");
+    if cfg!(windows) {
+        with_forward.to_lowercase()
+    } else {
+        with_forward
+    }
+}
+
+/// `sanitizeProjectName`: basename, `[^a-zA-Z0-9._-]+ → "-"`, strip
+/// leading/trailing `-`, fallback `"project"`.
+fn sanitize_project_name(normalized_path: &str) -> String {
+    let name = normalized_path
+        .trim_end_matches('/')
+        .rsplit('/')
+        .next()
+        .unwrap_or("");
+    let mut sanitized = String::with_capacity(name.len());
+    let mut last_was_dash = false;
+    for c in name.chars() {
+        if c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-' {
+            sanitized.push(c);
+            last_was_dash = false;
+        } else if !last_was_dash {
+            sanitized.push('-');
+            last_was_dash = true;
+        }
+    }
+    let trimmed = sanitized.trim_matches('-');
+    if trimmed.is_empty() {
+        "project".to_string()
+    } else {
+        trimmed.to_string()
+    }
+}
+
+/// `getProjectStorageKey(projectPath)` = `"<name≤40>-<sha256[..12]>"` over
+/// the normalized (lowercased-on-win32, `/`-separated) path. NOTE: the name
+/// part comes from the NORMALIZED path, so it is lowercase on Windows.
+pub fn get_project_storage_key(project_path: &Path) -> String {
+    let normalized_path = normalize_project_path(project_path);
+    let hash: String = compute_sha256(&normalized_path)
+        .chars()
+        .take(PROJECT_KEY_HASH_LENGTH)
+        .collect();
+    let project_name: String = sanitize_project_name(&normalized_path)
+        .chars()
+        .take(40)
+        .collect();
+    format!("{project_name}-{hash}")
+}
+
+/// `getProjectGlobalConfigDir(projectPath)` =
+/// `<configDir>/projects/<storageKey>`.
+pub fn get_project_global_config_dir(project_path: &Path) -> PathBuf {
+    get_config_dir()
+        .join(PROJECTS_DIR)
+        .join(get_project_storage_key(project_path))
+}
+
+// ---------------------------------------------------------------------------
+// Project detection
+// ---------------------------------------------------------------------------
+
+/// `isProjectDirectory(dir)`: any [`PROJECT_MARKERS`] entry exists.
+pub fn is_project_directory(dir: &Path) -> bool {
+    PROJECT_MARKERS.iter().any(|marker| dir.join(marker).exists())
+}
+
+/// `findProjectRoot(startDir)`: walk up; the FIRST dir containing `.git`
+/// wins immediately; otherwise remember the first marker match and keep
+/// walking to the fs root looking for `.git` (gotcha 24: `.git` anywhere
+/// above beats a closer non-git marker).
+pub fn find_project_root(start_dir: &Path) -> Option<PathBuf> {
+    let mut current = start_dir.to_path_buf();
+    let mut first_marker_root: Option<PathBuf> = None;
+
+    loop {
+        if current.as_os_str().is_empty() {
+            break;
+        }
+        if current.join(".git").exists() {
+            return Some(current);
+        }
+        if first_marker_root.is_none() && is_project_directory(&current) {
+            first_marker_root = Some(current.clone());
+        }
+        let Some(parent) = current.parent().map(Path::to_path_buf) else {
+            break;
+        };
+        if parent == current {
+            break;
+        }
+        current = parent;
+    }
+
+    first_marker_root
+}
+
+// ---------------------------------------------------------------------------
+// Git-worktree identity resolution (spec 02 §2.5)
+// ---------------------------------------------------------------------------
+
+/// First line of a `.git` pointer file: `gitdir: <value>` (case-insensitive,
+/// CRLF-tolerant, first line only).
+fn parse_git_dir_pointer(pointer_content: &str) -> Option<String> {
+    let first_line = pointer_content
+        .split(['\r', '\n'])
+        .next()
+        .unwrap_or("")
+        .trim();
+    if first_line.is_empty() {
+        return None;
+    }
+    // `/^gitdir:\s*(.+)$/i`
+    if first_line.len() < 7 || !first_line[..7].eq_ignore_ascii_case("gitdir:") {
+        return None;
+    }
+    let value = first_line[7..].trim();
+    if value.is_empty() {
+        None
+    } else {
+        Some(value.to_string())
+    }
+}
+
+fn normalize_path_delimiters(path_value: &str) -> String {
+    path_value.replace('\\', "/")
+}
+
+/// `/^[A-Za-z]:[\\/]/`, `/^\\\\[^\\]/` or `/^\/\/[^/]/`.
+fn is_windows_rooted_path(path_value: &str) -> bool {
+    let bytes: Vec<char> = path_value.chars().collect();
+    if bytes.len() >= 3 && bytes[0].is_ascii_alphabetic() && bytes[1] == ':' && (bytes[2] == '\\' || bytes[2] == '/') {
+        return true;
+    }
+    if bytes.len() >= 3 && bytes[0] == '\\' && bytes[1] == '\\' && bytes[2] != '\\' {
+        return true;
+    }
+    bytes.len() >= 3 && bytes[0] == '/' && bytes[1] == '/' && bytes[2] != '/'
+}
+
+/// Minimal `path.win32.normalize` analogue for git-pointer handling: `/`→`\`,
+/// collapse separators, resolve `.`/`..` segments below the root.
+fn normalize_win32_str(input: &str) -> String {
+    let converted = input.replace('/', "\\");
+    // Split root: UNC (\\server\share\), drive (C:\ or C:), or rooted (\).
+    let (root, rest): (String, String) = if let Some(after) = converted.strip_prefix("\\\\") {
+        if let Some(server_end) = after.find('\\') {
+            let after_server = &after[server_end + 1..];
+            if let Some(share_end) = after_server.find('\\') {
+                let root_len = 2 + server_end + 1 + share_end + 1;
+                (converted[..root_len].to_string(), converted[root_len..].to_string())
+            } else {
+                (converted.clone(), String::new())
+            }
+        } else {
+            (converted.clone(), String::new())
+        }
+    } else {
+        let chars: Vec<char> = converted.chars().collect();
+        if chars.len() >= 2 && chars[0].is_ascii_alphabetic() && chars[1] == ':' {
+            if chars.len() >= 3 && chars[2] == '\\' {
+                (format!("{}{}\\", chars[0], chars[1]), converted[3..].to_string())
+            } else {
+                (format!("{}{}", chars[0], chars[1]), converted[2..].to_string())
+            }
+        } else if let Some(stripped) = converted.strip_prefix('\\') {
+            ("\\".to_string(), stripped.to_string())
+        } else {
+            (String::new(), converted.clone())
+        }
+    };
+
+    let mut components: Vec<&str> = Vec::new();
+    for part in rest.split('\\') {
+        if part.is_empty() || part == "." {
+            continue;
+        }
+        if part == ".." {
+            match components.last() {
+                Some(last) if *last != ".." => {
+                    components.pop();
+                }
+                _ if root.is_empty() => components.push(".."),
+                _ => {}
+            }
+        } else {
+            components.push(part);
+        }
+    }
+    let joined = components.join("\\");
+    if root.is_empty() {
+        if joined.is_empty() { ".".to_string() } else { joined }
+    } else {
+        format!("{root}{joined}")
+    }
+}
+
+/// `win32.isAbsolute` analogue (drive-rooted, UNC, or root-relative `\x`).
+fn is_win32_absolute(s: &str) -> bool {
+    let chars: Vec<char> = s.chars().collect();
+    if chars.first() == Some(&'\\') || chars.first() == Some(&'/') {
+        return true;
+    }
+    chars.len() >= 3
+        && chars[0].is_ascii_alphabetic()
+        && chars[1] == ':'
+        && (chars[2] == '\\' || chars[2] == '/')
+}
+
+/// `resolveGitPath(basePath, pointerValue)` — resolves a git pointer relative
+/// to its base, handling mixed Windows/POSIX rooted paths (spec 02 §2.5 step
+/// 3). On non-Windows hosts a Windows-flavored result converts `\` → `/`.
+fn resolve_git_path(base_path: &Path, pointer_value: &str) -> PathBuf {
+    let trimmed_pointer = pointer_value.trim();
+    if trimmed_pointer.is_empty() {
+        return base_path.to_path_buf();
+    }
+    let base_str = base_path.to_string_lossy().into_owned();
+
+    if is_windows_rooted_path(&base_str) || is_windows_rooted_path(trimmed_pointer) {
+        let windows_base = normalize_win32_str(&base_str);
+        let windows_pointer = normalize_win32_str(trimmed_pointer);
+        let windows_resolved = if is_win32_absolute(&windows_pointer) {
+            // win32.resolve stops at the first absolute segment; a
+            // root-relative pointer (`\x`) adopts the base's drive.
+            let chars: Vec<char> = windows_pointer.chars().collect();
+            if chars.first() == Some(&'\\')
+                && !(chars.len() >= 2 && chars[1] == '\\')
+            {
+                let drive: String = windows_base.chars().take_while(|c| *c != '\\').collect();
+                if drive.ends_with(':') {
+                    normalize_win32_str(&format!("{drive}{windows_pointer}"))
+                } else {
+                    windows_pointer
+                }
+            } else {
+                windows_pointer
+            }
+        } else {
+            normalize_win32_str(&format!("{windows_base}\\{windows_pointer}"))
+        };
+        if cfg!(windows) {
+            PathBuf::from(windows_resolved)
+        } else {
+            PathBuf::from(normalize_path_delimiters(&windows_resolved))
+        }
+    } else {
+        let normalized_pointer = normalize_path_delimiters(trimmed_pointer);
+        if normalized_pointer.starts_with('/') {
+            PathBuf::from(normalized_pointer)
+        } else {
+            normalize_lexical(&base_path.join(normalized_pointer))
+        }
+    }
+}
+
+fn read_git_common_dir(git_dir_path: &Path) -> PathBuf {
+    let common_dir_file = git_dir_path.join("commondir");
+    if !common_dir_file.exists() {
+        return git_dir_path.to_path_buf();
+    }
+    match fs::read(&common_dir_file) {
+        Ok(bytes) => {
+            let raw = String::from_utf8_lossy(&bytes).trim().to_string();
+            if raw.is_empty() {
+                git_dir_path.to_path_buf()
+            } else {
+                resolve_git_path(git_dir_path, &raw)
+            }
+        }
+        Err(_) => git_dir_path.to_path_buf(),
+    }
+}
+
+fn is_worktree_git_dir_path(git_dir_path: &Path) -> bool {
+    normalize_path_delimiters(&git_dir_path.to_string_lossy())
+        .to_lowercase()
+        .contains("/.git/worktrees/")
+}
+
+/// `normalizePathForIdentityCheck` — trim, `\`→`/`; Windows-rooted values go
+/// through win32 normalization + lowercase; others resolve lexically
+/// (+lowercase on win32 hosts).
+fn normalize_path_for_identity_check(path_value: &str) -> String {
+    let normalized_delimiters = normalize_path_delimiters(path_value.trim());
+    if normalized_delimiters.is_empty() {
+        return normalized_delimiters;
+    }
+    if is_windows_rooted_path(&normalized_delimiters) {
+        return normalize_win32_str(&normalized_delimiters).to_lowercase();
+    }
+    let resolved = resolve_lexical(Path::new(&normalized_delimiters));
+    let normalized_resolved = normalize_path_delimiters(&resolved.to_string_lossy());
+    if cfg!(windows) {
+        normalized_resolved.to_lowercase()
+    } else {
+        normalized_resolved
+    }
+}
+
+fn normalize_canonical_path_for_identity_check(path_value: &str) -> String {
+    let normalized = normalize_path_for_identity_check(path_value);
+    if normalized.is_empty() {
+        return normalized;
+    }
+    match fs::canonicalize(Path::new(path_value)) {
+        Ok(canonical) => normalize_path_for_identity_check(
+            &simplify_canonical(canonical).to_string_lossy(),
+        ),
+        Err(_) => normalized,
+    }
+}
+
+fn worktree_git_dir_belongs_to_project(project_root: &Path, git_dir_path: &Path) -> bool {
+    let backref_path = git_dir_path.join("gitdir");
+    if !backref_path.exists() {
+        return false;
+    }
+    let Ok(bytes) = fs::read(&backref_path) else {
+        return false;
+    };
+    let backref_raw = String::from_utf8_lossy(&bytes).trim().to_string();
+    if backref_raw.is_empty() {
+        return false;
+    }
+    let resolved_backref = resolve_git_path(git_dir_path, &backref_raw);
+    let expected_backref = project_root.join(".git");
+    normalize_canonical_path_for_identity_check(&resolved_backref.to_string_lossy())
+        == normalize_canonical_path_for_identity_check(&expected_backref.to_string_lossy())
+}
+
+fn is_git_dir_under_common_worktrees(git_dir_path: &Path, common_git_dir: &Path) -> bool {
+    let normalized_git_dir = normalize_path_delimiters(&normalize_path_for_identity_check(
+        &git_dir_path.to_string_lossy(),
+    ));
+    let normalized_git_dir = normalized_git_dir.trim_end_matches('/');
+    let normalized_common = normalize_path_delimiters(&normalize_path_for_identity_check(
+        &common_git_dir.to_string_lossy(),
+    ));
+    let normalized_common = normalized_common.trim_end_matches('/');
+    if normalized_git_dir.is_empty() || normalized_common.is_empty() {
+        return false;
+    }
+    let worktrees_root = format!("{normalized_common}/worktrees/");
+    normalized_git_dir.starts_with(&worktrees_root)
+}
+
+/// `resolveProjectStorageIdentityRoot(projectRoot)` — linked git worktrees
+/// resolve to the shared repository root so all worktrees use one per-project
+/// storage key; any failure falls back to `projectRoot` (spec 02 §2.5).
+pub fn resolve_project_storage_identity_root(project_root: &Path) -> PathBuf {
+    let git_entry_path = project_root.join(".git");
+    if !git_entry_path.exists() {
+        return project_root.to_path_buf();
+    }
+
+    let resolved = (|| -> Option<PathBuf> {
+        let git_entry_stat = fs::metadata(&git_entry_path).ok()?;
+        if git_entry_stat.is_dir() || !git_entry_stat.is_file() {
+            return None;
+        }
+        let pointer_bytes = fs::read(&git_entry_path).ok()?;
+        let git_pointer = String::from_utf8_lossy(&pointer_bytes).into_owned();
+        let git_dir_value = parse_git_dir_pointer(&git_pointer)?;
+        let git_dir_path = resolve_git_path(project_root, &git_dir_value);
+        if !is_worktree_git_dir_path(&git_dir_path) {
+            return None;
+        }
+        if !worktree_git_dir_belongs_to_project(project_root, &git_dir_path) {
+            return None;
+        }
+        let common_git_dir = read_git_common_dir(&git_dir_path);
+        if !is_git_dir_under_common_worktrees(&git_dir_path, &common_git_dir) {
+            return None;
+        }
+        let candidate_repo_root = common_git_dir.parent()?.to_path_buf();
+        if !candidate_repo_root.join(".git").exists() {
+            return None;
+        }
+        Some(candidate_repo_root)
+    })();
+
+    resolved.unwrap_or_else(|| project_root.to_path_buf())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    // ----- project keys -----
+
+    #[test]
+    fn project_storage_key_is_name_dash_12_hex() {
+        let key = get_project_storage_key(Path::new("/work/My Project"));
+        let (name, hash) = key.rsplit_once('-').expect("name-hash split");
+        assert_eq!(hash.len(), 12);
+        assert!(hash.chars().all(|c| c.is_ascii_hexdigit()));
+        // Space collapsed to a single dash; lowercase on Windows.
+        if cfg!(windows) {
+            assert_eq!(name, "my-project");
+        } else {
+            assert_eq!(name, "My-Project");
+        }
+    }
+
+    #[test]
+    fn project_storage_key_is_stable_for_equivalent_paths() {
+        let a = get_project_storage_key(Path::new("/work/app"));
+        let b = get_project_storage_key(Path::new("/work/app"));
+        assert_eq!(a, b);
+        let c = get_project_storage_key(Path::new("/work/other"));
+        assert_ne!(a, c);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn project_storage_key_is_case_insensitive_on_windows() {
+        let a = get_project_storage_key(Path::new(r"C:\Work\App"));
+        let b = get_project_storage_key(Path::new(r"c:\work\app"));
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn sanitize_project_name_falls_back_to_project() {
+        assert_eq!(sanitize_project_name("/x/@@@"), "project");
+        assert_eq!(sanitize_project_name("/x/-abc-"), "abc");
+        assert_eq!(sanitize_project_name("/x/a b  c"), "a-b-c");
+        assert_eq!(sanitize_project_name("/x/ok_name.v2"), "ok_name.v2");
+    }
+
+    // ----- project root detection -----
+
+    #[test]
+    fn find_project_root_prefers_git_anywhere_above_a_closer_marker() {
+        let dir = tempfile::tempdir().unwrap();
+        let repo = dir.path().join("repo");
+        let nested = repo.join("packages").join("app");
+        fs::create_dir_all(&nested).unwrap();
+        fs::create_dir_all(repo.join(".git")).unwrap();
+        // The nested dir has a package.json marker, but `.git` above wins.
+        fs::write(nested.join("package.json"), "{}").unwrap();
+        let root = find_project_root(&nested).expect("root found");
+        assert_eq!(fs::canonicalize(root).unwrap(), fs::canonicalize(&repo).unwrap());
+    }
+
+    #[test]
+    fn find_project_root_uses_first_marker_when_no_git_exists() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("proj");
+        let nested = project.join("src");
+        fs::create_dir_all(&nested).unwrap();
+        fs::write(project.join("Cargo.toml"), "").unwrap();
+        let root = find_project_root(&nested).expect("root found");
+        assert_eq!(root, project);
+    }
+
+    #[test]
+    fn is_project_directory_checks_all_markers() {
+        let dir = tempfile::tempdir().unwrap();
+        assert!(!is_project_directory(dir.path()));
+        fs::write(dir.path().join("go.mod"), "").unwrap();
+        assert!(is_project_directory(dir.path()));
+    }
+
+    // ----- identity root (worktrees) -----
+
+    #[test]
+    fn identity_root_returns_project_root_for_a_normal_repo() {
+        let dir = tempfile::tempdir().unwrap();
+        let repo = dir.path().join("repo");
+        fs::create_dir_all(repo.join(".git")).unwrap();
+        assert_eq!(resolve_project_storage_identity_root(&repo), repo);
+    }
+
+    #[test]
+    fn identity_root_resolves_a_linked_worktree_to_the_main_repo() {
+        let dir = tempfile::tempdir().unwrap();
+        let main_repo = dir.path().join("main");
+        let git_dir = main_repo.join(".git");
+        let wt_git_dir = git_dir.join("worktrees").join("wt1");
+        let worktree = dir.path().join("wt1");
+        fs::create_dir_all(&wt_git_dir).unwrap();
+        fs::create_dir_all(&worktree).unwrap();
+        // Worktree .git pointer file → main repo's worktrees dir.
+        fs::write(
+            worktree.join(".git"),
+            format!("gitdir: {}\n", wt_git_dir.to_string_lossy()),
+        )
+        .unwrap();
+        // Backref + commondir as git lays them out.
+        fs::write(
+            wt_git_dir.join("gitdir"),
+            format!("{}\n", worktree.join(".git").to_string_lossy()),
+        )
+        .unwrap();
+        fs::write(wt_git_dir.join("commondir"), "../..\n").unwrap();
+        let resolved = resolve_project_storage_identity_root(&worktree);
+        assert_eq!(
+            fs::canonicalize(resolved).unwrap(),
+            fs::canonicalize(&main_repo).unwrap()
+        );
+    }
+
+    #[test]
+    fn identity_root_rejects_a_forged_pointer_without_backref() {
+        let dir = tempfile::tempdir().unwrap();
+        let main_repo = dir.path().join("main");
+        let wt_git_dir = main_repo.join(".git").join("worktrees").join("wt1");
+        let worktree = dir.path().join("wt1");
+        fs::create_dir_all(&wt_git_dir).unwrap();
+        fs::create_dir_all(&worktree).unwrap();
+        fs::write(
+            worktree.join(".git"),
+            format!("gitdir: {}\n", wt_git_dir.to_string_lossy()),
+        )
+        .unwrap();
+        // No gitdir backref file ⇒ stays at the worktree root.
+        assert_eq!(resolve_project_storage_identity_root(&worktree), worktree);
+    }
+
+    // ----- resolvePath -----
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn resolve_path_rejects_nul_bytes_with_frozen_message() {
+        let error = resolve_path("bad\0path.json").unwrap_err();
+        assert_eq!(error.0, "Invalid path: contains a NUL byte");
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn resolve_path_allows_paths_inside_the_temp_dir() {
+        let target = std::env::temp_dir().join("cma-resolve-path-test.json");
+        let resolved = resolve_path(&target.to_string_lossy()).expect("tmp is an approved root");
+        assert!(resolved.ends_with("cma-resolve-path-test.json"));
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn resolve_path_denies_paths_outside_all_roots() {
+        let outside = if cfg!(windows) {
+            r"C:\cma-definitely-not-a-root\file.json"
+        } else {
+            "/cma-definitely-not-a-root/file.json"
+        };
+        let error = resolve_path(outside).unwrap_err();
+        assert_eq!(
+            error.0,
+            "Access denied: path must be within home directory, project directory, or temp directory"
+        );
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn resolve_path_expands_a_bare_tilde_prefix() {
+        let resolved = resolve_path("~/cma-tilde-test.json").expect("home is approved");
+        assert!(resolved.starts_with(os_home_dir()));
+        assert!(resolved.ends_with("cma-tilde-test.json"));
+        // `~foo` slices only the tilde: it lands at `<home>/foo` too.
+        let sliced = resolve_path("~cma-tilde-file.json").expect("home is approved");
+        assert_eq!(sliced, os_home_dir().join("cma-tilde-file.json"));
+    }
+
+    #[test]
+    #[serial(storage_path_state)]
+    fn resolve_path_rejects_lookalike_siblings_of_home() {
+        let home = os_home_dir();
+        let sibling = format!("{}-outside{}file.json", home.to_string_lossy(), std::path::MAIN_SEPARATOR);
+        let error = resolve_path(&sibling).unwrap_err();
+        assert_eq!(
+            error.0,
+            "Access denied: path must be within home directory, project directory, or temp directory"
+        );
+    }
+
+    // ----- helpers -----
+
+    #[test]
+    fn within_directory_component_semantics() {
+        if cfg!(windows) {
+            assert!(is_within_directory(Path::new(r"C:\a"), Path::new(r"C:\a\b.json")));
+            assert!(is_within_directory(Path::new(r"C:\a"), Path::new(r"C:\A")));
+            assert!(!is_within_directory(Path::new(r"C:\a"), Path::new(r"C:\ab")));
+            assert!(!is_within_directory(Path::new(r"C:\a"), Path::new(r"D:\a\b")));
+        } else {
+            assert!(is_within_directory(Path::new("/a"), Path::new("/a/b.json")));
+            assert!(is_within_directory(Path::new("/a"), Path::new("/a")));
+            assert!(!is_within_directory(Path::new("/a"), Path::new("/ab")));
+            assert!(is_within_directory(Path::new("/"), Path::new("/anything")));
+        }
+    }
+
+    #[test]
+    fn lookalike_sibling_detection() {
+        if cfg!(windows) {
+            assert!(is_lookalike_sibling(Path::new(r"C:\home\user"), Path::new(r"C:\home\user-evil\x")));
+            assert!(!is_lookalike_sibling(Path::new(r"C:\home\user"), Path::new(r"C:\home\user\x")));
+            // A bare drive root has no siblings.
+            assert!(!is_lookalike_sibling(Path::new(r"C:\"), Path::new(r"C:\anything")));
+        } else {
+            assert!(is_lookalike_sibling(Path::new("/home/user"), Path::new("/home/user-evil/x")));
+            assert!(!is_lookalike_sibling(Path::new("/home/user"), Path::new("/home/user/x")));
+            // The filesystem root has no siblings.
+            assert!(!is_lookalike_sibling(Path::new("/"), Path::new("/anything")));
+        }
+    }
+
+    #[test]
+    fn git_pointer_parsing_is_case_insensitive_and_first_line_only() {
+        assert_eq!(
+            parse_git_dir_pointer("gitdir: /x/.git/worktrees/a\n"),
+            Some("/x/.git/worktrees/a".to_string())
+        );
+        assert_eq!(
+            parse_git_dir_pointer("GITDIR:   ..\\main\\.git\\worktrees\\a\r\nsecond"),
+            Some("..\\main\\.git\\worktrees\\a".to_string())
+        );
+        assert_eq!(parse_git_dir_pointer(""), None);
+        assert_eq!(parse_git_dir_pointer("nonsense"), None);
+        assert_eq!(parse_git_dir_pointer("gitdir:"), None);
+    }
+
+    #[test]
+    fn windows_rooted_detection() {
+        assert!(is_windows_rooted_path(r"C:\x"));
+        assert!(is_windows_rooted_path("C:/x"));
+        assert!(is_windows_rooted_path(r"\\server\share"));
+        assert!(is_windows_rooted_path("//server/share"));
+        assert!(!is_windows_rooted_path("/plain/posix"));
+        assert!(!is_windows_rooted_path("relative/path"));
+    }
+}
diff --git a/crates/storage/src/project_migration.rs b/crates/storage/src/project_migration.rs
new file mode 100644
index 000000000..84cdadfd1
--- /dev/null
+++ b/crates/storage/src/project_migration.rs
@@ -0,0 +1,405 @@
+//! Port of `lib/storage/project-migration.ts` (spec 02 §5.4–§5.5).
+//!
+//! - [`load_normalized_storage_from_path`]: warn + `None` on any failure
+//!   (non-ENOENT failures logged) — the tolerant read used by the legacy
+//!   project-storage migration and the synthetic-fixture save guard.
+//! - [`merge_storage_for_migration`]: pin captured BY IDENTITY **before** the
+//!   merge (gotcha 8) — `normalizeAccountStorage` only range-validates the
+//!   pin, so it must be re-pointed (or cleared) after dedupe.
+//!
+//! The `migrateLegacyProjectStorageIfNeeded` ladder itself is private to
+//! `lib/storage.ts` and lives in `crate::load` (commit mode) /
+//! `crate::load::load_accounts_for_export` (export mode) — this module only
+//! provides the two helpers project-migration.ts exports (gotcha 35: one
+//! canonical copy, no divergent duplicates).
+
+use std::io;
+use std::path::Path;
+
+use serde_json::{Map, Value, json};
+
+use cma_core::fs_retry::code_of;
+use cma_core::logger::create_logger;
+use cma_core::schemas::account_storage::AccountStorageV3;
+
+use crate::matching::{AccountMatchOptions, find_matching_account_index};
+
+fn is_enoent(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::NotFound || code_of(error) == Some("ENOENT")
+}
+
+/// TS `loadNormalizedStorageFromPath(path, label)` — warn + `None` on any
+/// failure (non-ENOENT failures logged; schema warnings truncated to the
+/// first 5 like the storage loader).
+pub async fn load_normalized_storage_from_path(
+    path: impl AsRef<Path>,
+    label: &str,
+) -> Option<AccountStorageV3> {
+    let log = create_logger("storage");
+    let path = path.as_ref();
+    let path_display = path.to_string_lossy();
+    match crate::parser::load_accounts_from_path(path).await {
+        Ok(parsed) => {
+            if !parsed.schema_errors.is_empty() {
+                let errors: Vec<&String> = parsed.schema_errors.iter().take(5).collect();
+                log.warn(
+                    &format!("{label} schema validation warnings"),
+                    Some(&json!({ "path": path_display, "errors": errors })),
+                );
+            }
+            parsed.normalized
+        }
+        Err(error) => {
+            if !is_enoent(&error) {
+                log.warn(
+                    &format!("Failed to load {label}"),
+                    Some(&json!({ "path": path_display, "error": error.to_string() })),
+                );
+            }
+            None
+        }
+    }
+}
+
+/// TS `mergeStorageForMigration(current, incoming, normalize, findMatch)`.
+///
+/// `current == None` ⇒ incoming verbatim. Otherwise the concatenated account
+/// list is pushed through `normalizeAccountStorage` (dedupe + index
+/// re-resolution); normalize failure returns `current` unchanged. A manual
+/// pin is captured by index BEFORE the merge and re-resolved by identity
+/// afterwards — cleared when the pinned account no longer resolves (#474).
+pub fn merge_storage_for_migration(
+    current: Option<&AccountStorageV3>,
+    incoming: &AccountStorageV3,
+) -> AccountStorageV3 {
+    let Some(current) = current else {
+        return incoming.clone();
+    };
+
+    // Resolve the pinned account by IDENTITY before merging (#474).
+    let pinned_account = current
+        .pinned_account_index
+        .and_then(|index| usize::try_from(index).ok())
+        .and_then(|index| current.accounts.get(index).cloned());
+
+    let mut payload = Map::new();
+    payload.insert("version".to_string(), Value::from(3));
+    payload.insert("activeIndex".to_string(), Value::from(current.active_index));
+    if let Some(by_family) = &current.active_index_by_family {
+        payload.insert(
+            "activeIndexByFamily".to_string(),
+            serde_json::to_value(by_family).unwrap_or(Value::Object(Map::new())),
+        );
+    }
+    let mut merged_accounts: Vec<Value> = Vec::new();
+    for account in current.accounts.iter().chain(incoming.accounts.iter()) {
+        merged_accounts.push(serde_json::to_value(account).unwrap_or(Value::Null));
+    }
+    payload.insert("accounts".to_string(), Value::Array(merged_accounts));
+    // Carry the manual pin (#474) and affinity generation through the
+    // migration; the normalizer validates/clamps them against the merged
+    // list.
+    if let Some(pinned_index) = current.pinned_account_index {
+        payload.insert("pinnedAccountIndex".to_string(), Value::from(pinned_index));
+    }
+    if let Some(affinity_generation) = current.affinity_generation {
+        payload.insert(
+            "affinityGeneration".to_string(),
+            Value::from(affinity_generation),
+        );
+    }
+
+    let Some(mut merged) = crate::normalize::normalize_account_storage(&Value::Object(payload))
+    else {
+        return current.clone();
+    };
+    let Some(pinned_account) = pinned_account else {
+        return merged;
+    };
+    // Re-point the pin at the account the user actually pinned; clear it when
+    // that account no longer resolves in the normalized list.
+    merged.pinned_account_index = find_matching_account_index(
+        &merged.accounts,
+        &pinned_account,
+        AccountMatchOptions::default(),
+    )
+    .map(|index| index as i64);
+    merged
+}
+
+// ============================================================================
+// migrateLegacyProjectStorageIfNeeded (storage.ts private; canonical here,
+// consumed by crate::load in both commit and export modes)
+// ============================================================================
+
+/// How a committed migration should persist the merged storage.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum MigrationPersist {
+    /// `saveAccounts` — takes the storage lock (default TS persist).
+    Locked,
+    /// `saveAccountsUnlocked` — the lock is already held
+    /// (`loadAccountsInternal` inside a transaction).
+    Unlocked,
+    /// `commit: false` — export mode, no writes and no legacy unlinks.
+    None,
+}
+
+async fn persist_merged(
+    persist: MigrationPersist,
+    storage: &AccountStorageV3,
+) -> Result<(), cma_core::errors::CodexError> {
+    match persist {
+        MigrationPersist::Locked => crate::save::save_accounts(storage).await,
+        MigrationPersist::Unlocked => crate::save::save_accounts_unlocked(storage).await,
+        MigrationPersist::None => Ok(()),
+    }
+}
+
+struct LiveCurrentStorage {
+    exists: bool,
+    storage: Option<AccountStorageV3>,
+}
+
+/// Export-mode-only live re-read of the current storage file (a concurrent
+/// writer creating it mid-migration wins the race). Non-ENOENT read errors
+/// PROPAGATE (spec §8.6).
+async fn read_live_current_storage_if_export_mode(
+    commit: bool,
+    current_storage_path: &str,
+) -> Result<LiveCurrentStorage, cma_core::errors::CodexError> {
+    let log = create_logger("storage");
+    if commit || !Path::new(current_storage_path).exists() {
+        return Ok(LiveCurrentStorage {
+            exists: false,
+            storage: None,
+        });
+    }
+    match crate::parser::load_accounts_from_path(current_storage_path).await {
+        Ok(parsed) => {
+            if !parsed.schema_errors.is_empty() {
+                let errors: Vec<&String> = parsed.schema_errors.iter().take(5).collect();
+                log.warn(
+                    "current account storage schema validation warnings",
+                    Some(&json!({ "path": current_storage_path, "errors": errors })),
+                );
+            }
+            Ok(LiveCurrentStorage {
+                exists: true,
+                storage: parsed.normalized,
+            })
+        }
+        Err(error) if is_enoent(&error) => Ok(LiveCurrentStorage {
+            exists: false,
+            storage: None,
+        }),
+        Err(error) => {
+            let mapped = cma_core::errors::CodexError::new(error.to_string());
+            Err(match code_of(&error) {
+                Some(code) => mapped.with_code(code).with_cause(error),
+                None => mapped.with_cause(error),
+            })
+        }
+    }
+}
+
+/// TS `migrateLegacyProjectStorageIfNeeded({persist, commit})` — merge legacy
+/// worktree/project storage files into the current project-scoped storage.
+/// Returns the merged storage when anything migrated; else the loaded
+/// current storage if the current file doesn't exist; else `None`. Commit
+/// mode never errors (persist failures are warn-only); export-mode live
+/// re-read failures propagate.
+pub async fn migrate_legacy_project_storage_if_needed(
+    persist: MigrationPersist,
+) -> Result<Option<AccountStorageV3>, cma_core::errors::CodexError> {
+    let log = create_logger("storage");
+    let commit = persist != MigrationPersist::None;
+    let state = crate::path_state::get_storage_path_state();
+    let Some(current_storage_path) = state.current_storage_path.clone() else {
+        return Ok(None);
+    };
+
+    let mut candidate_paths: Vec<String> = Vec::new();
+    for candidate in [
+        state.current_legacy_worktree_storage_path.as_ref(),
+        state.current_legacy_project_storage_path.as_ref(),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        if candidate.is_empty() || *candidate == current_storage_path {
+            continue;
+        }
+        if !candidate_paths.contains(candidate) {
+            candidate_paths.push(candidate.clone());
+        }
+    }
+    if candidate_paths.is_empty() {
+        return Ok(None);
+    }
+
+    let existing_candidate_paths: Vec<String> = candidate_paths
+        .into_iter()
+        .filter(|legacy_path| Path::new(legacy_path).exists())
+        .collect();
+    if existing_candidate_paths.is_empty() {
+        return Ok(None);
+    }
+
+    let mut target_storage =
+        load_normalized_storage_from_path(&current_storage_path, "current account storage").await;
+    let mut migrated = false;
+
+    for legacy_path in &existing_candidate_paths {
+        let live_before_merge =
+            read_live_current_storage_if_export_mode(commit, &current_storage_path).await?;
+        if live_before_merge.exists {
+            return Ok(live_before_merge.storage);
+        }
+
+        let Some(legacy_storage) =
+            load_normalized_storage_from_path(legacy_path, "legacy account storage").await
+        else {
+            continue;
+        };
+
+        let live_after_legacy_read =
+            read_live_current_storage_if_export_mode(commit, &current_storage_path).await?;
+        if live_after_legacy_read.exists {
+            return Ok(live_after_legacy_read.storage);
+        }
+
+        let merged_storage = merge_storage_for_migration(target_storage.as_ref(), &legacy_storage);
+        let fallback_storage = target_storage.clone().or(Some(legacy_storage));
+
+        if commit {
+            match persist_merged(persist, &merged_storage).await {
+                Ok(()) => {
+                    target_storage = Some(merged_storage.clone());
+                    migrated = true;
+                }
+                Err(error) => {
+                    target_storage = fallback_storage;
+                    log.warn(
+                        "Failed to persist migrated account storage",
+                        Some(&json!({
+                            "from": legacy_path,
+                            "to": current_storage_path,
+                            "error": error.to_string(),
+                        })),
+                    );
+                    continue;
+                }
+            }
+
+            match tokio::fs::remove_file(legacy_path).await {
+                Ok(()) => {}
+                Err(unlink_error) => {
+                    if !is_enoent(&unlink_error) {
+                        log.warn(
+                            "Failed to remove legacy account storage file after migration",
+                            Some(&json!({
+                                "path": legacy_path,
+                                "error": unlink_error.to_string(),
+                            })),
+                        );
+                    }
+                }
+            }
+
+            log.info(
+                "Migrated legacy project account storage",
+                Some(&json!({
+                    "from": legacy_path,
+                    "to": current_storage_path,
+                    "accounts": merged_storage.accounts.len(),
+                })),
+            );
+            continue;
+        }
+
+        target_storage = Some(merged_storage);
+        migrated = true;
+    }
+
+    if migrated {
+        return Ok(target_storage);
+    }
+    if target_storage.is_some() && !Path::new(&current_storage_path).exists() {
+        return Ok(target_storage);
+    }
+    Ok(None)
+}
+
+// ============================================================================
+// Tests (merge semantics ported from the project-migration suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::schemas::account_storage::AccountMetadataV3;
+
+    fn account(id: &str, rt: &str, last_used: i64) -> AccountMetadataV3 {
+        let mut a = AccountMetadataV3::new(rt, 1, last_used);
+        a.account_id = Some(id.to_string());
+        a.email = Some(format!("{id}@example.com"));
+        a
+    }
+
+    fn storage(accounts: Vec<AccountMetadataV3>) -> AccountStorageV3 {
+        let mut s = AccountStorageV3::empty();
+        s.accounts = accounts;
+        s
+    }
+
+    #[test]
+    fn none_current_returns_incoming() {
+        let incoming = storage(vec![account("a", "rt_a", 10)]);
+        let merged = merge_storage_for_migration(None, &incoming);
+        assert_eq!(merged, incoming);
+    }
+
+    #[test]
+    fn merges_and_dedupes_accounts() {
+        let current = storage(vec![account("a", "rt_a", 10)]);
+        let incoming = storage(vec![account("a", "rt_a_new", 20), account("b", "rt_b", 5)]);
+        let merged = merge_storage_for_migration(Some(&current), &incoming);
+        assert_eq!(merged.accounts.len(), 2);
+        // Newest content wins the duplicate identity's slot.
+        assert_eq!(merged.accounts[0].refresh_token, "rt_a_new");
+    }
+
+    #[test]
+    fn pin_is_captured_before_merge_and_reresolved_by_identity() {
+        let mut current = storage(vec![account("a", "rt_a", 10), account("b", "rt_b", 30)]);
+        current.pinned_account_index = Some(1); // pins "b"
+        current.affinity_generation = Some(4);
+        // Incoming duplicates "a" with newer content — dedupe keeps 2 slots,
+        // pin must still point at "b".
+        let incoming = storage(vec![account("a", "rt_a_new", 40)]);
+        let merged = merge_storage_for_migration(Some(&current), &incoming);
+        assert_eq!(merged.pinned_account_index, Some(1));
+        assert_eq!(merged.affinity_generation, Some(4));
+        assert_eq!(merged.accounts[1].refresh_token, "rt_b");
+    }
+
+    #[test]
+    fn unresolvable_pin_is_cleared() {
+        let mut current = storage(vec![account("a", "rt_a", 10)]);
+        current.pinned_account_index = Some(7); // dangling ⇒ no pinned account
+        let incoming = storage(vec![account("b", "rt_b", 10)]);
+        let merged = merge_storage_for_migration(Some(&current), &incoming);
+        assert_eq!(merged.pinned_account_index, None);
+    }
+
+    #[test]
+    fn keeps_current_active_index_through_normalizer() {
+        let mut current = storage(vec![account("a", "rt_a", 10), account("b", "rt_b", 20)]);
+        current.active_index = 1;
+        let incoming = storage(vec![account("c", "rt_c", 5)]);
+        let merged = merge_storage_for_migration(Some(&current), &incoming);
+        // Identity-follow keeps "b" active after the merge.
+        assert_eq!(merged.active_index, 1);
+        assert_eq!(merged.accounts.len(), 3);
+    }
+}
diff --git a/crates/storage/src/public_types.rs b/crates/storage/src/public_types.rs
new file mode 100644
index 000000000..a3fe9ed4f
--- /dev/null
+++ b/crates/storage/src/public_types.rs
@@ -0,0 +1,39 @@
+//! Port of `lib/storage/public-types.ts` — the current-version storage shapes
+//! shared with external consumers via the storage facade.
+//!
+//! In the Rust workspace the actual serde models live in
+//! `cma_core::schemas` (foundation-frozen, ARCHITECTURE §7 F3); this module
+//! re-exports them under the storage crate so downstream crates can keep
+//! importing the types from the storage layer, exactly like the TS facade
+//! re-exported them from `lib/storage.ts`.
+//!
+//! Historical migration-era shapes (V1) are also re-exported here for the
+//! `migrations` module; the TS facade deliberately did not export them, but
+//! Rust module privacy is handled by consumers importing from
+//! `cma_storage::public_types` vs `cma_storage::migrations`.
+
+pub use cma_core::schemas::account_storage::{
+    AccountIdSource, AccountMetadataV1, AccountMetadataV3, AccountStorageV1, AccountStorageV3,
+    ActiveIndexByFamily, AnyAccountStorage, CooldownReason, PersistedSwitchReason, RateLimitReason,
+    RateLimitStateV3, SwitchReason, Workspace,
+};
+pub use cma_core::schemas::flagged::{FlaggedAccountMetadataV1, FlaggedAccountStorageV1};
+pub use cma_core::schemas::journal::AccountsJournalEntry;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn re_exported_types_are_usable_from_the_storage_layer() {
+        let storage = AccountStorageV3::empty();
+        assert!(storage.accounts.is_empty());
+        assert_eq!(storage.active_index, 0);
+        let account = AccountMetadataV3::new("rt", 1, 2);
+        assert!(account.is_enabled());
+        assert_eq!(CooldownReason::RateLimit.as_str(), "rate-limit");
+        assert_eq!(SwitchReason::Manual.as_str(), "manual");
+        let flagged = FlaggedAccountStorageV1::empty();
+        assert!(flagged.accounts.is_empty());
+    }
+}
diff --git a/crates/storage/src/restore.rs b/crates/storage/src/restore.rs
new file mode 100644
index 000000000..3e41cb723
--- /dev/null
+++ b/crates/storage/src/restore.rs
@@ -0,0 +1,314 @@
+//! Port of `lib/storage/restore-assessment.ts` + `restore-metadata.ts`
+//! (spec 02 §13.2, R6).
+//!
+//! R6: `restoreEligible` / `restoreReason` are IN-MEMORY-ONLY fields. The TS
+//! code spliced them onto returned storage objects; the Rust port keeps them
+//! in the side-band [`RestoreMeta`] struct so they can NEVER be serialized
+//! into `AccountStorageV3` (the spec's own recommended consciously-accepted
+//! harmless byte difference — gotcha 20).
+
+use serde::Serialize;
+
+use cma_core::schemas::account_storage::{AccountStorageV3, ActiveIndexByFamily};
+
+use crate::backup_metadata::{
+    BackupMetadata, BackupSnapshotKind, BackupSnapshotMetadata, RestoreAssessment,
+};
+
+/// TS `RestoreReason`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+pub enum RestoreReason {
+    #[serde(rename = "empty-storage")]
+    EmptyStorage,
+    #[serde(rename = "intentional-reset")]
+    IntentionalReset,
+    #[serde(rename = "missing-storage")]
+    MissingStorage,
+}
+
+impl RestoreReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::EmptyStorage => "empty-storage",
+            Self::IntentionalReset => "intentional-reset",
+            Self::MissingStorage => "missing-storage",
+        }
+    }
+}
+
+impl std::fmt::Display for RestoreReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Side-band restore metadata (R6) — never serialized into storage.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct RestoreMeta {
+    pub restore_eligible: bool,
+    pub restore_reason: RestoreReason,
+}
+
+/// Storage + side-band restore metadata — the Rust analogue of the TS
+/// `AccountStorageV3 & { restoreEligible?, restoreReason? }` intersection.
+#[derive(Clone, Debug, PartialEq)]
+pub struct StorageWithRestoreMeta {
+    pub storage: AccountStorageV3,
+    pub restore_meta: Option<RestoreMeta>,
+}
+
+/// TS `createEmptyStorageWithRestoreMetadata` — empty v3 storage
+/// (`activeIndexByFamily: {}` present!) plus restore metadata.
+pub fn create_empty_storage_with_restore_metadata(
+    restore_eligible: bool,
+    restore_reason: RestoreReason,
+) -> StorageWithRestoreMeta {
+    let mut storage = AccountStorageV3::empty();
+    storage.active_index_by_family = Some(ActiveIndexByFamily::default());
+    StorageWithRestoreMeta {
+        storage,
+        restore_meta: Some(RestoreMeta {
+            restore_eligible,
+            restore_reason,
+        }),
+    }
+}
+
+/// TS `withRestoreMetadata` — attach restore metadata to existing storage.
+pub fn with_restore_metadata(
+    storage: AccountStorageV3,
+    restore_eligible: bool,
+    restore_reason: RestoreReason,
+) -> StorageWithRestoreMeta {
+    StorageWithRestoreMeta {
+        storage,
+        restore_meta: Some(RestoreMeta {
+            restore_eligible,
+            restore_reason,
+        }),
+    }
+}
+
+fn find_latest_snapshot(backup_metadata: &BackupMetadata) -> Option<BackupSnapshotMetadata> {
+    let latest_valid_path = backup_metadata.accounts.latest_valid_path.as_deref()?;
+    backup_metadata
+        .accounts
+        .snapshots
+        .iter()
+        .find(|snapshot| snapshot.path == latest_valid_path)
+        .cloned()
+}
+
+/// TS `buildRestoreAssessment` (restore-assessment.ts) — pure.
+pub fn build_restore_assessment(
+    storage_path: &str,
+    backup_metadata: BackupMetadata,
+    has_reset_marker: bool,
+) -> RestoreAssessment {
+    if has_reset_marker {
+        return RestoreAssessment {
+            storage_path: storage_path.to_string(),
+            restore_eligible: false,
+            restore_reason: Some(RestoreReason::IntentionalReset),
+            latest_snapshot: None,
+            backup_metadata,
+        };
+    }
+
+    let primary_snapshot = backup_metadata
+        .accounts
+        .snapshots
+        .iter()
+        .find(|snapshot| snapshot.kind == BackupSnapshotKind::AccountsPrimary)
+        .cloned();
+    let primary_exists = primary_snapshot
+        .as_ref()
+        .is_some_and(|snapshot| snapshot.exists);
+    if !primary_exists {
+        let latest_snapshot = find_latest_snapshot(&backup_metadata);
+        return RestoreAssessment {
+            storage_path: storage_path.to_string(),
+            restore_eligible: true,
+            restore_reason: Some(RestoreReason::MissingStorage),
+            latest_snapshot,
+            backup_metadata,
+        };
+    }
+
+    let primary_snapshot = primary_snapshot.expect("primary exists");
+    if primary_snapshot.valid && primary_snapshot.account_count == Some(0) {
+        return RestoreAssessment {
+            storage_path: storage_path.to_string(),
+            restore_eligible: true,
+            restore_reason: Some(RestoreReason::EmptyStorage),
+            latest_snapshot: Some(primary_snapshot),
+            backup_metadata,
+        };
+    }
+
+    let latest_snapshot = find_latest_snapshot(&backup_metadata);
+    RestoreAssessment {
+        storage_path: storage_path.to_string(),
+        restore_eligible: false,
+        restore_reason: None,
+        latest_snapshot,
+        backup_metadata,
+    }
+}
+
+/// TS `getRestoreAssessment()` (storage.ts export).
+pub async fn get_restore_assessment() -> RestoreAssessment {
+    let storage_path = std::path::PathBuf::from(crate::facade::get_storage_path())
+        .to_string_lossy()
+        .into_owned();
+    let reset_marker_path = crate::backup_paths::get_intentional_reset_marker_path(&storage_path);
+    let backup_metadata = crate::backup_metadata::get_backup_metadata().await;
+    build_restore_assessment(
+        &storage_path,
+        backup_metadata,
+        std::path::Path::new(&reset_marker_path).exists(),
+    )
+}
+
+// ============================================================================
+// Tests (ported from the restore-assessment suites)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::backup_metadata::{BackupMetadataSection, build_metadata_section};
+
+    fn snapshot(
+        kind: BackupSnapshotKind,
+        path: &str,
+        exists: bool,
+        valid: bool,
+        account_count: Option<usize>,
+        mtime_ms: Option<f64>,
+    ) -> BackupSnapshotMetadata {
+        BackupSnapshotMetadata {
+            kind,
+            path: path.to_string(),
+            exists,
+            valid,
+            account_count,
+            mtime_ms,
+            ..Default::default()
+        }
+    }
+
+    fn metadata_with(accounts: Vec<BackupSnapshotMetadata>) -> BackupMetadata {
+        BackupMetadata {
+            accounts: build_metadata_section("/x/accounts.json", accounts),
+            flagged_accounts: BackupMetadataSection::default(),
+        }
+    }
+
+    #[test]
+    fn reset_marker_blocks_restore() {
+        let assessment =
+            build_restore_assessment("/x/accounts.json", metadata_with(Vec::new()), true);
+        assert!(!assessment.restore_eligible);
+        assert_eq!(
+            assessment.restore_reason,
+            Some(RestoreReason::IntentionalReset)
+        );
+        assert!(assessment.latest_snapshot.is_none());
+    }
+
+    #[test]
+    fn missing_primary_is_eligible_with_latest_valid_snapshot() {
+        let metadata = metadata_with(vec![
+            snapshot(
+                BackupSnapshotKind::AccountsPrimary,
+                "/x/accounts.json",
+                false,
+                false,
+                None,
+                None,
+            ),
+            snapshot(
+                BackupSnapshotKind::AccountsBackup,
+                "/x/accounts.json.bak",
+                true,
+                true,
+                Some(2),
+                Some(10.0),
+            ),
+        ]);
+        let assessment = build_restore_assessment("/x/accounts.json", metadata, false);
+        assert!(assessment.restore_eligible);
+        assert_eq!(assessment.restore_reason, Some(RestoreReason::MissingStorage));
+        assert_eq!(
+            assessment.latest_snapshot.as_ref().map(|s| s.path.as_str()),
+            Some("/x/accounts.json.bak")
+        );
+    }
+
+    #[test]
+    fn empty_primary_is_eligible_with_primary_as_latest() {
+        let metadata = metadata_with(vec![snapshot(
+            BackupSnapshotKind::AccountsPrimary,
+            "/x/accounts.json",
+            true,
+            true,
+            Some(0),
+            Some(10.0),
+        )]);
+        let assessment = build_restore_assessment("/x/accounts.json", metadata, false);
+        assert!(assessment.restore_eligible);
+        assert_eq!(assessment.restore_reason, Some(RestoreReason::EmptyStorage));
+        assert_eq!(
+            assessment
+                .latest_snapshot
+                .as_ref()
+                .map(|s| s.kind),
+            Some(BackupSnapshotKind::AccountsPrimary)
+        );
+    }
+
+    #[test]
+    fn healthy_primary_is_not_eligible() {
+        let metadata = metadata_with(vec![snapshot(
+            BackupSnapshotKind::AccountsPrimary,
+            "/x/accounts.json",
+            true,
+            true,
+            Some(3),
+            Some(10.0),
+        )]);
+        let assessment = build_restore_assessment("/x/accounts.json", metadata, false);
+        assert!(!assessment.restore_eligible);
+        assert_eq!(assessment.restore_reason, None);
+        // latestSnapshot still reported for the doctor view.
+        assert!(assessment.latest_snapshot.is_some());
+    }
+
+    #[test]
+    fn empty_storage_helper_populates_active_index_by_family_object() {
+        let created = create_empty_storage_with_restore_metadata(
+            false,
+            RestoreReason::IntentionalReset,
+        );
+        // TS writes `activeIndexByFamily: {}` — present, empty.
+        let value = serde_json::to_value(&created.storage).unwrap();
+        assert_eq!(value["activeIndexByFamily"], serde_json::json!({}));
+        let meta = created.restore_meta.unwrap();
+        assert!(!meta.restore_eligible);
+        assert_eq!(meta.restore_reason, RestoreReason::IntentionalReset);
+        // R6: the serialized storage never carries restore fields.
+        assert!(value.get("restoreEligible").is_none());
+        assert!(value.get("restoreReason").is_none());
+    }
+
+    #[test]
+    fn with_restore_metadata_wraps_existing_storage() {
+        let storage = AccountStorageV3::empty();
+        let wrapped = with_restore_metadata(storage, true, RestoreReason::EmptyStorage);
+        assert_eq!(
+            wrapped.restore_meta.unwrap().restore_reason,
+            RestoreReason::EmptyStorage
+        );
+    }
+}
diff --git a/crates/storage/src/save.rs b/crates/storage/src/save.rs
new file mode 100644
index 000000000..d795fa458
--- /dev/null
+++ b/crates/storage/src/save.rs
@@ -0,0 +1,336 @@
+//! Port of the accounts save pipeline: `lib/storage/account-save.ts`
+//! (`saveAccountsToDisk`) + `account-save-entry.ts` + the
+//! `saveAccountsUnlocked` wiring from `lib/storage.ts`.
+//!
+//! ORDERED pipeline (spec 02 §7.2 — order is load-bearing):
+//! lock → dir 0700 (+POSIX chmod re-assert) → gitignore → synthetic-fixture
+//! guard → rotating backup (warn-only) → WAL-first sha256-checksummed compact
+//! entry → temp write → zero-byte EEMPTY check → rename (EPERM/EBUSY ×5,
+//! `10·2^(n-1)` ms, no jitter) → reset-marker unlink → save-timestamp →
+//! WAL unlink.
+//!
+//! Error path: best-effort temp cleanup (retried, swallowed), error log
+//! `"Failed to save accounts"`, then EVERYTHING (including the synthetic
+//! guard's own StorageError and the EEMPTY check) is wrapped as
+//! `StorageError("Failed to save accounts: <msg>", <code|"UNKNOWN">, path,
+//! hint, cause)` — matching the TS catch-all `createStorageError`.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use cma_core::errors::CodexError;
+use cma_core::fs_retry::{
+    Backoff, RetryOptions, code_of, io_error_with_code, with_file_operation_retry, with_retry,
+};
+use cma_core::json_io::stringify_pretty2;
+use cma_core::logger::create_logger;
+use cma_core::schemas::journal::AccountsJournalEntry;
+use cma_core::temp_path::temp_path_for_str;
+use cma_core::utils::now_ms;
+use serde_json::json;
+
+use crate::backup_paths::{
+    get_accounts_backup_path, get_accounts_wal_path, get_intentional_reset_marker_path,
+};
+use crate::facade;
+use crate::fixture_guards::looks_like_synthetic_fixture_storage;
+use crate::misc::{compute_sha256, ensure_codex_gitignore_entry, format_storage_error_hint};
+use crate::path_state::get_storage_path_state;
+use crate::public_types::AccountStorageV3;
+
+/// Write a file with `mode` applied atomically at open(2) on unix (no-op mode
+/// on Windows — Node parity). Node passes `mode` into `fs.writeFile`, so the
+/// WAL/temp files (which hold every account's refresh token) never exist with
+/// broader permissions — no write-then-chmod window, no 0644 crash residue.
+pub(crate) fn write_file_with_mode(path: &Path, content: &str, mode: u32) -> io::Result<()> {
+    cma_core::json_io::write_text_file_with_mode_sync(path, content, Some(mode))
+}
+
+/// `ensureDirectory` — `mkdir -p` with mode 0700 plus a best-effort POSIX
+/// `chmod 0o700` re-assert for pre-existing dirs (account storage holds
+/// OAuth token material).
+async fn ensure_directory(path: &str) -> io::Result<()> {
+    let path = Path::new(path);
+    let Some(dir) = path.parent() else {
+        return Ok(());
+    };
+    if dir.as_os_str().is_empty() {
+        return Ok(());
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        use std::os::unix::fs::PermissionsExt;
+        let mut builder = fs::DirBuilder::new();
+        builder.recursive(true).mode(0o700);
+        builder.create(dir)?;
+        // mkdir's mode only applies to freshly-created dirs; re-assert.
+        let _ = fs::set_permissions(dir, fs::Permissions::from_mode(0o700));
+    }
+    #[cfg(not(unix))]
+    {
+        fs::create_dir_all(dir)?;
+    }
+    Ok(())
+}
+
+/// `ensureGitignore` — project-scoped saves only (storage-path state set).
+async fn ensure_gitignore(storage_path: &str) {
+    let state = get_storage_path_state();
+    if state.current_storage_path.is_none() {
+        return;
+    }
+    let project_root = state.current_project_root.map(PathBuf::from);
+    ensure_codex_gitignore_entry(Path::new(storage_path), project_root.as_deref()).await;
+}
+
+/// The wrapped save failure (`createStorageError`).
+fn create_storage_error(error: &io::Error, path: &str) -> CodexError {
+    let code = code_of(error).unwrap_or("UNKNOWN").to_string();
+    let hint = format_storage_error_hint(error, path);
+    let message = format!("Failed to save accounts: {error}");
+    CodexError::storage(
+        message,
+        code,
+        path,
+        hint,
+        Some(Box::new(io_error_with_code_dup(error))),
+    )
+}
+
+/// Duplicate an io::Error for the cause chain (io::Error is not Clone).
+fn io_error_with_code_dup(error: &io::Error) -> io::Error {
+    match code_of(error) {
+        Some(code) => {
+            // Re-mint with the same code string so downstream code-matching
+            // on the cause keeps working. The static-code table covers every
+            // code the pipeline can produce; unknown codes fall through.
+            for known in [
+                "EBUSY", "EPERM", "EAGAIN", "ENOTEMPTY", "EACCES", "ENOENT", "ENOSPC", "EEMPTY",
+                "EINVALID", "EEXIST", "EROFS", "EINVAL",
+            ] {
+                if code == known {
+                    return io_error_with_code(known, error.to_string());
+                }
+            }
+            io::Error::other(error.to_string())
+        }
+        None => io::Error::other(error.to_string()),
+    }
+}
+
+/// `saveAccounts(storage)` = `withStorageLock(saveAccountsUnlocked(storage))`.
+pub async fn save_accounts(storage: &AccountStorageV3) -> Result<(), CodexError> {
+    crate::transactions::with_storage_lock(|| async { save_accounts_unlocked(storage).await })
+        .await
+}
+
+/// `saveAccountsUnlocked(storage)` — the full ordered pipeline. Callers MUST
+/// already hold the storage lock (used directly by transactions and
+/// load-side migration persists where the lock is already held).
+pub async fn save_accounts_unlocked(storage: &AccountStorageV3) -> Result<(), CodexError> {
+    let log = create_logger("storage");
+    let path = facade::get_storage_path();
+    let reset_marker_path = get_intentional_reset_marker_path(&path);
+    let wal_path = get_accounts_wal_path(&path);
+    let backup_path = get_accounts_backup_path(&path);
+    let storage_backup_enabled = facade::storage_backup_enabled() && Path::new(&path).exists();
+    let temp_path = temp_path_for_str(&path);
+
+    let result: io::Result<()> = async {
+        ensure_directory(&path).await?;
+        ensure_gitignore(&path).await;
+
+        // Synthetic fixture guard (spec 02 §7.2 step 3 / gotcha 13).
+        if looks_like_synthetic_fixture_storage(Some(storage)) {
+            let existing =
+                crate::project_migration::load_normalized_storage_from_path(
+                    &path,
+                    "existing account storage",
+                )
+                .await;
+            if let Some(existing) = existing
+                && !existing.accounts.is_empty()
+                && !looks_like_synthetic_fixture_storage(Some(&existing))
+            {
+                // Wrapped by the catch-all below exactly like the TS
+                // StorageError flowing into createStorageError.
+                return Err(io_error_with_code(
+                    "EINVALID",
+                    "Refusing to overwrite non-synthetic account storage with synthetic fixture payload",
+                ));
+            }
+        }
+
+        if storage_backup_enabled
+            && let Err(backup_error) =
+                crate::backups::create_rotating_accounts_backup(&path).await
+        {
+            log.warn(
+                "Failed to create account storage backup",
+                Some(&json!({
+                    "path": path,
+                    "backupPath": backup_path,
+                    "error": backup_error.to_string(),
+                })),
+            );
+        }
+
+        let content = stringify_pretty2(storage);
+
+        // WAL first (gotcha 2): compact sha256-checksummed entry, retried on
+        // the shared transient-code taxonomy, mode 0600.
+        let journal_entry = AccountsJournalEntry::new(
+            now_ms(),
+            path.clone(),
+            compute_sha256(&content),
+            content.clone(),
+        );
+        let journal_json = cma_core::json_io::stringify_compact(&journal_entry);
+        with_file_operation_retry(|| {
+            let wal_path = wal_path.clone();
+            let journal_json = journal_json.clone();
+            async move { write_file_with_mode(Path::new(&wal_path), &journal_json, 0o600) }
+        })
+        .await?;
+
+        // Temp write (same retry wrapper, mode 0600).
+        with_file_operation_retry(|| {
+            let temp_path = temp_path.clone();
+            let content = content.clone();
+            async move { write_file_with_mode(Path::new(&temp_path), &content, 0o600) }
+        })
+        .await?;
+
+        // Zero-byte EEMPTY check (gotcha 15: catches full-disk/AV truncation).
+        let stats = fs::metadata(&temp_path)?;
+        if stats.len() == 0 {
+            return Err(io_error_with_code("EEMPTY", "File written but size is 0"));
+        }
+
+        // Rename retries ONLY EPERM/EBUSY (gotcha 16), 5 × 10·2^(n-1) ms.
+        with_retry(
+            || {
+                let temp_path = temp_path.clone();
+                let path = path.clone();
+                async move { fs::rename(&temp_path, &path) }
+            },
+            RetryOptions::<io::Error>::new(
+                5,
+                Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1)))),
+            )
+            .with_codes(&["EPERM", "EBUSY"]),
+        )
+        .await?;
+
+        // Best-effort reset-marker unlink (the marker persists across clears
+        // until this very unlink — spec 02 §3.4).
+        let _ = fs::remove_file(&reset_marker_path);
+
+        facade::set_last_accounts_save_timestamp(now_ms());
+
+        // Best-effort WAL unlink AFTER the successful rename (gotcha 2).
+        let _ = fs::remove_file(&wal_path);
+        Ok(())
+    }
+    .await;
+
+    match result {
+        Ok(()) => Ok(()),
+        Err(error) => {
+            // Best-effort temp cleanup — retried so a transient lock cannot
+            // strand a secret-bearing *.tmp, then swallowed.
+            let _ = with_file_operation_retry(|| {
+                let temp_path = temp_path.clone();
+                async move { fs::remove_file(&temp_path) }
+            })
+            .await;
+            log.error(
+                "Failed to save accounts",
+                Some(&json!({
+                    "path": path,
+                    "error": error.to_string(),
+                })),
+            );
+            Err(create_storage_error(&error, &path))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn storage_error_wraps_message_code_path_and_hint() {
+        let error = io_error_with_code("EEMPTY", "File written but size is 0");
+        let wrapped = create_storage_error(&error, "/x/a.json");
+        assert_eq!(
+            wrapped.message(),
+            "Failed to save accounts: File written but size is 0"
+        );
+        assert_eq!(wrapped.code(), "EEMPTY");
+        assert_eq!(wrapped.path(), Some("/x/a.json"));
+        assert!(wrapped.hint().is_some());
+    }
+
+    #[test]
+    fn storage_error_defaults_unknown_code() {
+        let error = io::Error::other("mystery failure");
+        let wrapped = create_storage_error(&error, "/x/a.json");
+        assert_eq!(wrapped.code(), "UNKNOWN");
+        assert_eq!(wrapped.message(), "Failed to save accounts: mystery failure");
+    }
+
+    #[test]
+    fn synthetic_guard_error_carries_the_frozen_inner_message() {
+        let inner = io_error_with_code(
+            "EINVALID",
+            "Refusing to overwrite non-synthetic account storage with synthetic fixture payload",
+        );
+        let wrapped = create_storage_error(&inner, "/x/a.json");
+        assert_eq!(wrapped.code(), "EINVALID");
+        assert_eq!(
+            wrapped.message(),
+            "Failed to save accounts: Refusing to overwrite non-synthetic account storage with synthetic fixture payload"
+        );
+    }
+
+    #[tokio::test]
+    async fn write_file_with_mode_creates_content() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("f.json");
+        write_file_with_mode(&path, "{}", 0o600).unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "{}");
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+            // Applied at open(2): never any bits outside 0600 (default umask
+            // leaves exactly 0600; a write-then-chmod impl would transiently
+            // expose 0644 and could leave it behind on crash).
+            assert_eq!(mode & !0o600, 0, "no bits outside 0600: {mode:o}");
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn write_file_with_mode_does_not_chmod_pre_existing_files() {
+        // Node's fs.writeFile uses `mode` only when O_CREAT creates the file;
+        // a pre-existing file keeps its permissions. This pins the fix from
+        // write-then-chmod (which always chmodded) to mode-at-open.
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("wal.json");
+        fs::write(&path, "old").unwrap();
+        fs::set_permissions(&path, fs::Permissions::from_mode(0o640)).unwrap();
+        write_file_with_mode(&path, "new", 0o600).unwrap();
+        assert_eq!(fs::read_to_string(&path).unwrap(), "new");
+        assert_eq!(
+            fs::metadata(&path).unwrap().permissions().mode() & 0o777,
+            0o640,
+            "pre-existing perms preserved (Node parity)"
+        );
+    }
+}
diff --git a/crates/storage/src/save_retry.rs b/crates/storage/src/save_retry.rs
new file mode 100644
index 000000000..7d1252a2a
--- /dev/null
+++ b/crates/storage/src/save_retry.rs
@@ -0,0 +1,127 @@
+//! Port of `lib/storage/save-retry.ts` — retry wrapper for account-storage
+//! writes used by `lib/accounts.ts` / codex-manager callers.
+//!
+//! Behavior source: spec 02 §11 / §16: up to 4 TOTAL attempts, retrying only
+//! codes {EBUSY, EPERM}, delay `10·2^attempt` ms with a 0-based attempt
+//! counter (10/20/40 between the four attempts).
+
+use std::time::Duration;
+
+use cma_core::errors::CodexError;
+
+const RETRYABLE_STORAGE_WRITE_CODES: [&str; 2] = ["EBUSY", "EPERM"];
+
+/// `isRetryableStorageWriteError(error)` — code ∈ {EBUSY, EPERM}. The TS
+/// helper read `error.code`; the port takes the code string (CodexError's
+/// `code()` for StorageErrors carries the errno).
+pub fn is_retryable_storage_write_code(code: &str) -> bool {
+    RETRYABLE_STORAGE_WRITE_CODES.contains(&code)
+}
+
+/// `isRetryableStorageWriteError` over the storage error type.
+pub fn is_retryable_storage_write_error(error: &CodexError) -> bool {
+    is_retryable_storage_write_code(error.code())
+}
+
+/// `saveAccountsWithRetry(storage, saveAccounts)` — generic over the save
+/// callable so tests and the account manager can inject their own persist.
+pub async fn save_accounts_with_retry_via<S, F, Fut>(
+    storage: &S,
+    mut save_accounts: F,
+) -> Result<(), CodexError>
+where
+    F: FnMut(&S) -> Fut,
+    Fut: Future<Output = Result<(), CodexError>>,
+{
+    let mut attempt: u32 = 0;
+    loop {
+        match save_accounts(storage).await {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if !is_retryable_storage_write_error(&error) || attempt >= 3 {
+                    return Err(error);
+                }
+                let delay_ms = 10u64.saturating_mul(2u64.saturating_pow(attempt));
+                tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// Convenience wrapper bound to the real `saveAccounts`.
+pub async fn save_accounts_with_retry(
+    storage: &crate::public_types::AccountStorageV3,
+) -> Result<(), CodexError> {
+    // The generic runner's future type cannot borrow from the closure
+    // argument, so clone per attempt (retries are rare; the pipeline clones
+    // the storage for the WAL entry anyway).
+    save_accounts_with_retry_via(storage, |s| {
+        let s = s.clone();
+        async move { crate::save::save_accounts(&s).await }
+    })
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU32, Ordering};
+
+    fn storage_error(code: &str) -> CodexError {
+        CodexError::storage("Failed to save accounts: x", code, "/x/a.json", "hint", None)
+    }
+
+    #[test]
+    fn retryable_codes_are_ebusy_and_eperm_only() {
+        assert!(is_retryable_storage_write_code("EBUSY"));
+        assert!(is_retryable_storage_write_code("EPERM"));
+        assert!(!is_retryable_storage_write_code("EACCES"));
+        assert!(!is_retryable_storage_write_code("ENOENT"));
+        assert!(!is_retryable_storage_write_code("UNKNOWN"));
+        assert!(is_retryable_storage_write_error(&storage_error("EBUSY")));
+        assert!(!is_retryable_storage_write_error(&storage_error("EINVALID")));
+    }
+
+    #[tokio::test]
+    async fn retries_until_success_within_four_attempts() {
+        let calls = AtomicU32::new(0);
+        let result = save_accounts_with_retry_via(&(), |_| {
+            let n = calls.fetch_add(1, Ordering::SeqCst);
+            async move {
+                if n < 2 {
+                    Err(storage_error("EBUSY"))
+                } else {
+                    Ok(())
+                }
+            }
+        })
+        .await;
+        assert!(result.is_ok());
+        assert_eq!(calls.load(Ordering::SeqCst), 3);
+    }
+
+    #[tokio::test]
+    async fn gives_up_after_four_total_attempts() {
+        let calls = AtomicU32::new(0);
+        let result = save_accounts_with_retry_via(&(), |_| {
+            calls.fetch_add(1, Ordering::SeqCst);
+            async { Err(storage_error("EPERM")) }
+        })
+        .await;
+        assert!(result.is_err());
+        assert_eq!(calls.load(Ordering::SeqCst), 4);
+    }
+
+    #[tokio::test]
+    async fn non_retryable_errors_fail_immediately() {
+        let calls = AtomicU32::new(0);
+        let result = save_accounts_with_retry_via(&(), |_| {
+            calls.fetch_add(1, Ordering::SeqCst);
+            async { Err(storage_error("ENOSPC")) }
+        })
+        .await;
+        assert!(result.is_err());
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+}
diff --git a/crates/storage/src/snapshot.rs b/crates/storage/src/snapshot.rs
new file mode 100644
index 000000000..e8b60a308
--- /dev/null
+++ b/crates/storage/src/snapshot.rs
@@ -0,0 +1,252 @@
+//! Port of `lib/storage/account-snapshot.ts` (spec 02 §13.1).
+//!
+//! - [`stat_snapshot`]: EBUSY/EPERM ⇒ "exists but locked" (`exists: true`
+//!   without bytes/mtime — gotcha 27); ENOENT silent; other errors warn.
+//! - [`describe_account_snapshot`]: load + normalize with up to 2 stat
+//!   refreshes while bytes/mtime are missing; ENOENT load races count as
+//!   invalid-but-present snapshots.
+
+use std::io;
+use std::path::Path;
+use std::time::UNIX_EPOCH;
+
+use serde_json::json;
+
+use cma_core::fs_retry::code_of;
+use cma_core::logger::create_logger;
+
+use crate::backup_metadata::{BackupSnapshotKind, BackupSnapshotMetadata};
+
+/// TS `SnapshotStats`.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct SnapshotStats {
+    pub exists: bool,
+    pub bytes: Option<u64>,
+    pub mtime_ms: Option<f64>,
+}
+
+fn mtime_ms_of(metadata: &std::fs::Metadata) -> f64 {
+    metadata
+        .modified()
+        .ok()
+        .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok())
+        .map(|duration| duration.as_secs_f64() * 1000.0)
+        .unwrap_or(0.0)
+}
+
+fn is_enoent(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::NotFound || code_of(error) == Some("ENOENT")
+}
+
+/// TS `statSnapshot` — size/mtime metadata for a backup candidate.
+pub async fn stat_snapshot(path: &str) -> SnapshotStats {
+    let log = create_logger("storage");
+    match tokio::fs::metadata(path).await {
+        Ok(metadata) => SnapshotStats {
+            exists: true,
+            bytes: Some(metadata.len()),
+            mtime_ms: Some(mtime_ms_of(&metadata)),
+        },
+        Err(error) => {
+            let error_code = code_of(&error);
+            if error_code == Some("EBUSY") || error_code == Some("EPERM") {
+                log.warn(
+                    "Backup candidate is locked",
+                    Some(&json!({ "path": path, "error": error.to_string() })),
+                );
+                return SnapshotStats {
+                    exists: true,
+                    bytes: None,
+                    mtime_ms: None,
+                };
+            }
+            if !is_enoent(&error) {
+                log.warn(
+                    "Failed to stat backup candidate",
+                    Some(&json!({ "path": path, "error": error.to_string() })),
+                );
+            }
+            SnapshotStats::default()
+        }
+    }
+}
+
+/// TS `describeAccountSnapshot` — backup metadata for an account snapshot.
+pub async fn describe_account_snapshot(
+    path: &str,
+    kind: BackupSnapshotKind,
+    index: Option<usize>,
+) -> BackupSnapshotMetadata {
+    let log = create_logger("storage");
+    let stats = stat_snapshot(path).await;
+    if !stats.exists {
+        return BackupSnapshotMetadata {
+            kind,
+            path: path.to_string(),
+            index,
+            exists: false,
+            valid: false,
+            ..Default::default()
+        };
+    }
+    match crate::parser::load_accounts_from_path(Path::new(path)).await {
+        Ok(parsed) => {
+            let mut resolved_stats = stats;
+            for _ in 0..2 {
+                if resolved_stats.bytes.is_some() && resolved_stats.mtime_ms.is_some() {
+                    break;
+                }
+                let refreshed_stats = stat_snapshot(path).await;
+                if refreshed_stats.exists {
+                    resolved_stats = refreshed_stats;
+                }
+            }
+            BackupSnapshotMetadata {
+                kind,
+                path: path.to_string(),
+                index,
+                exists: true,
+                valid: parsed.normalized.is_some(),
+                bytes: Some(resolved_stats.bytes.unwrap_or(0)),
+                mtime_ms: Some(resolved_stats.mtime_ms.unwrap_or(0.0)),
+                version: parsed.stored_version,
+                account_count: parsed
+                    .normalized
+                    .as_ref()
+                    .map(|normalized| normalized.accounts.len()),
+                flagged_count: None,
+                schema_errors: if parsed.schema_errors.is_empty() {
+                    None
+                } else {
+                    Some(parsed.schema_errors)
+                },
+            }
+        }
+        Err(error) => {
+            if !is_enoent(&error) {
+                log.warn(
+                    "Failed to inspect account snapshot",
+                    Some(&json!({ "path": path, "error": error.to_string() })),
+                );
+            }
+            BackupSnapshotMetadata {
+                kind,
+                path: path.to_string(),
+                index,
+                exists: true,
+                valid: false,
+                bytes: stats.bytes,
+                mtime_ms: stats.mtime_ms,
+                ..Default::default()
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Tests (ported from the account-snapshot suites; explicit-path filesystem
+// tests via tempfile — no env mutation)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn valid_storage_json() -> String {
+        serde_json::to_string(&json!({
+            "version": 3,
+            "accounts": [{ "refreshToken": "rt", "addedAt": 1, "lastUsed": 2 }],
+            "activeIndex": 0,
+        }))
+        .unwrap()
+    }
+
+    #[tokio::test]
+    async fn stat_snapshot_missing_file_is_default() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("missing.json");
+        let stats = stat_snapshot(&path.to_string_lossy()).await;
+        assert_eq!(stats, SnapshotStats::default());
+        assert!(!stats.exists);
+    }
+
+    #[tokio::test]
+    async fn stat_snapshot_reports_bytes_and_mtime() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        std::fs::write(&path, "hello").unwrap();
+        let stats = stat_snapshot(&path.to_string_lossy()).await;
+        assert!(stats.exists);
+        assert_eq!(stats.bytes, Some(5));
+        assert!(stats.mtime_ms.unwrap_or(0.0) > 0.0);
+    }
+
+    #[tokio::test]
+    async fn describe_missing_snapshot_is_nonexistent_and_invalid() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("missing.json");
+        let snapshot = describe_account_snapshot(
+            &path.to_string_lossy(),
+            BackupSnapshotKind::AccountsPrimary,
+            None,
+        )
+        .await;
+        assert!(!snapshot.exists);
+        assert!(!snapshot.valid);
+        assert_eq!(snapshot.bytes, None);
+    }
+
+    #[tokio::test]
+    async fn describe_valid_snapshot_reports_counts_and_stats() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        std::fs::write(&path, valid_storage_json()).unwrap();
+        let snapshot = describe_account_snapshot(
+            &path.to_string_lossy(),
+            BackupSnapshotKind::AccountsBackup,
+            Some(1),
+        )
+        .await;
+        assert!(snapshot.exists);
+        assert!(snapshot.valid);
+        assert_eq!(snapshot.kind, BackupSnapshotKind::AccountsBackup);
+        assert_eq!(snapshot.index, Some(1));
+        assert_eq!(snapshot.account_count, Some(1));
+        assert_eq!(snapshot.version, Some(3));
+        assert!(snapshot.bytes.unwrap_or(0) > 0);
+        assert!(snapshot.mtime_ms.unwrap_or(0.0) > 0.0);
+    }
+
+    #[tokio::test]
+    async fn describe_corrupt_snapshot_is_present_but_invalid() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        std::fs::write(&path, "{ this is not json").unwrap();
+        let snapshot = describe_account_snapshot(
+            &path.to_string_lossy(),
+            BackupSnapshotKind::AccountsPrimary,
+            None,
+        )
+        .await;
+        assert!(snapshot.exists);
+        assert!(!snapshot.valid);
+    }
+
+    #[tokio::test]
+    async fn describe_unnormalizable_snapshot_is_invalid_but_existing() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("accounts.json");
+        // Parses as JSON but fails normalization (unknown version).
+        std::fs::write(&path, r#"{"version":42}"#).unwrap();
+        let snapshot = describe_account_snapshot(
+            &path.to_string_lossy(),
+            BackupSnapshotKind::AccountsPrimary,
+            None,
+        )
+        .await;
+        assert!(snapshot.exists);
+        assert!(!snapshot.valid);
+        assert_eq!(snapshot.version, Some(42));
+    }
+}
diff --git a/crates/storage/src/transactions.rs b/crates/storage/src/transactions.rs
new file mode 100644
index 000000000..bc7275236
--- /dev/null
+++ b/crates/storage/src/transactions.rs
@@ -0,0 +1,379 @@
+//! Port of `lib/storage/transactions.ts` + the concrete transaction wiring
+//! from `lib/storage.ts` (spec 02 §11).
+//!
+//! - [`with_storage_lock`]: the global storage mutex — a fair (FIFO)
+//!   `tokio::sync::Mutex`, **non-reentrant** (nested acquisition deadlocks,
+//!   exactly like the TS promise chain). The critical section runs with a
+//!   task-local "held" flag; [`is_storage_lock_held`] reads it so code that
+//!   may run both standalone and nested (flagged recovery persistence during
+//!   a transaction) can choose the unlocked save instead of deadlocking.
+//! - Transaction snapshot context: task-local [`TransactionSnapshotState`]
+//!   consulted by `export_accounts` (spec gotcha 11) so exports inside a
+//!   transaction reuse the in-memory snapshot instead of re-acquiring the
+//!   lock.
+//! - [`with_account_storage_transaction`],
+//!   [`with_account_and_flagged_storage_transaction`] (accounts rollback on
+//!   flagged-save failure; `AggregateError` message FROZEN),
+//!   [`with_flagged_storage_transaction`] (flagged rollback; message FROZEN).
+//!
+//! Task-local values do NOT cross `tokio::spawn` — any spawn inside a scoped
+//! region must re-wrap explicitly (ARCHITECTURE §5.4).
+
+use std::future::Future;
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex as StdMutex};
+
+use serde_json::json;
+
+use cma_core::errors::CodexError;
+use cma_core::logger::create_logger;
+use cma_core::schemas::account_storage::AccountStorageV3;
+use cma_core::schemas::flagged::FlaggedAccountStorageV1;
+
+static STORAGE_MUTEX: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+tokio::task_local! {
+    static STORAGE_LOCK_HELD: ();
+    static TRANSACTION_SNAPSHOT: Arc<TransactionSnapshotState>;
+}
+
+/// Reports whether the caller is already running inside a
+/// [`with_storage_lock`] critical section (TS `isStorageLockHeld`).
+pub fn is_storage_lock_held() -> bool {
+    STORAGE_LOCK_HELD.try_with(|_| ()).is_ok()
+}
+
+/// Snapshot state of an active account-storage transaction (TS
+/// `TransactionSnapshotState`). `snapshot` is interior-mutable because
+/// `persist` updates it while the handler still holds the state.
+#[derive(Debug)]
+pub struct TransactionSnapshotState {
+    pub storage_path: PathBuf,
+    pub active: bool,
+    snapshot: StdMutex<Option<AccountStorageV3>>,
+}
+
+impl TransactionSnapshotState {
+    pub fn new(storage_path: PathBuf, snapshot: Option<AccountStorageV3>) -> Self {
+        Self {
+            storage_path,
+            active: true,
+            snapshot: StdMutex::new(snapshot),
+        }
+    }
+
+    /// Current snapshot (cloned).
+    pub fn snapshot(&self) -> Option<AccountStorageV3> {
+        self.snapshot.lock().expect("snapshot mutex poisoned").clone()
+    }
+
+    pub fn set_snapshot(&self, snapshot: Option<AccountStorageV3>) {
+        *self.snapshot.lock().expect("snapshot mutex poisoned") = snapshot;
+    }
+}
+
+/// TS `getTransactionSnapshotState` — the active transaction's snapshot
+/// state, when the caller runs inside one.
+pub fn get_transaction_snapshot_state() -> Option<Arc<TransactionSnapshotState>> {
+    TRANSACTION_SNAPSHOT.try_with(Arc::clone).ok()
+}
+
+/// TS `runInTransactionSnapshotContext` — run `fut` with the given snapshot
+/// state visible to [`get_transaction_snapshot_state`].
+pub async fn run_in_transaction_snapshot_context<T>(
+    state: Arc<TransactionSnapshotState>,
+    fut: impl Future<Output = T>,
+) -> T {
+    TRANSACTION_SNAPSHOT.scope(state, fut).await
+}
+
+/// TS `withStorageLock(fn)` — global FIFO mutex around all storage writes.
+/// **Non-reentrant**: acquiring it while already held deadlocks (TS parity).
+pub async fn with_storage_lock<T, Fut>(f: impl FnOnce() -> Fut) -> T
+where
+    Fut: Future<Output = T>,
+{
+    let _guard = STORAGE_MUTEX.lock().await;
+    STORAGE_LOCK_HELD.scope((), f()).await
+}
+
+fn clone_flagged_storage_for_persistence(
+    storage: Option<&FlaggedAccountStorageV1>,
+) -> FlaggedAccountStorageV1 {
+    match storage {
+        Some(storage) => FlaggedAccountStorageV1 {
+            version: storage.version,
+            accounts: storage.accounts.clone(),
+        },
+        None => FlaggedAccountStorageV1::empty(),
+    }
+}
+
+/// Persist handle passed to [`with_account_storage_transaction`] handlers.
+pub struct AccountTransactionPersist {
+    state: Arc<TransactionSnapshotState>,
+}
+
+impl AccountTransactionPersist {
+    /// Save via the UNLOCKED writer (the lock is already held) and update the
+    /// transaction snapshot.
+    pub async fn persist(&self, storage: &AccountStorageV3) -> Result<(), CodexError> {
+        crate::save::save_accounts_unlocked(storage).await?;
+        self.state.set_snapshot(Some(storage.clone()));
+        Ok(())
+    }
+}
+
+/// TS `withAccountStorageTransaction(handler)` — lock, load current storage
+/// (migrations persist via the UNLOCKED save — the lock is already held),
+/// then run the handler under the snapshot context.
+pub async fn with_account_storage_transaction<T, F, Fut>(handler: F) -> Result<T, CodexError>
+where
+    F: FnOnce(Option<AccountStorageV3>, AccountTransactionPersist) -> Fut,
+    Fut: Future<Output = Result<T, CodexError>>,
+{
+    with_storage_lock(|| async move {
+        // Migrations persist via the UNLOCKED save — the lock is already held.
+        let snapshot = crate::load::load_accounts_internal(crate::load::PersistMigration::Unlocked)
+            .await
+            .map(|loaded| loaded.storage);
+        let state = Arc::new(TransactionSnapshotState::new(
+            PathBuf::from(crate::facade::get_storage_path()),
+            snapshot.clone(),
+        ));
+        let persist = AccountTransactionPersist {
+            state: Arc::clone(&state),
+        };
+        run_in_transaction_snapshot_context(state, handler(snapshot, persist)).await
+    })
+    .await
+}
+
+/// Persist handle for the combined account + flagged transaction.
+pub struct AccountAndFlaggedTransactionPersist {
+    state: Arc<TransactionSnapshotState>,
+}
+
+impl AccountAndFlaggedTransactionPersist {
+    /// Save accounts first, then flagged; on flagged failure ROLL BACK the
+    /// accounts file to the pre-persist snapshot. If the rollback also fails,
+    /// the frozen `AggregateError` message is raised (spec 02 §11).
+    pub async fn persist(
+        &self,
+        account_storage: &AccountStorageV3,
+        flagged_storage: &FlaggedAccountStorageV1,
+    ) -> Result<(), CodexError> {
+        let log = create_logger("storage");
+        let previous_accounts =
+            crate::misc::clone_account_storage_for_persistence(self.state.snapshot().as_ref());
+        let next_accounts =
+            crate::misc::clone_account_storage_for_persistence(Some(account_storage));
+        let next_flagged = clone_flagged_storage_for_persistence(Some(flagged_storage));
+        crate::save::save_accounts_unlocked(&next_accounts).await?;
+        match crate::flagged::save_flagged_accounts_unlocked(&next_flagged).await {
+            Ok(()) => {
+                self.state.set_snapshot(Some(next_accounts));
+                Ok(())
+            }
+            Err(error) => match crate::save::save_accounts_unlocked(&previous_accounts).await {
+                Ok(()) => {
+                    self.state.set_snapshot(Some(previous_accounts));
+                    Err(error)
+                }
+                Err(rollback_error) => {
+                    log.error(
+                        "Failed to rollback account storage after flagged save failure",
+                        Some(&json!({
+                            "error": error.to_string(),
+                            "rollbackError": rollback_error.to_string(),
+                        })),
+                    );
+                    Err(CodexError::new(
+                        "Flagged save failed and account storage rollback also failed",
+                    ))
+                }
+            },
+        }
+    }
+}
+
+/// TS `withAccountAndFlaggedStorageTransaction(handler)` — lock, load
+/// accounts (unlocked persist) + flagged storage, run the handler with a
+/// rollback-capable persist.
+pub async fn with_account_and_flagged_storage_transaction<T, F, Fut>(
+    handler: F,
+) -> Result<T, CodexError>
+where
+    F: FnOnce(
+        Option<AccountStorageV3>,
+        AccountAndFlaggedTransactionPersist,
+        FlaggedAccountStorageV1,
+    ) -> Fut,
+    Fut: Future<Output = Result<T, CodexError>>,
+{
+    with_storage_lock(|| async move {
+        let snapshot = crate::load::load_accounts_internal(crate::load::PersistMigration::Unlocked)
+            .await
+            .map(|loaded| loaded.storage);
+        let state = Arc::new(TransactionSnapshotState::new(
+            PathBuf::from(crate::facade::get_storage_path()),
+            snapshot.clone(),
+        ));
+        let current_flagged = crate::flagged::load_flagged_accounts().await;
+        let persist = AccountAndFlaggedTransactionPersist {
+            state: Arc::clone(&state),
+        };
+        run_in_transaction_snapshot_context(state, handler(snapshot, persist, current_flagged))
+            .await
+    })
+    .await
+}
+
+/// Persist handle for the flagged-only transaction.
+pub struct FlaggedTransactionPersist {
+    snapshot: Arc<StdMutex<FlaggedAccountStorageV1>>,
+}
+
+impl FlaggedTransactionPersist {
+    /// Save flagged storage; on failure restore the previous flagged state.
+    /// Double failure raises the frozen `AggregateError` message.
+    pub async fn persist(&self, storage: &FlaggedAccountStorageV1) -> Result<(), CodexError> {
+        let log = create_logger("storage");
+        let previous_storage = clone_flagged_storage_for_persistence(Some(
+            &self.snapshot.lock().expect("flagged snapshot poisoned").clone(),
+        ));
+        let next_storage = clone_flagged_storage_for_persistence(Some(storage));
+        match crate::flagged::save_flagged_accounts_unlocked(&next_storage).await {
+            Ok(()) => {
+                *self.snapshot.lock().expect("flagged snapshot poisoned") = next_storage;
+                Ok(())
+            }
+            Err(error) => {
+                match crate::flagged::save_flagged_accounts_unlocked(&previous_storage).await {
+                    Ok(()) => {
+                        *self.snapshot.lock().expect("flagged snapshot poisoned") =
+                            previous_storage;
+                        Err(error)
+                    }
+                    Err(rollback_error) => {
+                        log.error(
+                            "Failed to rollback flagged storage after flagged save failure",
+                            Some(&json!({
+                                "error": error.to_string(),
+                                "rollbackError": rollback_error.to_string(),
+                            })),
+                        );
+                        Err(CodexError::new(
+                            "Flagged save failed and flagged storage rollback also failed",
+                        ))
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// TS `withFlaggedStorageTransaction(handler)`.
+pub async fn with_flagged_storage_transaction<T, F, Fut>(handler: F) -> Result<T, CodexError>
+where
+    F: FnOnce(FlaggedAccountStorageV1, FlaggedTransactionPersist) -> Fut,
+    Fut: Future<Output = Result<T, CodexError>>,
+{
+    with_storage_lock(|| async move {
+        let current = crate::flagged::load_flagged_accounts().await;
+        let snapshot = Arc::new(StdMutex::new(clone_flagged_storage_for_persistence(Some(
+            &current,
+        ))));
+        let handler_copy = clone_flagged_storage_for_persistence(Some(
+            &snapshot.lock().expect("flagged snapshot poisoned").clone(),
+        ));
+        let persist = FlaggedTransactionPersist {
+            snapshot: Arc::clone(&snapshot),
+        };
+        handler(handler_copy, persist).await
+    })
+    .await
+}
+
+// ============================================================================
+// Tests — lock semantics + snapshot context (pure; the filesystem-backed
+// transaction round-trips live in tests/transactions_test.rs)
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    #[tokio::test]
+    async fn lock_is_fifo_and_exclusive() {
+        let counter = Arc::new(AtomicUsize::new(0));
+        let mut handles = Vec::new();
+        let order = Arc::new(StdMutex::new(Vec::new()));
+        for i in 0..4 {
+            let counter = Arc::clone(&counter);
+            let order = Arc::clone(&order);
+            handles.push(tokio::spawn(async move {
+                with_storage_lock(|| async move {
+                    let inside = counter.fetch_add(1, Ordering::SeqCst);
+                    // Only one holder at a time.
+                    assert_eq!(counter.load(Ordering::SeqCst), inside + 1);
+                    tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+                    counter.fetch_sub(1, Ordering::SeqCst);
+                    order.lock().unwrap().push(i);
+                })
+                .await;
+            }));
+            // Give each task a chance to enqueue so FIFO order is observable.
+            tokio::time::sleep(std::time::Duration::from_millis(1)).await;
+        }
+        for handle in handles {
+            handle.await.unwrap();
+        }
+        assert_eq!(order.lock().unwrap().clone(), vec![0, 1, 2, 3]);
+    }
+
+    #[tokio::test]
+    async fn held_flag_is_scoped_to_the_critical_section() {
+        assert!(!is_storage_lock_held());
+        with_storage_lock(|| async {
+            assert!(is_storage_lock_held());
+        })
+        .await;
+        assert!(!is_storage_lock_held());
+    }
+
+    #[tokio::test]
+    async fn held_flag_does_not_leak_into_spawned_tasks() {
+        with_storage_lock(|| async {
+            let spawned = tokio::spawn(async { is_storage_lock_held() });
+            assert!(!spawned.await.unwrap());
+        })
+        .await;
+    }
+
+    #[tokio::test]
+    async fn snapshot_context_is_visible_and_mutable() {
+        assert!(get_transaction_snapshot_state().is_none());
+        let state = Arc::new(TransactionSnapshotState::new(
+            PathBuf::from("/tmp/accounts.json"),
+            None,
+        ));
+        run_in_transaction_snapshot_context(Arc::clone(&state), async {
+            let visible = get_transaction_snapshot_state().expect("state visible");
+            assert!(visible.active);
+            assert_eq!(visible.storage_path, PathBuf::from("/tmp/accounts.json"));
+            assert!(visible.snapshot().is_none());
+            visible.set_snapshot(Some(AccountStorageV3::empty()));
+        })
+        .await;
+        assert!(state.snapshot().is_some());
+        assert!(get_transaction_snapshot_state().is_none());
+    }
+
+    #[test]
+    fn clone_flagged_storage_defaults_to_empty() {
+        let cloned = clone_flagged_storage_for_persistence(None);
+        assert!(cloned.accounts.is_empty());
+    }
+}
diff --git a/crates/storage/tests/facade_test.rs b/crates/storage/tests/facade_test.rs
new file mode 100644
index 000000000..834ac443f
--- /dev/null
+++ b/crates/storage/tests/facade_test.rs
@@ -0,0 +1,272 @@
+//! Integration tests for the cma-storage save/load/clear pipeline (the
+//! modules owned by the save+load+backup agent: facade, paths, parser, save,
+//! backups, load, clear, normalize, fixture_guards, misc).
+//!
+//! Ports the highest-value assertions from `test/storage.test.ts`:
+//! - byte-compat against the TS-produced goldens `accounts-v3.json` /
+//!   `accounts-v3.wal` (crates/testkit/goldens);
+//! - WAL-first save pipeline (marker unlink, WAL unlink, rotating backup);
+//! - the load recovery ladder (WAL checksum replay → discovered backups);
+//! - intentional-reset marker semantics (clear marker-first, accounts clear
+//!   never removes its own marker, next save does);
+//! - the synthetic-fixture save guard (frozen StorageError EINVALID);
+//! - restore metadata (missing-storage / empty-storage / intentional-reset).
+//!
+//! Every test pins the storage root with `EnvSandbox` (HOME/CODEX_HOME/
+//! CODEX_MULTI_AUTH_DIR) and must run `#[serial(env)]`; the storage-path
+//! global is additionally serialized via the `storage_path_state` key.
+
+use std::fs;
+use std::path::PathBuf;
+
+use serial_test::serial;
+
+use cma_storage::facade;
+use cma_storage::load::{self, PersistMigration};
+use cma_storage::misc::compute_sha256;
+use cma_storage::public_types::{AccountMetadataV3, AccountStorageV3, AccountsJournalEntry};
+use cma_testkit::goldens::{read_golden_bytes, read_golden_string};
+use cma_testkit::sandbox::EnvSandbox;
+
+fn golden_storage() -> (String, AccountStorageV3) {
+    let golden = read_golden_string("accounts-v3.json");
+    let storage: AccountStorageV3 =
+        serde_json::from_str(&golden).expect("golden accounts-v3.json deserializes");
+    (golden, storage)
+}
+
+fn storage_path() -> PathBuf {
+    PathBuf::from(facade::get_storage_path())
+}
+
+fn synthetic_storage() -> AccountStorageV3 {
+    let mut storage = AccountStorageV3::empty();
+    let mut account = AccountMetadataV3::new("fake_refresh_token_1", 1, 2);
+    account.email = Some("account1@example.com".to_string());
+    account.account_id = Some("acc_1".to_string());
+    storage.accounts.push(account);
+    storage
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn serializer_and_save_pipeline_reproduce_the_golden_bytes() {
+    let _sandbox = EnvSandbox::new();
+    let (golden, storage) = golden_storage();
+
+    // Pure serializer parity first (JSON.stringify(x, null, 2), no trailing
+    // newline, schema key order).
+    assert_eq!(cma_core::json_io::stringify_pretty2(&storage), golden);
+
+    // The full save pipeline writes exactly those bytes to the accounts path.
+    facade::save_accounts(&storage).await.expect("save succeeds");
+    let path = storage_path();
+    let written = fs::read(&path).expect("accounts file written");
+    assert_eq!(written, read_golden_bytes("accounts-v3.json"));
+
+    // WAL and temp artifacts are gone after a successful save.
+    assert!(!path.with_extension("json.wal").exists());
+    let leftovers: Vec<String> = fs::read_dir(path.parent().unwrap())
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .map(|e| e.file_name().to_string_lossy().into_owned())
+        .filter(|name| name.ends_with(".tmp") || name.ends_with(".wal"))
+        .collect();
+    assert!(leftovers.is_empty(), "stale artifacts: {leftovers:?}");
+
+    // And the load pipeline round-trips the identical storage.
+    let loaded = load::load_accounts().await.expect("loads");
+    assert_eq!(loaded.storage, storage);
+    assert!(loaded.restore.is_none());
+}
+
+#[test]
+fn wal_journal_entry_matches_the_golden_bytes() {
+    // The WAL is deleted after a successful save, so parity is asserted on
+    // the entry serialization itself: compact JSON, key order
+    // {version, createdAt, path, checksum, content}, sha256 of the content.
+    let golden_content = read_golden_string("accounts-v3.json");
+    let entry = AccountsJournalEntry::new(
+        1_750_000_000_000,
+        "/golden/multi-auth/openai-codex-accounts.json",
+        compute_sha256(&golden_content),
+        golden_content,
+    );
+    let serialized = cma_core::json_io::stringify_compact(&entry);
+    assert_eq!(serialized.into_bytes(), read_golden_bytes("accounts-v3.wal"));
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn save_rotates_backups_and_a_marker_is_unlinked_by_the_next_save() {
+    let _sandbox = EnvSandbox::new();
+    let (_, storage) = golden_storage();
+    facade::save_accounts(&storage).await.unwrap();
+    let path = storage_path();
+    let first_bytes = fs::read(&path).unwrap();
+
+    // Simulate a prior clear: the reset marker persists until a save.
+    let marker = PathBuf::from(format!("{}.reset-intent", path.to_string_lossy()));
+    fs::write(&marker, "{\"version\":1,\"createdAt\":1}").unwrap();
+
+    let mut second = storage.clone();
+    second.active_index = 0;
+    facade::save_accounts(&second).await.unwrap();
+
+    assert!(!marker.exists(), "successful save unlinks the reset marker");
+    let bak = PathBuf::from(format!("{}.bak", path.to_string_lossy()));
+    assert_eq!(
+        fs::read(&bak).unwrap(),
+        first_bytes,
+        ".bak holds the previous file state byte-for-byte"
+    );
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn load_recovers_from_wal_then_from_backups() {
+    let _sandbox = EnvSandbox::new();
+    let (golden, storage) = golden_storage();
+    let path = storage_path();
+    fs::create_dir_all(path.parent().unwrap()).unwrap();
+
+    // Corrupt primary + valid WAL ⇒ WAL replay wins and re-persists.
+    fs::write(&path, "{definitely not json").unwrap();
+    let wal_entry = AccountsJournalEntry::new(
+        1,
+        path.to_string_lossy().into_owned(),
+        compute_sha256(&golden),
+        golden.clone(),
+    );
+    let wal_path = PathBuf::from(format!("{}.wal", path.to_string_lossy()));
+    fs::write(&wal_path, cma_core::json_io::stringify_compact(&wal_entry)).unwrap();
+
+    let recovered = load::load_accounts().await.expect("recovers from WAL");
+    assert_eq!(recovered.storage, storage);
+    // The recovery persisted the primary (and the save unlinked the WAL).
+    assert_eq!(fs::read(&path).unwrap(), golden.as_bytes());
+    assert!(!wal_path.exists());
+
+    // Corrupt primary + NO WAL + valid .bak ⇒ backup recovery.
+    fs::write(&path, "{still not json").unwrap();
+    let bak_path = PathBuf::from(format!("{}.bak", path.to_string_lossy()));
+    fs::write(&bak_path, golden.as_bytes()).unwrap();
+    let recovered = load::load_accounts().await.expect("recovers from backup");
+    assert_eq!(recovered.storage, storage);
+    assert_eq!(fs::read(&path).unwrap(), golden.as_bytes());
+
+    // A corrupted WAL checksum is rejected (fail-closed) — with no backups it
+    // falls through the whole ladder to None.
+    fs::write(&path, "{corrupt again").unwrap();
+    fs::remove_file(&bak_path).unwrap();
+    let mut bad_entry = wal_entry;
+    bad_entry.checksum = "0".repeat(64);
+    fs::write(&wal_path, cma_core::json_io::stringify_compact(&bad_entry)).unwrap();
+    // Remove the .bak.1/.bak.2 artifacts a prior save may have rotated in.
+    for candidate in fs::read_dir(path.parent().unwrap()).unwrap().flatten() {
+        let name = candidate.file_name().to_string_lossy().into_owned();
+        if name.contains(".bak") {
+            let _ = fs::remove_file(candidate.path());
+        }
+    }
+    assert!(load::load_accounts().await.is_none());
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn clear_is_marker_first_and_load_reports_intentional_reset() {
+    let _sandbox = EnvSandbox::new();
+    let (_, storage) = golden_storage();
+    facade::save_accounts(&storage).await.unwrap();
+    let path = storage_path();
+
+    facade::clear_accounts().await.expect("clear succeeds");
+    assert!(!path.exists(), "primary removed");
+    let marker = PathBuf::from(format!("{}.reset-intent", path.to_string_lossy()));
+    assert!(marker.exists(), "accounts clear never removes its marker");
+    let marker_content = fs::read_to_string(&marker).unwrap();
+    assert!(marker_content.starts_with("{\"version\":1,\"createdAt\":"));
+
+    let loaded = load::load_accounts().await.expect("marker yields empty storage");
+    assert!(loaded.storage.accounts.is_empty());
+    let restore = loaded.restore.expect("restore metadata attached");
+    assert!(!restore.restore_eligible);
+    assert_eq!(restore.restore_reason, "intentional-reset");
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn missing_and_empty_storage_report_restore_metadata() {
+    let _sandbox = EnvSandbox::new();
+
+    let loaded = load::load_accounts().await.expect("missing file yields empty");
+    let restore = loaded.restore.expect("restore metadata");
+    assert!(restore.restore_eligible);
+    assert_eq!(restore.restore_reason, "missing-storage");
+
+    facade::save_accounts(&AccountStorageV3::empty()).await.unwrap();
+    let loaded = load::load_accounts().await.expect("empty file yields storage");
+    let restore = loaded.restore.expect("restore metadata");
+    assert!(restore.restore_eligible);
+    assert_eq!(restore.restore_reason, "empty-storage");
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn synthetic_fixture_payload_cannot_overwrite_real_storage() {
+    let _sandbox = EnvSandbox::new();
+    let (_, real_storage) = golden_storage();
+    facade::save_accounts(&real_storage).await.unwrap();
+    let before = fs::read(storage_path()).unwrap();
+
+    let error = facade::save_accounts(&synthetic_storage())
+        .await
+        .expect_err("synthetic payload over real accounts must fail");
+    assert_eq!(error.code(), "EINVALID");
+    assert_eq!(
+        error.message(),
+        "Failed to save accounts: Refusing to overwrite non-synthetic account storage with synthetic fixture payload"
+    );
+    assert_eq!(
+        fs::read(storage_path()).unwrap(),
+        before,
+        "the real file is untouched"
+    );
+
+    // Synthetic-over-synthetic (or over nothing) is allowed — fixtures can
+    // seed empty sandboxes.
+    facade::clear_accounts().await.unwrap();
+    facade::save_accounts(&synthetic_storage())
+        .await
+        .expect("synthetic payload over empty storage is fine");
+}
+
+#[tokio::test]
+#[serial(env, storage_path_state)]
+async fn v1_storage_migrates_to_v3_and_persists() {
+    let _sandbox = EnvSandbox::new();
+    let path = storage_path();
+    fs::create_dir_all(path.parent().unwrap()).unwrap();
+    fs::write(
+        &path,
+        r#"{"version":1,"accounts":[{"refreshToken":"rt_v1","addedAt":5,"lastUsed":6}],"activeIndex":0}"#,
+    )
+    .unwrap();
+
+    let loaded = load::load_accounts_internal(PersistMigration::Locked)
+        .await
+        .expect("v1 file loads");
+    assert_eq!(loaded.storage.accounts.len(), 1);
+    let by_family = loaded
+        .storage
+        .active_index_by_family
+        .as_ref()
+        .expect("family map fanned out");
+    assert!(!by_family.is_empty());
+
+    // The migration persisted a v3 file in place.
+    let migrated: serde_json::Value =
+        serde_json::from_str(&fs::read_to_string(&path).unwrap()).unwrap();
+    assert_eq!(migrated["version"], 3);
+    assert_eq!(migrated["accounts"][0]["refreshToken"], "rt_v1");
+}
diff --git a/crates/testkit/Cargo.toml b/crates/testkit/Cargo.toml
new file mode 100644
index 000000000..d6a91c6e2
--- /dev/null
+++ b/crates/testkit/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+name = "cma-testkit"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde_json.workspace = true
+tempfile.workspace = true
+serial_test.workspace = true
+insta.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/testkit/goldens/README.md b/crates/testkit/goldens/README.md
new file mode 100644
index 000000000..1010aeb83
--- /dev/null
+++ b/crates/testkit/goldens/README.md
@@ -0,0 +1,244 @@
+# Golden byte fixtures (TypeScript reference implementation)
+
+Byte-exact fixtures for the Rust rewrite, produced by the **real** TypeScript
+implementation (`dist/lib/`, package version 2.7.1). Every fixture is the file
+the TS library actually wrote to disk in a sandboxed HOME; the Rust
+implementation must reproduce these bytes exactly (or parse them exactly).
+
+Regenerate with:
+
+```
+npm run build   # only if dist/ is stale
+node crates/testkit/goldens/generate.mjs
+```
+
+The generator is deterministic: repeated runs produce byte-identical fixtures.
+It runs fully sandboxed (`HOME`, `USERPROFILE`, `CODEX_HOME`,
+`CODEX_MULTI_AUTH_DIR` all point into a fresh temp dir set in-process **before**
+any `dist/` import, because several modules resolve their target path at module
+load time). The real user profile is never touched; the sandbox is deleted
+afterwards.
+
+## Fixed inputs
+
+| Constant | Value |
+| --- | --- |
+| `T0` (canonical timestamp) | `1750000000000` |
+| `EXPIRES_AT` | `1750003600000` (T0 + 1h) |
+| `FIXED_CLIENT_KEY` | `"0123456789abcdef"` x 4 (64 hex chars) |
+| `FIXED_PLAIN_TOKEN` | `cma_local_` + base64url(bytes `0x00..0x1f`) |
+| `BASE_URL` | `http://127.0.0.1:8123` |
+| minimal `config.toml` | `model = "gpt-5.2"` / `model_provider = "openai"` / `disable_response_storage = true` + `[tools]` table (see `generate.mjs`) |
+
+All timestamps/ids that the public API lets callers inject use these fixed
+values. Where the library stamps clock/randomness internally, the produced file
+is re-parsed, **only** that field is replaced, and the payload is re-serialized
+with the exact same serializer call the library used (same indent and
+trailing-newline convention). Every such replacement is listed per fixture
+below; everything else is authentic library output.
+
+## Fixture catalog
+
+### accounts-v3.json
+- **Producer:** `saveAccounts(storage)` (`dist/lib/storage.js`), on-disk name
+  `openai-codex-accounts.json`. Serialization: `JSON.stringify(storage, null, 2)`,
+  no trailing newline.
+- **Input:** a v3 pool with 2 accounts (workspaces incl. a disabled one,
+  per-family `rateLimitResetTimes`, cooldown on account 2), `activeIndex: 1`,
+  `activeIndexByFamily` covering all 5 model families, `pinnedAccountIndex: 1`,
+  `affinityGeneration: 4`. Note `saveAccounts` serializes the caller's object
+  verbatim (no reordering on the write path), so the generator constructs the
+  input in the same canonical field order the library itself uses when it
+  builds storage objects (`normalizeAccountStorage` /
+  `cloneAccountStorageForPersistence` top-level order; `AccountMetadataV3`
+  declaration order per account).
+- **Post-processing:** none.
+
+### accounts-v3.wal
+- **Producer:** the WAL journal entry `saveAccounts` writes (via its internal
+  `writeJournal`) before the atomic rename, for the exact save above.
+  Single-line `JSON.stringify` of
+  `{version: 1, createdAt, path, checksum, content}` where `checksum` =
+  sha256 hex of `content` and `content` is byte-identical to
+  `accounts-v3.json`.
+- **Capture harness:** `saveAccounts` deletes the WAL after a successful save,
+  so the generator temporarily wraps `fs.promises.unlink` to read the `*.wal`
+  bytes immediately before the (still executed) real deletion. The bytes are
+  what the library wrote.
+- **Post-processing:** `createdAt` (internally `Date.now()`) -> `T0`; `path`
+  (sandbox-absolute accounts path) -> `/golden/multi-auth/openai-codex-accounts.json`.
+  The checksum covers only `content`, so both replacements keep it valid.
+
+### flagged-v1.json
+- **Producer:** `saveFlaggedAccounts(storage)` (`dist/lib/storage.js`), on-disk
+  name `openai-codex-flagged-accounts.json`. The library normalizes through
+  `normalizeFlaggedStorage` before writing (that function defines the field
+  order). `JSON.stringify(..., null, 2)`, no trailing newline.
+- **Input:** one flagged account (`flaggedAt: T0`,
+  `flaggedReason: "invalid_grant on refresh"`, `lastError`, cooldown fields,
+  one workspace).
+- **Post-processing:** none.
+
+### settings.json
+- **Producer:** `saveUnifiedPluginConfig(getDefaultPluginConfig())` followed by
+  `saveUnifiedDashboardSettings(DEFAULT_DASHBOARD_DISPLAY_SETTINGS)`
+  (`dist/lib/unified-settings.js`, defaults from `dist/lib/config.js` and
+  `dist/lib/dashboard-settings.js`). Record shape:
+  `{pluginConfig, version: 1, dashboardDisplaySettings}`.
+  `JSON.stringify(..., null, 2)` + trailing newline.
+- **Input:** the library's own default plugin config and default dashboard
+  display settings (canonical defaults of version 2.7.1).
+- **Post-processing:** none.
+
+### quota-cache.json
+- **Producer:** `saveQuotaCache(data)` (`dist/lib/quota-cache.js`). Payload
+  `{version: 1, byAccountId, byEmail}`, `JSON.stringify(..., null, 2)` +
+  trailing newline.
+- **Input:** two entries (one healthy 200/`gpt-5.2`/`plus`, one exhausted
+  429/`gpt-5-codex`/`team`) keyed by both accountId and email, fixed
+  `updatedAt: T0` and fixed window numbers. Entry field order matches the
+  library's `normalizeEntry` order.
+- **Post-processing:** none.
+
+### budget-guards.json
+- **Producer:** `loadBudgetGuardStore()` + `upsertBudgetLimit(store, limit, T0)`
+  (x2) + `saveBudgetGuardStore(store)` (`dist/lib/budget-guard.js`; save runs
+  the store through `normalizeStore`). Trailing newline.
+- **Input:** `team-alpha` day limit (requests/tokens/cost) and `personal` month
+  limit (cost only; absent caps are omitted from the JSON).
+- **Post-processing:** none (`updatedAt` is injectable via the `now` parameter).
+
+### account-policies.json
+- **Producer:** `getAccountPolicyKey({accountId})` +
+  `upsertAccountPolicy(store, key, mutate, T0)` (x2) +
+  `saveAccountPolicyStore(store)` (`dist/lib/account-policy.js`). Keys are the
+  library's own `sha256:<hex of accountId>` derivation for `acct-user-one` /
+  `acct-user-two`. Trailing newline.
+- **Input:** policy 1: tags `personal, primary`, weight 2, note; policy 2:
+  tags `team`, weight 1, `paused: true`, note.
+- **Post-processing:** none.
+
+### routing-profiles.json
+- **Producer:** `createDefaultRoutingProfile({... now: T0})` +
+  `upsertRoutingProfile(store, profile, mutate, T0)` +
+  `saveRoutingProfileStore(store)` (`dist/lib/routing-profiles.js`). Trailing
+  newline.
+- **Input:** `projectKey: "my-app-0123456789ab"` (fixed string in the library's
+  `<name>-<12-hex>` format, chosen instead of `getProjectStorageKey` so the
+  bytes don't depend on the generating machine's filesystem),
+  `identityRoot: "/workspace/my-app"`, preferred/avoid tags, model allowlist,
+  `accountWeightByKey` keyed by the same `sha256:` account-policy keys,
+  `budgetKey: "team-alpha"`.
+- **Post-processing:** none.
+
+### local-client-tokens.json
+- **Producer:** `addLocalClientToken({label: "workstation", now: T0})`
+  (`dist/lib/local-client-tokens.js`). Trailing newline.
+- **Post-processing:** the library generates `id` via `randomUUID()` and the
+  token via `randomBytes(32)`. Replaced with values derived from
+  `FIXED_PLAIN_TOKEN` using the library's own scheme so the record stays
+  internally consistent: `id` -> `00000000-0000-4000-8000-000000000001`,
+  `prefix` -> first 18 chars of `FIXED_PLAIN_TOKEN` (`cma_local_AAECAwQF`),
+  `tokenHash` -> `sha256:` + sha256 hex of `FIXED_PLAIN_TOKEN`.
+
+### runtime-observability.json
+- **Producer:** `mutateRuntimeObservabilitySnapshot(mutator)`
+  (`dist/lib/runtime/runtime-observability.js`), which persists the snapshot
+  asynchronously. `JSON.stringify(..., null, 2)`, no trailing newline. The
+  full default snapshot shape (all fields of `createDefaultSnapshot`) is
+  present; the mutator sets pool-exhaustion state, skip reasons, policy blocks,
+  reload markers, and runtime metrics to fixed values.
+- **Post-processing:** `updatedAt` (stamped `Date.now()` by the library after
+  the mutator runs) -> `T0`.
+- **Note:** persistence is disabled when `VITEST=true`; the generator clears
+  that variable before import.
+
+### app-bind-state.json
+- **Producer:** `bindCodexAppRuntimeRotation(options)`
+  (`dist/lib/runtime/app-bind.js`), on-disk name
+  `runtime-rotation-app-bind.json`. `JSON.stringify(..., null, 2)` + trailing
+  newline.
+- **Input:** options `{platform: "linux", now: () => T0, nodePath:
+  "/usr/bin/node", routerScriptPath: "/opt/codex-multi-auth/scripts/codex-app-router.js",
+  spawnDetached: false}` plus a dedicated bind codex-home
+  (`CODEX_MULTI_AUTH_APP_BIND_CODEX_HOME`) seeded with the minimal
+  `config.toml`. A **seeded input** router status file
+  (`runtime-rotation-app-bind-status.json` with `state: "running"`,
+  `pid: <generator pid>`, `baseUrl: BASE_URL`) lets bind resolve port 8123
+  without spawning a real router process.
+- **Post-processing:** `clientApiKey` (internally `randomBytes(32).hex`) ->
+  `FIXED_CLIENT_KEY`; `boundConfigHash` recomputed with the library's own
+  `rewriteConfigTomlForAppBind(minimalConfig, BASE_URL, FIXED_CLIENT_KEY)` so it
+  stays consistent -- it equals the sha256 of
+  `config-toml-provider-block.toml`; the five sandbox-absolute path fields
+  (`configPath`, `statePath`, `backupPath`, `statusPath`, `logPath`) ->
+  stable `/golden/...` placeholders. `platform`, `nodePath`,
+  `routerScriptPath`, `updatedAt` were already fixed via options.
+
+### first-run-setup.json
+- **Producer:** `ensureFirstRunSetup(deps)` (`dist/lib/runtime/first-run.js`)
+  with injected deps: `env: {}`, `installedContext: true`, `now: () => T0`,
+  `resolveRotation: () => true`, `bindCodexApp: async () => "completed"`,
+  `installLauncher: async () => "skipped"`. Tab-indented JSON
+  (`JSON.stringify(..., null, "\t")`) + trailing newline -- the finalized
+  marker, not the initial claim stub.
+- **Post-processing:** none.
+
+### usage-ledger-row.jsonl
+- **Producer:** `appendUsageLedgerRow(input)` (`dist/lib/usage/ledger.js`);
+  single JSONL line (`JSON.stringify(row)` + `\n`) from
+  `usage/usage-ledger.jsonl`.
+- **Input:** fixed `id`/`createdAt`, `runtime-proxy`/`responses`/`success`,
+  model `gpt-5.2`, fixed token counts, explicit `costUsd: 0.0123` (explicit so
+  the fixture doesn't track the pricing table). `accountHash`/`emailHash` are
+  the library's `sha256:` hashes of `acct-user-one` and
+  `user.one@example.com` (input email deliberately mixed-case
+  `User.One@Example.com` to exercise the library's lowercasing).
+- **Post-processing:** none.
+
+### update-check-cache.json
+- **Producer:** `checkForUpdates(true)` (`dist/lib/update-notice.js`), on-disk
+  `cache/update-check-cache.json`. `JSON.stringify(..., null, 2)`, no trailing
+  newline.
+- **Input:** `globalThis.fetch` is stubbed during the call to return
+  `{name: "codex-multi-auth", version: "9.9.9"}` (the npm-registry network
+  boundary is the only thing replaced; the cache bytes are written by the
+  library). `currentVersion` is read by the library from the repo's real
+  `package.json` -- it is `2.7.1` and **will change when the package version
+  bumps**; regenerate after releases.
+- **Post-processing:** `lastCheck` (stamped `Date.now()`) -> `T0`.
+
+### codex-cli-accounts.json and codex-cli-auth.json
+- **Producer:** `setCodexCliActiveSelection(selection)`
+  (`dist/lib/codex-cli/writer.js`) -- the mirror writer output for
+  `$CODEX_HOME/accounts.json` and `$CODEX_HOME/auth.json`.
+  `JSON.stringify(..., null, 2)`, no trailing newline.
+- **Input:** a **seeded input** CLI `accounts.json` (2 records with stale
+  `at-old-cli-*` tokens, account two active) -- the writer only rewrites
+  `accounts.json` when it already exists; `auth.json` did not exist (created
+  from `{}`). Selection: account one with the fixture tokens and
+  `expiresAt: EXPIRES_AT` (hence `last_refresh: "2025-06-15T16:06:40.000Z"`).
+- **Post-processing:** `codexMultiAuthSyncVersion` in **both** files (stamped
+  `Date.now()`) -> `T0`.
+
+### config-toml-provider-block.toml
+- **Producer:** `rewriteConfigTomlForRuntimeRotationProvider(minimalConfig,
+  BASE_URL, FIXED_CLIENT_KEY)` (`dist/lib/runtime/config-toml.js`) -- the
+  byte-exact result of applying the runtime-rotation provider-block insert to
+  the minimal `config.toml` (provider swap to
+  `codex-multi-auth-runtime-proxy`, `disable_response_storage` flipped to
+  `false`, provider table with `experimental_bearer_token` appended).
+- **Post-processing:** none. Invariant: `sha256(this file)` ==
+  `boundConfigHash` in `app-bind-state.json` (same config, base URL, and key).
+
+## Non-obvious environment gotchas encoded in the generator
+
+- Path constants are frozen at module load in several modules
+  (`quota-cache.js`, `unified-settings.js`, `update-notice.js`, `config.js`):
+  sandbox env vars must be exported before the first `dist/` import.
+- `runtime-observability.js` skips persistence entirely when `VITEST === "true"`.
+- `saveAccounts` refuses payloads matching the synthetic-fixture heuristic
+  (`accountN@example.com` + `fake_refresh_token_*`) when real storage exists;
+  the fixture identities intentionally do not match that pattern.
+- The WAL is deleted on successful save; it only survives on disk after a crash
+  between journal write and rename (which is what the fixture simulates).
diff --git a/crates/testkit/goldens/account-policies.json b/crates/testkit/goldens/account-policies.json
new file mode 100644
index 000000000..575a55de9
--- /dev/null
+++ b/crates/testkit/goldens/account-policies.json
@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "accounts": {
+    "sha256:7dafc00442dea304b0c5d8639eb8980385d63c449b9ff6575eff2e8638af520a": {
+      "accountKey": "sha256:7dafc00442dea304b0c5d8639eb8980385d63c449b9ff6575eff2e8638af520a",
+      "tags": [
+        "personal",
+        "primary"
+      ],
+      "weight": 2,
+      "paused": false,
+      "drained": false,
+      "note": "Primary fixture account",
+      "updatedAt": 1750000000000
+    },
+    "sha256:0b8d380cc8093df83db8e2144faf9aa628e69c44eec806942ccba174d09bbbcd": {
+      "accountKey": "sha256:0b8d380cc8093df83db8e2144faf9aa628e69c44eec806942ccba174d09bbbcd",
+      "tags": [
+        "team"
+      ],
+      "weight": 1,
+      "paused": true,
+      "drained": false,
+      "note": "Paused fixture account",
+      "updatedAt": 1750000000000
+    }
+  }
+}
diff --git a/crates/testkit/goldens/accounts-v3.json b/crates/testkit/goldens/accounts-v3.json
new file mode 100644
index 000000000..5fbb4fab4
--- /dev/null
+++ b/crates/testkit/goldens/accounts-v3.json
@@ -0,0 +1,74 @@
+{
+  "version": 3,
+  "accounts": [
+    {
+      "accountId": "acct-user-one",
+      "accountIdSource": "id_token",
+      "accountLabel": "Personal Plus",
+      "email": "user.one@example.com",
+      "refreshToken": "rt-fixture-account-one-0000000001",
+      "accessToken": "at-fixture-account-one-0000000001",
+      "expiresAt": 1750003600000,
+      "enabled": true,
+      "addedAt": 1749900000000,
+      "lastUsed": 1749999000000,
+      "lastSwitchReason": "rotation",
+      "rateLimitResetTimes": {
+        "gpt-5-codex": 1750000600000,
+        "codex": 1750000300000
+      },
+      "workspaces": [
+        {
+          "id": "ws-personal-1",
+          "name": "Personal",
+          "enabled": true,
+          "isDefault": true
+        },
+        {
+          "id": "ws-team-alpha",
+          "name": "Team Alpha",
+          "enabled": false,
+          "disabledAt": 1749950000000
+        }
+      ],
+      "currentWorkspaceIndex": 0
+    },
+    {
+      "accountId": "acct-user-two",
+      "accountIdSource": "token",
+      "accountLabel": "Team Business",
+      "email": "user.two@example.com",
+      "refreshToken": "rt-fixture-account-two-0000000002",
+      "accessToken": "at-fixture-account-two-0000000002",
+      "expiresAt": 1750003600000,
+      "enabled": true,
+      "addedAt": 1749910000000,
+      "lastUsed": 1750000000000,
+      "lastSwitchReason": "manual",
+      "rateLimitResetTimes": {
+        "gpt-5.2": 1750001200000
+      },
+      "coolingDownUntil": 1750000060000,
+      "cooldownReason": "rate-limit",
+      "workspaces": [
+        {
+          "id": "ws-biz-2",
+          "name": "Business",
+          "enabled": true,
+          "isDefault": true
+        }
+      ],
+      "currentWorkspaceIndex": 0
+    }
+  ],
+  "activeIndex": 1,
+  "activeIndexByFamily": {
+    "gpt-5-codex": 0,
+    "codex-max": 1,
+    "codex": 0,
+    "gpt-5.2": 1,
+    "gpt-5.1": 0
+  },
+  "pinnedAccountIndex": 1,
+  "affinityGeneration": 4
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/accounts-v3.wal b/crates/testkit/goldens/accounts-v3.wal
new file mode 100644
index 000000000..040b058a7
--- /dev/null
+++ b/crates/testkit/goldens/accounts-v3.wal
@@ -0,0 +1 @@
+{"version":1,"createdAt":1750000000000,"path":"/golden/multi-auth/openai-codex-accounts.json","checksum":"2b768a77c9efd4bdbc584f4fcfc31fe419f32ec8662a24d5cb6bc17529826fc1","content":"{\n  \"version\": 3,\n  \"accounts\": [\n    {\n      \"accountId\": \"acct-user-one\",\n      \"accountIdSource\": \"id_token\",\n      \"accountLabel\": \"Personal Plus\",\n      \"email\": \"user.one@example.com\",\n      \"refreshToken\": \"rt-fixture-account-one-0000000001\",\n      \"accessToken\": \"at-fixture-account-one-0000000001\",\n      \"expiresAt\": 1750003600000,\n      \"enabled\": true,\n      \"addedAt\": 1749900000000,\n      \"lastUsed\": 1749999000000,\n      \"lastSwitchReason\": \"rotation\",\n      \"rateLimitResetTimes\": {\n        \"gpt-5-codex\": 1750000600000,\n        \"codex\": 1750000300000\n      },\n      \"workspaces\": [\n        {\n          \"id\": \"ws-personal-1\",\n          \"name\": \"Personal\",\n          \"enabled\": true,\n          \"isDefault\": true\n        },\n        {\n          \"id\": \"ws-team-alpha\",\n          \"name\": \"Team Alpha\",\n          \"enabled\": false,\n          \"disabledAt\": 1749950000000\n        }\n      ],\n      \"currentWorkspaceIndex\": 0\n    },\n    {\n      \"accountId\": \"acct-user-two\",\n      \"accountIdSource\": \"token\",\n      \"accountLabel\": \"Team Business\",\n      \"email\": \"user.two@example.com\",\n      \"refreshToken\": \"rt-fixture-account-two-0000000002\",\n      \"accessToken\": \"at-fixture-account-two-0000000002\",\n      \"expiresAt\": 1750003600000,\n      \"enabled\": true,\n      \"addedAt\": 1749910000000,\n      \"lastUsed\": 1750000000000,\n      \"lastSwitchReason\": \"manual\",\n      \"rateLimitResetTimes\": {\n        \"gpt-5.2\": 1750001200000\n      },\n      \"coolingDownUntil\": 1750000060000,\n      \"cooldownReason\": \"rate-limit\",\n      \"workspaces\": [\n        {\n          \"id\": \"ws-biz-2\",\n          \"name\": \"Business\",\n          \"enabled\": true,\n          \"isDefault\": true\n        }\n      ],\n      \"currentWorkspaceIndex\": 0\n    }\n  ],\n  \"activeIndex\": 1,\n  \"activeIndexByFamily\": {\n    \"gpt-5-codex\": 0,\n    \"codex-max\": 1,\n    \"codex\": 0,\n    \"gpt-5.2\": 1,\n    \"gpt-5.1\": 0\n  },\n  \"pinnedAccountIndex\": 1,\n  \"affinityGeneration\": 4\n}"}
\ No newline at end of file
diff --git a/crates/testkit/goldens/app-bind-state.json b/crates/testkit/goldens/app-bind-state.json
new file mode 100644
index 000000000..7f374eb34
--- /dev/null
+++ b/crates/testkit/goldens/app-bind-state.json
@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "platform": "linux",
+  "host": "127.0.0.1",
+  "port": 8123,
+  "baseUrl": "http://127.0.0.1:8123",
+  "configPath": "/golden/codex-home/config.toml",
+  "statePath": "/golden/multi-auth/app-bind/runtime-rotation-app-bind.json",
+  "backupPath": "/golden/multi-auth/app-bind/codex-config-backup.json",
+  "statusPath": "/golden/multi-auth/app-bind/runtime-rotation-app-bind-status.json",
+  "logPath": "/golden/multi-auth/app-bind/runtime-rotation-app-router.log",
+  "nodePath": "/usr/bin/node",
+  "routerScriptPath": "/opt/codex-multi-auth/scripts/codex-app-router.js",
+  "clientApiKey": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "startupPath": null,
+  "launchAgentPath": null,
+  "boundConfigHash": "686846a0dcbcf1311a05bb1870b6434748f185c1f738abaa92c23a8dbdebed91",
+  "updatedAt": 1750000000000
+}
diff --git a/crates/testkit/goldens/budget-guards.json b/crates/testkit/goldens/budget-guards.json
new file mode 100644
index 000000000..741764b1b
--- /dev/null
+++ b/crates/testkit/goldens/budget-guards.json
@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "limits": {
+    "team-alpha": {
+      "key": "team-alpha",
+      "window": "day",
+      "maxRequests": 500,
+      "maxTokens": 2000000,
+      "maxCostUsd": 25,
+      "updatedAt": 1750000000000
+    },
+    "personal": {
+      "key": "personal",
+      "window": "month",
+      "maxCostUsd": 100,
+      "updatedAt": 1750000000000
+    }
+  }
+}
diff --git a/crates/testkit/goldens/codex-cli-accounts.json b/crates/testkit/goldens/codex-cli-accounts.json
new file mode 100644
index 000000000..afe5f6500
--- /dev/null
+++ b/crates/testkit/goldens/codex-cli-accounts.json
@@ -0,0 +1,45 @@
+{
+  "accounts": [
+    {
+      "accountId": "acct-user-one",
+      "email": "user.one@example.com",
+      "access_token": "at-fixture-account-one-0000000001",
+      "refresh_token": "rt-fixture-account-one-0000000001",
+      "id_token": "idt-fixture-account-one-0000000001",
+      "active": true,
+      "accessToken": "at-fixture-account-one-0000000001",
+      "refreshToken": "rt-fixture-account-one-0000000001",
+      "idToken": "idt-fixture-account-one-0000000001",
+      "account_id": "acct-user-one",
+      "auth": {
+        "tokens": {
+          "access_token": "at-fixture-account-one-0000000001",
+          "accessToken": "at-fixture-account-one-0000000001",
+          "refresh_token": "rt-fixture-account-one-0000000001",
+          "refreshToken": "rt-fixture-account-one-0000000001",
+          "id_token": "idt-fixture-account-one-0000000001",
+          "idToken": "idt-fixture-account-one-0000000001",
+          "account_id": "acct-user-one",
+          "accountId": "acct-user-one"
+        }
+      },
+      "isActive": true,
+      "is_active": true
+    },
+    {
+      "accountId": "acct-user-two",
+      "email": "user.two@example.com",
+      "access_token": "at-old-cli-two",
+      "refresh_token": "rt-old-cli-two",
+      "id_token": "idt-old-cli-two",
+      "active": false,
+      "isActive": false,
+      "is_active": false
+    }
+  ],
+  "activeAccountId": "acct-user-one",
+  "active_account_id": "acct-user-one",
+  "activeEmail": "user.one@example.com",
+  "active_email": "user.one@example.com",
+  "codexMultiAuthSyncVersion": 1750000000000
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/codex-cli-auth.json b/crates/testkit/goldens/codex-cli-auth.json
new file mode 100644
index 000000000..7aa823a63
--- /dev/null
+++ b/crates/testkit/goldens/codex-cli-auth.json
@@ -0,0 +1,13 @@
+{
+  "auth_mode": "chatgpt",
+  "OPENAI_API_KEY": null,
+  "email": "user.one@example.com",
+  "tokens": {
+    "access_token": "at-fixture-account-one-0000000001",
+    "refresh_token": "rt-fixture-account-one-0000000001",
+    "account_id": "acct-user-one",
+    "id_token": "idt-fixture-account-one-0000000001"
+  },
+  "last_refresh": "2025-06-15T16:06:40.000Z",
+  "codexMultiAuthSyncVersion": 1750000000000
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/config-toml-provider-block.toml b/crates/testkit/goldens/config-toml-provider-block.toml
new file mode 100644
index 000000000..cdc4b0165
--- /dev/null
+++ b/crates/testkit/goldens/config-toml-provider-block.toml
@@ -0,0 +1,13 @@
+model = "gpt-5.2"
+model_provider = "codex-multi-auth-runtime-proxy"
+disable_response_storage = false
+
+[tools]
+web_search = true
+
+[model_providers.codex-multi-auth-runtime-proxy]
+name = "codex-multi-auth"
+base_url = "http://127.0.0.1:8123"
+requires_openai_auth = false
+experimental_bearer_token = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+wire_api = "responses"
diff --git a/crates/testkit/goldens/first-run-setup.json b/crates/testkit/goldens/first-run-setup.json
new file mode 100644
index 000000000..dd90e7ea0
--- /dev/null
+++ b/crates/testkit/goldens/first-run-setup.json
@@ -0,0 +1,7 @@
+{
+	"version": 1,
+	"startedAt": 1750000000000,
+	"completedAt": 1750000000000,
+	"appBind": "completed",
+	"launcher": "skipped"
+}
diff --git a/crates/testkit/goldens/flagged-v1.json b/crates/testkit/goldens/flagged-v1.json
new file mode 100644
index 000000000..ba60a54a0
--- /dev/null
+++ b/crates/testkit/goldens/flagged-v1.json
@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "accounts": [
+    {
+      "refreshToken": "rt-fixture-flagged-0000000003",
+      "addedAt": 1749800000000,
+      "lastUsed": 1749990000000,
+      "accountId": "acct-user-three",
+      "accountIdSource": "id_token",
+      "accountLabel": "Flagged Account",
+      "email": "user.three@example.com",
+      "accessToken": "at-fixture-flagged-0000000003",
+      "expiresAt": 1750003600000,
+      "enabled": false,
+      "lastSwitchReason": "rate-limit",
+      "rateLimitResetTimes": {
+        "codex": 1750000900000
+      },
+      "coolingDownUntil": 1750003600000,
+      "cooldownReason": "auth-failure",
+      "workspaces": [
+        {
+          "id": "ws-three-1",
+          "name": "Personal",
+          "enabled": true,
+          "isDefault": true
+        }
+      ],
+      "currentWorkspaceIndex": 0,
+      "flaggedAt": 1750000000000,
+      "flaggedReason": "invalid_grant on refresh",
+      "lastError": "401 Unauthorized: invalid_grant"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/generate.mjs b/crates/testkit/goldens/generate.mjs
new file mode 100644
index 000000000..c5ce9cb1c
--- /dev/null
+++ b/crates/testkit/goldens/generate.mjs
@@ -0,0 +1,607 @@
+#!/usr/bin/env node
+/**
+ * Golden byte-fixture generator for the Rust rewrite of codex-multi-auth.
+ *
+ * Exercises the REAL TypeScript implementation (build output in dist/lib) inside a
+ * throwaway sandbox HOME, then copies each persisted artifact into this directory
+ * under a stable name. See README.md (same directory) for the fixture catalog,
+ * the exact producing function per fixture, and every post-processing step.
+ *
+ * Determinism rules:
+ *  - All caller-injectable timestamps/ids use fixed values (T0 = 1750000000000).
+ *  - Where the library stamps Date.now() / randomness INTERNALLY (documented in
+ *    README.md), the produced file is re-parsed, ONLY the random/clock field is
+ *    replaced with a fixed value, and the payload is re-serialized with the exact
+ *    same serializer call the library used (same indent, same trailing-newline
+ *    convention), so every other byte is authentic library output.
+ *
+ * Run:  node crates/testkit/goldens/generate.mjs
+ */
+
+import { promises as fsp } from "node:fs";
+import { createHash } from "node:crypto";
+import os from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const goldensDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(goldensDir, "..", "..", "..");
+const distLib = join(repoRoot, "dist", "lib");
+
+// ---------------------------------------------------------------------------
+// Fixed deterministic inputs
+// ---------------------------------------------------------------------------
+const T0 = 1750000000000; // 2025-06-15T15:06:40.000Z
+const EXPIRES_AT = 1750003600000; // T0 + 1h
+const FIXED_CLIENT_KEY = "0123456789abcdef".repeat(4); // 64 hex chars, stands in for randomBytes(32).hex
+const FIXED_TOKEN_UUID = "00000000-0000-4000-8000-000000000001";
+const FIXED_PLAIN_TOKEN = `cma_local_${Buffer.from([...Array(32).keys()]).toString("base64url")}`;
+const BASE_URL = "http://127.0.0.1:8123";
+const MINIMAL_CONFIG_TOML = [
+  'model = "gpt-5.2"',
+  'model_provider = "openai"',
+  "disable_response_storage = true",
+  "",
+  "[tools]",
+  "web_search = true",
+  "",
+].join("\n");
+
+const sha256hex = (value) => createHash("sha256").update(value).digest("hex");
+
+// ---------------------------------------------------------------------------
+// Sandbox: must be fully configured BEFORE any dist/ import. Several modules
+// (quota-cache, unified-settings, update-notice, config) resolve their target
+// path at module-load time via getCodexMultiAuthDir()/getCodexHomeDir().
+// ---------------------------------------------------------------------------
+const sandbox = await fsp.mkdtemp(join(os.tmpdir(), "cma-goldens-"));
+const codexHome = join(sandbox, "codex-home");
+const multiAuthDir = join(sandbox, "multi-auth");
+const appBindCodexHome = join(sandbox, "app-bind-codex-home");
+
+process.env.HOME = sandbox;
+process.env.USERPROFILE = sandbox;
+process.env.CODEX_HOME = codexHome;
+process.env.CODEX_MULTI_AUTH_DIR = multiAuthDir;
+for (const key of [
+  "VITEST", // runtime-observability disables persistence when VITEST === "true"
+  "CODEX_MULTI_AUTH_SYNC_CODEX_CLI",
+  "CODEX_AUTH_SYNC_CODEX_CLI",
+  "CODEX_CLI_ACCOUNTS_PATH",
+  "CODEX_CLI_AUTH_PATH",
+  "CODEX_CLI_CONFIG_PATH",
+  "CODEX_MULTI_AUTH_ENFORCE_CLI_FILE_AUTH_STORE",
+  "CODEX_MULTI_AUTH_APP_BIND_CODEX_HOME",
+  "CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY",
+]) {
+  delete process.env[key];
+}
+
+const mod = (p) => import(pathToFileURL(join(distLib, p)).href);
+
+const emitted = [];
+async function emit(name, data) {
+  await fsp.writeFile(join(goldensDir, name), data);
+  emitted.push(name);
+}
+async function copyFixture(sourcePath, name) {
+  await emit(name, await fsp.readFile(sourcePath));
+}
+async function waitForFile(path, predicate, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const raw = await fsp.readFile(path, "utf8");
+      if (predicate(raw)) return raw;
+    } catch {
+      // not there yet
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Timed out waiting for ${path}`);
+}
+
+try {
+  // =========================================================================
+  // 1+2. accounts-v3.json + accounts-v3.wal  (storage.saveAccounts)
+  // =========================================================================
+  const storage = await mod("storage.js");
+
+  const account1 = {
+    accountId: "acct-user-one",
+    accountIdSource: "id_token",
+    accountLabel: "Personal Plus",
+    email: "user.one@example.com",
+    refreshToken: "rt-fixture-account-one-0000000001",
+    accessToken: "at-fixture-account-one-0000000001",
+    expiresAt: EXPIRES_AT,
+    enabled: true,
+    addedAt: 1749900000000,
+    lastUsed: 1749999000000,
+    lastSwitchReason: "rotation",
+    rateLimitResetTimes: { "gpt-5-codex": 1750000600000, codex: 1750000300000 },
+    workspaces: [
+      { id: "ws-personal-1", name: "Personal", enabled: true, isDefault: true },
+      { id: "ws-team-alpha", name: "Team Alpha", enabled: false, disabledAt: 1749950000000 },
+    ],
+    currentWorkspaceIndex: 0,
+  };
+  const account2 = {
+    accountId: "acct-user-two",
+    accountIdSource: "token",
+    accountLabel: "Team Business",
+    email: "user.two@example.com",
+    refreshToken: "rt-fixture-account-two-0000000002",
+    accessToken: "at-fixture-account-two-0000000002",
+    expiresAt: EXPIRES_AT,
+    enabled: true,
+    addedAt: 1749910000000,
+    lastUsed: T0,
+    lastSwitchReason: "manual",
+    rateLimitResetTimes: { "gpt-5.2": 1750001200000 },
+    coolingDownUntil: 1750000060000,
+    cooldownReason: "rate-limit",
+    workspaces: [{ id: "ws-biz-2", name: "Business", enabled: true, isDefault: true }],
+    currentWorkspaceIndex: 0,
+  };
+  const accountsStorage = {
+    version: 3,
+    accounts: [account1, account2],
+    activeIndex: 1,
+    activeIndexByFamily: { "gpt-5-codex": 0, "codex-max": 1, codex: 0, "gpt-5.2": 1, "gpt-5.1": 0 },
+    pinnedAccountIndex: 1,
+    affinityGeneration: 4,
+  };
+
+  // WAL capture harness: saveAccounts writes the WAL journal, then deletes it
+  // after the atomic rename succeeds (cleanupWal). To capture the exact bytes
+  // the library wrote, temporarily wrap fs.promises.unlink so the *.wal file is
+  // read (not blocked -- the real unlink still runs) right before deletion.
+  const realUnlink = fsp.unlink;
+  let walBytes = null;
+  fsp.unlink = async function patchedUnlink(target, ...rest) {
+    if (typeof target === "string" && target.endsWith(".wal") && walBytes === null) {
+      try {
+        walBytes = await fsp.readFile(target);
+      } catch {
+        // ignore; fall through to the real unlink
+      }
+    }
+    return realUnlink.call(this, target, ...rest);
+  };
+  try {
+    await storage.saveAccounts(accountsStorage);
+  } finally {
+    fsp.unlink = realUnlink;
+  }
+  if (!walBytes) throw new Error("WAL journal was not captured during saveAccounts");
+
+  await copyFixture(join(multiAuthDir, "openai-codex-accounts.json"), "accounts-v3.json");
+
+  // Post-process (documented): createdAt is Date.now(), path embeds the sandbox
+  // dir. checksum covers only `content`, so neither replacement invalidates it.
+  const walEntry = JSON.parse(walBytes.toString("utf8"));
+  walEntry.createdAt = T0;
+  walEntry.path = "/golden/multi-auth/openai-codex-accounts.json";
+  await emit("accounts-v3.wal", JSON.stringify(walEntry));
+
+  // =========================================================================
+  // 3. flagged-v1.json  (storage.saveFlaggedAccounts)
+  // =========================================================================
+  await storage.saveFlaggedAccounts({
+    version: 1,
+    accounts: [
+      {
+        refreshToken: "rt-fixture-flagged-0000000003",
+        addedAt: 1749800000000,
+        lastUsed: 1749990000000,
+        accountId: "acct-user-three",
+        accountIdSource: "id_token",
+        accountLabel: "Flagged Account",
+        email: "user.three@example.com",
+        accessToken: "at-fixture-flagged-0000000003",
+        expiresAt: EXPIRES_AT,
+        enabled: false,
+        lastSwitchReason: "rate-limit",
+        rateLimitResetTimes: { codex: 1750000900000 },
+        coolingDownUntil: EXPIRES_AT,
+        cooldownReason: "auth-failure",
+        workspaces: [{ id: "ws-three-1", name: "Personal", enabled: true, isDefault: true }],
+        currentWorkspaceIndex: 0,
+        flaggedAt: T0,
+        flaggedReason: "invalid_grant on refresh",
+        lastError: "401 Unauthorized: invalid_grant",
+      },
+    ],
+  });
+  await copyFixture(join(multiAuthDir, "openai-codex-flagged-accounts.json"), "flagged-v1.json");
+
+  // =========================================================================
+  // 4. settings.json  (unified-settings saveUnifiedPluginConfig +
+  //    saveUnifiedDashboardSettings, with library default payloads)
+  // =========================================================================
+  const config = await mod("config.js");
+  const dashboard = await mod("dashboard-settings.js");
+  const unifiedSettings = await mod("unified-settings.js");
+  await unifiedSettings.saveUnifiedPluginConfig(config.getDefaultPluginConfig());
+  await unifiedSettings.saveUnifiedDashboardSettings(dashboard.DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+  await copyFixture(join(multiAuthDir, "settings.json"), "settings.json");
+
+  // =========================================================================
+  // 5. quota-cache.json  (quota-cache saveQuotaCache)
+  // =========================================================================
+  const quotaCache = await mod("quota-cache.js");
+  const quotaEntryOne = {
+    updatedAt: T0,
+    status: 200,
+    model: "gpt-5.2",
+    planType: "plus",
+    primary: { usedPercent: 42, windowMinutes: 300, resetAtMs: 1750010000000 },
+    secondary: { usedPercent: 12.5, windowMinutes: 10080, resetAtMs: 1750600000000 },
+  };
+  const quotaEntryTwo = {
+    updatedAt: T0,
+    status: 429,
+    model: "gpt-5-codex",
+    planType: "team",
+    primary: { usedPercent: 100, windowMinutes: 300, resetAtMs: 1750000600000 },
+    secondary: { usedPercent: 63, windowMinutes: 10080, resetAtMs: 1750550000000 },
+  };
+  await quotaCache.saveQuotaCache({
+    byAccountId: { "acct-user-one": quotaEntryOne, "acct-user-two": quotaEntryTwo },
+    byEmail: { "user.one@example.com": quotaEntryOne, "user.two@example.com": quotaEntryTwo },
+  });
+  await copyFixture(join(multiAuthDir, "quota-cache.json"), "quota-cache.json");
+
+  // =========================================================================
+  // 6. budget-guards.json  (budget-guard upsertBudgetLimit + saveBudgetGuardStore)
+  // =========================================================================
+  const budgetGuard = await mod("budget-guard.js");
+  const budgetStore = await budgetGuard.loadBudgetGuardStore();
+  budgetGuard.upsertBudgetLimit(
+    budgetStore,
+    { key: "team-alpha", window: "day", maxRequests: 500, maxTokens: 2000000, maxCostUsd: 25 },
+    T0,
+  );
+  budgetGuard.upsertBudgetLimit(budgetStore, { key: "personal", window: "month", maxCostUsd: 100 }, T0);
+  await budgetGuard.saveBudgetGuardStore(budgetStore);
+  await copyFixture(join(multiAuthDir, "budget-guards.json"), "budget-guards.json");
+
+  // =========================================================================
+  // 7. account-policies.json  (account-policy getAccountPolicyKey +
+  //    upsertAccountPolicy + saveAccountPolicyStore)
+  // =========================================================================
+  const accountPolicy = await mod("account-policy.js");
+  const policyKeyOne = accountPolicy.getAccountPolicyKey({ accountId: "acct-user-one" }, 0);
+  const policyKeyTwo = accountPolicy.getAccountPolicyKey({ accountId: "acct-user-two" }, 1);
+  const policyStore = await accountPolicy.loadAccountPolicyStore();
+  accountPolicy.upsertAccountPolicy(
+    policyStore,
+    policyKeyOne,
+    (policy) => {
+      policy.tags = ["personal", "primary"];
+      policy.weight = 2;
+      policy.note = "Primary fixture account";
+    },
+    T0,
+  );
+  accountPolicy.upsertAccountPolicy(
+    policyStore,
+    policyKeyTwo,
+    (policy) => {
+      policy.tags = ["team"];
+      policy.weight = 1;
+      policy.paused = true;
+      policy.note = "Paused fixture account";
+    },
+    T0,
+  );
+  await accountPolicy.saveAccountPolicyStore(policyStore);
+  await copyFixture(join(multiAuthDir, "account-policies.json"), "account-policies.json");
+
+  // =========================================================================
+  // 8. routing-profiles.json  (routing-profiles createDefaultRoutingProfile +
+  //    upsertRoutingProfile + saveRoutingProfileStore)
+  // =========================================================================
+  const routingProfiles = await mod("routing-profiles.js");
+  const routingStore = await routingProfiles.loadRoutingProfileStore();
+  const routingProfile = routingProfiles.createDefaultRoutingProfile({
+    projectKey: "my-app-0123456789ab",
+    projectName: "my-app",
+    identityRoot: "/workspace/my-app",
+    now: T0,
+  });
+  routingProfiles.upsertRoutingProfile(
+    routingStore,
+    routingProfile,
+    (profile) => {
+      profile.preferredTags = ["primary"];
+      profile.avoidTags = ["burner"];
+      profile.modelAllowlist = ["gpt-5.2", "gpt-5-codex"];
+      profile.accountWeightByKey = { [policyKeyOne]: 2, [policyKeyTwo]: 0.5 };
+      profile.budgetKey = "team-alpha";
+    },
+    T0,
+  );
+  await routingProfiles.saveRoutingProfileStore(routingStore);
+  await copyFixture(join(multiAuthDir, "routing-profiles.json"), "routing-profiles.json");
+
+  // =========================================================================
+  // 9. local-client-tokens.json  (local-client-tokens addLocalClientToken)
+  // =========================================================================
+  const localClientTokens = await mod("local-client-tokens.js");
+  await localClientTokens.addLocalClientToken({ label: "workstation", now: T0 });
+  // Post-process (documented): id is randomUUID(), prefix/tokenHash derive from
+  // randomBytes(32). Replaced with values derived from FIXED_PLAIN_TOKEN so the
+  // record stays internally consistent (prefix = first 18 chars of the plain
+  // token, tokenHash = sha256 of the plain token, library's own scheme).
+  const tokenStore = JSON.parse(await fsp.readFile(join(multiAuthDir, "local-client-tokens.json"), "utf8"));
+  tokenStore.tokens[0].id = FIXED_TOKEN_UUID;
+  tokenStore.tokens[0].prefix = FIXED_PLAIN_TOKEN.slice(0, 18);
+  tokenStore.tokens[0].tokenHash = `sha256:${sha256hex(FIXED_PLAIN_TOKEN)}`;
+  await emit("local-client-tokens.json", `${JSON.stringify(tokenStore, null, 2)}\n`);
+
+  // =========================================================================
+  // 10. runtime-observability.json  (runtime-observability
+  //     mutateRuntimeObservabilitySnapshot -> debounced persisted snapshot)
+  // =========================================================================
+  const observability = await mod("runtime/runtime-observability.js");
+  observability.mutateRuntimeObservabilitySnapshot((snapshot) => {
+    snapshot.responsesRequests = 3;
+    snapshot.authRefreshRequests = 1;
+    snapshot.lastAccountIndex = 1;
+    snapshot.lastAccountLabel = "Team Business";
+    snapshot.lastAccountEmail = "user.two@example.com";
+    snapshot.lastAccountId = "acct-user-two";
+    snapshot.lastAccountUpdatedAt = T0;
+    snapshot.lastPoolExhaustionReason = "all-accounts-rate-limited";
+    snapshot.lastPoolExhaustionRetryAfterMs = 30000;
+    snapshot.lastPoolExhaustionSkipReasons = { 0: "rate-limited", 1: "cooldown" };
+    snapshot.accountSkipReasons = { 0: "rate-limited" };
+    snapshot.policyBlockedIndexes = [2];
+    snapshot.policyBlockedReasons = { 2: "paused" };
+    snapshot.lastRuntimeReloadAt = T0;
+    snapshot.lastRuntimeReloadReason = "accounts-file-changed";
+    Object.assign(snapshot.runtimeMetrics, {
+      startedAt: 1749990000000,
+      totalRequests: 3,
+      successfulRequests: 2,
+      failedRequests: 1,
+      responsesRequests: 3,
+      authRefreshRequests: 1,
+      rateLimitedResponses: 1,
+      accountRotations: 1,
+      cumulativeLatencyMs: 5150,
+      lastRequestAt: T0,
+      lastError: "429 rate_limit_exceeded",
+    });
+  });
+  const snapshotPath = join(multiAuthDir, "runtime-observability.json");
+  const snapshotRaw = await waitForFile(snapshotPath, (raw) => {
+    try {
+      return JSON.parse(raw).updatedAt > 0;
+    } catch {
+      return false;
+    }
+  });
+  // Post-process (documented): updatedAt is stamped Date.now() by the library.
+  const snapshot = JSON.parse(snapshotRaw);
+  snapshot.updatedAt = T0;
+  await emit("runtime-observability.json", JSON.stringify(snapshot, null, 2));
+
+  // =========================================================================
+  // 11. app-bind-state.json  (runtime/app-bind bindCodexAppRuntimeRotation;
+  //     on-disk name runtime-rotation-app-bind.json)
+  // =========================================================================
+  const appBind = await mod("runtime/app-bind.js");
+  const configToml = await mod("runtime/config-toml.js");
+  const bindDir = join(multiAuthDir, "app-bind");
+  await fsp.mkdir(appBindCodexHome, { recursive: true });
+  await fsp.writeFile(join(appBindCodexHome, "config.toml"), MINIMAL_CONFIG_TOML, "utf8");
+  await fsp.mkdir(bindDir, { recursive: true });
+  // Seeded INPUT (documented): a router status file reporting a live router on a
+  // fixed port, so bind resolves port 8123 without spawning a real router
+  // process. pid = this generator process (alive for the isProcessAlive check).
+  await fsp.writeFile(
+    join(bindDir, "runtime-rotation-app-bind-status.json"),
+    `${JSON.stringify({ state: "running", pid: process.pid, baseUrl: BASE_URL, totalRequests: 0, updatedAt: T0 })}\n`,
+    "utf8",
+  );
+  const bindEnv = {
+    CODEX_MULTI_AUTH_APP_BIND_CODEX_HOME: appBindCodexHome,
+    CODEX_MULTI_AUTH_DIR: multiAuthDir,
+  };
+  await appBind.bindCodexAppRuntimeRotation({
+    env: bindEnv,
+    platform: "linux", // no Startup/LaunchAgent side files; stable platform field
+    home: sandbox,
+    now: () => T0,
+    nodePath: "/usr/bin/node",
+    routerScriptPath: "/opt/codex-multi-auth/scripts/codex-app-router.js",
+    spawnDetached: false,
+  });
+  // Post-process (documented): clientApiKey is randomBytes(32).hex -> replaced
+  // with FIXED_CLIENT_KEY; boundConfigHash recomputed with the library's own
+  // rewriteConfigTomlForAppBind over the same inputs so it stays consistent
+  // (it equals sha256 of config-toml-provider-block.toml); sandbox-absolute
+  // paths replaced with stable /golden placeholders.
+  const bindState = JSON.parse(await fsp.readFile(join(bindDir, "runtime-rotation-app-bind.json"), "utf8"));
+  bindState.clientApiKey = FIXED_CLIENT_KEY;
+  bindState.boundConfigHash = sha256hex(
+    appBind.rewriteConfigTomlForAppBind(MINIMAL_CONFIG_TOML, BASE_URL, FIXED_CLIENT_KEY),
+  );
+  bindState.configPath = "/golden/codex-home/config.toml";
+  bindState.statePath = "/golden/multi-auth/app-bind/runtime-rotation-app-bind.json";
+  bindState.backupPath = "/golden/multi-auth/app-bind/codex-config-backup.json";
+  bindState.statusPath = "/golden/multi-auth/app-bind/runtime-rotation-app-bind-status.json";
+  bindState.logPath = "/golden/multi-auth/app-bind/runtime-rotation-app-router.log";
+  await emit("app-bind-state.json", `${JSON.stringify(bindState, null, 2)}\n`);
+
+  // =========================================================================
+  // 12. first-run-setup.json  (runtime/first-run ensureFirstRunSetup)
+  // =========================================================================
+  const firstRun = await mod("runtime/first-run.js");
+  const firstRunResult = await firstRun.ensureFirstRunSetup({
+    env: {},
+    installedContext: true,
+    markerPath: join(multiAuthDir, "first-run-setup.json"),
+    now: () => T0,
+    resolveRotation: () => true,
+    bindCodexApp: async () => "completed",
+    installLauncher: async () => "skipped",
+    notify: () => {},
+  });
+  if (!firstRunResult.ran) throw new Error(`first-run setup did not run: ${firstRunResult.reason}`);
+  await copyFixture(join(multiAuthDir, "first-run-setup.json"), "first-run-setup.json");
+
+  // =========================================================================
+  // 13. usage-ledger-row.jsonl  (usage/ledger appendUsageLedgerRow)
+  // =========================================================================
+  const ledger = await mod("usage/ledger.js");
+  await ledger.appendUsageLedgerRow({
+    id: "usage-fixture-0000000000000001",
+    createdAt: T0,
+    source: "runtime-proxy",
+    operation: "responses",
+    outcome: "success",
+    model: "gpt-5.2",
+    projectKey: "my-app-0123456789ab",
+    accountId: "acct-user-one",
+    email: "User.One@Example.com", // library lowercases before hashing
+    accountIndex: 0,
+    requestId: "req-fixture-0001",
+    statusCode: 200,
+    durationMs: 1234,
+    inputTokens: 1200,
+    outputTokens: 350,
+    cachedInputTokens: 800,
+    reasoningTokens: 64,
+    costUsd: 0.0123,
+  });
+  await copyFixture(join(multiAuthDir, "usage", "usage-ledger.jsonl"), "usage-ledger-row.jsonl");
+
+  // =========================================================================
+  // 14. update-check-cache.json  (update-notice checkForUpdates with the npm
+  //     registry fetch stubbed to a fixed payload)
+  // =========================================================================
+  const updateNotice = await mod("update-notice.js");
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = async () =>
+    new Response(JSON.stringify({ name: "codex-multi-auth", version: "9.9.9" }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  try {
+    await updateNotice.checkForUpdates(true);
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+  // Post-process (documented): lastCheck is stamped Date.now() by the library.
+  const updateCache = JSON.parse(
+    await fsp.readFile(join(multiAuthDir, "cache", "update-check-cache.json"), "utf8"),
+  );
+  updateCache.lastCheck = T0;
+  await emit("update-check-cache.json", JSON.stringify(updateCache, null, 2));
+
+  // =========================================================================
+  // 15+16. codex-cli-accounts.json + codex-cli-auth.json
+  //        (codex-cli/writer setCodexCliActiveSelection mirror writer)
+  // =========================================================================
+  const cliWriter = await mod("codex-cli/writer.js");
+  await fsp.mkdir(codexHome, { recursive: true });
+  // Seeded INPUT (documented): a pre-existing Codex CLI accounts.json that the
+  // mirror writer rewrites in place (it only touches accounts.json when the
+  // file already exists).
+  const seededCliAccounts = {
+    accounts: [
+      {
+        accountId: "acct-user-one",
+        email: "user.one@example.com",
+        access_token: "at-old-cli-one",
+        refresh_token: "rt-old-cli-one",
+        id_token: "idt-old-cli-one",
+        active: false,
+      },
+      {
+        accountId: "acct-user-two",
+        email: "user.two@example.com",
+        access_token: "at-old-cli-two",
+        refresh_token: "rt-old-cli-two",
+        id_token: "idt-old-cli-two",
+        active: true,
+      },
+    ],
+    activeAccountId: "acct-user-two",
+    active_account_id: "acct-user-two",
+  };
+  await fsp.writeFile(join(codexHome, "accounts.json"), JSON.stringify(seededCliAccounts, null, 2), "utf8");
+  const wroteSelection = await cliWriter.setCodexCliActiveSelection({
+    accountId: "acct-user-one",
+    email: "user.one@example.com",
+    accessToken: "at-fixture-account-one-0000000001",
+    refreshToken: "rt-fixture-account-one-0000000001",
+    expiresAt: EXPIRES_AT,
+    idToken: "idt-fixture-account-one-0000000001",
+  });
+  if (!wroteSelection) throw new Error("setCodexCliActiveSelection reported failure");
+  // Post-process (documented): codexMultiAuthSyncVersion is stamped Date.now()
+  // by the library in both mirror files.
+  const cliAccounts = JSON.parse(await fsp.readFile(join(codexHome, "accounts.json"), "utf8"));
+  cliAccounts.codexMultiAuthSyncVersion = T0;
+  await emit("codex-cli-accounts.json", JSON.stringify(cliAccounts, null, 2));
+  const cliAuth = JSON.parse(await fsp.readFile(join(codexHome, "auth.json"), "utf8"));
+  cliAuth.codexMultiAuthSyncVersion = T0;
+  await emit("codex-cli-auth.json", JSON.stringify(cliAuth, null, 2));
+
+  // =========================================================================
+  // 17. config-toml-provider-block.toml  (runtime/config-toml
+  //     rewriteConfigTomlForRuntimeRotationProvider, pure function)
+  // =========================================================================
+  const rewrittenConfig = configToml.rewriteConfigTomlForRuntimeRotationProvider(
+    MINIMAL_CONFIG_TOML,
+    BASE_URL,
+    FIXED_CLIENT_KEY,
+  );
+  await emit("config-toml-provider-block.toml", rewrittenConfig);
+
+  // =========================================================================
+  // Verify all fixtures landed, then clean up the sandbox.
+  // =========================================================================
+  const expected = [
+    "accounts-v3.json",
+    "accounts-v3.wal",
+    "flagged-v1.json",
+    "settings.json",
+    "quota-cache.json",
+    "budget-guards.json",
+    "account-policies.json",
+    "routing-profiles.json",
+    "local-client-tokens.json",
+    "runtime-observability.json",
+    "app-bind-state.json",
+    "first-run-setup.json",
+    "usage-ledger-row.jsonl",
+    "update-check-cache.json",
+    "codex-cli-accounts.json",
+    "codex-cli-auth.json",
+    "config-toml-provider-block.toml",
+  ];
+  const missing = [];
+  for (const name of expected) {
+    const stat = await fsp.stat(join(goldensDir, name)).catch(() => null);
+    if (!stat || stat.size === 0) missing.push(name);
+  }
+  if (missing.length > 0) {
+    throw new Error(`Missing or empty fixtures: ${missing.join(", ")}`);
+  }
+  console.log(`OK: ${expected.length} fixtures written to ${goldensDir}`);
+  for (const name of expected) {
+    const bytes = await fsp.readFile(join(goldensDir, name));
+    console.log(`  ${name}  ${bytes.length} bytes  sha256:${sha256hex(bytes).slice(0, 16)}`);
+  }
+} finally {
+  await fsp.rm(sandbox, { recursive: true, force: true }).catch(() => {});
+}
+
+// Some imported dist modules keep timers/queues alive; exit explicitly.
+process.exit(0);
diff --git a/crates/testkit/goldens/local-client-tokens.json b/crates/testkit/goldens/local-client-tokens.json
new file mode 100644
index 000000000..6f16a2834
--- /dev/null
+++ b/crates/testkit/goldens/local-client-tokens.json
@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "tokens": [
+    {
+      "id": "00000000-0000-4000-8000-000000000001",
+      "label": "workstation",
+      "prefix": "cma_local_AAECAwQF",
+      "tokenHash": "sha256:7de937f6bef93e60a3f6fa9074d756f2b62a7c0b9c5621cef751b47fdf84480f",
+      "createdAt": 1750000000000,
+      "lastUsedAt": null,
+      "revokedAt": null
+    }
+  ]
+}
diff --git a/crates/testkit/goldens/quota-cache.json b/crates/testkit/goldens/quota-cache.json
new file mode 100644
index 000000000..0918eb449
--- /dev/null
+++ b/crates/testkit/goldens/quota-cache.json
@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "byAccountId": {
+    "acct-user-one": {
+      "updatedAt": 1750000000000,
+      "status": 200,
+      "model": "gpt-5.2",
+      "planType": "plus",
+      "primary": {
+        "usedPercent": 42,
+        "windowMinutes": 300,
+        "resetAtMs": 1750010000000
+      },
+      "secondary": {
+        "usedPercent": 12.5,
+        "windowMinutes": 10080,
+        "resetAtMs": 1750600000000
+      }
+    },
+    "acct-user-two": {
+      "updatedAt": 1750000000000,
+      "status": 429,
+      "model": "gpt-5-codex",
+      "planType": "team",
+      "primary": {
+        "usedPercent": 100,
+        "windowMinutes": 300,
+        "resetAtMs": 1750000600000
+      },
+      "secondary": {
+        "usedPercent": 63,
+        "windowMinutes": 10080,
+        "resetAtMs": 1750550000000
+      }
+    }
+  },
+  "byEmail": {
+    "user.one@example.com": {
+      "updatedAt": 1750000000000,
+      "status": 200,
+      "model": "gpt-5.2",
+      "planType": "plus",
+      "primary": {
+        "usedPercent": 42,
+        "windowMinutes": 300,
+        "resetAtMs": 1750010000000
+      },
+      "secondary": {
+        "usedPercent": 12.5,
+        "windowMinutes": 10080,
+        "resetAtMs": 1750600000000
+      }
+    },
+    "user.two@example.com": {
+      "updatedAt": 1750000000000,
+      "status": 429,
+      "model": "gpt-5-codex",
+      "planType": "team",
+      "primary": {
+        "usedPercent": 100,
+        "windowMinutes": 300,
+        "resetAtMs": 1750000600000
+      },
+      "secondary": {
+        "usedPercent": 63,
+        "windowMinutes": 10080,
+        "resetAtMs": 1750550000000
+      }
+    }
+  }
+}
diff --git a/crates/testkit/goldens/routing-profiles.json b/crates/testkit/goldens/routing-profiles.json
new file mode 100644
index 000000000..b0132660d
--- /dev/null
+++ b/crates/testkit/goldens/routing-profiles.json
@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "profiles": {
+    "my-app-0123456789ab": {
+      "projectKey": "my-app-0123456789ab",
+      "projectName": "my-app",
+      "identityRoot": "/workspace/my-app",
+      "preferredTags": [
+        "primary"
+      ],
+      "avoidTags": [
+        "burner"
+      ],
+      "modelAllowlist": [
+        "gpt-5-codex",
+        "gpt-5.2"
+      ],
+      "modelDenylist": [],
+      "accountWeightByKey": {
+        "sha256:7dafc00442dea304b0c5d8639eb8980385d63c449b9ff6575eff2e8638af520a": 2,
+        "sha256:0b8d380cc8093df83db8e2144faf9aa628e69c44eec806942ccba174d09bbbcd": 0.5
+      },
+      "budgetKey": "team-alpha",
+      "updatedAt": 1750000000000
+    }
+  }
+}
diff --git a/crates/testkit/goldens/runtime-observability.json b/crates/testkit/goldens/runtime-observability.json
new file mode 100644
index 000000000..b8d65c7df
--- /dev/null
+++ b/crates/testkit/goldens/runtime-observability.json
@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "updatedAt": 1750000000000,
+  "currentRequestId": null,
+  "responsesRequests": 3,
+  "authRefreshRequests": 1,
+  "diagnosticProbeRequests": 0,
+  "poolExhaustionCooldownUntil": null,
+  "serverBurstCooldownUntil": null,
+  "lastAccountIndex": 1,
+  "lastAccountLabel": "Team Business",
+  "lastAccountEmail": "user.two@example.com",
+  "lastAccountId": "acct-user-two",
+  "lastAccountUpdatedAt": 1750000000000,
+  "lastPoolExhaustionReason": "all-accounts-rate-limited",
+  "lastPoolExhaustionRetryAfterMs": 30000,
+  "lastPoolExhaustionSkipReasons": {
+    "0": "rate-limited",
+    "1": "cooldown"
+  },
+  "lastRuntimeResetAt": null,
+  "lastRuntimeResetReason": null,
+  "lastRuntimeReloadAt": 1750000000000,
+  "lastRuntimeReloadReason": "accounts-file-changed",
+  "accountSkipReasons": {
+    "0": "rate-limited"
+  },
+  "policyBlockedIndexes": [
+    2
+  ],
+  "policyBlockedReasons": {
+    "2": "paused"
+  },
+  "runtimeMetrics": {
+    "startedAt": 1749990000000,
+    "totalRequests": 3,
+    "successfulRequests": 2,
+    "failedRequests": 1,
+    "responsesRequests": 3,
+    "authRefreshRequests": 1,
+    "diagnosticProbeRequests": 0,
+    "outboundRequestAttemptBudget": null,
+    "outboundRequestAttemptsConsumed": 0,
+    "requestAttemptBudgetExhaustions": 0,
+    "poolExhaustionFastFails": 0,
+    "serverBurstFastFails": 0,
+    "rateLimitedResponses": 1,
+    "serverErrors": 0,
+    "networkErrors": 0,
+    "userAborts": 0,
+    "authRefreshFailures": 0,
+    "emptyResponseRetries": 0,
+    "accountRotations": 1,
+    "sameAccountRetries": 0,
+    "streamFailoverAttempts": 0,
+    "streamFailoverCandidatesConsidered": 0,
+    "lastStreamFailoverCandidateCount": 0,
+    "streamFailoverRecoveries": 0,
+    "streamFailoverCrossAccountRecoveries": 0,
+    "cumulativeLatencyMs": 5150,
+    "lastRequestAt": 1750000000000,
+    "lastError": "429 rate_limit_exceeded"
+  }
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/settings.json b/crates/testkit/goldens/settings.json
new file mode 100644
index 000000000..95a4ad5bd
--- /dev/null
+++ b/crates/testkit/goldens/settings.json
@@ -0,0 +1,91 @@
+{
+  "pluginConfig": {
+    "codexMode": true,
+    "codexRuntimeRotationProxy": true,
+    "codexTuiV2": true,
+    "codexTuiColorProfile": "truecolor",
+    "codexTuiGlyphMode": "ascii",
+    "fastSession": false,
+    "fastSessionStrategy": "hybrid",
+    "fastSessionMaxInputItems": 30,
+    "retryAllAccountsRateLimited": false,
+    "retryAllAccountsMaxWaitMs": 0,
+    "retryAllAccountsMaxRetries": 0,
+    "unsupportedCodexPolicy": "strict",
+    "fallbackOnUnsupportedCodexModel": false,
+    "fallbackToGpt52OnUnsupportedGpt53": true,
+    "unsupportedCodexFallbackChain": {},
+    "tokenRefreshSkewMs": 60000,
+    "rateLimitToastDebounceMs": 60000,
+    "toastDurationMs": 5000,
+    "perProjectAccounts": true,
+    "sessionRecovery": true,
+    "autoResume": true,
+    "parallelProbing": false,
+    "parallelProbingMaxConcurrency": 2,
+    "emptyResponseMaxRetries": 2,
+    "emptyResponseRetryDelayMs": 1000,
+    "rateLimitDedupWindowMs": 2000,
+    "rateLimitStateResetMs": 120000,
+    "rateLimitMaxBackoffMs": 60000,
+    "rateLimitShortRetryThresholdMs": 5000,
+    "pidOffsetEnabled": true,
+    "fetchTimeoutMs": 60000,
+    "streamStallTimeoutMs": 45000,
+    "liveAccountSync": true,
+    "liveAccountSyncDebounceMs": 250,
+    "liveAccountSyncPollMs": 2000,
+    "sessionAffinity": true,
+    "sessionAffinityTtlMs": 1200000,
+    "sessionAffinityMaxEntries": 512,
+    "responseContinuation": false,
+    "backgroundResponses": false,
+    "proactiveRefreshGuardian": true,
+    "proactiveRefreshIntervalMs": 60000,
+    "proactiveRefreshBufferMs": 300000,
+    "networkErrorCooldownMs": 6000,
+    "serverErrorCooldownMs": 4000,
+    "tokenInvalidationCooldownMs": 300000,
+    "minRotationIntervalMs": 60000,
+    "storageBackupEnabled": true,
+    "preemptiveQuotaEnabled": true,
+    "preemptiveQuotaRemainingPercent5h": 5,
+    "preemptiveQuotaRemainingPercent7d": 5,
+    "preemptiveQuotaMaxDeferralMs": 7200000,
+    "routingMutex": "legacy",
+    "schedulingStrategy": "hybrid"
+  },
+  "version": 1,
+  "dashboardDisplaySettings": {
+    "showPerAccountRows": true,
+    "showQuotaDetails": true,
+    "showForecastReasons": true,
+    "showRecommendations": true,
+    "showLiveProbeNotes": true,
+    "actionAutoReturnMs": 2000,
+    "actionPauseOnKey": true,
+    "menuAutoFetchLimits": true,
+    "menuSortEnabled": true,
+    "menuSortMode": "ready-first",
+    "menuSortPinCurrent": false,
+    "menuSortQuickSwitchVisibleRow": true,
+    "uiThemePreset": "green",
+    "uiAccentColor": "green",
+    "menuShowStatusBadge": true,
+    "menuShowCurrentBadge": true,
+    "menuShowLastUsed": true,
+    "menuShowQuotaSummary": true,
+    "menuShowQuotaCooldown": true,
+    "menuShowFetchStatus": true,
+    "menuShowDetailsForUnselectedRows": false,
+    "menuLayoutMode": "compact-details",
+    "menuQuotaTtlMs": 300000,
+    "menuFocusStyle": "row-invert",
+    "menuHighlightCurrentRow": true,
+    "menuStatuslineFields": [
+      "last-used",
+      "limits",
+      "status"
+    ]
+  }
+}
diff --git a/crates/testkit/goldens/update-check-cache.json b/crates/testkit/goldens/update-check-cache.json
new file mode 100644
index 000000000..17bfd407b
--- /dev/null
+++ b/crates/testkit/goldens/update-check-cache.json
@@ -0,0 +1,5 @@
+{
+  "lastCheck": 1750000000000,
+  "latestVersion": "9.9.9",
+  "currentVersion": "2.7.1"
+}
\ No newline at end of file
diff --git a/crates/testkit/goldens/usage-ledger-row.jsonl b/crates/testkit/goldens/usage-ledger-row.jsonl
new file mode 100644
index 000000000..e04d8a39b
--- /dev/null
+++ b/crates/testkit/goldens/usage-ledger-row.jsonl
@@ -0,0 +1 @@
+{"version":1,"id":"usage-fixture-0000000000000001","createdAt":1750000000000,"source":"runtime-proxy","operation":"responses","outcome":"success","model":"gpt-5.2","projectKey":"my-app-0123456789ab","account":{"accountHash":"sha256:7dafc00442dea304b0c5d8639eb8980385d63c449b9ff6575eff2e8638af520a","emailHash":"sha256:f5a8d0510985a6e5261673053fc3698df6c9b9f02d3174f8f012d6a74c30ff7d","index":0},"requestId":"req-fixture-0001","statusCode":200,"errorCode":null,"durationMs":1234,"tokens":{"inputTokens":1200,"outputTokens":350,"cachedInputTokens":800,"reasoningTokens":64,"totalTokens":1614},"costUsd":0.0123}
diff --git a/crates/testkit/src/goldens.rs b/crates/testkit/src/goldens.rs
new file mode 100644
index 000000000..dace203d8
--- /dev/null
+++ b/crates/testkit/src/goldens.rs
@@ -0,0 +1,669 @@
+//! Golden-fixture helpers — byte-compare test output against TS-produced fixtures
+//! under `crates/testkit/goldens/` (ARCHITECTURE.md §7 F6 / §9.1).
+//!
+//! Golden fixtures are the byte-compat gate for every persisted format (accounts
+//! v3, WAL, flagged, settings.json, quota-cache, …). They are **seeded by running
+//! the existing TypeScript tool** — the Rust side only READS them. There is
+//! deliberately no "bless"/update mode here: regenerating goldens from Rust output
+//! would let byte drift certify itself (§8.1 is the contract these tests enforce).
+//!
+//! Primary API: [`assert_golden_bytes`] — compare exact bytes with a diagnostic
+//! diff (first-diff offset, line diff, trailing-newline and JSON-formatting-only
+//! notes). [`assert_golden_json`] is a softer, *semantic* JSON comparison for
+//! tests that only care about structure; it is NOT a substitute for the byte gate.
+//!
+//! Fixture names use `/` separators relative to the goldens root (e.g.
+//! `"accounts/v3-minimal.json"`). The root resolves to
+//! `<this crate>/goldens/`, overridable via the [`GOLDENS_DIR_ENV`] env var
+//! (tests that set it must be `#[serial(env)]` and should do so through
+//! [`crate::sandbox::EnvSandbox::set_var`]).
+//!
+//! For snapshot-style tests (as opposed to TS-seeded byte fixtures), use the
+//! `insta` crate directly from your own test module — its macros must expand at
+//! the call site so snapshots land next to the calling crate, which is why this
+//! module does not wrap them.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+
+/// Env var that overrides the goldens root directory. Intended for harness
+/// tests; production test suites should rely on the default in-repo location.
+pub const GOLDENS_DIR_ENV: &str = "CMA_TESTKIT_GOLDENS_DIR";
+
+/// The goldens root: `$CMA_TESTKIT_GOLDENS_DIR` when set and non-empty,
+/// otherwise `crates/testkit/goldens/` (resolved from this crate's manifest dir,
+/// so it is stable regardless of the working directory `cargo test` uses).
+pub fn goldens_dir() -> PathBuf {
+    if let Some(dir) = std::env::var_os(GOLDENS_DIR_ENV)
+        && !dir.is_empty()
+    {
+        return PathBuf::from(dir);
+    }
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("goldens")
+}
+
+/// Absolute path of a named golden fixture.
+///
+/// # Panics
+/// Panics on malformed names (empty, `\` separators, `.`/`..` components,
+/// absolute paths, or components containing `:`); goldens are addressed only by
+/// forward-slash-relative names inside the goldens root.
+pub fn golden_path(name: &str) -> PathBuf {
+    join_validated(&goldens_dir(), name)
+}
+
+/// Read a golden fixture, returning the raw `io::Result` for callers that treat
+/// a missing fixture as an expected condition.
+pub fn try_read_golden_bytes(name: &str) -> io::Result<Vec<u8>> {
+    fs::read(golden_path(name))
+}
+
+/// Read a golden fixture's bytes, panicking with an actionable message (goldens
+/// root, available fixture list, seeding instructions) when it cannot be read.
+pub fn read_golden_bytes(name: &str) -> Vec<u8> {
+    read_bytes_at(&goldens_dir(), name)
+}
+
+/// Read a golden fixture as UTF-8 text.
+///
+/// # Panics
+/// Panics when the fixture is missing (see [`read_golden_bytes`]) or not UTF-8.
+pub fn read_golden_string(name: &str) -> String {
+    let bytes = read_golden_bytes(name);
+    match String::from_utf8(bytes) {
+        Ok(text) => text,
+        Err(error) => panic!("golden fixture {name:?} is not valid UTF-8: {error}"),
+    }
+}
+
+/// Read and parse a golden fixture as JSON.
+///
+/// # Panics
+/// Panics when the fixture is missing or not valid JSON.
+pub fn read_golden_json(name: &str) -> Value {
+    read_json_at(&goldens_dir(), name)
+}
+
+/// List every available golden fixture name (recursive, `/`-separated, sorted).
+/// Returns an empty list when the goldens directory does not exist yet.
+pub fn available_goldens() -> Vec<String> {
+    let dir = goldens_dir();
+    let mut names = Vec::new();
+    collect_names(&dir, &dir, &mut names);
+    names.sort();
+    names
+}
+
+/// THE byte-compat assertion: `actual` must equal the golden fixture
+/// byte-for-byte. On mismatch, panics with the first-diff offset, a line diff
+/// (or hex context for binary content), and targeted notes for the two most
+/// common drift classes — trailing-newline-matrix violations and
+/// formatting-only JSON differences (§8.1).
+pub fn assert_golden_bytes(name: &str, actual: impl AsRef<[u8]>) {
+    assert_bytes_at(&goldens_dir(), name, actual.as_ref());
+}
+
+/// [`assert_golden_bytes`] for string output.
+pub fn assert_golden_str(name: &str, actual: &str) {
+    assert_golden_bytes(name, actual.as_bytes());
+}
+
+/// SEMANTIC JSON comparison against a golden fixture: order-insensitive for
+/// object keys, exact for values and array order. Reports the first divergent
+/// JSON path on failure.
+///
+/// This is deliberately weaker than [`assert_golden_bytes`] — key order,
+/// indentation, and trailing newlines are invisible to it. Byte-compat gates
+/// (§9.1) must use [`assert_golden_bytes`].
+pub fn assert_golden_json(name: &str, actual: &Value) {
+    assert_json_at(&goldens_dir(), name, actual);
+}
+
+// ---------------------------------------------------------------------------
+// Internals (path-parameterized so unit tests run against temp dirs without
+// touching process env).
+// ---------------------------------------------------------------------------
+
+fn join_validated(dir: &Path, name: &str) -> PathBuf {
+    assert!(!name.is_empty(), "golden name must not be empty");
+    assert!(
+        !name.contains('\\'),
+        "golden name must use '/' separators: {name:?}"
+    );
+    let mut path = dir.to_path_buf();
+    for component in name.split('/') {
+        assert!(
+            !component.is_empty(),
+            "golden name has an empty path component (absolute names and '//' are rejected): {name:?}"
+        );
+        assert!(
+            component != "." && component != "..",
+            "golden name must not traverse directories: {name:?}"
+        );
+        assert!(
+            !component.contains(':'),
+            "golden name component must not contain ':': {name:?}"
+        );
+        path.push(component);
+    }
+    path
+}
+
+fn read_bytes_at(dir: &Path, name: &str) -> Vec<u8> {
+    let path = join_validated(dir, name);
+    match fs::read(&path) {
+        Ok(bytes) => bytes,
+        Err(error) => panic!("{}", missing_golden_message(dir, name, &path, &error)),
+    }
+}
+
+fn read_json_at(dir: &Path, name: &str) -> Value {
+    let bytes = read_bytes_at(dir, name);
+    match serde_json::from_slice(&bytes) {
+        Ok(value) => value,
+        Err(error) => panic!("golden fixture {name:?} is not valid JSON: {error}"),
+    }
+}
+
+fn assert_bytes_at(dir: &Path, name: &str, actual: &[u8]) {
+    let expected = read_bytes_at(dir, name);
+    if expected == actual {
+        return;
+    }
+    let path = join_validated(dir, name);
+    panic!("{}", describe_mismatch(name, &path, &expected, actual));
+}
+
+fn assert_json_at(dir: &Path, name: &str, actual: &Value) {
+    let expected = read_json_at(dir, name);
+    if &expected == actual {
+        return;
+    }
+    let divergence =
+        first_json_divergence(&expected, actual, "$").unwrap_or_else(|| "$".to_string());
+    // Pretty-printing here is diagnostics-only output; persisted-JSON writes in
+    // feature code must go through cma_core::json_io (§8.1).
+    panic!(
+        "golden JSON mismatch: {name:?}\nfirst divergence at {divergence}\n--- golden ---\n{}\n--- actual ---\n{}\n(semantic compare; the byte-compat gate is assert_golden_bytes)",
+        serde_json::to_string_pretty(&expected).unwrap_or_else(|_| "<unprintable>".into()),
+        serde_json::to_string_pretty(actual).unwrap_or_else(|_| "<unprintable>".into()),
+    );
+}
+
+fn missing_golden_message(dir: &Path, name: &str, path: &Path, error: &io::Error) -> String {
+    let mut message = format!(
+        "golden fixture {name:?} could not be read at {}: {error}\n",
+        path.display()
+    );
+    if dir.is_dir() {
+        let mut names = Vec::new();
+        collect_names(dir, dir, &mut names);
+        names.sort();
+        if names.is_empty() {
+            message.push_str(&format!(
+                "goldens directory {} exists but contains no fixtures.\n",
+                dir.display()
+            ));
+        } else {
+            const MAX_LISTED: usize = 100;
+            message.push_str(&format!(
+                "available goldens under {} ({}):\n",
+                dir.display(),
+                names.len()
+            ));
+            for fixture in names.iter().take(MAX_LISTED) {
+                message.push_str(&format!("  - {fixture}\n"));
+            }
+            if names.len() > MAX_LISTED {
+                message.push_str(&format!("  ... and {} more\n", names.len() - MAX_LISTED));
+            }
+        }
+    } else {
+        message.push_str(&format!(
+            "goldens directory {} does not exist.\n",
+            dir.display()
+        ));
+    }
+    message.push_str(
+        "Goldens are seeded from the TypeScript tool (ARCHITECTURE.md \u{a7}7 F6); \
+         they are never generated by the Rust tests.",
+    );
+    message
+}
+
+fn collect_names(root: &Path, dir: &Path, out: &mut Vec<String>) {
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let Ok(file_type) = entry.file_type() else {
+            continue;
+        };
+        if file_type.is_dir() {
+            collect_names(root, &path, out);
+        } else if let Ok(relative) = path.strip_prefix(root) {
+            let name = relative
+                .components()
+                .map(|component| component.as_os_str().to_string_lossy())
+                .collect::<Vec<_>>()
+                .join("/");
+            out.push(name);
+        }
+    }
+}
+
+fn describe_mismatch(name: &str, path: &Path, expected: &[u8], actual: &[u8]) -> String {
+    let offset = first_diff_offset(expected, actual);
+    let mut out = format!(
+        "golden mismatch: {name:?} ({})\nexpected {} bytes, actual {} bytes; first difference at byte offset {offset}\n",
+        path.display(),
+        expected.len(),
+        actual.len()
+    );
+    if let Some(note) = trailing_newline_note(expected, actual) {
+        out.push_str(note);
+    }
+    if let (Ok(expected_json), Ok(actual_json)) = (
+        serde_json::from_slice::<Value>(expected),
+        serde_json::from_slice::<Value>(actual),
+    ) && expected_json == actual_json
+    {
+        out.push_str(
+            "note: both sides parse to semantically-equal JSON — the difference is \
+             formatting only (indentation, key order, or the trailing-newline matrix; \
+             see ARCHITECTURE.md \u{a7}8.1). The byte-compat gate still fails.\n",
+        );
+    }
+    match (std::str::from_utf8(expected), std::str::from_utf8(actual)) {
+        (Ok(expected_text), Ok(actual_text)) => out.push_str(&text_diff(expected_text, actual_text)),
+        _ => out.push_str(&hex_context(expected, actual, offset)),
+    }
+    out
+}
+
+fn first_diff_offset(expected: &[u8], actual: &[u8]) -> usize {
+    let shared = expected.len().min(actual.len());
+    for index in 0..shared {
+        if expected[index] != actual[index] {
+            return index;
+        }
+    }
+    shared
+}
+
+fn trailing_newline_note(expected: &[u8], actual: &[u8]) -> Option<&'static str> {
+    if expected.len() == actual.len() + 1
+        && expected.ends_with(b"\n")
+        && &expected[..actual.len()] == actual
+    {
+        Some(
+            "note: actual output is MISSING the trailing newline the golden file has \
+             (trailing-newline matrix, ARCHITECTURE.md \u{a7}8.1).\n",
+        )
+    } else if actual.len() == expected.len() + 1
+        && actual.ends_with(b"\n")
+        && &actual[..expected.len()] == expected
+    {
+        Some(
+            "note: actual output HAS a trailing newline the golden file does not \
+             (trailing-newline matrix, ARCHITECTURE.md \u{a7}8.1).\n",
+        )
+    } else {
+        None
+    }
+}
+
+fn text_diff(expected: &str, actual: &str) -> String {
+    const MAX_SHOWN: usize = 8;
+    let expected_lines: Vec<&str> = expected.split('\n').collect();
+    let actual_lines: Vec<&str> = actual.split('\n').collect();
+
+    let mut start = 0;
+    while start < expected_lines.len()
+        && start < actual_lines.len()
+        && expected_lines[start] == actual_lines[start]
+    {
+        start += 1;
+    }
+    let mut expected_end = expected_lines.len();
+    let mut actual_end = actual_lines.len();
+    while expected_end > start
+        && actual_end > start
+        && expected_lines[expected_end - 1] == actual_lines[actual_end - 1]
+    {
+        expected_end -= 1;
+        actual_end -= 1;
+    }
+
+    let mut out =
+        String::from("line diff (- golden, + actual; lines rendered with Debug escapes):\n");
+    for (index, line) in expected_lines
+        .iter()
+        .enumerate()
+        .take(start)
+        .skip(start.saturating_sub(2))
+    {
+        out.push_str(&format!("  {:>4} | {line:?}\n", index + 1));
+    }
+    for (shown, index) in (start..expected_end).enumerate() {
+        if shown == MAX_SHOWN {
+            out.push_str(&format!(
+                "  ... {} more golden line(s) differ\n",
+                expected_end - index
+            ));
+            break;
+        }
+        out.push_str(&format!("- {:>4} | {:?}\n", index + 1, expected_lines[index]));
+    }
+    for (shown, index) in (start..actual_end).enumerate() {
+        if shown == MAX_SHOWN {
+            out.push_str(&format!(
+                "  ... {} more actual line(s) differ\n",
+                actual_end - index
+            ));
+            break;
+        }
+        out.push_str(&format!("+ {:>4} | {:?}\n", index + 1, actual_lines[index]));
+    }
+    out
+}
+
+fn hex_context(expected: &[u8], actual: &[u8], offset: usize) -> String {
+    let start = offset.saturating_sub(16);
+    format!(
+        "binary content; bytes around offset {offset}:\n  golden[{start}..]: {}\n  actual[{start}..]: {}\n",
+        hex_slice(expected, start, 48),
+        hex_slice(actual, start, 48)
+    )
+}
+
+fn hex_slice(bytes: &[u8], start: usize, len: usize) -> String {
+    if start >= bytes.len() {
+        return "<past end>".to_string();
+    }
+    let end = (start + len).min(bytes.len());
+    bytes[start..end]
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn first_json_divergence(expected: &Value, actual: &Value, path: &str) -> Option<String> {
+    match (expected, actual) {
+        (Value::Object(expected_map), Value::Object(actual_map)) => {
+            for (key, expected_value) in expected_map {
+                match actual_map.get(key) {
+                    None => return Some(format!("{path}.{key}: missing from actual")),
+                    Some(actual_value) => {
+                        if let Some(divergence) = first_json_divergence(
+                            expected_value,
+                            actual_value,
+                            &format!("{path}.{key}"),
+                        ) {
+                            return Some(divergence);
+                        }
+                    }
+                }
+            }
+            for key in actual_map.keys() {
+                if !expected_map.contains_key(key) {
+                    return Some(format!("{path}.{key}: unexpected key in actual"));
+                }
+            }
+            None
+        }
+        (Value::Array(expected_items), Value::Array(actual_items)) => {
+            for (index, (expected_value, actual_value)) in
+                expected_items.iter().zip(actual_items.iter()).enumerate()
+            {
+                if let Some(divergence) =
+                    first_json_divergence(expected_value, actual_value, &format!("{path}[{index}]"))
+                {
+                    return Some(divergence);
+                }
+            }
+            if expected_items.len() != actual_items.len() {
+                return Some(format!(
+                    "{path}: array length {} (golden) vs {} (actual)",
+                    expected_items.len(),
+                    actual_items.len()
+                ));
+            }
+            None
+        }
+        _ if expected == actual => None,
+        _ => Some(format!(
+            "{path}: golden {} vs actual {}",
+            short_json(expected),
+            short_json(actual)
+        )),
+    }
+}
+
+fn short_json(value: &Value) -> String {
+    let text = value.to_string();
+    if text.chars().count() > 80 {
+        let truncated: String = text.chars().take(80).collect();
+        format!("{truncated}\u{2026}")
+    } else {
+        text
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::sandbox::EnvSandbox;
+    use serde_json::json;
+    use serial_test::serial;
+
+    fn panic_message<F: FnOnce()>(operation: F) -> String {
+        let payload = std::panic::catch_unwind(std::panic::AssertUnwindSafe(operation))
+            .expect_err("expected the operation to panic");
+        if let Some(text) = payload.downcast_ref::<String>() {
+            text.clone()
+        } else if let Some(text) = payload.downcast_ref::<&str>() {
+            (*text).to_string()
+        } else {
+            "<non-string panic payload>".to_string()
+        }
+    }
+
+    #[test]
+    fn reads_and_asserts_equal_bytes_including_subdirectories() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::create_dir_all(dir.path().join("fixtures")).unwrap();
+        let content = b"{\n  \"version\": 3\n}\n";
+        fs::write(dir.path().join("fixtures").join("sample.json"), content).unwrap();
+
+        assert_eq!(read_bytes_at(dir.path(), "fixtures/sample.json"), content);
+        assert_bytes_at(dir.path(), "fixtures/sample.json", content); // no panic
+    }
+
+    #[test]
+    fn mismatch_reports_offset_and_line_diff() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("g.txt"), "line one\nline two\nline three\n").unwrap();
+
+        let message = panic_message(|| {
+            assert_bytes_at(dir.path(), "g.txt", b"line one\nline 2wo\nline three\n");
+        });
+        assert!(message.contains("golden mismatch"), "{message}");
+        assert!(
+            message.contains("first difference at byte offset 14"),
+            "{message}"
+        );
+        assert!(message.contains("- "), "{message}");
+        assert!(message.contains("+ "), "{message}");
+        assert!(message.contains("line two"), "{message}");
+        assert!(message.contains("line 2wo"), "{message}");
+    }
+
+    #[test]
+    fn trailing_newline_difference_is_called_out_both_ways() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("t.txt"), "abc\n").unwrap();
+        let message = panic_message(|| assert_bytes_at(dir.path(), "t.txt", b"abc"));
+        assert!(message.contains("MISSING the trailing newline"), "{message}");
+
+        fs::write(dir.path().join("u.txt"), "abc").unwrap();
+        let message = panic_message(|| assert_bytes_at(dir.path(), "u.txt", b"abc\n"));
+        assert!(message.contains("HAS a trailing newline"), "{message}");
+    }
+
+    #[test]
+    fn formatting_only_json_difference_gets_a_semantic_note() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("j.json"), "{\n  \"a\": 1\n}\n").unwrap();
+        let message = panic_message(|| assert_bytes_at(dir.path(), "j.json", b"{\"a\":1}"));
+        assert!(message.contains("semantically-equal JSON"), "{message}");
+    }
+
+    #[test]
+    fn semantically_different_json_gets_no_formatting_note() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("j.json"), "{\"a\":1}").unwrap();
+        let message = panic_message(|| assert_bytes_at(dir.path(), "j.json", b"{\"a\":2}"));
+        assert!(!message.contains("semantically-equal JSON"), "{message}");
+    }
+
+    #[test]
+    fn binary_mismatch_falls_back_to_hex_context() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("b.bin"), [0x00u8, 0xff, 0xfe]).unwrap();
+        let message =
+            panic_message(|| assert_bytes_at(dir.path(), "b.bin", &[0x00u8, 0xff, 0x00][..]));
+        assert!(message.contains("binary content"), "{message}");
+        assert!(message.contains("ff fe"), "{message}");
+    }
+
+    #[test]
+    fn missing_fixture_lists_available_goldens_and_seeding_note() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("present.json"), b"{}").unwrap();
+
+        let message = panic_message(|| {
+            read_bytes_at(dir.path(), "absent.json");
+        });
+        assert!(message.contains("could not be read"), "{message}");
+        assert!(message.contains("present.json"), "{message}");
+        assert!(message.contains("seeded from the TypeScript tool"), "{message}");
+    }
+
+    #[test]
+    fn missing_goldens_directory_is_reported() {
+        let dir = tempfile::tempdir().unwrap();
+        let nonexistent = dir.path().join("no-goldens-here");
+        let message = panic_message(|| {
+            read_bytes_at(&nonexistent, "anything.json");
+        });
+        assert!(message.contains("does not exist"), "{message}");
+    }
+
+    #[test]
+    fn golden_names_are_validated() {
+        let dir = tempfile::tempdir().unwrap();
+        let cases: [(&str, &str); 6] = [
+            ("", "must not be empty"),
+            ("a\\b", "'/' separators"),
+            ("../escape", "must not traverse"),
+            ("a/./b", "must not traverse"),
+            ("a//b", "empty path component"),
+            ("c:/evil", "must not contain ':'"),
+        ];
+        for (name, expected_fragment) in cases {
+            let message = panic_message(|| {
+                join_validated(dir.path(), name);
+            });
+            assert!(
+                message.contains(expected_fragment),
+                "name {name:?}: {message}"
+            );
+        }
+    }
+
+    #[test]
+    fn json_divergence_reports_first_divergent_path() {
+        let expected = json!({ "a": { "b": 1 }, "c": [1, 2] });
+        assert_eq!(
+            first_json_divergence(&expected, &json!({ "a": { "b": 2 }, "c": [1, 2] }), "$"),
+            Some("$.a.b: golden 1 vs actual 2".to_string())
+        );
+        assert_eq!(
+            first_json_divergence(&expected, &json!({ "a": { "b": 1 }, "c": [1] }), "$"),
+            Some("$.c: array length 2 (golden) vs 1 (actual)".to_string())
+        );
+        assert_eq!(
+            first_json_divergence(&expected, &json!({ "a": { "b": 1 } }), "$"),
+            Some("$.c: missing from actual".to_string())
+        );
+        assert_eq!(
+            first_json_divergence(
+                &expected,
+                &json!({ "a": { "b": 1 }, "c": [1, 2], "d": true }),
+                "$"
+            ),
+            Some("$.d: unexpected key in actual".to_string())
+        );
+        assert_eq!(first_json_divergence(&expected, &expected.clone(), "$"), None);
+    }
+
+    #[test]
+    fn assert_json_is_semantic_and_reports_path() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("s.json"), "{\"a\":1,\"b\":2}").unwrap();
+        // Key order and formatting are invisible to the semantic compare.
+        assert_json_at(dir.path(), "s.json", &json!({ "b": 2, "a": 1 }));
+
+        let message =
+            panic_message(|| assert_json_at(dir.path(), "s.json", &json!({ "a": 9, "b": 2 })));
+        assert!(message.contains("first divergence at $.a"), "{message}");
+        assert!(message.contains("byte-compat gate"), "{message}");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn env_override_redirects_goldens_dir() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("env.json"), b"{}").unwrap();
+
+        let mut sandbox = EnvSandbox::new();
+        sandbox.set_var(GOLDENS_DIR_ENV, dir.path());
+        assert_eq!(goldens_dir(), dir.path());
+        assert_eq!(golden_path("env.json"), dir.path().join("env.json"));
+        assert_eq!(read_golden_bytes("env.json"), b"{}");
+        assert_eq!(read_golden_string("env.json"), "{}");
+        assert_eq!(read_golden_json("env.json"), json!({}));
+        assert_golden_bytes("env.json", b"{}");
+        assert_golden_str("env.json", "{}");
+        assert_golden_json("env.json", &json!({}));
+        assert_eq!(available_goldens(), vec!["env.json".to_string()]);
+        assert_eq!(
+            try_read_golden_bytes("missing.json")
+                .unwrap_err()
+                .kind(),
+            io::ErrorKind::NotFound
+        );
+    }
+
+    #[test]
+    #[serial(env)]
+    fn default_goldens_dir_points_into_this_crate() {
+        let mut sandbox = EnvSandbox::new();
+        sandbox.remove_var(GOLDENS_DIR_ENV);
+        let dir = goldens_dir();
+        assert!(dir.ends_with("goldens"), "{}", dir.display());
+        assert!(
+            dir.parent()
+                .and_then(|parent| parent.file_name())
+                .is_some_and(|name| name == "testkit"),
+            "{}",
+            dir.display()
+        );
+    }
+}
diff --git a/crates/testkit/src/lib.rs b/crates/testkit/src/lib.rs
new file mode 100644
index 000000000..539e951f2
--- /dev/null
+++ b/crates/testkit/src/lib.rs
@@ -0,0 +1,5 @@
+//! cma-testkit - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod goldens;
+pub mod port1455;
+pub mod remove_with_retry;
+pub mod sandbox;
diff --git a/crates/testkit/src/port1455.rs b/crates/testkit/src/port1455.rs
new file mode 100644
index 000000000..a094ba899
--- /dev/null
+++ b/crates/testkit/src/port1455.rs
@@ -0,0 +1,107 @@
+//! Serialization guard for tests that touch the fixed OAuth callback port **1455**
+//! — the Rust analogue of the vitest single-worker rule (spec 14 §11, harness
+//! invariant 2).
+//!
+//! The OAuth redirect URI is provider-registered against port 1455 and is
+//! immovable (spec 14 §6). The TS suite prevents port collisions by running the
+//! entire suite in ONE worker (`pool: 'forks'`, `fileParallelism: false`,
+//! `--maxWorkers=1` in `vitest.config.ts`) plus an awaited port release in
+//! `test/oauth-server.integration.test.ts`'s `afterEach`. Rust tests run
+//! multi-threaded by default, so the equivalent contract is:
+//!
+//! 1. **Every test that binds, probes, or otherwise depends on port 1455 MUST be
+//!    annotated `#[serial(oauth_1455)]`** — the shared key is
+//!    [`OAUTH_1455_SERIAL_KEY`] (ARCHITECTURE.md §9.4). The attribute macro is
+//!    re-exported here so callers need no direct `serial_test` dependency:
+//!
+//!    ```no_run
+//!    use cma_testkit::port1455::serial;
+//!
+//!    #[serial(oauth_1455)]
+//!    fn callback_server_binds_1455() {
+//!        // ... bind 127.0.0.1:1455, run assertions, and RELEASE the port
+//!        // before returning (awaited shutdown — TS parity).
+//!    }
+//!    ```
+//!
+//! 2. Each such test must fully release the port before returning (drop/await
+//!    server shutdown), mirroring the awaited release in the TS integration
+//!    suite. `serial_test` only serializes test bodies — a leaked listener still
+//!    breaks the next holder of the key.
+//!
+//! Note `cargo test` runs each test *binary* sequentially, so the serial key is
+//! only needed within a binary — but every 1455 test must still carry it, because
+//! unit and integration tests of the same crate share a binary and future suites
+//! may co-locate.
+
+/// The immovable OAuth callback port (provider-registered redirect URI —
+/// `http://localhost:1455/auth/callback`). Test-side pin; the authoritative
+/// runtime constant lives with the OAuth flow in `cma-auth`.
+pub const OAUTH_CALLBACK_PORT: u16 = 1455;
+
+/// The `serial_test` key for port-1455 tests: `#[serial(oauth_1455)]`.
+///
+/// The macro takes the key as a bare identifier; this constant exists so the
+/// convention is greppable, documented, and usable in assertion messages.
+pub const OAUTH_1455_SERIAL_KEY: &str = "oauth_1455";
+
+/// Re-export of the whole `serial_test` crate, so downstream test code can use
+/// additional items (e.g. `parallel`, `file_serial`) without declaring its own
+/// dependency.
+pub use ::serial_test;
+
+/// Re-export of the `#[serial]` attribute macro. Use as
+/// `#[cma_testkit::port1455::serial(oauth_1455)]` or import it:
+/// `use cma_testkit::port1455::serial;` then `#[serial(oauth_1455)]`.
+pub use serial_test::serial;
+
+/// Fail fast (with an actionable message) when port 1455 is already occupied.
+///
+/// Call at the top of a `#[serial(oauth_1455)]` test to distinguish "a previous
+/// test leaked the port" from downstream bind-failure behavior under test (the
+/// callback server itself must NEVER reject on bind failure — it reports
+/// `ready:false` — so without this probe a leaked port turns into confusing
+/// downstream assertions instead of a clear harness error).
+///
+/// # Panics
+/// Panics when `127.0.0.1:1455` cannot be bound.
+pub fn assert_port_1455_free() {
+    match std::net::TcpListener::bind(("127.0.0.1", OAUTH_CALLBACK_PORT)) {
+        Ok(listener) => drop(listener),
+        Err(error) => panic!(
+            "port {OAUTH_CALLBACK_PORT} is already in use ({error}); OAuth-callback tests must \
+             hold #[serial({OAUTH_1455_SERIAL_KEY})] and release the port before returning \
+             (awaited shutdown — see test/oauth-server.integration.test.ts afterEach in the TS suite)"
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Uses the re-exported attribute via `super::*` — proves the re-export works
+    // exactly as downstream crates will consume it.
+    #[test]
+    #[serial(oauth_1455)]
+    fn constants_and_serial_reexport() {
+        assert_eq!(OAUTH_CALLBACK_PORT, 1455);
+        assert_eq!(OAUTH_1455_SERIAL_KEY, "oauth_1455");
+    }
+
+    #[test]
+    #[serial(oauth_1455)]
+    fn port_probe_binds_and_releases() {
+        // Skip (don't fail) when the developer machine genuinely has 1455 busy —
+        // e.g. a live OAuth login in another process. The helper's panic path is
+        // for leaks WITHIN a serialized test run, not ambient occupancy.
+        if std::net::TcpListener::bind(("127.0.0.1", OAUTH_CALLBACK_PORT)).is_err() {
+            eprintln!("skipping port_probe_binds_and_releases: port 1455 busy on this machine");
+            return;
+        }
+        // Bind/drop through the helper twice: if the helper leaked its listener,
+        // the second call would panic.
+        assert_port_1455_free();
+        assert_port_1455_free();
+    }
+}
diff --git a/crates/testkit/src/remove_with_retry.rs b/crates/testkit/src/remove_with_retry.rs
new file mode 100644
index 000000000..51ec5e94f
--- /dev/null
+++ b/crates/testkit/src/remove_with_retry.rs
@@ -0,0 +1,390 @@
+//! Windows-safe removal with retry — Rust port of `test/helpers/remove-with-retry.ts`
+//! (spec 14 §11, harness invariant 3: Windows cleanup always via `removeWithRetry`
+//! — never bare `rm`).
+//!
+//! On Windows, deleting files that another process (antivirus, indexer, a
+//! just-exited child) still holds open fails transiently with sharing/permission
+//! errors. The TS helper retries exactly this class of failures:
+//!
+//! - retryable codes: `EBUSY`, `EPERM`, `ENOTEMPTY`, `EACCES`
+//! - `ENOENT` is success (the target is already gone)
+//! - 6 attempts total, sleeping `25 * 2^attempt` ms between failures
+//!   (25, 50, 100, 200, 400 ms; the 6th failure propagates)
+//! - any other error propagates immediately
+//!
+//! This port is deliberately self-contained (like the TS helper, which does NOT
+//! use `lib/fs-retry.ts`): it carries its own `io::Error` → errno-code mapping so
+//! the testkit stays dependency-light and usable while `cma-core` is still being
+//! ported. Feature code must keep using `cma_core::fs_retry` (ARCHITECTURE.md §8.2).
+
+use std::fs;
+use std::io;
+use std::path::Path;
+use std::thread;
+use std::time::Duration;
+
+/// Error codes the removal loop retries — mirrors `RETRYABLE_REMOVE_CODES` in the
+/// TS helper exactly.
+pub const RETRYABLE_REMOVE_CODES: [&str; 4] = ["EBUSY", "EPERM", "ENOTEMPTY", "EACCES"];
+
+/// Total attempts (TS: `for (let attempt = 0; attempt < 6; ...)`).
+const MAX_ATTEMPTS: u32 = 6;
+
+/// Base backoff in milliseconds (TS: `25 * 2 ** attempt`).
+const BASE_DELAY_MS: u64 = 25;
+
+/// Options mirroring Node's `fs.rm(path, { recursive, force })` shape used by the
+/// TS helper.
+///
+/// - `recursive`: remove directories and their contents; without it, directories
+///   are refused (Node `ERR_FS_EISDIR` parity — a non-retryable error).
+/// - `force`: kept for signature parity. The helper always treats `ENOENT` as
+///   success (the TS helper returns on `ENOENT` before consulting `force`), so
+///   the flag has no additional effect here — exactly as in the TS helper.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RemoveOptions {
+    pub recursive: bool,
+    pub force: bool,
+}
+
+impl RemoveOptions {
+    /// `{ recursive: true, force: true }` — the ubiquitous test-cleanup shape.
+    pub const fn recursive_force() -> Self {
+        Self {
+            recursive: true,
+            force: true,
+        }
+    }
+}
+
+/// Remove `target_path` (file, symlink, or — with `recursive` — a directory tree),
+/// retrying transient Windows sharing/permission failures.
+///
+/// Behavior is a 1:1 port of `removeWithRetry` from `test/helpers/remove-with-retry.ts`:
+/// `ENOENT` returns `Ok(())`; codes in [`RETRYABLE_REMOVE_CODES`] are retried up to
+/// 6 attempts with `25 * 2^attempt` ms sleeps; everything else (and the final
+/// failed attempt) returns the error.
+pub fn remove_with_retry(
+    target_path: impl AsRef<Path>,
+    options: RemoveOptions,
+) -> io::Result<()> {
+    let target_path = target_path.as_ref();
+    for attempt in 0..MAX_ATTEMPTS {
+        match attempt_remove(target_path, options) {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if is_not_found(&error) {
+                    return Ok(());
+                }
+                let retryable = matches!(
+                    code_of(&error),
+                    Some(code) if RETRYABLE_REMOVE_CODES.contains(&code)
+                );
+                if !retryable || attempt == MAX_ATTEMPTS - 1 {
+                    return Err(error);
+                }
+                thread::sleep(Duration::from_millis(BASE_DELAY_MS << attempt));
+            }
+        }
+    }
+    unreachable!("remove_with_retry: the loop returns on every path")
+}
+
+/// Convenience wrapper: `remove_with_retry(path, { recursive: true, force: true })` —
+/// what nearly every test cleanup site wants.
+pub fn remove_recursive_with_retry(target_path: impl AsRef<Path>) -> io::Result<()> {
+    remove_with_retry(target_path, RemoveOptions::recursive_force())
+}
+
+/// One removal attempt, dispatched on the target's (non-followed) file type so
+/// symlinks are removed as links, never traversed (Node `fs.rm` parity).
+fn attempt_remove(path: &Path, options: RemoveOptions) -> io::Result<()> {
+    let metadata = fs::symlink_metadata(path)?;
+    let file_type = metadata.file_type();
+    if file_type.is_symlink() {
+        return remove_symlink(path);
+    }
+    if file_type.is_dir() {
+        if options.recursive {
+            fs::remove_dir_all(path)
+        } else {
+            // Node: fs.rm(dir, { recursive: false }) → ERR_FS_EISDIR. Not in the
+            // retry set, so it propagates immediately.
+            Err(io::Error::new(
+                io::ErrorKind::IsADirectory,
+                format!(
+                    "Path is a directory: {} (pass RemoveOptions {{ recursive: true, .. }}; Node ERR_FS_EISDIR parity)",
+                    path.display()
+                ),
+            ))
+        }
+    } else {
+        fs::remove_file(path)
+    }
+}
+
+#[cfg(windows)]
+fn remove_symlink(path: &Path) -> io::Result<()> {
+    // Windows directory symlinks/junctions must be removed with remove_dir;
+    // file symlinks with remove_file. Try file-first, preserving the original
+    // error when both fail.
+    fs::remove_file(path).or_else(|file_error| fs::remove_dir(path).map_err(|_| file_error))
+}
+
+#[cfg(not(windows))]
+fn remove_symlink(path: &Path) -> io::Result<()> {
+    fs::remove_file(path)
+}
+
+/// Map an `io::Error` to a Node-style errno code string, covering the codes the
+/// removal loop cares about (`ENOENT` + [`RETRYABLE_REMOVE_CODES`]).
+///
+/// Raw OS codes are consulted first (they disambiguate `EPERM` vs `EACCES`,
+/// which both surface as `ErrorKind::PermissionDenied`), then stable
+/// `ErrorKind`s as a fallback. Windows raw-code mapping follows ARCHITECTURE.md
+/// §8.2: `ERROR_SHARING_VIOLATION`/`ERROR_LOCK_VIOLATION` → `EBUSY`,
+/// `ERROR_ACCESS_DENIED` → `EPERM`, `ERROR_DIR_NOT_EMPTY` → `ENOTEMPTY`.
+pub fn code_of(error: &io::Error) -> Option<&'static str> {
+    if let Some(raw) = error.raw_os_error()
+        && let Some(code) = raw_code(raw)
+    {
+        return Some(code);
+    }
+    match error.kind() {
+        io::ErrorKind::NotFound => Some("ENOENT"),
+        io::ErrorKind::PermissionDenied => {
+            Some(if cfg!(windows) { "EPERM" } else { "EACCES" })
+        }
+        io::ErrorKind::DirectoryNotEmpty => Some("ENOTEMPTY"),
+        io::ErrorKind::ResourceBusy => Some("EBUSY"),
+        _ => None,
+    }
+}
+
+#[cfg(windows)]
+fn raw_code(raw: i32) -> Option<&'static str> {
+    match raw {
+        2 | 3 => Some("ENOENT"),   // ERROR_FILE_NOT_FOUND / ERROR_PATH_NOT_FOUND
+        5 => Some("EPERM"),        // ERROR_ACCESS_DENIED (§8.2 mapping)
+        32 | 33 => Some("EBUSY"),  // ERROR_SHARING_VIOLATION / ERROR_LOCK_VIOLATION
+        145 => Some("ENOTEMPTY"),  // ERROR_DIR_NOT_EMPTY
+        _ => None,
+    }
+}
+
+#[cfg(any(target_os = "linux", target_os = "android"))]
+const ENOTEMPTY_RAW: i32 = 39;
+#[cfg(all(unix, not(any(target_os = "linux", target_os = "android"))))]
+const ENOTEMPTY_RAW: i32 = 66; // macOS / BSDs
+
+#[cfg(unix)]
+fn raw_code(raw: i32) -> Option<&'static str> {
+    match raw {
+        1 => Some("EPERM"),
+        2 => Some("ENOENT"),
+        13 => Some("EACCES"),
+        16 => Some("EBUSY"),
+        code if code == ENOTEMPTY_RAW => Some("ENOTEMPTY"),
+        _ => None,
+    }
+}
+
+#[cfg(not(any(unix, windows)))]
+fn raw_code(_raw: i32) -> Option<&'static str> {
+    None
+}
+
+fn is_not_found(error: &io::Error) -> bool {
+    matches!(code_of(error), Some("ENOENT"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn removes_nested_directory_tree() {
+        let dir = tempfile::tempdir().unwrap();
+        let root = dir.path().join("tree");
+        fs::create_dir_all(root.join("a").join("b")).unwrap();
+        fs::write(root.join("a").join("b").join("file.txt"), b"x").unwrap();
+        fs::write(root.join("top.txt"), b"y").unwrap();
+
+        remove_with_retry(&root, RemoveOptions::recursive_force()).unwrap();
+        assert!(!root.exists());
+    }
+
+    #[test]
+    fn missing_path_is_success() {
+        let dir = tempfile::tempdir().unwrap();
+        let missing = dir.path().join("does-not-exist");
+        remove_with_retry(&missing, RemoveOptions::recursive_force()).unwrap();
+        remove_with_retry(
+            &missing,
+            RemoveOptions {
+                recursive: false,
+                force: false,
+            },
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn removes_single_file_without_recursive() {
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("file.txt");
+        fs::write(&file, b"contents").unwrap();
+        remove_with_retry(
+            &file,
+            RemoveOptions {
+                recursive: false,
+                force: false,
+            },
+        )
+        .unwrap();
+        assert!(!file.exists());
+    }
+
+    #[test]
+    fn non_recursive_on_directory_errors_immediately() {
+        let dir = tempfile::tempdir().unwrap();
+        let sub = dir.path().join("sub");
+        fs::create_dir(&sub).unwrap();
+        let started = std::time::Instant::now();
+        let error = remove_with_retry(
+            &sub,
+            RemoveOptions {
+                recursive: false,
+                force: false,
+            },
+        )
+        .unwrap_err();
+        assert_eq!(error.kind(), io::ErrorKind::IsADirectory);
+        assert!(sub.exists());
+        // EISDIR is not retryable — must not have gone through backoff sleeps.
+        assert!(
+            started.elapsed() < Duration::from_millis(BASE_DELAY_MS),
+            "non-retryable errors must propagate without sleeping"
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn removes_symlink_not_its_target() {
+        let dir = tempfile::tempdir().unwrap();
+        let target = dir.path().join("target.txt");
+        fs::write(&target, b"kept").unwrap();
+        let link = dir.path().join("link.txt");
+        std::os::unix::fs::symlink(&target, &link).unwrap();
+
+        remove_with_retry(
+            &link,
+            RemoveOptions {
+                recursive: false,
+                force: true,
+            },
+        )
+        .unwrap();
+        assert!(!link.exists());
+        assert!(target.exists(), "symlink target must survive");
+    }
+
+    #[test]
+    fn code_of_maps_stable_error_kinds() {
+        assert_eq!(
+            code_of(&io::Error::from(io::ErrorKind::NotFound)),
+            Some("ENOENT")
+        );
+        assert_eq!(
+            code_of(&io::Error::from(io::ErrorKind::DirectoryNotEmpty)),
+            Some("ENOTEMPTY")
+        );
+        assert_eq!(
+            code_of(&io::Error::from(io::ErrorKind::ResourceBusy)),
+            Some("EBUSY")
+        );
+        let permission_expected = if cfg!(windows) { "EPERM" } else { "EACCES" };
+        assert_eq!(
+            code_of(&io::Error::from(io::ErrorKind::PermissionDenied)),
+            Some(permission_expected)
+        );
+        assert_eq!(code_of(&io::Error::from(io::ErrorKind::TimedOut)), None);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn code_of_maps_windows_raw_codes() {
+        assert_eq!(code_of(&io::Error::from_raw_os_error(2)), Some("ENOENT"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(3)), Some("ENOENT"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(5)), Some("EPERM"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(32)), Some("EBUSY"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(33)), Some("EBUSY"));
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(145)),
+            Some("ENOTEMPTY")
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn code_of_maps_unix_raw_codes() {
+        assert_eq!(code_of(&io::Error::from_raw_os_error(1)), Some("EPERM"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(2)), Some("ENOENT"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(13)), Some("EACCES"));
+        assert_eq!(code_of(&io::Error::from_raw_os_error(16)), Some("EBUSY"));
+        assert_eq!(
+            code_of(&io::Error::from_raw_os_error(ENOTEMPTY_RAW)),
+            Some("ENOTEMPTY")
+        );
+    }
+
+    /// The real Windows scenario: a file held open without share-delete access.
+    /// The helper must burn through all six attempts (25+50+100+200+400 ms of
+    /// backoff) before surfacing the retryable error, and succeed once the
+    /// handle is released.
+    #[cfg(windows)]
+    #[test]
+    fn retries_locked_file_then_errors_and_succeeds_after_release() {
+        use std::os::windows::fs::OpenOptionsExt;
+
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("locked.txt");
+        fs::write(&file, b"locked").unwrap();
+        let handle = fs::OpenOptions::new()
+            .read(true)
+            .share_mode(0) // deny all sharing, including FILE_SHARE_DELETE
+            .open(&file)
+            .unwrap();
+
+        let started = std::time::Instant::now();
+        let error = remove_with_retry(
+            &file,
+            RemoveOptions {
+                recursive: false,
+                force: true,
+            },
+        )
+        .unwrap_err();
+        let code = code_of(&error);
+        assert!(
+            matches!(code, Some("EBUSY") | Some("EPERM")),
+            "expected a retryable sharing/permission code, got {code:?} ({error})"
+        );
+        assert!(
+            started.elapsed() >= Duration::from_millis(700),
+            "expected the full backoff schedule (25+50+100+200+400 ms), took {:?}",
+            started.elapsed()
+        );
+
+        drop(handle);
+        remove_with_retry(
+            &file,
+            RemoveOptions {
+                recursive: false,
+                force: true,
+            },
+        )
+        .unwrap();
+        assert!(!file.exists());
+    }
+}
diff --git a/crates/testkit/src/sandbox.rs b/crates/testkit/src/sandbox.rs
new file mode 100644
index 000000000..4788f203b
--- /dev/null
+++ b/crates/testkit/src/sandbox.rs
@@ -0,0 +1,359 @@
+//! Environment sandbox for tests — Rust port of `test/helpers/global-sandbox.ts`
+//! (spec 14 §11, harness invariant 1 / tests-ci-01).
+//!
+//! Several subsystems resolve storage/config paths from `HOME` / `USERPROFILE` /
+//! `CODEX_HOME` / `CODEX_MULTI_AUTH_DIR`. A test that forgets to redirect them (or
+//! only deletes `CODEX_HOME` without pinning a home) can resolve to the developer's
+//! real `~/.codex` and read or clobber live account state. [`EnvSandbox`] pins all
+//! four to a fresh per-instance temp directory BEFORE the code under test runs, so
+//! the unsandboxed default is an empty throwaway dir rather than the real home.
+//!
+//! It also pins `CODEX_AUTH_PID_OFFSET_ENABLED=0`. The production default is `true`
+//! (verified by the plugin-config suite; it spreads parallel agents across accounts —
+//! #628), but the offset biases selection by the current process id, which is
+//! inherently non-deterministic inside a test process. Pinning it off keeps
+//! account-selection assertions deterministic; the offset's own behaviour is covered
+//! by the rotation suite, which passes the flag to the selector directly (spec 14
+//! gotcha 21).
+//!
+//! # `#[serial]` is MANDATORY
+//!
+//! **Every test that constructs an [`EnvSandbox`] (or otherwise mutates process
+//! environment variables) MUST be annotated `#[serial_test::serial(env)]`** — the
+//! shared key is [`ENV_SERIAL_KEY`]. Process environment is process-global state:
+//! two tests mutating it concurrently corrupt each other's view, and on some
+//! platforms concurrent mutation while non-std code reads the environment is
+//! undefined behavior. The vitest suite achieves the same isolation with
+//! `pool: 'forks'` + `fileParallelism: false` (one worker); `serial_test` is the
+//! Rust analogue (spec 14 §11 invariant 2, ARCHITECTURE.md §9.4).
+//!
+//! ```no_run
+//! use cma_testkit::sandbox::EnvSandbox;
+//!
+//! #[serial_test::serial(env)]
+//! fn my_env_test() {
+//!     let sandbox = EnvSandbox::new();
+//!     // HOME/USERPROFILE point at sandbox.root(); CODEX_HOME at
+//!     // sandbox.codex_home(); CODEX_MULTI_AUTH_DIR at
+//!     // sandbox.codex_multi_auth_dir(); CODEX_AUTH_PID_OFFSET_ENABLED=0.
+//!     // ... exercise code under test ...
+//!     drop(sandbox); // prior env values restored, temp dir removed
+//! }
+//! ```
+//!
+//! Like the TS global sandbox, this is intentionally a *baseline*: tests that need
+//! additional env vars should set them through [`EnvSandbox::set_var`] /
+//! [`EnvSandbox::remove_var`] so the original values are restored on drop — never
+//! by leaving stray process-global mutations behind.
+
+use std::env;
+use std::ffi::{OsStr, OsString};
+use std::path::{Path, PathBuf};
+
+use tempfile::TempDir;
+
+use crate::remove_with_retry::remove_recursive_with_retry;
+
+/// The `serial_test` key every env-mutating test must hold:
+/// `#[serial_test::serial(env)]` (ARCHITECTURE.md §9.4).
+///
+/// The macro takes the key as a bare identifier; this constant exists so the
+/// convention is greppable and documented in one place.
+pub const ENV_SERIAL_KEY: &str = "env";
+
+/// Temp-dir prefix, matching the TS sandbox (`mkdtempSync(join(tmpdir(), "cma-test-home-"))`).
+pub const SANDBOX_PREFIX: &str = "cma-test-home-";
+
+/// The environment variables [`EnvSandbox::new`] pins, in the order they are set.
+/// Mirrors `test/helpers/global-sandbox.ts` exactly.
+pub const PINNED_ENV_KEYS: [&str; 5] = [
+    "HOME",
+    "USERPROFILE",
+    "CODEX_HOME",
+    "CODEX_MULTI_AUTH_DIR",
+    "CODEX_AUTH_PID_OFFSET_ENABLED",
+];
+
+/// Guard struct that pins the home/codex env vars to a fresh temp directory and
+/// restores every mutated variable to its prior value (set or unset) on drop.
+///
+/// Layout inside the sandbox root (identical to the TS sandbox):
+///
+/// | variable                         | value                        |
+/// |----------------------------------|------------------------------|
+/// | `HOME`                           | `<root>`                     |
+/// | `USERPROFILE`                    | `<root>`                     |
+/// | `CODEX_HOME`                     | `<root>/.codex`              |
+/// | `CODEX_MULTI_AUTH_DIR`           | `<root>/.codex/multi-auth`   |
+/// | `CODEX_AUTH_PID_OFFSET_ENABLED`  | `"0"`                        |
+///
+/// The `.codex` subdirectories are NOT created eagerly — application code creates
+/// them lazily, exactly as it would against a pristine real home (TS parity).
+///
+/// Nesting is supported: an inner sandbox captures the outer sandbox's values and
+/// restores them when dropped. Restoration also runs during unwinding, so a failed
+/// assertion cannot leak sandbox paths into the next `#[serial(env)]` test.
+///
+/// See the module docs: any test using this type must be `#[serial_test::serial(env)]`.
+#[derive(Debug)]
+pub struct EnvSandbox {
+    root: PathBuf,
+    temp: Option<TempDir>,
+    /// Original values, captured once per key on first mutation (first-capture wins,
+    /// so repeated `set_var` calls still restore the true pre-sandbox value).
+    saved: Vec<(OsString, Option<OsString>)>,
+}
+
+impl EnvSandbox {
+    /// Create the sandbox: makes a fresh `cma-test-home-*` temp dir and pins the
+    /// five [`PINNED_ENV_KEYS`] into it.
+    ///
+    /// # Panics
+    /// Panics if the temp directory cannot be created (tests cannot proceed
+    /// meaningfully without an isolated home).
+    pub fn new() -> Self {
+        let temp = tempfile::Builder::new()
+            .prefix(SANDBOX_PREFIX)
+            .tempdir()
+            .expect("EnvSandbox: failed to create sandbox temp dir");
+        let root = temp.path().to_path_buf();
+        let mut sandbox = EnvSandbox {
+            root: root.clone(),
+            temp: Some(temp),
+            saved: Vec::new(),
+        };
+        let codex_home = root.join(".codex");
+        let multi_auth_dir = codex_home.join("multi-auth");
+        // Pin home + codex roots to the sandbox. Every in-repo resolver consults
+        // these env vars before falling back to the OS home directory.
+        sandbox.set_var("HOME", &root);
+        sandbox.set_var("USERPROFILE", &root);
+        sandbox.set_var("CODEX_HOME", &codex_home);
+        sandbox.set_var("CODEX_MULTI_AUTH_DIR", &multi_auth_dir);
+        // Deterministic account selection in tests (production default is true).
+        sandbox.set_var("CODEX_AUTH_PID_OFFSET_ENABLED", "0");
+        sandbox
+    }
+
+    /// The sandbox root directory (`HOME` / `USERPROFILE` point here).
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// `<root>/.codex` — the value pinned into `CODEX_HOME`.
+    pub fn codex_home(&self) -> PathBuf {
+        self.root.join(".codex")
+    }
+
+    /// `<root>/.codex/multi-auth` — the value pinned into `CODEX_MULTI_AUTH_DIR`.
+    pub fn codex_multi_auth_dir(&self) -> PathBuf {
+        self.codex_home().join("multi-auth")
+    }
+
+    /// Set an environment variable for the lifetime of the sandbox, restoring the
+    /// prior value (or unset state) on drop. The original value is captured only
+    /// on the FIRST mutation of a given key.
+    ///
+    /// Caller contract: the test holding this sandbox is `#[serial(env)]`.
+    pub fn set_var(&mut self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>) {
+        let key = key.as_ref();
+        self.capture(key);
+        env_set(key, value.as_ref());
+    }
+
+    /// Remove an environment variable for the lifetime of the sandbox, restoring
+    /// the prior value (or unset state) on drop.
+    ///
+    /// Caller contract: the test holding this sandbox is `#[serial(env)]`.
+    pub fn remove_var(&mut self, key: impl AsRef<OsStr>) {
+        let key = key.as_ref();
+        self.capture(key);
+        env_remove(key);
+    }
+
+    fn capture(&mut self, key: &OsStr) {
+        if self.saved.iter().any(|(saved_key, _)| saved_key == key) {
+            return;
+        }
+        self.saved.push((key.to_os_string(), env::var_os(key)));
+    }
+}
+
+impl Default for EnvSandbox {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Drop for EnvSandbox {
+    fn drop(&mut self) {
+        // Restore env first (reverse order, stack discipline), THEN remove the
+        // temp dir, so nothing observes sandbox paths after their backing dir is
+        // gone.
+        for (key, original) in self.saved.drain(..).rev() {
+            match original {
+                Some(value) => env_set(&key, &value),
+                None => env_remove(&key),
+            }
+        }
+        if let Some(temp) = self.temp.take() {
+            let path = temp.path().to_path_buf();
+            // TempDir's own Drop is a best-effort single attempt; follow up with
+            // the Windows-safe retry helper for EBUSY/EPERM stragglers
+            // (spec 14 §11 harness invariant 3: never bare rm on Windows).
+            drop(temp);
+            if path.exists() {
+                let _ = remove_recursive_with_retry(&path);
+            }
+        }
+    }
+}
+
+/// Set a process environment variable.
+///
+/// In edition 2024 `std::env::set_var` is an `unsafe fn` because mutating the
+/// process environment races with any other thread reading it through non-std
+/// (e.g. libc) APIs. This crate's safety contract makes the call sound in
+/// practice: env mutation only ever happens under the process-wide
+/// `#[serial(env)]` test key ([`ENV_SERIAL_KEY`]), std's own env accessors are
+/// internally synchronized, and no test code hands the environment to foreign
+/// readers while a sandbox is live. This is the narrowest possible carve-out
+/// from the workspace `unsafe_code = "deny"` lint; there is no safe std API for
+/// env mutation.
+#[allow(unsafe_code)]
+fn env_set(key: &OsStr, value: &OsStr) {
+    // SAFETY: see function docs — callers hold the `#[serial(env)]` key, so no
+    // other test thread is concurrently mutating or foreign-reading the env.
+    unsafe { env::set_var(key, value) }
+}
+
+/// Remove a process environment variable. Same safety contract as [`env_set`].
+#[allow(unsafe_code)]
+fn env_remove(key: &OsStr) {
+    // SAFETY: see `env_set` — callers hold the `#[serial(env)]` key.
+    unsafe { env::remove_var(key) }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    #[test]
+    #[serial(env)]
+    fn pins_env_to_tempdir_and_restores_on_drop() {
+        let before: Vec<(String, Option<OsString>)> = PINNED_ENV_KEYS
+            .iter()
+            .map(|key| ((*key).to_string(), env::var_os(key)))
+            .collect();
+
+        let root;
+        {
+            let sandbox = EnvSandbox::new();
+            root = sandbox.root().to_path_buf();
+            assert!(root.exists());
+            assert!(
+                root.file_name()
+                    .and_then(|name| name.to_str())
+                    .is_some_and(|name| name.starts_with(SANDBOX_PREFIX)),
+                "sandbox root should carry the {SANDBOX_PREFIX:?} prefix: {}",
+                root.display()
+            );
+
+            assert_eq!(env::var_os("HOME"), Some(root.clone().into_os_string()));
+            assert_eq!(
+                env::var_os("USERPROFILE"),
+                Some(root.clone().into_os_string())
+            );
+            assert_eq!(
+                env::var_os("CODEX_HOME"),
+                Some(sandbox.codex_home().into_os_string())
+            );
+            assert_eq!(
+                env::var_os("CODEX_MULTI_AUTH_DIR"),
+                Some(sandbox.codex_multi_auth_dir().into_os_string())
+            );
+            assert_eq!(
+                env::var_os("CODEX_AUTH_PID_OFFSET_ENABLED"),
+                Some(OsString::from("0"))
+            );
+            assert_eq!(sandbox.codex_home(), root.join(".codex"));
+            assert_eq!(
+                sandbox.codex_multi_auth_dir(),
+                root.join(".codex").join("multi-auth")
+            );
+            // TS parity: the sandbox does NOT eagerly create the codex dirs.
+            assert!(!sandbox.codex_home().exists());
+        }
+
+        for (key, value) in before {
+            assert_eq!(env::var_os(&key), value, "{key} was not restored");
+        }
+        assert!(!root.exists(), "sandbox temp dir should be removed on drop");
+    }
+
+    #[test]
+    #[serial(env)]
+    fn nested_sandboxes_restore_to_outer_values() {
+        let outer = EnvSandbox::new();
+        let outer_home = env::var_os("HOME");
+        let outer_mad = env::var_os("CODEX_MULTI_AUTH_DIR");
+        {
+            let inner = EnvSandbox::new();
+            assert_ne!(env::var_os("HOME"), outer_home);
+            assert_ne!(env::var_os("CODEX_MULTI_AUTH_DIR"), outer_mad);
+            let _ = inner.root();
+        }
+        assert_eq!(env::var_os("HOME"), outer_home);
+        assert_eq!(env::var_os("CODEX_MULTI_AUTH_DIR"), outer_mad);
+        drop(outer);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn set_var_and_remove_var_capture_once_and_restore() {
+        const KEY: &str = "CMA_TESTKIT_SANDBOX_CUSTOM_VAR";
+        let mut outer = EnvSandbox::new();
+        outer.set_var(KEY, "outer-value");
+
+        {
+            let mut inner = EnvSandbox::new();
+            inner.set_var(KEY, "first");
+            inner.set_var(KEY, "second");
+            assert_eq!(env::var_os(KEY), Some(OsString::from("second")));
+            inner.remove_var(KEY);
+            assert_eq!(env::var_os(KEY), None);
+        }
+        // Inner restores to the OUTER value captured at its first mutation.
+        assert_eq!(env::var_os(KEY), Some(OsString::from("outer-value")));
+
+        {
+            let mut inner = EnvSandbox::new();
+            inner.remove_var(KEY);
+            assert_eq!(env::var_os(KEY), None);
+        }
+        assert_eq!(env::var_os(KEY), Some(OsString::from("outer-value")));
+
+        drop(outer);
+        // The outer sandbox captured the true original (unset) and restores it.
+        assert_eq!(env::var_os(KEY), None);
+    }
+
+    #[test]
+    #[serial(env)]
+    fn restore_runs_even_when_values_were_previously_unset() {
+        const KEY: &str = "CMA_TESTKIT_SANDBOX_UNSET_PROBE";
+        let mut outer = EnvSandbox::new();
+        outer.remove_var(KEY); // guarantee unset without direct env mutation
+        {
+            let mut inner = EnvSandbox::new();
+            inner.set_var(KEY, "transient");
+            assert_eq!(env::var_os(KEY), Some(OsString::from("transient")));
+        }
+        assert_eq!(
+            env::var_os(KEY),
+            None,
+            "a previously-unset var must be UNSET again after drop, not empty"
+        );
+    }
+}
diff --git a/crates/tui/Cargo.toml b/crates/tui/Cargo.toml
new file mode 100644
index 000000000..dd26a605a
--- /dev/null
+++ b/crates/tui/Cargo.toml
@@ -0,0 +1,30 @@
+[package]
+name = "cma-tui"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+crossterm.workspace = true
+tokio.workspace = true
+serde_json.workspace = true
+unicode-segmentation.workspace = true
+chrono.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+# Menu-lifetime SIGINT/SIGTERM protection (TS process.once(signal, finish))
+# — already in-tree transitively via crossterm's unix event source.
+signal-hook = "0.3"
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/tui/src/ansi.rs b/crates/tui/src/ansi.rs
new file mode 100644
index 000000000..909520b3e
--- /dev/null
+++ b/crates/tui/src/ansi.rs
@@ -0,0 +1,153 @@
+//! Port of `lib/ui/ansi.ts` — ANSI escape helpers and keyboard parsing for
+//! interactive TUI menus.
+//!
+//! The escape constants are byte-exact copies of the TS `ANSI` map; `parse_key`
+//! matches **exact whole-byte-sequences** (spec 12 §1). Note the deliberate TS
+//! behaviors preserved here:
+//! - Ctrl-C (`\x03`) maps to `Escape`, NOT a signal (raw mode swallows SIGINT).
+//! - a lone ESC byte maps to `EscapeStart`; the caller disambiguates with the
+//!   50 ms timer in `select.rs`.
+
+use std::io::IsTerminal;
+
+// Cursor control
+pub const HIDE: &str = "\x1b[?25l";
+pub const SHOW: &str = "\x1b[?25h";
+pub const ALT_SCREEN_ON: &str = "\x1b[?1049h";
+pub const ALT_SCREEN_OFF: &str = "\x1b[?1049l";
+pub const CLEAR_LINE: &str = "\x1b[2K";
+pub const CLEAR_SCREEN: &str = "\x1b[2J";
+
+/// `ANSI.up(lines = 1)` => `\x1b[{lines}A`.
+pub fn up(lines: usize) -> String {
+    format!("\x1b[{lines}A")
+}
+
+/// `ANSI.moveTo(row, col)` => `\x1b[{row};{col}H`.
+pub fn move_to(row: usize, col: usize) -> String {
+    format!("\x1b[{row};{col}H")
+}
+
+// Styling
+pub const BLACK: &str = "\x1b[30m";
+pub const WHITE: &str = "\x1b[97m";
+pub const CYAN: &str = "\x1b[36m";
+pub const GREEN: &str = "\x1b[32m";
+pub const RED: &str = "\x1b[31m";
+pub const YELLOW: &str = "\x1b[33m";
+pub const BG_BLUE: &str = "\x1b[44m";
+pub const BG_BRIGHT_BLUE: &str = "\x1b[104m";
+pub const BG_GREEN: &str = "\x1b[42m";
+pub const BG_YELLOW: &str = "\x1b[43m";
+pub const BG_RED: &str = "\x1b[41m";
+pub const INVERSE: &str = "\x1b[7m";
+pub const DIM: &str = "\x1b[2m";
+pub const BOLD: &str = "\x1b[1m";
+pub const RESET: &str = "\x1b[0m";
+
+/// Normalized keyboard action token (TS `KeyAction`, minus the `null` arm which
+/// becomes `None` on the Rust side).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum KeyAction {
+    Up,
+    Down,
+    Home,
+    End,
+    Enter,
+    Escape,
+    EscapeStart,
+}
+
+/// Maps a raw stdin byte buffer to a normalized keyboard action token.
+///
+/// Interprets common ANSI/terminal key sequences via **exact whole-string**
+/// matches, mirroring `parseKey` from `lib/ui/ansi.ts` byte for byte.
+pub fn parse_key(data: &[u8]) -> Option<KeyAction> {
+    let input = String::from_utf8_lossy(data);
+    let input = input.as_ref();
+
+    if input == "\x1b[A" || input == "\x1bOA" {
+        return Some(KeyAction::Up);
+    }
+    if input == "\x1b[B" || input == "\x1bOB" {
+        return Some(KeyAction::Down);
+    }
+    if input == "\x1b[H" || input == "\x1bOH" || input == "\x1b[1~" || input == "\x1b[7~" {
+        return Some(KeyAction::Home);
+    }
+    if input == "\x1b[F" || input == "\x1bOF" || input == "\x1b[4~" || input == "\x1b[8~" {
+        return Some(KeyAction::End);
+    }
+    if input == "\r" || input == "\n" {
+        return Some(KeyAction::Enter);
+    }
+    // Ctrl-C maps to "escape", NOT SIGINT (raw mode delivers it as a byte).
+    if input == "\x03" {
+        return Some(KeyAction::Escape);
+    }
+    // A bare ESC byte may be the start of a longer sequence arriving split.
+    if input == "\x1b" {
+        return Some(KeyAction::EscapeStart);
+    }
+
+    None
+}
+
+/// `isTTY()` — BOTH stdin and stdout must be TTYs.
+pub fn is_tty() -> bool {
+    std::io::stdin().is_terminal() && std::io::stdout().is_terminal()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_key_maps_arrow_and_keypad_variants() {
+        assert_eq!(parse_key(b"\x1b[A"), Some(KeyAction::Up));
+        assert_eq!(parse_key(b"\x1bOA"), Some(KeyAction::Up));
+        assert_eq!(parse_key(b"\x1b[B"), Some(KeyAction::Down));
+        assert_eq!(parse_key(b"\x1bOB"), Some(KeyAction::Down));
+    }
+
+    #[test]
+    fn parse_key_maps_home_and_end_variants() {
+        for seq in [b"\x1b[H".as_ref(), b"\x1bOH", b"\x1b[1~", b"\x1b[7~"] {
+            assert_eq!(parse_key(seq), Some(KeyAction::Home));
+        }
+        for seq in [b"\x1b[F".as_ref(), b"\x1bOF", b"\x1b[4~", b"\x1b[8~"] {
+            assert_eq!(parse_key(seq), Some(KeyAction::End));
+        }
+    }
+
+    #[test]
+    fn parse_key_maps_enter_escape_and_escape_start() {
+        assert_eq!(parse_key(b"\r"), Some(KeyAction::Enter));
+        assert_eq!(parse_key(b"\n"), Some(KeyAction::Enter));
+        // Ctrl-C is "escape", not a signal.
+        assert_eq!(parse_key(b"\x03"), Some(KeyAction::Escape));
+        // Lone ESC is escape-start (50 ms disambiguation upstream).
+        assert_eq!(parse_key(b"\x1b"), Some(KeyAction::EscapeStart));
+    }
+
+    #[test]
+    fn parse_key_returns_none_for_unknown_input() {
+        assert_eq!(parse_key(b"a"), None);
+        assert_eq!(parse_key(b"\x1b[C"), None);
+        assert_eq!(parse_key(b""), None);
+        // Partial-prefix sequences are NOT whole-string matches.
+        assert_eq!(parse_key(b"\x1b[Ax"), None);
+    }
+
+    #[test]
+    fn escape_constants_are_exact() {
+        assert_eq!(HIDE, "\u{1b}[?25l");
+        assert_eq!(SHOW, "\u{1b}[?25h");
+        assert_eq!(up(3), "\u{1b}[3A");
+        assert_eq!(move_to(1, 1), "\u{1b}[1;1H");
+        assert_eq!(CLEAR_LINE, "\u{1b}[2K");
+        assert_eq!(CLEAR_SCREEN, "\u{1b}[2J");
+        assert_eq!(BG_BRIGHT_BLUE, "\u{1b}[104m");
+        assert_eq!(RESET, "\u{1b}[0m");
+    }
+}
diff --git a/crates/tui/src/auth_menu.rs b/crates/tui/src/auth_menu.rs
new file mode 100644
index 000000000..51cf25912
--- /dev/null
+++ b/crates/tui/src/auth_menu.rs
@@ -0,0 +1,615 @@
+//! Port of `lib/ui/auth-menu.ts` — the stateful accounts dashboard and the
+//! per-account details menu (search mode, 1-9 quick switch, confirms).
+//!
+//! Contracts preserved (spec 12 §10 + gotchas):
+//! - duplicate quick-switch numbers: the FIRST account keeps the map slot AND
+//!   the digit is fully disabled (pressing it does nothing);
+//! - the dashboard re-renders its subtitle every 200 ms via `dynamicSubtitle`
+//!   (`status_message` may be a closure returning fresh text);
+//! - `?` toggles the detailed-help flag (visible on the next `select` run —
+//!   the help text is captured per iteration, bug-compatible with TS);
+//! - refused confirms loop instead of returning;
+//! - focus is restored across loop iterations via `auth_menu_focus_key`.
+//!
+//! The item-list builder is exported as a pure function
+//! ([`build_auth_menu_items`]) so tests can assert the exact menu structure
+//! without a TTY.
+
+use std::cell::{Cell, RefCell};
+use std::collections::{HashMap, HashSet};
+use std::io::{BufRead, IsTerminal, Write};
+
+pub use crate::ansi::is_tty;
+use crate::ansi;
+use crate::auth_menu_builder::{
+    account_row_color, account_search_text, account_title, auth_menu_focus_key,
+    current_marker_label, format_account_hint, format_date, format_relative_time,
+    main_menu_title_with_version, status_badge, AccountAction, AccountCurrentMarker, AccountInfo,
+    AuthMenuAction, AuthMenuOptions,
+};
+use crate::confirm::confirm;
+use crate::format::{format_ui_badge, paint_ui_text, UiBadgeTone, UiTextTone};
+use crate::runtime_options::{get_ui_runtime_options, UiRuntimeOptions};
+use crate::select::{
+    select, FocusStyle, MenuItem, SelectError, SelectInputResult, SelectOptions,
+};
+use crate::ui_copy;
+
+/// Readline search prompt: non-TTY returns the current query unchanged;
+/// otherwise `Search[ (current)] (blank clears): `, trimmed + lowercased.
+fn prompt_search_query(current: &str) -> String {
+    if !std::io::stdin().is_terminal() || !std::io::stdout().is_terminal() {
+        return current.to_string();
+    }
+    let suffix = if current.is_empty() {
+        String::new()
+    } else {
+        format!(" ({current})")
+    };
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "Search{suffix} (blank clears): ");
+    let _ = stdout.flush();
+    let mut answer = String::new();
+    let _ = std::io::stdin().lock().read_line(&mut answer);
+    answer.trim().to_lowercase()
+}
+
+/// Pure builder for the dashboard menu structure (headings, quick actions,
+/// account rows, danger zone). Exactly mirrors the TS item list.
+pub fn build_auth_menu_items(
+    visible_accounts: &[AccountInfo],
+    verify_label: &str,
+    flagged_count: i64,
+    ui: &UiRuntimeOptions,
+) -> Vec<MenuItem<AuthMenuAction>> {
+    let mut items: Vec<MenuItem<AuthMenuAction>> = vec![
+        MenuItem::heading(ui_copy::main_menu::QUICK_START, AuthMenuAction::Cancel),
+        MenuItem::new(ui_copy::main_menu::ADD_ACCOUNT, AuthMenuAction::Add)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::new(ui_copy::main_menu::CHECK_ACCOUNTS, AuthMenuAction::Check)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::new(ui_copy::main_menu::BEST_ACCOUNT, AuthMenuAction::Forecast)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::new(ui_copy::main_menu::FIX_ISSUES, AuthMenuAction::Fix)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::new(ui_copy::main_menu::SETTINGS, AuthMenuAction::Settings)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::separator(AuthMenuAction::Cancel),
+        MenuItem::heading(ui_copy::main_menu::MORE_CHECKS, AuthMenuAction::Cancel),
+        MenuItem::new(ui_copy::main_menu::REFRESH_CHECKS, AuthMenuAction::DeepCheck)
+            .with_color(crate::select::MenuColor::Green),
+        MenuItem::new(verify_label, AuthMenuAction::VerifyFlagged).with_color(
+            if flagged_count > 0 {
+                crate::select::MenuColor::Red
+            } else {
+                crate::select::MenuColor::Yellow
+            },
+        ),
+        MenuItem::separator(AuthMenuAction::Cancel),
+        MenuItem::heading(ui_copy::main_menu::ACCOUNTS, AuthMenuAction::Cancel),
+    ];
+
+    if visible_accounts.is_empty() {
+        let mut row = MenuItem::new(ui_copy::main_menu::NO_SEARCH_MATCHES, AuthMenuAction::Cancel);
+        row.disabled = true;
+        items.push(row);
+    } else {
+        for account in visible_accounts {
+            let current_markers: Vec<AccountCurrentMarker> = account
+                .current_markers
+                .clone()
+                .unwrap_or_else(|| {
+                    if account.is_current_account == Some(true) {
+                        vec![AccountCurrentMarker::Current]
+                    } else {
+                        Vec::new()
+                    }
+                });
+            let current_badge = if account.show_current_badge != Some(false) {
+                current_markers
+                    .iter()
+                    .map(|&marker| {
+                        if ui.v2_enabled {
+                            format!(
+                                " {}",
+                                format_ui_badge(
+                                    ui,
+                                    current_marker_label(marker),
+                                    if marker == AccountCurrentMarker::Current {
+                                        UiBadgeTone::Accent
+                                    } else {
+                                        UiBadgeTone::Muted
+                                    }
+                                )
+                            )
+                        } else {
+                            format!(
+                                " {}[{}]{}",
+                                ansi::CYAN,
+                                current_marker_label(marker),
+                                ansi::RESET
+                            )
+                        }
+                    })
+                    .collect::<String>()
+            } else {
+                String::new()
+            };
+            let badge = if account.show_status_badge == Some(false) {
+                String::new()
+            } else {
+                status_badge(account.status)
+            };
+            let status_suffix = if badge.is_empty() {
+                String::new()
+            } else {
+                format!(" {badge}")
+            };
+            let title = if ui.v2_enabled {
+                paint_ui_text(
+                    ui,
+                    &account_title(account),
+                    if account.is_current_account == Some(true) {
+                        UiTextTone::Accent
+                    } else {
+                        UiTextTone::Heading
+                    },
+                )
+            } else {
+                account_title(account)
+            };
+            let label = format!("{title}{current_badge}{status_suffix}");
+            let hint = format_account_hint(account, ui);
+            let mut row = MenuItem::new(label, AuthMenuAction::SelectAccount(account.clone()));
+            if !hint.is_empty() {
+                row.hint = Some(hint);
+            }
+            row.color = Some(account_row_color(account));
+            items.push(row);
+        }
+    }
+
+    items.push(MenuItem::separator(AuthMenuAction::Cancel));
+    items.push(MenuItem::heading(
+        ui_copy::main_menu::DANGER_ZONE,
+        AuthMenuAction::Cancel,
+    ));
+    items.push(
+        MenuItem::new(
+            ui_copy::main_menu::REMOVE_ALL_ACCOUNTS,
+            AuthMenuAction::DeleteAll,
+        )
+        .with_color(crate::select::MenuColor::Red),
+    );
+    items
+}
+
+/// Show the accounts dashboard and return the chosen action. Loops internally
+/// on search / refused confirms, exactly like the TS.
+// focus-key bookkeeping mirrors the TS assignment order (set before every
+// return/continue), which trips the dead-store lint on the final assignment.
+#[allow(unused_assignments)]
+pub fn show_auth_menu(
+    accounts: &[AccountInfo],
+    options: &AuthMenuOptions<'_>,
+) -> Result<AuthMenuAction, SelectError> {
+    let flagged_count = options.flagged_count.unwrap_or(0);
+    let verify_label = ui_copy::format_check_flagged_label(flagged_count);
+    let ui = get_ui_runtime_options();
+    let show_detailed_help = Cell::new(false);
+    let mut search_query = String::new();
+    let mut focus_key = "action:add".to_string();
+
+    loop {
+        let normalized_search = search_query.trim().to_lowercase();
+        let visible_accounts: Vec<AccountInfo> = if normalized_search.is_empty() {
+            accounts.to_vec()
+        } else {
+            accounts
+                .iter()
+                .filter(|account| account_search_text(account).contains(&normalized_search))
+                .cloned()
+                .collect()
+        };
+        let mut visible_by_number: HashMap<i64, AccountInfo> = HashMap::new();
+        let mut duplicate_quick_switch_numbers: HashSet<i64> = HashSet::new();
+        for account in &visible_accounts {
+            let quick_switch_number = account.quick_switch_number.unwrap_or(account.index + 1);
+            if visible_by_number.contains_key(&quick_switch_number) {
+                duplicate_quick_switch_numbers.insert(quick_switch_number);
+                continue;
+            }
+            visible_by_number.insert(quick_switch_number, account.clone());
+        }
+
+        let items = build_auth_menu_items(&visible_accounts, &verify_label, flagged_count, &ui);
+
+        let show_hints_for_unselected_rows = visible_accounts
+            .first()
+            .and_then(|a| a.show_hints_for_unselected_rows)
+            .or_else(|| accounts.first().and_then(|a| a.show_hints_for_unselected_rows))
+            .unwrap_or(false);
+        let focus_style = visible_accounts
+            .first()
+            .and_then(|a| a.focus_style)
+            .or_else(|| accounts.first().and_then(|a| a.focus_style))
+            .unwrap_or(FocusStyle::RowInvert);
+        let resolve_status_message = || -> Option<String> {
+            let raw = options.status_message.as_ref()?.resolve()?;
+            let trimmed = raw.trim();
+            if trimmed.is_empty() {
+                None
+            } else {
+                Some(trimmed.to_string())
+            }
+        };
+        let normalized_search_for_subtitle = normalized_search.clone();
+        let build_subtitle = move || -> Option<String> {
+            let mut parts: Vec<String> = Vec::new();
+            if !normalized_search_for_subtitle.is_empty() {
+                parts.push(format!(
+                    "{} {}",
+                    ui_copy::main_menu::SEARCH_SUBTITLE_PREFIX,
+                    normalized_search_for_subtitle
+                ));
+            }
+            if let Some(status_text) = resolve_status_message() {
+                parts.push(status_text);
+            }
+            if parts.is_empty() {
+                None
+            } else {
+                Some(parts.join(" | "))
+            }
+        };
+        let initial_cursor = items.iter().position(|item| {
+            if item.separator || item.disabled || item.heading {
+                return false;
+            }
+            auth_menu_focus_key(&item.value) == focus_key
+        });
+
+        let focus_key_cell: RefCell<Option<String>> = RefCell::new(None);
+
+        let mut select_options = SelectOptions::new(main_menu_title_with_version());
+        select_options.subtitle = build_subtitle();
+        select_options.dynamic_subtitle = Some(Box::new(build_subtitle.clone()));
+        select_options.help = Some(if show_detailed_help.get() {
+            ui_copy::main_menu::HELP_DETAILED.to_string()
+        } else {
+            ui_copy::main_menu::HELP_COMPACT.to_string()
+        });
+        select_options.clear_screen = true;
+        select_options.selected_emphasis = Some(crate::select::SelectedEmphasis::Minimal);
+        select_options.focus_style = Some(focus_style);
+        select_options.show_hints_for_unselected = Some(show_hints_for_unselected_rows);
+        select_options.refresh_interval_ms = Some(200.0);
+        select_options.initial_cursor = initial_cursor.map(|i| i as i64);
+        select_options.theme = Some(ui.theme.clone());
+        select_options.on_input = Some(Box::new(|input, context| {
+            let lower = input.to_lowercase();
+            if lower == "?" {
+                show_detailed_help.set(!show_detailed_help.get());
+                context.request_rerender();
+                return SelectInputResult::Ignored;
+            }
+            if lower == "q" {
+                return SelectInputResult::Finish(Some(AuthMenuAction::Cancel));
+            }
+            if lower == "/" {
+                return SelectInputResult::Finish(Some(AuthMenuAction::Search));
+            }
+            if let Some(parsed) = crate::auth_menu_builder::parse_int_prefix(input)
+                && (1..=9).contains(&parsed) {
+                    if duplicate_quick_switch_numbers.contains(&parsed) {
+                        return SelectInputResult::Ignored;
+                    }
+                    if let Some(direct) = visible_by_number.get(&parsed) {
+                        return SelectInputResult::Finish(Some(AuthMenuAction::SetCurrentAccount(
+                            direct.clone(),
+                        )));
+                    }
+                }
+            SelectInputResult::Ignored
+        }));
+        select_options.on_cursor_change = Some(Box::new(|context| {
+            let selected = &context.items[context.cursor];
+            if selected.separator || selected.disabled || selected.heading {
+                return;
+            }
+            *focus_key_cell.borrow_mut() = Some(auth_menu_focus_key(&selected.value));
+        }));
+
+        let result = select(&items, select_options)?;
+        if let Some(tracked) = focus_key_cell.borrow_mut().take() {
+            focus_key = tracked;
+        }
+
+        let result = match result {
+            None => return Ok(AuthMenuAction::Cancel),
+            Some(result) => result,
+        };
+        match &result {
+            AuthMenuAction::Search => {
+                search_query = prompt_search_query(&search_query);
+                focus_key = "action:search".to_string();
+                continue;
+            }
+            AuthMenuAction::DeleteAll => {
+                let confirmed = confirm("Delete all accounts?", false)?;
+                if !confirmed {
+                    continue;
+                }
+            }
+            AuthMenuAction::DeleteAccount(account) => {
+                let confirmed = confirm(&format!("Delete {}?", account_title(account)), false)?;
+                if !confirmed {
+                    continue;
+                }
+            }
+            AuthMenuAction::RefreshAccount(account) => {
+                let confirmed = confirm(
+                    &format!("Re-authenticate {}?", account_title(account)),
+                    false,
+                )?;
+                if !confirmed {
+                    continue;
+                }
+            }
+            _ => {}
+        }
+        focus_key = auth_menu_focus_key(&result);
+        return Ok(result);
+    }
+}
+
+/// Show the per-account details menu and return the chosen action.
+// focus-action bookkeeping mirrors the TS assignment order; see show_auth_menu.
+#[allow(unused_assignments)]
+pub fn show_account_details(account: &AccountInfo) -> Result<AccountAction, SelectError> {
+    let ui = get_ui_runtime_options();
+    let disabled_suffix = if account.enabled == Some(false) {
+        if ui.v2_enabled {
+            format!(" {}", format_ui_badge(&ui, "disabled", UiBadgeTone::Danger))
+        } else {
+            format!(" {}[disabled]{}", ansi::RED, ansi::RESET)
+        }
+    } else {
+        String::new()
+    };
+    let header = format!(
+        "{} {}{disabled_suffix}",
+        account_title(account),
+        status_badge(account.status)
+    );
+    let status_label = account
+        .status
+        .map(crate::auth_menu_builder::AccountStatus::as_str)
+        .unwrap_or("unknown");
+    let subtitle = format!(
+        "Added: {} | Used: {} | Status: {status_label}",
+        format_date(account.added_at),
+        format_relative_time(account.last_used)
+    );
+    let mut focus_action = AccountAction::Back;
+
+    loop {
+        let items: Vec<MenuItem<AccountAction>> = vec![
+            MenuItem::new(ui_copy::account_details::BACK, AccountAction::Back),
+            MenuItem::new(
+                if account.enabled == Some(false) {
+                    ui_copy::account_details::ENABLE
+                } else {
+                    ui_copy::account_details::DISABLE
+                },
+                AccountAction::Toggle,
+            )
+            .with_color(if account.enabled == Some(false) {
+                crate::select::MenuColor::Green
+            } else {
+                crate::select::MenuColor::Yellow
+            }),
+            MenuItem::new(ui_copy::account_details::SET_CURRENT, AccountAction::SetCurrent)
+                .with_color(crate::select::MenuColor::Green),
+            MenuItem::new(ui_copy::account_details::REFRESH, AccountAction::Refresh)
+                .with_color(crate::select::MenuColor::Green),
+            MenuItem::new(ui_copy::account_details::REMOVE, AccountAction::Delete)
+                .with_color(crate::select::MenuColor::Red),
+        ];
+        let initial_cursor = items.iter().position(|item| item.value == focus_action);
+
+        let focus_cell: RefCell<Option<AccountAction>> = RefCell::new(None);
+        let mut select_options = SelectOptions::new(header.clone());
+        select_options.subtitle = Some(subtitle.clone());
+        select_options.help = Some(ui_copy::account_details::HELP.to_string());
+        select_options.clear_screen = true;
+        select_options.selected_emphasis = Some(crate::select::SelectedEmphasis::Minimal);
+        select_options.focus_style = Some(account.focus_style.unwrap_or(FocusStyle::RowInvert));
+        select_options.initial_cursor = initial_cursor.map(|i| i as i64);
+        select_options.theme = Some(ui.theme.clone());
+        select_options.on_input = Some(Box::new(|input, _context| {
+            let lower = input.to_lowercase();
+            match lower.as_str() {
+                "q" => SelectInputResult::Finish(Some(AccountAction::Cancel)),
+                "s" => SelectInputResult::Finish(Some(AccountAction::SetCurrent)),
+                "r" => SelectInputResult::Finish(Some(AccountAction::Refresh)),
+                "t" | "e" | "x" => SelectInputResult::Finish(Some(AccountAction::Toggle)),
+                "d" => SelectInputResult::Finish(Some(AccountAction::Delete)),
+                _ => SelectInputResult::Ignored,
+            }
+        }));
+        select_options.on_cursor_change = Some(Box::new(|context| {
+            let selected = &context.items[context.cursor];
+            if selected.separator || selected.disabled || selected.heading {
+                return;
+            }
+            *focus_cell.borrow_mut() = Some(selected.value);
+        }));
+
+        let action = select(&items, select_options)?;
+        if let Some(tracked) = focus_cell.borrow_mut().take() {
+            focus_action = tracked;
+        }
+
+        let action = match action {
+            None => return Ok(AccountAction::Cancel),
+            Some(action) => action,
+        };
+        focus_action = action;
+        if action == AccountAction::Delete {
+            let confirmed = confirm(&format!("Delete {}?", account_title(account)), false)?;
+            if !confirmed {
+                continue;
+            }
+        }
+        if action == AccountAction::Refresh {
+            let confirmed = confirm(
+                &format!("Re-authenticate {}?", account_title(account)),
+                false,
+            )?;
+            if !confirmed {
+                continue;
+            }
+        }
+        return Ok(action);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::auth_menu_builder::AccountStatus;
+    use crate::theme::{create_ui_theme, CreateUiThemeOptions, UiAccent, UiColorProfile, UiGlyphMode, UiPalette};
+
+    fn fixed_ui() -> UiRuntimeOptions {
+        UiRuntimeOptions {
+            v2_enabled: true,
+            color_profile: UiColorProfile::Truecolor,
+            glyph_mode: UiGlyphMode::Ascii,
+            palette: UiPalette::Green,
+            accent: UiAccent::Green,
+            theme: create_ui_theme(CreateUiThemeOptions {
+                profile: Some(UiColorProfile::Truecolor),
+                glyph_mode: Some(UiGlyphMode::Ascii),
+                disable_color: Some(false),
+                ..Default::default()
+            }),
+        }
+    }
+
+    fn sample_account() -> AccountInfo {
+        AccountInfo {
+            index: 0,
+            email: Some("owner@example.com".into()),
+            status: Some(AccountStatus::Ok),
+            last_used: Some(1_700_000_000_000),
+            quota_5h_left_percent: Some(50.0),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn builds_menu_with_exact_structure_and_order() {
+        let ui = fixed_ui();
+        let items = build_auth_menu_items(&[sample_account()], "Check Problem Accounts", 0, &ui);
+        // Quick actions heading + 5 actions.
+        assert!(items[0].heading);
+        assert_eq!(items[0].label, "Quick Actions");
+        assert_eq!(items[1].value, AuthMenuAction::Add);
+        assert_eq!(items[2].value, AuthMenuAction::Check);
+        assert_eq!(items[3].value, AuthMenuAction::Forecast);
+        assert_eq!(items[4].value, AuthMenuAction::Fix);
+        assert_eq!(items[5].value, AuthMenuAction::Settings);
+        assert!(items[6].separator);
+        assert!(items[7].heading);
+        assert_eq!(items[7].label, "Advanced Checks");
+        assert_eq!(items[8].value, AuthMenuAction::DeepCheck);
+        assert_eq!(items[9].value, AuthMenuAction::VerifyFlagged);
+        // Non-flagged verify row is yellow.
+        assert_eq!(items[9].color, Some(crate::select::MenuColor::Yellow));
+        assert!(items[10].separator);
+        assert!(items[11].heading);
+        assert_eq!(items[11].label, "Saved Accounts");
+        // Account row.
+        match &items[12].value {
+            AuthMenuAction::SelectAccount(account) => {
+                assert_eq!(account.email.as_deref(), Some("owner@example.com"));
+            }
+            other => panic!("expected select-account, got {other:?}"),
+        }
+        assert!(items[12].hint.is_some());
+        // Danger zone tail.
+        let n = items.len();
+        assert!(items[n - 3].separator);
+        assert!(items[n - 2].heading);
+        assert_eq!(items[n - 2].label, "Danger Zone");
+        assert_eq!(items[n - 1].value, AuthMenuAction::DeleteAll);
+        assert_eq!(items[n - 1].color, Some(crate::select::MenuColor::Red));
+    }
+
+    #[test]
+    fn flagged_count_colors_verify_row_red_and_labels_it() {
+        let ui = fixed_ui();
+        let items = build_auth_menu_items(
+            &[],
+            &ui_copy::format_check_flagged_label(2),
+            2,
+            &ui,
+        );
+        assert_eq!(items[9].label, "Check Problem Accounts (2)");
+        assert_eq!(items[9].color, Some(crate::select::MenuColor::Red));
+    }
+
+    #[test]
+    fn empty_visible_accounts_render_disabled_no_matches_row() {
+        let ui = fixed_ui();
+        let items = build_auth_menu_items(&[], "Check Problem Accounts", 0, &ui);
+        let row = &items[12];
+        assert!(row.disabled);
+        assert_eq!(row.label, "No accounts match your search");
+    }
+
+    #[test]
+    fn account_row_hint_contains_quota_bar() {
+        // ui-03 end-to-end: the account row's hint carries the rendered quota
+        // bar in the requested glyph mode.
+        let mut ui = fixed_ui();
+        ui.glyph_mode = UiGlyphMode::Unicode;
+        ui.theme = create_ui_theme(CreateUiThemeOptions {
+            profile: Some(UiColorProfile::Truecolor),
+            glyph_mode: Some(UiGlyphMode::Unicode),
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        let items = build_auth_menu_items(&[sample_account()], "x", 0, &ui);
+        let hint = items[12].hint.as_deref().unwrap_or("");
+        assert!(hint.contains('\u{2588}'));
+        assert!(hint.contains('\u{2592}'));
+        assert!(!hint.contains('#'));
+    }
+
+    #[test]
+    fn current_account_gets_current_badge_and_accent_title() {
+        let ui = fixed_ui();
+        let mut account = sample_account();
+        account.is_current_account = Some(true);
+        let items = build_auth_menu_items(&[account], "x", 0, &ui);
+        let label = &items[12].label;
+        assert!(label.contains("[current]"), "{label}");
+        // Status badge appended after the current badge.
+        assert!(label.contains("[ok]"), "{label}");
+    }
+
+    #[test]
+    fn hidden_badges_are_omitted_from_the_row_label() {
+        let ui = fixed_ui();
+        let mut account = sample_account();
+        account.is_current_account = Some(true);
+        account.show_current_badge = Some(false);
+        account.show_status_badge = Some(false);
+        let items = build_auth_menu_items(&[account], "x", 0, &ui);
+        let label = &items[12].label;
+        assert!(!label.contains("[current]"), "{label}");
+        assert!(!label.contains("[ok]"), "{label}");
+    }
+}
diff --git a/crates/tui/src/auth_menu_builder.rs b/crates/tui/src/auth_menu_builder.rs
new file mode 100644
index 000000000..31df47938
--- /dev/null
+++ b/crates/tui/src/auth_menu_builder.rs
@@ -0,0 +1,1460 @@
+//! Port of `lib/ui/auth-menu-builder.ts` — pure builders/formatters for the
+//! accounts dashboard (titles, badges, quota bars, hints).
+//!
+//! Key contracts preserved (spec 12 §9 + gotchas):
+//! - `quota5h*`/`quota7d*` are the *primary/secondary* windows positionally;
+//!   real durations live in `quota_primary_window_minutes` /
+//!   `quota_secondary_window_minutes` (a Codex Business monthly window labels
+//!   "30d", not "5h") — labels are duration-derived, never hard-coded.
+//! - quota bars use Unicode block glyphs ONLY when the theme's stored
+//!   (requested) glyph mode is literally `unicode`; `auto` stays ASCII (ui-03).
+//! - `account_row_color` default (unknown status) is yellow, not green.
+//! - `format_account_hint` shows `Status:` only when the badge is HIDDEN.
+
+use crate::ansi;
+use crate::format::{format_ui_badge, paint_ui_text, quota_tone_from_left_percent, UiBadgeTone, UiTextTone};
+use crate::runtime_options::{get_ui_runtime_options, UiRuntimeOptions};
+use crate::select::MenuColor;
+use crate::theme::UiGlyphMode;
+use crate::ui_copy;
+
+/// TS `AccountStatus` string union.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountStatus {
+    Active,
+    Ok,
+    QuotaExhausted,
+    RateLimited,
+    Cooldown,
+    Disabled,
+    Error,
+    Flagged,
+    Unknown,
+}
+
+impl AccountStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            AccountStatus::Active => "active",
+            AccountStatus::Ok => "ok",
+            AccountStatus::QuotaExhausted => "quota-exhausted",
+            AccountStatus::RateLimited => "rate-limited",
+            AccountStatus::Cooldown => "cooldown",
+            AccountStatus::Disabled => "disabled",
+            AccountStatus::Error => "error",
+            AccountStatus::Flagged => "flagged",
+            AccountStatus::Unknown => "unknown",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "active" => Some(AccountStatus::Active),
+            "ok" => Some(AccountStatus::Ok),
+            "quota-exhausted" => Some(AccountStatus::QuotaExhausted),
+            "rate-limited" => Some(AccountStatus::RateLimited),
+            "cooldown" => Some(AccountStatus::Cooldown),
+            "disabled" => Some(AccountStatus::Disabled),
+            "error" => Some(AccountStatus::Error),
+            "flagged" => Some(AccountStatus::Flagged),
+            "unknown" => Some(AccountStatus::Unknown),
+            _ => None,
+        }
+    }
+}
+
+/// TS `AccountCurrentMarker` (from `lib/runtime/runtime-current-account.ts`).
+/// Defined here because `cma-tui` sits below `cma-runtime` in the crate DAG;
+/// `cma-runtime`/`cma-manager` convert to/from this enum.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountCurrentMarker {
+    Current,
+    InUse,
+    Selected,
+}
+
+impl AccountCurrentMarker {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            AccountCurrentMarker::Current => "current",
+            AccountCurrentMarker::InUse => "in-use",
+            AccountCurrentMarker::Selected => "selected",
+        }
+    }
+}
+
+/// TS `AccountInfo` — display payload for one dashboard row. All fields except
+/// `index` are optional.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AccountInfo {
+    pub index: i64,
+    pub source_index: Option<i64>,
+    pub quick_switch_number: Option<i64>,
+    pub account_id: Option<String>,
+    pub account_label: Option<String>,
+    pub email: Option<String>,
+    pub added_at: Option<i64>,
+    pub last_used: Option<i64>,
+    pub status: Option<AccountStatus>,
+    pub quota_summary: Option<String>,
+    // Positional primary/secondary windows; see module docs.
+    pub quota_5h_left_percent: Option<f64>,
+    pub quota_5h_reset_at_ms: Option<f64>,
+    pub quota_7d_left_percent: Option<f64>,
+    pub quota_7d_reset_at_ms: Option<f64>,
+    pub quota_primary_window_minutes: Option<f64>,
+    pub quota_secondary_window_minutes: Option<f64>,
+    pub quota_rate_limited: Option<bool>,
+    pub quota_exhausted: Option<bool>,
+    pub is_current_account: Option<bool>,
+    pub is_default_account: Option<bool>,
+    pub is_runtime_current_account: Option<bool>,
+    pub current_markers: Option<Vec<AccountCurrentMarker>>,
+    pub enabled: Option<bool>,
+    pub show_status_badge: Option<bool>,
+    pub show_current_badge: Option<bool>,
+    pub show_last_used: Option<bool>,
+    pub show_quota_cooldown: Option<bool>,
+    pub show_hints_for_unselected_rows: Option<bool>,
+    pub highlight_current_row: Option<bool>,
+    pub focus_style: Option<crate::select::FocusStyle>,
+    pub statusline_fields: Option<Vec<String>>,
+}
+
+/// Status message for the dashboard subtitle: static text or a live closure.
+pub enum StatusMessage<'a> {
+    Text(String),
+    Dynamic(Box<dyn Fn() -> Option<String> + 'a>),
+}
+
+impl StatusMessage<'_> {
+    pub fn resolve(&self) -> Option<String> {
+        match self {
+            StatusMessage::Text(text) => Some(text.clone()),
+            StatusMessage::Dynamic(f) => f(),
+        }
+    }
+}
+
+/// TS `AuthMenuOptions`.
+#[derive(Default)]
+pub struct AuthMenuOptions<'a> {
+    pub flagged_count: Option<i64>,
+    pub status_message: Option<StatusMessage<'a>>,
+}
+
+/// TS `AuthMenuAction` tagged union.
+#[derive(Debug, Clone, PartialEq)]
+pub enum AuthMenuAction {
+    Add,
+    Forecast,
+    Fix,
+    Settings,
+    Fresh,
+    Check,
+    DeepCheck,
+    VerifyFlagged,
+    SelectAccount(AccountInfo),
+    SetCurrentAccount(AccountInfo),
+    RefreshAccount(AccountInfo),
+    ToggleAccount(AccountInfo),
+    DeleteAccount(AccountInfo),
+    Search,
+    DeleteAll,
+    Cancel,
+}
+
+impl AuthMenuAction {
+    /// The TS discriminant string (`action.type`).
+    pub fn type_str(&self) -> &'static str {
+        match self {
+            AuthMenuAction::Add => "add",
+            AuthMenuAction::Forecast => "forecast",
+            AuthMenuAction::Fix => "fix",
+            AuthMenuAction::Settings => "settings",
+            AuthMenuAction::Fresh => "fresh",
+            AuthMenuAction::Check => "check",
+            AuthMenuAction::DeepCheck => "deep-check",
+            AuthMenuAction::VerifyFlagged => "verify-flagged",
+            AuthMenuAction::SelectAccount(_) => "select-account",
+            AuthMenuAction::SetCurrentAccount(_) => "set-current-account",
+            AuthMenuAction::RefreshAccount(_) => "refresh-account",
+            AuthMenuAction::ToggleAccount(_) => "toggle-account",
+            AuthMenuAction::DeleteAccount(_) => "delete-account",
+            AuthMenuAction::Search => "search",
+            AuthMenuAction::DeleteAll => "delete-all",
+            AuthMenuAction::Cancel => "cancel",
+        }
+    }
+
+    pub fn account(&self) -> Option<&AccountInfo> {
+        match self {
+            AuthMenuAction::SelectAccount(a)
+            | AuthMenuAction::SetCurrentAccount(a)
+            | AuthMenuAction::RefreshAccount(a)
+            | AuthMenuAction::ToggleAccount(a)
+            | AuthMenuAction::DeleteAccount(a) => Some(a),
+            _ => None,
+        }
+    }
+}
+
+/// TS `AccountAction` string union.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountAction {
+    Back,
+    Delete,
+    Refresh,
+    Toggle,
+    SetCurrent,
+    Cancel,
+}
+
+fn resolve_cli_version_label_from(raw: Option<&str>) -> Option<String> {
+    let raw = raw.unwrap_or("").trim().to_string();
+    if raw.is_empty() {
+        return None;
+    }
+    if raw.starts_with('v') {
+        Some(raw)
+    } else {
+        Some(format!("v{raw}"))
+    }
+}
+
+/// Testable core of [`main_menu_title_with_version`].
+pub(crate) fn main_menu_title_with_version_from(raw: Option<&str>) -> String {
+    match resolve_cli_version_label_from(raw) {
+        None => ui_copy::main_menu::TITLE.to_string(),
+        Some(version_label) => format!("{} ({version_label})", ui_copy::main_menu::TITLE),
+    }
+}
+
+/// Reads env `CODEX_MULTI_AUTH_CLI_VERSION` (trimmed); prefixes `v` only when
+/// the value does not already start with lowercase `v`.
+pub fn main_menu_title_with_version() -> String {
+    let raw = std::env::var("CODEX_MULTI_AUTH_CLI_VERSION").ok();
+    main_menu_title_with_version_from(raw.as_deref())
+}
+
+/// Strip ANSI CSI sequences (`\x1b\[[0-?]*[ -/]*[@-~]`) and C0/DEL control
+/// characters, then trim; empty results become `None`.
+fn sanitize_terminal_text(value: Option<&str>) -> Option<String> {
+    let value = value?;
+    if value.is_empty() {
+        return None;
+    }
+    // Pass 1: strip full CSI sequences.
+    let mut stripped = String::with_capacity(value.len());
+    let bytes = value.as_bytes();
+    let mut i = 0usize;
+    while i < bytes.len() {
+        if bytes[i] == 0x1b && i + 1 < bytes.len() && bytes[i + 1] == b'[' {
+            let mut j = i + 2;
+            while j < bytes.len() && (0x30..=0x3f).contains(&bytes[j]) {
+                j += 1;
+            }
+            while j < bytes.len() && (0x20..=0x2f).contains(&bytes[j]) {
+                j += 1;
+            }
+            if j < bytes.len() && (0x40..=0x7e).contains(&bytes[j]) {
+                i = j + 1; // full CSI matched: drop it
+                continue;
+            }
+        }
+        // Copy one full UTF-8 char.
+        let ch = value[i..].chars().next().unwrap();
+        stripped.push(ch);
+        i += ch.len_utf8();
+    }
+    // Pass 2: strip C0 controls (U+0000-U+001F) and DEL (U+007F), then trim.
+    let cleaned: String = stripped
+        .chars()
+        .filter(|&c| !(c as u32 <= 0x1f || c as u32 == 0x7f))
+        .collect();
+    let trimmed = cleaned.trim().to_string();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+/// Days-from-epoch to civil date (Howard Hinnant's algorithm), UTC.
+fn civil_from_ms(timestamp_ms: i64) -> (i64, u32, u32) {
+    let days = (timestamp_ms as f64 / 86_400_000.0).floor() as i64;
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = doy - (153 * mp + 2) / 5 + 1;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 };
+    let year = if m <= 2 { y + 1 } else { y };
+    (year, m as u32, d as u32)
+}
+
+/// Locale-date analogue of `new Date(ts).toLocaleDateString()`.
+///
+/// DIVERGENCE (documented per spec 12 gotcha 30, scoped to the FORMAT only):
+/// the TS output is locale/OS dependent; this port pins the en-US `M/D/YYYY`
+/// form. The calendar day itself is computed in the LOCAL timezone exactly
+/// like `toLocaleDateString()` — using the UTC day would render `Added:` /
+/// `Last used:` one calendar day off for any user east/west of UTC when the
+/// timestamp falls near local midnight. The UTC civil algorithm remains only
+/// as the (practically unreachable) fallback when the local conversion is
+/// not representable.
+fn format_locale_date(timestamp_ms: i64) -> String {
+    use chrono::{Datelike, TimeZone};
+    if let Some(local) = chrono::Local.timestamp_millis_opt(timestamp_ms).single() {
+        return format!("{}/{}/{}", local.month(), local.day(), local.year());
+    }
+    let (year, month, day) = civil_from_ms(timestamp_ms);
+    format!("{month}/{day}/{year}")
+}
+
+/// Testable core of [`format_relative_time`].
+pub(crate) fn format_relative_time_at(timestamp: Option<i64>, now_ms: i64) -> String {
+    let ts = match timestamp {
+        None | Some(0) => return "never".to_string(), // TS falsy check
+        Some(ts) => ts,
+    };
+    let days = ((now_ms - ts) as f64 / 86_400_000.0).floor() as i64;
+    if days <= 0 {
+        return "today".to_string();
+    }
+    if days == 1 {
+        return "yesterday".to_string();
+    }
+    if days < 7 {
+        return format!("{days}d ago");
+    }
+    if days < 30 {
+        return format!("{}w ago", days / 7);
+    }
+    format_locale_date(ts)
+}
+
+pub fn format_relative_time(timestamp: Option<i64>) -> String {
+    format_relative_time_at(timestamp, cma_core::utils::now_ms())
+}
+
+pub fn format_date(timestamp: Option<i64>) -> String {
+    match timestamp {
+        None | Some(0) => "unknown".to_string(), // TS falsy check
+        Some(ts) => format_locale_date(ts),
+    }
+}
+
+fn status_tone(status: Option<AccountStatus>) -> UiBadgeTone {
+    match status {
+        Some(AccountStatus::Active) | Some(AccountStatus::Ok) => UiBadgeTone::Success,
+        Some(AccountStatus::QuotaExhausted)
+        | Some(AccountStatus::RateLimited)
+        | Some(AccountStatus::Cooldown) => UiBadgeTone::Warning,
+        Some(AccountStatus::Disabled)
+        | Some(AccountStatus::Error)
+        | Some(AccountStatus::Flagged) => UiBadgeTone::Danger,
+        Some(AccountStatus::Unknown) | None => UiBadgeTone::Muted,
+    }
+}
+
+fn status_text(status: Option<AccountStatus>) -> &'static str {
+    status.map(AccountStatus::as_str).unwrap_or("unknown")
+}
+
+fn badge_with_tone(ui: &UiRuntimeOptions, label: &str, tone: UiBadgeTone) -> String {
+    if ui.v2_enabled {
+        return format_ui_badge(ui, label, tone);
+    }
+    match tone {
+        UiBadgeTone::Primary | UiBadgeTone::Accent | UiBadgeTone::Success => format!(
+            "{}{}[{label}]{}",
+            ansi::BG_GREEN,
+            ansi::BLACK,
+            ansi::RESET
+        ),
+        UiBadgeTone::Warning => format!(
+            "{}{}[{label}]{}",
+            ansi::BG_YELLOW,
+            ansi::BLACK,
+            ansi::RESET
+        ),
+        UiBadgeTone::Danger => {
+            format!("{}{}[{label}]{}", ansi::BG_RED, ansi::WHITE, ansi::RESET)
+        }
+        UiBadgeTone::Muted => format!("{}[{label}]{}", ansi::INVERSE, ansi::RESET),
+    }
+}
+
+/// Maps a status to a `[label]` badge (v2 badge or legacy ANSI). The label is
+/// the status string itself; missing/unknown → "unknown" muted.
+pub fn status_badge(status: Option<AccountStatus>) -> String {
+    let ui = get_ui_runtime_options();
+    let label = status_text(status);
+    badge_with_tone(&ui, label, status_tone(status))
+}
+
+fn account_number(account: &AccountInfo) -> i64 {
+    account.quick_switch_number.unwrap_or(account.index + 1)
+}
+
+/// `accountTitle` — `${accountNumber}. ${base}` where base is the first
+/// non-empty of sanitized email, label, id, else `Account ${accountNumber}`.
+pub fn account_title(account: &AccountInfo) -> String {
+    let number = account_number(account);
+    let base = sanitize_terminal_text(account.email.as_deref())
+        .or_else(|| sanitize_terminal_text(account.account_label.as_deref()))
+        .or_else(|| sanitize_terminal_text(account.account_id.as_deref()))
+        .unwrap_or_else(|| format!("Account {number}"));
+    format!("{number}. {base}")
+}
+
+/// `accountSearchText` — sanitized identity fields + the row number, joined
+/// with spaces and lowercased.
+pub fn account_search_text(account: &AccountInfo) -> String {
+    let mut parts: Vec<String> = Vec::new();
+    for value in [
+        sanitize_terminal_text(account.email.as_deref()),
+        sanitize_terminal_text(account.account_label.as_deref()),
+        sanitize_terminal_text(account.account_id.as_deref()),
+        Some(account_number(account).to_string()),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        if !value.trim().is_empty() {
+            parts.push(value);
+        }
+    }
+    parts.join(" ").to_lowercase()
+}
+
+/// `accountRowColor` — current row (highlighting enabled) is green; otherwise
+/// mapped by status with a **yellow** default for unknown statuses.
+pub fn account_row_color(account: &AccountInfo) -> MenuColor {
+    if account.is_current_account == Some(true) && account.highlight_current_row != Some(false) {
+        return MenuColor::Green;
+    }
+    match account.status {
+        Some(AccountStatus::Active) | Some(AccountStatus::Ok) => MenuColor::Green,
+        Some(AccountStatus::QuotaExhausted)
+        | Some(AccountStatus::RateLimited)
+        | Some(AccountStatus::Cooldown) => MenuColor::Yellow,
+        Some(AccountStatus::Disabled)
+        | Some(AccountStatus::Error)
+        | Some(AccountStatus::Flagged) => MenuColor::Red,
+        _ => MenuColor::Yellow,
+    }
+}
+
+/// `currentMarkerLabel` — `"in-use"` humanizes to `"in use"`.
+pub fn current_marker_label(marker: AccountCurrentMarker) -> &'static str {
+    match marker {
+        AccountCurrentMarker::InUse => "in use",
+        marker => marker.as_str(),
+    }
+}
+
+fn normalize_quota_percent(value: Option<f64>) -> Option<i64> {
+    let value = value?;
+    if !value.is_finite() {
+        return None;
+    }
+    Some((value.round() as i64).clamp(0, 100))
+}
+
+/// `Number.parseInt(value, 10)` prefix-parse semantics.
+pub(crate) fn parse_int_prefix(value: &str) -> Option<i64> {
+    let trimmed = value.trim_start();
+    let mut chars = trimmed.chars().peekable();
+    let mut digits = String::new();
+    let mut negative = false;
+    if let Some(&sign) = chars.peek()
+        && (sign == '-' || sign == '+') {
+            negative = sign == '-';
+            chars.next();
+        }
+    for ch in chars {
+        if ch.is_ascii_digit() {
+            digits.push(ch);
+        } else {
+            break;
+        }
+    }
+    if digits.is_empty() {
+        return None;
+    }
+    let magnitude: i64 = digits.parse().ok()?;
+    Some(if negative { -magnitude } else { magnitude })
+}
+
+fn parse_left_percent_from_summary(summary: &str, window_label: &str) -> Option<i64> {
+    for segment in summary.split('|') {
+        let trimmed = segment.trim().to_lowercase();
+        if !trimmed.starts_with(&format!("{window_label} ")) {
+            continue;
+        }
+        let percent_token = trimmed[window_label.len()..]
+            .split_whitespace()
+            .next()
+            .unwrap_or("")
+            .to_string();
+        let parsed = match parse_int_prefix(&percent_token.replacen('%', "", 1)) {
+            Some(parsed) => parsed,
+            None => continue,
+        };
+        return Some(parsed.clamp(0, 100));
+    }
+    None
+}
+
+fn format_duration_compact(milliseconds: f64) -> String {
+    let total_seconds = ((milliseconds / 1_000.0).ceil() as i64).max(0);
+    if total_seconds < 60 {
+        return format!("{total_seconds}s");
+    }
+    let total_minutes = total_seconds / 60;
+    if total_minutes < 60 {
+        let seconds = total_seconds % 60;
+        return if seconds > 0 {
+            format!("{total_minutes}m {seconds}s")
+        } else {
+            format!("{total_minutes}m")
+        };
+    }
+    let total_hours = total_minutes / 60;
+    if total_hours < 24 {
+        let minutes = total_minutes % 60;
+        return if minutes > 0 {
+            format!("{total_hours}h {minutes}m")
+        } else {
+            format!("{total_hours}h")
+        };
+    }
+    let days = total_hours / 24;
+    let hours = total_hours % 24;
+    if hours > 0 {
+        format!("{days}d {hours}h")
+    } else {
+        format!("{days}d")
+    }
+}
+
+fn format_limit_cooldown(reset_at_ms: Option<f64>, now_ms: i64) -> Option<String> {
+    let reset_at = reset_at_ms?;
+    if !reset_at.is_finite() {
+        return None;
+    }
+    let remaining = reset_at - now_ms as f64;
+    if remaining <= 0.0 {
+        return Some("reset ready".to_string());
+    }
+    Some(format!("reset {}", format_duration_compact(remaining)))
+}
+
+fn format_quota_bar(left_percent: Option<i64>, ui: &UiRuntimeOptions) -> String {
+    let width: i64 = 10;
+    let ratio = left_percent.unwrap_or(0) as f64 / 100.0;
+    let filled = ((ratio * width as f64).round() as i64).clamp(0, width) as usize;
+    // ui-03: honor glyph mode — the check reads the theme's STORED (requested)
+    // glyph mode, and only a literal `unicode` gets block glyphs; `auto`
+    // deliberately stays ASCII.
+    let use_unicode_bar = ui.theme.glyph_mode == UiGlyphMode::Unicode;
+    let fill_char = if use_unicode_bar { "\u{2588}" } else { "#" };
+    let empty_char = if use_unicode_bar { "\u{2592}" } else { "-" };
+    let filled_text = fill_char.repeat(filled);
+    let empty_text = empty_char.repeat((width as usize) - filled);
+    if ui.v2_enabled {
+        let tone = match left_percent {
+            None => UiTextTone::Muted,
+            Some(percent) => quota_tone_from_left_percent(percent as f64),
+        };
+        let filled_segment = if !filled_text.is_empty() {
+            paint_ui_text(ui, &filled_text, tone)
+        } else {
+            String::new()
+        };
+        let empty_segment = if !empty_text.is_empty() {
+            paint_ui_text(ui, &empty_text, UiTextTone::Muted)
+        } else {
+            String::new()
+        };
+        return format!("{filled_segment}{empty_segment}");
+    }
+    let left_percent = match left_percent {
+        None => return format!("{}{empty_text}{}", ansi::DIM, ansi::RESET),
+        Some(percent) => percent,
+    };
+    let color = if left_percent <= 15 {
+        ansi::RED
+    } else if left_percent <= 35 {
+        ansi::YELLOW
+    } else {
+        ansi::GREEN
+    };
+    let filled_segment = if !filled_text.is_empty() {
+        format!("{color}{filled_text}{}", ansi::RESET)
+    } else {
+        String::new()
+    };
+    let empty_segment = if !empty_text.is_empty() {
+        format!("{}{empty_text}{}", ansi::DIM, ansi::RESET)
+    } else {
+        String::new()
+    };
+    format!("{filled_segment}{empty_segment}")
+}
+
+fn format_quota_percent(left_percent: Option<i64>, ui: &UiRuntimeOptions) -> Option<String> {
+    let left_percent = left_percent?;
+    let percent_text = format!("{left_percent}%");
+    if !ui.v2_enabled {
+        let color = if left_percent <= 15 {
+            ansi::RED
+        } else if left_percent <= 35 {
+            ansi::YELLOW
+        } else {
+            ansi::GREEN
+        };
+        return Some(format!("{color}{percent_text}{}", ansi::RESET));
+    }
+    let tone = quota_tone_from_left_percent(left_percent as f64);
+    Some(paint_ui_text(ui, &percent_text, tone))
+}
+
+/// JS-style number rendering: integers print without a decimal point.
+fn format_js_number(value: f64) -> String {
+    if value.fract() == 0.0 && value.abs() < 1e15 {
+        format!("{}", value as i64)
+    } else {
+        format!("{value}")
+    }
+}
+
+/// Resolve a quota-window label from its duration in minutes (`Nd`/`Nh`/`Nm`);
+/// falls back to the positional label when the duration is unknown or invalid.
+pub fn resolve_quota_window_label(window_minutes: Option<f64>, fallback_label: &str) -> String {
+    let minutes = match window_minutes {
+        Some(minutes) if minutes.is_finite() && minutes > 0.0 => minutes,
+        _ => return fallback_label.to_string(),
+    };
+    if minutes % 1440.0 == 0.0 {
+        return format!("{}d", format_js_number(minutes / 1440.0));
+    }
+    if minutes % 60.0 == 0.0 {
+        return format!("{}h", format_js_number(minutes / 60.0));
+    }
+    format!("{}m", format_js_number(minutes))
+}
+
+fn format_quota_window(
+    label: &str,
+    left_percent: Option<i64>,
+    reset_at_ms: Option<f64>,
+    show_cooldown: bool,
+    ui: &UiRuntimeOptions,
+    now_ms: i64,
+) -> String {
+    let label_text = if ui.v2_enabled {
+        paint_ui_text(ui, label, UiTextTone::Muted)
+    } else {
+        label.to_string()
+    };
+    let bar = format_quota_bar(left_percent, ui);
+    let percent = format_quota_percent(left_percent, ui);
+    if !show_cooldown {
+        return match percent {
+            Some(percent) => format!("{label_text} {bar} {percent}"),
+            None => format!("{label_text} {bar}"),
+        };
+    }
+    let cooldown = format_limit_cooldown(reset_at_ms, now_ms);
+    let cooldown = match cooldown {
+        None => {
+            return match percent {
+                Some(percent) => format!("{label_text} {bar} {percent}"),
+                None => format!("{label_text} {bar}"),
+            };
+        }
+        Some(cooldown) => cooldown,
+    };
+    let cooldown_text = if ui.v2_enabled {
+        paint_ui_text(ui, &cooldown, UiTextTone::Muted)
+    } else {
+        cooldown
+    };
+    match percent {
+        None => format!("{label_text} {bar} {cooldown_text}"),
+        Some(percent) => format!("{label_text} {bar} {percent} {cooldown_text}"),
+    }
+}
+
+fn format_quota_summary(account: &AccountInfo, ui: &UiRuntimeOptions, now_ms: i64) -> String {
+    let summary = account.quota_summary.clone().unwrap_or_default();
+    let show_cooldown = account.show_quota_cooldown != Some(false);
+    // Resolve window labels BEFORE parsing the summary — the summary string is
+    // already labelled by duration (a Business row reads "30d 18%, ..."), so
+    // searching it for a literal "5h"/"7d" would silently drop the bar.
+    let primary_label = resolve_quota_window_label(account.quota_primary_window_minutes, "5h");
+    let secondary_label = resolve_quota_window_label(account.quota_secondary_window_minutes, "7d");
+    let left_5h = normalize_quota_percent(account.quota_5h_left_percent)
+        .or_else(|| parse_left_percent_from_summary(&summary, &primary_label));
+    let left_7d = normalize_quota_percent(account.quota_7d_left_percent)
+        .or_else(|| parse_left_percent_from_summary(&summary, &secondary_label));
+    let mut segments: Vec<String> = Vec::new();
+
+    if left_5h.is_some() || account.quota_5h_reset_at_ms.is_some() {
+        segments.push(format_quota_window(
+            &primary_label,
+            left_5h,
+            account.quota_5h_reset_at_ms,
+            show_cooldown,
+            ui,
+            now_ms,
+        ));
+    }
+    if left_7d.is_some() || account.quota_7d_reset_at_ms.is_some() {
+        segments.push(format_quota_window(
+            &secondary_label,
+            left_7d,
+            account.quota_7d_reset_at_ms,
+            show_cooldown,
+            ui,
+            now_ms,
+        ));
+    }
+    let summary_lower = summary.to_lowercase();
+    if account.quota_rate_limited == Some(true) || summary_lower.contains("rate-limited") {
+        segments.push(if ui.v2_enabled {
+            paint_ui_text(ui, "rate-limited", UiTextTone::Danger)
+        } else {
+            format!("{}rate-limited{}", ansi::RED, ansi::RESET)
+        });
+    }
+    if account.quota_exhausted == Some(true) || summary_lower.contains("quota-exhausted") {
+        segments.push(if ui.v2_enabled {
+            paint_ui_text(ui, "quota-exhausted", UiTextTone::Danger)
+        } else {
+            format!("{}quota-exhausted{}", ansi::RED, ansi::RESET)
+        });
+    }
+
+    if segments.is_empty() {
+        if summary.is_empty() {
+            return String::new();
+        }
+        return if ui.v2_enabled {
+            paint_ui_text(ui, &summary, UiTextTone::Muted)
+        } else {
+            summary
+        };
+    }
+
+    let separator = if ui.v2_enabled {
+        format!(" {} ", paint_ui_text(ui, "|", UiTextTone::Muted))
+    } else {
+        " | ".to_string()
+    };
+    segments.join(&separator)
+}
+
+fn badge_tone_to_text_tone(tone: UiBadgeTone) -> UiTextTone {
+    match tone {
+        UiBadgeTone::Primary => UiTextTone::Primary,
+        UiBadgeTone::Accent => UiTextTone::Accent,
+        UiBadgeTone::Success => UiTextTone::Success,
+        UiBadgeTone::Warning => UiTextTone::Warning,
+        UiBadgeTone::Danger => UiTextTone::Danger,
+        UiBadgeTone::Muted => UiTextTone::Muted,
+    }
+}
+
+/// `formatAccountHint` — builds the `status` / `last-used` / `limits` parts and
+/// joins them per `statusline_fields` (default `["last-used","limits","status"]`).
+pub fn format_account_hint(account: &AccountInfo, ui: &UiRuntimeOptions) -> String {
+    let now_ms = cma_core::utils::now_ms();
+    let with_key = |key: &str, value: &str, tone: UiTextTone| -> String {
+        if !ui.v2_enabled {
+            return format!("{key} {value}");
+        }
+        if value.contains("\x1b[") {
+            return format!("{} {value}", paint_ui_text(ui, key, UiTextTone::Muted));
+        }
+        format!(
+            "{} {}",
+            paint_ui_text(ui, key, UiTextTone::Muted),
+            paint_ui_text(ui, value, tone)
+        )
+    };
+
+    let mut parts_by_key: Vec<(&str, String)> = Vec::new();
+    if account.show_status_badge == Some(false) {
+        parts_by_key.push((
+            "status",
+            with_key(
+                "Status:",
+                status_text(account.status),
+                badge_tone_to_text_tone(status_tone(account.status)),
+            ),
+        ));
+    }
+    if account.show_last_used != Some(false) {
+        parts_by_key.push((
+            "last-used",
+            with_key(
+                "Last used:",
+                &format_relative_time_at(account.last_used, now_ms),
+                UiTextTone::Heading,
+            ),
+        ));
+    }
+    let quota_summary_text = format_quota_summary(account, ui, now_ms);
+    if !quota_summary_text.is_empty() {
+        parts_by_key.push(("limits", with_key("Limits:", &quota_summary_text, UiTextTone::Accent)));
+    }
+
+    let default_fields = ["last-used", "limits", "status"];
+    let configured: Vec<&str> = account
+        .statusline_fields
+        .as_ref()
+        .filter(|f| !f.is_empty())
+        .map(|f| f.iter().map(String::as_str).collect())
+        .unwrap_or_else(|| default_fields.to_vec());
+    let mut ordered_parts: Vec<String> = Vec::new();
+    for field in configured {
+        if let Some((_, part)) = parts_by_key.iter().find(|(key, _)| *key == field) {
+            ordered_parts.push(part.clone());
+        }
+    }
+
+    if ordered_parts.is_empty() {
+        return String::new();
+    }
+    let separator = if ui.v2_enabled {
+        format!(" {} ", paint_ui_text(ui, "|", UiTextTone::Muted))
+    } else {
+        " | ".to_string()
+    };
+    if ordered_parts.len() == 1 {
+        return ordered_parts[0].clone();
+    }
+
+    // NOTE: not actually two lines — a single string (spec 12 gotcha 11).
+    let first_line = ordered_parts[..2].join(&separator);
+    let second_line = ordered_parts[2..].join(&separator);
+    if second_line.is_empty() {
+        first_line
+    } else {
+        format!("{first_line}{separator}{second_line}")
+    }
+}
+
+/// `authMenuFocusKey` — account-carrying actions key by storage position;
+/// static actions key by their type.
+pub fn auth_menu_focus_key(action: &AuthMenuAction) -> String {
+    match action.account() {
+        Some(account) => format!(
+            "account:{}",
+            account.source_index.unwrap_or(account.index)
+        ),
+        None => format!("action:{}", action.type_str()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::{create_ui_theme, CreateUiThemeOptions, UiAccent, UiColorProfile, UiPalette};
+    use serial_test::serial;
+
+    const DAY_MS: i64 = 86_400_000;
+
+    fn strip_ansi(value: &str) -> String {
+        crate::select::strip_ansi(value)
+    }
+
+    fn account(overrides: impl FnOnce(&mut AccountInfo)) -> AccountInfo {
+        let mut info = AccountInfo {
+            index: 0,
+            ..Default::default()
+        };
+        overrides(&mut info);
+        info
+    }
+
+    fn fixed_ui(v2: bool, glyph_mode: UiGlyphMode) -> UiRuntimeOptions {
+        UiRuntimeOptions {
+            v2_enabled: v2,
+            color_profile: UiColorProfile::Truecolor,
+            glyph_mode,
+            palette: UiPalette::Green,
+            accent: UiAccent::Green,
+            theme: create_ui_theme(CreateUiThemeOptions {
+                profile: Some(UiColorProfile::Truecolor),
+                glyph_mode: Some(glyph_mode),
+                disable_color: Some(false),
+                ..Default::default()
+            }),
+        }
+    }
+
+    // ---- mainMenuTitleWithVersion ----
+
+    #[test]
+    fn returns_bare_title_when_no_cli_version_is_exported() {
+        assert_eq!(main_menu_title_with_version_from(None), "Accounts Dashboard");
+        assert_eq!(
+            main_menu_title_with_version_from(Some("  ")),
+            "Accounts Dashboard"
+        );
+    }
+
+    #[test]
+    fn appends_the_version_prefixing_v_only_when_missing() {
+        assert_eq!(
+            main_menu_title_with_version_from(Some("1.2.3")),
+            "Accounts Dashboard (v1.2.3)"
+        );
+        assert_eq!(
+            main_menu_title_with_version_from(Some("v2.0.0")),
+            "Accounts Dashboard (v2.0.0)"
+        );
+        // Capital V is not recognized — becomes vV1.2.3 (gotcha 29).
+        assert_eq!(
+            main_menu_title_with_version_from(Some("V1.2.3")),
+            "Accounts Dashboard (vV1.2.3)"
+        );
+    }
+
+    // ---- formatRelativeTime ----
+
+    #[test]
+    fn renders_relative_times() {
+        let now = cma_core::utils::now_ms();
+        assert_eq!(format_relative_time_at(None, now), "never");
+        assert_eq!(format_relative_time_at(Some(0), now), "never");
+        assert_eq!(format_relative_time_at(Some(now - 1_000), now), "today");
+        assert_eq!(
+            format_relative_time_at(Some(now - DAY_MS - 1_000), now),
+            "yesterday"
+        );
+        assert_eq!(
+            format_relative_time_at(Some(now - 3 * DAY_MS - 1_000), now),
+            "3d ago"
+        );
+        assert_eq!(
+            format_relative_time_at(Some(now - 15 * DAY_MS), now),
+            "2w ago"
+        );
+    }
+
+    #[test]
+    fn falls_back_to_a_date_beyond_a_month() {
+        let now = cma_core::utils::now_ms();
+        let old = now - 60 * DAY_MS;
+        let rendered = format_relative_time_at(Some(old), now);
+        // M/D/YYYY shape.
+        let parts: Vec<&str> = rendered.split('/').collect();
+        assert_eq!(parts.len(), 3);
+        assert!(parts.iter().all(|p| p.chars().all(|c| c.is_ascii_digit())));
+    }
+
+    #[test]
+    fn civil_date_conversion_is_correct() {
+        // The UTC civil fallback algorithm itself.
+        // 1784937600000 ms = day 20659 since the epoch = 2026-07-25 UTC.
+        assert_eq!(civil_from_ms(1_784_937_600_000), (2026, 7, 25));
+        assert_eq!(civil_from_ms(0), (1970, 1, 1));
+    }
+
+    /// `toLocaleDateString()` parity: the rendered day is the LOCAL calendar
+    /// day (timezone-aware expectation so this passes in any TZ), pinned to
+    /// the en-US M/D/YYYY shape.
+    #[test]
+    fn locale_date_uses_the_local_calendar_day() {
+        use chrono::{Datelike, TimeZone};
+        for ts in [1_784_937_600_000_i64, 0_i64] {
+            let local = chrono::Local
+                .timestamp_millis_opt(ts)
+                .single()
+                .expect("local conversion");
+            assert_eq!(
+                format_locale_date(ts),
+                format!("{}/{}/{}", local.month(), local.day(), local.year()),
+                "ts {ts}"
+            );
+        }
+    }
+
+    // ---- accountTitle ----
+
+    #[test]
+    fn prefers_email_then_label_then_id_then_generic() {
+        assert_eq!(
+            account_title(&account(|a| a.email = Some("a@example.com".into()))),
+            "1. a@example.com"
+        );
+        assert_eq!(
+            account_title(&account(|a| a.account_label = Some("Team A".into()))),
+            "1. Team A"
+        );
+        assert_eq!(
+            account_title(&account(|a| a.account_id = Some("acc_1".into()))),
+            "1. acc_1"
+        );
+        assert_eq!(account_title(&account(|_| {})), "1. Account 1");
+    }
+
+    #[test]
+    fn numbers_rows_by_quick_switch_number_when_present() {
+        assert_eq!(
+            account_title(&account(|a| {
+                a.index = 4;
+                a.quick_switch_number = Some(2);
+                a.email = Some("a@b.c".into());
+            })),
+            "2. a@b.c"
+        );
+    }
+
+    #[test]
+    fn strips_ansi_escapes_and_control_chars_from_identity_fields() {
+        assert_eq!(
+            account_title(&account(|a| a.account_label =
+                Some("\x1b[31mEvil\x1b[0m Label".into()))),
+            "1. Evil Label"
+        );
+        assert_eq!(
+            account_title(&account(|a| a.email = Some("\x1b[2Jevil@example.com".into()))),
+            "1. evil@example.com"
+        );
+        assert_eq!(
+            account_title(&account(|a| a.account_id = Some("acc\x1b[31m_red".into()))),
+            "1. acc_red"
+        );
+    }
+
+    // ---- accountSearchText ----
+
+    #[test]
+    fn joins_lowercased_identity_fields_and_row_number() {
+        assert_eq!(
+            account_search_text(&account(|a| {
+                a.index = 1;
+                a.email = Some("User@Example.com".into());
+                a.account_label = Some("Team A".into());
+                a.account_id = Some("ACC_9".into());
+            })),
+            "user@example.com team a acc_9 2"
+        );
+    }
+
+    // ---- accountRowColor ----
+
+    #[test]
+    fn highlights_current_row_green_unless_highlighting_disabled() {
+        assert_eq!(
+            account_row_color(&account(|a| {
+                a.is_current_account = Some(true);
+                a.status = Some(AccountStatus::Disabled);
+            })),
+            MenuColor::Green
+        );
+        assert_eq!(
+            account_row_color(&account(|a| {
+                a.is_current_account = Some(true);
+                a.highlight_current_row = Some(false);
+                a.status = Some(AccountStatus::Disabled);
+            })),
+            MenuColor::Red
+        );
+    }
+
+    #[test]
+    fn maps_status_to_row_color_with_yellow_default() {
+        assert_eq!(
+            account_row_color(&account(|a| a.status = Some(AccountStatus::Ok))),
+            MenuColor::Green
+        );
+        assert_eq!(
+            account_row_color(&account(|a| a.status = Some(AccountStatus::RateLimited))),
+            MenuColor::Yellow
+        );
+        assert_eq!(
+            account_row_color(&account(|a| a.status = Some(AccountStatus::Cooldown))),
+            MenuColor::Yellow
+        );
+        assert_eq!(
+            account_row_color(&account(|a| a.status = Some(AccountStatus::Flagged))),
+            MenuColor::Red
+        );
+        // Unknown/missing status defaults to yellow, not green (gotcha 10).
+        assert_eq!(account_row_color(&account(|_| {})), MenuColor::Yellow);
+    }
+
+    // ---- statusBadge ----
+
+    #[test]
+    #[serial]
+    fn labels_badges_with_their_status() {
+        crate::runtime_options::reset_ui_runtime_options();
+        for status in [
+            AccountStatus::Active,
+            AccountStatus::Ok,
+            AccountStatus::QuotaExhausted,
+            AccountStatus::RateLimited,
+            AccountStatus::Cooldown,
+            AccountStatus::Flagged,
+            AccountStatus::Disabled,
+            AccountStatus::Error,
+        ] {
+            assert!(strip_ansi(&status_badge(Some(status))).contains(status.as_str()));
+        }
+        assert!(strip_ansi(&status_badge(None)).contains("unknown"));
+    }
+
+    #[test]
+    #[serial]
+    fn legacy_badges_have_same_text_content() {
+        crate::runtime_options::set_ui_runtime_options(
+            crate::runtime_options::UiRuntimeOptionsPatch {
+                v2_enabled: Some(false),
+                ..Default::default()
+            },
+        );
+        let result = std::panic::catch_unwind(|| {
+            assert!(
+                strip_ansi(&status_badge(Some(AccountStatus::RateLimited)))
+                    .contains("rate-limited")
+            );
+            assert!(strip_ansi(&status_badge(None)).contains("unknown"));
+        });
+        crate::runtime_options::reset_ui_runtime_options();
+        if let Err(panic) = result {
+            std::panic::resume_unwind(panic);
+        }
+    }
+
+    // ---- formatDate ----
+
+    #[test]
+    fn format_date_renders_unknown_for_missing_timestamps() {
+        assert_eq!(format_date(None), "unknown");
+        assert_eq!(format_date(Some(0)), "unknown");
+        assert!(format_date(Some(1_784_937_600_000)).contains('/'));
+    }
+
+    // ---- currentMarkerLabel ----
+
+    #[test]
+    fn humanizes_in_use_and_passes_other_markers_through() {
+        assert_eq!(current_marker_label(AccountCurrentMarker::InUse), "in use");
+        assert_eq!(current_marker_label(AccountCurrentMarker::Current), "current");
+        assert_eq!(
+            current_marker_label(AccountCurrentMarker::Selected),
+            "selected"
+        );
+    }
+
+    // ---- formatAccountHint ----
+
+    #[test]
+    fn renders_last_used_and_quota_limits_in_default_order() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.last_used = Some(now - 1_000);
+                a.quota_5h_left_percent = Some(50.0);
+                a.quota_5h_reset_at_ms = Some((now + 30_000) as f64);
+            }),
+            &ui,
+        ));
+        assert!(hint.starts_with("Last used: today | Limits: 5h "), "{hint}");
+        assert!(hint.contains("50%"));
+        assert!(hint.contains("reset "));
+    }
+
+    #[test]
+    fn includes_status_text_only_when_badge_column_is_hidden() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let visible_badge = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.status = Some(AccountStatus::Ok);
+                a.last_used = Some(now);
+            }),
+            &ui,
+        ));
+        assert!(!visible_badge.contains("Status:"));
+
+        let hidden_badge = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.status = Some(AccountStatus::Ok);
+                a.last_used = Some(now);
+                a.show_status_badge = Some(false);
+            }),
+            &ui,
+        ));
+        assert!(hidden_badge.contains("Status: ok"));
+    }
+
+    #[test]
+    fn orders_parts_by_configured_statusline_fields() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.status = Some(AccountStatus::Ok);
+                a.last_used = Some(now);
+                a.show_status_badge = Some(false);
+                a.statusline_fields = Some(vec!["status".into(), "last-used".into()]);
+            }),
+            &ui,
+        ));
+        let status_idx = hint.find("Status:").expect("status part");
+        let last_used_idx = hint.find("Last used:").expect("last-used part");
+        assert!(status_idx < last_used_idx);
+    }
+
+    #[test]
+    fn flags_rate_limited_and_exhausted_accounts_in_limits_segment() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.last_used = Some(now);
+                a.quota_rate_limited = Some(true);
+                a.quota_exhausted = Some(true);
+            }),
+            &ui,
+        ));
+        assert!(hint.contains("rate-limited"));
+        assert!(hint.contains("quota-exhausted"));
+    }
+
+    #[test]
+    fn returns_empty_string_when_every_field_is_hidden() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        assert_eq!(
+            format_account_hint(&account(|a| a.show_last_used = Some(false)), &ui),
+            ""
+        );
+    }
+
+    // Regression for issue #635: window labels derive from real durations.
+    #[test]
+    fn labels_primary_window_from_duration_instead_of_positional_5h() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.last_used = Some(now - 2 * DAY_MS);
+                a.quota_5h_left_percent = Some(18.0);
+                a.quota_5h_reset_at_ms = Some((now + 28 * DAY_MS) as f64);
+                a.quota_primary_window_minutes = Some((30 * 24 * 60) as f64);
+                a.quota_7d_left_percent = Some(100.0);
+                a.quota_secondary_window_minutes = Some((7 * 24 * 60) as f64);
+            }),
+            &ui,
+        ));
+        assert!(hint.contains("30d "), "{hint}");
+        assert!(hint.contains("7d "), "{hint}");
+        assert!(!hint.contains("5h"), "{hint}");
+    }
+
+    #[test]
+    fn falls_back_to_positional_labels_when_durations_unknown() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.last_used = Some(now);
+                a.quota_5h_left_percent = Some(50.0);
+                a.quota_7d_left_percent = Some(80.0);
+            }),
+            &ui,
+        ));
+        assert!(hint.contains("5h "));
+        assert!(hint.contains("7d "));
+    }
+
+    fn window_label_for(window_minutes: Option<f64>, primary: bool) -> String {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.show_last_used = Some(false);
+                if primary {
+                    a.quota_5h_left_percent = Some(50.0);
+                    a.quota_primary_window_minutes = window_minutes;
+                } else {
+                    a.quota_7d_left_percent = Some(50.0);
+                    a.quota_secondary_window_minutes = window_minutes;
+                }
+            }),
+            &ui,
+        ));
+        hint.strip_prefix("Limits: ")
+            .unwrap_or(&hint)
+            .split(' ')
+            .next()
+            .unwrap_or("")
+            .to_string()
+    }
+
+    #[test]
+    fn labels_windows_by_duration_table() {
+        assert_eq!(window_label_for(Some(1_440.0), true), "1d");
+        assert_eq!(window_label_for(Some(43_200.0), true), "30d");
+        assert_eq!(window_label_for(Some(300.0), true), "5h");
+        assert_eq!(window_label_for(Some(720.0), true), "12h");
+        assert_eq!(window_label_for(Some(100.0), true), "100m");
+        assert_eq!(window_label_for(Some(90.0), true), "90m");
+    }
+
+    #[test]
+    fn keeps_positional_labels_for_corrupt_durations() {
+        for bad in [Some(0.0), Some(-1.0), Some(f64::NAN), Some(f64::INFINITY)] {
+            assert_eq!(window_label_for(bad, true), "5h");
+            assert_eq!(window_label_for(bad, false), "7d");
+        }
+    }
+
+    #[test]
+    fn recovers_percent_from_summary_using_resolved_window_label() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.show_last_used = Some(false);
+                a.quota_summary = Some("30d 42%, resets in 12d | 7d 80%".into());
+                a.quota_primary_window_minutes = Some((30 * 24 * 60) as f64);
+                a.quota_secondary_window_minutes = Some((7 * 24 * 60) as f64);
+            }),
+            &ui,
+        ));
+        assert!(hint.contains("30d "), "{hint}");
+        assert!(hint.contains("42%"), "{hint}");
+        assert!(hint.contains("80%"), "{hint}");
+    }
+
+    #[test]
+    fn legacy_v1_rendering_has_same_text_content() {
+        let mut ui = fixed_ui(false, UiGlyphMode::Ascii);
+        ui.v2_enabled = false;
+        let now = cma_core::utils::now_ms();
+        let hint = strip_ansi(&format_account_hint(
+            &account(|a| {
+                a.last_used = Some(now - 1_000);
+                a.quota_5h_left_percent = Some(50.0);
+                a.quota_5h_reset_at_ms = Some((now + 30_000) as f64);
+            }),
+            &ui,
+        ));
+        assert!(hint.starts_with("Last used: today | Limits: 5h "), "{hint}");
+        assert!(hint.contains("50%"));
+    }
+
+    // ---- quota bar glyph modes (ui-03), via the public formatter ----
+
+    #[test]
+    fn quota_bar_renders_unicode_block_glyphs_in_unicode_mode() {
+        let ui = fixed_ui(true, UiGlyphMode::Unicode);
+        let hint = format_account_hint(
+            &account(|a| {
+                a.show_last_used = Some(false);
+                a.quota_5h_left_percent = Some(50.0);
+            }),
+            &ui,
+        );
+        assert!(hint.contains('\u{2588}'));
+        assert!(hint.contains('\u{2592}'));
+        assert!(!hint.contains('#'));
+    }
+
+    #[test]
+    fn quota_bar_renders_ascii_glyphs_in_ascii_mode() {
+        let ui = fixed_ui(true, UiGlyphMode::Ascii);
+        let hint = format_account_hint(
+            &account(|a| {
+                a.show_last_used = Some(false);
+                a.quota_5h_left_percent = Some(50.0);
+            }),
+            &ui,
+        );
+        assert!(hint.contains('#'));
+        assert!(!hint.contains('\u{2588}'));
+        assert!(!hint.contains('\u{2592}'));
+    }
+
+    #[test]
+    fn quota_bar_falls_back_to_ascii_in_auto_mode() {
+        // The theme keeps the raw "auto" and only a literal "unicode" gets the
+        // block glyphs, so auto -> ascii regardless of the resolved glyph set.
+        let ui = fixed_ui(true, UiGlyphMode::Auto);
+        let hint = format_account_hint(
+            &account(|a| {
+                a.show_last_used = Some(false);
+                a.quota_5h_left_percent = Some(50.0);
+            }),
+            &ui,
+        );
+        assert!(hint.contains('#'));
+        assert!(!hint.contains('\u{2588}'));
+        assert!(!hint.contains('\u{2592}'));
+    }
+
+    // ---- authMenuFocusKey ----
+
+    #[test]
+    fn keys_account_actions_by_storage_position() {
+        let row = account(|a| {
+            a.index = 2;
+            a.source_index = Some(5);
+        });
+        assert_eq!(
+            auth_menu_focus_key(&AuthMenuAction::SelectAccount(row)),
+            "account:5"
+        );
+        assert_eq!(
+            auth_menu_focus_key(&AuthMenuAction::DeleteAccount(account(|a| a.index = 2))),
+            "account:2"
+        );
+    }
+
+    #[test]
+    fn keys_static_actions_by_their_type() {
+        assert_eq!(auth_menu_focus_key(&AuthMenuAction::Add), "action:add");
+        assert_eq!(auth_menu_focus_key(&AuthMenuAction::Cancel), "action:cancel");
+        assert_eq!(
+            auth_menu_focus_key(&AuthMenuAction::DeepCheck),
+            "action:deep-check"
+        );
+    }
+
+    // ---- helpers ----
+
+    #[test]
+    fn parse_int_prefix_matches_js_parseint() {
+        assert_eq!(parse_int_prefix("42,"), Some(42));
+        assert_eq!(parse_int_prefix("42"), Some(42));
+        assert_eq!(parse_int_prefix("-7x"), Some(-7));
+        assert_eq!(parse_int_prefix("x42"), None);
+        assert_eq!(parse_int_prefix(""), None);
+    }
+
+    #[test]
+    fn duration_compact_formats_all_magnitudes() {
+        assert_eq!(format_duration_compact(500.0), "1s");
+        assert_eq!(format_duration_compact(59_000.0), "59s");
+        assert_eq!(format_duration_compact(60_000.0), "1m");
+        assert_eq!(format_duration_compact(90_000.0), "1m 30s");
+        assert_eq!(format_duration_compact(3_600_000.0), "1h");
+        assert_eq!(format_duration_compact(5_400_000.0), "1h 30m");
+        assert_eq!(format_duration_compact(86_400_000.0), "1d");
+        assert_eq!(format_duration_compact(90_000_000.0), "1d 1h");
+        assert_eq!(format_duration_compact(-5.0), "0s");
+    }
+}
diff --git a/crates/tui/src/confirm.rs b/crates/tui/src/confirm.rs
new file mode 100644
index 000000000..66eb7d8e9
--- /dev/null
+++ b/crates/tui/src/confirm.rs
@@ -0,0 +1,40 @@
+//! Port of `lib/ui/confirm.ts` — Yes/No prompt built on `select`.
+//!
+//! `default_yes` only changes item ORDER (the cursor starts on the first
+//! item); there is no timeout/default-submit behavior. Cancel (Esc / Q /
+//! Ctrl-C) returns `false` (spec 12 gotcha 27).
+
+use crate::runtime_options::get_ui_runtime_options;
+use crate::select::{select, MenuItem, SelectError, SelectOptions};
+
+/// Prompt the user with a Yes/No choice. Returns `true` iff "Yes" is selected;
+/// cancel returns `false`. Propagates `select`'s precondition errors (non-TTY).
+pub fn confirm(message: &str, default_yes: bool) -> Result<bool, SelectError> {
+    let ui = get_ui_runtime_options();
+    let items: Vec<MenuItem<bool>> = if default_yes {
+        vec![MenuItem::new("Yes", true), MenuItem::new("No", false)]
+    } else {
+        vec![MenuItem::new("No", false), MenuItem::new("Yes", true)]
+    };
+
+    let mut options = SelectOptions::new(message);
+    options.theme = Some(ui.theme);
+    let result = select(&items, options)?;
+    Ok(result.unwrap_or(false))
+}
+
+#[cfg(test)]
+mod tests {
+    // `confirm` itself requires a TTY (select throws first), so only the item
+    // ordering contract is testable headlessly; the interactive behavior is
+    // covered by the select engine tests.
+
+    #[test]
+    fn default_yes_flag_only_changes_item_order() {
+        // Mirror the construction logic to pin the order contract.
+        let default_no: Vec<(&str, bool)> = vec![("No", false), ("Yes", true)];
+        let default_yes: Vec<(&str, bool)> = vec![("Yes", true), ("No", false)];
+        assert_eq!(default_no[0].0, "No");
+        assert_eq!(default_yes[0].0, "Yes");
+    }
+}
diff --git a/crates/tui/src/format.rs b/crates/tui/src/format.rs
new file mode 100644
index 000000000..b21ee5139
--- /dev/null
+++ b/crates/tui/src/format.rs
@@ -0,0 +1,357 @@
+//! Port of `lib/ui/format.ts` — tone-based text/badge/key-value formatting.
+//!
+//! DELIBERATE BUG PRESERVED (spec 12 §5 gotcha): `format_ui_badge` ignores
+//! color-disabled themes — the hard-coded background/foreground start
+//! sequences are emitted whenever `v2_enabled`; only the trailing reset comes
+//! from the (possibly blanked) theme. Do NOT "fix" this: snapshot parity
+//! depends on it.
+
+use crate::runtime_options::UiRuntimeOptions;
+use crate::theme::{UiAccent, UiColorProfile, UiPalette};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiTextTone {
+    Primary,
+    Heading,
+    Accent,
+    Muted,
+    Success,
+    Warning,
+    Danger,
+    Normal,
+}
+
+/// Badge tones — `UiTextTone` minus `Normal`/`Heading` (TS `Exclude<...>`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiBadgeTone {
+    Primary,
+    Accent,
+    Success,
+    Warning,
+    Danger,
+    Muted,
+}
+
+fn tone_color(ui: &UiRuntimeOptions, tone: UiTextTone) -> Option<&str> {
+    let colors = &ui.theme.colors;
+    match tone {
+        UiTextTone::Primary => Some(&colors.primary),
+        UiTextTone::Heading => Some(&colors.heading),
+        UiTextTone::Accent => Some(&colors.accent),
+        UiTextTone::Muted => Some(&colors.muted),
+        UiTextTone::Success => Some(&colors.success),
+        UiTextTone::Warning => Some(&colors.warning),
+        UiTextTone::Danger => Some(&colors.danger),
+        UiTextTone::Normal => None,
+    }
+}
+
+/// `badgeStyleForTone` — hard-coded escape sequences per profile/accent/palette
+/// (start; end is the theme reset).
+fn badge_style_for_tone(ui: &UiRuntimeOptions, tone: UiBadgeTone) -> (&'static str, String) {
+    let end = ui.theme.colors.reset.clone();
+    let is_blue = ui.palette == UiPalette::Blue;
+    let accent = ui.accent;
+    if ui.color_profile == UiColorProfile::Truecolor {
+        let accent_start = match accent {
+            UiAccent::Cyan => "\x1b[48;2;8;89;106m\x1b[38;2;224;242;254m\x1b[1m",
+            UiAccent::Blue => "\x1b[48;2;30;64;175m\x1b[38;2;219;234;254m\x1b[1m",
+            UiAccent::Yellow => "\x1b[48;2;120;53;15m\x1b[38;2;255;247;237m\x1b[1m",
+            UiAccent::Green => "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m",
+        };
+        let success_start = if is_blue {
+            "\x1b[48;2;30;64;175m\x1b[38;2;219;234;254m\x1b[1m"
+        } else {
+            "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m"
+        };
+        let start = match tone {
+            UiBadgeTone::Primary | UiBadgeTone::Accent => accent_start,
+            UiBadgeTone::Success => success_start,
+            UiBadgeTone::Warning => "\x1b[48;2;120;53;15m\x1b[38;2;255;247;237m\x1b[1m",
+            UiBadgeTone::Danger => "\x1b[48;2;127;29;29m\x1b[38;2;254;226;226m\x1b[1m",
+            UiBadgeTone::Muted => "\x1b[48;2;51;65;85m\x1b[38;2;226;232;240m\x1b[1m",
+        };
+        return (start, end);
+    }
+
+    if ui.color_profile == UiColorProfile::Ansi256 {
+        let accent_start = match accent {
+            UiAccent::Cyan => "\x1b[48;5;23m\x1b[38;5;159m\x1b[1m",
+            UiAccent::Blue => "\x1b[48;5;19m\x1b[38;5;153m\x1b[1m",
+            UiAccent::Yellow => "\x1b[48;5;94m\x1b[38;5;230m\x1b[1m",
+            UiAccent::Green => "\x1b[48;5;22m\x1b[38;5;157m\x1b[1m",
+        };
+        let success_start = if is_blue {
+            "\x1b[48;5;19m\x1b[38;5;153m\x1b[1m"
+        } else {
+            "\x1b[48;5;22m\x1b[38;5;157m\x1b[1m"
+        };
+        let start = match tone {
+            UiBadgeTone::Primary | UiBadgeTone::Accent => accent_start,
+            UiBadgeTone::Success => success_start,
+            UiBadgeTone::Warning => "\x1b[48;5;94m\x1b[38;5;230m\x1b[1m",
+            UiBadgeTone::Danger => "\x1b[48;5;88m\x1b[38;5;224m\x1b[1m",
+            UiBadgeTone::Muted => "\x1b[48;5;240m\x1b[38;5;255m\x1b[1m",
+        };
+        return (start, end);
+    }
+
+    let accent_start = match accent {
+        UiAccent::Cyan => "\x1b[46m\x1b[30m\x1b[1m",
+        UiAccent::Blue => "\x1b[44m\x1b[97m\x1b[1m",
+        UiAccent::Yellow => "\x1b[43m\x1b[30m\x1b[1m",
+        UiAccent::Green => "\x1b[42m\x1b[30m\x1b[1m",
+    };
+    let success_start = if is_blue {
+        "\x1b[44m\x1b[97m\x1b[1m"
+    } else {
+        "\x1b[42m\x1b[30m\x1b[1m"
+    };
+    let start = match tone {
+        UiBadgeTone::Primary | UiBadgeTone::Accent => accent_start,
+        UiBadgeTone::Success => success_start,
+        UiBadgeTone::Warning => "\x1b[43m\x1b[30m\x1b[1m",
+        UiBadgeTone::Danger => "\x1b[41m\x1b[97m\x1b[1m",
+        UiBadgeTone::Muted => "\x1b[100m\x1b[97m\x1b[1m",
+    };
+    (start, end)
+}
+
+/// Colorize text according to the theme and tone. If `!ui.v2_enabled` or the
+/// tone maps to no color, the text is returned unchanged.
+pub fn paint_ui_text(ui: &UiRuntimeOptions, text: &str, tone: UiTextTone) -> String {
+    if !ui.v2_enabled {
+        return text.to_string();
+    }
+    match tone_color(ui, tone) {
+        None => text.to_string(),
+        Some(color) => format!("{color}{text}{}", ui.theme.colors.reset),
+    }
+}
+
+pub fn format_ui_header(ui: &UiRuntimeOptions, title: &str) -> Vec<String> {
+    if !ui.v2_enabled {
+        return vec![title.to_string()];
+    }
+    // TS uses `title.length` (UTF-16 code units) for the divider width.
+    let divider = "-".repeat(std::cmp::max(8, title.encode_utf16().count()));
+    vec![
+        paint_ui_text(ui, title, UiTextTone::Heading),
+        paint_ui_text(ui, &divider, UiTextTone::Muted),
+    ]
+}
+
+pub fn format_ui_section(ui: &UiRuntimeOptions, title: &str) -> Vec<String> {
+    if !ui.v2_enabled {
+        return vec![title.to_string()];
+    }
+    vec![paint_ui_text(ui, title, UiTextTone::Accent)]
+}
+
+pub fn format_ui_item(ui: &UiRuntimeOptions, text: &str, tone: UiTextTone) -> String {
+    if !ui.v2_enabled {
+        return format!("- {text}");
+    }
+    let bullet = paint_ui_text(ui, ui.theme.glyphs.bullet, UiTextTone::Muted);
+    format!("{bullet} {}", paint_ui_text(ui, text, tone))
+}
+
+pub fn format_ui_key_value(
+    ui: &UiRuntimeOptions,
+    key: &str,
+    value: &str,
+    value_tone: UiTextTone,
+) -> String {
+    if !ui.v2_enabled {
+        return format!("{key}: {value}");
+    }
+    let key_text = paint_ui_text(ui, &format!("{key}:"), UiTextTone::Muted);
+    let value_text = paint_ui_text(ui, value, value_tone);
+    format!("{key_text} {value_text}")
+}
+
+/// Format a badge label: `[label]`; with tone-specific hard-coded styling when
+/// v2 is enabled (badge styling does NOT honor `disableColor` — bug-compatible,
+/// see module docs).
+pub fn format_ui_badge(ui: &UiRuntimeOptions, label: &str, tone: UiBadgeTone) -> String {
+    let text = format!("[{label}]");
+    if !ui.v2_enabled {
+        return text;
+    }
+    let (start, end) = badge_style_for_tone(ui, tone);
+    format!("{start}{text}{end}")
+}
+
+/// `quotaToneFromLeftPercent`: `<=15` danger, `<=35` warning, else success.
+pub fn quota_tone_from_left_percent(left_percent: f64) -> UiTextTone {
+    if left_percent <= 15.0 {
+        return UiTextTone::Danger;
+    }
+    if left_percent <= 35.0 {
+        return UiTextTone::Warning;
+    }
+    UiTextTone::Success
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::{create_ui_theme, CreateUiThemeOptions, UiGlyphMode};
+
+    // Fixtures ported from test/ui-format.test.ts.
+
+    fn v2_ui() -> UiRuntimeOptions {
+        UiRuntimeOptions {
+            v2_enabled: true,
+            color_profile: UiColorProfile::Truecolor,
+            glyph_mode: UiGlyphMode::Ascii,
+            palette: UiPalette::Green,
+            accent: UiAccent::Green,
+            // Force color on, independent of the test env (ui-04).
+            theme: create_ui_theme(CreateUiThemeOptions {
+                profile: Some(UiColorProfile::Truecolor),
+                glyph_mode: Some(UiGlyphMode::Ascii),
+                disable_color: Some(false),
+                ..Default::default()
+            }),
+        }
+    }
+
+    fn legacy_ui() -> UiRuntimeOptions {
+        UiRuntimeOptions {
+            v2_enabled: false,
+            color_profile: UiColorProfile::Ansi16,
+            glyph_mode: UiGlyphMode::Ascii,
+            palette: UiPalette::Green,
+            accent: UiAccent::Green,
+            theme: create_ui_theme(CreateUiThemeOptions {
+                profile: Some(UiColorProfile::Ansi16),
+                glyph_mode: Some(UiGlyphMode::Ascii),
+                disable_color: Some(true),
+                ..Default::default()
+            }),
+        }
+    }
+
+    #[test]
+    fn returns_plain_text_in_legacy_mode() {
+        let ui = legacy_ui();
+        assert_eq!(paint_ui_text(&ui, "hello", UiTextTone::Accent), "hello");
+        assert_eq!(format_ui_item(&ui, "line", UiTextTone::Normal), "- line");
+        assert_eq!(
+            format_ui_key_value(&ui, "Key", "Value", UiTextTone::Normal),
+            "Key: Value"
+        );
+    }
+
+    #[test]
+    fn returns_styled_text_in_v2_mode() {
+        let ui = v2_ui();
+        let text = paint_ui_text(&ui, "hello", UiTextTone::Accent);
+        assert!(text.contains("hello"));
+        assert!(text.contains("\x1b["));
+    }
+
+    #[test]
+    fn normal_tone_is_unpainted_even_in_v2() {
+        let ui = v2_ui();
+        assert_eq!(paint_ui_text(&ui, "hello", UiTextTone::Normal), "hello");
+    }
+
+    #[test]
+    fn formats_codex_style_headers_and_sections() {
+        let ui = v2_ui();
+        let header = format_ui_header(&ui, "Codex accounts");
+        assert_eq!(header.len(), 2);
+        assert!(header[0].contains("Codex accounts"));
+        // Divider length: max(8, title.length) dashes.
+        assert!(header[1].contains(&"-".repeat("Codex accounts".len())));
+
+        let section = format_ui_section(&ui, "Accounts");
+        assert!(section[0].contains("Accounts"));
+    }
+
+    #[test]
+    fn formats_badges_and_list_items() {
+        let ui = v2_ui();
+        let badge = format_ui_badge(&ui, "ok", UiBadgeTone::Success);
+        assert!(badge.contains("[ok]"));
+
+        let item = format_ui_item(&ui, "1. user@example.com", UiTextTone::Normal);
+        assert!(item.contains("1. user@example.com"));
+        assert!(item.contains(ui.theme.glyphs.bullet));
+    }
+
+    #[test]
+    fn maps_quota_severity_with_traffic_light_thresholds() {
+        assert_eq!(quota_tone_from_left_percent(70.0), UiTextTone::Success);
+        assert_eq!(quota_tone_from_left_percent(35.0), UiTextTone::Warning);
+        assert_eq!(quota_tone_from_left_percent(16.0), UiTextTone::Warning);
+        assert_eq!(quota_tone_from_left_percent(15.0), UiTextTone::Danger);
+        assert_eq!(quota_tone_from_left_percent(0.0), UiTextTone::Danger);
+    }
+
+    #[test]
+    fn badge_exact_sequences_truecolor_green() {
+        let ui = v2_ui();
+        assert_eq!(
+            format_ui_badge(&ui, "active", UiBadgeTone::Success),
+            "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m[active]\x1b[0m"
+        );
+        assert_eq!(
+            format_ui_badge(&ui, "error", UiBadgeTone::Danger),
+            "\x1b[48;2;127;29;29m\x1b[38;2;254;226;226m\x1b[1m[error]\x1b[0m"
+        );
+    }
+
+    #[test]
+    fn badge_ignores_color_disabled_theme_bug_compatible() {
+        // NO_COLOR bug (spec 12 gotcha 8): the badge start sequences are
+        // hard-coded and emitted whenever v2 is enabled; only the trailing
+        // reset comes from the blanked theme.
+        let mut ui = v2_ui();
+        ui.theme = create_ui_theme(CreateUiThemeOptions {
+            profile: Some(UiColorProfile::Truecolor),
+            glyph_mode: Some(UiGlyphMode::Ascii),
+            disable_color: Some(true),
+            ..Default::default()
+        });
+        let badge = format_ui_badge(&ui, "ok", UiBadgeTone::Success);
+        assert_eq!(
+            badge,
+            "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m[ok]"
+        );
+        // Regular painted text IS blanked by the disabled theme.
+        assert_eq!(paint_ui_text(&ui, "ok", UiTextTone::Success), "ok");
+    }
+
+    #[test]
+    fn badge_blue_palette_success_uses_blue_variant() {
+        let mut ui = v2_ui();
+        ui.palette = UiPalette::Blue;
+        assert_eq!(
+            format_ui_badge(&ui, "ok", UiBadgeTone::Success),
+            "\x1b[48;2;30;64;175m\x1b[38;2;219;234;254m\x1b[1m[ok]\x1b[0m"
+        );
+    }
+
+    #[test]
+    fn badge_ansi16_accent_variants() {
+        let mut ui = v2_ui();
+        ui.color_profile = UiColorProfile::Ansi16;
+        ui.accent = UiAccent::Cyan;
+        assert_eq!(
+            format_ui_badge(&ui, "x", UiBadgeTone::Accent),
+            "\x1b[46m\x1b[30m\x1b[1m[x]\x1b[0m"
+        );
+        ui.accent = UiAccent::Yellow;
+        assert_eq!(
+            format_ui_badge(&ui, "x", UiBadgeTone::Primary),
+            "\x1b[43m\x1b[30m\x1b[1m[x]\x1b[0m"
+        );
+        assert_eq!(
+            format_ui_badge(&ui, "x", UiBadgeTone::Muted),
+            "\x1b[100m\x1b[97m\x1b[1m[x]\x1b[0m"
+        );
+    }
+}
diff --git a/crates/tui/src/lib.rs b/crates/tui/src/lib.rs
new file mode 100644
index 000000000..2861a32c0
--- /dev/null
+++ b/crates/tui/src/lib.rs
@@ -0,0 +1,11 @@
+//! cma-tui - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod ansi;
+pub mod auth_menu;
+pub mod auth_menu_builder;
+pub mod confirm;
+pub mod format;
+pub mod login_prompts;
+pub mod runtime_options;
+pub mod select;
+pub mod theme;
+pub mod ui_copy;
diff --git a/crates/tui/src/login_prompts.rs b/crates/tui/src/login_prompts.rs
new file mode 100644
index 000000000..08573323c
--- /dev/null
+++ b/crates/tui/src/login_prompts.rs
@@ -0,0 +1,587 @@
+//! Port of `lib/cli.ts` — readline/TUI prompts for the `login` command
+//! (mode menu, workspace selection, non-interactive detection).
+//!
+//! Contracts preserved (spec 07 §11 + gotcha 20):
+//! - non-interactive `prompt_login_mode` always returns `add`; non-interactive
+//!   `prompt_account_selection` silently picks the default index;
+//! - the plain-readline fallback "fresh" path skips the typed confirmation,
+//!   while the TUI path requires typing `DELETE` exactly;
+//! - `FORCE_INTERACTIVE_MODE=1` overrides every non-interactive signal.
+
+use std::io::{BufRead, IsTerminal, Write};
+
+pub use crate::ansi::is_tty;
+pub use crate::auth_menu_builder::AccountStatus;
+use crate::auth_menu::{show_account_details, show_auth_menu};
+use crate::auth_menu_builder::{AccountAction, AccountInfo, AuthMenuAction, AuthMenuOptions};
+use crate::select::SelectError;
+use crate::ui_copy;
+use cma_core::schemas::account_storage::AccountIdSource;
+
+/// TS `ExistingAccountInfo` — same field set as the dashboard payload.
+pub type ExistingAccountInfo = AccountInfo;
+
+/// TS `LoginMenuOptions` — same shape as the dashboard options.
+pub type LoginMenuOptions<'a> = AuthMenuOptions<'a>;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Default)]
+pub enum LoginMode {
+    Add,
+    Forecast,
+    Fix,
+    Settings,
+    Fresh,
+    Manage,
+    Check,
+    DeepCheck,
+    VerifyFlagged,
+    #[default]
+    Cancel,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct LoginMenuResult {
+    pub mode: LoginModeField,
+    pub delete_account_index: Option<i64>,
+    pub refresh_account_index: Option<i64>,
+    pub toggle_account_index: Option<i64>,
+    pub switch_account_index: Option<i64>,
+    pub delete_all: bool,
+}
+
+// `LoginMenuResult.mode` is required in TS; default only exists so struct
+// update syntax stays ergonomic.
+pub type LoginModeField = LoginMode;
+
+
+impl LoginMenuResult {
+    pub fn mode(mode: LoginMode) -> Self {
+        LoginMenuResult {
+            mode,
+            ..Default::default()
+        }
+    }
+}
+
+/// Testable core of [`is_non_interactive_mode`].
+pub(crate) fn is_non_interactive_mode_from(
+    env: &dyn Fn(&str) -> Option<String>,
+    stdin_tty: bool,
+    stdout_tty: bool,
+) -> bool {
+    if env("FORCE_INTERACTIVE_MODE").as_deref() == Some("1") {
+        return false;
+    }
+    if !stdin_tty || !stdout_tty {
+        return true;
+    }
+    if env("CODEX_TUI").as_deref() == Some("1") {
+        return true;
+    }
+    if env("CODEX_DESKTOP").as_deref() == Some("1") {
+        return true;
+    }
+    if env("TERM_PROGRAM").unwrap_or_default().trim().to_lowercase() == "codex" {
+        return true;
+    }
+    if env("ELECTRON_RUN_AS_NODE").as_deref() == Some("1") {
+        return true;
+    }
+    false
+}
+
+/// Detect host Desktop/TUI mode where readline prompts don't work (the host
+/// owns stdio there).
+pub fn is_non_interactive_mode() -> bool {
+    is_non_interactive_mode_from(
+        &|key| std::env::var(key).ok(),
+        std::io::stdin().is_terminal(),
+        std::io::stdout().is_terminal(),
+    )
+}
+
+/// `rl.question(...)` analogue: print the prompt without a newline, read one
+/// line. EOF/read failure yields an empty answer.
+fn question(prompt: &str) -> String {
+    let mut stdout = std::io::stdout();
+    let _ = write!(stdout, "{prompt}");
+    let _ = stdout.flush();
+    let mut answer = String::new();
+    let _ = std::io::stdin().lock().read_line(&mut answer);
+    answer.trim_end_matches(['\r', '\n']).to_string()
+}
+
+/// `promptAddAnotherAccount` — non-interactive → `false`; else prints the tip
+/// and asks `Add another account? (N added) (y/n): `.
+pub fn prompt_add_another_account(current_count: i64) -> bool {
+    if is_non_interactive_mode() {
+        return false;
+    }
+    println!("\n{}\n", ui_copy::fallback::ADD_ANOTHER_TIP);
+    let answer = question(&ui_copy::fallback::add_another_question(current_count));
+    let normalized = answer.trim().to_lowercase();
+    normalized == "y" || normalized == "yes"
+}
+
+/// `formatAccountLabel` — `"<n>. <label> (<email>)"` | `"<n>. <email>"` |
+/// `"<n>. <label>"` | `"<n>. <last-6-of-accountId>"` | `"<n>. Account"`.
+pub(crate) fn format_account_label(account: &ExistingAccountInfo, index: i64) -> String {
+    let num = index + 1;
+    let label = account
+        .account_label
+        .as_deref()
+        .map(str::trim)
+        .filter(|l| !l.is_empty());
+    if let Some(email) = account.email.as_deref()
+        && !email.trim().is_empty() {
+            return match label {
+                Some(label) => format!("{num}. {label} ({email})"),
+                None => format!("{num}. {email}"),
+            };
+        }
+    if let Some(label) = label {
+        return format!("{num}. {label}");
+    }
+    if let Some(account_id) = account.account_id.as_deref()
+        && !account_id.trim().is_empty() {
+            let chars: Vec<char> = account_id.chars().collect();
+            let suffix: String = if chars.len() > 6 {
+                chars[chars.len() - 6..].iter().collect()
+            } else {
+                account_id.to_string()
+            };
+            return format!("{num}. {suffix}");
+        }
+    format!("{num}. Account")
+}
+
+/// `resolveAccountSourceIndex` — prefer finite `source_index` (floored, min 0),
+/// else `index`, else `-1`.
+pub(crate) fn resolve_account_source_index(account: &ExistingAccountInfo) -> i64 {
+    if let Some(source_index) = account.source_index {
+        return source_index.max(0);
+    }
+    account.index.max(0)
+}
+
+fn warn_unresolvable_account_selection(account: &ExistingAccountInfo) {
+    let label = account
+        .email
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(str::to_string)
+        .or_else(|| {
+            account
+                .account_id
+                .as_deref()
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .map(str::to_string)
+        })
+        .unwrap_or_else(|| format!("index {}", account.index + 1));
+    println!("Unable to resolve saved account for action: {label}");
+}
+
+fn prompt_delete_all_typed_confirm() -> bool {
+    let answer = question("Type DELETE to remove all saved accounts: ");
+    answer.trim() == "DELETE"
+}
+
+/// Pure classification of one fallback-menu answer. `None` = invalid input
+/// (the caller prints the invalid-mode message and re-prompts).
+pub(crate) fn classify_fallback_mode_input(answer: &str) -> Option<LoginMenuResult> {
+    let normalized = answer.trim().to_lowercase();
+    match normalized.as_str() {
+        "a" | "add" => Some(LoginMenuResult::mode(LoginMode::Add)),
+        "b" | "p" | "forecast" => Some(LoginMenuResult::mode(LoginMode::Forecast)),
+        "x" | "fix" => Some(LoginMenuResult::mode(LoginMode::Fix)),
+        "s" | "settings" | "configure" => Some(LoginMenuResult::mode(LoginMode::Settings)),
+        // NOTE: no typed DELETE confirm on the fallback path (gotcha 20).
+        "f" | "fresh" | "clear" => Some(LoginMenuResult {
+            mode: LoginMode::Fresh,
+            delete_all: true,
+            ..Default::default()
+        }),
+        "c" | "check" => Some(LoginMenuResult::mode(LoginMode::Check)),
+        "d" | "deep" => Some(LoginMenuResult::mode(LoginMode::DeepCheck)),
+        "g" | "flagged" | "verify-flagged" | "verify" => {
+            Some(LoginMenuResult::mode(LoginMode::VerifyFlagged))
+        }
+        "q" | "quit" => Some(LoginMenuResult::mode(LoginMode::Cancel)),
+        _ => None,
+    }
+}
+
+fn prompt_login_mode_fallback(existing_accounts: &[ExistingAccountInfo]) -> LoginMenuResult {
+    if !existing_accounts.is_empty() {
+        println!("\n{} account(s) saved:", existing_accounts.len());
+        for account in existing_accounts {
+            println!("  {}", format_account_label(account, account.index));
+        }
+        println!();
+    }
+
+    loop {
+        let answer = question(ui_copy::fallback::SELECT_MODE_PROMPT);
+        if let Some(result) = classify_fallback_mode_input(&answer) {
+            return result;
+        }
+        println!("{}", ui_copy::fallback::INVALID_MODE_PROMPT);
+    }
+}
+
+fn manage_result(account: &ExistingAccountInfo, action: AccountAction) -> Option<LoginMenuResult> {
+    let index = resolve_account_source_index(account);
+    if index < 0 {
+        warn_unresolvable_account_selection(account);
+        return None;
+    }
+    let mut result = LoginMenuResult::mode(LoginMode::Manage);
+    match action {
+        AccountAction::Delete => result.delete_account_index = Some(index),
+        AccountAction::SetCurrent => result.switch_account_index = Some(index),
+        AccountAction::Refresh => result.refresh_account_index = Some(index),
+        AccountAction::Toggle => result.toggle_account_index = Some(index),
+        AccountAction::Back | AccountAction::Cancel => return None,
+    }
+    Some(result)
+}
+
+/// `promptLoginMode` — headless → `add`; interactive-but-not-TTY → readline
+/// fallback menu; full TTY → dashboard TUI loop.
+pub fn prompt_login_mode(
+    existing_accounts: &[ExistingAccountInfo],
+    options: &LoginMenuOptions<'_>,
+) -> Result<LoginMenuResult, SelectError> {
+    if is_non_interactive_mode() {
+        return Ok(LoginMenuResult::mode(LoginMode::Add));
+    }
+
+    if !is_tty() {
+        return Ok(prompt_login_mode_fallback(existing_accounts));
+    }
+
+    loop {
+        let action = show_auth_menu(existing_accounts, options)?;
+
+        match action {
+            AuthMenuAction::Add => return Ok(LoginMenuResult::mode(LoginMode::Add)),
+            AuthMenuAction::Forecast => return Ok(LoginMenuResult::mode(LoginMode::Forecast)),
+            AuthMenuAction::Fix => return Ok(LoginMenuResult::mode(LoginMode::Fix)),
+            AuthMenuAction::Settings => return Ok(LoginMenuResult::mode(LoginMode::Settings)),
+            AuthMenuAction::Fresh | AuthMenuAction::DeleteAll => {
+                if !prompt_delete_all_typed_confirm() {
+                    println!("\nDelete all cancelled.\n");
+                    continue;
+                }
+                return Ok(LoginMenuResult {
+                    mode: LoginMode::Fresh,
+                    delete_all: true,
+                    ..Default::default()
+                });
+            }
+            AuthMenuAction::Check => return Ok(LoginMenuResult::mode(LoginMode::Check)),
+            AuthMenuAction::DeepCheck => return Ok(LoginMenuResult::mode(LoginMode::DeepCheck)),
+            AuthMenuAction::VerifyFlagged => {
+                return Ok(LoginMenuResult::mode(LoginMode::VerifyFlagged));
+            }
+            AuthMenuAction::SelectAccount(account) => {
+                let account_action = show_account_details(&account)?;
+                match account_action {
+                    AccountAction::Delete
+                    | AccountAction::SetCurrent
+                    | AccountAction::Refresh
+                    | AccountAction::Toggle => {
+                        if let Some(result) = manage_result(&account, account_action) {
+                            return Ok(result);
+                        }
+                        continue;
+                    }
+                    _ => continue,
+                }
+            }
+            AuthMenuAction::SetCurrentAccount(account) => {
+                if let Some(result) = manage_result(&account, AccountAction::SetCurrent) {
+                    return Ok(result);
+                }
+                continue;
+            }
+            AuthMenuAction::RefreshAccount(account) => {
+                if let Some(result) = manage_result(&account, AccountAction::Refresh) {
+                    return Ok(result);
+                }
+                continue;
+            }
+            AuthMenuAction::ToggleAccount(account) => {
+                if let Some(result) = manage_result(&account, AccountAction::Toggle) {
+                    return Ok(result);
+                }
+                continue;
+            }
+            AuthMenuAction::DeleteAccount(account) => {
+                if let Some(result) = manage_result(&account, AccountAction::Delete) {
+                    return Ok(result);
+                }
+                continue;
+            }
+            // Search is handled in show_auth_menu; keep the main loop active.
+            AuthMenuAction::Search => continue,
+            AuthMenuAction::Cancel => return Ok(LoginMenuResult::mode(LoginMode::Cancel)),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountSelectionCandidate {
+    pub account_id: String,
+    pub label: String,
+    pub source: Option<AccountIdSource>,
+    pub is_default: bool,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct AccountSelectionOptions {
+    pub default_index: Option<i64>,
+    pub title: Option<String>,
+}
+
+/// `promptAccountSelection` — workspace picker. Empty list → `None`;
+/// non-interactive → the default candidate without prompting.
+pub fn prompt_account_selection(
+    candidates: &[AccountSelectionCandidate],
+    options: &AccountSelectionOptions,
+) -> Option<AccountSelectionCandidate> {
+    if candidates.is_empty() {
+        return None;
+    }
+    let default_index = options
+        .default_index
+        .map(|i| i.clamp(0, candidates.len() as i64 - 1) as usize)
+        .unwrap_or(0);
+
+    if is_non_interactive_mode() {
+        return candidates
+            .get(default_index)
+            .or_else(|| candidates.first())
+            .cloned();
+    }
+
+    println!(
+        "\n{}",
+        options
+            .title
+            .as_deref()
+            .unwrap_or("Multiple workspaces detected for this account:")
+    );
+    for (index, candidate) in candidates.iter().enumerate() {
+        let is_default = if candidate.is_default { " (default)" } else { "" };
+        println!("  {}. {}{is_default}", index + 1, candidate.label);
+    }
+    println!();
+
+    loop {
+        let answer = question(&format!("Select workspace [{}]: ", default_index + 1));
+        let normalized = answer.trim().to_lowercase();
+        if normalized.is_empty() || normalized == "q" || normalized == "quit" {
+            return candidates
+                .get(default_index)
+                .or_else(|| candidates.first())
+                .cloned();
+        }
+        if let Some(parsed) = crate::auth_menu_builder::parse_int_prefix(&normalized) {
+            let idx = parsed - 1;
+            if idx >= 0 && (idx as usize) < candidates.len() {
+                return candidates.get(idx as usize).cloned();
+            }
+        }
+        println!("Please enter a number between 1 and {}.", candidates.len());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    fn env_from(pairs: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> + use<> {
+        let map: HashMap<String, String> = pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect();
+        move |key: &str| map.get(key).cloned()
+    }
+
+    // ---- isNonInteractiveMode (spec 07 §11) ----
+
+    #[test]
+    fn force_interactive_mode_overrides_everything() {
+        let env = env_from(&[("FORCE_INTERACTIVE_MODE", "1"), ("CODEX_TUI", "1")]);
+        assert!(!is_non_interactive_mode_from(&env, false, false));
+    }
+
+    #[test]
+    fn non_tty_streams_are_non_interactive() {
+        let env = env_from(&[]);
+        assert!(is_non_interactive_mode_from(&env, false, true));
+        assert!(is_non_interactive_mode_from(&env, true, false));
+        assert!(!is_non_interactive_mode_from(&env, true, true));
+    }
+
+    #[test]
+    fn host_env_markers_force_non_interactive() {
+        for var in ["CODEX_TUI", "CODEX_DESKTOP", "ELECTRON_RUN_AS_NODE"] {
+            let env = env_from(&[(var, "1")]);
+            assert!(is_non_interactive_mode_from(&env, true, true), "{var}");
+            // Only the literal "1" triggers.
+            let env = env_from(&[(var, "true")]);
+            assert!(!is_non_interactive_mode_from(&env, true, true), "{var}");
+        }
+    }
+
+    #[test]
+    fn term_program_codex_is_case_insensitive_and_trimmed() {
+        let env = env_from(&[("TERM_PROGRAM", "  Codex  ")]);
+        assert!(is_non_interactive_mode_from(&env, true, true));
+        let env = env_from(&[("TERM_PROGRAM", "vscode")]);
+        assert!(!is_non_interactive_mode_from(&env, true, true));
+    }
+
+    // ---- formatAccountLabel ----
+
+    fn acct(overrides: impl FnOnce(&mut ExistingAccountInfo)) -> ExistingAccountInfo {
+        let mut info = ExistingAccountInfo {
+            index: 0,
+            ..Default::default()
+        };
+        overrides(&mut info);
+        info
+    }
+
+    #[test]
+    fn formats_account_labels_by_priority() {
+        assert_eq!(
+            format_account_label(
+                &acct(|a| {
+                    a.account_label = Some("Team".into());
+                    a.email = Some("a@b.c".into());
+                }),
+                0
+            ),
+            "1. Team (a@b.c)"
+        );
+        assert_eq!(
+            format_account_label(&acct(|a| a.email = Some("a@b.c".into())), 1),
+            "2. a@b.c"
+        );
+        assert_eq!(
+            format_account_label(&acct(|a| a.account_label = Some("Team".into())), 0),
+            "1. Team"
+        );
+        assert_eq!(
+            format_account_label(&acct(|a| a.account_id = Some("acc_1234567890".into())), 0),
+            "1. 567890"
+        );
+        assert_eq!(
+            format_account_label(&acct(|a| a.account_id = Some("abc".into())), 0),
+            "1. abc"
+        );
+        assert_eq!(format_account_label(&acct(|_| {}), 2), "3. Account");
+    }
+
+    // ---- resolveAccountSourceIndex ----
+
+    #[test]
+    fn resolves_source_index_with_floor_at_zero() {
+        assert_eq!(
+            resolve_account_source_index(&acct(|a| a.source_index = Some(5))),
+            5
+        );
+        assert_eq!(
+            resolve_account_source_index(&acct(|a| a.source_index = Some(-3))),
+            0
+        );
+        assert_eq!(resolve_account_source_index(&acct(|a| a.index = 4)), 4);
+        assert_eq!(resolve_account_source_index(&acct(|a| a.index = -2)), 0);
+    }
+
+    // ---- fallback mode classification (spec 07 §11 mapping) ----
+
+    #[test]
+    fn classifies_every_fallback_mode_token() {
+        let cases: Vec<(&str, LoginMode)> = vec![
+            ("a", LoginMode::Add),
+            ("add", LoginMode::Add),
+            ("b", LoginMode::Forecast),
+            ("p", LoginMode::Forecast),
+            ("forecast", LoginMode::Forecast),
+            ("x", LoginMode::Fix),
+            ("fix", LoginMode::Fix),
+            ("s", LoginMode::Settings),
+            ("settings", LoginMode::Settings),
+            ("configure", LoginMode::Settings),
+            ("c", LoginMode::Check),
+            ("check", LoginMode::Check),
+            ("d", LoginMode::DeepCheck),
+            ("deep", LoginMode::DeepCheck),
+            ("g", LoginMode::VerifyFlagged),
+            ("flagged", LoginMode::VerifyFlagged),
+            ("verify-flagged", LoginMode::VerifyFlagged),
+            ("verify", LoginMode::VerifyFlagged),
+            ("q", LoginMode::Cancel),
+            ("quit", LoginMode::Cancel),
+        ];
+        for (token, expected) in cases {
+            let result = classify_fallback_mode_input(token).unwrap_or_else(|| {
+                panic!("token {token:?} should classify");
+            });
+            assert_eq!(result.mode, expected, "token {token:?}");
+            assert!(!result.delete_all);
+        }
+        // Trim + case-insensitive.
+        assert_eq!(
+            classify_fallback_mode_input("  ADD  ").unwrap().mode,
+            LoginMode::Add
+        );
+    }
+
+    #[test]
+    fn fallback_fresh_sets_delete_all_without_typed_confirm() {
+        for token in ["f", "fresh", "clear"] {
+            let result = classify_fallback_mode_input(token).unwrap();
+            assert_eq!(result.mode, LoginMode::Fresh);
+            assert!(result.delete_all);
+        }
+    }
+
+    #[test]
+    fn invalid_fallback_tokens_are_rejected() {
+        assert!(classify_fallback_mode_input("z").is_none());
+        assert!(classify_fallback_mode_input("").is_none());
+        assert!(classify_fallback_mode_input("delete").is_none());
+    }
+
+    // ---- manage_result index shaping ----
+
+    #[test]
+    fn manage_result_maps_actions_to_index_fields() {
+        let account = acct(|a| {
+            a.index = 1;
+            a.source_index = Some(7);
+        });
+        let delete = manage_result(&account, AccountAction::Delete).unwrap();
+        assert_eq!(delete.mode, LoginMode::Manage);
+        assert_eq!(delete.delete_account_index, Some(7));
+        assert_eq!(delete.switch_account_index, None);
+
+        let switch = manage_result(&account, AccountAction::SetCurrent).unwrap();
+        assert_eq!(switch.switch_account_index, Some(7));
+
+        let refresh = manage_result(&account, AccountAction::Refresh).unwrap();
+        assert_eq!(refresh.refresh_account_index, Some(7));
+
+        let toggle = manage_result(&account, AccountAction::Toggle).unwrap();
+        assert_eq!(toggle.toggle_account_index, Some(7));
+    }
+}
diff --git a/crates/tui/src/runtime_options.rs b/crates/tui/src/runtime_options.rs
new file mode 100644
index 000000000..656b1acd0
--- /dev/null
+++ b/crates/tui/src/runtime_options.rs
@@ -0,0 +1,170 @@
+//! Port of `lib/ui/runtime.ts` — process-global mutable UI runtime options.
+//!
+//! The TS default `theme` was computed once at module load (sampling
+//! NO_COLOR/FORCE_COLOR/TTY exactly once); we preserve "evaluated once"
+//! semantics with a `LazyLock` (spec 12 §4). `set_ui_runtime_options` rebuilds
+//! the theme via `create_ui_theme`, which re-evaluates `should_disable_color`
+//! live.
+
+use std::sync::{LazyLock, RwLock};
+
+use crate::theme::{
+    create_ui_theme, CreateUiThemeOptions, UiAccent, UiColorProfile, UiGlyphMode, UiPalette,
+    UiTheme,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UiRuntimeOptions {
+    pub v2_enabled: bool,
+    pub color_profile: UiColorProfile,
+    pub glyph_mode: UiGlyphMode,
+    pub palette: UiPalette,
+    pub accent: UiAccent,
+    pub theme: UiTheme,
+}
+
+/// Partial update for [`set_ui_runtime_options`] (`Partial<Omit<..,"theme">>`).
+#[derive(Debug, Clone, Copy, Default)]
+pub struct UiRuntimeOptionsPatch {
+    pub v2_enabled: Option<bool>,
+    pub color_profile: Option<UiColorProfile>,
+    pub glyph_mode: Option<UiGlyphMode>,
+    pub palette: Option<UiPalette>,
+    pub accent: Option<UiAccent>,
+}
+
+/// The default theme instance, computed exactly once per process (mirrors the
+/// TS module-load-time evaluation of `shouldDisableColor()`).
+static DEFAULT_THEME: LazyLock<UiTheme> = LazyLock::new(|| {
+    create_ui_theme(CreateUiThemeOptions {
+        profile: Some(UiColorProfile::Truecolor),
+        glyph_mode: Some(UiGlyphMode::Ascii),
+        palette: Some(UiPalette::Green),
+        accent: Some(UiAccent::Green),
+        disable_color: None,
+    })
+});
+
+fn default_options() -> UiRuntimeOptions {
+    UiRuntimeOptions {
+        v2_enabled: true,
+        color_profile: UiColorProfile::Truecolor,
+        glyph_mode: UiGlyphMode::Ascii,
+        palette: UiPalette::Green,
+        accent: UiAccent::Green,
+        theme: DEFAULT_THEME.clone(),
+    }
+}
+
+static RUNTIME_OPTIONS: LazyLock<RwLock<UiRuntimeOptions>> =
+    LazyLock::new(|| RwLock::new(default_options()));
+
+/// Update UI runtime options and recompute the derived theme. Unspecified
+/// fields keep their current values. Returns the resolved options.
+pub fn set_ui_runtime_options(options: UiRuntimeOptionsPatch) -> UiRuntimeOptions {
+    let mut guard = RUNTIME_OPTIONS
+        .write()
+        .unwrap_or_else(|poison| poison.into_inner());
+    let v2_enabled = options.v2_enabled.unwrap_or(guard.v2_enabled);
+    let color_profile = options.color_profile.unwrap_or(guard.color_profile);
+    let glyph_mode = options.glyph_mode.unwrap_or(guard.glyph_mode);
+    let palette = options.palette.unwrap_or(guard.palette);
+    let accent = options.accent.unwrap_or(guard.accent);
+    *guard = UiRuntimeOptions {
+        v2_enabled,
+        color_profile,
+        glyph_mode,
+        palette,
+        accent,
+        // Re-evaluates should_disable_color() live, unlike the default theme.
+        theme: create_ui_theme(CreateUiThemeOptions {
+            profile: Some(color_profile),
+            glyph_mode: Some(glyph_mode),
+            palette: Some(palette),
+            accent: Some(accent),
+            disable_color: None,
+        }),
+    };
+    guard.clone()
+}
+
+/// Returns the current UI runtime options (a clone of the live global; each
+/// call observes the latest state, matching the TS live-object semantics).
+pub fn get_ui_runtime_options() -> UiRuntimeOptions {
+    RUNTIME_OPTIONS
+        .read()
+        .unwrap_or_else(|poison| poison.into_inner())
+        .clone()
+}
+
+/// Reset the UI runtime options to the default configuration (the theme is the
+/// original default theme instance, NOT re-evaluated).
+pub fn reset_ui_runtime_options() -> UiRuntimeOptions {
+    let mut guard = RUNTIME_OPTIONS
+        .write()
+        .unwrap_or_else(|poison| poison.into_inner());
+    *guard = default_options();
+    guard.clone()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    // Ported from test/ui-runtime.test.ts behaviors. These mutate the process
+    // global, so they are serialized.
+
+    #[test]
+    #[serial]
+    fn defaults_are_v2_truecolor_ascii_green() {
+        reset_ui_runtime_options();
+        let options = get_ui_runtime_options();
+        assert!(options.v2_enabled);
+        assert_eq!(options.color_profile, UiColorProfile::Truecolor);
+        assert_eq!(options.glyph_mode, UiGlyphMode::Ascii);
+        assert_eq!(options.palette, UiPalette::Green);
+        assert_eq!(options.accent, UiAccent::Green);
+        assert_eq!(options.theme.profile, UiColorProfile::Truecolor);
+    }
+
+    #[test]
+    #[serial]
+    fn set_merges_fields_and_rebuilds_theme() {
+        reset_ui_runtime_options();
+        let updated = set_ui_runtime_options(UiRuntimeOptionsPatch {
+            color_profile: Some(UiColorProfile::Ansi256),
+            glyph_mode: Some(UiGlyphMode::Unicode),
+            ..Default::default()
+        });
+        // Unspecified fields kept their current values.
+        assert!(updated.v2_enabled);
+        assert_eq!(updated.palette, UiPalette::Green);
+        // Theme rebuilt from the merged fields.
+        assert_eq!(updated.color_profile, UiColorProfile::Ansi256);
+        assert_eq!(updated.theme.profile, UiColorProfile::Ansi256);
+        assert_eq!(updated.theme.glyph_mode, UiGlyphMode::Unicode);
+        assert_eq!(updated.theme.glyphs.selected, "\u{25c6}");
+        // The getter observes the update.
+        assert_eq!(
+            get_ui_runtime_options().color_profile,
+            UiColorProfile::Ansi256
+        );
+        reset_ui_runtime_options();
+    }
+
+    #[test]
+    #[serial]
+    fn reset_restores_defaults() {
+        set_ui_runtime_options(UiRuntimeOptionsPatch {
+            v2_enabled: Some(false),
+            palette: Some(UiPalette::Blue),
+            ..Default::default()
+        });
+        let restored = reset_ui_runtime_options();
+        assert!(restored.v2_enabled);
+        assert_eq!(restored.palette, UiPalette::Green);
+        // The restored theme is the original default instance's value.
+        assert_eq!(restored.theme, DEFAULT_THEME.clone());
+    }
+}
diff --git a/crates/tui/src/select.rs b/crates/tui/src/select.rs
new file mode 100644
index 000000000..83935fae6
--- /dev/null
+++ b/crates/tui/src/select.rs
@@ -0,0 +1,1474 @@
+//! Port of `lib/ui/select.ts` — the interactive single-select TUI menu engine.
+//!
+//! A hand-rolled inline (non-alt-screen) raw-mode renderer over crossterm
+//! (ARCHITECTURE §5.3). Contracts preserved from TS (spec 12 §6 + gotchas):
+//! - exactly ONE selectable item => its value is returned immediately with no
+//!   terminal interaction;
+//! - 120 ms input-suppression guard after open (drops enter/escape only);
+//! - bare-ESC vs escape-sequence disambiguation with a 50 ms timer;
+//! - Ctrl-C in raw mode is "escape" (cancel), not a signal;
+//! - `on_input` finishing condition: `Finish(None)` cancels, `Ignored`
+//!   continues;
+//! - `truncate_ansi` appends `\x1b[0m` after the `...` suffix only when the
+//!   kept prefix contains an ESC (ui-01);
+//! - cleanup tears down timers/listeners BEFORE restoring the terminal mode,
+//!   each step individually guarded, and the cursor is always re-shown;
+//! - external SIGINT/SIGTERM during the menu cancels WITH terminal
+//!   restoration (unix, [`menu_signals`]) — TS `process.once(signal,
+//!   () => finish(null))` — instead of dying with raw mode on and the
+//!   cursor hidden.
+//!
+//! Accepted loss vs TS (R-deviation): VT application-keypad hotkeys
+//! (`ESC O p`..`ESC O y` → '0'-'9' etc., DECKPAM mode) do NOT reach the live
+//! loop on unix — crossterm's parser only understands `ESC O` for
+//! A/B/C/D/H/F/P-S and discards the rest, and it never surfaces raw bytes.
+//! TS decoded them in `decodeHotkeyInput`; the pure decoder is kept below
+//! ([`decode_hotkey_input`]) for parity tests and for a future raw-stdin
+//! reader, but numpad digits in application-keypad mode are currently
+//! ignored by [`select`]. (NumLock-normal mode and the Windows console are
+//! unaffected.)
+//!
+//! Rendering is split into the pure [`render_select_frame`] (exact-string
+//! testable) and the thin stdout writer used by [`select`].
+
+use std::io::Write;
+use std::time::{Duration, Instant};
+
+use cma_core::display_width::display_width;
+use crossterm::event::{Event, KeyCode, KeyEventKind, KeyModifiers};
+
+use crate::ansi;
+use crate::ansi::KeyAction;
+use crate::theme::UiTheme;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MenuColor {
+    Red,
+    Green,
+    Yellow,
+    Cyan,
+}
+
+/// TS `MenuItem<T>`; `kind: "heading"` becomes the `heading` flag.
+#[derive(Debug, Clone)]
+pub struct MenuItem<T> {
+    pub label: String,
+    pub selected_label: Option<String>,
+    pub value: T,
+    pub hint: Option<String>,
+    pub disabled: bool,
+    pub hide_unavailable_suffix: bool,
+    pub separator: bool,
+    pub heading: bool,
+    pub color: Option<MenuColor>,
+}
+
+impl<T> MenuItem<T> {
+    pub fn new(label: impl Into<String>, value: T) -> Self {
+        MenuItem {
+            label: label.into(),
+            selected_label: None,
+            value,
+            hint: None,
+            disabled: false,
+            hide_unavailable_suffix: false,
+            separator: false,
+            heading: false,
+            color: None,
+        }
+    }
+
+    pub fn separator(value: T) -> Self {
+        let mut item = MenuItem::new("", value);
+        item.separator = true;
+        item
+    }
+
+    pub fn heading(label: impl Into<String>, value: T) -> Self {
+        let mut item = MenuItem::new(label, value);
+        item.heading = true;
+        item
+    }
+
+    pub fn with_color(mut self, color: MenuColor) -> Self {
+        self.color = Some(color);
+        self
+    }
+
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SelectedEmphasis {
+    Chip,
+    Minimal,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum FocusStyle {
+    #[default]
+    RowInvert,
+    Chip,
+}
+
+/// Result of an `on_input` callback (TS `T | null | undefined`):
+/// `Ignored` = `undefined` (continue), `Finish(None)` = `null` (cancel),
+/// `Finish(Some(v))` = finish with `v`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SelectInputResult<T> {
+    Ignored,
+    Finish(Option<T>),
+}
+
+/// Context passed to `on_input` / `on_cursor_change` callbacks.
+pub struct SelectContext<'i, T> {
+    pub cursor: usize,
+    pub items: &'i [MenuItem<T>],
+    rerender_requested: &'i mut bool,
+}
+
+impl<T> SelectContext<'_, T> {
+    pub fn request_rerender(&mut self) {
+        *self.rerender_requested = true;
+    }
+}
+
+pub type OnCursorChange<'cb, T> = Box<dyn FnMut(&mut SelectContext<'_, T>) + 'cb>;
+pub type OnInput<'cb, T> =
+    Box<dyn FnMut(&str, &mut SelectContext<'_, T>) -> SelectInputResult<T> + 'cb>;
+
+/// TS `SelectOptions<T>`. `selected_emphasis` is accepted but never read by the
+/// render code (API compatibility only) — only `focus_style` matters.
+pub struct SelectOptions<'cb, T> {
+    pub message: String,
+    pub subtitle: Option<String>,
+    pub dynamic_subtitle: Option<Box<dyn Fn() -> Option<String> + 'cb>>,
+    pub help: Option<String>,
+    pub clear_screen: bool,
+    pub theme: Option<UiTheme>,
+    pub selected_emphasis: Option<SelectedEmphasis>,
+    pub focus_style: Option<FocusStyle>,
+    pub show_hints_for_unselected: Option<bool>,
+    pub refresh_interval_ms: Option<f64>,
+    pub initial_cursor: Option<i64>,
+    pub allow_escape: Option<bool>,
+    pub on_cursor_change: Option<OnCursorChange<'cb, T>>,
+    pub on_input: Option<OnInput<'cb, T>>,
+}
+
+impl<T> SelectOptions<'_, T> {
+    pub fn new(message: impl Into<String>) -> Self {
+        SelectOptions {
+            message: message.into(),
+            subtitle: None,
+            dynamic_subtitle: None,
+            help: None,
+            clear_screen: false,
+            theme: None,
+            selected_emphasis: None,
+            focus_style: None,
+            show_hints_for_unselected: None,
+            refresh_interval_ms: None,
+            initial_cursor: None,
+            allow_escape: None,
+            on_cursor_change: None,
+            on_input: None,
+        }
+    }
+}
+
+/// Errors thrown by `select` in TS; message strings are FROZEN.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SelectError {
+    NotTty,
+    NoItems,
+    AllDisabled,
+}
+
+impl std::fmt::Display for SelectError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            SelectError::NotTty => write!(f, "Interactive select requires a TTY terminal"),
+            SelectError::NoItems => write!(f, "No menu items provided"),
+            SelectError::AllDisabled => write!(f, "All menu items are disabled"),
+        }
+    }
+}
+
+impl std::error::Error for SelectError {}
+
+const ESCAPE_TIMEOUT_MS: u64 = 50;
+const INPUT_GUARD_MS: u64 = 120;
+
+/// Matches the leading `\x1b\[[0-9;]*m` SGR sequence, if any.
+fn match_leading_sgr(input: &str) -> Option<&str> {
+    let bytes = input.as_bytes();
+    if bytes.len() < 2 || bytes[0] != 0x1b || bytes[1] != b'[' {
+        return None;
+    }
+    let mut i = 2;
+    while i < bytes.len() && (bytes[i].is_ascii_digit() || bytes[i] == b';') {
+        i += 1;
+    }
+    if i < bytes.len() && bytes[i] == b'm' {
+        Some(&input[..=i])
+    } else {
+        None
+    }
+}
+
+/// Strips SGR sequences (`/\x1b\[[0-9;]*m/g`) — SGR only, like the TS regex.
+pub fn strip_ansi(input: &str) -> String {
+    let mut output = String::with_capacity(input.len());
+    let mut rest = input;
+    while let Some(pos) = rest.find('\x1b') {
+        output.push_str(&rest[..pos]);
+        let tail = &rest[pos..];
+        if let Some(m) = match_leading_sgr(tail) {
+            rest = &tail[m.len()..];
+        } else {
+            // Not an SGR sequence: keep the ESC char and move on.
+            output.push('\x1b');
+            rest = &tail['\x1b'.len_utf8()..];
+        }
+    }
+    output.push_str(rest);
+    output
+}
+
+/// Truncates a string to at most `max_visible_chars` display columns while
+/// preserving ANSI SGR sequences, appending a `...` suffix (and a reset when
+/// the kept prefix contains an ESC — ui-01). Widths are display columns, so a
+/// 2-column glyph is never split. Exported for unit testing, like the TS.
+pub fn truncate_ansi(input: &str, max_visible_chars: i64) -> String {
+    if max_visible_chars <= 0 {
+        return String::new();
+    }
+    let max_visible = max_visible_chars as usize;
+    let visible = strip_ansi(input);
+    if display_width(&visible) <= max_visible {
+        return input.to_string();
+    }
+
+    // Reserve room for the suffix in display columns ("..." is 3 columns).
+    let suffix = if max_visible >= 3 {
+        "...".to_string()
+    } else {
+        ".".repeat(max_visible)
+    };
+    let keep = max_visible.saturating_sub(display_width(&suffix));
+    let mut kept_width = 0usize;
+    let mut output = String::new();
+    let mut rest = input;
+
+    while !rest.is_empty() && kept_width < keep {
+        if rest.starts_with('\x1b')
+            && let Some(m) = match_leading_sgr(rest) {
+                output.push_str(m);
+                rest = &rest[m.len()..];
+                continue;
+            }
+        // Advance one full code point and budget by its display width so a
+        // 2-column glyph is never split or allowed to overflow.
+        let ch = match rest.chars().next() {
+            Some(ch) => ch,
+            None => break,
+        };
+        let mut buf = [0u8; 4];
+        let ch_str: &str = ch.encode_utf8(&mut buf);
+        let w = display_width(ch_str);
+        if kept_width + w > keep {
+            break;
+        }
+        output.push(ch);
+        rest = &rest[ch.len_utf8()..];
+        kept_width += w;
+    }
+
+    // ui-01: if the kept portion contains any ANSI escape, append a reset so
+    // the color does not bleed past the truncation point.
+    let reset = if output.contains('\x1b') { "\x1b[0m" } else { "" };
+    format!("{output}{suffix}{reset}")
+}
+
+fn color_code(color: Option<MenuColor>) -> &'static str {
+    match color {
+        Some(MenuColor::Red) => ansi::RED,
+        Some(MenuColor::Green) => ansi::GREEN,
+        Some(MenuColor::Yellow) => ansi::YELLOW,
+        Some(MenuColor::Cyan) => ansi::CYAN,
+        None => "",
+    }
+}
+
+/// TS `decodeHotkeyInput`: keypad escape sequences map to their digit/operator;
+/// otherwise the first printable ASCII char wins; else `None`.
+///
+/// NOTE: this pure byte-level decoder is NOT wired into the live loop — the
+/// loop consumes crossterm events, and crossterm neither parses `ESC O p..y`
+/// (application-keypad digits) nor exposes the raw bytes, so those hotkeys
+/// are an accepted loss on unix (see the module header). Kept for parity
+/// tests and for a future raw-stdin reader.
+pub fn decode_hotkey_input(data: &[u8]) -> Option<char> {
+    let input = String::from_utf8_lossy(data);
+    let mapped = match input.as_ref() {
+        "\x1bOp" => Some('0'),
+        "\x1bOq" => Some('1'),
+        "\x1bOr" => Some('2'),
+        "\x1bOs" => Some('3'),
+        "\x1bOt" => Some('4'),
+        "\x1bOu" => Some('5'),
+        "\x1bOv" => Some('6'),
+        "\x1bOw" => Some('7'),
+        "\x1bOx" => Some('8'),
+        "\x1bOy" => Some('9'),
+        "\x1bOk" => Some('+'),
+        "\x1bOm" => Some('-'),
+        "\x1bOj" => Some('*'),
+        "\x1bOo" => Some('/'),
+        "\x1bOn" => Some('.'),
+        _ => None,
+    };
+    if mapped.is_some() {
+        return mapped;
+    }
+    // Fallback: strip control bytes and keep first printable ASCII char.
+    input.chars().find(|&ch| (' '..='~').contains(&ch))
+}
+
+fn is_selectable<T>(item: &MenuItem<T>) -> bool {
+    !item.disabled && !item.separator && !item.heading
+}
+
+/// External-signal protection for the menu's lifetime — TS
+/// `process.once("SIGINT"/"SIGTERM", onSignal)` where `onSignal` is
+/// `finish(null)`: while a menu is open, SIGINT/SIGTERM set a flag that the
+/// select loop (which wakes at least every 500 ms) turns into a cancel WITH
+/// terminal restoration. Without this, an external `kill <pid>` (SIGTERM) or
+/// out-of-TTY SIGINT terminates mid-menu with raw mode still enabled and the
+/// cursor hidden (`\x1b[?25l` never undone), corrupting the shell until
+/// `reset`. Outside any menu the conditional-default action re-runs the OS
+/// default handler (terminate), so normal Ctrl-C / kill behavior is
+/// preserved for the rest of the process. Windows: console Ctrl-C arrives as
+/// a key event in raw mode and is handled by the Ctrl-C-as-escape arm.
+#[cfg(unix)]
+mod menu_signals {
+    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+    use std::sync::{Arc, LazyLock};
+
+    /// TRUE while NO menu is open → a signal runs the default handler.
+    static OUTSIDE_MENU: LazyLock<Arc<AtomicBool>> =
+        LazyLock::new(|| Arc::new(AtomicBool::new(true)));
+    /// Set by the handler while a menu is open; polled by the select loop.
+    static SIGNALLED: LazyLock<Arc<AtomicBool>> =
+        LazyLock::new(|| Arc::new(AtomicBool::new(false)));
+    /// Menu nesting depth (`on_input` callbacks may open nested menus).
+    static DEPTH: AtomicUsize = AtomicUsize::new(0);
+    static INSTALL: LazyLock<()> = LazyLock::new(|| {
+        for signal in [signal_hook::consts::SIGINT, signal_hook::consts::SIGTERM] {
+            // Registration order matters (actions run in order): outside a
+            // menu the first action terminates via the emulated default
+            // handler; inside a menu it is skipped and the second action
+            // records the signal for the loop.
+            let _ = signal_hook::flag::register_conditional_default(
+                signal,
+                Arc::clone(&OUTSIDE_MENU),
+            );
+            let _ = signal_hook::flag::register(signal, Arc::clone(&SIGNALLED));
+        }
+    });
+
+    /// RAII guard for the menu-open window; nested menus keep protection
+    /// until the outermost scope drops.
+    pub struct MenuSignalScope;
+
+    impl MenuSignalScope {
+        pub fn enter() -> Self {
+            LazyLock::force(&INSTALL);
+            if DEPTH.fetch_add(1, Ordering::SeqCst) == 0 {
+                SIGNALLED.store(false, Ordering::SeqCst);
+                OUTSIDE_MENU.store(false, Ordering::SeqCst);
+            }
+            MenuSignalScope
+        }
+
+        pub fn signalled(&self) -> bool {
+            SIGNALLED.load(Ordering::SeqCst)
+        }
+    }
+
+    impl Drop for MenuSignalScope {
+        fn drop(&mut self) {
+            if DEPTH.fetch_sub(1, Ordering::SeqCst) == 1 {
+                OUTSIDE_MENU.store(true, Ordering::SeqCst);
+            }
+        }
+    }
+}
+
+/// Inputs to the pure frame renderer (one call == one TS `render()`).
+pub struct SelectFrameParams<'a, T> {
+    pub items: &'a [MenuItem<T>],
+    pub cursor: usize,
+    pub message: &'a str,
+    /// Already-resolved subtitle (`dynamicSubtitle?.() ?? subtitle`).
+    pub subtitle_text: Option<&'a str>,
+    pub help: Option<&'a str>,
+    pub clear_screen: bool,
+    pub theme: Option<&'a UiTheme>,
+    pub focus_style: FocusStyle,
+    pub show_hints_for_unselected: bool,
+    pub columns: usize,
+    pub rows: usize,
+}
+
+pub struct SelectFrame {
+    /// The exact byte sequence written to stdout for this frame.
+    pub output: String,
+    /// Number of physical lines written (TS `renderedLines`).
+    pub lines_written: usize,
+}
+
+/// Pure port of the TS `render()` — produces the exact stdout byte sequence.
+pub fn render_select_frame<T>(
+    params: &SelectFrameParams<'_, T>,
+    previous_rendered_lines: usize,
+    has_rendered: bool,
+) -> SelectFrame {
+    let columns = params.columns as i64;
+    let rows = params.rows as i64;
+    let items = params.items;
+    let cursor = params.cursor;
+    let theme = params.theme;
+    // Empty subtitles are falsy in TS.
+    let subtitle_text = params.subtitle_text.filter(|s| !s.is_empty());
+
+    let mut output = String::new();
+    let mut did_full_clear = false;
+    if params.clear_screen && !has_rendered {
+        output.push_str(ansi::CLEAR_SCREEN);
+        output.push_str(&ansi::move_to(1, 1));
+        did_full_clear = true;
+    } else if previous_rendered_lines > 0 {
+        output.push_str(&ansi::up(previous_rendered_lines));
+    }
+
+    let mut lines_written = 0usize;
+    let write_line = |output: &mut String, lines_written: &mut usize, line: &str| {
+        output.push_str(ansi::CLEAR_LINE);
+        output.push_str(line);
+        output.push('\n');
+        *lines_written += 1;
+    };
+
+    let subtitle_lines: i64 = if subtitle_text.is_some() { 2 } else { 0 };
+    let fixed_lines = 2 + subtitle_lines + 2;
+    let max_visible_items =
+        std::cmp::max(1, std::cmp::min(items.len() as i64, rows - fixed_lines - 1)) as usize;
+
+    let mut window_start = 0usize;
+    let mut window_end = items.len();
+    if items.len() > max_visible_items {
+        let half = (max_visible_items / 2) as i64;
+        let start = (cursor as i64) - half;
+        let clamped = std::cmp::max(
+            0,
+            std::cmp::min(start, items.len() as i64 - max_visible_items as i64),
+        ) as usize;
+        window_start = clamped;
+        window_end = window_start + max_visible_items;
+    }
+
+    let visible_len = window_end - window_start;
+    let border = theme.map(|t| t.colors.border.as_str()).unwrap_or(ansi::DIM);
+    let muted = theme.map(|t| t.colors.muted.as_str()).unwrap_or(ansi::DIM);
+    let heading_color = theme
+        .map(|t| t.colors.heading.as_str())
+        .unwrap_or(ansi::RESET);
+    let reset = theme.map(|t| t.colors.reset.as_str()).unwrap_or(ansi::RESET);
+    let selected_glyph = theme.map(|t| t.glyphs.selected).unwrap_or(">");
+    let unselected_glyph = theme.map(|t| t.glyphs.unselected).unwrap_or("o");
+    let selected_glyph_color = theme
+        .map(|t| t.colors.success.as_str())
+        .unwrap_or(ansi::GREEN);
+    let selected_chip = match theme {
+        None => format!("{}{}{}", ansi::BG_GREEN, ansi::BLACK, ansi::BOLD),
+        Some(t) => format!("{}{}{}", t.colors.focus_bg, t.colors.focus_text, ansi::BOLD),
+    };
+    let codex_color_code = |color: Option<MenuColor>| -> &str {
+        match theme {
+            None => color_code(color),
+            Some(t) => match color {
+                Some(MenuColor::Red) => t.colors.danger.as_str(),
+                Some(MenuColor::Green) => t.colors.success.as_str(),
+                Some(MenuColor::Yellow) => t.colors.warning.as_str(),
+                Some(MenuColor::Cyan) => t.colors.accent.as_str(),
+                None => t.colors.heading.as_str(),
+            },
+        }
+    };
+
+    write_line(
+        &mut output,
+        &mut lines_written,
+        &format!(
+            "{border}+{reset} {heading_color}{}{reset}",
+            truncate_ansi(params.message, std::cmp::max(1, columns - 4))
+        ),
+    );
+    if let Some(subtitle) = subtitle_text {
+        write_line(
+            &mut output,
+            &mut lines_written,
+            &format!(
+                " {muted}{}{reset}",
+                truncate_ansi(subtitle, std::cmp::max(1, columns - 2))
+            ),
+        );
+    }
+    write_line(&mut output, &mut lines_written, "");
+
+    for (i, item) in items[window_start..window_end].iter().enumerate() {
+        let item_index = window_start + i;
+
+        if item.separator {
+            write_line(&mut output, &mut lines_written, "");
+            continue;
+        }
+
+        if item.heading {
+            let heading_text = truncate_ansi(
+                &format!("{muted}{}{reset}", item.label),
+                std::cmp::max(1, columns - 2),
+            );
+            write_line(&mut output, &mut lines_written, &format!(" {heading_text}"));
+            continue;
+        }
+
+        let selected = item_index == cursor;
+        if selected {
+            let selected_text = match &item.selected_label {
+                Some(selected_label) => strip_ansi(selected_label),
+                None => {
+                    if item.disabled {
+                        if item.hide_unavailable_suffix {
+                            strip_ansi(&item.label)
+                        } else {
+                            format!("{} (unavailable)", strip_ansi(&item.label))
+                        }
+                    } else {
+                        strip_ansi(&item.label)
+                    }
+                }
+            };
+            match params.focus_style {
+                FocusStyle::RowInvert => {
+                    let row_text = format!("{selected_glyph} {selected_text}");
+                    let focused_row = match theme {
+                        Some(t) => format!(
+                            "{}{}{}{}{reset}",
+                            t.colors.focus_bg,
+                            t.colors.focus_text,
+                            ansi::BOLD,
+                            truncate_ansi(&row_text, std::cmp::max(1, columns - 2))
+                        ),
+                        None => format!(
+                            "{}{}{}",
+                            ansi::INVERSE,
+                            truncate_ansi(&row_text, std::cmp::max(1, columns - 2)),
+                            ansi::RESET
+                        ),
+                    };
+                    write_line(&mut output, &mut lines_written, &format!(" {focused_row}"));
+                }
+                FocusStyle::Chip => {
+                    let selected_label = format!("{selected_chip}{selected_text}{reset}");
+                    write_line(
+                        &mut output,
+                        &mut lines_written,
+                        &format!(
+                            " {selected_glyph_color}{selected_glyph}{reset} {}",
+                            truncate_ansi(&selected_label, std::cmp::max(1, columns - 4))
+                        ),
+                    );
+                }
+            }
+            if let Some(hint) = &item.hint {
+                for detail_line in hint.split('\n').take(3) {
+                    let detail = truncate_ansi(detail_line, std::cmp::max(1, columns - 8));
+                    write_line(&mut output, &mut lines_written, &format!("   {muted}{detail}{reset}"));
+                }
+            }
+        } else {
+            let item_color = codex_color_code(item.color);
+            let label_text = if item.disabled {
+                if item.hide_unavailable_suffix {
+                    format!("{muted}{}{reset}", item.label)
+                } else {
+                    format!("{muted}{} (unavailable){reset}", item.label)
+                }
+            } else {
+                format!("{item_color}{}{reset}", item.label)
+            };
+            write_line(
+                &mut output,
+                &mut lines_written,
+                &format!(
+                    " {muted}{unselected_glyph}{reset} {}",
+                    truncate_ansi(&label_text, std::cmp::max(1, columns - 4))
+                ),
+            );
+            if let Some(hint) = &item.hint
+                && params.show_hints_for_unselected {
+                    for detail_line in hint.split('\n').take(2) {
+                        let detail = truncate_ansi(
+                            &format!("{muted}{detail_line}{reset}"),
+                            std::cmp::max(1, columns - 8),
+                        );
+                        write_line(&mut output, &mut lines_written, &format!("   {detail}"));
+                    }
+                }
+        }
+    }
+
+    let window_hint = if items.len() > visible_len {
+        format!(" ({}-{}/{})", window_start + 1, window_end, items.len())
+    } else {
+        String::new()
+    };
+    let help_text = match params.help {
+        Some(help) => help.to_string(),
+        None => format!("\u{2191}\u{2193} Move | Enter Select | Q Back{window_hint}"),
+    };
+    write_line(
+        &mut output,
+        &mut lines_written,
+        &format!(
+            " {muted}{}{reset}",
+            truncate_ansi(&help_text, std::cmp::max(1, columns - 2))
+        ),
+    );
+    write_line(&mut output, &mut lines_written, &format!("{border}+{reset}"));
+
+    if !did_full_clear && previous_rendered_lines > lines_written {
+        let extra = previous_rendered_lines - lines_written;
+        for _ in 0..extra {
+            write_line(&mut output, &mut lines_written, "");
+        }
+    }
+
+    SelectFrame {
+        output,
+        lines_written,
+    }
+}
+
+fn terminal_size() -> (usize, usize) {
+    match crossterm::terminal::size() {
+        Ok((cols, rows)) => (cols as usize, rows as usize),
+        Err(_) => (80, 24),
+    }
+}
+
+fn write_stdout(text: &str) {
+    let mut out = std::io::stdout();
+    let _ = out.write_all(text.as_bytes());
+    let _ = out.flush();
+}
+
+/// Restore terminal state. Mirrors the TS cleanup ordering guarantees: every
+/// step is individually best-effort and the cursor is always re-shown.
+fn cleanup_terminal(was_raw: bool) {
+    if !was_raw {
+        let _ = crossterm::terminal::disable_raw_mode();
+    }
+    write_stdout(ansi::SHOW);
+}
+
+/// Present an interactive TTY menu and let the user navigate and choose.
+///
+/// Returns `Ok(Some(value))` on selection, `Ok(None)` on cancel (Q / Esc /
+/// Ctrl-C / raw-mode failure), or `Err` with the frozen TS error strings when
+/// preconditions fail.
+// The rerender flag mirrors the TS mutable `rerenderRequested` write pattern
+// (reset before every callback), which trips the dead-store lint.
+#[allow(unused_assignments)]
+pub fn select<T: Clone>(
+    items: &[MenuItem<T>],
+    mut options: SelectOptions<'_, T>,
+) -> Result<Option<T>, SelectError> {
+    if !crate::ansi::is_tty() {
+        return Err(SelectError::NotTty);
+    }
+    if items.is_empty() {
+        return Err(SelectError::NoItems);
+    }
+
+    let selectable_count = items.iter().filter(|i| is_selectable(i)).count();
+    if selectable_count == 0 {
+        return Err(SelectError::AllDisabled);
+    }
+    if selectable_count == 1 {
+        // Exactly one selectable item: return its value immediately without
+        // rendering anything — callers rely on this.
+        return Ok(items.iter().find(|i| is_selectable(i)).map(|i| i.value.clone()));
+    }
+
+    let first_selectable = items.iter().position(is_selectable).unwrap_or(0);
+    let mut cursor = first_selectable;
+    if let Some(initial) = options.initial_cursor {
+        let bounded = std::cmp::max(0, std::cmp::min(items.len() as i64 - 1, initial)) as usize;
+        cursor = bounded;
+    }
+    if !is_selectable(&items[cursor]) {
+        cursor = first_selectable;
+    }
+
+    // Pull the render inputs and callbacks out of the options bag once.
+    let message = options.message.clone();
+    let static_subtitle = options.subtitle.clone();
+    let dynamic_subtitle = options.dynamic_subtitle.take();
+    let help = options.help.clone();
+    let clear_screen = options.clear_screen;
+    let theme = options.theme.clone();
+    let focus_style = options.focus_style.unwrap_or_default();
+    let show_hints_for_unselected = options.show_hints_for_unselected.unwrap_or(true);
+    let allow_escape = options.allow_escape.unwrap_or(true);
+    let mut on_cursor_change = options.on_cursor_change.take();
+    let mut on_input = options.on_input.take();
+
+    let was_raw = crossterm::terminal::is_raw_mode_enabled().unwrap_or(false);
+    if crossterm::terminal::enable_raw_mode().is_err() {
+        cleanup_terminal(was_raw);
+        return Ok(None);
+    }
+    // Menu-lifetime SIGINT/SIGTERM protection (TS process.once(signal,
+    // finish(null))); dropped on every return path.
+    #[cfg(unix)]
+    let signal_scope = menu_signals::MenuSignalScope::enter();
+
+    // Drain any buffered input so a queued Enter cannot instantly accept.
+    while crossterm::event::poll(Duration::from_millis(0)).unwrap_or(false) {
+        let _ = crossterm::event::read();
+    }
+    let input_guard_until = Instant::now() + Duration::from_millis(INPUT_GUARD_MS);
+    write_stdout(ansi::HIDE);
+
+    let mut rendered_lines = 0usize;
+    let mut has_rendered = false;
+    let mut rerender_requested = false;
+
+    macro_rules! render {
+        () => {{
+            let subtitle_owned: Option<String> = match &dynamic_subtitle {
+                Some(f) => f(),
+                None => static_subtitle.clone(),
+            };
+            let (columns, rows) = terminal_size();
+            let frame = render_select_frame(
+                &SelectFrameParams {
+                    items,
+                    cursor,
+                    message: &message,
+                    subtitle_text: subtitle_owned.as_deref(),
+                    help: help.as_deref(),
+                    clear_screen,
+                    theme: theme.as_ref(),
+                    focus_style,
+                    show_hints_for_unselected,
+                    columns,
+                    rows,
+                },
+                rendered_lines,
+                has_rendered,
+            );
+            write_stdout(&frame.output);
+            rendered_lines = frame.lines_written;
+            has_rendered = true;
+        }};
+    }
+
+    macro_rules! notify_cursor_change {
+        () => {{
+            if let Some(cb) = on_cursor_change.as_mut() {
+                rerender_requested = false;
+                let mut ctx = SelectContext {
+                    cursor,
+                    items,
+                    rerender_requested: &mut rerender_requested,
+                };
+                cb(&mut ctx);
+            }
+        }};
+    }
+
+    macro_rules! finish {
+        ($value:expr) => {{
+            cleanup_terminal(was_raw);
+            return Ok($value);
+        }};
+    }
+
+    notify_cursor_change!();
+    render!();
+
+    let refresh_interval: Option<Duration> = match (&dynamic_subtitle, options.refresh_interval_ms)
+    {
+        (Some(_), Some(ms)) if ms > 0.0 => {
+            Some(Duration::from_millis(std::cmp::max(80, ms.round() as u64)))
+        }
+        _ => None,
+    };
+    let mut next_refresh = refresh_interval.map(|d| Instant::now() + d);
+    let mut escape_deadline: Option<Instant> = None;
+
+    let find_next_selectable = |from: usize, direction: i64| -> usize {
+        let len = items.len() as i64;
+        let mut next = from as i64;
+        loop {
+            next = (next + direction + len) % len;
+            let item = &items[next as usize];
+            if !(item.disabled || item.separator || item.heading) {
+                break;
+            }
+        }
+        next as usize
+    };
+
+    loop {
+        let now = Instant::now();
+        // External SIGINT/SIGTERM during the menu: TS finish(null) —
+        // restore the terminal (raw mode + cursor) and return cancel. The
+        // poll timeout below is ≤500 ms, bounding the latency.
+        #[cfg(unix)]
+        if signal_scope.signalled() {
+            finish!(None);
+        }
+        if let Some(deadline) = escape_deadline
+            && now >= deadline {
+                // Bare ESC with no follow-up bytes: it really was Escape.
+                finish!(None);
+            }
+        if let Some(due) = next_refresh
+            && now >= due {
+                render!();
+                next_refresh = refresh_interval.map(|d| Instant::now() + d);
+            }
+
+        let mut timeout = Duration::from_millis(500);
+        for deadline in [escape_deadline, next_refresh].into_iter().flatten() {
+            let remaining = deadline.saturating_duration_since(now);
+            if remaining < timeout {
+                timeout = remaining;
+            }
+        }
+
+        let has_event = crossterm::event::poll(timeout).unwrap_or(false);
+        if !has_event {
+            continue;
+        }
+        let event = match crossterm::event::read() {
+            Ok(event) => event,
+            Err(_) => continue,
+        };
+        let key = match event {
+            Event::Key(key) if key.kind == KeyEventKind::Press => key,
+            _ => continue,
+        };
+
+        // Every input event first clears any pending escape timeout (it was an
+        // escape-sequence prefix, not a lone ESC).
+        escape_deadline = None;
+
+        let action: Option<KeyAction> = match key.code {
+            KeyCode::Up => Some(KeyAction::Up),
+            KeyCode::Down => Some(KeyAction::Down),
+            KeyCode::Home => Some(KeyAction::Home),
+            KeyCode::End => Some(KeyAction::End),
+            KeyCode::Enter => Some(KeyAction::Enter),
+            KeyCode::Esc => Some(KeyAction::EscapeStart),
+            KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
+                Some(KeyAction::Escape)
+            }
+            _ => None,
+        };
+
+        // 120 ms input guard: drop enter/escape/escape-start only; arrows and
+        // hotkeys still work immediately.
+        if Instant::now() < input_guard_until
+            && matches!(
+                action,
+                Some(KeyAction::Enter) | Some(KeyAction::Escape) | Some(KeyAction::EscapeStart)
+            )
+        {
+            continue;
+        }
+
+        match action {
+            Some(KeyAction::Up) => {
+                cursor = find_next_selectable(cursor, -1);
+                notify_cursor_change!();
+                render!();
+            }
+            Some(KeyAction::Down) => {
+                cursor = find_next_selectable(cursor, 1);
+                notify_cursor_change!();
+                render!();
+            }
+            Some(KeyAction::Home) => {
+                cursor = items.iter().position(is_selectable).unwrap_or(cursor);
+                notify_cursor_change!();
+                render!();
+            }
+            Some(KeyAction::End) => {
+                for i in (0..items.len()).rev() {
+                    if is_selectable(&items[i]) {
+                        cursor = i;
+                        break;
+                    }
+                }
+                notify_cursor_change!();
+                render!();
+            }
+            Some(KeyAction::Enter) => {
+                finish!(Some(items[cursor].value.clone()));
+            }
+            Some(KeyAction::Escape) => {
+                if allow_escape {
+                    finish!(None);
+                }
+            }
+            Some(KeyAction::EscapeStart) => {
+                if allow_escape {
+                    escape_deadline =
+                        Some(Instant::now() + Duration::from_millis(ESCAPE_TIMEOUT_MS));
+                }
+            }
+            None => {
+                let hotkey: Option<char> = match key.code {
+                    KeyCode::Char(ch)
+                        if (' '..='~').contains(&ch)
+                            && !key.modifiers.contains(KeyModifiers::CONTROL) =>
+                    {
+                        Some(ch)
+                    }
+                    _ => None,
+                };
+                if let Some(hk) = hotkey {
+                    if hk.eq_ignore_ascii_case(&'q') {
+                        finish!(None);
+                    }
+                    if let Some(cb) = on_input.as_mut() {
+                        rerender_requested = false;
+                        let result = {
+                            let mut ctx = SelectContext {
+                                cursor,
+                                items,
+                                rerender_requested: &mut rerender_requested,
+                            };
+                            cb(&hk.to_string(), &mut ctx)
+                        };
+                        match result {
+                            SelectInputResult::Finish(value) => {
+                                finish!(value);
+                            }
+                            SelectInputResult::Ignored => {
+                                if rerender_requested {
+                                    render!();
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::{create_ui_theme, CreateUiThemeOptions};
+
+    const ESC: char = '\x1b';
+
+    /// Finding: an external SIGINT/SIGTERM during a menu must become a
+    /// cancel (flag polled by the loop → terminal restore) instead of
+    /// terminating the process with raw mode on and the cursor hidden. The
+    /// process surviving `raise(SIGTERM)` here proves the default handler
+    /// was suppressed while a menu scope is active; the flag is what the
+    /// loop turns into `finish!(None)`.
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(menu_signals)]
+    fn external_signal_inside_a_menu_scope_flags_cancel_instead_of_terminating() {
+        let scope = menu_signals::MenuSignalScope::enter();
+        assert!(!scope.signalled());
+        signal_hook::low_level::raise(signal_hook::consts::SIGTERM).unwrap();
+        for _ in 0..200 {
+            if scope.signalled() {
+                break;
+            }
+            std::thread::sleep(Duration::from_millis(5));
+        }
+        assert!(
+            scope.signalled(),
+            "SIGTERM inside a menu scope must set the cancel flag"
+        );
+        // A second signal inside the SAME scope is still swallowed (flag
+        // already set; loop exits within one poll interval anyway).
+        signal_hook::low_level::raise(signal_hook::consts::SIGINT).unwrap();
+        std::thread::sleep(Duration::from_millis(20));
+        assert!(scope.signalled());
+        drop(scope);
+        // NOTE: the outside-menu path (conditional default → terminate) is
+        // deliberately not exercised — it would kill the test binary.
+    }
+
+    // ---- truncateAnsi ANSI reset placement (ui-01) — from test/select.test.ts ----
+
+    #[test]
+    fn appends_suffix_and_reset_when_kept_portion_contains_ansi() {
+        let red = format!("{ESC}[31m");
+        let reset = format!("{ESC}[0m");
+        // 10 colored visible chars truncated to 5 -> keep 2 visible, then reset.
+        let out = truncate_ansi(&format!("{red}abcdefghij"), 5);
+        assert!(out.ends_with(&format!("...{reset}")));
+        assert!(out.starts_with(&red));
+        assert_eq!(out, format!("{red}ab...{reset}"));
+    }
+
+    #[test]
+    fn does_not_add_extra_reset_when_colored_input_fits() {
+        let red = format!("{ESC}[31m");
+        let reset = format!("{ESC}[0m");
+        let input = format!("{red}abc{reset}");
+        // Fits within width -> returned unchanged, no second reset appended.
+        assert_eq!(truncate_ansi(&input, 10), input);
+    }
+
+    #[test]
+    fn does_not_add_reset_when_plain_input_is_truncated() {
+        let reset = format!("{ESC}[0m");
+        let out = truncate_ansi("abcdefghij", 5);
+        assert!(!out.contains(&reset));
+        assert!(out.ends_with("..."));
+        assert_eq!(out, "ab...");
+    }
+
+    #[test]
+    fn still_ends_with_single_reset_when_multiple_escapes_kept() {
+        let red = format!("{ESC}[31m");
+        let reset = format!("{ESC}[0m");
+        let out = truncate_ansi(&format!("{red}a{reset}{red}bcdefghij"), 5);
+        assert!(out.ends_with(&reset));
+        assert!(!out.ends_with(&format!("{reset}{reset}")));
+    }
+
+    #[test]
+    fn truncate_ansi_zero_or_negative_budget_yields_empty() {
+        assert_eq!(truncate_ansi("abc", 0), "");
+        assert_eq!(truncate_ansi("abc", -3), "");
+    }
+
+    #[test]
+    fn truncate_ansi_short_budget_uses_dot_suffix() {
+        // maxVisibleChars < 3 => suffix is ".".repeat(maxVisibleChars), keep 0.
+        assert_eq!(truncate_ansi("abcdef", 2), "..");
+        assert_eq!(truncate_ansi("abcdef", 1), ".");
+    }
+
+    #[test]
+    fn truncate_ansi_never_splits_a_wide_glyph() {
+        // "漢" is 2 columns. Budget 6 => keep 3 => "漢" (2) fits, second would
+        // exceed keep, so it stops at 1 glyph + "...".
+        let out = truncate_ansi("漢漢漢漢", 6);
+        assert_eq!(out, "漢...");
+    }
+
+    #[test]
+    fn strip_ansi_removes_sgr_only() {
+        assert_eq!(strip_ansi("\x1b[31mred\x1b[0m"), "red");
+        // Non-SGR CSI (cursor up) is NOT stripped by the SGR-only regex.
+        assert_eq!(strip_ansi("\x1b[2Ax"), "\x1b[2Ax");
+    }
+
+    // ---- decodeHotkeyInput ----
+
+    #[test]
+    fn decode_hotkey_maps_keypad_sequences() {
+        assert_eq!(decode_hotkey_input(b"\x1bOp"), Some('0'));
+        assert_eq!(decode_hotkey_input(b"\x1bOq"), Some('1'));
+        assert_eq!(decode_hotkey_input(b"\x1bOy"), Some('9'));
+        assert_eq!(decode_hotkey_input(b"\x1bOk"), Some('+'));
+        assert_eq!(decode_hotkey_input(b"\x1bOm"), Some('-'));
+        assert_eq!(decode_hotkey_input(b"\x1bOj"), Some('*'));
+        assert_eq!(decode_hotkey_input(b"\x1bOo"), Some('/'));
+        assert_eq!(decode_hotkey_input(b"\x1bOn"), Some('.'));
+    }
+
+    #[test]
+    fn decode_hotkey_keeps_first_printable_ascii_char() {
+        assert_eq!(decode_hotkey_input(b"x"), Some('x'));
+        assert_eq!(decode_hotkey_input(b"\x01a"), Some('a'));
+        assert_eq!(decode_hotkey_input(b"\x01\x02"), None);
+        assert_eq!(decode_hotkey_input(b""), None);
+    }
+
+    // ---- error strings (frozen contract) ----
+
+    #[test]
+    fn select_error_messages_are_frozen() {
+        assert_eq!(
+            SelectError::NotTty.to_string(),
+            "Interactive select requires a TTY terminal"
+        );
+        assert_eq!(SelectError::NoItems.to_string(), "No menu items provided");
+        assert_eq!(
+            SelectError::AllDisabled.to_string(),
+            "All menu items are disabled"
+        );
+    }
+
+    // ---- pure render frame: exact output strings ----
+
+    fn plain_items() -> Vec<MenuItem<&'static str>> {
+        vec![MenuItem::new("A", "a"), MenuItem::new("B", "b")]
+    }
+
+    #[test]
+    fn renders_exact_unthemed_first_frame() {
+        let items = plain_items();
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "Pick one",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let expected = concat!(
+            // header: `${border}+${reset} ${heading}${message}${reset}`
+            "\x1b[2K\x1b[2m+\x1b[0m \x1b[0mPick one\x1b[0m\n",
+            // unconditional blank line
+            "\x1b[2K\n",
+            // selected row (no theme): inverse `> A`
+            "\x1b[2K \x1b[7m> A\x1b[0m\n",
+            // unselected row: ` ${muted}o${reset} B${reset}` (no item color)
+            "\x1b[2K \x1b[2mo\x1b[0m B\x1b[0m\n",
+            // footer help (default text, no window hint)
+            "\x1b[2K \x1b[2m\u{2191}\u{2193} Move | Enter Select | Q Back\x1b[0m\n",
+            // closing border
+            "\x1b[2K\x1b[2m+\x1b[0m\n",
+        );
+        assert_eq!(frame.output, expected);
+        assert_eq!(frame.lines_written, 6);
+    }
+
+    #[test]
+    fn first_render_with_clear_screen_prefixes_clear_and_home() {
+        let items = plain_items();
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: true,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        assert!(frame.output.starts_with("\x1b[2J\x1b[1;1H"));
+    }
+
+    #[test]
+    fn subsequent_render_moves_cursor_up_and_pads_shrunk_frames() {
+        let items = plain_items();
+        let params = SelectFrameParams {
+            items: &items,
+            cursor: 0,
+            message: "M",
+            subtitle_text: None,
+            help: None,
+            clear_screen: false,
+            theme: None,
+            focus_style: FocusStyle::RowInvert,
+            show_hints_for_unselected: true,
+            columns: 80,
+            rows: 24,
+        };
+        let frame = render_select_frame(&params, 8, true);
+        assert!(frame.output.starts_with("\x1b[8A"));
+        // Previous render had 8 lines, this one writes 6 + 2 blank pads.
+        assert_eq!(frame.lines_written, 8);
+        assert!(frame.output.ends_with("\x1b[2K\n\x1b[2K\n"));
+    }
+
+    #[test]
+    fn subtitle_line_and_hints_render_with_muted_wrapping() {
+        let mut items = plain_items();
+        items[0].hint = Some("one\ntwo\nthree\nfour".to_string());
+        items[1].hint = Some("h1\nh2\nh3".to_string());
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: Some("Sub"),
+                help: Some("HELP"),
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let lines: Vec<&str> = frame.output.split('\n').collect();
+        // header + subtitle + blank + selected row + 3 selected hints (max 3
+        // of 4) + unselected row + 2 unselected hints (max 2 of 3) + help +
+        // border = 12 physical lines.
+        assert_eq!(frame.lines_written, 12);
+        assert_eq!(lines[1], "\x1b[2K \x1b[2mSub\x1b[0m");
+        // Selected hints: raw line truncated, then wrapped in muted...reset.
+        assert_eq!(lines[4], "\x1b[2K   \x1b[2mone\x1b[0m");
+        assert_eq!(lines[6], "\x1b[2K   \x1b[2mthree\x1b[0m");
+        // Unselected hints: wrapped first, then truncated (identical here).
+        assert_eq!(lines[8], "\x1b[2K   \x1b[2mh1\x1b[0m");
+        assert_eq!(lines[9], "\x1b[2K   \x1b[2mh2\x1b[0m");
+        // Custom help does NOT get the window hint appended.
+        assert_eq!(lines[10], "\x1b[2K \x1b[2mHELP\x1b[0m");
+    }
+
+    #[test]
+    fn overflowing_items_window_appends_range_hint_to_default_help() {
+        let items: Vec<MenuItem<usize>> = (0..10)
+            .map(|i| MenuItem::new(format!("Item {i}"), i))
+            .collect();
+        // rows 8 -> fixedLines 4 -> maxVisible = max(1, min(10, 8-4-1)) = 3.
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 5,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 8,
+            },
+            0,
+            false,
+        );
+        // windowStart = clamp(5 - 1, 0, 7) = 4 -> window 4..7 -> hint "(5-7/10)".
+        assert!(frame.output.contains(" (5-7/10)"));
+        assert!(frame.output.contains("Item 4"));
+        assert!(frame.output.contains("Item 6"));
+        assert!(!frame.output.contains("Item 7"));
+    }
+
+    #[test]
+    fn disabled_rows_get_unavailable_suffix_unless_hidden() {
+        let mut items = plain_items();
+        items.push(MenuItem::new("C", "c"));
+        items[1].disabled = true;
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        assert!(frame.output.contains("B (unavailable)"));
+
+        items[1].hide_unavailable_suffix = true;
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        assert!(!frame.output.contains("(unavailable)"));
+    }
+
+    #[test]
+    fn themed_selected_row_uses_focus_colors_and_chip_style_uses_glyph() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        let items = plain_items();
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: Some(&theme),
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let expected_row = format!(
+            " {}{}{}{}{}",
+            theme.colors.focus_bg,
+            theme.colors.focus_text,
+            crate::ansi::BOLD,
+            "> A",
+            theme.colors.reset
+        );
+        assert!(frame.output.contains(&expected_row));
+
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: Some(&theme),
+                focus_style: FocusStyle::Chip,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let expected_chip_row = format!(
+            " {}{}{} {}{}{}A{}",
+            theme.colors.success,
+            theme.glyphs.selected,
+            theme.colors.reset,
+            theme.colors.focus_bg,
+            theme.colors.focus_text,
+            crate::ansi::BOLD,
+            theme.colors.reset
+        );
+        assert!(frame.output.contains(&expected_chip_row));
+    }
+
+    #[test]
+    fn separators_and_headings_render_without_glyphs() {
+        let items = vec![
+            MenuItem::heading("Section", 0usize),
+            MenuItem::new("A", 1usize),
+            MenuItem::separator(0usize),
+            MenuItem::new("B", 2usize),
+        ];
+        let frame = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 1,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let lines: Vec<&str> = frame.output.split('\n').collect();
+        // header, blank, heading row, selected A, blank separator, B, help, border
+        assert_eq!(lines[2], "\x1b[2K \x1b[2mSection\x1b[0m");
+        assert_eq!(lines[4], "\x1b[2K");
+    }
+
+    #[test]
+    fn empty_dynamic_subtitle_is_falsy_and_renders_no_subtitle_line() {
+        let items = plain_items();
+        let with_none = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: None,
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        let with_empty = render_select_frame(
+            &SelectFrameParams {
+                items: &items,
+                cursor: 0,
+                message: "M",
+                subtitle_text: Some(""),
+                help: None,
+                clear_screen: false,
+                theme: None,
+                focus_style: FocusStyle::RowInvert,
+                show_hints_for_unselected: true,
+                columns: 80,
+                rows: 24,
+            },
+            0,
+            false,
+        );
+        assert_eq!(with_none.output, with_empty.output);
+        assert_eq!(with_none.lines_written, with_empty.lines_written);
+    }
+}
diff --git a/crates/tui/src/theme.rs b/crates/tui/src/theme.rs
new file mode 100644
index 000000000..cfd4cd84b
--- /dev/null
+++ b/crates/tui/src/theme.rs
@@ -0,0 +1,580 @@
+//! Port of `lib/ui/theme.ts` — shared terminal theme primitives.
+//!
+//! 3 color profiles × 2 palettes × 4 accents, glyph sets, and the
+//! NO_COLOR/FORCE_COLOR/TTY color gate (ui-04). All escape sequences are
+//! byte-exact copies of the TS source (spec 12 §3).
+
+use std::io::IsTerminal;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiColorProfile {
+    Ansi16,
+    Ansi256,
+    Truecolor,
+}
+
+impl UiColorProfile {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            UiColorProfile::Ansi16 => "ansi16",
+            UiColorProfile::Ansi256 => "ansi256",
+            UiColorProfile::Truecolor => "truecolor",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "ansi16" => Some(UiColorProfile::Ansi16),
+            "ansi256" => Some(UiColorProfile::Ansi256),
+            "truecolor" => Some(UiColorProfile::Truecolor),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiGlyphMode {
+    Ascii,
+    Unicode,
+    Auto,
+}
+
+impl UiGlyphMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            UiGlyphMode::Ascii => "ascii",
+            UiGlyphMode::Unicode => "unicode",
+            UiGlyphMode::Auto => "auto",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "ascii" => Some(UiGlyphMode::Ascii),
+            "unicode" => Some(UiGlyphMode::Unicode),
+            "auto" => Some(UiGlyphMode::Auto),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiPalette {
+    Green,
+    Blue,
+}
+
+impl UiPalette {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            UiPalette::Green => "green",
+            UiPalette::Blue => "blue",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "green" => Some(UiPalette::Green),
+            "blue" => Some(UiPalette::Blue),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiAccent {
+    Green,
+    Cyan,
+    Blue,
+    Yellow,
+}
+
+impl UiAccent {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            UiAccent::Green => "green",
+            UiAccent::Cyan => "cyan",
+            UiAccent::Blue => "blue",
+            UiAccent::Yellow => "yellow",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "green" => Some(UiAccent::Green),
+            "cyan" => Some(UiAccent::Cyan),
+            "blue" => Some(UiAccent::Blue),
+            "yellow" => Some(UiAccent::Yellow),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UiGlyphSet {
+    pub selected: &'static str,
+    pub unselected: &'static str,
+    pub bullet: &'static str,
+    pub check: &'static str,
+    pub cross: &'static str,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UiThemeColors {
+    pub reset: String,
+    pub dim: String,
+    pub muted: String,
+    pub heading: String,
+    pub primary: String,
+    pub accent: String,
+    pub success: String,
+    pub warning: String,
+    pub danger: String,
+    pub border: String,
+    pub focus_bg: String,
+    pub focus_text: String,
+}
+
+/// NOTE: `glyph_mode` keeps the **requested** mode (may be `Auto`); only
+/// `glyphs` reflects the resolved mode. The quota-bar renderer keys off the
+/// stored requested mode deliberately (ui-03).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UiTheme {
+    pub profile: UiColorProfile,
+    pub glyph_mode: UiGlyphMode,
+    pub glyphs: UiGlyphSet,
+    pub colors: UiThemeColors,
+}
+
+fn ansi16(code: u32) -> String {
+    format!("\x1b[{code}m")
+}
+
+fn ansi256(code: u32) -> String {
+    format!("\x1b[38;5;{code}m")
+}
+
+fn truecolor(r: u32, g: u32, b: u32) -> String {
+    format!("\x1b[38;2;{r};{g};{b}m")
+}
+
+fn ansi256_bg(code: u32) -> String {
+    format!("\x1b[48;5;{code}m")
+}
+
+fn truecolor_bg(r: u32, g: u32, b: u32) -> String {
+    format!("\x1b[48;2;{r};{g};{b}m")
+}
+
+/// Testable core of `resolveGlyphMode("auto")`: `"unicode"` iff `WT_SESSION`
+/// is defined (any value) OR `TERM_PROGRAM === "vscode"` OR lowercased `TERM`
+/// contains `"xterm"`.
+pub(crate) fn resolve_glyph_mode_from(
+    mode: UiGlyphMode,
+    wt_session_defined: bool,
+    term_program: Option<&str>,
+    term: Option<&str>,
+) -> UiGlyphMode {
+    if mode != UiGlyphMode::Auto {
+        return mode;
+    }
+    let is_likely_unicode_safe = wt_session_defined
+        || term_program == Some("vscode")
+        || term
+            .map(|t| t.to_lowercase().contains("xterm"))
+            .unwrap_or(false);
+    if is_likely_unicode_safe {
+        UiGlyphMode::Unicode
+    } else {
+        UiGlyphMode::Ascii
+    }
+}
+
+fn resolve_glyph_mode(mode: UiGlyphMode) -> UiGlyphMode {
+    resolve_glyph_mode_from(
+        mode,
+        std::env::var_os("WT_SESSION").is_some(),
+        std::env::var("TERM_PROGRAM").ok().as_deref(),
+        std::env::var("TERM").ok().as_deref(),
+    )
+}
+
+fn get_glyphs(mode: UiGlyphMode) -> UiGlyphSet {
+    if mode == UiGlyphMode::Unicode {
+        return UiGlyphSet {
+            selected: "\u{25c6}",   // ◆
+            unselected: "\u{25cb}", // ○
+            bullet: "\u{2022}",     // •
+            check: "\u{2713}",      // ✓
+            cross: "\u{2717}",      // ✗
+        };
+    }
+    UiGlyphSet {
+        selected: ">",
+        unselected: "o",
+        bullet: "-",
+        check: "+",
+        cross: "x",
+    }
+}
+
+fn accent_color_for_profile(profile: UiColorProfile, accent: UiAccent) -> String {
+    match profile {
+        UiColorProfile::Truecolor => match accent {
+            UiAccent::Cyan => truecolor(34, 211, 238),
+            UiAccent::Blue => truecolor(59, 130, 246),
+            UiAccent::Yellow => truecolor(245, 158, 11),
+            UiAccent::Green => truecolor(74, 222, 128),
+        },
+        UiColorProfile::Ansi256 => match accent {
+            UiAccent::Cyan => ansi256(51),
+            UiAccent::Blue => ansi256(75),
+            UiAccent::Yellow => ansi256(214),
+            UiAccent::Green => ansi256(83),
+        },
+        UiColorProfile::Ansi16 => match accent {
+            UiAccent::Cyan => ansi16(96),
+            UiAccent::Blue => ansi16(94),
+            UiAccent::Yellow => ansi16(93),
+            UiAccent::Green => ansi16(92),
+        },
+    }
+}
+
+fn get_colors(profile: UiColorProfile, palette: UiPalette, accent: UiAccent) -> UiThemeColors {
+    let accent_color = accent_color_for_profile(profile, accent);
+    let is_blue_palette = palette == UiPalette::Blue;
+    match profile {
+        UiColorProfile::Truecolor => UiThemeColors {
+            reset: "\x1b[0m".to_string(),
+            dim: "\x1b[2m".to_string(),
+            muted: truecolor(148, 163, 184),
+            heading: truecolor(240, 253, 244),
+            primary: if is_blue_palette {
+                truecolor(96, 165, 250)
+            } else {
+                truecolor(74, 222, 128)
+            },
+            accent: accent_color,
+            success: if is_blue_palette {
+                truecolor(96, 165, 250)
+            } else {
+                truecolor(74, 222, 128)
+            },
+            warning: truecolor(245, 158, 11),
+            danger: truecolor(239, 68, 68),
+            border: if is_blue_palette {
+                truecolor(59, 130, 246)
+            } else {
+                truecolor(34, 197, 94)
+            },
+            focus_bg: if is_blue_palette {
+                truecolor_bg(37, 99, 235)
+            } else {
+                truecolor_bg(22, 101, 52)
+            },
+            focus_text: truecolor(248, 250, 252),
+        },
+        UiColorProfile::Ansi256 => UiThemeColors {
+            reset: "\x1b[0m".to_string(),
+            dim: "\x1b[2m".to_string(),
+            muted: ansi256(102),
+            heading: ansi256(255),
+            primary: if is_blue_palette {
+                ansi256(75)
+            } else {
+                ansi256(83)
+            },
+            accent: accent_color,
+            success: if is_blue_palette {
+                ansi256(75)
+            } else {
+                ansi256(83)
+            },
+            warning: ansi256(214),
+            danger: ansi256(196),
+            border: if is_blue_palette {
+                ansi256(27)
+            } else {
+                ansi256(40)
+            },
+            focus_bg: if is_blue_palette {
+                ansi256_bg(26)
+            } else {
+                ansi256_bg(28)
+            },
+            focus_text: ansi256(231),
+        },
+        UiColorProfile::Ansi16 => UiThemeColors {
+            reset: "\x1b[0m".to_string(),
+            dim: "\x1b[2m".to_string(),
+            muted: ansi16(37),
+            heading: ansi16(97),
+            primary: if is_blue_palette {
+                ansi16(94)
+            } else {
+                ansi16(92)
+            },
+            accent: accent_color,
+            success: if is_blue_palette {
+                ansi16(94)
+            } else {
+                ansi16(92)
+            },
+            warning: ansi16(93),
+            danger: ansi16(91),
+            border: if is_blue_palette {
+                ansi16(94)
+            } else {
+                ansi16(92)
+            },
+            focus_bg: if is_blue_palette {
+                "\x1b[104m".to_string()
+            } else {
+                "\x1b[102m".to_string()
+            },
+            focus_text: "\x1b[30m".to_string(),
+        },
+    }
+}
+
+/// Testable core of `shouldDisableColor` (ui-04).
+///
+/// - `force_color` `"0"`/`"false"` (trimmed, lowercased) => disable;
+///   any other non-empty value => force color ON (beats NO_COLOR and non-TTY).
+/// - else `no_color` present as a string (any value, even `""`) => disable.
+/// - else `!is_tty`.
+pub fn should_disable_color_from(
+    force_color: Option<&str>,
+    no_color: Option<&str>,
+    is_tty: bool,
+) -> bool {
+    let force = force_color.unwrap_or("").trim().to_lowercase();
+    if force == "0" || force == "false" {
+        return true;
+    }
+    if !force.is_empty() {
+        return false; // explicit force-on wins over TTY/NO_COLOR
+    }
+    if no_color.is_some() {
+        return true;
+    }
+    !is_tty
+}
+
+/// Live `shouldDisableColor()` — samples the process env and stdout TTY-ness.
+pub fn should_disable_color() -> bool {
+    let force = std::env::var("FORCE_COLOR").ok();
+    let no_color = std::env::var_os("NO_COLOR").map(|v| v.to_string_lossy().into_owned());
+    should_disable_color_from(
+        force.as_deref(),
+        no_color.as_deref(),
+        std::io::stdout().is_terminal(),
+    )
+}
+
+/// Replace every color token with an empty string (color-disabled theme).
+fn strip_colors(_colors: UiThemeColors) -> UiThemeColors {
+    UiThemeColors {
+        reset: String::new(),
+        dim: String::new(),
+        muted: String::new(),
+        heading: String::new(),
+        primary: String::new(),
+        accent: String::new(),
+        success: String::new(),
+        warning: String::new(),
+        danger: String::new(),
+        border: String::new(),
+        focus_bg: String::new(),
+        focus_text: String::new(),
+    }
+}
+
+/// Options bag for [`create_ui_theme`], mirroring the TS optional fields.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct CreateUiThemeOptions {
+    pub profile: Option<UiColorProfile>,
+    pub glyph_mode: Option<UiGlyphMode>,
+    pub palette: Option<UiPalette>,
+    pub accent: Option<UiAccent>,
+    pub disable_color: Option<bool>,
+}
+
+/// Create a UI theme. Defaults: profile `truecolor`, glyphMode `ascii`,
+/// palette `green`, accent `green`; `disable_color` defaults to the live
+/// [`should_disable_color`] result (env + stdout TTY).
+pub fn create_ui_theme(options: CreateUiThemeOptions) -> UiTheme {
+    let profile = options.profile.unwrap_or(UiColorProfile::Truecolor);
+    let glyph_mode = options.glyph_mode.unwrap_or(UiGlyphMode::Ascii);
+    let palette = options.palette.unwrap_or(UiPalette::Green);
+    let accent = options.accent.unwrap_or(UiAccent::Green);
+    let resolved_glyph_mode = resolve_glyph_mode(glyph_mode);
+    let colors = get_colors(profile, palette, accent);
+    // ui-04: honor NO_COLOR / FORCE_COLOR / non-TTY by blanking color tokens.
+    // The caller may also force this explicitly (snapshot-stable output).
+    let disable_color = options.disable_color.unwrap_or_else(should_disable_color);
+    UiTheme {
+        profile,
+        glyph_mode,
+        glyphs: get_glyphs(resolved_glyph_mode),
+        colors: if disable_color {
+            strip_colors(colors)
+        } else {
+            colors
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Ported from test/ui-theme.test.ts. Color-token assertions opt into color
+    // explicitly (disable_color: Some(false)) so the test env's NO_COLOR /
+    // FORCE_COLOR cannot blank the tokens (ui-04).
+
+    #[test]
+    fn uses_defaults_when_options_are_omitted() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        assert_eq!(theme.profile, UiColorProfile::Truecolor);
+        assert_eq!(theme.glyph_mode, UiGlyphMode::Ascii);
+        assert!(!theme.glyphs.selected.is_empty());
+        assert_eq!(theme.colors.reset, "\x1b[0m");
+        assert!(theme.colors.primary.contains("\x1b["));
+        assert!(theme.colors.focus_bg.contains("\x1b["));
+        assert!(theme.colors.focus_text.contains("\x1b["));
+    }
+
+    #[test]
+    fn uses_ansi16_color_profile_when_requested() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            profile: Some(UiColorProfile::Ansi16),
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        assert_eq!(theme.profile, UiColorProfile::Ansi16);
+        assert!(theme.colors.accent.contains("\x1b["));
+        assert_eq!(theme.colors.accent, "\x1b[92m");
+        assert_eq!(theme.colors.focus_bg, "\x1b[102m");
+        assert_eq!(theme.colors.focus_text, "\x1b[30m");
+    }
+
+    #[test]
+    fn uses_ansi256_color_profile_when_requested() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            profile: Some(UiColorProfile::Ansi256),
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        assert_eq!(theme.profile, UiColorProfile::Ansi256);
+        assert!(theme.colors.accent.contains("38;5;"));
+        assert_eq!(theme.colors.accent, "\x1b[38;5;83m");
+        assert_eq!(theme.colors.focus_bg, "\x1b[48;5;28m");
+    }
+
+    #[test]
+    fn supports_blue_palette_and_cyan_accent_overrides() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            profile: Some(UiColorProfile::Truecolor),
+            palette: Some(UiPalette::Blue),
+            accent: Some(UiAccent::Cyan),
+            disable_color: Some(false),
+            ..Default::default()
+        });
+        assert_eq!(theme.colors.primary, "\x1b[38;2;96;165;250m");
+        assert_eq!(theme.colors.accent, "\x1b[38;2;34;211;238m");
+        assert_eq!(theme.colors.focus_bg, "\x1b[48;2;37;99;235m");
+        assert_eq!(theme.colors.border, "\x1b[38;2;59;130;246m");
+    }
+
+    #[test]
+    fn uses_unicode_glyph_set_when_explicitly_requested() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            glyph_mode: Some(UiGlyphMode::Unicode),
+            ..Default::default()
+        });
+        assert_eq!(theme.glyphs.selected, "\u{25c6}");
+        assert_eq!(theme.glyphs.check, "\u{2713}");
+    }
+
+    #[test]
+    fn keeps_ascii_glyph_set_when_explicitly_requested() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            glyph_mode: Some(UiGlyphMode::Ascii),
+            ..Default::default()
+        });
+        assert_eq!(theme.glyphs.selected, ">");
+        assert_eq!(theme.glyphs.check, "+");
+    }
+
+    #[test]
+    fn resolve_glyph_mode_auto_heuristics() {
+        // WT_SESSION defined with ANY value => unicode.
+        assert_eq!(
+            resolve_glyph_mode_from(UiGlyphMode::Auto, true, None, None),
+            UiGlyphMode::Unicode
+        );
+        assert_eq!(
+            resolve_glyph_mode_from(UiGlyphMode::Auto, false, Some("vscode"), None),
+            UiGlyphMode::Unicode
+        );
+        assert_eq!(
+            resolve_glyph_mode_from(UiGlyphMode::Auto, false, None, Some("XTERM-256color")),
+            UiGlyphMode::Unicode
+        );
+        assert_eq!(
+            resolve_glyph_mode_from(UiGlyphMode::Auto, false, Some("iTerm.app"), Some("dumb")),
+            UiGlyphMode::Ascii
+        );
+        // Non-auto modes pass through untouched.
+        assert_eq!(
+            resolve_glyph_mode_from(UiGlyphMode::Ascii, true, Some("vscode"), Some("xterm")),
+            UiGlyphMode::Ascii
+        );
+    }
+
+    #[test]
+    fn no_color_disables_with_any_value() {
+        assert!(should_disable_color_from(None, Some(""), true));
+        assert!(should_disable_color_from(None, Some("1"), true));
+    }
+
+    #[test]
+    fn force_color_zero_disables_even_on_a_tty() {
+        assert!(should_disable_color_from(Some("0"), None, true));
+        assert!(should_disable_color_from(Some("false"), None, true));
+        assert!(should_disable_color_from(Some(" FALSE "), None, true));
+    }
+
+    #[test]
+    fn force_color_truthy_forces_color_on() {
+        assert!(!should_disable_color_from(Some("1"), Some("1"), false));
+    }
+
+    #[test]
+    fn disables_color_when_stdout_is_not_a_tty() {
+        assert!(should_disable_color_from(None, None, false));
+    }
+
+    #[test]
+    fn enables_color_on_a_plain_tty_with_no_overrides() {
+        assert!(!should_disable_color_from(None, None, true));
+    }
+
+    #[test]
+    fn blanks_all_color_tokens_when_disable_color_is_true() {
+        let theme = create_ui_theme(CreateUiThemeOptions {
+            disable_color: Some(true),
+            ..Default::default()
+        });
+        assert_eq!(theme.colors.reset, "");
+        assert_eq!(theme.colors.primary, "");
+        assert_eq!(theme.colors.focus_bg, "");
+        // glyphs are unaffected by color gating
+        assert!(!theme.glyphs.selected.is_empty());
+    }
+}
diff --git a/crates/tui/src/ui_copy.rs b/crates/tui/src/ui_copy.rs
new file mode 100644
index 000000000..1186cd2f0
--- /dev/null
+++ b/crates/tui/src/ui_copy.rs
@@ -0,0 +1,300 @@
+//! Port of `lib/ui/ui-copy.ts` — ALL user-facing copy strings, verbatim.
+//!
+//! The TS `UI_COPY` nested const object maps to nested modules of consts;
+//! function-valued entries become functions. Strings are FROZEN — do not edit
+//! wording, punctuation, or spacing (spec 12 §8 / spec 14 §8).
+
+pub mod main_menu {
+    pub const TITLE: &str = "Accounts Dashboard";
+    pub const SEARCH_SUBTITLE_PREFIX: &str = "Search:";
+    pub const QUICK_START: &str = "Quick Actions";
+    pub const ADD_ACCOUNT: &str = "Add New Account";
+    pub const CHECK_ACCOUNTS: &str = "Run Health Check";
+    pub const BEST_ACCOUNT: &str = "Pick Best Account";
+    pub const FIX_ISSUES: &str = "Auto-Repair Issues";
+    pub const SETTINGS: &str = "Settings";
+    pub const MORE_CHECKS: &str = "Advanced Checks";
+    pub const REFRESH_CHECKS: &str = "Refresh All Accounts";
+    pub const CHECK_FLAGGED: &str = "Check Problem Accounts";
+    pub const ACCOUNTS: &str = "Saved Accounts";
+    pub const LOADING_LIMITS: &str = "Fetching account limits...";
+    pub const NO_SEARCH_MATCHES: &str = "No accounts match your search";
+    pub const DANGER_ZONE: &str = "Danger Zone";
+    pub const REMOVE_ALL_ACCOUNTS: &str = "Delete All Accounts";
+    pub const HELP_COMPACT: &str = "\u{2191}\u{2193} Move | Enter Select | / Search | 1-9 Switch | Q Back";
+    pub const HELP_DETAILED: &str =
+        "Arrow keys move, Enter selects, / searches, 1-9 switches account, Q goes back";
+}
+
+pub mod account_details {
+    pub const BACK: &str = "Back";
+    pub const ENABLE: &str = "Enable Account";
+    pub const DISABLE: &str = "Disable Account";
+    pub const SET_CURRENT: &str = "Set As Current";
+    pub const REFRESH: &str = "Re-Login";
+    pub const REMOVE: &str = "Delete Account";
+    pub const HELP: &str = "\u{2191}\u{2193} Move | Enter Select | S Use | R Sign In | D Delete | Q Back";
+}
+
+pub mod oauth {
+    pub const CHOOSE_MODE_TITLE: &str = "Get Started";
+    pub const CHOOSE_MODE_SUBTITLE: &str = "Choose how you want to continue.";
+    pub const SIGN_IN_HEADING: &str = "Sign in";
+    pub const RESTORE_HEADING: &str = "Recover saved accounts";
+    pub const OPEN_BROWSER: &str = "Open Browser (Easy)";
+    pub const MANUAL_MODE: &str = "Manual / Incognito";
+    pub const RESTORE_SAVED_BACKUP: &str = "Restore Saved Backup";
+    pub const LOAD_LAST_BACKUP: &str = "Load Last Saved Backup (Recommended)";
+    pub const CHOOSE_BACKUP_MANUALLY: &str = "Choose Backup Manually";
+    pub const BACK: &str = "Back";
+    pub const CHOOSE_MODE_HELP: &str =
+        "\u{2191}\u{2193} Move | Enter Select | 1 Easy | 2 Manual | Q Back";
+    pub const CHOOSE_MODE_HELP_WITH_BACKUP: &str =
+        "\u{2191}\u{2193} Move | Enter Select | 1 Easy | 2 Manual | 3 Backup | Q Back";
+    pub const RESTORE_BACKUP_TITLE: &str = "Restore Saved Backup";
+    pub const RESTORE_BACKUP_SUBTITLE: &str = "Choose how you want to recover saved accounts.";
+    pub const RESTORE_BACKUP_LATEST_HINT: &str = "Fastest way to recover your saved accounts.";
+    pub const RESTORE_BACKUP_HELP: &str =
+        "\u{2191}\u{2193} Move | Enter Select | 1 Latest | 2 Manual | Q Back";
+    pub const MANUAL_BACKUP_TITLE: &str = "Choose Backup";
+    pub const MANUAL_BACKUP_SUBTITLE: &str = "Pick a saved backup to restore.";
+    pub const MANUAL_BACKUP_HELP: &str = "\u{2191}\u{2193} Move | Enter Select | Q Back";
+
+    /// `loadLastBackupHint(fileName, accountCount, savedAt)`.
+    pub fn load_last_backup_hint(file_name: &str, account_count: i64, saved_at: &str) -> String {
+        format!(
+            "{file_name} | {account_count} account{} | saved {saved_at}",
+            if account_count == 1 { "" } else { "s" }
+        )
+    }
+
+    /// `manualBackupHint(accountCount, savedAt)`.
+    pub fn manual_backup_hint(account_count: i64, saved_at: &str) -> String {
+        format!(
+            "{account_count} account{} | saved {saved_at}",
+            if account_count == 1 { "" } else { "s" }
+        )
+    }
+
+    /// `restoreBackupConfirm(fileName, accountCount)`.
+    pub fn restore_backup_confirm(file_name: &str, account_count: i64) -> String {
+        format!(
+            "Load {file_name} ({account_count} account{})?",
+            if account_count == 1 { "" } else { "s" }
+        )
+    }
+
+    /// `restoreBackupLoaded(fileName, accountCount)`.
+    pub fn restore_backup_loaded(file_name: &str, account_count: i64) -> String {
+        format!(
+            "Loaded {file_name} ({account_count} account{}).",
+            if account_count == 1 { "" } else { "s" }
+        )
+    }
+
+    pub const RESTORE_BACKUP_SYNC_WARNING: &str = "Backup loaded locally, but Codex auth sync did not complete. Multi-auth routing will still use the restored account pool.";
+    pub const GO_TO: &str = "Go to:";
+    pub const COPY_OK: &str = "Login link copied.";
+    pub const COPY_FAIL: &str = "Could not copy login link.";
+    pub const PASTE_PROMPT: &str = "Paste callback URL or code here (Q to cancel):";
+    pub const BROWSER_OPENED: &str = "Browser opened.";
+    pub const BROWSER_OPEN_FAIL: &str = "Could not open browser. Use this link:";
+    /// `Waiting for login callback on ${AUTH_REDIRECT.host}:${AUTH_REDIRECT.port}...`
+    /// with `AUTH_REDIRECT` parsed from `REDIRECT_URI =
+    /// "http://localhost:1455/auth/callback"` (host `localhost`, port `1455`).
+    pub const WAITING_CALLBACK: &str = "Waiting for login callback on localhost:1455...";
+    pub const CALLBACK_BYPASSED: &str = "Manual mode active. Paste the callback URL manually.";
+    pub const CALLBACK_UNAVAILABLE: &str =
+        "Callback listener unavailable. Paste the callback URL manually.";
+    pub const CALLBACK_MISSED: &str = "No callback received. Paste manually.";
+    pub const CANCELLED: &str = "Sign-in cancelled.";
+    pub const CANCELLED_BACK_TO_MENU: &str = "Sign-in cancelled. Going back to menu.";
+    pub const CALLBACK_INVALID: &str = "That callback URL is missing the code or state parameter. Paste the full URL you were redirected to (it should contain both code= and state=).";
+    pub const CALLBACK_STATE_MISMATCH: &str = "OAuth state mismatch. That callback URL was generated for a different login attempt. Restart login and paste the callback URL from this attempt.";
+}
+
+pub mod return_flow {
+    pub const CONTINUE_PROMPT: &str = "Press Enter to go back.";
+    pub const ACTION_FAILED_PROMPT: &str = "Action failed. Press Enter to go back.";
+
+    /// `autoReturn(seconds)`.
+    pub fn auto_return(seconds: i64) -> String {
+        format!("Returning in {seconds}s... Press any key to pause.")
+    }
+
+    pub const PAUSED: &str = "Paused. Press any key to continue.";
+    pub const WORKING: &str = "Running...";
+    pub const DONE: &str = "Done.";
+    pub const FAILED: &str = "Failed.";
+}
+
+pub mod settings {
+    pub const TITLE: &str = "Settings";
+    pub const SUBTITLE: &str = "Customize menu, behavior, backend, and experiments";
+    pub const HELP: &str = "\u{2191}\u{2193} Move | Enter Select | Q Back";
+    pub const SECTION_TITLE: &str = "Basic";
+    pub const ADVANCED_TITLE: &str = "Advanced";
+    pub const EXIT_TITLE: &str = "Back";
+    pub const ACCOUNT_LIST: &str = "Account List View";
+    pub const SUMMARY_FIELDS: &str = "Summary Line";
+    pub const BEHAVIOR: &str = "Menu Behavior";
+    pub const THEME: &str = "Color Theme";
+    pub const EXPERIMENTAL: &str = "Experimental";
+    pub const EXPERIMENTAL_TITLE: &str = "Experimental";
+    pub const EXPERIMENTAL_SUBTITLE: &str =
+        "Preview sync and backup actions before they become stable";
+    pub const EXPERIMENTAL_HELP_MENU: &str =
+        "Enter Select | 1 Sync | 2 Backup | 3 Guard | [ - Down | ] + Up | S Save | Q Back";
+    pub const EXPERIMENTAL_HELP_PREVIEW: &str = "Enter Select | A Apply | Q Back";
+    pub const EXPERIMENTAL_HELP_STATUS: &str = "Enter Select | Q Back";
+    pub const EXPERIMENTAL_SYNC: &str = "Sync Accounts to oc-chatgpt-multi-auth";
+    pub const EXPERIMENTAL_APPLY_SYNC: &str = "Apply Sync";
+    pub const EXPERIMENTAL_BACKUP: &str = "Save Pool Backup";
+    pub const EXPERIMENTAL_BACKUP_PROMPT: &str = "Backup file name (.json): ";
+    pub const EXPERIMENTAL_REFRESH_GUARD: &str = "Enable Refresh Guard";
+    pub const EXPERIMENTAL_REFRESH_INTERVAL: &str = "Refresh Guard Interval";
+    pub const EXPERIMENTAL_DECREASE_INTERVAL: &str = "Decrease Refresh Interval";
+    pub const EXPERIMENTAL_INCREASE_INTERVAL: &str = "Increase Refresh Interval";
+    pub const BACKEND: &str = "Backend Controls";
+    pub const BACK: &str = "Back";
+    pub const PREVIEW_HEADING: &str = "Live Preview";
+    pub const DISPLAY_HEADING: &str = "Options";
+    pub const RESET_DEFAULT: &str = "Reset to Default";
+    pub const SAVE_AND_BACK: &str = "Save and Back";
+    pub const BACK_NO_SAVE: &str = "Back Without Saving";
+    pub const ACCOUNT_LIST_TITLE: &str = "Account List View";
+    pub const ACCOUNT_LIST_SUBTITLE: &str = "Choose row details and optional smart sorting";
+    pub const ACCOUNT_LIST_HELP: &str =
+        "Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)";
+    pub const SUMMARY_TITLE: &str = "Account Details Row";
+    pub const SUMMARY_SUBTITLE: &str = "Choose and order detail fields";
+    pub const SUMMARY_HELP: &str =
+        "Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)";
+    pub const BEHAVIOR_TITLE: &str = "Return Behavior";
+    pub const BEHAVIOR_SUBTITLE: &str = "Control how result screens return";
+    pub const BEHAVIOR_HELP: &str =
+        "Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)";
+    pub const THEME_TITLE: &str = "Color Theme";
+    pub const THEME_SUBTITLE: &str = "Pick base color and accent";
+    pub const THEME_HELP: &str = "Enter Select | 1-2 Base | S Save | Q Back (No Save)";
+    pub const BACKEND_TITLE: &str = "Backend Controls";
+    pub const BACKEND_SUBTITLE: &str = "Tune sync, retry, and limit behavior";
+    pub const BACKEND_HELP: &str = "Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)";
+    pub const BACKEND_CATEGORIES_HEADING: &str = "Categories";
+    pub const BACKEND_CATEGORY_TITLE: &str = "Backend Category";
+    pub const BACKEND_CATEGORY_HELP: &str =
+        "Enter Toggle/Adjust | +/- or [ ] Number | 1-9 Toggle | R Reset | Q Back";
+    pub const BACKEND_TOGGLE_HEADING: &str = "Switches";
+    pub const BACKEND_NUMBER_HEADING: &str = "Numbers";
+    pub const BACKEND_DECREASE: &str = "Decrease Focused Value";
+    pub const BACKEND_INCREASE: &str = "Increase Focused Value";
+    pub const BACKEND_RESET_CATEGORY: &str = "Reset Category";
+    pub const BACKEND_BACK_TO_CATEGORIES: &str = "Back to Categories";
+    pub const BASE_THEME: &str = "Base Color";
+    pub const ACCENT_COLOR: &str = "Accent Color";
+    pub const ACTION_TIMING: &str = "Auto Return Delay";
+    pub const MOVE_UP: &str = "Move Focused Field Up";
+    pub const MOVE_DOWN: &str = "Move Focused Field Down";
+}
+
+pub mod fallback {
+    pub const ADD_ANOTHER_TIP: &str =
+        "Tip: Use private mode or sign out before adding another account.";
+
+    /// `addAnotherQuestion(count)`.
+    pub fn add_another_question(count: i64) -> String {
+        format!("Add another account? ({count} added) (y/n): ")
+    }
+
+    pub const SELECT_MODE_PROMPT: &str = "(a) add, (c) check, (b) best, fi(x), (s) settings, (d) deep, (g) problem, (f) fresh, (q) back [a/c/b/x/s/d/g/f/q]: ";
+    pub const INVALID_MODE_PROMPT: &str = "Use one of: a, c, b, x, s, d, g, f, q.";
+}
+
+/// `formatCheckFlaggedLabel(flaggedCount)` — appends the flagged count when
+/// greater than zero.
+pub fn format_check_flagged_label(flagged_count: i64) -> String {
+    if flagged_count > 0 {
+        format!("{} ({flagged_count})", main_menu::CHECK_FLAGGED)
+    } else {
+        main_menu::CHECK_FLAGGED.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn format_check_flagged_label_appends_count_only_when_positive() {
+        assert_eq!(format_check_flagged_label(0), "Check Problem Accounts");
+        assert_eq!(format_check_flagged_label(-1), "Check Problem Accounts");
+        assert_eq!(format_check_flagged_label(3), "Check Problem Accounts (3)");
+    }
+
+    #[test]
+    fn key_strings_are_frozen() {
+        assert_eq!(main_menu::TITLE, "Accounts Dashboard");
+        assert_eq!(
+            main_menu::HELP_COMPACT,
+            "↑↓ Move | Enter Select | / Search | 1-9 Switch | Q Back"
+        );
+        assert_eq!(
+            main_menu::HELP_DETAILED,
+            "Arrow keys move, Enter selects, / searches, 1-9 switches account, Q goes back"
+        );
+        assert_eq!(
+            account_details::HELP,
+            "↑↓ Move | Enter Select | S Use | R Sign In | D Delete | Q Back"
+        );
+        assert_eq!(
+            oauth::WAITING_CALLBACK,
+            "Waiting for login callback on localhost:1455..."
+        );
+        assert_eq!(
+            oauth::PASTE_PROMPT,
+            "Paste callback URL or code here (Q to cancel):"
+        );
+        assert_eq!(
+            settings::EXPERIMENTAL_SYNC,
+            "Sync Accounts to oc-chatgpt-multi-auth"
+        );
+        assert_eq!(
+            settings::EXPERIMENTAL_BACKUP_PROMPT,
+            "Backup file name (.json): "
+        );
+        assert_eq!(
+            fallback::SELECT_MODE_PROMPT,
+            "(a) add, (c) check, (b) best, fi(x), (s) settings, (d) deep, (g) problem, (f) fresh, (q) back [a/c/b/x/s/d/g/f/q]: "
+        );
+        assert_eq!(fallback::INVALID_MODE_PROMPT, "Use one of: a, c, b, x, s, d, g, f, q.");
+    }
+
+    #[test]
+    fn function_valued_entries_pluralize_exactly() {
+        assert_eq!(
+            oauth::load_last_backup_hint("pool.json", 1, "2026-07-01"),
+            "pool.json | 1 account | saved 2026-07-01"
+        );
+        assert_eq!(
+            oauth::load_last_backup_hint("pool.json", 2, "2026-07-01"),
+            "pool.json | 2 accounts | saved 2026-07-01"
+        );
+        assert_eq!(oauth::manual_backup_hint(0, "x"), "0 accounts | saved x");
+        assert_eq!(
+            oauth::restore_backup_confirm("a.json", 1),
+            "Load a.json (1 account)?"
+        );
+        assert_eq!(
+            oauth::restore_backup_loaded("a.json", 5),
+            "Loaded a.json (5 accounts)."
+        );
+        assert_eq!(
+            return_flow::auto_return(3),
+            "Returning in 3s... Press any key to pause."
+        );
+        assert_eq!(
+            fallback::add_another_question(2),
+            "Add another account? (2 added) (y/n): "
+        );
+    }
+}
diff --git a/crates/usage/Cargo.toml b/crates/usage/Cargo.toml
new file mode 100644
index 000000000..9320f7d74
--- /dev/null
+++ b/crates/usage/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "cma-usage"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+rand.workspace = true
+uuid.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/usage/src/ledger.rs b/crates/usage/src/ledger.rs
new file mode 100644
index 000000000..db9147ab0
--- /dev/null
+++ b/crates/usage/src/ledger.rs
@@ -0,0 +1,1120 @@
+//! Port of `lib/usage/ledger.ts` — JSONL append-only ledger with a
+//! cross-process lock file, read/summarize/rotate.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §5.4. Key contracts:
+//! - Paths are RECOMPUTED on every call (env can change under tests).
+//! - Cross-process lock = `{current}.lock` created with O_EXCL (`create_new`),
+//!   stale after 30 s (mtime), max wait 10 s → `Timed out waiting for usage
+//!   ledger lock: {path}`.
+//! - In-process serialization: appends and rotates share one FIFO queue.
+//! - Read-side validation is STRICTER than write-side
+//!   ([`normalize_parsed_usage_row`]): rows missing `version: 1`, a non-empty
+//!   `id`, a finite `createdAt`, or a `tokens` record are dropped silently.
+//! - Rotation renames to `usage-ledger.<stamp>.jsonl` where the stamp is the
+//!   ISO timestamp with `-`/`:` removed and the FIRST `.` removed
+//!   (`20260102T030405006Z`).
+//! - Bucket `costUsd` re-rounds through `Number(x.toFixed(8))` at EVERY
+//!   accumulation step ([`crate::pricing::js_to_fixed_8`]).
+
+use std::fs;
+use std::io;
+use std::io::Write as _;
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+
+use cma_core::fs_retry::{Backoff, RetryOptions, code_of, with_retry};
+use cma_core::json_io::{file_mtime_ms, read_text_file, stringify_compact};
+use cma_core::logger::log_warn;
+use cma_core::runtime_paths::get_codex_multi_auth_dir;
+use cma_core::utils::{now_ms, sleep};
+
+use crate::pricing::js_to_fixed_8;
+use crate::redaction::{normalize_usage_ledger_row, usage_row_to_json_line};
+use crate::types::{
+    UsageLedgerAccountRef, UsageLedgerAppendInput, UsageLedgerOperation, UsageLedgerOutcome,
+    UsageLedgerPaths, UsageLedgerQuery, UsageLedgerRow, UsageLedgerSource, UsageSummary,
+    UsageSummaryBucket, UsageSummaryGroupBy, UsageSummaryQuery, UsageTokenCounts, js_trim,
+};
+
+const USAGE_DIR_NAME: &str = "usage";
+const USAGE_LEDGER_FILE_NAME: &str = "usage-ledger.jsonl";
+const RETRYABLE_FS_CODES: &[&str] = &["EBUSY", "EPERM"];
+/// EEXIST is what a held lock produces on `create_new`.
+const LOCK_RETRYABLE_FS_CODES: &[&str] = &["EACCES", "EBUSY", "EEXIST", "EPERM"];
+const LOCK_STALE_MS: f64 = 30_000.0;
+const LOCK_MAX_WAIT_MS: i64 = 10_000;
+
+/// In-process append/rotate serialization (the TS module promise chain).
+/// tokio's Mutex is fair FIFO, matching the chained-promise ordering.
+static APPEND_QUEUE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+/// TS `resetUsageLedgerQueueForTests` re-armed a possibly-rejected promise
+/// chain; the tokio mutex cannot be poisoned by a failed task, so this is a
+/// no-op kept for API parity.
+pub fn reset_usage_ledger_queue_for_tests() {}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/// `getUsageLedgerPaths` — `<multiAuthDir>/usage/usage-ledger.jsonl`.
+/// Recomputed on every call — never cache at module load.
+pub fn get_usage_ledger_paths() -> UsageLedgerPaths {
+    let dir = get_codex_multi_auth_dir().join(USAGE_DIR_NAME);
+    let current = dir.join(USAGE_LEDGER_FILE_NAME);
+    UsageLedgerPaths { dir, current }
+}
+
+fn lock_path_for(current: &Path) -> PathBuf {
+    let mut os = current.as_os_str().to_os_string();
+    os.push(".lock");
+    PathBuf::from(os)
+}
+
+fn basename(path: &Path) -> String {
+    path.file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default()
+}
+
+fn make_ledger_dir(dir: &Path) -> io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::DirBuilderExt;
+        fs::DirBuilder::new().recursive(true).mode(0o700).create(dir)
+    }
+    #[cfg(not(unix))]
+    {
+        fs::create_dir_all(dir)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Retry helpers (per-site schedules copied from the TS source)
+// ---------------------------------------------------------------------------
+
+/// TS backoff `10 * 2 ** attempt` with a 0-based attempt index == our
+/// 1-based `10 * 2^(n-1)` → 10/20/40/80 ms between the 5 attempts.
+fn ledger_backoff() -> Backoff {
+    Backoff::from_fn(|attempt| 10u64.saturating_mul(2u64.saturating_pow(attempt.saturating_sub(1))))
+}
+
+fn retry_options() -> RetryOptions<io::Error> {
+    RetryOptions::new(5, ledger_backoff()).with_codes(RETRYABLE_FS_CODES)
+}
+
+/// `unlinkWithRetry` — ENOENT is success; EBUSY/EPERM retried ×5.
+async fn unlink_with_retry(path: &Path) -> io::Result<()> {
+    with_retry(
+        || async {
+            match fs::remove_file(path) {
+                Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+                result => result,
+            }
+        },
+        retry_options(),
+    )
+    .await
+}
+
+async fn rename_with_retry(from: &Path, to: &Path) -> io::Result<()> {
+    with_retry(|| async { fs::rename(from, to) }, retry_options()).await
+}
+
+async fn read_file_with_retry(path: &Path) -> io::Result<String> {
+    // Node `readFile(path, "utf8")` decodes lossily; `read_text_file` matches.
+    with_retry(|| async { read_text_file(path) }, retry_options()).await
+}
+
+// ---------------------------------------------------------------------------
+// Cross-process append lock
+// ---------------------------------------------------------------------------
+
+struct AppendLock {
+    lock_path: PathBuf,
+    file: Option<fs::File>,
+    released: bool,
+}
+
+impl AppendLock {
+    /// Idempotent release: close the handle (drop — Rust cannot observe or
+    /// retry close failures the way the TS handle.close() loop did), then
+    /// unlink the lock with retry.
+    async fn release(&mut self) -> io::Result<()> {
+        if self.released {
+            return Ok(());
+        }
+        self.released = true;
+        drop(self.file.take());
+        unlink_with_retry(&self.lock_path).await
+    }
+}
+
+impl Drop for AppendLock {
+    fn drop(&mut self) {
+        // Panic-safety net only — every non-panicking path calls release().
+        if !self.released {
+            self.released = true;
+            drop(self.file.take());
+            let _ = fs::remove_file(&self.lock_path);
+        }
+    }
+}
+
+fn is_lock_retryable(error: &io::Error) -> bool {
+    matches!(code_of(error), Some(code) if LOCK_RETRYABLE_FS_CODES.contains(&code))
+}
+
+/// One O_EXCL claim attempt: create the lock file exclusively and write the
+/// `{"pid":…,"createdAt":…}` metadata line. On failure returns the handle (if
+/// one was opened) so the caller can clean up, plus the error.
+fn try_create_lock(lock_path: &Path) -> Result<AppendLock, (Option<fs::File>, io::Error)> {
+    let mut options = fs::OpenOptions::new();
+    options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    let mut file = match options.open(lock_path) {
+        Ok(file) => file,
+        Err(error) => return Err((None, error)),
+    };
+    let metadata = format!(
+        "{}\n",
+        stringify_compact(&serde_json::json!({
+            "pid": std::process::id(),
+            "createdAt": now_ms(),
+        }))
+    );
+    if let Err(error) = file.write_all(metadata.as_bytes()) {
+        return Err((Some(file), error));
+    }
+    Ok(AppendLock {
+        lock_path: lock_path.to_path_buf(),
+        file: Some(file),
+        released: false,
+    })
+}
+
+/// `removeStaleLockIfNeeded` — leave locks younger than 30 s alone; unlink
+/// older ones. A missing lock counts as removed.
+async fn remove_stale_lock_if_needed(lock_path: &Path) -> io::Result<bool> {
+    match file_mtime_ms(lock_path)? {
+        Some(mtime_ms) => {
+            if (now_ms() as f64) - mtime_ms < LOCK_STALE_MS {
+                return Ok(false);
+            }
+            unlink_with_retry(lock_path).await?;
+            Ok(true)
+        }
+        None => Ok(true),
+    }
+}
+
+/// `acquireAppendLock` — O_EXCL create loop with stale takeover (30 s) and a
+/// 10 s wait budget.
+async fn acquire_append_lock(lock_path: &Path) -> io::Result<AppendLock> {
+    let started = now_ms();
+    let mut attempt: u32 = 0;
+    loop {
+        match try_create_lock(lock_path) {
+            Ok(lock) => return Ok(lock),
+            Err((opened_handle, error)) => {
+                if let Some(handle) = opened_handle {
+                    // Best-effort cleanup after a failed lock metadata write
+                    // (close is swallowed; the unlink error propagates, as in
+                    // the TS catch block).
+                    drop(handle);
+                    unlink_with_retry(lock_path).await?;
+                }
+                if !is_lock_retryable(&error) {
+                    return Err(error);
+                }
+                remove_stale_lock_if_needed(lock_path).await?;
+                if now_ms() - started >= LOCK_MAX_WAIT_MS {
+                    return Err(io::Error::other(format!(
+                        "Timed out waiting for usage ledger lock: {}",
+                        lock_path.display()
+                    )));
+                }
+                sleep(
+                    250u64.min(10u64.saturating_mul(2u64.saturating_pow(attempt.min(5)))),
+                )
+                .await;
+                attempt += 1;
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Append
+// ---------------------------------------------------------------------------
+
+fn append_line(path: &Path, line: &str) -> io::Result<()> {
+    let mut options = fs::OpenOptions::new();
+    options.create(true).append(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        // Applied only when the file is created — Node appendFile parity.
+        options.mode(0o600);
+    }
+    let mut file = options.open(path)?;
+    file.write_all(line.as_bytes())
+}
+
+/// `appendFileWithRetry` — lock, append (retry EBUSY/EPERM ×5), release in a
+/// finally. A release failure overrides the body result (JS finally-throw
+/// semantics).
+async fn append_file_with_retry(path: &Path, line: &str) -> io::Result<()> {
+    let mut lock = acquire_append_lock(&lock_path_for(path)).await?;
+    let result = with_retry(|| async { append_line(path, line) }, retry_options()).await;
+    let release_result = lock.release().await;
+    release_result?;
+    result
+}
+
+/// `appendUsageLedgerRow` — normalize, serialize (single compact JSONL line),
+/// then append under both the in-process queue and the cross-process lock.
+/// Returns the normalized row.
+pub async fn append_usage_ledger_row(
+    input: &UsageLedgerAppendInput,
+) -> io::Result<UsageLedgerRow> {
+    let row = normalize_usage_ledger_row(input);
+    let paths = get_usage_ledger_paths();
+    let line = usage_row_to_json_line(&row);
+    {
+        let _queue = APPEND_QUEUE.lock().await;
+        make_ledger_dir(&paths.dir)?;
+        append_file_with_retry(&paths.current, &line).await?;
+    }
+    Ok(row)
+}
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+fn value_as_finite_f64(value: Option<&Value>) -> Option<f64> {
+    value.and_then(Value::as_f64).filter(|v| v.is_finite())
+}
+
+fn value_as_string(value: Option<&Value>) -> Option<String> {
+    value.and_then(Value::as_str).map(str::to_string)
+}
+
+fn parsed_token_count(tokens: &Value, key: &str) -> u64 {
+    match value_as_finite_f64(tokens.get(key)) {
+        Some(numeric) => {
+            let truncated = numeric.trunc();
+            if truncated <= 0.0 { 0 } else { truncated as u64 }
+        }
+        None => 0,
+    }
+}
+
+/// `normalizeParsedUsageRow` — read-side validation, STRICTER than write-side:
+/// requires `version === 1`, a non-empty string `id`, a finite `createdAt`
+/// and a `tokens` record; otherwise the row is dropped (`None`, silent).
+pub fn normalize_parsed_usage_row(value: &Value) -> Option<UsageLedgerRow> {
+    if !value.is_object() {
+        return None;
+    }
+    if value.get("version").and_then(Value::as_f64) != Some(1.0) {
+        return None;
+    }
+    let id = value.get("id").and_then(Value::as_str)?;
+    if js_trim(id).is_empty() {
+        return None;
+    }
+    let created_at = value_as_finite_f64(value.get("createdAt"))?;
+    let tokens_value = value.get("tokens").filter(|t| t.is_object())?;
+
+    let source = value
+        .get("source")
+        .and_then(Value::as_str)
+        .and_then(UsageLedgerSource::parse)
+        .unwrap_or(UsageLedgerSource::Unknown);
+    let operation = value
+        .get("operation")
+        .and_then(Value::as_str)
+        .and_then(UsageLedgerOperation::parse)
+        .unwrap_or(UsageLedgerOperation::Unknown);
+    let outcome = value
+        .get("outcome")
+        .and_then(Value::as_str)
+        .and_then(UsageLedgerOutcome::parse)
+        .unwrap_or(UsageLedgerOutcome::Failure);
+    let tokens = UsageTokenCounts {
+        input_tokens: parsed_token_count(tokens_value, "inputTokens"),
+        output_tokens: parsed_token_count(tokens_value, "outputTokens"),
+        cached_input_tokens: parsed_token_count(tokens_value, "cachedInputTokens"),
+        reasoning_tokens: parsed_token_count(tokens_value, "reasoningTokens"),
+        total_tokens: parsed_token_count(tokens_value, "totalTokens"),
+    };
+    let account = value
+        .get("account")
+        .filter(|a| a.is_object())
+        .map(|a| UsageLedgerAccountRef {
+            account_hash: value_as_string(a.get("accountHash"))
+                .filter(|hash| hash.starts_with("sha256:")),
+            email_hash: value_as_string(a.get("emailHash"))
+                .filter(|hash| hash.starts_with("sha256:")),
+            index: value_as_finite_f64(a.get("index"))
+                .filter(|v| v.fract() == 0.0 && *v >= 0.0)
+                .map(|v| v as u64),
+        })
+        .filter(|a| a.account_hash.is_some() || a.email_hash.is_some() || a.index.is_some());
+
+    Some(UsageLedgerRow {
+        version: 1,
+        id: id.to_string(),
+        created_at,
+        source,
+        operation,
+        outcome,
+        model: value_as_string(value.get("model")),
+        project_key: value_as_string(value.get("projectKey")),
+        account,
+        request_id: value_as_string(value.get("requestId")),
+        status_code: value_as_finite_f64(value.get("statusCode"))
+            .filter(|v| v.fract() == 0.0 && (100.0..=599.0).contains(v))
+            .map(|v| v as u16),
+        error_code: value_as_string(value.get("errorCode")),
+        duration_ms: value_as_finite_f64(value.get("durationMs")).map(|v| {
+            let truncated = v.trunc();
+            if truncated <= 0.0 { 0 } else { truncated as u64 }
+        }),
+        tokens,
+        cost_usd: value_as_finite_f64(value.get("costUsd")).map(|v| v.max(0.0)),
+    })
+}
+
+fn parse_jsonl_rows(content: &str, label: &str) -> Vec<UsageLedgerRow> {
+    let mut rows = Vec::new();
+    for (index, line) in content.split('\n').enumerate() {
+        let trimmed = js_trim(line);
+        if trimmed.is_empty() {
+            continue;
+        }
+        match serde_json::from_str::<Value>(trimmed) {
+            Ok(parsed) => {
+                if let Some(row) = normalize_parsed_usage_row(&parsed) {
+                    rows.push(row);
+                }
+            }
+            Err(error) => {
+                log_warn(
+                    &format!(
+                        "Skipped malformed usage ledger row in {label}:{}: {error}",
+                        index + 1
+                    ),
+                    None,
+                );
+            }
+        }
+    }
+    rows
+}
+
+/// The archive-name filter: `^usage-ledger(?:\.\d{8}T\d{6}\d{3}Z)?\.jsonl$`.
+fn is_ledger_file_name(name: &str) -> bool {
+    if name == USAGE_LEDGER_FILE_NAME {
+        return true;
+    }
+    let Some(rest) = name.strip_prefix("usage-ledger.") else {
+        return false;
+    };
+    let Some(stamp) = rest.strip_suffix(".jsonl") else {
+        return false;
+    };
+    let bytes = stamp.as_bytes();
+    bytes.len() == 19
+        && bytes[8] == b'T'
+        && bytes[18] == b'Z'
+        && bytes[..8].iter().all(u8::is_ascii_digit)
+        && bytes[9..18].iter().all(u8::is_ascii_digit)
+}
+
+fn list_ledger_files(include_archives: bool) -> io::Result<Vec<PathBuf>> {
+    let UsageLedgerPaths { dir, current } = get_usage_ledger_paths();
+    if !include_archives {
+        return Ok(if current.exists() { vec![current] } else { vec![] });
+    }
+    if !dir.exists() {
+        return Ok(Vec::new());
+    }
+    let mut names: Vec<String> = fs::read_dir(&dir)?
+        .filter_map(|entry| entry.ok())
+        .map(|entry| entry.file_name().to_string_lossy().into_owned())
+        .filter(|name| is_ledger_file_name(name))
+        .collect();
+    names.sort();
+    Ok(names.into_iter().map(|name| dir.join(name)).collect())
+}
+
+fn normalize_timestamp(value: Option<f64>) -> Option<f64> {
+    value.filter(|v| v.is_finite())
+}
+
+fn row_in_range(row: &UsageLedgerRow, since: Option<f64>, until: Option<f64>) -> bool {
+    if let Some(since) = since
+        && row.created_at < since
+    {
+        return false;
+    }
+    if let Some(until) = until
+        && row.created_at > until
+    {
+        return false;
+    }
+    true
+}
+
+/// `readUsageLedgerRows` — per-file read failures are warned and skipped;
+/// malformed lines are warned and skipped; invalid rows are dropped silently.
+/// Result is filtered by `since`/`until` (inclusive) and sorted ascending by
+/// `createdAt` (stable).
+pub async fn read_usage_ledger_rows(query: &UsageLedgerQuery) -> io::Result<Vec<UsageLedgerRow>> {
+    let mut rows: Vec<UsageLedgerRow> = Vec::new();
+    for file in list_ledger_files(query.include_archives)? {
+        match read_file_with_retry(&file).await {
+            Ok(content) => rows.extend(parse_jsonl_rows(&content, &basename(&file))),
+            Err(error) => {
+                log_warn(
+                    &format!("Failed to read usage ledger {}: {error}", basename(&file)),
+                    None,
+                );
+            }
+        }
+    }
+    let since = normalize_timestamp(query.since);
+    let until = normalize_timestamp(query.until);
+    rows.retain(|row| row_in_range(row, since, until));
+    rows.sort_by(|a, b| a.created_at.total_cmp(&b.created_at));
+    Ok(rows)
+}
+
+// ---------------------------------------------------------------------------
+// Summaries
+// ---------------------------------------------------------------------------
+
+fn create_bucket(key: String) -> UsageSummaryBucket {
+    UsageSummaryBucket {
+        key,
+        requests: 0,
+        successes: 0,
+        failures: 0,
+        blocked: 0,
+        cancelled: 0,
+        input_tokens: 0,
+        output_tokens: 0,
+        cached_input_tokens: 0,
+        reasoning_tokens: 0,
+        total_tokens: 0,
+        cost_usd: 0.0,
+    }
+}
+
+fn get_bucket_key(row: &UsageLedgerRow, by: UsageSummaryGroupBy) -> String {
+    match by {
+        UsageSummaryGroupBy::Account => row
+            .account
+            .as_ref()
+            .and_then(|account| {
+                account
+                    .account_hash
+                    .clone()
+                    .or_else(|| account.email_hash.clone())
+            })
+            .unwrap_or_else(|| "unknown".to_string()),
+        UsageSummaryGroupBy::Project => row
+            .project_key
+            .clone()
+            .unwrap_or_else(|| "global".to_string()),
+        UsageSummaryGroupBy::Outcome => row.outcome.as_str().to_string(),
+        UsageSummaryGroupBy::Day => js_to_iso_string(row.created_at)
+            .map(|iso| iso[..10].to_string())
+            // TS would throw RangeError for timestamps outside the JS Date
+            // range (±8.64e15 ms); such rows are pathological — bucket them
+            // as "unknown" instead of failing the whole summary.
+            .unwrap_or_else(|| "unknown".to_string()),
+        UsageSummaryGroupBy::Model => row
+            .model
+            .clone()
+            .unwrap_or_else(|| "unknown".to_string()),
+    }
+}
+
+fn add_row_to_bucket(bucket: &mut UsageSummaryBucket, row: &UsageLedgerRow) {
+    bucket.requests += 1;
+    match row.outcome {
+        UsageLedgerOutcome::Success => bucket.successes += 1,
+        UsageLedgerOutcome::Failure => bucket.failures += 1,
+        UsageLedgerOutcome::Blocked => bucket.blocked += 1,
+        UsageLedgerOutcome::Cancelled => bucket.cancelled += 1,
+    }
+    bucket.input_tokens = bucket.input_tokens.saturating_add(row.tokens.input_tokens);
+    bucket.output_tokens = bucket.output_tokens.saturating_add(row.tokens.output_tokens);
+    bucket.cached_input_tokens = bucket
+        .cached_input_tokens
+        .saturating_add(row.tokens.cached_input_tokens);
+    bucket.reasoning_tokens = bucket
+        .reasoning_tokens
+        .saturating_add(row.tokens.reasoning_tokens);
+    bucket.total_tokens = bucket.total_tokens.saturating_add(row.tokens.total_tokens);
+    // Re-rounded to 8 dp at EVERY add — part of the TS numeric contract.
+    bucket.cost_usd = js_to_fixed_8(bucket.cost_usd + row.cost_usd.unwrap_or(0.0));
+}
+
+/// `summarizeUsageRows` — filter + sort again, accumulate totals and per-key
+/// buckets, buckets sorted by key.
+pub fn summarize_usage_rows(rows: &[UsageLedgerRow], query: &UsageSummaryQuery) -> UsageSummary {
+    let by = query.by.unwrap_or_default();
+    let since = normalize_timestamp(query.since);
+    let until = normalize_timestamp(query.until);
+    let mut filtered: Vec<&UsageLedgerRow> = rows
+        .iter()
+        .filter(|row| row_in_range(row, since, until))
+        .collect();
+    filtered.sort_by(|a, b| a.created_at.total_cmp(&b.created_at));
+
+    let mut totals = create_bucket("total".to_string());
+    let mut buckets: Vec<UsageSummaryBucket> = Vec::new();
+    for row in filtered {
+        add_row_to_bucket(&mut totals, row);
+        let key = get_bucket_key(row, by);
+        match buckets.iter_mut().find(|bucket| bucket.key == key) {
+            Some(bucket) => add_row_to_bucket(bucket, row),
+            None => {
+                let mut bucket = create_bucket(key);
+                add_row_to_bucket(&mut bucket, row);
+                buckets.push(bucket);
+            }
+        }
+    }
+    // TS sorts with localeCompare; ledger keys are ASCII (hashes, model ids,
+    // ISO dates, "unknown"/"global"), where byte order coincides.
+    buckets.sort_by(|a, b| a.key.cmp(&b.key));
+
+    UsageSummary {
+        since,
+        until,
+        by,
+        totals,
+        buckets,
+    }
+}
+
+/// `summarizeUsageLedger` — read + summarize.
+pub async fn summarize_usage_ledger(query: &UsageSummaryQuery) -> io::Result<UsageSummary> {
+    let rows = read_usage_ledger_rows(&query.ledger_query()).await?;
+    Ok(summarize_usage_rows(&rows, query))
+}
+
+// ---------------------------------------------------------------------------
+// Rotation
+// ---------------------------------------------------------------------------
+
+/// Options for [`rotate_usage_ledger`].
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RotateUsageLedgerOptions {
+    /// Timestamp for the archive stamp (epoch ms); defaults to now.
+    pub now: Option<f64>,
+    /// Skip rotation when the current ledger is at most this many bytes.
+    pub if_larger_than_bytes: Option<u64>,
+}
+
+async fn rotate_locked(
+    paths: &UsageLedgerPaths,
+    options: &RotateUsageLedgerOptions,
+) -> io::Result<Option<PathBuf>> {
+    if !paths.current.exists() {
+        return Ok(None);
+    }
+    let metadata = fs::metadata(&paths.current)?;
+    if let Some(threshold) = options.if_larger_than_bytes
+        && metadata.len() <= threshold
+    {
+        return Ok(None);
+    }
+    let now = options.now.unwrap_or_else(|| now_ms() as f64);
+    let iso = js_to_iso_string(now)
+        .ok_or_else(|| io::Error::other("Invalid time value"))?;
+    // `.replace(/[-:]/g, "")` then `.replace(".", "")` (FIRST dot only — the
+    // millisecond separator).
+    let mut stamp: String = iso.chars().filter(|c| !matches!(c, '-' | ':')).collect();
+    if let Some(dot) = stamp.find('.') {
+        stamp.remove(dot);
+    }
+    let rotated = paths.dir.join(format!("usage-ledger.{stamp}.jsonl"));
+    rename_with_retry(&paths.current, &rotated).await?;
+    Ok(Some(rotated))
+}
+
+/// `rotateUsageLedger` — queued + locked rename of the current ledger to
+/// `usage-ledger.<stamp>.jsonl`; `None` when there is nothing to rotate or
+/// the size threshold is not exceeded.
+pub async fn rotate_usage_ledger(
+    options: &RotateUsageLedgerOptions,
+) -> io::Result<Option<PathBuf>> {
+    let paths = get_usage_ledger_paths();
+    let _queue = APPEND_QUEUE.lock().await;
+    make_ledger_dir(&paths.dir)?;
+    let mut lock = acquire_append_lock(&lock_path_for(&paths.current)).await?;
+    let result = rotate_locked(&paths, options).await;
+    let release_result = lock.release().await;
+    release_result?;
+    result
+}
+
+// ---------------------------------------------------------------------------
+// ECMAScript Date.prototype.toISOString
+// ---------------------------------------------------------------------------
+
+/// `new Date(ms).toISOString()` — `None` where JS throws (non-finite input or
+/// |time| > 8.64e15 after truncation toward zero). Years outside 0000–9999
+/// use the JS expanded-year form (`±YYYYYY`).
+fn js_to_iso_string(ms: f64) -> Option<String> {
+    if !ms.is_finite() {
+        return None;
+    }
+    let time = ms.trunc();
+    if time.abs() > 8.64e15 {
+        return None;
+    }
+    let time = time as i64;
+    let days = time.div_euclid(86_400_000);
+    let ms_of_day = time.rem_euclid(86_400_000);
+    let (year, month, day) = civil_from_days(days);
+    let hours = ms_of_day / 3_600_000;
+    let minutes = (ms_of_day % 3_600_000) / 60_000;
+    let seconds = (ms_of_day % 60_000) / 1_000;
+    let millis = ms_of_day % 1_000;
+    let year_part = if (0..=9999).contains(&year) {
+        format!("{year:04}")
+    } else if year < 0 {
+        format!("-{:06}", -year)
+    } else {
+        format!("+{year:06}")
+    };
+    Some(format!(
+        "{year_part}-{month:02}-{day:02}T{hours:02}:{minutes:02}:{seconds:02}.{millis:03}Z"
+    ))
+}
+
+/// Days-since-epoch → proleptic Gregorian civil date (Howard Hinnant's
+/// `civil_from_days`, exact for the whole JS Date range).
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let day_of_era = z - era * 146_097; // [0, 146096]
+    let year_of_era =
+        (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
+    let year = year_of_era + era * 400;
+    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
+    let mp = (5 * day_of_year + 2) / 153;
+    let day = (day_of_year - (153 * mp + 2) / 5 + 1) as u32;
+    let month = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    (if month <= 2 { year + 1 } else { year }, month, day)
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/usage-ledger.test.ts)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_testkit::sandbox::EnvSandbox;
+    use serial_test::serial;
+
+    fn append_input(id: &str, created_at: f64, outcome: &str, model: Option<&str>) -> UsageLedgerAppendInput {
+        UsageLedgerAppendInput {
+            id: Some(id.to_string()),
+            created_at: Some(created_at),
+            outcome: Some(outcome.to_string()),
+            model: model.map(str::to_string),
+            ..Default::default()
+        }
+    }
+
+    fn set_lock_mtime_stale(lock_path: &Path) {
+        let file = fs::OpenOptions::new()
+            .write(true)
+            .open(lock_path)
+            .expect("open lock for utimes");
+        file.set_modified(std::time::SystemTime::now() - std::time::Duration::from_secs(60))
+            .expect("set stale mtime");
+    }
+
+    // ----- pure helpers -----
+
+    #[test]
+    fn iso_string_matches_ecmascript_to_iso_string() {
+        assert_eq!(js_to_iso_string(0.0).unwrap(), "1970-01-01T00:00:00.000Z");
+        assert_eq!(js_to_iso_string(-1.0).unwrap(), "1969-12-31T23:59:59.999Z");
+        // Date.UTC(2026, 0, 2, 3, 4, 5, 6)
+        assert_eq!(
+            js_to_iso_string(1_767_323_045_006.0).unwrap(),
+            "2026-01-02T03:04:05.006Z"
+        );
+        assert_eq!(js_to_iso_string(f64::NAN), None);
+        assert_eq!(js_to_iso_string(8.641e15), None);
+    }
+
+    #[test]
+    fn ledger_file_name_filter_matches_the_ts_regex() {
+        assert!(is_ledger_file_name("usage-ledger.jsonl"));
+        assert!(is_ledger_file_name("usage-ledger.20260102T030405006Z.jsonl"));
+        assert!(!is_ledger_file_name("usage-ledger.20260102T030405006Z.jsonl.lock"));
+        assert!(!is_ledger_file_name("usage-ledger.2026T030405006Z.jsonl"));
+        assert!(!is_ledger_file_name("usage-ledger.20260102X030405006Z.jsonl"));
+        assert!(!is_ledger_file_name("other-file.jsonl"));
+        assert!(!is_ledger_file_name("usage-ledger..jsonl"));
+    }
+
+    #[test]
+    fn parsed_row_validation_is_stricter_than_write_side() {
+        // version must be 1
+        assert!(normalize_parsed_usage_row(&serde_json::json!({
+            "version": 2, "id": "x", "createdAt": 1, "tokens": {}
+        }))
+        .is_none());
+        // id must be a non-empty string
+        assert!(normalize_parsed_usage_row(&serde_json::json!({
+            "version": 1, "id": "  ", "createdAt": 1, "tokens": {}
+        }))
+        .is_none());
+        // createdAt must be a finite number
+        assert!(normalize_parsed_usage_row(&serde_json::json!({
+            "version": 1, "id": "x", "createdAt": "soon", "tokens": {}
+        }))
+        .is_none());
+        // tokens must be a record
+        assert!(normalize_parsed_usage_row(&serde_json::json!({
+            "version": 1, "id": "x", "createdAt": 1, "tokens": 5
+        }))
+        .is_none());
+
+        let row = normalize_parsed_usage_row(&serde_json::json!({
+            "version": 1,
+            "id": "x",
+            "createdAt": 1,
+            "source": "not-a-source",
+            "operation": "responses",
+            "outcome": "nope",
+            "tokens": { "inputTokens": 3.9, "outputTokens": -1 },
+            "account": {
+                "accountHash": "md5:nope",
+                "emailHash": "sha256:abc",
+                "index": 1.5
+            },
+            "statusCode": 200,
+            "costUsd": -4,
+            "durationMs": 12.7
+        }))
+        .unwrap();
+        assert_eq!(row.source, UsageLedgerSource::Unknown);
+        assert_eq!(row.operation, UsageLedgerOperation::Responses);
+        assert_eq!(row.outcome, UsageLedgerOutcome::Failure);
+        assert_eq!(row.tokens.input_tokens, 3);
+        assert_eq!(row.tokens.output_tokens, 0);
+        let account = row.account.unwrap();
+        // Hashes without the sha256: prefix are dropped; fractional index too.
+        assert_eq!(account.account_hash, None);
+        assert_eq!(account.email_hash, Some("sha256:abc".to_string()));
+        assert_eq!(account.index, None);
+        assert_eq!(row.status_code, Some(200));
+        assert_eq!(row.cost_usd, Some(0.0));
+        assert_eq!(row.duration_ms, Some(12));
+    }
+
+    // ----- filesystem behavior (EnvSandbox + #[serial(env)]) -----
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn appends_normalized_jsonl_rows_without_raw_identifiers() {
+        let _sandbox = EnvSandbox::new();
+        let row = append_usage_ledger_row(&UsageLedgerAppendInput {
+            id: Some("row-1".to_string()),
+            created_at: Some(1_700_000_000_000.0),
+            source: Some("runtime-proxy".to_string()),
+            operation: Some("responses".to_string()),
+            outcome: Some("success".to_string()),
+            model: Some(" gpt-5.3-codex ".to_string()),
+            account_id: Some("acct_sensitive_123".to_string()),
+            email: Some("Owner@Example.com".to_string()),
+            account_index: Some(2.0),
+            request_id: Some("req_123".to_string()),
+            status_code: Some(200.0),
+            duration_ms: Some(123.9),
+            input_tokens: Some(1_000.0),
+            output_tokens: Some(200.0),
+            cached_input_tokens: Some(50.0),
+            reasoning_tokens: Some(25.0),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex"));
+        let account = row.account.clone().unwrap();
+        assert!(account.account_hash.unwrap().starts_with("sha256:"));
+        assert!(account.email_hash.unwrap().starts_with("sha256:"));
+        assert_eq!(account.index, Some(2));
+        assert_eq!(row.tokens.total_tokens, 1_225);
+        assert_eq!(row.tokens.cached_input_tokens, 50);
+        assert!(row.cost_usd.unwrap() > 0.0);
+        assert_eq!(row.duration_ms, Some(123));
+
+        let raw = fs::read_to_string(get_usage_ledger_paths().current).unwrap();
+        assert!(raw.contains("\"version\":1"));
+        assert!(!raw.contains("acct_sensitive_123"));
+        assert!(!raw.contains("Owner@Example.com"));
+        assert!(!raw.contains("owner@example.com"));
+
+        let read_back = read_usage_ledger_rows(&UsageLedgerQuery::default())
+            .await
+            .unwrap();
+        assert_eq!(read_back, vec![row]);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn append_produces_the_golden_byte_line_on_disk() {
+        let _sandbox = EnvSandbox::new();
+        append_usage_ledger_row(&UsageLedgerAppendInput {
+            id: Some("usage-fixture-0000000000000001".to_string()),
+            created_at: Some(1_750_000_000_000.0),
+            source: Some("runtime-proxy".to_string()),
+            operation: Some("responses".to_string()),
+            outcome: Some("success".to_string()),
+            model: Some("gpt-5.2".to_string()),
+            project_key: Some("my-app-0123456789ab".to_string()),
+            account_id: Some("acct-user-one".to_string()),
+            email: Some("User.One@Example.com".to_string()),
+            account_index: Some(0.0),
+            request_id: Some("req-fixture-0001".to_string()),
+            status_code: Some(200.0),
+            duration_ms: Some(1234.0),
+            input_tokens: Some(1200.0),
+            output_tokens: Some(350.0),
+            cached_input_tokens: Some(800.0),
+            reasoning_tokens: Some(64.0),
+            cost_usd: Some(0.0123),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+        let written = fs::read_to_string(get_usage_ledger_paths().current).unwrap();
+        let golden = cma_testkit::goldens::read_golden_string("usage-ledger-row.jsonl")
+            .replace("\r\n", "\n");
+        assert_eq!(written, golden);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn summarizes_usage_by_model_and_applies_date_filters() {
+        let _sandbox = EnvSandbox::new();
+        for input in [
+            {
+                let mut i = append_input("old", 100.0, "success", Some("gpt-5.3-codex"));
+                i.input_tokens = Some(100.0);
+                i.output_tokens = Some(10.0);
+                i
+            },
+            {
+                let mut i = append_input("new-success", 200.0, "success", Some("gpt-5.3-codex"));
+                i.input_tokens = Some(200.0);
+                i.output_tokens = Some(20.0);
+                i
+            },
+            {
+                let mut i = append_input("new-failure", 300.0, "failure", Some("gpt-5.5"));
+                i.input_tokens = Some(50.0);
+                i.output_tokens = Some(5.0);
+                i
+            },
+        ] {
+            append_usage_ledger_row(&input).await.unwrap();
+        }
+
+        let summary = summarize_usage_ledger(&UsageSummaryQuery {
+            since: Some(150.0),
+            by: Some(UsageSummaryGroupBy::Model),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(summary.totals.requests, 2);
+        assert_eq!(summary.totals.successes, 1);
+        assert_eq!(summary.totals.failures, 1);
+        assert_eq!(summary.totals.input_tokens, 250);
+        assert_eq!(
+            summary
+                .buckets
+                .iter()
+                .map(|bucket| bucket.key.as_str())
+                .collect::<Vec<_>>(),
+            vec!["gpt-5.3-codex", "gpt-5.5"]
+        );
+        assert_eq!(summary.buckets[0].requests, 1);
+        assert_eq!(summary.since, Some(150.0));
+        assert_eq!(summary.until, None);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn rotates_the_current_ledger_and_can_include_archived_rows() {
+        let _sandbox = EnvSandbox::new();
+        append_usage_ledger_row(&append_input("before-rotate", 100.0, "success", Some("gpt-5.3-codex")))
+            .await
+            .unwrap();
+        let paths = get_usage_ledger_paths();
+        let lock_path = lock_path_for(&paths.current);
+        // A stale foreign lock must be taken over during rotation.
+        fs::write(&lock_path, "stale\n").unwrap();
+        set_lock_mtime_stale(&lock_path);
+
+        let rotated = rotate_usage_ledger(&RotateUsageLedgerOptions {
+            now: Some(1_767_323_045_006.0), // Date.UTC(2026, 0, 2, 3, 4, 5, 6)
+            if_larger_than_bytes: None,
+        })
+        .await
+        .unwrap()
+        .expect("rotation performed");
+
+        assert!(
+            rotated
+                .to_string_lossy()
+                .contains("usage-ledger.20260102T030405006Z.jsonl")
+        );
+        assert!(!lock_path.exists());
+        assert!(!paths.current.exists());
+
+        append_usage_ledger_row(&append_input("after-rotate", 200.0, "success", Some("gpt-5.5")))
+            .await
+            .unwrap();
+
+        let current_only = read_usage_ledger_rows(&UsageLedgerQuery::default())
+            .await
+            .unwrap();
+        assert_eq!(
+            current_only.iter().map(|row| row.id.as_str()).collect::<Vec<_>>(),
+            vec!["after-rotate"]
+        );
+        let with_archives = read_usage_ledger_rows(&UsageLedgerQuery {
+            include_archives: true,
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+        assert_eq!(
+            with_archives.iter().map(|row| row.id.as_str()).collect::<Vec<_>>(),
+            vec!["before-rotate", "after-rotate"]
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn skips_rotation_when_below_the_configured_byte_threshold() {
+        let _sandbox = EnvSandbox::new();
+        append_usage_ledger_row(&append_input("small", 100.0, "success", None))
+            .await
+            .unwrap();
+        let rotated = rotate_usage_ledger(&RotateUsageLedgerOptions {
+            now: None,
+            if_larger_than_bytes: Some(1_000_000),
+        })
+        .await
+        .unwrap();
+        assert_eq!(rotated, None);
+        // Nothing to rotate at all → also None (after the ledger is gone).
+        fs::remove_file(get_usage_ledger_paths().current).unwrap();
+        let rotated = rotate_usage_ledger(&RotateUsageLedgerOptions::default())
+            .await
+            .unwrap();
+        assert_eq!(rotated, None);
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn removes_stale_append_locks_before_writing() {
+        let _sandbox = EnvSandbox::new();
+        let paths = get_usage_ledger_paths();
+        make_ledger_dir(&paths.dir).unwrap();
+        let lock_path = lock_path_for(&paths.current);
+        fs::write(&lock_path, "stale\n").unwrap();
+        set_lock_mtime_stale(&lock_path);
+
+        append_usage_ledger_row(&UsageLedgerAppendInput {
+            id: Some("after-stale-lock".to_string()),
+            outcome: Some("success".to_string()),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+
+        assert!(!lock_path.exists());
+        let rows = read_usage_ledger_rows(&UsageLedgerQuery::default())
+            .await
+            .unwrap();
+        assert_eq!(
+            rows.iter().map(|row| row.id.as_str()).collect::<Vec<_>>(),
+            vec!["after-stale-lock"]
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn skips_malformed_lines_but_keeps_valid_rows() {
+        let _sandbox = EnvSandbox::new();
+        let paths = get_usage_ledger_paths();
+        make_ledger_dir(&paths.dir).unwrap();
+        let valid = append_input("valid", 100.0, "success", None);
+        let valid_line = usage_row_to_json_line(&normalize_usage_ledger_row(&valid));
+        fs::write(
+            &paths.current,
+            format!("{{ not json\n\n{valid_line}{{\"version\":2,\"id\":\"wrong-version\",\"createdAt\":1,\"tokens\":{{}}}}\n"),
+        )
+        .unwrap();
+        let rows = read_usage_ledger_rows(&UsageLedgerQuery::default())
+            .await
+            .unwrap();
+        assert_eq!(
+            rows.iter().map(|row| row.id.as_str()).collect::<Vec<_>>(),
+            vec!["valid"]
+        );
+    }
+
+    #[tokio::test]
+    #[serial(env)]
+    async fn summarize_day_buckets_use_utc_dates() {
+        let _sandbox = EnvSandbox::new();
+        append_usage_ledger_row(&append_input("epoch", 0.0, "success", None))
+            .await
+            .unwrap();
+        append_usage_ledger_row(&append_input("y2026", 1_767_323_045_006.0, "success", None))
+            .await
+            .unwrap();
+        let summary = summarize_usage_ledger(&UsageSummaryQuery {
+            by: Some(UsageSummaryGroupBy::Day),
+            ..Default::default()
+        })
+        .await
+        .unwrap();
+        assert_eq!(
+            summary
+                .buckets
+                .iter()
+                .map(|bucket| bucket.key.as_str())
+                .collect::<Vec<_>>(),
+            vec!["1970-01-01", "2026-01-02"]
+        );
+    }
+}
diff --git a/crates/usage/src/lib.rs b/crates/usage/src/lib.rs
new file mode 100644
index 000000000..f0b219793
--- /dev/null
+++ b/crates/usage/src/lib.rs
@@ -0,0 +1,5 @@
+//! cma-usage - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod ledger;
+pub mod pricing;
+pub mod redaction;
+pub mod types;
diff --git a/crates/usage/src/pricing.rs b/crates/usage/src/pricing.rs
new file mode 100644
index 000000000..57562ca4a
--- /dev/null
+++ b/crates/usage/src/pricing.rs
@@ -0,0 +1,323 @@
+//! Port of `lib/usage/pricing.ts` — hardcoded per-model USD pricing + cost
+//! estimator.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §5.2.
+//!
+//! Byte-compat critical: `estimateUsageCostUsd` rounds via
+//! `Number(sum.toFixed(8))` — 8-decimal rounding is part of the on-disk
+//! format. [`js_to_fixed_8`] reproduces ECMAScript `Number.prototype.toFixed`
+//! semantics exactly: the rounding decision is made on the EXACT decimal
+//! expansion of the binary double (so e.g. `0.000000015` rounds DOWN to
+//! `1e-8` because the double is `0.0000000149999…`), and true ties pick the
+//! larger magnitude (ES2023 §Number.prototype.toFixed "pick the larger n").
+//! The ledger summarizer reuses this helper at every accumulation step.
+
+use crate::types::{UsageTokenCounts, js_trim};
+
+/// `UsageModelPricing` — USD per million tokens. `cached_input`/`reasoning`
+/// fall back to `input`/`output` respectively when absent.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageModelPricing {
+    pub input_usd_per_million: f64,
+    pub output_usd_per_million: f64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cached_input_usd_per_million: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reasoning_usd_per_million: Option<f64>,
+}
+
+const fn pricing(input: f64, output: f64, cached: f64, reasoning: f64) -> UsageModelPricing {
+    UsageModelPricing {
+        input_usd_per_million: input,
+        output_usd_per_million: output,
+        cached_input_usd_per_million: Some(cached),
+        reasoning_usd_per_million: Some(reasoning),
+    }
+}
+
+/// `MODEL_PRICING` — exact table from `lib/usage/pricing.ts` (keys are
+/// lowercase model ids, insertion order preserved).
+pub const MODEL_PRICING: [(&str, UsageModelPricing); 9] = [
+    ("gpt-5-codex", pricing(1.25, 10.0, 0.125, 10.0)),
+    ("gpt-5.1-codex", pricing(1.25, 10.0, 0.125, 10.0)),
+    ("gpt-5.2", pricing(1.25, 10.0, 0.125, 10.0)),
+    ("gpt-5.3-codex", pricing(1.25, 10.0, 0.125, 10.0)),
+    ("gpt-5.4", pricing(2.0, 12.0, 0.2, 12.0)),
+    ("gpt-5.5", pricing(2.0, 12.0, 0.2, 12.0)),
+    ("gpt-5.6-sol", pricing(5.0, 30.0, 0.5, 30.0)),
+    ("gpt-5.6-terra", pricing(2.5, 15.0, 0.25, 15.0)),
+    ("gpt-5.6-luna", pricing(1.0, 6.0, 0.1, 6.0)),
+];
+
+fn normalize_model_name(model: Option<&str>) -> Option<String> {
+    let trimmed = js_trim(model?).to_lowercase();
+    if trimmed.is_empty() { None } else { Some(trimmed) }
+}
+
+/// `getUsageModelPricing` — trim+lowercase lookup; `None` for unknown/empty.
+pub fn get_usage_model_pricing(model: Option<&str>) -> Option<&'static UsageModelPricing> {
+    let normalized = normalize_model_name(model)?;
+    MODEL_PRICING
+        .iter()
+        .find(|(key, _)| *key == normalized)
+        .map(|(_, value)| value)
+}
+
+/// `estimateUsageCostUsd` — `None` when the model has no price card (so the
+/// summary layer can distinguish "free" from "unpriceable").
+///
+/// `billableInput = max(0, inputTokens - cachedInputTokens)`; cached input is
+/// billed at the cached rate (falling back to the input rate), reasoning at
+/// the reasoning rate (falling back to the output rate). The final sum is
+/// rounded through [`js_to_fixed_8`] — part of the on-disk format.
+pub fn estimate_usage_cost_usd(model: Option<&str>, tokens: &UsageTokenCounts) -> Option<f64> {
+    let pricing = get_usage_model_pricing(model)?;
+
+    let billable_input_tokens = tokens.input_tokens.saturating_sub(tokens.cached_input_tokens);
+    let input = (billable_input_tokens as f64 / 1_000_000.0) * pricing.input_usd_per_million;
+    let output = (tokens.output_tokens as f64 / 1_000_000.0) * pricing.output_usd_per_million;
+    let cached = (tokens.cached_input_tokens as f64 / 1_000_000.0)
+        * pricing
+            .cached_input_usd_per_million
+            .unwrap_or(pricing.input_usd_per_million);
+    let reasoning = (tokens.reasoning_tokens as f64 / 1_000_000.0)
+        * pricing
+            .reasoning_usd_per_million
+            .unwrap_or(pricing.output_usd_per_million);
+    Some(js_to_fixed_8(input + output + cached + reasoning))
+}
+
+/// `listUsageModelPricing` — a copy of the table in declaration order.
+pub fn list_usage_model_pricing() -> Vec<(&'static str, UsageModelPricing)> {
+    MODEL_PRICING.to_vec()
+}
+
+// ---------------------------------------------------------------------------
+// js_to_fixed_8 — Number(x.toFixed(8)) with exact ECMAScript semantics
+// ---------------------------------------------------------------------------
+
+/// `Number(value.toFixed(8))` — byte-exact ECMAScript semantics.
+///
+/// - Non-finite values round-trip unchanged (`Number(String(NaN))` etc.).
+/// - `|x| >= 1e21` takes the `ToString(x)` path, which `Number()` round-trips
+///   exactly → returned unchanged.
+/// - Otherwise the integer `n` minimizing `|n / 10^8 - x|` is chosen against
+///   the EXACT decimal expansion of the double, with true ties picking the
+///   larger `n` (round half away from zero in magnitude).
+/// - The decimal string is then re-parsed to the nearest double, exactly like
+///   JS `Number(string)`.
+pub fn js_to_fixed_8(value: f64) -> f64 {
+    if !value.is_finite() {
+        return value;
+    }
+    if value.abs() >= 1e21 {
+        // toFixed returns ToString(x) here; Number() round-trips it exactly.
+        return value;
+    }
+    let text = js_to_fixed_string_8(value);
+    text.parse::<f64>()
+        .expect("fixed-decimal string always parses as f64")
+}
+
+/// `value.toFixed(8)` as a string, for `|value| < 1e21` finite doubles.
+fn js_to_fixed_string_8(value: f64) -> String {
+    // Note: -0 is NOT negative here (JS: only `x < 0` sets the sign), so
+    // (-0).toFixed(8) === "0.00000000" → Number → +0.
+    let negative = value < 0.0;
+    let abs = value.abs();
+
+    // Exact decimal expansion: every finite double's fraction terminates
+    // within 1074 decimal digits (the smallest subnormal), so `{:.1074}`
+    // performs no rounding — it IS the exact value.
+    let exact = format!("{abs:.1074}");
+    let (int_part, frac_part) = exact
+        .split_once('.')
+        .expect("fixed-precision format always contains a fraction");
+    let frac = frac_part.as_bytes();
+
+    // digits = <int digits><first 8 fraction digits> as a decimal integer.
+    let mut digits: Vec<u8> = Vec::with_capacity(int_part.len() + 8);
+    digits.extend_from_slice(int_part.as_bytes());
+    digits.extend_from_slice(&frac[..8]);
+
+    // The expansion is exact, so: first tail digit >= 5 ⇒ tail >= half an
+    // ulp at digit 8 ⇒ round up (exact half is a tie → "pick the larger n").
+    if frac[8] >= b'5' {
+        increment_decimal_digits(&mut digits);
+    }
+
+    let split = digits.len() - 8;
+    let int_str = std::str::from_utf8(&digits[..split]).expect("ascii digits");
+    let frac_str = std::str::from_utf8(&digits[split..]).expect("ascii digits");
+    let int_str = if int_str.is_empty() { "0" } else { int_str };
+    if negative {
+        format!("-{int_str}.{frac_str}")
+    } else {
+        format!("{int_str}.{frac_str}")
+    }
+}
+
+fn increment_decimal_digits(digits: &mut Vec<u8>) {
+    for digit in digits.iter_mut().rev() {
+        if *digit == b'9' {
+            *digit = b'0';
+        } else {
+            *digit += 1;
+            return;
+        }
+    }
+    digits.insert(0, b'1');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tokens(input: u64, output: u64, cached: u64, reasoning: u64) -> UsageTokenCounts {
+        UsageTokenCounts {
+            input_tokens: input,
+            output_tokens: output,
+            cached_input_tokens: cached,
+            reasoning_tokens: reasoning,
+            total_tokens: input + output + reasoning,
+        }
+    }
+
+    // ----- table + lookup -----
+
+    #[test]
+    fn pricing_table_matches_ts_entries_and_order() {
+        assert_eq!(MODEL_PRICING.len(), 9);
+        assert_eq!(MODEL_PRICING[0].0, "gpt-5-codex");
+        assert_eq!(MODEL_PRICING[8].0, "gpt-5.6-luna");
+        let listed = list_usage_model_pricing();
+        assert!(listed.iter().any(|(key, _)| *key == "gpt-5.3-codex"));
+        let sol = get_usage_model_pricing(Some("gpt-5.6-sol")).unwrap();
+        assert_eq!(sol.input_usd_per_million, 5.0);
+        assert_eq!(sol.output_usd_per_million, 30.0);
+        assert_eq!(sol.cached_input_usd_per_million, Some(0.5));
+        assert_eq!(sol.reasoning_usd_per_million, Some(30.0));
+    }
+
+    #[test]
+    fn lookup_trims_and_lowercases_and_rejects_empty_or_unknown() {
+        assert!(get_usage_model_pricing(Some("  GPT-5.2  ")).is_some());
+        assert!(get_usage_model_pricing(Some("unknown-model")).is_none());
+        assert!(get_usage_model_pricing(Some("")).is_none());
+        assert!(get_usage_model_pricing(Some("   ")).is_none());
+        assert!(get_usage_model_pricing(None).is_none());
+    }
+
+    // ----- estimateUsageCostUsd (assertions ported from usage-ledger.test.ts) -----
+
+    #[test]
+    fn estimates_deterministic_costs_from_the_price_card() {
+        // 1M of everything on gpt-5.3-codex: billable input 0, output 10,
+        // cached 0.125, reasoning 10 → 20.125.
+        assert_eq!(
+            estimate_usage_cost_usd(
+                Some("gpt-5.3-codex"),
+                &tokens(1_000_000, 1_000_000, 1_000_000, 1_000_000)
+            ),
+            Some(20.125)
+        );
+        assert_eq!(
+            estimate_usage_cost_usd(Some("gpt-5.3-codex"), &tokens(1_000, 200, 50, 25)),
+            Some(0.00344375)
+        );
+        // Literal pin of the gpt-5.2 price card ($1.25/M in + $10/M out).
+        assert_eq!(
+            estimate_usage_cost_usd(Some("gpt-5.2"), &tokens(1_000_000, 1_000_000, 0, 0)),
+            Some(11.25)
+        );
+        assert_eq!(estimate_usage_cost_usd(None, &tokens(1, 1, 0, 0)), None);
+        assert_eq!(
+            estimate_usage_cost_usd(Some("unknown-model"), &tokens(1, 1, 0, 0)),
+            None
+        );
+    }
+
+    #[test]
+    fn billable_input_clamps_at_zero_when_cached_exceeds_input() {
+        // billable = max(0, 100 - 200) = 0 → only cached tokens billed.
+        assert_eq!(
+            estimate_usage_cost_usd(Some("gpt-5.2"), &tokens(100, 0, 200, 0)),
+            Some(0.000025)
+        );
+    }
+
+    // ----- js_to_fixed_8 (vectors verified against Node `Number(x.toFixed(8))`) -----
+
+    #[test]
+    fn js_to_fixed_8_matches_ecmascript_tofixed_vectors() {
+        // (value, Number(value.toFixed(8))) — generated with Node 24.
+        let cases: &[(f64, f64)] = &[
+            (0.1 + 0.2, 0.3),
+            // Doubles just below the printed tie round DOWN (exact expansion
+            // 0.0000000149999… / 1.0000000049999…) — the "toFixed is not
+            // naive half-up" cases.
+            (0.000000015, 1e-8),
+            (0.000000025, 2e-8),
+            (1.000000005, 1.0),
+            (0.123456785, 0.12345678),
+            (0.123456775, 0.12345678),
+            (3.000000004999999, 3.0),
+            // TRUE ties (odd/2^9 terminates exactly at digit 9 with a 5):
+            // spec picks the larger n → round up, in magnitude for negatives.
+            (0.001953125, 0.00195313),
+            (0.005859375, 0.00585938),
+            (-0.001953125, -0.00195313),
+            // Rounding to zero / carry propagation into the integer part.
+            (2.5e-9, 0.0),
+            (1.5e-9, 0.0),
+            (1e-9, 0.0),
+            (-0.000000015, -1e-8),
+            (0.9999999995, 1.0),
+            // Pass-throughs.
+            (0.00344375, 0.00344375),
+            // JS source literal 123456789.123456789 — same double as below.
+            (123456789.12345679, 123456789.12345679),
+            (1e21, 1e21),
+            (0.0, 0.0),
+        ];
+        for (input, expected) in cases {
+            let actual = js_to_fixed_8(*input);
+            assert_eq!(
+                actual.to_bits(),
+                expected.to_bits(),
+                "input {input:e}: got {actual:e}, want {expected:e}"
+            );
+        }
+        assert!(js_to_fixed_8(f64::NAN).is_nan());
+        assert_eq!(js_to_fixed_8(f64::INFINITY), f64::INFINITY);
+        assert_eq!(js_to_fixed_8(f64::NEG_INFINITY), f64::NEG_INFINITY);
+    }
+
+    #[test]
+    fn js_to_fixed_8_rounds_at_every_accumulation_step_like_the_ts_summarizer() {
+        // Mirrors addRowToBucket: acc = Number((acc + cost).toFixed(8)).
+        // Expected intermediates generated with Node 24 — note the 0.2 step
+        // (11.36574375 + 0.2 = 11.565743750000001) collapses back to
+        // 11.56574375 only because of the per-step re-rounding.
+        let costs: [f64; 7] = [0.00344375, 0.0123, 11.25, 0.1, 0.2, 1e-9, 2.5e-9];
+        let expected: [f64; 7] = [
+            0.00344375,
+            0.01574375,
+            11.26574375,
+            11.36574375,
+            11.56574375,
+            11.56574375,
+            11.56574375,
+        ];
+        let mut acc = 0.0;
+        for (cost, want) in costs.iter().zip(expected.iter()) {
+            acc = js_to_fixed_8(acc + cost);
+            assert_eq!(acc.to_bits(), want.to_bits(), "after adding {cost}");
+        }
+    }
+}
diff --git a/crates/usage/src/redaction.rs b/crates/usage/src/redaction.rs
new file mode 100644
index 000000000..99591b87a
--- /dev/null
+++ b/crates/usage/src/redaction.rs
@@ -0,0 +1,489 @@
+//! Port of `lib/usage/redaction.ts` — row normalization + PII hashing.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §5.3. Privacy P0:
+//! - Identifiers are persisted ONLY as `sha256:`-prefixed hex digests.
+//! - `hashUsageIdentifier` trims but does NOT lowercase — callers lowercase
+//!   email first ([`create_usage_account_ref`] does).
+//! - `accountId` is trimmed; `email` is trimmed then lowercased.
+//! - `usageRowToJsonLine` = `JSON.stringify(row) + "\n"` (single compact
+//!   line; field order frozen by the [`UsageLedgerRow`] declaration).
+
+use std::fmt::Write as _;
+
+use sha2::{Digest, Sha256};
+
+use cma_core::json_io::stringify_compact;
+use cma_core::utils::now_ms;
+
+use crate::pricing::estimate_usage_cost_usd;
+use crate::types::{
+    USAGE_LEDGER_ROW_VERSION, UsageLedgerAccountRef, UsageLedgerAppendInput, UsageLedgerOperation,
+    UsageLedgerOutcome, UsageLedgerRow, UsageLedgerSource, UsageTokenCounts, js_trim,
+};
+
+// ---------------------------------------------------------------------------
+// Scalar normalizers (private in TS; kept private here)
+// ---------------------------------------------------------------------------
+
+fn normalize_finite_number(value: Option<f64>) -> Option<f64> {
+    value.filter(|v| v.is_finite())
+}
+
+/// `max(0, Math.trunc(x))`, defaulting to 0 for absent/non-finite values.
+fn normalize_non_negative_integer(value: Option<f64>) -> u64 {
+    match normalize_finite_number(value) {
+        Some(numeric) => {
+            let truncated = numeric.trunc();
+            if truncated <= 0.0 { 0 } else { truncated as u64 }
+        }
+        None => 0,
+    }
+}
+
+fn normalize_optional_string(value: Option<&str>) -> Option<String> {
+    let trimmed = js_trim(value?);
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn normalize_status_code(value: Option<f64>) -> Option<u16> {
+    let numeric = normalize_finite_number(value)?;
+    let status_code = numeric.trunc();
+    if (100.0..=599.0).contains(&status_code) {
+        Some(status_code as u16)
+    } else {
+        None
+    }
+}
+
+fn normalize_duration_ms(value: Option<f64>) -> Option<u64> {
+    let numeric = normalize_finite_number(value)?;
+    let truncated = numeric.trunc();
+    Some(if truncated <= 0.0 { 0 } else { truncated as u64 })
+}
+
+fn normalize_source(value: Option<&str>) -> UsageLedgerSource {
+    value
+        .and_then(UsageLedgerSource::parse)
+        .unwrap_or(UsageLedgerSource::Unknown)
+}
+
+fn normalize_operation(value: Option<&str>) -> UsageLedgerOperation {
+    value
+        .and_then(UsageLedgerOperation::parse)
+        .unwrap_or(UsageLedgerOperation::Unknown)
+}
+
+fn normalize_outcome(value: Option<&str>) -> UsageLedgerOutcome {
+    // Fallback is "failure", NOT "unknown": an unclassifiable outcome must
+    // never be counted as a success.
+    value
+        .and_then(UsageLedgerOutcome::parse)
+        .unwrap_or(UsageLedgerOutcome::Failure)
+}
+
+// ---------------------------------------------------------------------------
+// PII hashing
+// ---------------------------------------------------------------------------
+
+/// `hashUsageIdentifier` — `"sha256:" + hex(sha256(value.trim()))`.
+///
+/// Trims but does NOT lowercase (callers lowercase email first).
+pub fn hash_usage_identifier(value: &str) -> String {
+    let digest = Sha256::digest(js_trim(value).as_bytes());
+    let mut out = String::with_capacity(7 + 64);
+    out.push_str("sha256:");
+    for byte in digest {
+        let _ = write!(out, "{byte:02x}");
+    }
+    out
+}
+
+/// `createUsageAccountRef` — hash the raw facets; `None` when no identifying
+/// facet survives normalization. `index` is kept only when it is a
+/// non-negative integer (fractional and negative indexes are dropped).
+pub fn create_usage_account_ref(
+    account_id: Option<&str>,
+    email: Option<&str>,
+    account_index: Option<f64>,
+) -> Option<UsageLedgerAccountRef> {
+    let account_id = normalize_optional_string(account_id);
+    let email = normalize_optional_string(email).map(|e| e.to_lowercase());
+    let index = account_index
+        .filter(|v| v.is_finite() && v.fract() == 0.0 && *v >= 0.0)
+        .map(|v| v as u64);
+    if account_id.is_none() && email.is_none() && index.is_none() {
+        return None;
+    }
+
+    Some(UsageLedgerAccountRef {
+        account_hash: account_id.map(|id| hash_usage_identifier(&id)),
+        email_hash: email.map(|e| hash_usage_identifier(&e)),
+        index,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Row normalization
+// ---------------------------------------------------------------------------
+
+fn normalize_tokens(input: &UsageLedgerAppendInput) -> UsageTokenCounts {
+    let input_tokens = normalize_non_negative_integer(input.input_tokens);
+    let output_tokens = normalize_non_negative_integer(input.output_tokens);
+    let cached_input_tokens = normalize_non_negative_integer(input.cached_input_tokens);
+    let reasoning_tokens = normalize_non_negative_integer(input.reasoning_tokens);
+    let provided_total = normalize_finite_number(input.total_tokens);
+    // Cached input is NOT added: cached is a subset of input.
+    let computed_total = input_tokens
+        .saturating_add(output_tokens)
+        .saturating_add(reasoning_tokens);
+
+    UsageTokenCounts {
+        input_tokens,
+        output_tokens,
+        cached_input_tokens,
+        reasoning_tokens,
+        total_tokens: match provided_total {
+            None => computed_total,
+            Some(total) => {
+                let truncated = total.trunc();
+                if truncated <= 0.0 { 0 } else { truncated as u64 }
+            }
+        },
+    }
+}
+
+/// `normalizeUsageLedgerRow` — canonical row construction (write side). Raw
+/// identifiers never reach the returned row.
+pub fn normalize_usage_ledger_row(input: &UsageLedgerAppendInput) -> UsageLedgerRow {
+    let model = normalize_optional_string(input.model.as_deref());
+    let tokens = normalize_tokens(input);
+    let explicit_cost = normalize_finite_number(input.cost_usd);
+
+    UsageLedgerRow {
+        version: USAGE_LEDGER_ROW_VERSION,
+        id: normalize_optional_string(input.id.as_deref())
+            .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
+        created_at: normalize_finite_number(input.created_at).unwrap_or_else(|| now_ms() as f64),
+        source: normalize_source(input.source.as_deref()),
+        operation: normalize_operation(input.operation.as_deref()),
+        outcome: normalize_outcome(input.outcome.as_deref()),
+        model: model.clone(),
+        project_key: normalize_optional_string(input.project_key.as_deref()),
+        account: create_usage_account_ref(
+            input.account_id.as_deref(),
+            input.email.as_deref(),
+            input.account_index,
+        ),
+        request_id: normalize_optional_string(input.request_id.as_deref()),
+        status_code: normalize_status_code(input.status_code),
+        error_code: normalize_optional_string(input.error_code.as_deref()),
+        duration_ms: normalize_duration_ms(input.duration_ms),
+        cost_usd: match explicit_cost {
+            Some(cost) => Some(cost.max(0.0)),
+            None => estimate_usage_cost_usd(model.as_deref(), &tokens),
+        },
+        tokens,
+    }
+}
+
+/// `usageRowToJsonLine` — one compact JSON line terminated by `"\n"`. Field
+/// order follows the [`UsageLedgerRow`] declaration (the TS object-literal
+/// order); readers don't depend on it, but it keeps ledgers diff-friendly.
+pub fn usage_row_to_json_line(row: &UsageLedgerRow) -> String {
+    format!("{}\n", stringify_compact(row))
+}
+
+// ---------------------------------------------------------------------------
+// Tests (ported from test/usage-redaction.test.ts — privacy P0)
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sha256_plain(value: &str) -> String {
+        let digest = Sha256::digest(value.as_bytes());
+        let mut out = String::from("sha256:");
+        for byte in digest {
+            let _ = write!(out, "{byte:02x}");
+        }
+        out
+    }
+
+    fn base_input(outcome: &str) -> UsageLedgerAppendInput {
+        UsageLedgerAppendInput {
+            outcome: Some(outcome.to_string()),
+            ..Default::default()
+        }
+    }
+
+    // ----- hashUsageIdentifier -----
+
+    #[test]
+    fn trims_before_hashing_and_prefixes_the_digest_format() {
+        assert_eq!(hash_usage_identifier("  acct-123 "), sha256_plain("acct-123"));
+        assert_eq!(
+            hash_usage_identifier("acct-123"),
+            hash_usage_identifier("\tacct-123  ")
+        );
+        assert!(hash_usage_identifier("x").starts_with("sha256:"));
+    }
+
+    // ----- createUsageAccountRef -----
+
+    #[test]
+    fn hashes_account_id_and_lowercased_email_never_storing_raw_values() {
+        let account_ref =
+            create_usage_account_ref(Some(" acct-123 "), Some(" Alice@Example.COM "), Some(2.0))
+                .unwrap();
+        assert_eq!(account_ref.account_hash, Some(sha256_plain("acct-123")));
+        assert_eq!(
+            account_ref.email_hash,
+            Some(sha256_plain("alice@example.com"))
+        );
+        assert_eq!(account_ref.index, Some(2));
+    }
+
+    #[test]
+    fn returns_none_when_no_identifying_facet_survives_normalization() {
+        assert_eq!(create_usage_account_ref(Some("  "), Some(""), None), None);
+        assert_eq!(create_usage_account_ref(None, None, None), None);
+    }
+
+    #[test]
+    fn rejects_negative_and_fractional_indexes_but_keeps_zero() {
+        let zero = create_usage_account_ref(None, None, Some(0.0)).unwrap();
+        assert_eq!(zero.account_hash, None);
+        assert_eq!(zero.email_hash, None);
+        assert_eq!(zero.index, Some(0));
+        assert_eq!(create_usage_account_ref(None, None, Some(-1.0)), None);
+        assert_eq!(create_usage_account_ref(None, None, Some(1.5)), None);
+        assert_eq!(create_usage_account_ref(None, None, Some(f64::NAN)), None);
+    }
+
+    // ----- normalizeUsageLedgerRow -----
+
+    #[test]
+    fn coerces_unknown_enums_to_their_documented_fallbacks() {
+        let row = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            source: Some("smoke-signal".to_string()),
+            operation: Some("bogus".to_string()),
+            outcome: Some("exploded".to_string()),
+            ..Default::default()
+        });
+        assert_eq!(row.source, UsageLedgerSource::Unknown);
+        assert_eq!(row.operation, UsageLedgerOperation::Unknown);
+        // Outcome falls back to "failure", not "unknown": an unclassifiable
+        // outcome must never be counted as a success.
+        assert_eq!(row.outcome, UsageLedgerOutcome::Failure);
+        // Missing outcome behaves the same.
+        assert_eq!(
+            normalize_usage_ledger_row(&UsageLedgerAppendInput::default()).outcome,
+            UsageLedgerOutcome::Failure
+        );
+    }
+
+    #[test]
+    fn keeps_valid_enums_as_is() {
+        let row = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            source: Some("runtime-proxy".to_string()),
+            operation: Some("responses".to_string()),
+            outcome: Some("blocked".to_string()),
+            ..Default::default()
+        });
+        assert_eq!(row.source, UsageLedgerSource::RuntimeProxy);
+        assert_eq!(row.operation, UsageLedgerOperation::Responses);
+        assert_eq!(row.outcome, UsageLedgerOutcome::Blocked);
+    }
+
+    #[test]
+    fn clamps_token_counts_and_recomputes_total_when_none_is_provided() {
+        let row = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            input_tokens: Some(100.9),
+            output_tokens: Some(-5.0),
+            cached_input_tokens: Some(f64::NAN),
+            reasoning_tokens: Some(7.0),
+            ..base_input("success")
+        });
+        assert_eq!(
+            row.tokens,
+            UsageTokenCounts {
+                input_tokens: 100,
+                output_tokens: 0,
+                cached_input_tokens: 0,
+                reasoning_tokens: 7,
+                // input + output + reasoning; cached input is informational.
+                total_tokens: 107,
+            }
+        );
+    }
+
+    #[test]
+    fn trusts_a_provided_total_but_clamps_it_non_negative() {
+        let truncated = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            total_tokens: Some(42.7),
+            ..base_input("success")
+        });
+        assert_eq!(truncated.tokens.total_tokens, 42);
+        let clamped = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            total_tokens: Some(-10.0),
+            ..base_input("success")
+        });
+        assert_eq!(clamped.tokens.total_tokens, 0);
+    }
+
+    #[test]
+    fn accepts_only_real_http_status_codes() {
+        let case = |status: f64| {
+            normalize_usage_ledger_row(&UsageLedgerAppendInput {
+                status_code: Some(status),
+                ..base_input("success")
+            })
+            .status_code
+        };
+        assert_eq!(case(429.0), Some(429));
+        assert_eq!(case(99.0), None);
+        assert_eq!(case(600.0), None);
+        assert_eq!(case(f64::NAN), None);
+    }
+
+    #[test]
+    fn falls_back_to_the_pricing_estimate_when_no_explicit_cost_is_given() {
+        let row = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            model: Some("gpt-5.2".to_string()),
+            input_tokens: Some(1_000_000.0),
+            output_tokens: Some(1_000_000.0),
+            ..base_input("success")
+        });
+        // Literal pin of the gpt-5.2 price card ($1.25/M input + $10/M
+        // output), not just delegation: a wrong table entry must fail here.
+        assert_eq!(row.cost_usd, Some(11.25));
+        assert_eq!(
+            row.cost_usd,
+            estimate_usage_cost_usd(Some("gpt-5.2"), &row.tokens)
+        );
+        let negative = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            cost_usd: Some(-3.0),
+            ..base_input("success")
+        });
+        assert_eq!(negative.cost_usd, Some(0.0));
+        let explicit = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            cost_usd: Some(1.25),
+            ..base_input("success")
+        });
+        assert_eq!(explicit.cost_usd, Some(1.25));
+    }
+
+    #[test]
+    fn records_a_null_cost_for_models_without_a_price_card() {
+        // None (not 0) so the summary aggregator can distinguish "free" from
+        // "unpriceable".
+        let row = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            model: Some("mystery-model".to_string()),
+            input_tokens: Some(1_000.0),
+            ..base_input("success")
+        });
+        assert_eq!(row.cost_usd, None);
+    }
+
+    #[test]
+    fn clamps_and_truncates_duration_ms_dropping_non_finite_values() {
+        let case = |duration: Option<f64>| {
+            normalize_usage_ledger_row(&UsageLedgerAppendInput {
+                duration_ms: duration,
+                ..base_input("success")
+            })
+            .duration_ms
+        };
+        assert_eq!(case(Some(1234.9)), Some(1234));
+        assert_eq!(case(Some(-50.0)), Some(0));
+        assert_eq!(case(Some(f64::NAN)), None);
+        assert_eq!(case(None), None);
+    }
+
+    #[test]
+    fn fills_id_and_created_at_defaults() {
+        let before = now_ms() as f64;
+        let row = normalize_usage_ledger_row(&base_input("success"));
+        let after = now_ms() as f64;
+        assert!(row.created_at >= before && row.created_at <= after);
+        // randomUUID shape: 8-4-4-4-12 lowercase hex.
+        let id = row.id.as_bytes();
+        assert_eq!(id.len(), 36);
+        for (index, byte) in id.iter().enumerate() {
+            if matches!(index, 8 | 13 | 18 | 23) {
+                assert_eq!(*byte, b'-', "hyphen at {index}");
+            } else {
+                assert!(
+                    byte.is_ascii_digit() || (b'a'..=b'f').contains(byte),
+                    "lowercase hex at {index}"
+                );
+            }
+        }
+
+        let explicit = normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            id: Some(" row-1 ".to_string()),
+            created_at: Some(5.0),
+            ..base_input("success")
+        });
+        assert_eq!(explicit.id, "row-1");
+        assert_eq!(explicit.created_at, 5.0);
+    }
+
+    // ----- usageRowToJsonLine -----
+
+    #[test]
+    fn serializes_one_newline_terminated_json_line_with_no_raw_identifiers() {
+        let line = usage_row_to_json_line(&normalize_usage_ledger_row(&UsageLedgerAppendInput {
+            account_id: Some("acct-123".to_string()),
+            email: Some("Alice@Example.com".to_string()),
+            model: Some("gpt-5.2".to_string()),
+            ..base_input("success")
+        }));
+        assert!(line.ends_with('\n'));
+        assert_eq!(line.find('\n'), Some(line.len() - 1));
+        assert!(serde_json::from_str::<serde_json::Value>(&line).is_ok());
+        // The redaction guarantee the ledger relies on: raw identifiers must
+        // never reach the serialized row.
+        assert!(!line.contains("acct-123"));
+        assert!(!line.to_lowercase().contains("alice@example.com"));
+        assert!(line.contains(&sha256_plain("acct-123")));
+        assert!(line.contains(&sha256_plain("alice@example.com")));
+    }
+
+    // ----- golden byte fixture (crates/testkit/goldens/usage-ledger-row.jsonl) -----
+
+    #[test]
+    fn golden_usage_ledger_row_line_is_byte_identical_to_the_ts_writer() {
+        // Exact inputs from crates/testkit/goldens/generate.mjs §13.
+        let input = UsageLedgerAppendInput {
+            id: Some("usage-fixture-0000000000000001".to_string()),
+            created_at: Some(1_750_000_000_000.0),
+            source: Some("runtime-proxy".to_string()),
+            operation: Some("responses".to_string()),
+            outcome: Some("success".to_string()),
+            model: Some("gpt-5.2".to_string()),
+            project_key: Some("my-app-0123456789ab".to_string()),
+            account_id: Some("acct-user-one".to_string()),
+            email: Some("User.One@Example.com".to_string()),
+            account_index: Some(0.0),
+            request_id: Some("req-fixture-0001".to_string()),
+            status_code: Some(200.0),
+            duration_ms: Some(1234.0),
+            input_tokens: Some(1200.0),
+            output_tokens: Some(350.0),
+            cached_input_tokens: Some(800.0),
+            reasoning_tokens: Some(64.0),
+            cost_usd: Some(0.0123),
+            ..Default::default()
+        };
+        let line = usage_row_to_json_line(&normalize_usage_ledger_row(&input));
+        let golden = cma_testkit::goldens::read_golden_string("usage-ledger-row.jsonl")
+            .replace("\r\n", "\n");
+        assert_eq!(line, golden);
+    }
+}
diff --git a/crates/usage/src/types.rs b/crates/usage/src/types.rs
new file mode 100644
index 000000000..b8dda5c96
--- /dev/null
+++ b/crates/usage/src/types.rs
@@ -0,0 +1,457 @@
+//! Port of `lib/usage/types.ts` — usage ledger row/summary types.
+//!
+//! Behavior source: specs/11-cli-usage-recovery.md §5.1.
+//!
+//! Byte-compat notes (spec §5.3 "usageRowToJsonLine"):
+//! - [`UsageLedgerRow`] serializes its fields in the exact TS object-literal
+//!   order (version, id, createdAt, source, operation, outcome, model,
+//!   projectKey, account, requestId, statusCode, errorCode, durationMs,
+//!   tokens, costUsd). Nullable row fields serialize as JSON `null` (the TS
+//!   row always carries them, possibly `null`).
+//! - [`UsageLedgerAccountRef`] fields are *omitted* when absent (TS sets them
+//!   to `undefined`, which `JSON.stringify` drops).
+//! - `createdAt` is modeled as `f64` because the TS normalizer preserves a
+//!   caller-provided fractional timestamp verbatim; serialization goes through
+//!   `cma_core::json_io` (ECMAScript number formatting), so integer-valued
+//!   timestamps can never gain a decimal point.
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+/// The frozen on-disk row version (`version: 1`).
+pub const USAGE_LEDGER_ROW_VERSION: u8 = 1;
+
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+
+/// `UsageLedgerSource` — where a ledger row originated.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum UsageLedgerSource {
+    #[serde(rename = "runtime-proxy")]
+    RuntimeProxy,
+    #[serde(rename = "plugin-host")]
+    PluginHost,
+    #[serde(rename = "local-bridge")]
+    LocalBridge,
+    #[serde(rename = "cli")]
+    Cli,
+    #[serde(rename = "unknown")]
+    Unknown,
+}
+
+impl UsageLedgerSource {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            UsageLedgerSource::RuntimeProxy => "runtime-proxy",
+            UsageLedgerSource::PluginHost => "plugin-host",
+            UsageLedgerSource::LocalBridge => "local-bridge",
+            UsageLedgerSource::Cli => "cli",
+            UsageLedgerSource::Unknown => "unknown",
+        }
+    }
+
+    /// Strict membership test against the valid-source set (no fallback —
+    /// callers apply the TS `"unknown"` fallback themselves).
+    pub fn parse(value: &str) -> Option<Self> {
+        Some(match value {
+            "runtime-proxy" => UsageLedgerSource::RuntimeProxy,
+            "plugin-host" => UsageLedgerSource::PluginHost,
+            "local-bridge" => UsageLedgerSource::LocalBridge,
+            "cli" => UsageLedgerSource::Cli,
+            "unknown" => UsageLedgerSource::Unknown,
+            _ => return None,
+        })
+    }
+}
+
+/// `UsageLedgerOperation` — what kind of request the row describes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum UsageLedgerOperation {
+    #[serde(rename = "responses")]
+    Responses,
+    #[serde(rename = "models")]
+    Models,
+    #[serde(rename = "thread-goal")]
+    ThreadGoal,
+    #[serde(rename = "auth-refresh")]
+    AuthRefresh,
+    #[serde(rename = "diagnostic")]
+    Diagnostic,
+    #[serde(rename = "unknown")]
+    Unknown,
+}
+
+impl UsageLedgerOperation {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            UsageLedgerOperation::Responses => "responses",
+            UsageLedgerOperation::Models => "models",
+            UsageLedgerOperation::ThreadGoal => "thread-goal",
+            UsageLedgerOperation::AuthRefresh => "auth-refresh",
+            UsageLedgerOperation::Diagnostic => "diagnostic",
+            UsageLedgerOperation::Unknown => "unknown",
+        }
+    }
+
+    /// Strict membership test (no fallback).
+    pub fn parse(value: &str) -> Option<Self> {
+        Some(match value {
+            "responses" => UsageLedgerOperation::Responses,
+            "models" => UsageLedgerOperation::Models,
+            "thread-goal" => UsageLedgerOperation::ThreadGoal,
+            "auth-refresh" => UsageLedgerOperation::AuthRefresh,
+            "diagnostic" => UsageLedgerOperation::Diagnostic,
+            "unknown" => UsageLedgerOperation::Unknown,
+            _ => return None,
+        })
+    }
+}
+
+/// `UsageLedgerOutcome` — request outcome classification.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum UsageLedgerOutcome {
+    #[serde(rename = "success")]
+    Success,
+    #[serde(rename = "failure")]
+    Failure,
+    #[serde(rename = "blocked")]
+    Blocked,
+    #[serde(rename = "cancelled")]
+    Cancelled,
+}
+
+impl UsageLedgerOutcome {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            UsageLedgerOutcome::Success => "success",
+            UsageLedgerOutcome::Failure => "failure",
+            UsageLedgerOutcome::Blocked => "blocked",
+            UsageLedgerOutcome::Cancelled => "cancelled",
+        }
+    }
+
+    /// Strict membership test (no fallback — the TS fallback is `"failure"`,
+    /// applied by callers: an unclassifiable outcome must never count as a
+    /// success).
+    pub fn parse(value: &str) -> Option<Self> {
+        Some(match value {
+            "success" => UsageLedgerOutcome::Success,
+            "failure" => UsageLedgerOutcome::Failure,
+            "blocked" => UsageLedgerOutcome::Blocked,
+            "cancelled" => UsageLedgerOutcome::Cancelled,
+            _ => return None,
+        })
+    }
+}
+
+/// `UsageSummaryGroupBy` — summary bucketing dimension. Default `"model"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
+pub enum UsageSummaryGroupBy {
+    #[default]
+    #[serde(rename = "model")]
+    Model,
+    #[serde(rename = "account")]
+    Account,
+    #[serde(rename = "project")]
+    Project,
+    #[serde(rename = "outcome")]
+    Outcome,
+    #[serde(rename = "day")]
+    Day,
+}
+
+impl UsageSummaryGroupBy {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            UsageSummaryGroupBy::Model => "model",
+            UsageSummaryGroupBy::Account => "account",
+            UsageSummaryGroupBy::Project => "project",
+            UsageSummaryGroupBy::Outcome => "outcome",
+            UsageSummaryGroupBy::Day => "day",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        Some(match value {
+            "model" => UsageSummaryGroupBy::Model,
+            "account" => UsageSummaryGroupBy::Account,
+            "project" => UsageSummaryGroupBy::Project,
+            "outcome" => UsageSummaryGroupBy::Outcome,
+            "day" => UsageSummaryGroupBy::Day,
+            _ => return None,
+        })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Row shapes
+// ---------------------------------------------------------------------------
+
+/// `UsageTokenCounts` — always fully populated on a normalized row.
+///
+/// Invariant (spec §5.2/§5.3): `totalTokens = inputTokens + outputTokens +
+/// reasoningTokens` when computed (cached input EXCLUDED — cached is a subset
+/// of input), unless the writer provided an explicit total.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageTokenCounts {
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_input_tokens: u64,
+    pub reasoning_tokens: u64,
+    pub total_tokens: u64,
+}
+
+/// `UsageLedgerAccountRef` — hashed account facets. Raw identifiers are never
+/// persisted; absent facets are omitted from the serialized row (TS
+/// `undefined` semantics).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageLedgerAccountRef {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub account_hash: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub email_hash: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub index: Option<u64>,
+}
+
+/// `UsageLedgerRow` — one JSONL line (`version: 1`, COMPACT serialization).
+///
+/// Field declaration order is the serialization order and is FROZEN (matches
+/// the TS object literal in `normalizeUsageLedgerRow`).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageLedgerRow {
+    /// Always [`USAGE_LEDGER_ROW_VERSION`] (1).
+    pub version: u8,
+    pub id: String,
+    pub created_at: f64,
+    pub source: UsageLedgerSource,
+    pub operation: UsageLedgerOperation,
+    pub outcome: UsageLedgerOutcome,
+    pub model: Option<String>,
+    pub project_key: Option<String>,
+    pub account: Option<UsageLedgerAccountRef>,
+    pub request_id: Option<String>,
+    pub status_code: Option<u16>,
+    pub error_code: Option<String>,
+    pub duration_ms: Option<u64>,
+    pub tokens: UsageTokenCounts,
+    pub cost_usd: Option<f64>,
+}
+
+/// `UsageLedgerAppendInput` — the all-optional write-side input with RAW
+/// `account_id`/`email`/`account_index` facets (hashed during normalization,
+/// never persisted).
+///
+/// `source`/`operation`/`outcome` are plain strings because the TS normalizer
+/// validates arbitrary values against the enum sets, coercing unknown values
+/// to `"unknown"` (outcome: `"failure"`). Typed callers should pass
+/// `Some(UsageLedgerOutcome::Success.as_str().to_string())` etc.
+///
+/// Numeric fields are `f64` so the TS clamping rules (`Math.trunc`,
+/// `Number.isFinite`, `Number.isInteger`) apply to fractional/NaN inputs
+/// exactly as in the source.
+#[derive(Debug, Clone, Default)]
+pub struct UsageLedgerAppendInput {
+    pub id: Option<String>,
+    pub created_at: Option<f64>,
+    pub source: Option<String>,
+    pub operation: Option<String>,
+    pub outcome: Option<String>,
+    pub model: Option<String>,
+    pub project_key: Option<String>,
+    pub account_id: Option<String>,
+    pub email: Option<String>,
+    pub account_index: Option<f64>,
+    pub request_id: Option<String>,
+    pub status_code: Option<f64>,
+    pub error_code: Option<String>,
+    pub duration_ms: Option<f64>,
+    pub input_tokens: Option<f64>,
+    pub output_tokens: Option<f64>,
+    pub cached_input_tokens: Option<f64>,
+    pub reasoning_tokens: Option<f64>,
+    pub total_tokens: Option<f64>,
+    pub cost_usd: Option<f64>,
+}
+
+// ---------------------------------------------------------------------------
+// Query / summary shapes
+// ---------------------------------------------------------------------------
+
+/// `UsageLedgerQuery` — `since`/`until` are epoch milliseconds (the TS type
+/// also accepted `Date`/ISO strings, a JS-host affordance; Rust callers pass
+/// milliseconds). Non-finite values are treated as unset, matching the TS
+/// `normalizeTimestamp` null result.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct UsageLedgerQuery {
+    pub since: Option<f64>,
+    pub until: Option<f64>,
+    pub include_archives: bool,
+}
+
+/// `UsageSummaryQuery` — [`UsageLedgerQuery`] plus the group-by dimension.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct UsageSummaryQuery {
+    pub since: Option<f64>,
+    pub until: Option<f64>,
+    pub include_archives: bool,
+    /// `None` → `"model"` (TS default).
+    pub by: Option<UsageSummaryGroupBy>,
+}
+
+impl UsageSummaryQuery {
+    /// The row-filtering half of this query.
+    pub fn ledger_query(&self) -> UsageLedgerQuery {
+        UsageLedgerQuery {
+            since: self.since,
+            until: self.until,
+            include_archives: self.include_archives,
+        }
+    }
+}
+
+/// `UsageSummaryBucket` — accumulation bucket (also used for `totals`).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageSummaryBucket {
+    pub key: String,
+    pub requests: u64,
+    pub successes: u64,
+    pub failures: u64,
+    pub blocked: u64,
+    pub cancelled: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_input_tokens: u64,
+    pub reasoning_tokens: u64,
+    pub total_tokens: u64,
+    pub cost_usd: f64,
+}
+
+/// `UsageSummary` — totals plus per-key buckets sorted by key.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageSummary {
+    pub since: Option<f64>,
+    pub until: Option<f64>,
+    pub by: UsageSummaryGroupBy,
+    pub totals: UsageSummaryBucket,
+    pub buckets: Vec<UsageSummaryBucket>,
+}
+
+/// `UsageLedgerPaths` — resolved ledger locations.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageLedgerPaths {
+    pub dir: PathBuf,
+    pub current: PathBuf,
+}
+
+// ---------------------------------------------------------------------------
+// Crate-internal helpers
+// ---------------------------------------------------------------------------
+
+/// ECMAScript `String.prototype.trim` — Rust's `str::trim` matches the
+/// Unicode `White_Space` set JS uses, except JS additionally strips U+FEFF
+/// (ZWNBSP). Used by pricing/redaction/ledger wherever the TS called
+/// `.trim()`.
+pub(crate) fn js_trim(value: &str) -> &str {
+    value.trim_matches(|c: char| c.is_whitespace() || c == '\u{feff}')
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cma_core::json_io::stringify_compact;
+
+    #[test]
+    fn enum_serde_names_match_ts_literals() {
+        assert_eq!(
+            stringify_compact(&UsageLedgerSource::RuntimeProxy),
+            "\"runtime-proxy\""
+        );
+        assert_eq!(
+            stringify_compact(&UsageLedgerOperation::ThreadGoal),
+            "\"thread-goal\""
+        );
+        assert_eq!(
+            stringify_compact(&UsageLedgerOutcome::Cancelled),
+            "\"cancelled\""
+        );
+        assert_eq!(stringify_compact(&UsageSummaryGroupBy::Day), "\"day\"");
+        for source in [
+            UsageLedgerSource::RuntimeProxy,
+            UsageLedgerSource::PluginHost,
+            UsageLedgerSource::LocalBridge,
+            UsageLedgerSource::Cli,
+            UsageLedgerSource::Unknown,
+        ] {
+            assert_eq!(UsageLedgerSource::parse(source.as_str()), Some(source));
+        }
+        assert_eq!(UsageLedgerSource::parse("smoke-signal"), None);
+        assert_eq!(UsageLedgerOutcome::parse("exploded"), None);
+        assert_eq!(UsageSummaryGroupBy::default(), UsageSummaryGroupBy::Model);
+    }
+
+    #[test]
+    fn row_serializes_in_frozen_field_order_with_nulls() {
+        let row = UsageLedgerRow {
+            version: USAGE_LEDGER_ROW_VERSION,
+            id: "row-1".to_string(),
+            created_at: 5.0,
+            source: UsageLedgerSource::Cli,
+            operation: UsageLedgerOperation::Unknown,
+            outcome: UsageLedgerOutcome::Failure,
+            model: None,
+            project_key: None,
+            account: None,
+            request_id: None,
+            status_code: None,
+            error_code: None,
+            duration_ms: None,
+            tokens: UsageTokenCounts::default(),
+            cost_usd: None,
+        };
+        assert_eq!(
+            stringify_compact(&row),
+            concat!(
+                "{\"version\":1,\"id\":\"row-1\",\"createdAt\":5,",
+                "\"source\":\"cli\",\"operation\":\"unknown\",\"outcome\":\"failure\",",
+                "\"model\":null,\"projectKey\":null,\"account\":null,\"requestId\":null,",
+                "\"statusCode\":null,\"errorCode\":null,\"durationMs\":null,",
+                "\"tokens\":{\"inputTokens\":0,\"outputTokens\":0,\"cachedInputTokens\":0,",
+                "\"reasoningTokens\":0,\"totalTokens\":0},\"costUsd\":null}"
+            )
+        );
+    }
+
+    #[test]
+    fn account_ref_omits_absent_facets_like_js_undefined() {
+        let full = UsageLedgerAccountRef {
+            account_hash: Some("sha256:aa".to_string()),
+            email_hash: None,
+            index: Some(0),
+        };
+        assert_eq!(
+            stringify_compact(&full),
+            "{\"accountHash\":\"sha256:aa\",\"index\":0}"
+        );
+        assert_eq!(stringify_compact(&UsageLedgerAccountRef::default()), "{}");
+    }
+
+    #[test]
+    fn js_trim_strips_whitespace_and_bom() {
+        assert_eq!(js_trim("  x "), "x");
+        assert_eq!(js_trim("\t\r\n x \u{a0}"), "x");
+        assert_eq!(js_trim("\u{feff}x\u{feff}"), "x");
+        assert_eq!(js_trim(""), "");
+    }
+}
diff --git a/crates/wrapper/Cargo.toml b/crates/wrapper/Cargo.toml
new file mode 100644
index 000000000..85c3ca9e3
--- /dev/null
+++ b/crates/wrapper/Cargo.toml
@@ -0,0 +1,38 @@
+[package]
+name = "cma-wrapper"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+cma-core = { path = "../core" }
+cma-config = { path = "../config" }
+cma-storage = { path = "../storage" }
+cma-accounts = { path = "../accounts" }
+cma-cli-mirror = { path = "../climirror" }
+cma-runtime = { path = "../runtime" }
+cma-proxy = { path = "../proxy" }
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+uuid.workspace = true
+rand.workspace = true
+chrono.workspace = true
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.60", features = ["Win32_System_Threading"] }
+# NTFS junctions for the shadow-home dir mirror (Node symlinkSync(..,
+# "junction") parity): junctions need no privilege, unlike symlink_dir.
+junction = "1"
+
+[dev-dependencies]
+tempfile.workspace = true
+serial_test.workspace = true
+proptest.workspace = true
+insta.workspace = true
+cma-testkit = { path = "../testkit" }
+
+[lints.rust]
+unsafe_code = "deny"
diff --git a/crates/wrapper/src/account_force.rs b/crates/wrapper/src/account_force.rs
new file mode 100644
index 000000000..748d7c4d0
--- /dev/null
+++ b/crates/wrapper/src/account_force.rs
@@ -0,0 +1,452 @@
+//! `--account` per-invocation force-pin (issue #623 / PR #624) — port of the
+//! forced-account half of `scripts/codex.js`.
+//!
+//! Selector rules (spec 03 + spec 14 §2.4):
+//! - ALL-DIGIT selector is ALWAYS a 1-based index (numeric account ids are
+//!   unreachable by id).
+//! - Otherwise matched against `accountId` / `email` (case-insensitive).
+//! - Env `CODEX_MULTI_AUTH_FORCE_ACCOUNT` has the same effect; the flag wins.
+//! - The resolved 0-based index is published as
+//!   `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX` (on the SPAWNED environment — the
+//!   Rust wrapper never mutates its own process env) and fed to the
+//!   in-process proxy via `RuntimeRotationProxyOptions::forced_account_index`.
+//! - FAIL-HARD before spawn: proxy disabled / `CODEX_MULTI_AUTH_BYPASS=1` /
+//!   no match / out-of-range / empty pool all error WITHOUT launching Codex.
+
+use serde_json::Value;
+
+use crate::statusline::{
+    read_json_file_quiet, resolve_accounts_path, resolve_status_accounts_dir,
+};
+
+/// TS `FORCE_ACCOUNT_ENV`.
+pub const FORCE_ACCOUNT_ENV: &str = "CODEX_MULTI_AUTH_FORCE_ACCOUNT";
+/// TS `FORCE_ACCOUNT_INDEX_ENV` (internal, wrapper-published, 0-based).
+pub const FORCE_ACCOUNT_INDEX_ENV: &str = "CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX";
+
+/// TS `extractForcedAccountFlag(args)` result.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExtractedForcedAccountFlag {
+    pub selector: Option<String>,
+    pub stripped_args: Vec<String>,
+    pub error: Option<String>,
+    pub saw_flag: bool,
+}
+
+/// TS `extractForcedAccountFlag(args)` — strip `--account <sel>` /
+/// `--account=<sel>`; the flag is launcher-only and must never be forwarded.
+/// The LAST occurrence wins when repeated.
+pub fn extract_forced_account_flag(args: &[String]) -> ExtractedForcedAccountFlag {
+    let mut stripped_args: Vec<String> = Vec::with_capacity(args.len());
+    let mut selector: Option<String> = None;
+    let mut saw_flag = false;
+    let mut index = 0usize;
+    while index < args.len() {
+        let arg = args[index].as_str();
+        if arg == "--account" {
+            saw_flag = true;
+            match args.get(index + 1) {
+                Some(next) => {
+                    selector = Some(next.clone());
+                    index += 2;
+                    continue;
+                }
+                None => {
+                    return ExtractedForcedAccountFlag {
+                        selector: None,
+                        stripped_args: args.to_vec(),
+                        error: Some(
+                            "codex-multi-auth: --account requires a value (account index, email, or account id)."
+                                .to_string(),
+                        ),
+                        saw_flag,
+                    };
+                }
+            }
+        }
+        if let Some(value) = arg.strip_prefix("--account=") {
+            saw_flag = true;
+            selector = Some(value.to_string());
+            index += 1;
+            continue;
+        }
+        stripped_args.push(args[index].clone());
+        index += 1;
+    }
+    ExtractedForcedAccountFlag {
+        selector,
+        stripped_args,
+        error: None,
+        saw_flag,
+    }
+}
+
+/// TS `resolveForcedAccountSelector(rawArgs, env)` result.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedForcedSelector {
+    pub selector: Option<String>,
+    pub stripped_args: Vec<String>,
+    pub error: Option<String>,
+}
+
+/// TS `resolveForcedAccountSelector(rawArgs, env)` — flag wins over env; an
+/// explicit empty flag value is an error; env is trimmed and ignored when
+/// empty.
+pub fn resolve_forced_account_selector(
+    raw_args: &[String],
+    env_selector: Option<&str>,
+) -> ResolvedForcedSelector {
+    let extracted = extract_forced_account_flag(raw_args);
+    if let Some(error) = extracted.error {
+        return ResolvedForcedSelector {
+            selector: None,
+            stripped_args: extracted.stripped_args,
+            error: Some(error),
+        };
+    }
+    if extracted.saw_flag {
+        let trimmed = extracted
+            .selector
+            .as_deref()
+            .unwrap_or("")
+            .trim()
+            .to_string();
+        if trimmed.is_empty() {
+            return ResolvedForcedSelector {
+                selector: None,
+                stripped_args: extracted.stripped_args,
+                error: Some(
+                    "codex-multi-auth: --account requires a non-empty value (account index, email, or account id)."
+                        .to_string(),
+                ),
+            };
+        }
+        return ResolvedForcedSelector {
+            selector: Some(trimmed),
+            stripped_args: extracted.stripped_args,
+            error: None,
+        };
+    }
+    let env_selector = env_selector.unwrap_or("").trim().to_string();
+    if !env_selector.is_empty() {
+        return ResolvedForcedSelector {
+            selector: Some(env_selector),
+            stripped_args: extracted.stripped_args,
+            error: None,
+        };
+    }
+    ResolvedForcedSelector {
+        selector: None,
+        stripped_args: extracted.stripped_args,
+        error: None,
+    }
+}
+
+/// TS `formatForcedAccountList(accounts)` — the 1-based listing appended to
+/// mismatch errors.
+pub fn format_forced_account_list(accounts: &[Value]) -> String {
+    let lines: Vec<String> = accounts
+        .iter()
+        .enumerate()
+        .map(|(index, account)| {
+            let email = account
+                .get("email")
+                .and_then(Value::as_str)
+                .map(str::trim)
+                .filter(|e| !e.is_empty())
+                .map(str::to_string)
+                .unwrap_or_else(|| format!("account {}", index + 1));
+            format!("  {}. {}", index + 1, email)
+        })
+        .collect();
+    format!("Available accounts:\n{}", lines.join("\n"))
+}
+
+fn normalize_identifier(value: Option<&str>) -> String {
+    match value {
+        // Full Unicode lowercasing (TS String.prototype.toLowerCase), not
+        // ASCII-only: `--account Ä@example.com` must match a stored
+        // `ä@example.com` — --account never falls back, so an ASCII-only
+        // mismatch fails the run hard.
+        Some(v) if !v.trim().is_empty() => v.trim().to_lowercase(),
+        _ => String::new(),
+    }
+}
+
+/// TS `findAccountIndexByIdOrEmail` specialized for the forced-account path
+/// (single selector matched against BOTH id and email).
+fn find_account_index_by_selector(accounts: &[Value], selector: &str) -> Option<usize> {
+    let normalized = normalize_identifier(Some(selector));
+    if normalized.is_empty() {
+        return None;
+    }
+    for (index, account) in accounts.iter().enumerate() {
+        if !account.is_object() {
+            continue;
+        }
+        if normalize_identifier(account.get("accountId").and_then(Value::as_str)) == normalized {
+            return Some(index);
+        }
+        if normalize_identifier(account.get("email").and_then(Value::as_str)) == normalized {
+            return Some(index);
+        }
+    }
+    None
+}
+
+/// Pure selector→index resolution against an accounts array (TS
+/// `resolveForcedAccountIndex` minus the disk read). Returns the 0-based
+/// index or the exact TS error string.
+pub fn resolve_forced_account_index_in(
+    accounts: &[Value],
+    selector: &str,
+) -> Result<usize, String> {
+    if accounts.is_empty() {
+        return Err(
+            "codex-multi-auth: --account was set but no Codex accounts are configured. Run `codex-multi-auth login` first."
+                .to_string(),
+        );
+    }
+    if !selector.is_empty() && selector.chars().all(|c| c.is_ascii_digit()) {
+        // ALL-DIGIT selector is ALWAYS a 1-based index.
+        let one_based: u64 = selector.parse().unwrap_or(u64::MAX);
+        if one_based < 1 || one_based as usize > accounts.len() {
+            return Err(format!(
+                "codex-multi-auth: --account {selector} is out of range (have {} account{}).\n{}",
+                accounts.len(),
+                if accounts.len() == 1 { "" } else { "s" },
+                format_forced_account_list(accounts)
+            ));
+        }
+        return Ok(one_based as usize - 1);
+    }
+    match find_account_index_by_selector(accounts, selector) {
+        Some(index) => Ok(index),
+        None => Err(format!(
+            "codex-multi-auth: --account \"{selector}\" did not match any configured account.\n{}",
+            format_forced_account_list(accounts)
+        )),
+    }
+}
+
+/// TS `resolveForcedAccountIndex(selector, env)` — resolves against the same
+/// scoped accounts pool the runtime rotation proxy will load.
+pub fn resolve_forced_account_index(selector: &str) -> Result<usize, String> {
+    let accounts_dir = resolve_status_accounts_dir();
+    let storage = read_json_file_quiet(&resolve_accounts_path(&accounts_dir));
+    let accounts: Vec<Value> = storage
+        .as_ref()
+        .and_then(|s| s.get("accounts"))
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+    resolve_forced_account_index_in(&accounts, selector)
+}
+
+/// Outcome of [`apply_forced_account_selection`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ForcedAccountOutcome {
+    /// Forward with the flag stripped. `forced_index` is the resolved 0-based
+    /// pin (`None` when no forced account was requested — the spawn env must
+    /// then REMOVE any stray `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX`).
+    Forward {
+        forward_args: Vec<String>,
+        forced_index: Option<usize>,
+    },
+    /// Fail hard: print to stderr and exit non-zero WITHOUT launching Codex.
+    Error(String),
+}
+
+/// TS `applyForcedAccountSelection(rawArgs, env)` — full preflight. The
+/// `proxy_enabled` gate is computed by the caller (forward.rs owns
+/// `is_runtime_rotation_proxy_enabled`); it is only consulted when a forced
+/// account was actually requested, mirroring the TS await order.
+pub async fn apply_forced_account_selection(
+    raw_args: &[String],
+    proxy_enabled_for: impl AsyncFn(&[String]) -> bool,
+) -> ForcedAccountOutcome {
+    let env_selector = std::env::var(FORCE_ACCOUNT_ENV).ok();
+    let forced = resolve_forced_account_selector(raw_args, env_selector.as_deref());
+    if let Some(error) = forced.error {
+        return ForcedAccountOutcome::Error(error);
+    }
+    let Some(selector) = forced.selector else {
+        // Defensive: a request without --account can never inherit an
+        // unintended pin (the caller strips the internal env var from the
+        // spawn environment when forced_index is None).
+        return ForcedAccountOutcome::Forward {
+            forward_args: raw_args.to_vec(),
+            forced_index: None,
+        };
+    };
+    // The pin can only be honored when the runtime rotation proxy is active
+    // for this command; fail hard instead of silently using another account.
+    if !proxy_enabled_for(&forced.stripped_args).await {
+        return ForcedAccountOutcome::Error(
+            [
+                "codex-multi-auth: --account requires the runtime rotation proxy, which is not active for this command.",
+                "Enable it with `codex-multi-auth rotation enable`, and make sure CODEX_MULTI_AUTH_BYPASS is not set.",
+            ]
+            .join("\n"),
+        );
+    }
+    match resolve_forced_account_index(&selector) {
+        Ok(index) => ForcedAccountOutcome::Forward {
+            forward_args: forced.stripped_args,
+            forced_index: Some(index),
+        },
+        Err(error) => ForcedAccountOutcome::Error(error),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn v(args: &[&str]) -> Vec<String> {
+        args.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn accounts3() -> Vec<Value> {
+        vec![
+            json!({"accountId": "acc_alpha", "email": "first@x.com"}),
+            json!({"accountId": "acc_beta", "email": "second@x.com"}),
+            json!({"accountId": "12345", "email": "third@x.com"}),
+        ]
+    }
+
+    #[test]
+    fn flag_extraction_space_and_equals_forms() {
+        let extracted = extract_forced_account_flag(&v(&["exec", "--account", "2", "task"]));
+        assert_eq!(extracted.selector.as_deref(), Some("2"));
+        assert_eq!(extracted.stripped_args, v(&["exec", "task"]));
+        assert!(extracted.saw_flag);
+        assert!(extracted.error.is_none());
+
+        let extracted = extract_forced_account_flag(&v(&["--account=me@x.com", "exec"]));
+        assert_eq!(extracted.selector.as_deref(), Some("me@x.com"));
+        assert_eq!(extracted.stripped_args, v(&["exec"]));
+
+        // Last occurrence wins.
+        let extracted =
+            extract_forced_account_flag(&v(&["--account", "1", "--account=2"]));
+        assert_eq!(extracted.selector.as_deref(), Some("2"));
+        assert!(extracted.stripped_args.is_empty());
+    }
+
+    #[test]
+    fn flag_missing_value_is_error() {
+        let extracted = extract_forced_account_flag(&v(&["exec", "--account"]));
+        assert_eq!(
+            extracted.error.as_deref(),
+            Some("codex-multi-auth: --account requires a value (account index, email, or account id).")
+        );
+        // Args untouched on error.
+        assert_eq!(extracted.stripped_args, v(&["exec", "--account"]));
+    }
+
+    #[test]
+    fn selector_resolution_flag_wins_over_env() {
+        let resolved = resolve_forced_account_selector(&v(&["--account", "2"]), Some("9"));
+        assert_eq!(resolved.selector.as_deref(), Some("2"));
+        let resolved = resolve_forced_account_selector(&v(&["exec"]), Some(" env@x.com "));
+        assert_eq!(resolved.selector.as_deref(), Some("env@x.com"));
+        assert_eq!(resolved.stripped_args, v(&["exec"]));
+        let resolved = resolve_forced_account_selector(&v(&["exec"]), None);
+        assert_eq!(resolved.selector, None);
+        // Empty flag value fails hard even with env fallback available.
+        let resolved = resolve_forced_account_selector(&v(&["--account", "  "]), Some("2"));
+        assert_eq!(
+            resolved.error.as_deref(),
+            Some("codex-multi-auth: --account requires a non-empty value (account index, email, or account id).")
+        );
+    }
+
+    #[test]
+    fn all_digit_selector_is_always_one_based_index() {
+        let accounts = accounts3();
+        // "12345" matches an accountId literally, but digits NEVER match ids.
+        let err = resolve_forced_account_index_in(&accounts, "12345").unwrap_err();
+        assert!(err.contains("--account 12345 is out of range (have 3 accounts)"));
+        assert!(err.contains("Available accounts:"));
+        assert!(err.contains("  1. first@x.com"));
+        assert_eq!(resolve_forced_account_index_in(&accounts, "1").unwrap(), 0);
+        assert_eq!(resolve_forced_account_index_in(&accounts, "3").unwrap(), 2);
+        let err = resolve_forced_account_index_in(&accounts, "0").unwrap_err();
+        assert!(err.contains("out of range"));
+        let err = resolve_forced_account_index_in(&accounts, "4").unwrap_err();
+        assert!(err.contains("out of range"));
+    }
+
+    #[test]
+    fn email_and_account_id_selectors() {
+        let accounts = accounts3();
+        assert_eq!(
+            resolve_forced_account_index_in(&accounts, "SECOND@X.COM").unwrap(),
+            1
+        );
+        assert_eq!(
+            resolve_forced_account_index_in(&accounts, "acc_beta").unwrap(),
+            1
+        );
+        let err = resolve_forced_account_index_in(&accounts, "missing@x.com").unwrap_err();
+        assert!(err.contains(
+            "--account \"missing@x.com\" did not match any configured account."
+        ));
+        assert!(err.contains("  3. third@x.com"));
+    }
+
+    #[test]
+    fn empty_pool_error_string() {
+        let err = resolve_forced_account_index_in(&[], "1").unwrap_err();
+        assert_eq!(
+            err,
+            "codex-multi-auth: --account was set but no Codex accounts are configured. Run `codex-multi-auth login` first."
+        );
+    }
+
+    #[test]
+    fn singular_plural_in_out_of_range_message() {
+        let accounts = vec![json!({"email": "only@x.com"})];
+        let err = resolve_forced_account_index_in(&accounts, "2").unwrap_err();
+        assert!(err.contains("(have 1 account)"));
+    }
+
+    #[test]
+    fn account_list_formatting_fallback_label() {
+        let accounts = vec![json!({"email": ""}), json!({"email": "b@x.com"})];
+        let list = format_forced_account_list(&accounts);
+        assert_eq!(list, "Available accounts:\n  1. account 1\n  2. b@x.com");
+    }
+
+    #[tokio::test]
+    async fn apply_no_selector_passes_through() {
+        let outcome =
+            apply_forced_account_selection(&v(&["exec", "task"]), async |_args| false).await;
+        assert_eq!(
+            outcome,
+            ForcedAccountOutcome::Forward {
+                forward_args: v(&["exec", "task"]),
+                forced_index: None
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn apply_fails_hard_when_proxy_disabled() {
+        let outcome =
+            apply_forced_account_selection(&v(&["--account", "1", "exec"]), async |_args| false)
+                .await;
+        match outcome {
+            ForcedAccountOutcome::Error(message) => {
+                assert!(message.contains(
+                    "--account requires the runtime rotation proxy, which is not active for this command."
+                ));
+                assert!(message.contains("codex-multi-auth rotation enable"));
+                assert!(message.contains("CODEX_MULTI_AUTH_BYPASS"));
+            }
+            other => panic!("expected error, got {other:?}"),
+        }
+    }
+}
diff --git a/crates/wrapper/src/bin_resolver.rs b/crates/wrapper/src/bin_resolver.rs
new file mode 100644
index 000000000..75d5990c8
--- /dev/null
+++ b/crates/wrapper/src/bin_resolver.rs
@@ -0,0 +1,499 @@
+//! Port of `scripts/codex-bin-resolver.js` — discovery of the OFFICIAL
+//! `@openai/codex` binary the wrapper forwards to.
+//!
+//! Resolution order (TS parity):
+//! 1. `CODEX_MULTI_AUTH_REAL_CODEX_BIN` override (exists → use; set-but-missing
+//!    → `None`, the caller prints the error).
+//! 2. Package-relative search roots: `<self dir>/../..` (+ npm prefix roots)
+//!    joined with `@openai/codex/bin/codex.js`.
+//! 3. `npm root -g` (via `cmd /d /s /c` on Windows) joined the same way.
+//! 4. PATH scan for `codex`/`codex.exe` with a self-recursion guard (skip our
+//!    own binary and anything inside our own directory), then `where codex` /
+//!    `which codex` as a last resort.
+//!
+//! Deviation vs TS: Node's `require.resolve("@openai/codex/bin/codex.js")`
+//! step has no Rust analogue; the search-root walk (which the TS also does)
+//! covers the same install layouts.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+/// TS `createResolvedCodexBin(path)` result shape.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedCodexBin {
+    pub path: PathBuf,
+    /// True when the target is a JS entry (`.js`/`.mjs`/`.cjs`) that must be
+    /// launched through `node`.
+    pub launch_with_node: bool,
+}
+
+fn is_javascript_entry_path(candidate: &Path) -> bool {
+    matches!(
+        candidate
+            .extension()
+            .and_then(|e| e.to_str())
+            .map(|e| e.to_ascii_lowercase())
+            .as_deref(),
+        Some("js") | Some("mjs") | Some("cjs")
+    )
+}
+
+fn create_resolved_codex_bin(path: PathBuf) -> ResolvedCodexBin {
+    let launch_with_node = is_javascript_entry_path(&path);
+    ResolvedCodexBin {
+        path,
+        launch_with_node,
+    }
+}
+
+/// TS `splitPathEntries(pathValue)` — split on the platform PATH delimiter,
+/// trim, drop empties.
+pub fn split_path_entries(path_value: &str) -> Vec<String> {
+    if path_value.trim().is_empty() {
+        return Vec::new();
+    }
+    let delimiter = if cfg!(windows) { ';' } else { ':' };
+    path_value
+        .split(delimiter)
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+fn normalize_resolved_path(candidate: &Path) -> PathBuf {
+    candidate
+        .canonicalize()
+        .unwrap_or_else(|_| candidate.to_path_buf())
+}
+
+/// TS `isWithinDirectory` — defense-in-depth self-recursion guard: skip any
+/// candidate that resolves inside the wrapper's own directory.
+fn is_within_directory(candidate: &Path, directory: &Path) -> bool {
+    let resolved = normalize_resolved_path(candidate);
+    resolved.starts_with(directory)
+}
+
+/// Injectable environment for [`resolve_real_codex_bin_with`]; tests can pin
+/// the env map, disable process spawns, and fake the self path.
+#[derive(Debug, Clone, Default)]
+pub struct BinResolverOptions {
+    /// Environment snapshot; `None` reads the process environment.
+    pub env: Option<HashMap<String, String>>,
+    /// The wrapper's own executable path (self-recursion guard). `None` uses
+    /// `std::env::current_exe()`.
+    pub self_path: Option<PathBuf>,
+    /// When false, skip the `npm root -g` and `where`/`which` subprocess
+    /// lookups (hermetic tests).
+    pub allow_process_lookups: bool,
+    /// Extra search roots probed FIRST (tests / embedding).
+    pub extra_search_roots: Vec<PathBuf>,
+}
+
+impl BinResolverOptions {
+    pub fn hermetic(env: HashMap<String, String>) -> Self {
+        Self {
+            env: Some(env),
+            self_path: None,
+            allow_process_lookups: false,
+            extra_search_roots: Vec::new(),
+        }
+    }
+}
+
+fn env_get(env: &Option<HashMap<String, String>>, key: &str) -> Option<String> {
+    match env {
+        Some(map) => map.get(key).cloned(),
+        None => std::env::var(key).ok(),
+    }
+}
+
+fn resolve_windows_cmd_path(env: &Option<HashMap<String, String>>) -> String {
+    let com_spec = env_get(env, "ComSpec")
+        .or_else(|| env_get(env, "COMSPEC"))
+        .unwrap_or_default();
+    let com_spec = com_spec.trim();
+    if !com_spec.is_empty() {
+        return com_spec.to_string();
+    }
+    let system_root = env_get(env, "SystemRoot")
+        .or_else(|| env_get(env, "SYSTEMROOT"))
+        .unwrap_or_default();
+    let system_root = system_root.trim();
+    if !system_root.is_empty() {
+        let trimmed = system_root.trim_end_matches(['\\', '/']);
+        return format!("{trimmed}\\System32\\cmd.exe");
+    }
+    "cmd.exe".to_string()
+}
+
+fn candidate_executable_names() -> &'static [&'static str] {
+    if cfg!(windows) {
+        &["codex.exe", "codex"]
+    } else {
+        &["codex"]
+    }
+}
+
+fn self_guard_skips(candidate: &Path, self_script_path: Option<&Path>) -> bool {
+    let Some(self_path) = self_script_path else {
+        return false;
+    };
+    if normalize_resolved_path(candidate) == *self_path {
+        return true;
+    }
+    if let Some(dir) = self_path.parent()
+        && is_within_directory(candidate, dir)
+    {
+        return true;
+    }
+    false
+}
+
+fn resolve_codex_executable_from_path_entries(
+    path_entries: &[String],
+    self_script_path: Option<&Path>,
+) -> Option<PathBuf> {
+    for entry in path_entries {
+        for executable_name in candidate_executable_names() {
+            let candidate = Path::new(entry).join(executable_name);
+            if !candidate.exists() {
+                continue;
+            }
+            if self_guard_skips(&candidate, self_script_path) {
+                continue;
+            }
+            return Some(candidate);
+        }
+    }
+    None
+}
+
+fn normalize_where_output(stdout: &str) -> Vec<String> {
+    stdout
+        .split(['\r', '\n'])
+        .map(str::trim)
+        .filter(|line| !line.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+/// Run a lookup command with a 5 s deadline (TS `spawnSync … timeout: 5000`).
+fn run_lookup_command(program: &str, args: &[&str]) -> Option<String> {
+    let mut child = Command::new(program)
+        .args(args)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .ok()?;
+    let deadline = Instant::now() + Duration::from_millis(5000);
+    loop {
+        match child.try_wait() {
+            Ok(Some(status)) => {
+                if !status.success() {
+                    return None;
+                }
+                let mut output = String::new();
+                use std::io::Read;
+                if let Some(mut stdout) = child.stdout.take() {
+                    let _ = stdout.read_to_string(&mut output);
+                }
+                return Some(output);
+            }
+            Ok(None) => {
+                if Instant::now() >= deadline {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    return None;
+                }
+                std::thread::sleep(Duration::from_millis(25));
+            }
+            Err(_) => return None,
+        }
+    }
+}
+
+fn resolve_codex_executable_from_system_path(
+    options: &BinResolverOptions,
+    self_script_path: Option<&Path>,
+) -> Option<PathBuf> {
+    let path_value = env_get(&options.env, "PATH")
+        .or_else(|| env_get(&options.env, "Path"))
+        .unwrap_or_default();
+    let path_entries = split_path_entries(&path_value);
+    if let Some(found) = resolve_codex_executable_from_path_entries(&path_entries, self_script_path)
+    {
+        return Some(found);
+    }
+
+    if !options.allow_process_lookups {
+        return None;
+    }
+
+    let stdout = if cfg!(windows) {
+        let cmd = resolve_windows_cmd_path(&options.env);
+        run_lookup_command(&cmd, &["/d", "/s", "/c", "where codex"])?
+    } else {
+        run_lookup_command("which", &["codex"])?
+    };
+    for candidate in normalize_where_output(&stdout) {
+        let candidate_path = Path::new(&candidate);
+        if !candidate_path.exists() {
+            continue;
+        }
+        if self_guard_skips(candidate_path, self_script_path) {
+            continue;
+        }
+        let file_name = candidate_path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .map(|n| n.to_ascii_lowercase())
+            .unwrap_or_default();
+        if file_name == "codex" || file_name == "codex.exe" {
+            return Some(candidate_path.to_path_buf());
+        }
+    }
+    None
+}
+
+fn npm_global_root(options: &BinResolverOptions) -> Option<String> {
+    if !options.allow_process_lookups {
+        return None;
+    }
+    let stdout = if cfg!(windows) {
+        let cmd = resolve_windows_cmd_path(&options.env);
+        run_lookup_command(&cmd, &["/d", "/s", "/c", "npm root -g"])?
+    } else {
+        run_lookup_command("npm", &["root", "-g"])?
+    };
+    let trimmed = stdout.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// TS `resolveRealCodexBin(options)` with the process environment.
+pub fn resolve_real_codex_bin() -> Option<ResolvedCodexBin> {
+    resolve_real_codex_bin_with(&BinResolverOptions {
+        env: None,
+        self_path: None,
+        allow_process_lookups: true,
+        extra_search_roots: Vec::new(),
+    })
+}
+
+/// TS `resolveRealCodexBin(options)` — full resolution ladder.
+pub fn resolve_real_codex_bin_with(options: &BinResolverOptions) -> Option<ResolvedCodexBin> {
+    // 1. Explicit override.
+    let override_value = env_get(&options.env, "CODEX_MULTI_AUTH_REAL_CODEX_BIN")
+        .unwrap_or_default()
+        .trim()
+        .to_string();
+    if !override_value.is_empty() {
+        let override_path = PathBuf::from(&override_value);
+        if override_path.exists() {
+            return Some(create_resolved_codex_bin(override_path));
+        }
+        return None;
+    }
+
+    // Self path for the recursion guard (resolved once, TS parity).
+    let self_script_path: Option<PathBuf> = options
+        .self_path
+        .clone()
+        .or_else(|| std::env::current_exe().ok())
+        .map(|p| normalize_resolved_path(&p));
+
+    // 2. Package-relative search roots.
+    let mut search_roots: Vec<PathBuf> = options.extra_search_roots.clone();
+    if let Some(self_path) = &self_script_path
+        && let Some(script_dir) = self_path.parent()
+    {
+        search_roots.push(script_dir.join("..").join(".."));
+    }
+    let npm_prefix = env_get(&options.env, "npm_config_prefix")
+        .or_else(|| env_get(&options.env, "PREFIX"))
+        .unwrap_or_default();
+    let npm_prefix = npm_prefix.trim();
+    if !npm_prefix.is_empty() {
+        search_roots.push(Path::new(npm_prefix).join("node_modules"));
+        search_roots.push(Path::new(npm_prefix).join("lib").join("node_modules"));
+    }
+    for root in &search_roots {
+        let candidate = root
+            .join("@openai")
+            .join("codex")
+            .join("bin")
+            .join("codex.js");
+        if candidate.exists() {
+            return Some(create_resolved_codex_bin(candidate));
+        }
+    }
+
+    // 3. npm root -g.
+    if let Some(global_root) = npm_global_root(options) {
+        let global_bin = Path::new(&global_root)
+            .join("@openai")
+            .join("codex")
+            .join("bin")
+            .join("codex.js");
+        if global_bin.exists() {
+            return Some(create_resolved_codex_bin(global_bin));
+        }
+    }
+
+    // 4. Native codex on PATH (+ where/which fallback).
+    resolve_codex_executable_from_system_path(options, self_script_path.as_deref())
+        .map(create_resolved_codex_bin)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn env(pairs: &[(&str, &str)]) -> HashMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn split_path_entries_handles_empty_and_trims() {
+        assert!(split_path_entries("").is_empty());
+        assert!(split_path_entries("   ").is_empty());
+        let sep = if cfg!(windows) { ";" } else { ":" };
+        let joined = format!(" /a {sep}{sep} /b ");
+        assert_eq!(split_path_entries(&joined), vec!["/a", "/b"]);
+    }
+
+    #[test]
+    fn js_entries_launch_with_node() {
+        assert!(create_resolved_codex_bin(PathBuf::from("a/codex.js")).launch_with_node);
+        assert!(create_resolved_codex_bin(PathBuf::from("a/codex.MJS")).launch_with_node);
+        assert!(create_resolved_codex_bin(PathBuf::from("a/codex.cjs")).launch_with_node);
+        assert!(!create_resolved_codex_bin(PathBuf::from("a/codex.exe")).launch_with_node);
+        assert!(!create_resolved_codex_bin(PathBuf::from("a/codex")).launch_with_node);
+    }
+
+    #[test]
+    fn override_missing_returns_none() {
+        let temp = tempfile::tempdir().unwrap();
+        let missing = temp.path().join("nope").join("codex.js");
+        let options = BinResolverOptions::hermetic(env(&[(
+            "CODEX_MULTI_AUTH_REAL_CODEX_BIN",
+            missing.to_str().unwrap(),
+        )]));
+        assert_eq!(resolve_real_codex_bin_with(&options), None);
+    }
+
+    #[test]
+    fn override_existing_wins() {
+        let temp = tempfile::tempdir().unwrap();
+        let target = temp.path().join("codex.js");
+        std::fs::write(&target, "// stub").unwrap();
+        let options = BinResolverOptions::hermetic(env(&[(
+            "CODEX_MULTI_AUTH_REAL_CODEX_BIN",
+            target.to_str().unwrap(),
+        )]));
+        let resolved = resolve_real_codex_bin_with(&options).unwrap();
+        assert_eq!(resolved.path, target);
+        assert!(resolved.launch_with_node);
+    }
+
+    #[test]
+    fn search_roots_find_openai_codex_package_bin() {
+        let temp = tempfile::tempdir().unwrap();
+        let bin_dir = temp
+            .path()
+            .join("@openai")
+            .join("codex")
+            .join("bin");
+        std::fs::create_dir_all(&bin_dir).unwrap();
+        let target = bin_dir.join("codex.js");
+        std::fs::write(&target, "// stub").unwrap();
+        let mut options = BinResolverOptions::hermetic(env(&[]));
+        options.extra_search_roots = vec![temp.path().to_path_buf()];
+        // Self path outside the temp tree so the guard does not interfere.
+        options.self_path = Some(PathBuf::from("Z:/definitely/not/here/codex-wrapper.exe"));
+        let resolved = resolve_real_codex_bin_with(&options).unwrap();
+        assert_eq!(normalize_resolved_path(&resolved.path), normalize_resolved_path(&target));
+        assert!(resolved.launch_with_node);
+    }
+
+    #[test]
+    fn npm_prefix_roots_probed() {
+        let temp = tempfile::tempdir().unwrap();
+        let bin_dir = temp
+            .path()
+            .join("lib")
+            .join("node_modules")
+            .join("@openai")
+            .join("codex")
+            .join("bin");
+        std::fs::create_dir_all(&bin_dir).unwrap();
+        std::fs::write(bin_dir.join("codex.js"), "// stub").unwrap();
+        let mut options = BinResolverOptions::hermetic(env(&[(
+            "npm_config_prefix",
+            temp.path().to_str().unwrap(),
+        )]));
+        options.self_path = Some(PathBuf::from("Z:/definitely/not/here/codex-wrapper.exe"));
+        let resolved = resolve_real_codex_bin_with(&options).unwrap();
+        assert!(resolved.launch_with_node);
+    }
+
+    #[test]
+    fn path_scan_skips_self_directory() {
+        let temp = tempfile::tempdir().unwrap();
+        // The "self" wrapper lives in this directory and is itself named codex.exe.
+        let self_dir = temp.path().join("wrapper-bin");
+        std::fs::create_dir_all(&self_dir).unwrap();
+        let self_name = if cfg!(windows) { "codex.exe" } else { "codex" };
+        let self_binary = self_dir.join(self_name);
+        std::fs::write(&self_binary, "self").unwrap();
+
+        // A real codex lives in another PATH entry.
+        let real_dir = temp.path().join("real-bin");
+        std::fs::create_dir_all(&real_dir).unwrap();
+        let real_binary = real_dir.join(self_name);
+        std::fs::write(&real_binary, "real").unwrap();
+
+        let path_value = format!(
+            "{}{}{}",
+            self_dir.display(),
+            if cfg!(windows) { ";" } else { ":" },
+            real_dir.display()
+        );
+        let mut options = BinResolverOptions::hermetic(env(&[("PATH", path_value.as_str())]));
+        options.self_path = Some(normalize_resolved_path(&self_binary));
+        let resolved = resolve_real_codex_bin_with(&options).unwrap();
+        assert_eq!(
+            normalize_resolved_path(&resolved.path),
+            normalize_resolved_path(&real_binary)
+        );
+        assert!(!resolved.launch_with_node);
+    }
+
+    #[test]
+    fn windows_cmd_path_resolution_ladder() {
+        let e = Some(env(&[("ComSpec", "C:\\Windows\\system32\\cmd.exe")]));
+        assert_eq!(resolve_windows_cmd_path(&e), "C:\\Windows\\system32\\cmd.exe");
+        let e = Some(env(&[("SystemRoot", "C:\\Windows\\")]));
+        assert_eq!(resolve_windows_cmd_path(&e), "C:\\Windows\\System32\\cmd.exe");
+        let e = Some(env(&[]));
+        assert_eq!(resolve_windows_cmd_path(&e), "cmd.exe");
+    }
+
+    #[test]
+    fn where_output_normalization() {
+        assert_eq!(
+            normalize_where_output("C:\\a\\codex.exe\r\n C:\\b\\codex \r\n\r\n"),
+            vec!["C:\\a\\codex.exe", "C:\\b\\codex"]
+        );
+    }
+}
diff --git a/crates/wrapper/src/forward.rs b/crates/wrapper/src/forward.rs
new file mode 100644
index 000000000..5d82561de
--- /dev/null
+++ b/crates/wrapper/src/forward.rs
@@ -0,0 +1,3102 @@
+//! The forwarding engine — port of `scripts/codex.js` (minus the manager
+//! dispatch itself, which lives in `cma-manager`; see the DESIGN BOUNDARY in
+//! the crate docs: this crate only CLASSIFIES auth-family args, the cma-bin
+//! mains route them).
+//!
+//! Responsibilities:
+//! - arg classification ([`classify_wrapper_args`]) — auth-family vs forward;
+//! - `-c cli_auth_credentials_store="file"` injection (opt-out
+//!   `CODEX_MULTI_AUTH_FORCE_FILE_AUTH_STORE=0`);
+//! - wrapper-side model alias/effort coercion + unsupported-model retry;
+//! - runtime rotation proxy startup + shadow `CODEX_HOME` + provider env for
+//!   the spawned official codex;
+//! - `--account` force-pin plumbing (fail-hard before spawn — #623);
+//! - app / interactive-TUI runtime helper (detached self-spawn) and the
+//!   app-server account/read protocol proxy;
+//! - forwarded runtime observability + session-index repair.
+
+use std::collections::{HashMap, HashSet};
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::Duration;
+
+use serde_json::Value;
+
+use crate::account_force::{apply_forced_account_selection, ForcedAccountOutcome, FORCE_ACCOUNT_INDEX_ENV};
+use crate::bin_resolver::{resolve_real_codex_bin, ResolvedCodexBin};
+use crate::routing::{
+    is_codex_app_command, is_codex_app_server_command, is_codex_interactive_tui_command,
+    is_rotation_enable_command, normalize_auth_alias, should_handle_multi_auth_auth,
+    should_track_forwarded_runtime_observability, should_use_runtime_routing_for_forwarded_args,
+};
+use crate::shadow_home::{
+    acquire_shadow_home_sync_lock, create_runtime_rotation_proxy_codex_home,
+    create_shadow_home_mirror, remove_directory_with_retry, resolve_codex_home_dir,
+    resolve_original_multi_auth_dir, resolve_runtime_rotation_original_multi_auth_dir,
+    resolve_runtime_rotation_proxy_original_codex_home, write_owner_only_json_file_atomic_sync,
+    MirrorOptions, ShadowHomeContext,
+};
+
+pub const APP_SERVER_ACCOUNT_DISPLAY_NAME: &str = "codex-multi-auth";
+pub const APP_SERVER_ACCOUNT_LABEL_ENV: &str = "CODEX_MULTI_AUTH_APP_SERVER_ACCOUNT_LABEL";
+pub const INTERNAL_RUNTIME_ROTATION_APP_HELPER_ARG: &str = "--codex-multi-auth-runtime-app-helper";
+pub const APP_RUNTIME_HELPER_OWNER_PID_ENV: &str = "CODEX_MULTI_AUTH_APP_ROTATION_OWNER_PID";
+pub const APP_RUNTIME_HELPER_REAL_CODEX_HOME_ENV: &str = "CODEX_MULTI_AUTH_REAL_CODEX_HOME";
+pub const DEFAULT_APP_RUNTIME_HELPER_IDLE_MS: i64 = 12 * 60 * 60 * 1000;
+pub const DEFAULT_APP_RUNTIME_HELPER_DETACH_GRACE_MS: i64 = 5_000;
+pub const APP_RUNTIME_HELPER_LAUNCH_TIMEOUT_MS: u64 = 15_000;
+pub const APP_SERVER_SHIM_DIR_NAME: &str = "app-server-shims";
+pub const APP_SERVER_SHIM_HELPER_PREFIX: &str = "helper-";
+
+fn env_string(name: &str) -> String {
+    std::env::var(name).unwrap_or_default()
+}
+
+fn process_env_map() -> HashMap<String, String> {
+    std::env::vars().collect()
+}
+
+// ===========================================================================
+// Classification (consumed by the cma-bin mains).
+// ===========================================================================
+
+/// How the cma-bin main should route this invocation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WrapperDispatch {
+    /// The internal detached app-helper child (`--codex-multi-auth-runtime-app-helper`).
+    RunAppHelper,
+    /// Auth-family command → `cma_manager::run_codex_multi_auth_cli(normalized_args)`.
+    AuthManager { normalized_args: Vec<String> },
+    /// Everything else → [`forward`].
+    Forward { raw_args: Vec<String> },
+}
+
+/// Classify raw argv (post bin-name). `CODEX_MULTI_AUTH_BYPASS=1` forces the
+/// forward path even for auth-family args (TS `main()` parity).
+pub fn classify_wrapper_args(raw_args: &[String]) -> WrapperDispatch {
+    if raw_args.first().map(String::as_str) == Some(INTERNAL_RUNTIME_ROTATION_APP_HELPER_ARG) {
+        return WrapperDispatch::RunAppHelper;
+    }
+    let normalized_args = normalize_auth_alias(raw_args);
+    let bypass = env_string("CODEX_MULTI_AUTH_BYPASS").trim() == "1";
+    if !bypass && should_handle_multi_auth_auth(&normalized_args) {
+        return WrapperDispatch::AuthManager { normalized_args };
+    }
+    WrapperDispatch::Forward {
+        raw_args: raw_args.to_vec(),
+    }
+}
+
+/// TS `maybeInstallCodexAppLauncherAfterRotationEnable(args, exitCode)` — the
+/// bin main calls this after a successful manager run.
+pub async fn maybe_install_codex_app_launcher_after_rotation_enable(
+    normalized_args: &[String],
+    exit_code: i32,
+) {
+    if exit_code != 0 || !is_rotation_enable_command(normalized_args) {
+        return;
+    }
+    let override_value = std::env::var("CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL")
+        .unwrap_or_else(|_| "1".to_string());
+    let normalized = override_value.trim().to_ascii_lowercase();
+    if matches!(normalized.as_str(), "0" | "false" | "no") {
+        return;
+    }
+    let options = cma_runtime::app_launcher::AppLauncherOptions::default();
+    if let Err(error) = cma_runtime::app_launcher::install_codex_app_launcher(&options).await {
+        eprintln!("codex-multi-auth: could not route Codex app launchers: {error}");
+    }
+}
+
+// ===========================================================================
+// Wrapper-side model resolution (kept in sync with lib/request model-map).
+// ===========================================================================
+
+pub const CURRENT_CODEX_MODEL: &str = "gpt-5.3-codex";
+pub const LEGACY_CODEX_MODEL: &str = "gpt-5-codex";
+const DEFAULT_GENERAL_GPT5_MODEL: &str = "gpt-5.5";
+const GPT_5_6_SOL_MODEL: &str = "gpt-5.6-sol";
+const GPT_5_6_TERRA_MODEL: &str = "gpt-5.6-terra";
+const GPT_5_6_LUNA_MODEL: &str = "gpt-5.6-luna";
+
+/// TS `WRAPPER_UNSUPPORTED_MODEL_FALLBACK_CHAIN`.
+pub fn wrapper_unsupported_model_fallback_chain(model: &str) -> &'static [&'static str] {
+    match model {
+        "gpt-5" => &["gpt-5.5"],
+        "gpt-5-pro" => &["gpt-5.5-pro"],
+        "gpt-5-chat-latest" => &["gpt-5.5"],
+        "gpt-5.5" => &["gpt-5.4"],
+        "gpt-5.5-pro" => &["gpt-5.4"],
+        "gpt-5.5-2026-04-23" => &["gpt-5.4"],
+        "gpt-5.5-pro-2026-04-23" => &["gpt-5.4"],
+        "gpt-5.5-20260423" => &["gpt-5.4"],
+        "gpt-5.5-pro-20260423" => &["gpt-5.4"],
+        "gpt-5.3-codex-spark" => &[CURRENT_CODEX_MODEL],
+        "codex-max" => &[CURRENT_CODEX_MODEL],
+        "gpt-5.1-codex-max" => &[CURRENT_CODEX_MODEL],
+        "codex-mini-latest" => &[CURRENT_CODEX_MODEL],
+        "gpt-5-codex-mini" => &[CURRENT_CODEX_MODEL],
+        "gpt-5.1-codex-mini" => &[CURRENT_CODEX_MODEL],
+        "gpt-5-codex" => &[CURRENT_CODEX_MODEL],
+        "gpt-5.2-codex" => &[CURRENT_CODEX_MODEL],
+        "gpt-5.1-codex" => &[CURRENT_CODEX_MODEL],
+        _ => &[],
+    }
+}
+
+/// TS `SUPPORTED_REASONING_EFFORTS_BY_MODEL`.
+fn supported_reasoning_efforts_by_model(model: &str) -> Option<&'static [&'static str]> {
+    Some(match model {
+        "gpt-5.3-codex" => &["low", "medium", "high", "xhigh"],
+        "gpt-5.6-sol" | "gpt-5.6-terra" => &["low", "medium", "high", "xhigh", "max", "ultra"],
+        "gpt-5.6-luna" => &["low", "medium", "high", "xhigh", "max"],
+        "gpt-5.5" => &["none", "low", "medium", "high", "xhigh"],
+        "gpt-5.5-pro" => &["medium", "high", "xhigh"],
+        "gpt-5.4" => &["none", "low", "medium", "high", "xhigh"],
+        "gpt-5.4-pro" => &["medium", "high", "xhigh"],
+        "gpt-5.4-mini" => &["medium"],
+        "gpt-5.4-nano" => &["medium"],
+        "gpt-5.2-pro" => &["medium", "high", "xhigh"],
+        "gpt-5.2" => &["none", "low", "medium", "high", "xhigh"],
+        "gpt-5.1" => &["none", "low", "medium", "high"],
+        "gpt-5-mini" => &["medium"],
+        "gpt-5-nano" => &["medium"],
+        _ => return None,
+    })
+}
+
+/// TS `REASONING_FALLBACKS`.
+fn reasoning_fallbacks(effort: &str) -> Option<&'static [&'static str]> {
+    Some(match effort {
+        "none" => &["none", "low", "minimal", "medium", "high", "xhigh"],
+        "minimal" => &["minimal", "low", "none", "medium", "high", "xhigh"],
+        "low" => &["low", "minimal", "none", "medium", "high", "xhigh"],
+        "medium" => &["medium", "low", "high", "minimal", "none", "xhigh"],
+        "high" => &["high", "medium", "xhigh", "low", "minimal", "none"],
+        "xhigh" => &["xhigh", "high", "medium", "low", "minimal", "none"],
+        "max" => &["max", "xhigh", "high", "medium", "low", "minimal", "none"],
+        "ultra" => &["ultra", "max", "xhigh", "high", "medium", "low", "minimal", "none"],
+        _ => return None,
+    })
+}
+
+const REASONING_ALIAS_VARIANTS: &[&str] = &["none", "minimal", "low", "medium", "high", "xhigh"];
+const GPT_5_6_SOL_TERRA_EFFORTS: &[&str] = &["low", "medium", "high", "xhigh", "max", "ultra"];
+const GPT_5_6_LUNA_EFFORTS: &[&str] = &["low", "medium", "high", "xhigh", "max"];
+
+fn requested_model_aliases() -> &'static HashMap<String, String> {
+    static CELL: OnceLock<HashMap<String, String>> = OnceLock::new();
+    CELL.get_or_init(|| {
+        let mut map: HashMap<String, String> = HashMap::new();
+        // (alias, normalized) with the pre-5.6 effort-suffix variants.
+        let reasoning_seeded: &[(&str, &str)] = &[
+            ("gpt-5.5", "gpt-5.5"),
+            ("gpt-5.5-2026-04-23", "gpt-5.5"),
+            ("gpt-5.5-20260423", "gpt-5.5"),
+            ("gpt-5.5-pro", "gpt-5.5-pro"),
+            ("gpt-5.5-pro-2026-04-23", "gpt-5.5-pro"),
+            ("gpt-5.5-pro-20260423", "gpt-5.5-pro"),
+            ("gpt-5.4", "gpt-5.4"),
+            ("gpt-5.4-pro", "gpt-5.4-pro"),
+            ("gpt-5.4-mini", "gpt-5.4-mini"),
+            ("gpt-5.4-nano", "gpt-5.4-nano"),
+            ("gpt-5.2-pro", "gpt-5.2-pro"),
+            ("gpt-5-pro", "gpt-5.5-pro"),
+            ("gpt-5.2", "gpt-5.2"),
+            ("gpt-5.1", "gpt-5.1"),
+            ("gpt-5", DEFAULT_GENERAL_GPT5_MODEL),
+            ("gpt-5-mini", "gpt-5-mini"),
+            ("gpt-5-nano", "gpt-5-nano"),
+            ("gpt-5.1-chat-latest", "gpt-5.1"),
+            ("gpt-5-chat-latest", DEFAULT_GENERAL_GPT5_MODEL),
+            (CURRENT_CODEX_MODEL, CURRENT_CODEX_MODEL),
+            ("gpt-5.3-codex-spark", CURRENT_CODEX_MODEL),
+            (LEGACY_CODEX_MODEL, CURRENT_CODEX_MODEL),
+            ("gpt-5.2-codex", CURRENT_CODEX_MODEL),
+            ("gpt-5.1-codex", CURRENT_CODEX_MODEL),
+            ("codex-max", CURRENT_CODEX_MODEL),
+            ("gpt-5.1-codex-max", CURRENT_CODEX_MODEL),
+            ("gpt-5-codex-mini", CURRENT_CODEX_MODEL),
+            ("gpt-5.1-codex-mini", CURRENT_CODEX_MODEL),
+        ];
+        for (alias, normalized) in reasoning_seeded {
+            map.insert((*alias).to_string(), (*normalized).to_string());
+            for effort in REASONING_ALIAS_VARIANTS {
+                map.insert(format!("{alias}-{effort}"), (*normalized).to_string());
+            }
+        }
+        // (alias, normalized, explicit effort set) — GPT-5.6 tiers.
+        let effort_seeded: &[(&str, &str, &[&str])] = &[
+            (GPT_5_6_SOL_MODEL, GPT_5_6_SOL_MODEL, GPT_5_6_SOL_TERRA_EFFORTS),
+            (GPT_5_6_TERRA_MODEL, GPT_5_6_TERRA_MODEL, GPT_5_6_SOL_TERRA_EFFORTS),
+            (GPT_5_6_LUNA_MODEL, GPT_5_6_LUNA_MODEL, GPT_5_6_LUNA_EFFORTS),
+            ("gpt-5.6", GPT_5_6_SOL_MODEL, GPT_5_6_SOL_TERRA_EFFORTS),
+        ];
+        for (alias, normalized, efforts) in effort_seeded {
+            map.insert((*alias).to_string(), (*normalized).to_string());
+            for effort in *efforts {
+                map.insert(format!("{alias}-{effort}"), (*normalized).to_string());
+            }
+        }
+        // Plain aliases (no effort variants).
+        map.insert("gpt_5_codex".to_string(), CURRENT_CODEX_MODEL.to_string());
+        map.insert("codex-mini-latest".to_string(), CURRENT_CODEX_MODEL.to_string());
+        map
+    })
+}
+
+fn strip_provider_prefix(model: &str) -> &str {
+    match model.rfind('/') {
+        Some(pos) if model.contains('/') => &model[pos + 1..],
+        _ => model,
+    }
+}
+
+fn tokenize_requested_model(model: &str) -> Vec<String> {
+    model
+        .to_ascii_lowercase()
+        .split(|c: char| !c.is_ascii_alphanumeric())
+        .filter(|t| !t.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+fn resolve_codex_requested_model(normalized: &str) -> &'static str {
+    let includes = |needle: &str| normalized.contains(needle);
+    if includes("gpt-5.1-codex-max") || includes("gpt 5.1 codex max") || includes("codex-max") {
+        return CURRENT_CODEX_MODEL;
+    }
+    if includes("gpt-5.1-codex-mini")
+        || includes("gpt 5.1 codex mini")
+        || includes("gpt-5-codex-mini")
+        || includes("gpt 5 codex mini")
+        || includes("codex-mini-latest")
+    {
+        return CURRENT_CODEX_MODEL;
+    }
+    if includes("gpt-5.3-codex-spark")
+        || includes("gpt 5.3 codex spark")
+        || includes("gpt-5.3-codex")
+        || includes("gpt 5.3 codex")
+        || includes("gpt-5.2-codex")
+        || includes("gpt 5.2 codex")
+        || includes("gpt-5.1-codex")
+        || includes("gpt 5.1 codex")
+        || includes("gpt-5-codex")
+        || includes("gpt 5 codex")
+        || normalized == "codex"
+    {
+        return CURRENT_CODEX_MODEL;
+    }
+    ""
+}
+
+fn resolve_gpt56_requested_model(stripped: &str) -> &'static str {
+    let tokens = tokenize_requested_model(stripped);
+    let gpt_index = tokens.iter().position(|t| t == "gpt");
+    let is_gpt56 = gpt_index.is_some_and(|i| {
+        tokens.get(i + 1).map(String::as_str) == Some("5")
+            && tokens.get(i + 2).map(String::as_str) == Some("6")
+    });
+    if !is_gpt56 || tokens.iter().any(|t| t == "codex") {
+        return "";
+    }
+    if tokens.iter().any(|t| t == "terra") {
+        return GPT_5_6_TERRA_MODEL;
+    }
+    if tokens.iter().any(|t| t == "luna") {
+        return GPT_5_6_LUNA_MODEL;
+    }
+    GPT_5_6_SOL_MODEL
+}
+
+fn general_gpt5_catalog(minor: u32, variant: &str) -> Option<&'static str> {
+    let catalog: &[(&str, &str)] = match minor {
+        1 => &[("base", "gpt-5.1")],
+        2 => &[("base", "gpt-5.2"), ("pro", "gpt-5.2-pro")],
+        4 => &[
+            ("base", "gpt-5.5"),
+            ("pro", "gpt-5.4-pro"),
+            ("mini", "gpt-5.4-mini"),
+            ("nano", "gpt-5.4-nano"),
+        ],
+        5 => &[
+            ("base", "gpt-5.5"),
+            ("pro", "gpt-5.5-pro"),
+            ("mini", "gpt-5-mini"),
+            ("nano", "gpt-5-nano"),
+        ],
+        _ => return None,
+    };
+    catalog
+        .iter()
+        .find(|(v, _)| *v == variant)
+        .or_else(|| catalog.iter().find(|(v, _)| *v == "base"))
+        .map(|(_, m)| *m)
+}
+
+fn stable_general_gpt5_variant(variant: &str) -> &'static str {
+    match variant {
+        "pro" => "gpt-5.5-pro",
+        "mini" => "gpt-5-mini",
+        "nano" => "gpt-5-nano",
+        _ => "gpt-5.5",
+    }
+}
+
+fn resolve_general_gpt5_requested_model(stripped: &str) -> String {
+    let tokens = tokenize_requested_model(stripped);
+    let gpt_index = tokens.iter().position(|t| t == "gpt");
+    let is_gpt5 =
+        gpt_index.is_some_and(|i| tokens.get(i + 1).map(String::as_str) == Some("5"));
+    if !is_gpt5 || tokens.iter().any(|t| t == "codex") {
+        return String::new();
+    }
+    let raw_minor = gpt_index.and_then(|i| tokens.get(i + 2));
+    let minor: Option<u32> = raw_minor
+        .filter(|m| !m.is_empty() && m.chars().all(|c| c.is_ascii_digit()))
+        .and_then(|m| m.parse().ok());
+    let variant = if tokens.iter().any(|t| t == "mini") {
+        "mini"
+    } else if tokens.iter().any(|t| t == "nano") {
+        "nano"
+    } else if tokens.iter().any(|t| t == "pro") {
+        "pro"
+    } else {
+        "base"
+    };
+    let Some(minor) = minor else {
+        // Generic variants (no minor).
+        return match variant {
+            "pro" => "gpt-5.5-pro",
+            "mini" => "gpt-5-mini",
+            "nano" => "gpt-5-nano",
+            _ => DEFAULT_GENERAL_GPT5_MODEL,
+        }
+        .to_string();
+    };
+    if let Some(exact) = general_gpt5_catalog(minor, variant) {
+        return exact.to_string();
+    }
+    stable_general_gpt5_variant(variant).to_string()
+}
+
+/// TS `normalizeRequestedModel(model)`.
+pub fn normalize_requested_model(model: &str) -> String {
+    let stripped = strip_provider_prefix(model);
+    let normalized = stripped.trim().to_ascii_lowercase();
+    if normalized.is_empty() {
+        return String::new();
+    }
+    if let Some(exact) = requested_model_aliases().get(&normalized) {
+        return exact.clone();
+    }
+    let codex_model = resolve_codex_requested_model(&normalized);
+    if !codex_model.is_empty() {
+        return codex_model.to_string();
+    }
+    let gpt56 = resolve_gpt56_requested_model(stripped);
+    if !gpt56.is_empty() {
+        return gpt56.to_string();
+    }
+    resolve_general_gpt5_requested_model(stripped)
+}
+
+fn strip_effort_suffix(value: &str) -> String {
+    for effort in [
+        "-none", "-minimal", "-low", "-medium", "-high", "-xhigh", "-max", "-ultra",
+    ] {
+        if let Some(stripped) = value.strip_suffix(effort) {
+            return stripped.to_string();
+        }
+    }
+    value.to_string()
+}
+
+/// TS `canonicalizeRequestedModelName(model)`.
+pub fn canonicalize_requested_model_name(model: &str) -> String {
+    let normalized = normalize_requested_model(model);
+    if !normalized.is_empty() {
+        return normalized;
+    }
+    let stripped = strip_provider_prefix(model).trim().to_ascii_lowercase();
+    if stripped.is_empty() {
+        return String::new();
+    }
+    strip_effort_suffix(&stripped)
+}
+
+/// TS `canonicalizeUnsupportedModelKey(model)` — suffix strip only.
+pub fn canonicalize_unsupported_model_key(model: &str) -> String {
+    let stripped = strip_provider_prefix(model).trim().to_ascii_lowercase();
+    if stripped.is_empty() {
+        return String::new();
+    }
+    strip_effort_suffix(&stripped)
+}
+
+/// TS `resolveSupportedReasoningEffort`.
+fn resolve_supported_reasoning_effort<'a>(
+    normalized_effort: &'a str,
+    supported: Option<&'static [&'static str]>,
+) -> &'a str {
+    let Some(supported) = supported else {
+        return normalized_effort;
+    };
+    if supported.contains(&normalized_effort) {
+        return normalized_effort;
+    }
+    if let Some(order) = reasoning_fallbacks(normalized_effort) {
+        for candidate in order {
+            if supported.contains(candidate) {
+                return candidate;
+            }
+        }
+    }
+    normalized_effort
+}
+
+/// TS `coerceReasoningEffortForModel(model, effort)` — unknown efforts pass
+/// through untouched; `ultra` NEVER reaches the wire (rewritten to `max`).
+pub fn coerce_reasoning_effort_for_model(model: &str, effort: &str) -> String {
+    let normalized_effort = effort.trim().to_ascii_lowercase();
+    if reasoning_fallbacks(&normalized_effort).is_none() {
+        return effort.to_string();
+    }
+    let normalized_model = normalize_requested_model(model);
+    let supported = supported_reasoning_efforts_by_model(&normalized_model);
+    let resolved = resolve_supported_reasoning_effort(&normalized_effort, supported);
+    if resolved == "ultra" {
+        "max".to_string()
+    } else {
+        resolved.to_string()
+    }
+}
+
+/// TS `extractRequestedModel(args)`.
+pub fn extract_requested_model(args: &[String]) -> Option<String> {
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "--model" || arg == "-m" {
+            if let Some(next) = args.get(i + 1)
+                && !next.trim().is_empty()
+            {
+                return Some(next.trim().to_string());
+            }
+            i += 1;
+            continue;
+        }
+        if let Some(value) = arg.strip_prefix("--model=") {
+            let value = value.trim();
+            if !value.is_empty() {
+                return Some(value.to_string());
+            }
+        }
+        i += 1;
+    }
+    None
+}
+
+fn parse_config_assignment(value: &str) -> Option<(String, String)> {
+    let separator = value.find('=')?;
+    Some((
+        value[..separator].trim().to_string(),
+        value[separator + 1..].trim().to_string(),
+    ))
+}
+
+fn parse_quoted_value(value: &str) -> (char, String) {
+    let trimmed = value.trim();
+    let mut chars = trimmed.chars();
+    let first = chars.next();
+    let last = trimmed.chars().last();
+    if let (Some(f), Some(l)) = (first, last)
+        && (f == '"' || f == '\'')
+        && l == f
+        && trimmed.len() >= 2
+    {
+        return (f, trimmed[1..trimmed.len() - 1].to_string());
+    }
+    ('"', trimmed.to_string())
+}
+
+fn rewrite_reasoning_config_assignment(assignment: &str, requested_model: &str) -> String {
+    let Some((key, value)) = parse_config_assignment(assignment) else {
+        return assignment.to_string();
+    };
+    if key != "model_reasoning_effort" {
+        return assignment.to_string();
+    }
+    let (quote, inner) = parse_quoted_value(&value);
+    let coerced = coerce_reasoning_effort_for_model(requested_model, &inner);
+    if coerced == inner {
+        return assignment.to_string();
+    }
+    format!("{key}={quote}{coerced}{quote}")
+}
+
+/// TS `rewriteReasoningConfigArgs(rawArgs)` — coerce `-c
+/// model_reasoning_effort=…` for the requested model.
+pub fn rewrite_reasoning_config_args(raw_args: &[String]) -> (Vec<String>, Option<String>) {
+    let Some(requested_model) = extract_requested_model(raw_args) else {
+        return (raw_args.to_vec(), None);
+    };
+    let mut next_args = raw_args.to_vec();
+    let mut i = 0usize;
+    while i < next_args.len() {
+        let arg = next_args[i].clone();
+        if (arg == "-c" || arg == "--config") && i + 1 < next_args.len() {
+            next_args[i + 1] =
+                rewrite_reasoning_config_assignment(&next_args[i + 1], &requested_model);
+            i += 2;
+            continue;
+        }
+        if let Some(assignment) = arg.strip_prefix("--config=") {
+            next_args[i] = format!(
+                "--config={}",
+                rewrite_reasoning_config_assignment(assignment, &requested_model)
+            );
+        }
+        i += 1;
+    }
+    (next_args, Some(requested_model))
+}
+
+fn ensure_trailing_newline(value: &str) -> String {
+    if value.ends_with('\n') {
+        value.to_string()
+    } else {
+        format!("{value}\n")
+    }
+}
+
+/// TS `rewriteConfigTomlReasoningEffort(rawConfig, requestedModel)` —
+/// line-level rewrite of `model_reasoning_effort` (quoted or bare values).
+pub fn rewrite_config_toml_reasoning_effort(raw_config: &str, requested_model: &str) -> String {
+    let line_ending = if raw_config.contains("\r\n") { "\r\n" } else { "\n" };
+    let mut changed = false;
+    let lines: Vec<String> = raw_config
+        .split("\r\n")
+        .flat_map(|s| s.split('\n'))
+        .map(|line| {
+            let trimmed = line.trim_start();
+            let indent_len = line.len() - trimmed.len();
+            let Some(rest) = trimmed.strip_prefix("model_reasoning_effort") else {
+                return line.to_string();
+            };
+            let after_key = rest.trim_start();
+            let Some(after_eq) = after_key.strip_prefix('=') else {
+                return line.to_string();
+            };
+            let value_part = after_eq.trim_start();
+            let prefix_len = line.len() - value_part.len();
+            let prefix = &line[..prefix_len];
+            // Quoted form
+            if let Some(quote) = value_part.chars().next().filter(|c| *c == '"' || *c == '\'') {
+                let inner_start = 1;
+                if let Some(close) = value_part[inner_start..].find(quote) {
+                    let current = &value_part[inner_start..inner_start + close];
+                    let suffix = &value_part[inner_start + close..];
+                    let coerced = coerce_reasoning_effort_for_model(requested_model, current);
+                    if coerced != current {
+                        changed = true;
+                        return format!("{prefix}{quote}{coerced}{suffix}");
+                    }
+                }
+                return line.to_string();
+            }
+            // Bare form: value up to whitespace/#
+            let value_end = value_part
+                .find(|c: char| c.is_whitespace() || c == '#')
+                .unwrap_or(value_part.len());
+            if value_end == 0 {
+                return line.to_string();
+            }
+            let current = &value_part[..value_end];
+            let suffix = &value_part[value_end..];
+            let coerced = coerce_reasoning_effort_for_model(requested_model, current);
+            if coerced != current {
+                changed = true;
+                let _ = indent_len;
+                return format!("{prefix}{coerced}{suffix}");
+            }
+            line.to_string()
+        })
+        .collect();
+    if !changed {
+        return raw_config.to_string();
+    }
+    ensure_trailing_newline(&lines.join(line_ending))
+}
+
+// ===========================================================================
+// Unsupported-model output parsing + wrapper retry chain.
+// ===========================================================================
+
+/// Case-insensitive substring check.
+fn contains_ci(haystack_lower: &str, needle_lower: &str) -> bool {
+    haystack_lower.contains(needle_lower)
+}
+
+const UNSUPPORTED_SUBSTRING: &str = "model is not supported when using codex with a chatgpt account";
+const NORMALIZED_SUFFIX: &str =
+    " is not currently available for this chatgpt account when using codex oauth";
+const ACCESS_DENIED_SUFFIX: &str = " does not exist or you do not have access to it";
+
+fn find_quoted_capture(
+    haystack_lower: &str,
+    prefix_lower: &str,
+    suffix_lower: &str,
+    quotes: &[char],
+) -> Option<String> {
+    let mut search_from = 0usize;
+    while let Some(rel) = haystack_lower[search_from..].find(prefix_lower) {
+        let after_prefix = search_from + rel + prefix_lower.len();
+        let rest = &haystack_lower[after_prefix..];
+        let Some(open) = rest.chars().next().filter(|c| quotes.contains(c)) else {
+            search_from = after_prefix;
+            continue;
+        };
+        let inner = &rest[open.len_utf8()..];
+        let close_quotes: &[char] = quotes;
+        if let Some(close) = inner.find(|c: char| close_quotes.contains(&c)) {
+            let captured = &inner[..close];
+            let tail = &inner[close + inner[close..].chars().next().map(char::len_utf8).unwrap_or(1)..];
+            if tail.starts_with(suffix_lower) && !captured.is_empty() {
+                return Some(captured.to_string());
+            }
+        }
+        search_from = after_prefix;
+    }
+    None
+}
+
+/// TS `NORMALIZED_UNSUPPORTED_MODEL_PATTERN` capture.
+fn match_normalized_unsupported(output_lower: &str) -> Option<String> {
+    find_quoted_capture(output_lower, "model ", NORMALIZED_SUFFIX, &['\'', '"'])
+}
+
+/// TS `MODEL_ACCESS_DENIED_PATTERN` capture.
+fn match_access_denied(output_lower: &str) -> Option<String> {
+    find_quoted_capture(output_lower, "the model ", ACCESS_DENIED_SUFFIX, &['`', '\'', '"'])
+}
+
+/// TS `DIRECT_UNSUPPORTED_MODEL_PATTERN` capture —
+/// `['"]model['"]\s+model is not supported…`.
+fn match_direct_unsupported(output_lower: &str) -> Option<String> {
+    let bytes = output_lower.as_bytes();
+    let mut i = 0usize;
+    while i < bytes.len() {
+        let c = bytes[i] as char;
+        if c == '\'' || c == '"' {
+            let open = c;
+            if let Some(close_rel) = output_lower[i + 1..].find(['\'', '"']) {
+                let close_index = i + 1 + close_rel;
+                let close_char = output_lower[close_index..].chars().next().unwrap_or(open);
+                if close_char == open {
+                    let captured = &output_lower[i + 1..close_index];
+                    let tail = output_lower[close_index + 1..].trim_start();
+                    if !captured.is_empty() && tail.starts_with(UNSUPPORTED_SUBSTRING) {
+                        return Some(captured.to_string());
+                    }
+                }
+            }
+        }
+        i += 1;
+    }
+    None
+}
+
+/// TS `extractUnsupportedModelFromOutput(output)`.
+pub fn extract_unsupported_model_from_output(output: &str) -> Option<String> {
+    if output.is_empty() {
+        return None;
+    }
+    let lower = output.to_ascii_lowercase();
+    if let Some(direct) = match_direct_unsupported(&lower) {
+        return Some(canonicalize_unsupported_model_key(&direct));
+    }
+    if let Some(normalized) = match_normalized_unsupported(&lower) {
+        return Some(canonicalize_unsupported_model_key(&normalized));
+    }
+    if let Some(denied) = match_access_denied(&lower) {
+        return Some(canonicalize_unsupported_model_key(&denied));
+    }
+    None
+}
+
+fn output_mentions_unsupported_model(output_lower: &str) -> bool {
+    contains_ci(output_lower, UNSUPPORTED_SUBSTRING)
+        || match_normalized_unsupported(output_lower).is_some()
+        || match_access_denied(output_lower).is_some()
+}
+
+/// TS `resolveUnsupportedModelRetryTarget(requestedModel, output,
+/// attemptedModels)`.
+pub fn resolve_unsupported_model_retry_target(
+    requested_model: Option<&str>,
+    output: &str,
+    attempted_models: &[String],
+) -> Option<String> {
+    if output.is_empty() {
+        return None;
+    }
+    let lower = output.to_ascii_lowercase();
+    if !output_mentions_unsupported_model(&lower) {
+        return None;
+    }
+    let attempted: HashSet<String> = attempted_models
+        .iter()
+        .map(|m| canonicalize_unsupported_model_key(m))
+        .filter(|m| !m.is_empty())
+        .collect();
+    let normalized_requested = requested_model
+        .map(canonicalize_unsupported_model_key)
+        .unwrap_or_default();
+    let blocked_model = extract_unsupported_model_from_output(output).unwrap_or_else(|| {
+        normalized_requested.clone()
+    });
+    let chain = {
+        let direct = wrapper_unsupported_model_fallback_chain(&blocked_model);
+        if !direct.is_empty() || normalized_requested.is_empty() {
+            direct
+        } else {
+            wrapper_unsupported_model_fallback_chain(&normalized_requested)
+        }
+    };
+    for fallback_model in chain {
+        if *fallback_model != blocked_model && !attempted.contains(*fallback_model) {
+            return Some((*fallback_model).to_string());
+        }
+    }
+    None
+}
+
+/// TS `replaceRequestedModel(args, nextModel)`.
+pub fn replace_requested_model(args: &[String], next_model: &str) -> Vec<String> {
+    if next_model.is_empty() {
+        return args.to_vec();
+    }
+    let mut next_args = args.to_vec();
+    let mut i = 0usize;
+    while i < next_args.len() {
+        let arg = next_args[i].clone();
+        if (arg == "--model" || arg == "-m") && i + 1 < next_args.len() {
+            next_args[i + 1] = next_model.to_string();
+            return next_args;
+        }
+        if arg.starts_with("--model=") {
+            next_args[i] = format!("--model={next_model}");
+            return next_args;
+        }
+        i += 1;
+    }
+    next_args
+}
+
+// ===========================================================================
+// -c cli_auth_credentials_store="file" injection.
+// ===========================================================================
+
+/// TS `hasCliAuthCredentialsStoreOverride(args)`.
+pub fn has_cli_auth_credentials_store_override(args: &[String]) -> bool {
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == "-c" || arg == "--config" {
+            if let Some(next) = args.get(i + 1)
+                && next.contains('=')
+            {
+                let key = next.split('=').next().unwrap_or("");
+                if key.trim() == "cli_auth_credentials_store" {
+                    return true;
+                }
+            }
+            i += 1;
+        } else if let Some(assignment) = arg.strip_prefix("--config=") {
+            let key = assignment.split('=').next().unwrap_or("");
+            if key.trim() == "cli_auth_credentials_store" {
+                return true;
+            }
+        }
+        i += 1;
+    }
+    false
+}
+
+/// TS `buildForwardArgs(rawArgs)` — reasoning coercion + credentials-store
+/// injection (opt-out `CODEX_MULTI_AUTH_FORCE_FILE_AUTH_STORE=0`).
+pub fn build_forward_args(raw_args: &[String]) -> (Vec<String>, Option<String>) {
+    let (compatibility_args, requested_model) = rewrite_reasoning_config_args(raw_args);
+    let force_file_auth_store = std::env::var("CODEX_MULTI_AUTH_FORCE_FILE_AUTH_STORE")
+        .unwrap_or_else(|_| "1".to_string())
+        .trim()
+        != "0";
+    if !force_file_auth_store || has_cli_auth_credentials_store_override(&compatibility_args) {
+        return (compatibility_args, requested_model);
+    }
+    let mut args = compatibility_args;
+    args.push("-c".to_string());
+    args.push("cli_auth_credentials_store=\"file\"".to_string());
+    (args, requested_model)
+}
+
+// ===========================================================================
+// Runtime rotation proxy enablement.
+// ===========================================================================
+
+fn warned_invalid_runtime_rotation_proxy_env() -> &'static AtomicBool {
+    static CELL: OnceLock<AtomicBool> = OnceLock::new();
+    CELL.get_or_init(|| AtomicBool::new(false))
+}
+
+/// TS `parseRuntimeRotationProxyEnv(value)` — warn-once on invalid values.
+pub fn parse_runtime_rotation_proxy_env(value: Option<&str>) -> Option<bool> {
+    let value = value?;
+    let normalized = value.trim().to_ascii_lowercase();
+    if normalized.is_empty() {
+        return None;
+    }
+    match normalized.as_str() {
+        "1" | "true" | "yes" => Some(true),
+        "0" | "false" | "no" => Some(false),
+        _ => {
+            if !warned_invalid_runtime_rotation_proxy_env().swap(true, Ordering::SeqCst) {
+                eprintln!(
+                    "codex-multi-auth: ignoring invalid CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY value. Expected 0/1, true/false, or yes/no."
+                );
+            }
+            None
+        }
+    }
+}
+
+/// TS `isRuntimeRotationProxyEnabled(rawArgs, baseEnv)` — BYPASS gate, arg
+/// routing gate, env override, then config.
+pub async fn is_runtime_rotation_proxy_enabled(raw_args: &[String]) -> bool {
+    if env_string("CODEX_MULTI_AUTH_BYPASS").trim() == "1" {
+        return false;
+    }
+    if !should_use_runtime_routing_for_forwarded_args(raw_args) {
+        return false;
+    }
+    let env_value = std::env::var("CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY").ok();
+    if let Some(env_override) = parse_runtime_rotation_proxy_env(env_value.as_deref()) {
+        return env_override;
+    }
+    let plugin_config = cma_config::load::load_plugin_config();
+    cma_config::getters::get_codex_runtime_rotation_proxy(&plugin_config)
+}
+
+/// TS `createRuntimeRotationProxyClientApiKey()` — 32 random bytes hex.
+pub fn create_runtime_rotation_proxy_client_api_key() -> String {
+    use rand::RngCore;
+    let mut bytes = [0u8; 32];
+    rand::rng().fill_bytes(&mut bytes);
+    bytes.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+// ===========================================================================
+// Forward context assembly.
+// ===========================================================================
+
+enum ForwardCleanup {
+    None,
+    CompatShadow(ShadowHomeContext),
+    Proxy {
+        shadow: ShadowHomeContext,
+        server: cma_proxy::server::RuntimeRotationProxyServer,
+        base: Box<ForwardCleanup>,
+    },
+    AppHelper {
+        helper: tokio::process::Child,
+        started_at: i64,
+        detach_on_exit: bool,
+        base: Box<ForwardCleanup>,
+    },
+}
+
+impl ForwardCleanup {
+    /// Iterative (non-recursive) cleanup chain — TS parity: each context's
+    /// cleanup ends by invoking `baseContext.cleanup?.()`.
+    async fn run(self, exit_code: i32) {
+        let mut current = self;
+        loop {
+            match current {
+                ForwardCleanup::None => return,
+                ForwardCleanup::CompatShadow(shadow) => {
+                    shadow.cleanup();
+                    return;
+                }
+                ForwardCleanup::Proxy {
+                    shadow,
+                    server,
+                    base,
+                } => {
+                    shadow.cleanup();
+                    let _ = server.close().await;
+                    current = *base;
+                }
+                ForwardCleanup::AppHelper {
+                    mut helper,
+                    started_at,
+                    detach_on_exit,
+                    base,
+                } => {
+                    let lived_ms = cma_core::utils::now_ms() - started_at;
+                    let detach_grace_ms = resolve_app_helper_detach_grace_ms();
+                    if exit_code == 0 && (detach_on_exit || lived_ms < detach_grace_ms) {
+                        // Let the helper keep serving (idle timeout reclaims it).
+                        drop(helper.stdout.take());
+                        drop(helper.stderr.take());
+                    } else {
+                        stop_runtime_rotation_app_helper(&mut helper).await;
+                    }
+                    current = *base;
+                }
+            }
+        }
+    }
+}
+
+struct ForwardContext {
+    args: Vec<String>,
+    env_overrides: HashMap<String, String>,
+    env_removals: Vec<String>,
+    cleanup: ForwardCleanup,
+    proxy_app_server_account_read: bool,
+}
+
+/// TS `createCompatibilityCodexHome(processedArgs, requestedModel, baseEnv)`
+/// — when the requested model needs a coerced `model_reasoning_effort` in
+/// config.toml, run codex against a temp shadow home carrying the rewritten
+/// config.
+fn create_compatibility_codex_home(
+    processed_args: Vec<String>,
+    requested_model: Option<&str>,
+) -> ForwardContext {
+    let base = ForwardContext {
+        args: processed_args,
+        env_overrides: HashMap::new(),
+        env_removals: Vec::new(),
+        cleanup: ForwardCleanup::None,
+        proxy_app_server_account_read: false,
+    };
+    let Some(requested_model) = requested_model else {
+        return base;
+    };
+    let env_map = process_env_map();
+    let original_codex_home = resolve_codex_home_dir(&env_map);
+    let config_path = original_codex_home.join("config.toml");
+    if !config_path.exists() {
+        return base;
+    }
+    let Ok(raw_config) = fs::read_to_string(&config_path) else {
+        return base;
+    };
+    let compat_config = rewrite_config_toml_reasoning_effort(&raw_config, requested_model);
+    if compat_config == raw_config {
+        return base;
+    }
+
+    // mkdtemp(join(tmpdir(), "codex-multi-auth-home-")).
+    let shadow_codex_home = {
+        let mut created: Option<PathBuf> = None;
+        for _ in 0..64 {
+            let candidate = std::env::temp_dir().join(format!(
+                "codex-multi-auth-home-{}",
+                create_runtime_rotation_proxy_client_api_key()
+                    .chars()
+                    .take(12)
+                    .collect::<String>()
+            ));
+            if fs::create_dir(&candidate).is_ok() {
+                created = Some(candidate);
+                break;
+            }
+        }
+        match created {
+            Some(path) => path,
+            None => return base,
+        }
+    };
+
+    let mirror = create_shadow_home_mirror(
+        &original_codex_home,
+        &shadow_codex_home,
+        MirrorOptions::default(),
+    );
+    let sync_back = match mirror {
+        Ok(sync_back) => sync_back,
+        Err(_) => {
+            let _ = remove_directory_with_retry(&shadow_codex_home);
+            return base;
+        }
+    };
+    let compat_config_path = shadow_codex_home.join("config.toml");
+    if fs::write(&compat_config_path, &compat_config).is_err() {
+        let _ = remove_directory_with_retry(&shadow_codex_home);
+        return base;
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(&compat_config_path, fs::Permissions::from_mode(0o600));
+    }
+
+    let mut env_overrides = HashMap::new();
+    env_overrides.insert(
+        "CODEX_HOME".to_string(),
+        shadow_codex_home.display().to_string(),
+    );
+    if let Some(dir) = resolve_original_multi_auth_dir(&env_map) {
+        env_overrides.insert("CODEX_MULTI_AUTH_DIR".to_string(), dir);
+    }
+
+    let shadow_context = ShadowHomeContext::from_parts(shadow_codex_home, sync_back);
+    ForwardContext {
+        args: base.args,
+        env_overrides,
+        env_removals: Vec::new(),
+        cleanup: ForwardCleanup::CompatShadow(shadow_context),
+        proxy_app_server_account_read: false,
+    }
+}
+
+fn provider_config_args() -> [String; 2] {
+    [
+        "-c".to_string(),
+        format!(
+            "model_provider={}",
+            cma_runtime::config_toml::toml_string_literal(
+                cma_core::constants::RUNTIME_ROTATION_PROXY_PROVIDER_ID
+            )
+        ),
+    ]
+}
+
+/// TS `createRuntimeRotationProxyContextIfEnabled(baseContext, rawArgs)`.
+async fn create_runtime_rotation_proxy_context_if_enabled(
+    base: ForwardContext,
+    raw_args: &[String],
+    forced_account_index: Option<usize>,
+) -> ForwardContext {
+    if !is_runtime_rotation_proxy_enabled(raw_args).await {
+        return base;
+    }
+
+    if is_codex_app_command(raw_args) {
+        return create_runtime_rotation_app_helper_context(base, false).await;
+    }
+    if is_codex_interactive_tui_command(raw_args) {
+        return create_runtime_rotation_app_helper_context(base, true).await;
+    }
+
+    // In-process proxy for request-shaped commands.
+    let client_api_key = create_runtime_rotation_proxy_client_api_key();
+    let options = cma_runtime::rotation::server_types::RuntimeRotationProxyOptions {
+        client_api_key: client_api_key.clone(),
+        forced_account_index: forced_account_index.map(|i| i as i64),
+        // No `--account` on this run: the wrapper resolved "no pin", so the
+        // proxy must ignore any ambient CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX
+        // (TS deletes the env var; a request without --account can never
+        // inherit an unintended pin).
+        suppress_env_forced_account_index: forced_account_index.is_none(),
+        ..Default::default()
+    };
+    let server = match cma_proxy::server::start_runtime_rotation_proxy(options).await {
+        Ok(server) => server,
+        Err(error) => {
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: {error}"
+            );
+            return base;
+        }
+    };
+
+    let mut base_env = process_env_map();
+    for (key, value) in &base.env_overrides {
+        base_env.insert(key.clone(), value.clone());
+    }
+    let shadow = match create_runtime_rotation_proxy_codex_home(
+        &base_env,
+        &server.base_url,
+        &client_api_key,
+    ) {
+        Ok(shadow) => shadow,
+        Err(error) => {
+            let _ = server.close().await;
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: {error}"
+            );
+            return base;
+        }
+    };
+
+    let mut args = base.args.clone();
+    args.extend(provider_config_args());
+    let mut env_overrides = base.env_overrides.clone();
+    for (key, value) in &shadow.env {
+        env_overrides.insert(key.clone(), value.clone());
+    }
+    ForwardContext {
+        args,
+        env_overrides,
+        env_removals: base.env_removals.clone(),
+        cleanup: ForwardCleanup::Proxy {
+            shadow,
+            server,
+            base: Box::new(base.cleanup),
+        },
+        proxy_app_server_account_read: is_codex_app_server_command(raw_args),
+    }
+}
+
+// ===========================================================================
+// App runtime helper (detached self-spawn for `codex app` / interactive TUI).
+// ===========================================================================
+
+/// TS `resolveRuntimeRotationAppHelperStatusPath(env)`.
+pub fn resolve_runtime_rotation_app_helper_status_path() -> PathBuf {
+    let env_map = process_env_map();
+    let multi_auth_dir = resolve_original_multi_auth_dir(&env_map)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| resolve_codex_home_dir(&env_map).join("multi-auth"));
+    multi_auth_dir.join(cma_core::constants::APP_RUNTIME_HELPER_STATUS_FILE)
+}
+
+fn resolve_app_helper_idle_ms() -> i64 {
+    match env_string("CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS").trim().parse::<i64>() {
+        Ok(parsed) if parsed > 0 => parsed.max(50),
+        _ => DEFAULT_APP_RUNTIME_HELPER_IDLE_MS,
+    }
+}
+
+fn resolve_app_helper_owner_pid() -> Option<i64> {
+    match env_string(APP_RUNTIME_HELPER_OWNER_PID_ENV).trim().parse::<i64>() {
+        Ok(parsed) if parsed > 0 => Some(parsed),
+        _ => None,
+    }
+}
+
+fn resolve_app_helper_detach_grace_ms() -> i64 {
+    match env_string("CODEX_MULTI_AUTH_APP_ROTATION_DETACH_GRACE_MS")
+        .trim()
+        .parse::<i64>()
+    {
+        Ok(parsed) if parsed >= 0 => parsed,
+        _ => DEFAULT_APP_RUNTIME_HELPER_DETACH_GRACE_MS,
+    }
+}
+
+/// TS `pickRuntimeRotationAppHelperEnv(env)`.
+fn pick_runtime_rotation_app_helper_env(env: &HashMap<String, String>) -> serde_json::Map<String, Value> {
+    let mut picked = serde_json::Map::new();
+    picked.insert(
+        "CODEX_HOME".to_string(),
+        env.get("CODEX_HOME").cloned().map(Value::String).unwrap_or(Value::Null),
+    );
+    picked.insert(
+        "OPENAI_API_KEY".to_string(),
+        env.get("OPENAI_API_KEY").cloned().map(Value::String).unwrap_or(Value::Null),
+    );
+    for name in [
+        "CODEX_CLI_PATH",
+        "NODE_OPTIONS",
+        "CODEX_MULTI_AUTH_REAL_CODEX_BIN",
+        "CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY",
+        APP_SERVER_ACCOUNT_LABEL_ENV,
+    ] {
+        if let Some(value) = env.get(name).filter(|v| !v.is_empty()) {
+            picked.insert(name.to_string(), Value::String(value.clone()));
+        }
+    }
+    if let Some(dir) = env.get("CODEX_MULTI_AUTH_DIR").filter(|v| !v.is_empty()) {
+        picked.insert("CODEX_MULTI_AUTH_DIR".to_string(), Value::String(dir.clone()));
+    }
+    picked
+}
+
+/// TS `createRuntimeRotationAppHelperStatus({...})`.
+fn create_app_helper_status(
+    proxy_status: Option<&cma_runtime::rotation::server_types::RuntimeRotationProxyStatus>,
+    base_url: Option<&str>,
+    started_at: i64,
+    idle_timeout_ms: i64,
+    last_activity_at: i64,
+    state: &str,
+) -> Value {
+    let last_account_index = proxy_status.and_then(|s| s.last_account_index);
+    let last_account_label = proxy_status
+        .and_then(|s| s.last_account_label.clone())
+        .filter(|label| !label.contains('@'))
+        .or_else(|| last_account_index.map(|index| format!("Account {}", index + 1)));
+    serde_json::json!({
+        "version": 1,
+        "kind": "codex-app-runtime-rotation-helper",
+        "state": state,
+        "pid": std::process::id(),
+        "startedAt": started_at,
+        "updatedAt": cma_core::utils::now_ms(),
+        "baseUrl": base_url,
+        "idleTimeoutMs": idle_timeout_ms,
+        "idleExpiresAt": last_activity_at + idle_timeout_ms,
+        "totalRequests": proxy_status.map(|s| s.total_requests).unwrap_or(0),
+        "upstreamRequests": proxy_status.map(|s| s.upstream_requests).unwrap_or(0),
+        "retries": proxy_status.map(|s| s.retries).unwrap_or(0),
+        "rotations": proxy_status.map(|s| s.rotations).unwrap_or(0),
+        "lastAccountIndex": last_account_index,
+        "lastAccountLabel": last_account_label,
+        "lastAccountId": proxy_status.and_then(|s| s.last_account_id.clone()),
+        "lastAccountUpdatedAt": proxy_status.and_then(|s| s.last_account_updated_at),
+        "lastError": proxy_status.and_then(|s| s.last_error.clone()),
+    })
+}
+
+fn write_app_helper_status(payload: &Value) {
+    let status_path = resolve_runtime_rotation_app_helper_status_path();
+    let _ = write_owner_only_json_file_atomic_sync(&status_path, payload);
+}
+
+/// TS `sweepStaleRuntimeRotationAppServerShimDirs(shimRootDir)`.
+fn sweep_stale_app_server_shim_dirs(shim_root_dir: &Path) {
+    let Ok(entries) = fs::read_dir(shim_root_dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().into_owned();
+        let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
+        if !is_dir || !name.starts_with(APP_SERVER_SHIM_HELPER_PREFIX) {
+            continue;
+        }
+        let pid_text = &name[APP_SERVER_SHIM_HELPER_PREFIX.len()..];
+        let Ok(pid) = pid_text.parse::<i64>() else {
+            continue;
+        };
+        if pid <= 0
+            || pid == std::process::id() as i64
+            || cma_runtime::app_bind::is_process_alive(Some(pid))
+        {
+            continue;
+        }
+        let _ = remove_directory_with_retry(&shim_root_dir.join(&name));
+    }
+}
+
+/// TS `installRuntimeRotationAppServerCliShim(forwardedEnv)`.
+///
+/// Deviation vs TS: the Node build materialized a `node` executable + a
+/// `NODE_OPTIONS --import` preload; the Rust build hardlinks/copies THIS
+/// wrapper binary as `codex[.exe]` into the shim dir — when the packaged app
+/// spawns `<shim>/codex app-server …`, the wrapper (with
+/// `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0` +
+/// `CODEX_MULTI_AUTH_APP_SERVER_ACCOUNT_LABEL=1`) forwards to the real codex
+/// with the account-read protocol proxy, matching the preload's effect.
+fn install_runtime_rotation_app_server_cli_shim(
+    forwarded_env: &mut HashMap<String, String>,
+) -> io::Result<PathBuf> {
+    if !forwarded_env.contains_key("CODEX_HOME") {
+        return Err(io::Error::other("runtime app-server shim requires CODEX_HOME"));
+    }
+    let env_map = process_env_map();
+    let multi_auth_dir = resolve_original_multi_auth_dir(forwarded_env)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            resolve_runtime_rotation_proxy_original_codex_home(&env_map).join("multi-auth")
+        });
+    let shim_root_dir = multi_auth_dir.join(APP_SERVER_SHIM_DIR_NAME);
+    sweep_stale_app_server_shim_dirs(&shim_root_dir);
+    let shim_dir = shim_root_dir.join(format!(
+        "{APP_SERVER_SHIM_HELPER_PREFIX}{}",
+        std::process::id()
+    ));
+    fs::create_dir_all(&shim_dir)?;
+    let executable_name = if cfg!(windows) { "codex.exe" } else { "codex" };
+    let executable_path = shim_dir.join(executable_name);
+    let result = (|| -> io::Result<()> {
+        let _ = fs::remove_file(&executable_path);
+        let self_exe = std::env::current_exe()?;
+        if fs::hard_link(&self_exe, &executable_path).is_err() {
+            fs::copy(&self_exe, &executable_path)?;
+        }
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ = fs::set_permissions(&executable_path, fs::Permissions::from_mode(0o755));
+        }
+        Ok(())
+    })();
+    if let Err(error) = result {
+        let _ = remove_directory_with_retry(&shim_dir);
+        return Err(error);
+    }
+    forwarded_env.insert("CODEX_CLI_PATH".to_string(), shim_dir.display().to_string());
+    forwarded_env.insert(
+        "CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY".to_string(),
+        "0".to_string(),
+    );
+    forwarded_env.insert(APP_SERVER_ACCOUNT_LABEL_ENV.to_string(), "1".to_string());
+    Ok(shim_dir)
+}
+
+/// TS `runRuntimeRotationAppHelper()` — the helper-child main (invoked with
+/// [`INTERNAL_RUNTIME_ROTATION_APP_HELPER_ARG`]). Returns the exit code.
+pub async fn run_runtime_rotation_app_helper() -> i32 {
+    let started_at = cma_core::utils::now_ms();
+    let idle_timeout_ms = resolve_app_helper_idle_ms();
+    let owner_pid = resolve_app_helper_owner_pid();
+    let mut last_activity_at = started_at;
+
+    let client_api_key = create_runtime_rotation_proxy_client_api_key();
+    let options = cma_runtime::rotation::server_types::RuntimeRotationProxyOptions {
+        client_api_key: client_api_key.clone(),
+        ..Default::default()
+    };
+    let startup = async {
+        let server = cma_proxy::server::start_runtime_rotation_proxy(options)
+            .await
+            .map_err(|e| e.to_string())?;
+        let base_env = process_env_map();
+        let shadow =
+            create_runtime_rotation_proxy_codex_home(&base_env, &server.base_url, &client_api_key)
+                .map_err(|e| e.to_string())?;
+        Ok::<_, String>((server, shadow))
+    };
+    let (server, shadow) = match startup.await {
+        Ok(parts) => parts,
+        Err(message) => {
+            println!(
+                "{}",
+                cma_core::json_io::stringify_compact(&serde_json::json!({
+                    "type": "error",
+                    "message": message,
+                }))
+            );
+            write_app_helper_status(&create_app_helper_status(
+                None,
+                None,
+                started_at,
+                idle_timeout_ms,
+                last_activity_at,
+                "error",
+            ));
+            return 1;
+        }
+    };
+
+    let mut helper_env: HashMap<String, String> = process_env_map();
+    for (key, value) in &shadow.env {
+        helper_env.insert(key.clone(), value.clone());
+    }
+    let shim_dir = match install_runtime_rotation_app_server_cli_shim(&mut helper_env) {
+        Ok(dir) => Some(dir),
+        Err(error) => {
+            println!(
+                "{}",
+                cma_core::json_io::stringify_compact(&serde_json::json!({
+                    "type": "error",
+                    "message": error.to_string(),
+                }))
+            );
+            shadow.cleanup();
+            let _ = server.close().await;
+            write_app_helper_status(&create_app_helper_status(
+                None,
+                None,
+                started_at,
+                idle_timeout_ms,
+                last_activity_at,
+                "error",
+            ));
+            return 1;
+        }
+    };
+
+    async fn publish_status(
+        server: &cma_proxy::server::RuntimeRotationProxyServer,
+        started_at: i64,
+        idle_timeout_ms: i64,
+        last_activity_at: i64,
+        state: &str,
+    ) {
+        let status = server.get_status().await;
+        write_app_helper_status(&create_app_helper_status(
+            Some(&status),
+            Some(&server.base_url),
+            started_at,
+            idle_timeout_ms,
+            last_activity_at,
+            state,
+        ));
+    }
+    let mut last_request_count = server.get_status().await.total_requests;
+    publish_status(&server, started_at, idle_timeout_ms, last_activity_at, "running").await;
+    println!(
+        "{}",
+        cma_core::json_io::stringify_compact(&serde_json::json!({
+            "type": "ready",
+            "pid": std::process::id(),
+            "baseUrl": server.base_url,
+            "statusPath": resolve_runtime_rotation_app_helper_status_path().display().to_string(),
+            "env": Value::Object(pick_runtime_rotation_app_helper_env(&helper_env)),
+        }))
+    );
+    use std::io::Write;
+    let _ = std::io::stdout().flush();
+
+    let tick_ms = (idle_timeout_ms / 2).clamp(50, 1_000) as u64;
+    let mut interval = tokio::time::interval(Duration::from_millis(tick_ms));
+    interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+
+    loop {
+        let stop_state: (&str, i32) = tokio::select! {
+            _ = interval.tick() => {
+                let current_time = cma_core::utils::now_ms();
+                let request_count = server.get_status().await.total_requests;
+                if request_count != last_request_count {
+                    last_request_count = request_count;
+                    last_activity_at = current_time;
+                }
+                if let Some(owner) = owner_pid
+                    && cma_runtime::app_bind::is_process_alive(Some(owner))
+                {
+                    last_activity_at = current_time;
+                }
+                publish_status(&server, started_at, idle_timeout_ms, last_activity_at, "running")
+                    .await;
+                if current_time - last_activity_at >= idle_timeout_ms {
+                    ("idle-timeout", 0)
+                } else {
+                    continue;
+                }
+            }
+            _ = tokio::signal::ctrl_c() => ("stopped", 130),
+        };
+        let (state, exit_code) = stop_state;
+        if let Some(shim_dir) = &shim_dir {
+            let _ = remove_directory_with_retry(shim_dir);
+        }
+        publish_status(&server, started_at, idle_timeout_ms, last_activity_at, state).await;
+        shadow.cleanup();
+        let _ = server.close().await;
+        return exit_code;
+    }
+}
+
+async fn stop_runtime_rotation_app_helper(helper: &mut tokio::process::Child) {
+    // SIGTERM-flavored stop with a 2 s grace, then hard kill (TS parity: the
+    // Node helper handled SIGTERM by cleaning up and exiting 0).
+    #[cfg(unix)]
+    {
+        if let Some(pid) = helper.id() {
+            let _ = tokio::process::Command::new("kill")
+                .arg(pid.to_string())
+                .stdout(std::process::Stdio::null())
+                .stderr(std::process::Stdio::null())
+                .status()
+                .await;
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = helper.start_kill();
+    }
+    let _ = tokio::time::timeout(Duration::from_millis(2_000), helper.wait()).await;
+    let _ = helper.start_kill();
+    let _ = tokio::time::timeout(Duration::from_millis(200), helper.wait()).await;
+}
+
+/// TS `startRuntimeRotationAppHelper(baseContext)` +
+/// `createRuntimeRotationAppHelperContext` — spawn the detached helper, await
+/// its `ready` line, merge its env into the forwarded context.
+async fn create_runtime_rotation_app_helper_context(
+    base: ForwardContext,
+    detach_on_exit: bool,
+) -> ForwardContext {
+    let env_map = {
+        let mut merged = process_env_map();
+        for (key, value) in &base.env_overrides {
+            merged.insert(key.clone(), value.clone());
+        }
+        merged
+    };
+    let real_codex_home = resolve_runtime_rotation_proxy_original_codex_home(&env_map);
+    let self_exe = match std::env::current_exe() {
+        Ok(path) => path,
+        Err(error) => {
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: {error}"
+            );
+            return base;
+        }
+    };
+
+    let mut command = tokio::process::Command::new(&self_exe);
+    command
+        .arg(INTERNAL_RUNTIME_ROTATION_APP_HELPER_ARG)
+        .envs(&base.env_overrides)
+        .env(
+            "CODEX_MULTI_AUTH_DIR",
+            resolve_runtime_rotation_original_multi_auth_dir(&real_codex_home, &env_map),
+        );
+    // Apply the launcher's env scrubs to the detached helper too: without
+    // this the helper inherits a stray CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX
+    // (published by a parent forced run) and its proxy silently pins to one
+    // account via the env fallback, defeating rotation. TS deletes the var
+    // from process.env, which covers every child.
+    for key in &base.env_removals {
+        command.env_remove(key);
+    }
+    command
+        .env(APP_RUNTIME_HELPER_OWNER_PID_ENV, std::process::id().to_string())
+        .env(
+            APP_RUNTIME_HELPER_REAL_CODEX_HOME_ENV,
+            real_codex_home.display().to_string(),
+        )
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped());
+    #[cfg(windows)]
+    {
+        // DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP — survives the parent.
+        const DETACHED_PROCESS: u32 = 0x0000_0008;
+        const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
+        command.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP);
+    }
+    #[cfg(unix)]
+    {
+        command.process_group(0);
+    }
+
+    let mut helper = match command.spawn() {
+        Ok(child) => child,
+        Err(error) => {
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: {error}"
+            );
+            return base;
+        }
+    };
+
+    // Await the first stdout line ("ready" or "error") with the launch budget.
+    let ready = async {
+        use tokio::io::AsyncBufReadExt;
+        let stdout = helper.stdout.take().ok_or_else(|| "no helper stdout".to_string())?;
+        let mut lines = tokio::io::BufReader::new(stdout).lines();
+        let line = lines
+            .next_line()
+            .await
+            .map_err(|e| e.to_string())?
+            .ok_or_else(|| "runtime rotation app helper exited before startup".to_string())?;
+        let message: Value = serde_json::from_str(line.trim()).map_err(|e| e.to_string())?;
+        if message.get("type").and_then(Value::as_str) == Some("ready")
+            && message.get("env").is_some_and(Value::is_object)
+            && message.get("pid").is_some()
+        {
+            return Ok::<Value, String>(message);
+        }
+        Err(message
+            .get("message")
+            .and_then(Value::as_str)
+            .unwrap_or("runtime rotation app helper returned an invalid startup response")
+            .to_string())
+    };
+    let message = match tokio::time::timeout(
+        Duration::from_millis(APP_RUNTIME_HELPER_LAUNCH_TIMEOUT_MS),
+        ready,
+    )
+    .await
+    {
+        Ok(Ok(message)) => message,
+        Ok(Err(error)) => {
+            stop_runtime_rotation_app_helper(&mut helper).await;
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: {error}"
+            );
+            return base;
+        }
+        Err(_) => {
+            stop_runtime_rotation_app_helper(&mut helper).await;
+            eprintln!(
+                "codex-multi-auth runtime rotation proxy failed to start; continuing without runtime rotation: timed out waiting for runtime rotation app helper"
+            );
+            return base;
+        }
+    };
+
+    let mut env_overrides = base.env_overrides.clone();
+    if let Some(env_object) = message.get("env").and_then(Value::as_object) {
+        for (key, value) in env_object {
+            if let Some(value) = value.as_str() {
+                env_overrides.insert(key.clone(), value.to_string());
+            }
+        }
+    }
+    let mut args = base.args.clone();
+    args.extend(provider_config_args());
+    ForwardContext {
+        args,
+        env_overrides,
+        env_removals: base.env_removals.clone(),
+        cleanup: ForwardCleanup::AppHelper {
+            helper,
+            started_at: cma_core::utils::now_ms(),
+            detach_on_exit,
+            base: Box::new(base.cleanup),
+        },
+        proxy_app_server_account_read: false,
+    }
+}
+
+// ===========================================================================
+// app-server account/read protocol proxy (JSON-RPC line rewriting).
+// ===========================================================================
+
+/// TS `jsonRpcIdKey(id)`.
+pub fn json_rpc_id_key(id: &Value) -> Option<String> {
+    match id {
+        Value::String(s) => Some(format!("string:{}", cma_core::json_io::stringify_compact(s))),
+        Value::Number(_) => Some(format!("number:{}", cma_core::json_io::stringify_compact(id))),
+        Value::Bool(_) => Some(format!("boolean:{}", cma_core::json_io::stringify_compact(id))),
+        Value::Null => Some("object:null".to_string()),
+        _ => None,
+    }
+}
+
+/// TS `parseJsonObjectLine(line)`.
+pub fn parse_json_object_line(line: &str) -> Option<Value> {
+    let trimmed = line.trim();
+    if !trimmed.starts_with('{') {
+        return None;
+    }
+    let parsed: Value = serde_json::from_str(trimmed).ok()?;
+    if parsed.is_object() { Some(parsed) } else { None }
+}
+
+/// TS `splitProtocolLineEnding(line)`.
+pub fn split_protocol_line_ending(line: &str) -> (&str, &str) {
+    if let Some(body) = line.strip_suffix("\r\n") {
+        return (body, "\r\n");
+    }
+    if let Some(body) = line.strip_suffix('\n') {
+        return (body, "\n");
+    }
+    (line, "")
+}
+
+fn synthetic_account_read_result() -> Value {
+    serde_json::json!({
+        "account": {
+            "type": "chatgpt",
+            "email": APP_SERVER_ACCOUNT_DISPLAY_NAME,
+            "planType": "unknown",
+        },
+        "requiresOpenaiAuth": false,
+    })
+}
+
+fn synthetic_auth_status_result() -> Value {
+    serde_json::json!({
+        "authMethod": "apikey",
+        "authToken": null,
+        "requiresOpenaiAuth": false,
+    })
+}
+
+fn synthetic_rate_limits_result() -> Value {
+    serde_json::json!({
+        "rateLimits": {
+            "limitId": null,
+            "limitName": null,
+            "primary": null,
+            "secondary": null,
+            "credits": null,
+            "planType": null,
+            "rateLimitReachedType": null,
+        },
+        "rateLimitsByLimitId": null,
+    })
+}
+
+const MAX_PENDING_AUTH_REQUEST_IDS: usize = 4096;
+
+fn warned_pending_overflow() -> &'static AtomicBool {
+    static CELL: OnceLock<AtomicBool> = OnceLock::new();
+    CELL.get_or_init(|| AtomicBool::new(false))
+}
+
+/// Observe a client→server line; records pending auth-read request ids.
+pub fn observe_app_server_request_line(
+    line: &str,
+    pending: &mut std::collections::HashMap<String, String>,
+) {
+    let (body, _) = split_protocol_line_ending(line);
+    let Some(message) = parse_json_object_line(body) else {
+        return;
+    };
+    let method = message.get("method").and_then(Value::as_str).unwrap_or("");
+    if !matches!(
+        method,
+        "account/read" | "account/rateLimits/read" | "getAuthStatus"
+    ) || !message
+        .as_object()
+        .is_some_and(|o| o.contains_key("id"))
+    {
+        return;
+    }
+    if let Some(key) = message.get("id").and_then(json_rpc_id_key) {
+        if pending.len() >= MAX_PENDING_AUTH_REQUEST_IDS {
+            pending.clear();
+            if !warned_pending_overflow().swap(true, Ordering::SeqCst) {
+                eprintln!(
+                    "codex-multi-auth: cleared pending app-server auth request ids after exceeding the safety cap."
+                );
+            }
+        }
+        pending.insert(key, method.to_string());
+    }
+}
+
+/// TS `rewriteAppServerAccountReadResponseLine(line, pending)`.
+pub fn rewrite_app_server_account_read_response_line(
+    line: &str,
+    pending: &mut std::collections::HashMap<String, String>,
+) -> String {
+    let (body, line_ending) = split_protocol_line_ending(line);
+    let Some(message) = parse_json_object_line(body) else {
+        return line.to_string();
+    };
+    if !message.as_object().is_some_and(|o| o.contains_key("id")) {
+        return line.to_string();
+    }
+    let Some(key) = message.get("id").and_then(json_rpc_id_key) else {
+        return line.to_string();
+    };
+    let Some(method) = pending.remove(&key) else {
+        return line.to_string();
+    };
+    let result = match method.as_str() {
+        "account/read" => synthetic_account_read_result(),
+        "account/rateLimits/read" => synthetic_rate_limits_result(),
+        "getAuthStatus" => synthetic_auth_status_result(),
+        _ => return line.to_string(),
+    };
+    let jsonrpc = message
+        .get("jsonrpc")
+        .and_then(Value::as_str)
+        .unwrap_or("2.0");
+    format!(
+        "{}{}",
+        cma_core::json_io::stringify_compact(&serde_json::json!({
+            "jsonrpc": jsonrpc,
+            "id": message.get("id").cloned().unwrap_or(Value::Null),
+            "result": result,
+        })),
+        line_ending
+    )
+}
+
+/// Streaming line accumulator (TS `createProtocolLineAccumulator`).
+pub struct ProtocolLineAccumulator {
+    buffer: String,
+}
+
+impl ProtocolLineAccumulator {
+    pub fn new() -> Self {
+        Self { buffer: String::new() }
+    }
+
+    /// Feed a chunk; returns complete lines (each INCLUDING its newline).
+    pub fn write(&mut self, chunk: &str) -> Vec<String> {
+        self.buffer.push_str(chunk);
+        let mut lines = Vec::new();
+        while let Some(newline_index) = self.buffer.find('\n') {
+            let line: String = self.buffer.drain(..=newline_index).collect();
+            lines.push(line);
+        }
+        lines
+    }
+
+    /// Flush the trailing partial line (if any).
+    pub fn end(&mut self) -> Option<String> {
+        if self.buffer.is_empty() {
+            None
+        } else {
+            Some(std::mem::take(&mut self.buffer))
+        }
+    }
+}
+
+impl Default for ProtocolLineAccumulator {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ===========================================================================
+// Forwarded output capture / filtering.
+// ===========================================================================
+
+/// TS `shouldCaptureForwardedCodexOutput(env)`.
+pub fn should_capture_forwarded_codex_output() -> bool {
+    let override_value = env_string("CODEX_MULTI_AUTH_CAPTURE_FORWARD_OUTPUT");
+    let override_value = override_value.trim();
+    if override_value == "1" {
+        return true;
+    }
+    if override_value == "0" {
+        return false;
+    }
+    if env_string("CODEX_CI").trim() == "1" {
+        return true;
+    }
+    use std::io::IsTerminal;
+    !(std::io::stdout().is_terminal() && std::io::stderr().is_terminal())
+}
+
+fn should_capture_forwarded_output_for_args(raw_args: &[String]) -> bool {
+    if is_codex_app_server_command(raw_args) {
+        return false;
+    }
+    should_capture_forwarded_codex_output()
+}
+
+fn is_uuid_not_found_line(line: &str) -> bool {
+    // /^[0-9a-f]{8}-…-[0-9a-f]{12} not found$/i
+    let Some(rest) = line
+        .to_ascii_lowercase()
+        .strip_suffix(" not found")
+        .map(str::to_string)
+    else {
+        return false;
+    };
+    let parts: Vec<&str> = rest.split('-').collect();
+    parts.len() == 5
+        && [8usize, 4, 4, 4, 12]
+            .iter()
+            .zip(&parts)
+            .all(|(len, part)| part.len() == *len && part.chars().all(|c| c.is_ascii_hexdigit()))
+}
+
+/// TS `filterKnownForwardedCodexStderr(text)` — drops the known-noise rollout
+/// + rmcp session-delete error pairs.
+pub fn filter_known_forwarded_codex_stderr(text: &str) -> String {
+    if text.is_empty() {
+        return String::new();
+    }
+    let lines: Vec<&str> = text.split("\r\n").flat_map(|s| s.split('\n')).collect();
+    let mut filtered: Vec<&str> = Vec::with_capacity(lines.len());
+    let mut index = 0usize;
+    while index < lines.len() {
+        let line = lines[index];
+        let next = lines.get(index + 1).copied().unwrap_or("");
+        if line
+            .trim_end()
+            .ends_with("ERROR codex_core::session: failed to record rollout items: thread")
+            && line.contains("ERROR codex_core::session: failed to record rollout items: thread")
+            && is_uuid_not_found_line(next)
+        {
+            index += 2;
+            continue;
+        }
+        if line
+            .trim_end()
+            .ends_with("ERROR rmcp::transport::streamable_http_client: fail to delete session:")
+            && next.starts_with("unexpected server response: DELETE returned HTTP 404 session_id=\"")
+        {
+            index += 1; // skip the current line; scan forward past the payload
+            while index + 1 < lines.len() && !lines[index].trim_end().ends_with('"') {
+                index += 1;
+            }
+            index += 1;
+            continue;
+        }
+        filtered.push(line);
+        index += 1;
+    }
+    filtered.join("\n")
+}
+
+/// TS `withCiKnownForwardedCodexLogSilencers(env)` — returns the RUST_LOG
+/// override to add (only under `CODEX_CI=1` with no explicit RUST_LOG).
+fn ci_known_forwarded_codex_log_silencer() -> Option<(String, String)> {
+    if env_string("CODEX_CI").trim() != "1" {
+        return None;
+    }
+    if !env_string("RUST_LOG").trim().is_empty() {
+        return None;
+    }
+    Some(("RUST_LOG".to_string(), "codex_core::session=off".to_string()))
+}
+
+// ===========================================================================
+// Spawning the official codex.
+// ===========================================================================
+
+struct ForwardOnceResult {
+    exit_code: i32,
+    output: String,
+}
+
+fn exit_code_from_status(status: std::process::ExitStatus) -> i32 {
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(signal) = status.signal() {
+            return if signal == 2 { 130 } else { 1 };
+        }
+    }
+    status.code().unwrap_or(1)
+}
+
+/// TS `forwardToRealCodexOnce(codexBin, args, env, cleanup, options)`.
+async fn forward_to_real_codex_once(
+    codex_bin: &ResolvedCodexBin,
+    args: &[String],
+    env_overrides: &HashMap<String, String>,
+    env_removals: &[String],
+    cleanup: ForwardCleanup,
+    capture_output: bool,
+    proxy_app_server_account_read: bool,
+) -> ForwardOnceResult {
+    let (program, command_args): (PathBuf, Vec<String>) = if codex_bin.launch_with_node {
+        (
+            PathBuf::from("node"),
+            std::iter::once(codex_bin.path.display().to_string())
+                .chain(args.iter().cloned())
+                .collect(),
+        )
+    } else {
+        (codex_bin.path.clone(), args.to_vec())
+    };
+
+    let mut command = tokio::process::Command::new(&program);
+    command.args(&command_args);
+    for (key, value) in env_overrides {
+        command.env(key, value);
+    }
+    for key in env_removals {
+        command.env_remove(key);
+    }
+    if capture_output && let Some((key, value)) = ci_known_forwarded_codex_log_silencer() {
+        command.env(key, value);
+    }
+
+    if proxy_app_server_account_read {
+        command
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped());
+    } else if capture_output {
+        command
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped());
+    } else {
+        command
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::inherit())
+            .stderr(std::process::Stdio::inherit());
+    }
+
+    let mut child = match command.spawn() {
+        Ok(child) => child,
+        Err(error) => {
+            let message = format!("Failed to launch real Codex CLI: {error}");
+            eprintln!("{message}");
+            cleanup.run(1).await;
+            return ForwardOnceResult {
+                exit_code: 1,
+                output: message,
+            };
+        }
+    };
+
+    if proxy_app_server_account_read {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        let pending: Arc<Mutex<std::collections::HashMap<String, String>>> =
+            Arc::new(Mutex::new(std::collections::HashMap::new()));
+
+        // stdin passthrough + observation. The workspace tokio build has no
+        // `io-std` feature, so a blocking reader thread bridges our stdin
+        // into the async writer via a channel.
+        let (stdin_tx, mut stdin_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(16);
+        std::thread::spawn(move || {
+            use std::io::Read;
+            let mut stdin = std::io::stdin();
+            let mut buf = vec![0u8; 8192];
+            loop {
+                match stdin.read(&mut buf) {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => {
+                        if stdin_tx.blocking_send(buf[..n].to_vec()).is_err() {
+                            break;
+                        }
+                    }
+                }
+            }
+        });
+        let mut child_stdin = child.stdin.take();
+        let pending_in = Arc::clone(&pending);
+        let stdin_task = tokio::spawn(async move {
+            let mut accumulator = ProtocolLineAccumulator::new();
+            while let Some(chunk_bytes) = stdin_rx.recv().await {
+                let chunk = String::from_utf8_lossy(&chunk_bytes).into_owned();
+                {
+                    let mut pending = pending_in.lock().expect("pending poisoned");
+                    for line in accumulator.write(&chunk) {
+                        observe_app_server_request_line(&line, &mut pending);
+                    }
+                }
+                if let Some(stdin_pipe) = child_stdin.as_mut()
+                    && stdin_pipe.write_all(&chunk_bytes).await.is_err()
+                {
+                    break;
+                }
+            }
+            if let Some(rest) = accumulator.end() {
+                let mut pending = pending_in.lock().expect("pending poisoned");
+                observe_app_server_request_line(&rest, &mut pending);
+            }
+            if let Some(mut stdin_pipe) = child_stdin.take() {
+                let _ = stdin_pipe.shutdown().await;
+            }
+        });
+
+        // stdout rewrite (sync writes to our stdout are line-scale).
+        let mut child_stdout = child.stdout.take();
+        let pending_out = Arc::clone(&pending);
+        let stdout_task = tokio::spawn(async move {
+            use std::io::Write;
+            let Some(stdout) = child_stdout.as_mut() else {
+                return;
+            };
+            let mut accumulator = ProtocolLineAccumulator::new();
+            let mut buf = vec![0u8; 8192];
+            loop {
+                match stdout.read(&mut buf).await {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => {
+                        let chunk = String::from_utf8_lossy(&buf[..n]).into_owned();
+                        let lines = accumulator.write(&chunk);
+                        let mut out = std::io::stdout();
+                        let mut pending = pending_out.lock().expect("pending poisoned");
+                        for line in lines {
+                            let rewritten =
+                                rewrite_app_server_account_read_response_line(&line, &mut pending);
+                            let _ = out.write_all(rewritten.as_bytes());
+                        }
+                        drop(pending);
+                        let _ = out.flush();
+                    }
+                }
+            }
+            if let Some(rest) = accumulator.end() {
+                let mut out = std::io::stdout();
+                let mut pending = pending_out.lock().expect("pending poisoned");
+                let rewritten = rewrite_app_server_account_read_response_line(&rest, &mut pending);
+                let _ = out.write_all(rewritten.as_bytes());
+                let _ = out.flush();
+            }
+        });
+
+        // stderr passthrough.
+        let mut child_stderr = child.stderr.take();
+        let stderr_task = tokio::spawn(async move {
+            use std::io::Write;
+            let Some(stderr) = child_stderr.as_mut() else {
+                return;
+            };
+            let mut buf = vec![0u8; 8192];
+            loop {
+                match stderr.read(&mut buf).await {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => {
+                        let mut err = std::io::stderr();
+                        let _ = err.write_all(&buf[..n]);
+                        let _ = err.flush();
+                    }
+                }
+            }
+        });
+
+        let status = child.wait().await;
+        stdin_task.abort();
+        let _ = stdout_task.await;
+        let _ = stderr_task.await;
+        let exit_code = status.map(exit_code_from_status).unwrap_or(1);
+        cleanup.run(exit_code).await;
+        return ForwardOnceResult {
+            exit_code,
+            output: String::new(),
+        };
+    }
+
+    if capture_output {
+        use tokio::io::AsyncReadExt;
+        let mut stdout_pipe = child.stdout.take();
+        let mut stderr_pipe = child.stderr.take();
+        let stdout_task = tokio::spawn(async move {
+            let mut captured = String::new();
+            if let Some(stdout) = stdout_pipe.as_mut() {
+                let _ = stdout.read_to_string(&mut captured).await;
+            }
+            captured
+        });
+        let stderr_task = tokio::spawn(async move {
+            let mut captured = String::new();
+            if let Some(stderr) = stderr_pipe.as_mut() {
+                let _ = stderr.read_to_string(&mut captured).await;
+            }
+            captured
+        });
+        let status = child.wait().await;
+        let stdout_capture = stdout_task.await.unwrap_or_default();
+        let stderr_capture = stderr_task.await.unwrap_or_default();
+        let exit_code = status.map(exit_code_from_status).unwrap_or(1);
+        cleanup.run(exit_code).await;
+        if !stdout_capture.is_empty() {
+            let filtered_stdout = filter_known_forwarded_codex_stderr(&stdout_capture);
+            if !filtered_stdout.is_empty() {
+                print!("{filtered_stdout}");
+                use std::io::Write;
+                let _ = std::io::stdout().flush();
+            }
+        }
+        if !stderr_capture.is_empty() {
+            let filtered_stderr = filter_known_forwarded_codex_stderr(&stderr_capture);
+            if !filtered_stderr.trim().is_empty() {
+                eprint!("{filtered_stderr}");
+                if !filtered_stderr.ends_with('\n') {
+                    eprintln!();
+                }
+            }
+        }
+        return ForwardOnceResult {
+            exit_code,
+            output: format!("{stdout_capture}\n{stderr_capture}").trim().to_string(),
+        };
+    }
+
+    let status = child.wait().await;
+    let exit_code = status.map(exit_code_from_status).unwrap_or(1);
+    cleanup.run(exit_code).await;
+    ForwardOnceResult {
+        exit_code,
+        // No-capture output stays empty by design so retry parsing cannot
+        // reintroduce pipes that break terminal passthrough.
+        output: String::new(),
+    }
+}
+
+// ===========================================================================
+// Session-index repair.
+// ===========================================================================
+
+/// TS `extractRolloutIdFromFilename(fileName)` —
+/// `rollout-YYYY-MM-DDThh-mm-ss-<uuid>.jsonl` (case-insensitive uuid).
+pub fn extract_rollout_id_from_filename(file_name: &str) -> Option<String> {
+    let rest = file_name.strip_prefix("rollout-")?;
+    let rest_lower = rest.to_ascii_lowercase();
+    let rest_bytes = rest_lower.as_bytes();
+    // date part: dddd-dd-ddTdd-dd-dd-
+    let date_len = "0000-00-00T00-00-00-".len();
+    if rest_bytes.len() < date_len {
+        return None;
+    }
+    let date_part = &rest_lower[..date_len];
+    let date_template = "dddd-dd-ddTdd-dd-dd-";
+    for (c, t) in date_part.chars().zip(date_template.chars()) {
+        match t {
+            'd' => {
+                if !c.is_ascii_digit() {
+                    return None;
+                }
+            }
+            other => {
+                if c != other.to_ascii_lowercase() {
+                    return None;
+                }
+            }
+        }
+    }
+    let uuid_and_ext = &rest_lower[date_len..];
+    let uuid = uuid_and_ext.strip_suffix(".jsonl")?;
+    let parts: Vec<&str> = uuid.split('-').collect();
+    let valid = parts.len() == 5
+        && [8usize, 4, 4, 4, 12]
+            .iter()
+            .zip(&parts)
+            .all(|(len, part)| part.len() == *len && part.chars().all(|c| c.is_ascii_hexdigit()));
+    if valid { Some(uuid.to_string()) } else { None }
+}
+
+fn collect_rollout_files(root_dir: &Path, results: &mut Vec<PathBuf>) {
+    let Ok(entries) = fs::read_dir(root_dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let entry_path = entry.path();
+        let file_type = entry.file_type();
+        if file_type.as_ref().map(|t| t.is_dir()).unwrap_or(false) {
+            collect_rollout_files(&entry_path, results);
+            continue;
+        }
+        if file_type.map(|t| t.is_file()).unwrap_or(false)
+            && entry
+                .file_name()
+                .to_str()
+                .and_then(extract_rollout_id_from_filename)
+                .is_some()
+        {
+            results.push(entry_path);
+        }
+    }
+}
+
+/// TS `parseRolloutIndexEntry(rolloutPath)`.
+fn parse_rollout_index_entry(rollout_path: &Path) -> Option<Value> {
+    let file_name = rollout_path.file_name()?.to_str()?;
+    let id_from_name = extract_rollout_id_from_filename(file_name)?;
+    let content = fs::read_to_string(rollout_path).ok()?;
+    let mut id = id_from_name;
+    let mut thread_name = String::new();
+    let mut updated_at: Option<String> = None;
+    let mut has_session_meta = false;
+    for line in content.split(['\r', '\n']).filter(|l| !l.is_empty()) {
+        let Ok(record) = serde_json::from_str::<Value>(line) else {
+            continue;
+        };
+        if let Some(timestamp) = record.get("timestamp").and_then(Value::as_str) {
+            updated_at = Some(timestamp.to_string());
+        }
+        if record.get("type").and_then(Value::as_str) == Some("session_meta")
+            && let Some(session_id) = record
+                .get("payload")
+                .and_then(|p| p.get("id"))
+                .and_then(Value::as_str)
+        {
+            id = session_id.to_string();
+            has_session_meta = true;
+        }
+        if thread_name.is_empty()
+            && record.get("type").and_then(Value::as_str) == Some("event_msg")
+            && let Some(message) = record
+                .get("payload")
+                .and_then(|p| p.get("message"))
+                .and_then(Value::as_str)
+            && !message.trim().is_empty()
+        {
+            thread_name = message.trim().to_string();
+        }
+    }
+    let updated_at = updated_at.unwrap_or_else(|| {
+        // TS double fallback: `statSync(path).mtime.toISOString()`, then
+        // `new Date().toISOString()` when stat fails — ALWAYS an ISO-8601
+        // UTC string ("YYYY-MM-DDTHH:MM:SS.mmmZ"), never raw epoch millis or
+        // "". This entry is appended to the REAL ~/.codex/session_index.jsonl
+        // that the official Codex resume list sorts and renders; a non-ISO
+        // value mis-sorts that shared file. `to_rfc3339_opts(Millis, true)`
+        // matches Date.prototype.toISOString byte-for-byte.
+        fs::metadata(rollout_path)
+            .ok()
+            .and_then(|m| m.modified().ok())
+            .map(chrono::DateTime::<chrono::Utc>::from)
+            .unwrap_or_else(chrono::Utc::now)
+            .to_rfc3339_opts(chrono::SecondsFormat::Millis, true)
+    });
+    if !has_session_meta {
+        return None;
+    }
+    if thread_name.is_empty() {
+        thread_name = "Codex session".to_string();
+    }
+    if thread_name.chars().count() > 80 {
+        thread_name = format!("{}...", thread_name.chars().take(77).collect::<String>());
+    }
+    Some(serde_json::json!({
+        "id": id,
+        "thread_name": thread_name,
+        "updated_at": updated_at,
+    }))
+}
+
+fn write_session_index_atomic(index_path: &Path, lines: &[String]) -> io::Result<()> {
+    let index_dir = index_path
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| PathBuf::from("."));
+    fs::create_dir_all(&index_dir)?;
+    let payload = format!("{}\n", lines.join("\n"));
+    let base = index_path
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("session_index.jsonl");
+    for attempt in 0..4u32 {
+        let temp_path = index_dir.join(format!(
+            ".{base}.{}.{}.tmp",
+            std::process::id(),
+            cma_core::utils::now_ms()
+        ));
+        let result = fs::write(&temp_path, payload.as_bytes())
+            .and_then(|()| fs::rename(&temp_path, index_path));
+        match result {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                let _ = fs::remove_file(&temp_path);
+                let retryable = matches!(
+                    cma_core::fs_retry::code_of(&error),
+                    Some("EBUSY") | Some("EPERM") | Some("ENOTEMPTY")
+                );
+                if !retryable || attempt >= 3 {
+                    return Err(error);
+                }
+                std::thread::sleep(Duration::from_millis(20 * (attempt as u64 + 1)));
+            }
+        }
+    }
+    Ok(())
+}
+
+/// TS `repairCodexSessionIndex(codexHome)` — appends missing rollout entries
+/// to `session_index.jsonl` (best effort, lock-guarded).
+pub fn repair_codex_session_index(codex_home: &Path) {
+    let sessions_dir = codex_home.join("sessions");
+    if !sessions_dir.exists() {
+        return;
+    }
+    let index_path = codex_home.join("session_index.jsonl");
+    let Ok(lock) = acquire_shadow_home_sync_lock(codex_home) else {
+        return;
+    };
+    let result = (|| -> io::Result<()> {
+        let mut seen: HashSet<String> = HashSet::new();
+        let mut existing_lines: Vec<String> = Vec::new();
+        if index_path.exists() {
+            existing_lines = fs::read_to_string(&index_path)?
+                .split(['\r', '\n'])
+                .filter(|l| !l.is_empty())
+                .map(str::to_string)
+                .collect();
+            for line in &existing_lines {
+                if let Ok(entry) = serde_json::from_str::<Value>(line)
+                    && let Some(id) = entry.get("id").and_then(Value::as_str)
+                {
+                    seen.insert(id.to_string());
+                }
+            }
+        }
+        let mut rollout_files = Vec::new();
+        collect_rollout_files(&sessions_dir, &mut rollout_files);
+        let mut additions: Vec<Value> = Vec::new();
+        for rollout_path in rollout_files {
+            if let Some(file_name) = rollout_path.file_name().and_then(|n| n.to_str())
+                && let Some(id_from_name) = extract_rollout_id_from_filename(file_name)
+                && seen.contains(&id_from_name)
+            {
+                continue;
+            }
+            let Some(entry) = parse_rollout_index_entry(&rollout_path) else {
+                continue;
+            };
+            let id = entry
+                .get("id")
+                .and_then(Value::as_str)
+                .unwrap_or_default()
+                .to_string();
+            if seen.contains(&id) {
+                continue;
+            }
+            seen.insert(id);
+            additions.push(entry);
+        }
+        if additions.is_empty() {
+            return Ok(());
+        }
+        additions.sort_by(|a, b| {
+            let a_updated = a.get("updated_at").and_then(Value::as_str).unwrap_or("");
+            let b_updated = b.get("updated_at").and_then(Value::as_str).unwrap_or("");
+            a_updated.cmp(b_updated)
+        });
+        let mut lines = existing_lines;
+        lines.extend(
+            additions
+                .iter()
+                .map(cma_core::json_io::stringify_compact),
+        );
+        write_session_index_atomic(&index_path, &lines)
+    })();
+    let _ = result;
+    lock.release();
+}
+
+// ===========================================================================
+// Forwarded runtime observability.
+// ===========================================================================
+
+fn runtime_snapshot_change_token(
+    snapshot: Option<&cma_runtime::observability::RuntimeObservabilitySnapshot>,
+) -> String {
+    match snapshot {
+        None => "null".to_string(),
+        Some(s) => format!(
+            "{}|{}|{}|{}|{}|{}|{:?}",
+            s.responses_requests,
+            s.auth_refresh_requests,
+            s.diagnostic_probe_requests,
+            s.runtime_metrics.total_requests,
+            s.runtime_metrics.successful_requests,
+            s.runtime_metrics.failed_requests,
+            s.runtime_metrics.last_request_at,
+        ),
+    }
+}
+
+async fn load_runtime_snapshot_with_retry()
+-> Option<cma_runtime::observability::RuntimeObservabilitySnapshot> {
+    for attempt in 0..5 {
+        if let Some(snapshot) =
+            cma_runtime::observability::load_persisted_runtime_observability_snapshot()
+        {
+            return Some(snapshot);
+        }
+        if attempt < 4 {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    }
+    None
+}
+
+/// TS `withForwardedRuntimeObservability(rawArgs, runForwardedCommand)` — if
+/// the forwarded run left no runtime-observability trace (e.g. proxy
+/// bypassed), synthesize one request record.
+async fn with_forwarded_runtime_observability<F, Fut>(raw_args: &[String], run: F) -> i32
+where
+    F: FnOnce() -> Fut,
+    Fut: std::future::Future<Output = i32>,
+{
+    if !should_track_forwarded_runtime_observability(raw_args) {
+        return run().await;
+    }
+    let before = load_runtime_snapshot_with_retry().await;
+    let before_token = runtime_snapshot_change_token(before.as_ref());
+    let started_at = cma_core::utils::now_ms();
+    let exit_code = run().await;
+    let after = load_runtime_snapshot_with_retry().await;
+    let after_token = runtime_snapshot_change_token(after.as_ref());
+    if after_token != before_token {
+        return exit_code;
+    }
+    cma_runtime::observability::mutate_runtime_observability_snapshot(|snapshot| {
+        snapshot.current_request_id = None;
+        snapshot.responses_requests += 1;
+        snapshot.runtime_metrics.total_requests += 1;
+        snapshot.runtime_metrics.responses_requests += 1;
+        snapshot.runtime_metrics.cumulative_latency_ms +=
+            (cma_core::utils::now_ms() - started_at).max(0);
+        snapshot.runtime_metrics.last_request_at = Some(cma_core::utils::now_ms());
+        if snapshot.runtime_metrics.started_at == 0 {
+            snapshot.runtime_metrics.started_at = started_at;
+        }
+        if exit_code == 0 {
+            snapshot.runtime_metrics.successful_requests += 1;
+            snapshot.runtime_metrics.last_error = None;
+        } else {
+            snapshot.runtime_metrics.failed_requests += 1;
+            snapshot.runtime_metrics.last_error =
+                Some(format!("forwarded-codex-exit:{exit_code}"));
+        }
+    });
+    exit_code
+}
+
+// ===========================================================================
+// The forward loop + entrypoint.
+// ===========================================================================
+
+/// TS `forwardToRealCodex(codexBin, rawArgs, baseEnv)` — up to 4 attempts
+/// with wrapper-side unsupported-model fallback.
+async fn forward_to_real_codex(
+    codex_bin: &ResolvedCodexBin,
+    raw_args: &[String],
+    forced_account_index: Option<usize>,
+    extra_env: &HashMap<String, String>,
+) -> i32 {
+    let mut current_args: Vec<String> = raw_args.to_vec();
+    let mut last_exit_code = 1;
+    let mut attempted_models: Vec<String> = Vec::new();
+
+    for _attempt in 0..4 {
+        let requested_model = extract_requested_model(&current_args);
+        if let Some(model) = &requested_model
+            && !attempted_models.contains(model)
+        {
+            attempted_models.push(model.clone());
+        }
+
+        let (forward_args, compatibility_requested_model) = build_forward_args(&current_args);
+        let mut compatibility = create_compatibility_codex_home(
+            forward_args,
+            compatibility_requested_model.as_deref(),
+        );
+        for (key, value) in extra_env {
+            compatibility
+                .env_overrides
+                .entry(key.clone())
+                .or_insert_with(|| value.clone());
+        }
+        // Forced-account pin: publish on the spawned env (children + helper),
+        // or scrub any stray value when no pin was requested.
+        match forced_account_index {
+            Some(index) => {
+                compatibility
+                    .env_overrides
+                    .insert(FORCE_ACCOUNT_INDEX_ENV.to_string(), index.to_string());
+            }
+            None => {
+                compatibility
+                    .env_removals
+                    .push(FORCE_ACCOUNT_INDEX_ENV.to_string());
+            }
+        }
+        let runtime_context = create_runtime_rotation_proxy_context_if_enabled(
+            compatibility,
+            raw_args,
+            forced_account_index,
+        )
+        .await;
+        let capture_output = should_capture_forwarded_output_for_args(raw_args);
+        let proxy_app_server = is_codex_app_server_command(raw_args)
+            && (runtime_context.proxy_app_server_account_read
+                || runtime_context
+                    .env_overrides
+                    .get(APP_SERVER_ACCOUNT_LABEL_ENV)
+                    .map(|v| v.trim() == "1")
+                    .unwrap_or_else(|| env_string(APP_SERVER_ACCOUNT_LABEL_ENV).trim() == "1"));
+        let ForwardContext {
+            args,
+            env_overrides,
+            env_removals,
+            cleanup,
+            proxy_app_server_account_read: _,
+        } = runtime_context;
+        let result = forward_to_real_codex_once(
+            codex_bin,
+            &args,
+            &env_overrides,
+            &env_removals,
+            cleanup,
+            capture_output,
+            proxy_app_server,
+        )
+        .await;
+        last_exit_code = result.exit_code;
+        if result.exit_code == 0 {
+            let env_map = process_env_map();
+            repair_codex_session_index(&resolve_codex_home_dir(&env_map));
+            return result.exit_code;
+        }
+
+        let fallback_model = resolve_unsupported_model_retry_target(
+            requested_model.as_deref(),
+            &result.output,
+            &attempted_models,
+        );
+        let Some(fallback_model) = fallback_model else {
+            return result.exit_code;
+        };
+        eprintln!(
+            "codex-multi-auth: model {} is unsupported on this ChatGPT Codex surface. Retrying with {fallback_model}.",
+            requested_model.as_deref().unwrap_or("requested model")
+        );
+        if !attempted_models.contains(&fallback_model) {
+            attempted_models.push(fallback_model.clone());
+        }
+        let next_args = replace_requested_model(&current_args, &fallback_model);
+        if next_args == current_args {
+            return result.exit_code;
+        }
+        current_args = next_args;
+    }
+
+    last_exit_code
+}
+
+/// The wrapper's non-auth path (TS `main()` after the auth branch): resolve
+/// the official codex, preflight `--account`, print the status line, kick the
+/// background quota refresh, and forward with observability tracking.
+///
+/// The caller (cma-bin main) is responsible for [`classify_wrapper_args`],
+/// the startup update notice, and routing auth-family args to cma-manager.
+pub async fn forward(raw_args: &[String]) -> i32 {
+    let Some(real_codex_bin) = resolve_real_codex_bin() else {
+        let override_value = env_string("CODEX_MULTI_AUTH_REAL_CODEX_BIN");
+        let override_value = override_value.trim();
+        if !override_value.is_empty() && !Path::new(override_value).exists() {
+            eprintln!("CODEX_MULTI_AUTH_REAL_CODEX_BIN is set but missing: {override_value}");
+        }
+        eprintln!(
+            "{}",
+            [
+                "Could not locate the official Codex CLI.",
+                "Install it with npm, Homebrew, or an official native release so `codex` is on PATH.",
+                "Or set CODEX_MULTI_AUTH_REAL_CODEX_BIN to the full path of either codex or @openai/codex/bin/codex.js.",
+            ]
+            .join("\n")
+        );
+        return 1;
+    };
+
+    // Resolve `--account` / CODEX_MULTI_AUTH_FORCE_ACCOUNT before forwarding:
+    // strip the launcher-only flag and resolve the pin, or fail hard so a
+    // forced account can never silently fall back to another one.
+    let forced = apply_forced_account_selection(raw_args, async |args: &[String]| {
+        is_runtime_rotation_proxy_enabled(args).await
+    })
+    .await;
+    let (forward_args, forced_index) = match forced {
+        ForcedAccountOutcome::Error(message) => {
+            eprintln!("{message}");
+            return 1;
+        }
+        ForcedAccountOutcome::Forward {
+            forward_args,
+            forced_index,
+        } => (forward_args, forced_index),
+    };
+
+    // Version hydration for children (TS `hydrateCliVersionEnv`).
+    let mut extra_env: HashMap<String, String> = HashMap::new();
+    if env_string("CODEX_MULTI_AUTH_CLI_VERSION").trim().is_empty() {
+        extra_env.insert(
+            "CODEX_MULTI_AUTH_CLI_VERSION".to_string(),
+            env!("CARGO_PKG_VERSION").to_string(),
+        );
+    }
+
+    crate::statusline::maybe_print_forward_status_line(&forward_args);
+    crate::statusline::maybe_refresh_quota_cache_in_background(&extra_env);
+
+    with_forwarded_runtime_observability(&forward_args, || {
+        forward_to_real_codex(&real_codex_bin, &forward_args, forced_index, &extra_env)
+    })
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn v(args: &[&str]) -> Vec<String> {
+        args.iter().map(|s| s.to_string()).collect()
+    }
+
+    /// TS parity: when a rollout carries session_meta but no string
+    /// `timestamp`, the session-index `updated_at` falls back to the file
+    /// mtime as an ISO-8601 UTC string (`mtime.toISOString()`), never raw
+    /// epoch millis or "" — the entry lands in the REAL
+    /// ~/.codex/session_index.jsonl consumed by the official resume list.
+    #[test]
+    fn rollout_index_updated_at_fallback_is_iso8601_utc() {
+        let dir = tempfile::tempdir().unwrap();
+        let rollout = dir
+            .path()
+            .join("rollout-2026-07-27T10-00-00-11111111-2222-3333-4444-555555555555.jsonl");
+        std::fs::write(
+            &rollout,
+            "{\"type\":\"session_meta\",\"payload\":{\"id\":\"sess-1\"}}\n",
+        )
+        .unwrap();
+
+        let entry = parse_rollout_index_entry(&rollout).expect("entry");
+        let updated_at = entry["updated_at"].as_str().expect("string updated_at");
+        assert!(updated_at.ends_with('Z'), "UTC Z suffix: {updated_at}");
+        let parsed = chrono::DateTime::parse_from_rfc3339(updated_at)
+            .unwrap_or_else(|e| panic!("RFC3339 expected, got {updated_at}: {e}"));
+        // toISOString shape: exactly milliseconds precision.
+        assert_eq!(
+            updated_at,
+            parsed
+                .with_timezone(&chrono::Utc)
+                .to_rfc3339_opts(chrono::SecondsFormat::Millis, true)
+        );
+        // And it tracks the file mtime, not the epoch-millis digits.
+        assert!(!updated_at.chars().all(|c| c.is_ascii_digit()));
+    }
+
+    #[test]
+    fn classification_routes_helper_auth_and_forward() {
+        assert_eq!(
+            classify_wrapper_args(&v(&[INTERNAL_RUNTIME_ROTATION_APP_HELPER_ARG])),
+            WrapperDispatch::RunAppHelper
+        );
+        match classify_wrapper_args(&v(&["multi-auth", "status"])) {
+            WrapperDispatch::AuthManager { normalized_args } => {
+                assert_eq!(normalized_args, v(&["auth", "status"]));
+            }
+            other => panic!("expected AuthManager, got {other:?}"),
+        }
+        match classify_wrapper_args(&v(&["exec", "hello"])) {
+            WrapperDispatch::Forward { raw_args } => assert_eq!(raw_args, v(&["exec", "hello"])),
+            other => panic!("expected Forward, got {other:?}"),
+        }
+        // Unknown auth subcommand forwards.
+        match classify_wrapper_args(&v(&["auth", "whoami"])) {
+            WrapperDispatch::Forward { .. } => {}
+            other => panic!("expected Forward, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn model_normalization_aliases() {
+        assert_eq!(normalize_requested_model("gpt-5"), "gpt-5.5");
+        assert_eq!(normalize_requested_model("openai/gpt-5"), "gpt-5.5");
+        assert_eq!(normalize_requested_model("gpt-5-codex"), CURRENT_CODEX_MODEL);
+        assert_eq!(normalize_requested_model("codex"), CURRENT_CODEX_MODEL);
+        assert_eq!(normalize_requested_model("codex-max"), CURRENT_CODEX_MODEL);
+        assert_eq!(normalize_requested_model("gpt-5.6"), "gpt-5.6-sol");
+        assert_eq!(normalize_requested_model("gpt-5.6-terra"), "gpt-5.6-terra");
+        // Unknown 5.6 tier resolves to Sol; codex-suffixed 5.6 does not.
+        assert_eq!(normalize_requested_model("gpt-5.6-nova"), "gpt-5.6-sol");
+        assert_eq!(normalize_requested_model("gpt-5.6-luna-max"), "gpt-5.6-luna");
+        // Unknown general minor falls to the stable catalog.
+        assert_eq!(normalize_requested_model("gpt-5.9"), "gpt-5.5");
+        assert_eq!(normalize_requested_model("gpt-5.9-pro"), "gpt-5.5-pro");
+        assert_eq!(normalize_requested_model("gpt-5.4-mini"), "gpt-5.4-mini");
+        assert_eq!(normalize_requested_model(""), "");
+        assert_eq!(normalize_requested_model("o3"), "");
+        assert_eq!(normalize_requested_model("gpt-5.5-high"), "gpt-5.5");
+        assert_eq!(normalize_requested_model("gpt_5_codex"), CURRENT_CODEX_MODEL);
+    }
+
+    #[test]
+    fn effort_coercion_rules() {
+        // none is coerced up to low on GPT-5.6 tiers.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.6-sol", "none"), "low");
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.6-sol", "minimal"), "low");
+        // ultra never reaches the wire.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.6-sol", "ultra"), "max");
+        // Luna stops at max.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.6-luna", "ultra"), "max");
+        // Pre-5.6 model with max steps down to xhigh.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.5", "max"), "xhigh");
+        // gpt-5.1 has no xhigh.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.1", "xhigh"), "high");
+        // Unknown effort passes through untouched.
+        assert_eq!(coerce_reasoning_effort_for_model("gpt-5.5", "turbo"), "turbo");
+        // Unknown model keeps the effort.
+        assert_eq!(coerce_reasoning_effort_for_model("o3", "high"), "high");
+        // ultra on unknown model still rewritten to max.
+        assert_eq!(coerce_reasoning_effort_for_model("o3", "ultra"), "max");
+    }
+
+    #[test]
+    fn reasoning_config_arg_rewrite() {
+        let (args, model) = rewrite_reasoning_config_args(&v(&[
+            "-m",
+            "gpt-5.5",
+            "-c",
+            "model_reasoning_effort=\"max\"",
+        ]));
+        assert_eq!(model.as_deref(), Some("gpt-5.5"));
+        assert_eq!(args[3], "model_reasoning_effort=\"xhigh\"");
+        // No model → untouched.
+        let (args, model) =
+            rewrite_reasoning_config_args(&v(&["-c", "model_reasoning_effort=\"max\""]));
+        assert_eq!(model, None);
+        assert_eq!(args[1], "model_reasoning_effort=\"max\"");
+        // --config= form.
+        let (args, _) = rewrite_reasoning_config_args(&v(&[
+            "--model=gpt-5.5",
+            "--config=model_reasoning_effort='ultra'",
+        ]));
+        assert_eq!(args[1], "--config=model_reasoning_effort='xhigh'");
+    }
+
+    #[test]
+    fn config_toml_reasoning_rewrite() {
+        let raw = "model = \"gpt-5.5\"\nmodel_reasoning_effort = \"max\"\n";
+        let rewritten = rewrite_config_toml_reasoning_effort(raw, "gpt-5.5");
+        assert_eq!(
+            rewritten,
+            "model = \"gpt-5.5\"\nmodel_reasoning_effort = \"xhigh\"\n"
+        );
+        // Bare value + comment preserved.
+        let raw = "model_reasoning_effort = max # keep\n";
+        let rewritten = rewrite_config_toml_reasoning_effort(raw, "gpt-5.5");
+        assert_eq!(rewritten, "model_reasoning_effort = xhigh # keep\n");
+        // Unchanged config returns identical string.
+        let raw = "model_reasoning_effort = \"high\"\n";
+        assert_eq!(rewrite_config_toml_reasoning_effort(raw, "gpt-5.5"), raw);
+        // CRLF preserved.
+        let raw = "a = 1\r\nmodel_reasoning_effort = \"ultra\"\r\n";
+        let rewritten = rewrite_config_toml_reasoning_effort(raw, "gpt-5.6-sol");
+        assert!(rewritten.contains("model_reasoning_effort = \"max\""));
+        assert!(rewritten.contains("\r\n"));
+    }
+
+    #[test]
+    fn credentials_store_injection() {
+        // Opt-out env not set → injected.
+        if std::env::var("CODEX_MULTI_AUTH_FORCE_FILE_AUTH_STORE").is_err() {
+            let (args, _) = build_forward_args(&v(&["exec"]));
+            assert_eq!(
+                &args[args.len() - 2..],
+                &v(&["-c", "cli_auth_credentials_store=\"file\""])[..]
+            );
+            // Caller override suppresses injection.
+            let (args, _) =
+                build_forward_args(&v(&["-c", "cli_auth_credentials_store=keyring"]));
+            assert_eq!(args, v(&["-c", "cli_auth_credentials_store=keyring"]));
+            let (args, _) =
+                build_forward_args(&v(&["--config=cli_auth_credentials_store=keyring"]));
+            assert_eq!(args, v(&["--config=cli_auth_credentials_store=keyring"]));
+        }
+    }
+
+    #[test]
+    fn credentials_store_override_detection() {
+        assert!(has_cli_auth_credentials_store_override(&v(&[
+            "-c",
+            "cli_auth_credentials_store=file"
+        ])));
+        assert!(has_cli_auth_credentials_store_override(&v(&[
+            "--config",
+            " cli_auth_credentials_store =file"
+        ])));
+        assert!(has_cli_auth_credentials_store_override(&v(&[
+            "--config=cli_auth_credentials_store=x"
+        ])));
+        assert!(!has_cli_auth_credentials_store_override(&v(&["-c", "model=x"])));
+        assert!(!has_cli_auth_credentials_store_override(&v(&["-c"])));
+    }
+
+    #[test]
+    fn unsupported_model_output_parsing() {
+        let direct = "'gpt-5.5' model is not supported when using codex with a chatgpt account";
+        assert_eq!(
+            extract_unsupported_model_from_output(direct).as_deref(),
+            Some("gpt-5.5")
+        );
+        let normalized = "Model \"gpt-5.3-codex-spark\" is not currently available for this ChatGPT account when using Codex OAuth.";
+        assert_eq!(
+            extract_unsupported_model_from_output(normalized).as_deref(),
+            Some("gpt-5.3-codex-spark")
+        );
+        let denied = "The model `gpt-5.5-pro` does not exist or you do not have access to it.";
+        assert_eq!(
+            extract_unsupported_model_from_output(denied).as_deref(),
+            Some("gpt-5.5-pro")
+        );
+        assert_eq!(extract_unsupported_model_from_output("all good"), None);
+        // Effort suffix stripped by canonicalization.
+        let with_effort = "The model `gpt-5.5-high` does not exist or you do not have access to it.";
+        assert_eq!(
+            extract_unsupported_model_from_output(with_effort).as_deref(),
+            Some("gpt-5.5")
+        );
+    }
+
+    #[test]
+    fn unsupported_retry_target_resolution() {
+        let output = "'gpt-5.5' model is not supported when using codex with a chatgpt account";
+        assert_eq!(
+            resolve_unsupported_model_retry_target(Some("gpt-5.5"), output, &[]).as_deref(),
+            Some("gpt-5.4")
+        );
+        // Already-attempted fallback skipped.
+        assert_eq!(
+            resolve_unsupported_model_retry_target(
+                Some("gpt-5.5"),
+                output,
+                &v(&["gpt-5.4"])
+            ),
+            None
+        );
+        // Spark → current codex model.
+        let spark = "Model 'gpt-5.3-codex-spark' is not currently available for this ChatGPT account when using Codex OAuth";
+        assert_eq!(
+            resolve_unsupported_model_retry_target(Some("gpt-5.3-codex-spark"), spark, &[])
+                .as_deref(),
+            Some(CURRENT_CODEX_MODEL)
+        );
+        // No unsupported marker → no retry.
+        assert_eq!(
+            resolve_unsupported_model_retry_target(Some("gpt-5.5"), "boom", &[]),
+            None
+        );
+        // Unknown blocked model without chain → None.
+        let unknown = "'weird-model' model is not supported when using codex with a chatgpt account";
+        assert_eq!(
+            resolve_unsupported_model_retry_target(Some("weird-model"), unknown, &[]),
+            None
+        );
+    }
+
+    #[test]
+    fn model_replacement_forms() {
+        assert_eq!(
+            replace_requested_model(&v(&["-m", "a", "exec"]), "b"),
+            v(&["-m", "b", "exec"])
+        );
+        assert_eq!(
+            replace_requested_model(&v(&["--model=a"]), "b"),
+            v(&["--model=b"])
+        );
+        assert_eq!(replace_requested_model(&v(&["exec"]), "b"), v(&["exec"]));
+        assert_eq!(replace_requested_model(&v(&["-m", "a"]), ""), v(&["-m", "a"]));
+    }
+
+    #[test]
+    fn runtime_rotation_env_parsing() {
+        assert_eq!(parse_runtime_rotation_proxy_env(None), None);
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("")), None);
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("1")), Some(true));
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("TRUE")), Some(true));
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("yes")), Some(true));
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("0")), Some(false));
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("no")), Some(false));
+        assert_eq!(parse_runtime_rotation_proxy_env(Some("maybe")), None);
+    }
+
+    #[test]
+    fn json_rpc_id_keys_distinguish_types() {
+        assert_eq!(
+            json_rpc_id_key(&Value::from(1)).as_deref(),
+            Some("number:1")
+        );
+        assert_eq!(
+            json_rpc_id_key(&Value::from("1")).as_deref(),
+            Some("string:\"1\"")
+        );
+        assert_ne!(
+            json_rpc_id_key(&Value::from(1)),
+            json_rpc_id_key(&Value::from("1"))
+        );
+        assert_eq!(json_rpc_id_key(&Value::Null).as_deref(), Some("object:null"));
+        assert_eq!(json_rpc_id_key(&serde_json::json!({})), None);
+    }
+
+    #[test]
+    fn app_server_protocol_rewrite_round_trip() {
+        let mut pending = std::collections::HashMap::new();
+        observe_app_server_request_line(
+            "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"account/read\"}\n",
+            &mut pending,
+        );
+        assert_eq!(pending.len(), 1);
+        // Unrelated response passes through.
+        let unrelated = "{\"jsonrpc\":\"2.0\",\"id\":8,\"result\":{}}\n";
+        assert_eq!(
+            rewrite_app_server_account_read_response_line(unrelated, &mut pending),
+            unrelated
+        );
+        // The tracked id is rewritten with the synthetic account payload.
+        let response = "{\"jsonrpc\":\"2.0\",\"id\":7,\"result\":{\"account\":{\"email\":\"real@x.com\"}}}\r\n";
+        let rewritten = rewrite_app_server_account_read_response_line(response, &mut pending);
+        assert!(rewritten.ends_with("\r\n"));
+        let parsed: Value = serde_json::from_str(rewritten.trim()).unwrap();
+        assert_eq!(parsed["result"]["account"]["email"], "codex-multi-auth");
+        assert_eq!(parsed["result"]["requiresOpenaiAuth"], false);
+        assert_eq!(parsed["id"], 7);
+        // Consumed: second response with the same id passes through.
+        assert_eq!(
+            rewrite_app_server_account_read_response_line(response, &mut pending),
+            response
+        );
+
+        // getAuthStatus + rateLimits synthesize their own shapes.
+        observe_app_server_request_line(
+            "{\"id\":\"a\",\"method\":\"getAuthStatus\"}\n",
+            &mut pending,
+        );
+        let rewritten = rewrite_app_server_account_read_response_line(
+            "{\"id\":\"a\",\"result\":{\"authToken\":\"secret\"}}\n",
+            &mut pending,
+        );
+        let parsed: Value = serde_json::from_str(rewritten.trim()).unwrap();
+        assert_eq!(parsed["result"]["authMethod"], "apikey");
+        assert_eq!(parsed["result"]["authToken"], Value::Null);
+        // Requests without ids are ignored.
+        observe_app_server_request_line(
+            "{\"method\":\"account/read\"}\n",
+            &mut pending,
+        );
+        assert!(pending.is_empty());
+    }
+
+    #[test]
+    fn protocol_line_accumulator_buffers_partial_lines() {
+        let mut acc = ProtocolLineAccumulator::new();
+        assert!(acc.write("{\"a\":").is_empty());
+        let lines = acc.write("1}\n{\"b\":2}\n{\"partial");
+        assert_eq!(lines, vec!["{\"a\":1}\n".to_string(), "{\"b\":2}\n".to_string()]);
+        assert_eq!(acc.end().as_deref(), Some("{\"partial"));
+        assert_eq!(acc.end(), None);
+    }
+
+    #[test]
+    fn stderr_filter_drops_known_noise_pairs() {
+        let text = [
+            "keep me",
+            "2026-01-01 ERROR codex_core::session: failed to record rollout items: thread",
+            "0187a2b4-1111-2222-3333-444455556666 not found",
+            "also keep",
+        ]
+        .join("\n");
+        assert_eq!(filter_known_forwarded_codex_stderr(&text), "keep me\nalso keep");
+        // Non-matching second line keeps both.
+        let text = [
+            "ERROR codex_core::session: failed to record rollout items: thread",
+            "unrelated",
+        ]
+        .join("\n");
+        assert_eq!(
+            filter_known_forwarded_codex_stderr(&text),
+            "ERROR codex_core::session: failed to record rollout items: thread\nunrelated"
+        );
+        assert_eq!(filter_known_forwarded_codex_stderr(""), "");
+    }
+
+    #[test]
+    fn rollout_filename_parsing() {
+        assert_eq!(
+            extract_rollout_id_from_filename(
+                "rollout-2026-07-27T10-30-00-0187a2b4-1111-2222-3333-444455556666.jsonl"
+            )
+            .as_deref(),
+            Some("0187a2b4-1111-2222-3333-444455556666")
+        );
+        assert_eq!(
+            extract_rollout_id_from_filename("rollout-2026-07-27T10-30-00-nope.jsonl"),
+            None
+        );
+        assert_eq!(extract_rollout_id_from_filename("other.jsonl"), None);
+        assert_eq!(
+            extract_rollout_id_from_filename(
+                "rollout-2026-07-27T10-30-00-0187A2B4-1111-2222-3333-444455556666.JSONL"
+            )
+            .as_deref(),
+            Some("0187a2b4-1111-2222-3333-444455556666")
+        );
+    }
+
+    #[test]
+    fn client_api_key_is_64_hex_chars() {
+        let key = create_runtime_rotation_proxy_client_api_key();
+        assert_eq!(key.len(), 64);
+        assert!(key.chars().all(|c| c.is_ascii_hexdigit()));
+        assert_ne!(key, create_runtime_rotation_proxy_client_api_key());
+    }
+
+    #[test]
+    fn provider_args_use_frozen_provider_id() {
+        let args = provider_config_args();
+        assert_eq!(args[0], "-c");
+        assert_eq!(args[1], "model_provider=\"codex-multi-auth-runtime-proxy\"");
+    }
+}
diff --git a/crates/wrapper/src/lib.rs b/crates/wrapper/src/lib.rs
new file mode 100644
index 000000000..d15d6f495
--- /dev/null
+++ b/crates/wrapper/src/lib.rs
@@ -0,0 +1,9 @@
+//! cma-wrapper - foundation-owned module tree. Implementers: do NOT edit this file.
+pub mod account_force;
+pub mod bin_resolver;
+pub mod forward;
+pub mod mcodex;
+pub mod routing;
+pub mod shadow_home;
+pub mod statusline;
+pub mod update_check;
diff --git a/crates/wrapper/src/mcodex.rs b/crates/wrapper/src/mcodex.rs
new file mode 100644
index 000000000..9339e9524
--- /dev/null
+++ b/crates/wrapper/src/mcodex.rs
@@ -0,0 +1,520 @@
+//! Port of `scripts/mcodex.js` — the convenience launcher over the codex
+//! wrapper. Modes (spec 14 §2.1):
+//! - default: forward every arg to the sibling codex wrapper binary;
+//! - `--monitor`: `watch -n <interval> codex-multi-auth list` (interval
+//!   default 5 s via `MCODEX_MONITOR_INTERVAL`, positive number only; exits 1
+//!   with an install hint when `watch` is missing);
+//! - `--tmux`/`-t` (+ optional `--live-accounts` immediately after): tmux
+//!   session (default name `mcodex` via `MCODEX_TMUX_SESSION`; history limit
+//!   default 50000 via `MCODEX_TMUX_HISTORY_LIMIT`); warns and forwards
+//!   without tmux when tmux is missing (R8: shell out, no TUI).
+//!
+//! Deviation vs TS: the bash/node launcher spawned `node <sibling codex.js>`;
+//! the Rust port spawns the sibling `codex-multi-auth-codex` binary (same
+//! no-PATH-shim guarantee).
+
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+
+use crate::bin_resolver::split_path_entries;
+use crate::statusline::resolve_sibling_cma_binary;
+
+pub const DEFAULT_MONITOR_INTERVAL: &str = "5";
+pub const DEFAULT_TMUX_HISTORY_LIMIT: &str = "50000";
+pub const DEFAULT_TMUX_SESSION: &str = "mcodex";
+
+/// TS `parseMcodexArgs(argv)` mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McodexMode {
+    Forward,
+    Monitor,
+    Tmux,
+}
+
+/// TS `parseMcodexArgs(argv)` result.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ParsedMcodexArgs {
+    pub mode: McodexMode,
+    pub live_accounts: bool,
+    pub forward_args: Vec<String>,
+}
+
+/// TS `parseMcodexArgs(argv)` — the FIRST argument selects the mode; only
+/// `--tmux`/`-t` consumes a following `--live-accounts`.
+pub fn parse_mcodex_args(argv: &[String]) -> ParsedMcodexArgs {
+    let first = argv.first().map(String::as_str).unwrap_or("");
+    if first == "--monitor" {
+        return ParsedMcodexArgs {
+            mode: McodexMode::Monitor,
+            live_accounts: false,
+            forward_args: argv[1..].to_vec(),
+        };
+    }
+    if first == "--tmux" || first == "-t" {
+        let mut rest = argv[1..].to_vec();
+        let mut live_accounts = false;
+        if rest.first().map(String::as_str) == Some("--live-accounts") {
+            live_accounts = true;
+            rest.remove(0);
+        }
+        return ParsedMcodexArgs {
+            mode: McodexMode::Tmux,
+            live_accounts,
+            forward_args: rest,
+        };
+    }
+    ParsedMcodexArgs {
+        mode: McodexMode::Forward,
+        live_accounts: false,
+        forward_args: argv.to_vec(),
+    }
+}
+
+fn is_positive_number(value: &str) -> bool {
+    // /^[0-9]+(\.[0-9]+)?$/
+    let mut parts = value.split('.');
+    let int_part = parts.next().unwrap_or("");
+    let frac_part = parts.next();
+    if parts.next().is_some() {
+        return false;
+    }
+    if int_part.is_empty() || !int_part.chars().all(|c| c.is_ascii_digit()) {
+        return false;
+    }
+    match frac_part {
+        None => true,
+        Some(frac) => !frac.is_empty() && frac.chars().all(|c| c.is_ascii_digit()),
+    }
+}
+
+fn is_plain_integer(value: &str) -> bool {
+    !value.is_empty() && value.chars().all(|c| c.is_ascii_digit())
+}
+
+fn coerce_validated_setting(
+    raw_value: Option<&str>,
+    validate: impl Fn(&str) -> bool,
+    fallback: &str,
+    env_name: &str,
+    warn: &mut dyn FnMut(&str),
+) -> String {
+    // Mirror bash `${VAR:-default}`: unset OR empty falls back silently; any
+    // other value is validated and, if it fails, replaced with a warning.
+    let value = match raw_value {
+        None | Some("") => fallback,
+        Some(other) => other,
+    };
+    if !validate(value) {
+        warn(&format!("mcodex: invalid {env_name} '{value}'; using {fallback}"));
+        return fallback.to_string();
+    }
+    value.to_string()
+}
+
+/// TS `resolveMonitorInterval(env, warn)`.
+pub fn resolve_monitor_interval(
+    raw: Option<&str>,
+    warn: &mut dyn FnMut(&str),
+) -> String {
+    coerce_validated_setting(
+        raw,
+        is_positive_number,
+        DEFAULT_MONITOR_INTERVAL,
+        "MCODEX_MONITOR_INTERVAL",
+        warn,
+    )
+}
+
+/// TS `resolveTmuxHistoryLimit(env, warn)`.
+pub fn resolve_tmux_history_limit(
+    raw: Option<&str>,
+    warn: &mut dyn FnMut(&str),
+) -> String {
+    coerce_validated_setting(
+        raw,
+        is_plain_integer,
+        DEFAULT_TMUX_HISTORY_LIMIT,
+        "MCODEX_TMUX_HISTORY_LIMIT",
+        warn,
+    )
+}
+
+/// TS `resolveTmuxSession(env)`.
+pub fn resolve_tmux_session(raw: Option<&str>) -> String {
+    let configured = raw.unwrap_or("").trim();
+    if configured.is_empty() {
+        DEFAULT_TMUX_SESSION.to_string()
+    } else {
+        configured.to_string()
+    }
+}
+
+/// TS `resolvePosixToolOnPath(tool, env, platform)`.
+pub fn resolve_posix_tool_on_path(tool: &str, path_value: &str) -> Option<PathBuf> {
+    let names: Vec<String> = if cfg!(windows) {
+        vec![format!("{tool}.exe"), format!("{tool}.cmd"), tool.to_string()]
+    } else {
+        vec![tool.to_string()]
+    };
+    for entry in split_path_entries(path_value) {
+        for name in &names {
+            let candidate = Path::new(&entry).join(name);
+            if candidate.exists() {
+                return Some(candidate);
+            }
+        }
+    }
+    None
+}
+
+fn path_env_value() -> String {
+    std::env::var("PATH")
+        .or_else(|_| std::env::var("Path"))
+        .unwrap_or_default()
+}
+
+fn has_posix_tool(tool: &str) -> bool {
+    resolve_posix_tool_on_path(tool, &path_env_value()).is_some()
+}
+
+/// TS `buildWatchArgs(interval)` — argv tokens, never a shell string.
+pub fn build_watch_args(interval: &str) -> Vec<String> {
+    vec![
+        "-n".to_string(),
+        interval.to_string(),
+        "codex-multi-auth".to_string(),
+        "list".to_string(),
+    ]
+}
+
+const WATCH_MISSING_MESSAGE: &str = "mcodex: 'watch' is not installed; the live account monitor requires it (install procps / procps-ng).";
+
+fn exit_code_of(status: std::process::ExitStatus) -> i32 {
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(signal) = status.signal() {
+            // SIGINT → 130 (TS parity); any other signal → 1.
+            return if signal == 2 { 130 } else { 1 };
+        }
+    }
+    status.code().unwrap_or(1)
+}
+
+async fn spawn_and_wait_inherit(program: &Path, args: &[String], label: &str) -> i32 {
+    let mut command = tokio::process::Command::new(program);
+    command.args(args);
+    match command.spawn() {
+        Ok(mut child) => match child.wait().await {
+            Ok(status) => exit_code_of(status),
+            Err(_) => 1,
+        },
+        Err(error) => {
+            eprintln!("mcodex: failed to launch {label}: {error}");
+            1
+        }
+    }
+}
+
+async fn forward_to_codex_wrapper(forward_args: &[String]) -> i32 {
+    let wrapper = resolve_sibling_cma_binary("codex-multi-auth-codex");
+    spawn_and_wait_inherit(&wrapper, forward_args, "codex wrapper").await
+}
+
+async fn run_monitor(interval: &str) -> i32 {
+    let Some(watch_path) = resolve_posix_tool_on_path("watch", &path_env_value()) else {
+        eprintln!("{WATCH_MISSING_MESSAGE}");
+        return 1;
+    };
+    spawn_and_wait_inherit(&watch_path, &build_watch_args(interval), "watch").await
+}
+
+/// Run a tmux subcommand synchronously, swallowing output (TS `runTmux`).
+fn run_tmux(tmux_path: &Path, args: &[String]) -> Option<std::process::ExitStatus> {
+    std::process::Command::new(tmux_path)
+        .args(args)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .ok()
+}
+
+fn tmux_args(parts: &[&str]) -> Vec<String> {
+    parts.iter().map(|s| s.to_string()).collect()
+}
+
+fn configure_tmux_scrollback(tmux_path: &Path, history_limit: &str, target: Option<&str>) {
+    let target_args: Vec<String> = match target {
+        Some(t) => vec!["-t".to_string(), t.to_string()],
+        None => Vec::new(),
+    };
+    let mut set_mouse = tmux_args(&["set-option"]);
+    set_mouse.extend(target_args.clone());
+    set_mouse.extend(tmux_args(&["mouse", "on"]));
+    run_tmux(tmux_path, &set_mouse);
+    let mut set_history = tmux_args(&["set-option"]);
+    set_history.extend(target_args);
+    set_history.extend(vec!["history-limit".to_string(), history_limit.to_string()]);
+    run_tmux(tmux_path, &set_history);
+    run_tmux(tmux_path, &tmux_args(&["bind-key", "-T", "root", "WheelUpPane", "copy-mode", "-e"]));
+    run_tmux(
+        tmux_path,
+        &tmux_args(&["bind-key", "-T", "copy-mode", "WheelUpPane", "send-keys", "-X", "scroll-up"]),
+    );
+    run_tmux(
+        tmux_path,
+        &tmux_args(&["bind-key", "-T", "copy-mode", "WheelDownPane", "send-keys", "-X", "scroll-down"]),
+    );
+    run_tmux(
+        tmux_path,
+        &tmux_args(&["bind-key", "-T", "copy-mode-vi", "WheelUpPane", "send-keys", "-X", "scroll-up"]),
+    );
+    run_tmux(
+        tmux_path,
+        &tmux_args(&["bind-key", "-T", "copy-mode-vi", "WheelDownPane", "send-keys", "-X", "scroll-down"]),
+    );
+}
+
+/// TS `formatTmuxSessionSuffix(date)` — `HHMMSS` local-ish suffix. The Rust
+/// port derives it from the epoch clock (uniqueness is what matters).
+pub fn format_tmux_session_suffix(now_ms: i64) -> String {
+    let seconds_of_day = now_ms.div_euclid(1000).rem_euclid(86_400);
+    let hours = seconds_of_day / 3600;
+    let minutes = (seconds_of_day % 3600) / 60;
+    let seconds = seconds_of_day % 60;
+    format!("{hours:02}{minutes:02}{seconds:02}")
+}
+
+struct TmuxModeOptions {
+    live_accounts: bool,
+    forward_args: Vec<String>,
+    interval: String,
+    history_limit: String,
+    session: String,
+}
+
+async fn run_tmux_mode(options: TmuxModeOptions) -> i32 {
+    let TmuxModeOptions {
+        live_accounts,
+        forward_args,
+        interval,
+        history_limit,
+        session,
+    } = options;
+
+    let Some(tmux_path) = resolve_posix_tool_on_path("tmux", &path_env_value()) else {
+        // Degrade exactly like the bash version: warn, then forward without tmux.
+        eprintln!("mcodex: tmux is not installed; launching without tmux");
+        return forward_to_codex_wrapper(&forward_args).await;
+    };
+
+    let watch_available = live_accounts && has_posix_tool("watch");
+    if live_accounts && !watch_available {
+        eprintln!("{WATCH_MISSING_MESSAGE}");
+    }
+
+    // Already inside a tmux client: configure the current session, optionally
+    // add a live-accounts pane, then run codex in the current pane.
+    if !std::env::var("TMUX").unwrap_or_default().is_empty() {
+        configure_tmux_scrollback(&tmux_path, &history_limit, None);
+        if watch_available {
+            let mut split = tmux_args(&["split-window", "-h", "watch"]);
+            split.extend(build_watch_args(&interval));
+            run_tmux(&tmux_path, &split);
+        }
+        return forward_to_codex_wrapper(&forward_args).await;
+    }
+
+    // Not inside tmux: fresh detached session, configure, optional live pane,
+    // attach, propagate the exit code.
+    let mut target_session = session;
+    let has_session = run_tmux(
+        &tmux_path,
+        &tmux_args(&["has-session", "-t", &target_session]),
+    )
+    .is_some_and(|status| status.success());
+    if has_session {
+        target_session = format!(
+            "{target_session}-{}",
+            format_tmux_session_suffix(cma_core::utils::now_ms())
+        );
+    }
+    let wrapper = resolve_sibling_cma_binary("codex-multi-auth-codex");
+    let mut new_session = tmux_args(&["new-session", "-d", "-s", &target_session, "-n", "codex"]);
+    new_session.push(wrapper.display().to_string());
+    new_session.extend(forward_args.iter().cloned());
+    run_tmux(&tmux_path, &new_session);
+    configure_tmux_scrollback(&tmux_path, &history_limit, Some(&target_session));
+    if watch_available {
+        let mut split = tmux_args(&[
+            "split-window",
+            "-h",
+            "-t",
+            &format!("{target_session}:0"),
+            "watch",
+        ]);
+        split.extend(build_watch_args(&interval));
+        run_tmux(&tmux_path, &split);
+    }
+    run_tmux(
+        &tmux_path,
+        &tmux_args(&["select-pane", "-t", &format!("{target_session}:0.0")]),
+    );
+    let mut attach = tokio::process::Command::new(&tmux_path);
+    attach.args(["attach-session", "-t", &target_session]);
+    match attach.spawn() {
+        Ok(mut child) => match child.wait().await {
+            Ok(status) => {
+                #[cfg(unix)]
+                {
+                    use std::os::unix::process::ExitStatusExt;
+                    if status.signal() == Some(2) {
+                        return 130;
+                    }
+                }
+                status.code().unwrap_or(0)
+            }
+            Err(_) => 0,
+        },
+        Err(error) => {
+            eprintln!("mcodex: failed to attach tmux session: {error}");
+            1
+        }
+    }
+}
+
+/// TS `runMcodex(argv, env, platform)` — entrypoint for the `mcodex` bin.
+/// Returns the process exit code.
+pub async fn run_mcodex(argv: &[String]) -> i32 {
+    let parsed = parse_mcodex_args(argv);
+    let mut warn = |message: &str| eprintln!("{message}");
+    let interval_env = std::env::var("MCODEX_MONITOR_INTERVAL").ok();
+    let interval = resolve_monitor_interval(interval_env.as_deref(), &mut warn);
+    let history_env = std::env::var("MCODEX_TMUX_HISTORY_LIMIT").ok();
+    let history_limit = resolve_tmux_history_limit(history_env.as_deref(), &mut warn);
+
+    match parsed.mode {
+        McodexMode::Monitor => run_monitor(&interval).await,
+        McodexMode::Tmux => {
+            let session_env = std::env::var("MCODEX_TMUX_SESSION").ok();
+            run_tmux_mode(TmuxModeOptions {
+                live_accounts: parsed.live_accounts,
+                forward_args: parsed.forward_args,
+                interval,
+                history_limit,
+                session: resolve_tmux_session(session_env.as_deref()),
+            })
+            .await
+        }
+        McodexMode::Forward => forward_to_codex_wrapper(&parsed.forward_args).await,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn v(args: &[&str]) -> Vec<String> {
+        args.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn parse_modes() {
+        let parsed = parse_mcodex_args(&v(&["--monitor", "extra"]));
+        assert_eq!(parsed.mode, McodexMode::Monitor);
+        assert!(!parsed.live_accounts);
+        assert_eq!(parsed.forward_args, v(&["extra"]));
+
+        let parsed = parse_mcodex_args(&v(&["--tmux", "--live-accounts", "exec"]));
+        assert_eq!(parsed.mode, McodexMode::Tmux);
+        assert!(parsed.live_accounts);
+        assert_eq!(parsed.forward_args, v(&["exec"]));
+
+        let parsed = parse_mcodex_args(&v(&["-t", "exec"]));
+        assert_eq!(parsed.mode, McodexMode::Tmux);
+        assert!(!parsed.live_accounts);
+        assert_eq!(parsed.forward_args, v(&["exec"]));
+
+        // --live-accounts is only consumed right after --tmux/-t.
+        let parsed = parse_mcodex_args(&v(&["-t", "exec", "--live-accounts"]));
+        assert!(!parsed.live_accounts);
+        assert_eq!(parsed.forward_args, v(&["exec", "--live-accounts"]));
+
+        // Anything else forwards untouched (including a later --monitor).
+        let parsed = parse_mcodex_args(&v(&["exec", "--monitor"]));
+        assert_eq!(parsed.mode, McodexMode::Forward);
+        assert_eq!(parsed.forward_args, v(&["exec", "--monitor"]));
+
+        let parsed = parse_mcodex_args(&[]);
+        assert_eq!(parsed.mode, McodexMode::Forward);
+        assert!(parsed.forward_args.is_empty());
+    }
+
+    #[test]
+    fn monitor_interval_validation() {
+        let warnings = std::cell::RefCell::new(Vec::<String>::new());
+        let mut warn = |m: &str| warnings.borrow_mut().push(m.to_string());
+        assert_eq!(resolve_monitor_interval(None, &mut warn), "5");
+        assert_eq!(resolve_monitor_interval(Some(""), &mut warn), "5");
+        assert_eq!(resolve_monitor_interval(Some("2.5"), &mut warn), "2.5");
+        assert_eq!(resolve_monitor_interval(Some("10"), &mut warn), "10");
+        assert!(warnings.borrow().is_empty());
+        assert_eq!(resolve_monitor_interval(Some("2; rm -rf /"), &mut warn), "5");
+        assert_eq!(
+            *warnings.borrow(),
+            vec!["mcodex: invalid MCODEX_MONITOR_INTERVAL '2; rm -rf /'; using 5"]
+        );
+        assert_eq!(resolve_monitor_interval(Some("-1"), &mut warn), "5");
+        assert_eq!(resolve_monitor_interval(Some("1."), &mut warn), "5");
+    }
+
+    #[test]
+    fn tmux_history_limit_validation() {
+        let warnings = std::cell::RefCell::new(Vec::<String>::new());
+        let mut warn = |m: &str| warnings.borrow_mut().push(m.to_string());
+        assert_eq!(resolve_tmux_history_limit(None, &mut warn), "50000");
+        assert_eq!(resolve_tmux_history_limit(Some("123"), &mut warn), "123");
+        assert_eq!(resolve_tmux_history_limit(Some("1.5"), &mut warn), "50000");
+        assert_eq!(
+            *warnings.borrow(),
+            vec!["mcodex: invalid MCODEX_TMUX_HISTORY_LIMIT '1.5'; using 50000"]
+        );
+    }
+
+    #[test]
+    fn tmux_session_resolution() {
+        assert_eq!(resolve_tmux_session(None), "mcodex");
+        assert_eq!(resolve_tmux_session(Some("  ")), "mcodex");
+        assert_eq!(resolve_tmux_session(Some(" my-sess ")), "my-sess");
+    }
+
+    #[test]
+    fn watch_args_are_discrete_tokens() {
+        assert_eq!(
+            build_watch_args("2.5"),
+            v(&["-n", "2.5", "codex-multi-auth", "list"])
+        );
+    }
+
+    #[test]
+    fn session_suffix_is_hhmmss() {
+        // 18:10:42 UTC
+        let ms = ((18 * 3600 + 10 * 60 + 42) * 1000) as i64;
+        assert_eq!(format_tmux_session_suffix(ms), "181042");
+        assert_eq!(format_tmux_session_suffix(ms + 86_400_000), "181042");
+    }
+
+    #[test]
+    fn posix_tool_resolution_on_synthetic_path() {
+        let temp = tempfile::tempdir().unwrap();
+        let dir = temp.path().join("tools");
+        std::fs::create_dir_all(&dir).unwrap();
+        let name = if cfg!(windows) { "watch.exe" } else { "watch" };
+        std::fs::write(dir.join(name), "x").unwrap();
+        let found = resolve_posix_tool_on_path("watch", dir.to_str().unwrap()).unwrap();
+        assert_eq!(found, dir.join(name));
+        assert!(resolve_posix_tool_on_path("tmux", dir.to_str().unwrap()).is_none());
+        assert!(resolve_posix_tool_on_path("watch", "").is_none());
+    }
+}
diff --git a/crates/wrapper/src/routing.rs b/crates/wrapper/src/routing.rs
new file mode 100644
index 000000000..7981236a2
--- /dev/null
+++ b/crates/wrapper/src/routing.rs
@@ -0,0 +1,457 @@
+//! Port of `scripts/codex-routing.js` plus the forwarded-arg scanning helpers
+//! from `scripts/codex.js` (auth-family classification and runtime-routing
+//! decisions). Pure functions only — no I/O, no env reads.
+//!
+//! Spec: 14-docs-tests.md §2.1 (wrapper behavior contract).
+
+/// TS `AUTH_SUBCOMMANDS` — the account-manager command families the wrapper
+/// treats as "auth" (handled locally instead of forwarded to official Codex).
+pub const AUTH_SUBCOMMANDS: &[&str] = &[
+    "login",
+    "list",
+    "status",
+    "switch",
+    "unpin",
+    "workspace",
+    "best",
+    "check",
+    "features",
+    "usage",
+    "verify-flagged",
+    "verify",
+    "forecast",
+    "report",
+    "fix",
+    "doctor",
+    "uninstall",
+    "account",
+    "budget",
+    "bridge",
+    "integrations",
+    "models",
+    "monitor",
+    "rotation",
+    "why-selected",
+    "history",
+    "config",
+    "init-config",
+    "debug",
+];
+
+/// Membership test over [`AUTH_SUBCOMMANDS`].
+pub fn is_auth_subcommand(name: &str) -> bool {
+    AUTH_SUBCOMMANDS.contains(&name)
+}
+
+/// TS `normalizeAuthAlias(args)` — rewrites the compatibility spellings
+/// `codex multi auth …`, `codex multi-auth …`, `codex multiauth …` into
+/// `auth …`.
+pub fn normalize_auth_alias(args: &[String]) -> Vec<String> {
+    if args.len() >= 2 && args[0] == "multi" && args[1] == "auth" {
+        let mut out = Vec::with_capacity(args.len() - 1);
+        out.push("auth".to_string());
+        out.extend(args[2..].iter().cloned());
+        return out;
+    }
+    if !args.is_empty() && (args[0] == "multi-auth" || args[0] == "multiauth") {
+        let mut out = Vec::with_capacity(args.len());
+        out.push("auth".to_string());
+        out.extend(args[1..].iter().cloned());
+        return out;
+    }
+    args.to_vec()
+}
+
+/// TS `shouldHandleMultiAuthAuth(args)` — true when the (normalized) args are
+/// an auth-family invocation the local manager should handle:
+/// `auth` alone, `auth -<flag>…`, or `auth <known subcommand>`.
+pub fn should_handle_multi_auth_auth(args: &[String]) -> bool {
+    if args.first().map(String::as_str) != Some("auth") {
+        return false;
+    }
+    if args.len() == 1 {
+        return true;
+    }
+    let subcommand = &args[1];
+    if subcommand.starts_with('-') {
+        return true;
+    }
+    is_auth_subcommand(subcommand)
+}
+
+/// TS `isPureHelpOrVersionArgs(rawArgs)` — non-empty and EVERY arg is one of
+/// `--help`, `-h`, `--version`, `-V`.
+pub fn is_pure_help_or_version_args(raw_args: &[String]) -> bool {
+    if raw_args.is_empty() {
+        return false;
+    }
+    raw_args
+        .iter()
+        .all(|arg| matches!(arg.as_str(), "--help" | "-h" | "--version" | "-V"))
+}
+
+/// TS `consumesNextArg(arg)` — flags of official Codex that take a following
+/// value (so the forwarded-command scan can skip it).
+pub fn consumes_next_arg(arg: &str) -> bool {
+    matches!(
+        arg,
+        "-c" | "--config"
+            | "--enable"
+            | "--disable"
+            | "--listen"
+            | "--remote"
+            | "--remote-auth-token-env"
+            | "--ws-auth"
+            | "--ws-token-file"
+            | "--ws-token-sha256"
+            | "--ws-shared-secret-file"
+            | "--ws-issuer"
+            | "--ws-audience"
+            | "--ws-max-clock-skew-seconds"
+            | "--download-url"
+            | "-i"
+            | "--image"
+            | "-m"
+            | "--model"
+            | "--local-provider"
+            | "-p"
+            | "--profile"
+            | "-s"
+            | "--sandbox"
+            | "-a"
+            | "--ask-for-approval"
+            | "-C"
+            | "--cd"
+            | "--add-dir"
+            | "--output-schema"
+            | "--color"
+            | "-o"
+            | "--output-last-message"
+    )
+}
+
+/// Result of [`find_forwarded_command`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ForwardedCommand {
+    pub command: String,
+    pub index: usize,
+}
+
+/// TS `findForwardedCommand(rawArgs)` — first positional token (skipping
+/// value-consuming flags); `--` promotes the NEXT token to the command.
+pub fn find_forwarded_command(raw_args: &[String]) -> Option<ForwardedCommand> {
+    if raw_args.is_empty() {
+        return None;
+    }
+    let mut i = 0usize;
+    while i < raw_args.len() {
+        let arg = raw_args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--" {
+            return if i + 1 < raw_args.len() {
+                Some(ForwardedCommand {
+                    command: raw_args[i + 1].clone(),
+                    index: i + 1,
+                })
+            } else {
+                None
+            };
+        }
+        if arg.starts_with("--config=") {
+            i += 1;
+            continue;
+        }
+        if arg.starts_with("--") || (arg.starts_with('-') && arg != "-") {
+            if consumes_next_arg(arg) {
+                i += 1;
+            }
+            i += 1;
+            continue;
+        }
+        return Some(ForwardedCommand {
+            command: arg.to_string(),
+            index: i,
+        });
+    }
+    None
+}
+
+/// TS `findForwardedSubcommand(rawArgs, commandIndex)`.
+pub fn find_forwarded_subcommand(raw_args: &[String], command_index: usize) -> Option<String> {
+    let mut i = command_index + 1;
+    while i < raw_args.len() {
+        let arg = raw_args[i].as_str();
+        if arg.is_empty() {
+            i += 1;
+            continue;
+        }
+        if arg == "--" {
+            return if i + 1 < raw_args.len() {
+                Some(raw_args[i + 1].clone())
+            } else {
+                None
+            };
+        }
+        if arg.starts_with("--config=") {
+            i += 1;
+            continue;
+        }
+        if arg.starts_with("--") || (arg.starts_with('-') && arg != "-") {
+            if consumes_next_arg(arg) {
+                i += 1;
+            }
+            i += 1;
+            continue;
+        }
+        return Some(arg.to_string());
+    }
+    None
+}
+
+/// TS `hasHelpFlagAfterCommand(rawArgs, commandIndex)`.
+pub fn has_help_flag_after_command(raw_args: &[String], command_index: usize) -> bool {
+    let mut i = command_index + 1;
+    while i < raw_args.len() {
+        let arg = raw_args[i].as_str();
+        if arg == "--" {
+            return false;
+        }
+        if arg == "--help" || arg == "-h" || arg == "help" {
+            return true;
+        }
+        if consumes_next_arg(arg) {
+            i += 1;
+        }
+        i += 1;
+    }
+    false
+}
+
+/// TS `isCodexAppCommand(rawArgs)`.
+pub fn is_codex_app_command(raw_args: &[String]) -> bool {
+    find_forwarded_command(raw_args).is_some_and(|c| c.command == "app")
+}
+
+/// TS `isCodexAppServerCommand(rawArgs)`.
+pub fn is_codex_app_server_command(raw_args: &[String]) -> bool {
+    find_forwarded_command(raw_args).is_some_and(|c| c.command == "app-server")
+}
+
+/// TS `isCodexInteractiveTuiCommand(rawArgs)` — no positional command at all.
+pub fn is_codex_interactive_tui_command(raw_args: &[String]) -> bool {
+    find_forwarded_command(raw_args).is_none()
+}
+
+/// TS `shouldUseRuntimeRoutingForForwardedArgs(rawArgs)` — decides whether the
+/// runtime rotation proxy applies to this forwarded invocation.
+pub fn should_use_runtime_routing_for_forwarded_args(raw_args: &[String]) -> bool {
+    if raw_args.is_empty() {
+        return true;
+    }
+    if is_pure_help_or_version_args(raw_args) {
+        return false;
+    }
+
+    let Some(command) = find_forwarded_command(raw_args) else {
+        return true;
+    };
+
+    if command.command == "app-server" {
+        if has_help_flag_after_command(raw_args, command.index) {
+            return false;
+        }
+        let subcommand = find_forwarded_subcommand(raw_args, command.index);
+        return !matches!(
+            subcommand.as_deref(),
+            Some("help") | Some("generate-ts") | Some("generate-json-schema")
+        );
+    }
+
+    if command.command == "app" && has_help_flag_after_command(raw_args, command.index) {
+        return false;
+    }
+    // Request-shaped commands route through the proxy.
+    if matches!(
+        command.command.as_str(),
+        "exec" | "review" | "resume" | "fork" | "app"
+    ) {
+        return true;
+    }
+    // Non-request commands never need it.
+    if matches!(
+        command.command.as_str(),
+        "help"
+            | "completion"
+            | "login"
+            | "logout"
+            | "mcp"
+            | "mcp-server"
+            | "sandbox"
+            | "debug"
+            | "apply"
+            | "cloud"
+            | "features"
+            | "auth"
+    ) {
+        return false;
+    }
+    true
+}
+
+/// TS `shouldTrackForwardedRuntimeObservability(rawArgs)` — same predicate.
+pub fn should_track_forwarded_runtime_observability(raw_args: &[String]) -> bool {
+    should_use_runtime_routing_for_forwarded_args(raw_args)
+}
+
+/// TS `isRotationEnableCommand(args)` — `auth rotation enable` (post-normalize).
+pub fn is_rotation_enable_command(args: &[String]) -> bool {
+    args.first().map(String::as_str) == Some("auth")
+        && args.get(1).map(String::as_str) == Some("rotation")
+        && args.get(2).map(String::as_str) == Some("enable")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn v(args: &[&str]) -> Vec<String> {
+        args.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn normalize_auth_alias_rewrites_multi_auth_forms() {
+        assert_eq!(
+            normalize_auth_alias(&v(&["multi", "auth", "status"])),
+            v(&["auth", "status"])
+        );
+        assert_eq!(
+            normalize_auth_alias(&v(&["multi-auth", "login"])),
+            v(&["auth", "login"])
+        );
+        assert_eq!(normalize_auth_alias(&v(&["multiauth"])), v(&["auth"]));
+        // "multi" alone is NOT an alias.
+        assert_eq!(normalize_auth_alias(&v(&["multi"])), v(&["multi"]));
+        // untouched otherwise
+        assert_eq!(normalize_auth_alias(&v(&["exec", "hi"])), v(&["exec", "hi"]));
+    }
+
+    #[test]
+    fn should_handle_auth_family_detection() {
+        assert!(should_handle_multi_auth_auth(&v(&["auth"])));
+        assert!(should_handle_multi_auth_auth(&v(&["auth", "--json"])));
+        assert!(should_handle_multi_auth_auth(&v(&["auth", "login"])));
+        assert!(should_handle_multi_auth_auth(&v(&["auth", "rotation", "enable"])));
+        // unknown subcommand forwards to official codex (`codex auth ...` upstream surface)
+        assert!(!should_handle_multi_auth_auth(&v(&["auth", "whoami"])));
+        assert!(!should_handle_multi_auth_auth(&v(&["exec"])));
+        assert!(!should_handle_multi_auth_auth(&v(&[])));
+    }
+
+    #[test]
+    fn auth_subcommand_set_has_29_entries() {
+        assert_eq!(AUTH_SUBCOMMANDS.len(), 29);
+        assert!(is_auth_subcommand("why-selected"));
+        assert!(!is_auth_subcommand("app"));
+    }
+
+    #[test]
+    fn pure_help_or_version() {
+        assert!(is_pure_help_or_version_args(&v(&["--help"])));
+        assert!(is_pure_help_or_version_args(&v(&["-V", "--version"])));
+        assert!(!is_pure_help_or_version_args(&v(&[])));
+        assert!(!is_pure_help_or_version_args(&v(&["--help", "exec"])));
+    }
+
+    #[test]
+    fn find_forwarded_command_skips_flag_values() {
+        assert_eq!(
+            find_forwarded_command(&v(&["-m", "gpt-5.5", "exec", "task"])),
+            Some(ForwardedCommand {
+                command: "exec".into(),
+                index: 2
+            })
+        );
+        assert_eq!(
+            find_forwarded_command(&v(&["--config=a=b", "review"])),
+            Some(ForwardedCommand {
+                command: "review".into(),
+                index: 1
+            })
+        );
+        assert_eq!(
+            find_forwarded_command(&v(&["--", "exec"])),
+            Some(ForwardedCommand {
+                command: "exec".into(),
+                index: 1
+            })
+        );
+        assert_eq!(find_forwarded_command(&v(&["--"])), None);
+        assert_eq!(find_forwarded_command(&v(&["-m", "gpt"])), None);
+        assert_eq!(find_forwarded_command(&v(&[])), None);
+    }
+
+    #[test]
+    fn runtime_routing_decisions() {
+        // interactive TUI (no positional) routes
+        assert!(should_use_runtime_routing_for_forwarded_args(&v(&[])));
+        assert!(should_use_runtime_routing_for_forwarded_args(&v(&["-m", "gpt-5.5"])));
+        // help/version never route
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&["--help"])));
+        // request commands route
+        for cmd in ["exec", "review", "resume", "fork", "app"] {
+            assert!(should_use_runtime_routing_for_forwarded_args(&v(&[cmd])), "{cmd}");
+        }
+        // non-request commands do not
+        for cmd in [
+            "help",
+            "completion",
+            "login",
+            "logout",
+            "mcp",
+            "mcp-server",
+            "sandbox",
+            "debug",
+            "apply",
+            "cloud",
+            "features",
+            "auth",
+        ] {
+            assert!(!should_use_runtime_routing_for_forwarded_args(&v(&[cmd])), "{cmd}");
+        }
+        // unknown commands default to routing
+        assert!(should_use_runtime_routing_for_forwarded_args(&v(&["something-new"])));
+        // app-server special cases
+        assert!(should_use_runtime_routing_for_forwarded_args(&v(&["app-server"])));
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&[
+            "app-server",
+            "generate-ts"
+        ])));
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&[
+            "app-server",
+            "generate-json-schema"
+        ])));
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&["app-server", "help"])));
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&["app-server", "--help"])));
+        // app --help does not route
+        assert!(!should_use_runtime_routing_for_forwarded_args(&v(&["app", "--help"])));
+    }
+
+    #[test]
+    fn app_command_detection() {
+        assert!(is_codex_app_command(&v(&["app"])));
+        assert!(is_codex_app_server_command(&v(&["app-server"])));
+        assert!(!is_codex_app_command(&v(&["exec"])));
+        assert!(is_codex_interactive_tui_command(&v(&["-m", "x"])));
+        assert!(!is_codex_interactive_tui_command(&v(&["exec"])));
+    }
+
+    #[test]
+    fn rotation_enable_detection() {
+        assert!(is_rotation_enable_command(&v(&["auth", "rotation", "enable"])));
+        assert!(!is_rotation_enable_command(&v(&["auth", "rotation", "disable"])));
+        assert!(!is_rotation_enable_command(&v(&["rotation", "enable"])));
+    }
+}
diff --git a/crates/wrapper/src/shadow_home.rs b/crates/wrapper/src/shadow_home.rs
new file mode 100644
index 000000000..cb752fcf2
--- /dev/null
+++ b/crates/wrapper/src/shadow_home.rs
@@ -0,0 +1,2085 @@
+//! Shadow `CODEX_HOME` lifecycle — port of the shadow-home half of
+//! `scripts/codex.js`.
+//!
+//! A per-run temp home is mirrored from the real Codex home; the official
+//! state files (`auth.json`, `accounts.json`, `.codex-global-state.json`) are
+//! synced BACK to the real home before cleanup (guarded by a cross-process
+//! lock + external-edit detection), and the shadow directory is removed after
+//! the owning run exits. Runtime-rotation shadow homes additionally OMIT the
+//! official auth state (the proxy owns auth) and link-rather-than-copy the
+//! heavyweight generated directories.
+
+use std::collections::{HashMap, HashSet};
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicI64, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::Duration;
+
+use cma_storage::misc::compute_sha256;
+
+/// Retryable codes for shadow-home cleanup/rename (TS
+/// `RETRYABLE_SHADOW_HOME_CLEANUP_CODES`).
+pub const RETRYABLE_SHADOW_HOME_CLEANUP_CODES: &[&str] = &["EBUSY", "EPERM", "ENOTEMPTY"];
+/// TS `SHADOW_HOME_CLEANUP_BACKOFF_MS`.
+pub const SHADOW_HOME_CLEANUP_BACKOFF_MS: &[u64] = &[20, 60, 120];
+/// TS `SHADOW_HOME_ORPHAN_LOCK_STALE_AGE_MS`.
+pub const SHADOW_HOME_ORPHAN_LOCK_STALE_AGE_MS: i64 = 2_000;
+/// TS `SHADOW_HOME_SYNC_LOCK_WAIT_TIMEOUT_MS` = stale age + Σ backoff.
+pub const SHADOW_HOME_SYNC_LOCK_WAIT_TIMEOUT_MS: i64 = SHADOW_HOME_ORPHAN_LOCK_STALE_AGE_MS + 200;
+/// TS `SHADOW_HOME_STATE_FILES` — synced back after every run.
+pub const SHADOW_HOME_STATE_FILES: &[&str] =
+    &["auth.json", "accounts.json", ".codex-global-state.json"];
+/// TS `RUNTIME_ROTATION_SHADOW_HOME_OMIT_STATE_FILES`.
+pub const RUNTIME_ROTATION_SHADOW_HOME_OMIT_STATE_FILES: &[&str] = &["auth.json", "accounts.json"];
+/// TS `RUNTIME_ROTATION_SHADOW_HOME_OMIT_ROOT_DIRS`.
+pub const RUNTIME_ROTATION_SHADOW_HOME_OMIT_ROOT_DIRS: &[&str] = &["multi-auth"];
+/// TS `RUNTIME_ROTATION_SHADOW_HOME_LINK_ONLY_ROOT_DIRS`.
+pub const RUNTIME_ROTATION_SHADOW_HOME_LINK_ONLY_ROOT_DIRS: &[&str] = &[
+    ".sandbox",
+    ".sandbox-bin",
+    ".sandbox-secrets",
+    ".tmp",
+    "ambient-suggestions",
+    "archived_sessions",
+    "backups",
+    "cache",
+    "generated_images",
+    "log",
+    "sqlite",
+    "tmp",
+    "understand-anything",
+    "vendor_imports",
+];
+/// TS `SHADOW_HOME_CONFIG_FILE`.
+pub const SHADOW_HOME_CONFIG_FILE: &str = "config.toml";
+/// TS `SHADOW_HOME_SYNC_LOCK_DIR`.
+pub const SHADOW_HOME_SYNC_LOCK_DIR: &str = ".codex-multi-auth-shadow-sync.lock";
+/// TS `SHADOW_HOME_SYNC_STATE_FILE`.
+pub const SHADOW_HOME_SYNC_STATE_FILE: &str = ".codex-multi-auth-shadow-sync-state.json";
+
+// ---------------------------------------------------------------------------
+// Test fault-injection hooks (TS module-level counters seeded from env).
+// ---------------------------------------------------------------------------
+
+fn env_counter(name: &str) -> AtomicI64 {
+    let value = std::env::var(name)
+        .ok()
+        .and_then(|raw| raw.trim().parse::<i64>().ok())
+        .unwrap_or(0);
+    AtomicI64::new(value)
+}
+
+fn cleanup_busy_failures() -> &'static AtomicI64 {
+    static CELL: OnceLock<AtomicI64> = OnceLock::new();
+    CELL.get_or_init(|| env_counter("CODEX_MULTI_AUTH_TEST_SHADOW_CLEANUP_BUSY_FAILURES"))
+}
+
+fn preflight_read_busy_failures() -> &'static AtomicI64 {
+    static CELL: OnceLock<AtomicI64> = OnceLock::new();
+    CELL.get_or_init(|| env_counter("CODEX_MULTI_AUTH_TEST_SHADOW_PREFLIGHT_READ_BUSY_FAILURES"))
+}
+
+fn sync_metadata_busy_failures() -> &'static AtomicI64 {
+    static CELL: OnceLock<AtomicI64> = OnceLock::new();
+    CELL.get_or_init(|| env_counter("CODEX_MULTI_AUTH_TEST_SHADOW_SYNC_METADATA_BUSY_FAILURES"))
+}
+
+fn lock_owner_write_failures() -> &'static AtomicI64 {
+    static CELL: OnceLock<AtomicI64> = OnceLock::new();
+    CELL.get_or_init(|| env_counter("CODEX_MULTI_AUTH_TEST_SHADOW_LOCK_OWNER_WRITE_FAILURES"))
+}
+
+fn take_injected_failure(counter: &AtomicI64) -> bool {
+    loop {
+        let current = counter.load(Ordering::SeqCst);
+        if current <= 0 {
+            return false;
+        }
+        if counter
+            .compare_exchange(current, current - 1, Ordering::SeqCst, Ordering::SeqCst)
+            .is_ok()
+        {
+            return true;
+        }
+    }
+}
+
+fn busy_error(message: &str) -> io::Error {
+    cma_core::fs_retry::io_error_with_code("EBUSY", message.to_string())
+}
+
+fn maybe_simulated_cleanup_busy() -> io::Result<()> {
+    if take_injected_failure(cleanup_busy_failures()) {
+        return Err(busy_error("simulated busy shadow-home operation"));
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Warn-once registries (TS module-level flags/sets).
+// ---------------------------------------------------------------------------
+
+fn warned_set() -> &'static Mutex<HashSet<String>> {
+    static CELL: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+    CELL.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+fn warn_once_keyed(key: String, message: String) {
+    let mut guard = warned_set().lock().expect("shadow-home warn set poisoned");
+    if guard.insert(key) {
+        eprintln!("{message}");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Retry primitives.
+// ---------------------------------------------------------------------------
+
+fn error_code_of(error: &io::Error) -> Option<&'static str> {
+    cma_core::fs_retry::code_of(error)
+}
+
+/// TS `isRetryableShadowHomeCleanupError`.
+pub fn is_retryable_shadow_home_cleanup_error(error: &io::Error) -> bool {
+    matches!(error_code_of(error), Some(code) if RETRYABLE_SHADOW_HOME_CLEANUP_CODES.contains(&code))
+}
+
+fn sleep_sync(ms: u64) {
+    if ms > 0 {
+        std::thread::sleep(Duration::from_millis(ms));
+    }
+}
+
+/// TS `removeDirectoryWithRetry(targetPath)` — `rmSync(recursive, force)` with
+/// EBUSY/EPERM/ENOTEMPTY backoff 20/60/120 ms.
+pub fn remove_directory_with_retry(target_path: &Path) -> io::Result<()> {
+    let mut attempt = 0usize;
+    loop {
+        let result = maybe_simulated_cleanup_busy().and_then(|()| {
+            match fs::remove_dir_all(target_path) {
+                Ok(()) => Ok(()),
+                // force:true semantics — missing target is success.
+                Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(()),
+                Err(e) => {
+                    // Non-directory targets: force-remove the file.
+                    if target_path.is_file() {
+                        match fs::remove_file(target_path) {
+                            Ok(()) => Ok(()),
+                            Err(e2) if e2.kind() == io::ErrorKind::NotFound => Ok(()),
+                            Err(e2) => Err(e2),
+                        }
+                    } else {
+                        Err(e)
+                    }
+                }
+            }
+        });
+        match result {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if !is_retryable_shadow_home_cleanup_error(&error)
+                    || attempt == SHADOW_HOME_CLEANUP_BACKOFF_MS.len()
+                {
+                    return Err(error);
+                }
+                sleep_sync(SHADOW_HOME_CLEANUP_BACKOFF_MS[attempt]);
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// TS `removeDirectoryBestEffortAsync` — best-effort removal that never blocks
+/// the caller (detached thread; failures reclaimed by stale-lock recovery).
+pub fn remove_directory_best_effort_detached(target_path: PathBuf) {
+    std::thread::spawn(move || {
+        for _ in 0..4 {
+            match fs::remove_dir_all(&target_path) {
+                Ok(()) => return,
+                Err(e) if e.kind() == io::ErrorKind::NotFound => return,
+                Err(_) => sleep_sync(20),
+            }
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// File state snapshots.
+// ---------------------------------------------------------------------------
+
+/// TS `captureShadowHomeState` result.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ShadowFileState {
+    pub exists: bool,
+    pub content: Option<String>,
+    pub unreadable: bool,
+}
+
+impl ShadowFileState {
+    pub fn missing() -> Self {
+        Self {
+            exists: false,
+            content: None,
+            unreadable: false,
+        }
+    }
+}
+
+/// TS `captureShadowHomeState(filePath)` (non-rethrowing form).
+pub fn capture_shadow_home_state(file_path: &Path) -> ShadowFileState {
+    capture_shadow_home_state_inner(file_path, false).unwrap_or(ShadowFileState {
+        exists: true,
+        content: None,
+        unreadable: true,
+    })
+}
+
+/// TS `captureShadowHomeState(filePath, { rethrowRetryableReadErrors: true })`.
+pub fn capture_shadow_home_state_rethrow(file_path: &Path) -> io::Result<ShadowFileState> {
+    capture_shadow_home_state_inner(file_path, true)
+}
+
+fn capture_shadow_home_state_inner(
+    file_path: &Path,
+    rethrow_retryable: bool,
+) -> io::Result<ShadowFileState> {
+    if !file_path.exists() {
+        return Ok(ShadowFileState::missing());
+    }
+    if rethrow_retryable && take_injected_failure(preflight_read_busy_failures()) {
+        return Err(busy_error("simulated busy shadow-home preflight read"));
+    }
+    match fs::read(file_path) {
+        Ok(bytes) => Ok(ShadowFileState {
+            exists: true,
+            content: Some(String::from_utf8_lossy(&bytes).into_owned()),
+            unreadable: false,
+        }),
+        Err(error) => {
+            if rethrow_retryable && is_retryable_shadow_home_cleanup_error(&error) {
+                return Err(error);
+            }
+            Ok(ShadowFileState {
+                exists: true,
+                content: None,
+                unreadable: true,
+            })
+        }
+    }
+}
+
+/// TS `shadowHomeStateMatches(left, right)`.
+pub fn shadow_home_state_matches(left: &ShadowFileState, right: &ShadowFileState) -> bool {
+    left.exists == right.exists
+        && left.content == right.content
+        && left.unreadable == right.unreadable
+}
+
+/// TS `hashShadowHomeState(state)` — `None` for unreadable / non-string,
+/// `"missing"` for absent files, else `sha256:<hex>` of the content.
+pub fn hash_shadow_home_state(state: &ShadowFileState) -> Option<String> {
+    if state.unreadable {
+        return None;
+    }
+    if !state.exists {
+        return Some("missing".to_string());
+    }
+    state
+        .content
+        .as_ref()
+        .map(|content| format!("sha256:{}", compute_sha256(content)))
+}
+
+// ---------------------------------------------------------------------------
+// Sync-state metadata (`.codex-multi-auth-shadow-sync-state.json`).
+// ---------------------------------------------------------------------------
+
+/// TS `readShadowHomeSyncState(originalCodexHome)` — tolerant `{version:1,
+/// files:{}}` fallback.
+pub fn read_shadow_home_sync_state(original_codex_home: &Path) -> serde_json::Value {
+    let path = original_codex_home.join(SHADOW_HOME_SYNC_STATE_FILE);
+    let fallback = serde_json::json!({ "version": 1, "files": {} });
+    let Ok(raw) = fs::read_to_string(&path) else {
+        return fallback;
+    };
+    let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&raw) else {
+        return fallback;
+    };
+    let valid = parsed.is_object()
+        && parsed.get("version").and_then(serde_json::Value::as_i64) == Some(1)
+        && parsed.get("files").is_some_and(serde_json::Value::is_object);
+    if valid { parsed } else { fallback }
+}
+
+/// TS `rememberShadowHomeSyncState` — records `{baseHash, syncedHash,
+/// updatedAt}` for `name`; silently skipped when either hash is unavailable
+/// or the metadata write fails.
+pub fn remember_shadow_home_sync_state(
+    original_codex_home: &Path,
+    sync_state: &mut serde_json::Value,
+    name: &str,
+    base_state: &ShadowFileState,
+    synced_state: &ShadowFileState,
+) {
+    let (Some(base_hash), Some(synced_hash)) = (
+        hash_shadow_home_state(base_state),
+        hash_shadow_home_state(synced_state),
+    ) else {
+        return;
+    };
+    if let Some(files) = sync_state
+        .get_mut("files")
+        .and_then(serde_json::Value::as_object_mut)
+    {
+        files.insert(
+            name.to_string(),
+            serde_json::json!({
+                "baseHash": base_hash,
+                "syncedHash": synced_hash,
+                "updatedAt": cma_core::utils::now_ms(),
+            }),
+        );
+    }
+    let _ = write_owner_only_json_file_atomic_sync(
+        &original_codex_home.join(SHADOW_HOME_SYNC_STATE_FILE),
+        sync_state,
+    );
+}
+
+/// TS `canRebaseShadowHomeSyncState` — permit a later shadow session to write
+/// over an earlier shadow sync from the same launch snapshot.
+pub fn can_rebase_shadow_home_sync_state(
+    sync_state: &serde_json::Value,
+    name: &str,
+    base_state: &ShadowFileState,
+    current_state: &ShadowFileState,
+) -> bool {
+    let Some(entry) = sync_state
+        .get("files")
+        .and_then(|files| files.get(name))
+        .filter(|entry| entry.is_object())
+    else {
+        return false;
+    };
+    entry.get("baseHash").and_then(serde_json::Value::as_str)
+        == hash_shadow_home_state(base_state).as_deref()
+        && entry.get("syncedHash").and_then(serde_json::Value::as_str)
+            == hash_shadow_home_state(current_state).as_deref()
+}
+
+// ---------------------------------------------------------------------------
+// Owner-only atomic JSON writer (TS `writeOwnerOnlyJsonFileAtomicSync`).
+// ---------------------------------------------------------------------------
+
+fn tighten_file_permissions(path: &Path) {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = fs::set_permissions(path, fs::Permissions::from_mode(0o600));
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path; // Node parity: chmod is best-effort/no-op on Windows.
+    }
+}
+
+/// TS `writeOwnerOnlyJsonFileAtomicSync(targetPath, payload)` —
+/// `JSON.stringify(payload, null, 2) + "\n"`, 0600, temp+rename with
+/// EBUSY/EPERM/ENOTEMPTY backoff 20/60/120.
+pub fn write_owner_only_json_file_atomic_sync(
+    target_path: &Path,
+    payload: &serde_json::Value,
+) -> io::Result<()> {
+    let target_dir = target_path
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| PathBuf::from("."));
+    fs::create_dir_all(&target_dir)?;
+    let base_name = target_path
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("payload.json");
+    let serialized = format!("{}\n", cma_core::json_io::stringify_pretty2(payload));
+    let mut attempt = 0usize;
+    loop {
+        let temp_path = target_dir.join(format!(
+            ".{base_name}.{}.{}.{}.tmp",
+            std::process::id(),
+            cma_core::utils::now_ms(),
+            random_hex(8),
+        ));
+        let result = (|| -> io::Result<()> {
+            fs::write(&temp_path, serialized.as_bytes())?;
+            tighten_file_permissions(&temp_path);
+            if take_injected_failure(sync_metadata_busy_failures())
+                && target_path
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .is_some_and(|n| n == SHADOW_HOME_SYNC_STATE_FILE)
+            {
+                return Err(busy_error("simulated busy shadow-home sync metadata write"));
+            }
+            fs::rename(&temp_path, target_path)?;
+            tighten_file_permissions(target_path);
+            Ok(())
+        })();
+        match result {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                let _ = fs::remove_file(&temp_path);
+                if is_retryable_shadow_home_cleanup_error(&error)
+                    && attempt < SHADOW_HOME_CLEANUP_BACKOFF_MS.len()
+                {
+                    sleep_sync(SHADOW_HOME_CLEANUP_BACKOFF_MS[attempt]);
+                    attempt += 1;
+                    continue;
+                }
+                return Err(error);
+            }
+        }
+    }
+}
+
+fn random_hex(bytes: usize) -> String {
+    use rand::RngCore;
+    let mut buf = vec![0u8; bytes / 2];
+    rand::rng().fill_bytes(&mut buf);
+    buf.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+// ---------------------------------------------------------------------------
+// Sync lock (`.codex-multi-auth-shadow-sync.lock` directory + owner.json).
+// ---------------------------------------------------------------------------
+
+fn read_shadow_home_sync_lock_owner_pid(lock_path: &Path) -> Option<i64> {
+    let raw = fs::read_to_string(lock_path.join("owner.json")).ok()?;
+    let value: serde_json::Value = serde_json::from_str(&raw).ok()?;
+    let pid = value.get("pid")?.as_i64()?;
+    if pid > 0 { Some(pid) } else { None }
+}
+
+fn is_shadow_home_sync_lock_old_enough_to_steal(lock_path: &Path) -> bool {
+    match fs::metadata(lock_path) {
+        Ok(meta) => {
+            let newest = meta
+                .modified()
+                .ok()
+                .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
+                .map(|d| d.as_millis() as i64)
+                .unwrap_or(0);
+            cma_core::utils::now_ms() - newest >= SHADOW_HOME_ORPHAN_LOCK_STALE_AGE_MS
+        }
+        Err(_) => true,
+    }
+}
+
+fn remove_stale_shadow_home_sync_lock(lock_path: &Path) -> bool {
+    let owner_pid = read_shadow_home_sync_lock_owner_pid(lock_path);
+    if let Some(pid) = owner_pid
+        && cma_runtime::app_bind::is_process_alive(Some(pid))
+    {
+        return false;
+    }
+    if owner_pid.is_none() && !is_shadow_home_sync_lock_old_enough_to_steal(lock_path) {
+        return false;
+    }
+    remove_directory_with_retry(lock_path).is_ok()
+}
+
+fn write_shadow_home_sync_lock_owner(lock_path: &Path, pid: u32) -> io::Result<()> {
+    if take_injected_failure(lock_owner_write_failures()) {
+        return Err(cma_core::fs_retry::io_error_with_code(
+            "EPERM",
+            "simulated shadow sync lock owner write failure".to_string(),
+        ));
+    }
+    let owner_path = lock_path.join("owner.json");
+    let payload = serde_json::json!({ "pid": pid, "createdAt": cma_core::utils::now_ms() });
+    fs::write(
+        &owner_path,
+        format!("{}\n", cma_core::json_io::stringify_compact(&payload)),
+    )?;
+    tighten_file_permissions(&owner_path);
+    Ok(())
+}
+
+fn write_shadow_home_sync_lock_owner_with_retry(lock_path: &Path, pid: u32) -> io::Result<()> {
+    let mut attempt = 0usize;
+    loop {
+        match write_shadow_home_sync_lock_owner(lock_path, pid) {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if !is_retryable_shadow_home_cleanup_error(&error)
+                    || attempt == SHADOW_HOME_CLEANUP_BACKOFF_MS.len()
+                {
+                    return Err(error);
+                }
+                sleep_sync(SHADOW_HOME_CLEANUP_BACKOFF_MS[attempt]);
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// Held sync lock; released (best-effort) on [`ShadowHomeSyncLock::release`]
+/// or drop.
+pub struct ShadowHomeSyncLock {
+    lock_path: Option<PathBuf>,
+}
+
+impl ShadowHomeSyncLock {
+    pub fn release(mut self) {
+        self.release_inner();
+    }
+
+    fn release_inner(&mut self) {
+        if let Some(path) = self.lock_path.take() {
+            let _ = remove_directory_with_retry(&path);
+        }
+    }
+}
+
+impl Drop for ShadowHomeSyncLock {
+    fn drop(&mut self) {
+        self.release_inner();
+    }
+}
+
+/// TS `acquireShadowHomeSyncLock(originalCodexHome)` — `mkdir` claim with
+/// owner.json, stale-lock takeover, bounded wait (deadline = stale age + Σ
+/// backoff), then error.
+pub fn acquire_shadow_home_sync_lock(original_codex_home: &Path) -> io::Result<ShadowHomeSyncLock> {
+    let lock_path = original_codex_home.join(SHADOW_HOME_SYNC_LOCK_DIR);
+    fs::create_dir_all(original_codex_home)?;
+    let max_stale_recoveries = SHADOW_HOME_CLEANUP_BACKOFF_MS.len() + 1;
+    let mut stale_recoveries = 0usize;
+    let mut attempt = 0usize;
+    let deadline = cma_core::utils::now_ms() + SHADOW_HOME_SYNC_LOCK_WAIT_TIMEOUT_MS;
+    loop {
+        match fs::create_dir(&lock_path) {
+            Ok(()) => {
+                if let Err(error) =
+                    write_shadow_home_sync_lock_owner_with_retry(&lock_path, std::process::id())
+                {
+                    let _ = remove_directory_with_retry(&lock_path);
+                    return Err(error);
+                }
+                return Ok(ShadowHomeSyncLock {
+                    lock_path: Some(lock_path),
+                });
+            }
+            Err(error) => {
+                if error.kind() != io::ErrorKind::AlreadyExists {
+                    return Err(error);
+                }
+                if stale_recoveries < max_stale_recoveries
+                    && remove_stale_shadow_home_sync_lock(&lock_path)
+                {
+                    stale_recoveries += 1;
+                    attempt = 0;
+                    continue;
+                }
+                let remaining_ms = deadline - cma_core::utils::now_ms();
+                if remaining_ms <= 0 {
+                    return Err(error);
+                }
+                let backoff_ms = SHADOW_HOME_CLEANUP_BACKOFF_MS
+                    [attempt.min(SHADOW_HOME_CLEANUP_BACKOFF_MS.len() - 1)];
+                sleep_sync(backoff_ms.min(remaining_ms as u64));
+                attempt += 1;
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// State-file sync-back.
+// ---------------------------------------------------------------------------
+
+fn ensure_destination_matches_snapshot(
+    destination_path: &Path,
+    expected_state: Option<&ShadowFileState>,
+) -> io::Result<()> {
+    let Some(expected) = expected_state else {
+        return Ok(());
+    };
+    let current = capture_shadow_home_state_rethrow(destination_path)?;
+    if !shadow_home_state_matches(&current, expected) {
+        return Err(cma_core::fs_retry::io_error_with_code(
+            "EEXIST",
+            "shadow-home destination changed during sync-back retry".to_string(),
+        ));
+    }
+    Ok(())
+}
+
+fn rename_file_with_retry(
+    source_path: &Path,
+    destination_path: &Path,
+    expected_destination_state: Option<&ShadowFileState>,
+) -> io::Result<()> {
+    let mut attempt = 0usize;
+    loop {
+        let result = ensure_destination_matches_snapshot(destination_path, expected_destination_state)
+            .and_then(|()| maybe_simulated_cleanup_busy())
+            .and_then(|()| fs::rename(source_path, destination_path));
+        match result {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                if !is_retryable_shadow_home_cleanup_error(&error)
+                    || attempt == SHADOW_HOME_CLEANUP_BACKOFF_MS.len()
+                {
+                    return Err(error);
+                }
+                sleep_sync(SHADOW_HOME_CLEANUP_BACKOFF_MS[attempt]);
+                attempt += 1;
+            }
+        }
+    }
+}
+
+/// TS `syncShadowHomeStateFile` — copy to a sibling temp then rename over the
+/// destination (with destination-change detection).
+pub fn sync_shadow_home_state_file(
+    source_path: &Path,
+    destination_path: &Path,
+    expected_destination_state: Option<&ShadowFileState>,
+) -> io::Result<()> {
+    let dest_dir = destination_path
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| PathBuf::from("."));
+    let base = destination_path
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("state");
+    let temp_path = dest_dir.join(format!(
+        ".{base}.codex-multi-auth-sync-{}.tmp",
+        std::process::id()
+    ));
+    let result = (|| -> io::Result<()> {
+        fs::create_dir_all(&dest_dir)?;
+        fs::copy(source_path, &temp_path)?;
+        rename_file_with_retry(&temp_path, destination_path, expected_destination_state)
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(&temp_path);
+    }
+    result
+}
+
+fn sync_shadow_home_state_file_best_effort(
+    source_path: &Path,
+    destination_path: &Path,
+    expected_destination_state: Option<&ShadowFileState>,
+) -> bool {
+    match sync_shadow_home_state_file(source_path, destination_path, expected_destination_state) {
+        Ok(()) => {
+            tighten_file_permissions(destination_path);
+            true
+        }
+        Err(_) => false,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Directory / file mirroring into the shadow home.
+// ---------------------------------------------------------------------------
+
+fn is_directory_like(path: &Path) -> bool {
+    fs::metadata(path).map(|m| m.is_dir()).unwrap_or(false)
+}
+
+fn is_file_like(path: &Path) -> bool {
+    fs::metadata(path).map(|m| m.is_file()).unwrap_or(false)
+}
+
+fn force_shadow_dir_copy() -> bool {
+    std::env::var("CODEX_MULTI_AUTH_TEST_FORCE_SHADOW_DIR_COPY")
+        .map(|v| v.trim() == "1")
+        .unwrap_or(false)
+}
+
+fn symlink_dir_impl(source: &Path, destination: &Path) -> io::Result<()> {
+    #[cfg(unix)]
+    {
+        std::os::unix::fs::symlink(source, destination)
+    }
+    #[cfg(windows)]
+    {
+        // Node parity: `fs.symlinkSync(source, destination, "junction")` —
+        // on win32 the JS launcher creates NTFS junctions, which need NO
+        // privilege. `std::os::windows::fs::symlink_dir` requires
+        // SeCreateSymbolicLinkPrivilege / Developer Mode and fails for a
+        // standard user, which would skip every link-only dir (sqlite,
+        // cache, …) and degrade sessions/plugins/skills to full copies.
+        // Junctions require an absolute target; the call sites pass absolute
+        // paths, but canonicalize-by-joining defensively for relative ones.
+        let absolute_source = if source.is_absolute() {
+            source.to_path_buf()
+        } else {
+            std::env::current_dir()?.join(source)
+        };
+        junction::create(&absolute_source, destination)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = (source, destination);
+        Err(io::Error::other("symlinks unsupported"))
+    }
+}
+
+fn symlink_file_impl(source: &Path, destination: &Path) -> io::Result<()> {
+    #[cfg(unix)]
+    {
+        std::os::unix::fs::symlink(source, destination)
+    }
+    #[cfg(windows)]
+    {
+        std::os::windows::fs::symlink_file(source, destination)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = (source, destination);
+        Err(io::Error::other("symlinks unsupported"))
+    }
+}
+
+fn copy_dir_recursive(source: &Path, destination: &Path) -> io::Result<()> {
+    fs::create_dir_all(destination)?;
+    for entry in fs::read_dir(source)? {
+        let entry = entry?;
+        let file_type = entry.file_type()?;
+        let from = entry.path();
+        let to = destination.join(entry.file_name());
+        if file_type.is_dir() {
+            copy_dir_recursive(&from, &to)?;
+        } else if file_type.is_symlink() {
+            // dereference:false parity — recreate the link target reference
+            // (best effort: fall back to copying the resolved file).
+            #[cfg(unix)]
+            {
+                if let Ok(target) = fs::read_link(&from) {
+                    let _ = std::os::unix::fs::symlink(&target, &to);
+                    continue;
+                }
+            }
+            if is_directory_like(&from) {
+                copy_dir_recursive(&from, &to)?;
+            } else if fs::copy(&from, &to).is_err() {
+                continue;
+            }
+        } else {
+            fs::copy(&from, &to)?;
+        }
+    }
+    Ok(())
+}
+
+/// TS `mirrorDirectoryIntoShadowHome` — link preferred, copy fallback.
+/// Returns `"linked"` or `"copied"`.
+fn mirror_directory_into_shadow_home(source: &Path, destination: &Path) -> io::Result<&'static str> {
+    if !force_shadow_dir_copy() && symlink_dir_impl(source, destination).is_ok() {
+        return Ok("linked");
+    }
+    copy_dir_recursive(source, destination)?;
+    Ok("copied")
+}
+
+fn link_directory_into_shadow_home(source: &Path, destination: &Path) -> bool {
+    !force_shadow_dir_copy() && symlink_dir_impl(source, destination).is_ok()
+}
+
+fn warn_skipped_link_only_directory(name: &str) {
+    warn_once_keyed(
+        format!("link-only-dir:{name}"),
+        format!(
+            "codex-multi-auth: skipped optional shadow-home directory {name} because linking failed; refusing to copy generated runtime data."
+        ),
+    );
+}
+
+fn should_copy_runtime_generated_dirs_fallback() -> bool {
+    let normalized = std::env::var("CODEX_MULTI_AUTH_RUNTIME_SHADOW_COPY_GENERATED_DIRS")
+        .unwrap_or_default()
+        .trim()
+        .to_ascii_lowercase();
+    normalized == "1" || normalized == "true" || normalized == "yes"
+}
+
+fn link_file_into_shadow_home(source: &Path, destination: &Path) -> bool {
+    if symlink_file_impl(source, destination).is_ok() {
+        return true;
+    }
+    fs::hard_link(source, destination).is_ok()
+}
+
+fn mirror_file_into_shadow_home(source: &Path, destination: &Path) -> io::Result<()> {
+    if link_file_into_shadow_home(source, destination) {
+        return Ok(());
+    }
+    fs::copy(source, destination)?;
+    tighten_file_permissions(destination);
+    Ok(())
+}
+
+fn is_sqlite_main_file(name: &str) -> bool {
+    name.to_ascii_lowercase().ends_with(".sqlite")
+}
+
+fn is_sqlite_sidecar_file(name: &str) -> bool {
+    let lower = name.to_ascii_lowercase();
+    lower.ends_with(".sqlite-shm") || lower.ends_with(".sqlite-wal")
+}
+
+fn normalize_runtime_entry_name(name: &str) -> String {
+    if cfg!(any(windows, target_os = "macos")) {
+        name.to_ascii_lowercase()
+    } else {
+        name.to_string()
+    }
+}
+
+fn is_codex_runtime_local_sqlite_file(name: &str) -> bool {
+    let normalized = normalize_runtime_entry_name(name);
+    let Some(rest) = normalized
+        .strip_prefix("state_")
+        .or_else(|| normalized.strip_prefix("logs_"))
+    else {
+        return false;
+    };
+    let digits_end = rest.find(|c: char| !c.is_ascii_digit()).unwrap_or(rest.len());
+    if digits_end == 0 {
+        return false;
+    }
+    matches!(
+        &rest[digits_end..],
+        ".sqlite" | ".sqlite-shm" | ".sqlite-wal"
+    )
+}
+
+fn is_codex_runtime_transient_state_file(name: &str) -> bool {
+    let normalized = normalize_runtime_entry_name(name);
+    // /^(?:auth|accounts)\.json\.\d+\.[a-z0-9]+\.tmp$/
+    for prefix in ["auth.json.", "accounts.json."] {
+        if let Some(rest) = normalized.strip_prefix(prefix)
+            && let Some(rest) = rest.strip_suffix(".tmp")
+        {
+            let mut parts = rest.splitn(2, '.');
+            let digits = parts.next().unwrap_or("");
+            let nonce = parts.next().unwrap_or("");
+            if !digits.is_empty()
+                && digits.chars().all(|c| c.is_ascii_digit())
+                && !nonce.is_empty()
+                && nonce.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
+            {
+                return true;
+            }
+        }
+    }
+    // /^\.codex-global-state\.json\.tmp-[a-z0-9-]+$/
+    if let Some(rest) = normalized.strip_prefix(".codex-global-state.json.tmp-") {
+        return !rest.is_empty()
+            && rest
+                .chars()
+                .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-');
+    }
+    false
+}
+
+/// TS `isRuntimeRotationShadowHomeOmittedEntry(name)`.
+pub fn is_runtime_rotation_shadow_home_omitted_entry(name: &str) -> bool {
+    let normalized = normalize_runtime_entry_name(name);
+    RUNTIME_ROTATION_SHADOW_HOME_OMIT_ROOT_DIRS.contains(&normalized.as_str())
+        || is_codex_runtime_local_sqlite_file(name)
+        || is_codex_runtime_transient_state_file(name)
+}
+
+/// TS `isRuntimeRotationShadowHomeLinkOnlyDirectory(name)`.
+pub fn is_runtime_rotation_shadow_home_link_only_directory(name: &str) -> bool {
+    let normalized = normalize_runtime_entry_name(name);
+    RUNTIME_ROTATION_SHADOW_HOME_LINK_ONLY_ROOT_DIRS.contains(&normalized.as_str())
+}
+
+fn should_materialize_file_into_shadow_home(name: &str) -> bool {
+    is_sqlite_main_file(name) || is_sqlite_sidecar_file(name)
+}
+
+fn warn_skipped_sqlite_materialization() {
+    warn_once_keyed(
+        "sqlite-link-failure".to_string(),
+        "codex-multi-auth: skipped SQLite shadow-home materialization because linking failed; refusing to copy active SQLite state.".to_string(),
+    );
+}
+
+fn warn_skipped_sqlite_sidecar_placeholder(error: &io::Error, destination: &Path) {
+    warn_once_keyed(
+        format!("sqlite-sidecar:{}", destination.display()),
+        format!(
+            "codex-multi-auth: skipped SQLite shadow-home sidecar placeholder for {} because linking failed: {error}",
+            destination.display()
+        ),
+    );
+}
+
+fn materialize_sqlite_sidecar_placeholder(source_sidecar: &Path, destination_sidecar: &Path) -> bool {
+    if std::env::var("CODEX_MULTI_AUTH_TEST_FORCE_SHADOW_SIDECAR_PLACEHOLDER_FAILURE")
+        .map(|v| v.trim() == "1")
+        .unwrap_or(false)
+    {
+        let error = cma_core::fs_retry::io_error_with_code(
+            "EPERM",
+            "simulated SQLite sidecar placeholder failure".to_string(),
+        );
+        warn_skipped_sqlite_sidecar_placeholder(&error, destination_sidecar);
+        return false;
+    }
+    match symlink_file_impl(source_sidecar, destination_sidecar) {
+        Ok(()) => true,
+        Err(error) if error.kind() == io::ErrorKind::AlreadyExists => true,
+        Err(error) => {
+            warn_skipped_sqlite_sidecar_placeholder(&error, destination_sidecar);
+            false
+        }
+    }
+}
+
+fn materialize_file_into_shadow_home(source: &Path, destination: &Path) -> bool {
+    let forced_sidecar_failure =
+        std::env::var("CODEX_MULTI_AUTH_TEST_FORCE_SHADOW_SQLITE_SIDECAR_LINK_FAILURE")
+            .map(|v| v.trim() == "1")
+            .unwrap_or(false)
+            && source
+                .file_name()
+                .and_then(|n| n.to_str())
+                .is_some_and(is_sqlite_sidecar_file);
+    if forced_sidecar_failure || !link_file_into_shadow_home(source, destination) {
+        warn_skipped_sqlite_materialization();
+        return false;
+    }
+    true
+}
+
+fn materialize_sqlite_sidecars_into_shadow_home(source: &Path, destination: &Path) -> bool {
+    for suffix in ["-wal", "-shm"] {
+        let source_sidecar = PathBuf::from(format!("{}{suffix}", source.display()));
+        let destination_sidecar = PathBuf::from(format!("{}{suffix}", destination.display()));
+        if destination_sidecar.exists() {
+            continue;
+        }
+        if source_sidecar.exists() {
+            if !materialize_file_into_shadow_home(&source_sidecar, &destination_sidecar)
+                && !materialize_sqlite_sidecar_placeholder(&source_sidecar, &destination_sidecar)
+            {
+                return false;
+            }
+            continue;
+        }
+        if !materialize_sqlite_sidecar_placeholder(&source_sidecar, &destination_sidecar) {
+            return false;
+        }
+    }
+    true
+}
+
+fn remove_sqlite_shadow_home_materialization(destination: &Path) {
+    for path in [
+        destination.to_path_buf(),
+        PathBuf::from(format!("{}-wal", destination.display())),
+        PathBuf::from(format!("{}-shm", destination.display())),
+    ] {
+        let _ = fs::remove_file(&path);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Mirror creation + sync-back closure.
+// ---------------------------------------------------------------------------
+
+/// Predicate type used by [`MirrorOptions`].
+pub type NamePredicate = Arc<dyn Fn(&str) -> bool + Send + Sync>;
+
+/// Options for [`create_shadow_home_mirror`] (TS `createShadowHomeMirror`
+/// options bag).
+#[derive(Clone, Default)]
+pub struct MirrorOptions {
+    pub skip_sync_back_names: Vec<String>,
+    pub skip_mirror_predicate: Option<NamePredicate>,
+    pub skip_sync_back_predicate: Option<NamePredicate>,
+    pub link_only_directory_predicate: Option<NamePredicate>,
+}
+
+impl MirrorOptions {
+    /// The runtime-rotation option set (omit official auth state, link-only
+    /// generated dirs).
+    pub fn runtime_rotation() -> Self {
+        Self {
+            skip_sync_back_names: RUNTIME_ROTATION_SHADOW_HOME_OMIT_STATE_FILES
+                .iter()
+                .map(|s| s.to_string())
+                .collect(),
+            skip_mirror_predicate: Some(Arc::new(is_runtime_rotation_shadow_home_omitted_entry)),
+            skip_sync_back_predicate: Some(Arc::new(is_runtime_rotation_shadow_home_omitted_entry)),
+            link_only_directory_predicate: Some(Arc::new(
+                is_runtime_rotation_shadow_home_link_only_directory,
+            )),
+        }
+    }
+}
+
+/// The sync-back handle returned by [`create_shadow_home_mirror`]; call
+/// [`ShadowHomeSyncBack::run`] before removing the shadow home.
+pub struct ShadowHomeSyncBack {
+    original_codex_home: PathBuf,
+    shadow_codex_home: PathBuf,
+    sync_file_names: HashSet<String>,
+    original_file_states: HashMap<String, ShadowFileState>,
+    copied_directory_names: HashSet<String>,
+    options: MirrorOptions,
+}
+
+impl ShadowHomeSyncBack {
+    /// TS: the closure returned by `createShadowHomeMirror` — best-effort
+    /// (never propagates errors).
+    pub fn run(&self) {
+        let names =
+            collect_shadow_home_sync_file_names(&self.shadow_codex_home, &self.sync_file_names);
+        let Ok(lock) = acquire_shadow_home_sync_lock(&self.original_codex_home) else {
+            return;
+        };
+        self.sync_auth_bundle();
+        self.sync_copied_directories();
+        self.sync_additional_files(&names);
+        lock.release();
+    }
+
+    fn skip_sync_back(&self, name: &str) -> bool {
+        self.options
+            .skip_sync_back_names
+            .iter()
+            .any(|skip| skip == name)
+    }
+
+    fn skip_sync_back_predicate(&self, name: &str) -> bool {
+        self.options
+            .skip_sync_back_predicate
+            .as_ref()
+            .is_some_and(|p| p(name))
+    }
+
+    /// TS `syncShadowHomeAuthBundle`.
+    fn sync_auth_bundle(&self) {
+        let mut sync_state = read_shadow_home_sync_state(&self.original_codex_home);
+        for name in SHADOW_HOME_STATE_FILES {
+            if self.skip_sync_back(name) {
+                continue;
+            }
+            let shadow_path = self.shadow_codex_home.join(name);
+            let shadow_state = capture_shadow_home_state(&shadow_path);
+            if !shadow_state.exists || shadow_state.unreadable {
+                continue;
+            }
+            let original_path = self.original_codex_home.join(name);
+            let original_snapshot = self
+                .original_file_states
+                .get(*name)
+                .cloned()
+                .unwrap_or_else(ShadowFileState::missing);
+            let current_original_state = capture_shadow_home_state(&original_path);
+            let mut expected_destination_state = original_snapshot.clone();
+            if !shadow_home_state_matches(&current_original_state, &original_snapshot) {
+                if !can_rebase_shadow_home_sync_state(
+                    &sync_state,
+                    name,
+                    &original_snapshot,
+                    &current_original_state,
+                ) {
+                    continue;
+                }
+                expected_destination_state = current_original_state;
+            }
+            if expected_destination_state.unreadable
+                || shadow_home_state_matches(&shadow_state, &expected_destination_state)
+            {
+                continue;
+            }
+            if sync_shadow_home_state_file_best_effort(
+                &shadow_path,
+                &original_path,
+                Some(&expected_destination_state),
+            ) {
+                remember_shadow_home_sync_state(
+                    &self.original_codex_home,
+                    &mut sync_state,
+                    name,
+                    &original_snapshot,
+                    &shadow_state,
+                );
+            }
+        }
+    }
+
+    /// TS `syncCopiedShadowHomeDirectories`.
+    fn sync_copied_directories(&self) {
+        for name in &self.copied_directory_names {
+            let shadow_path = self.shadow_codex_home.join(name);
+            if !is_directory_like(&shadow_path) {
+                continue;
+            }
+            let _ = copy_dir_recursive(&shadow_path, &self.original_codex_home.join(name));
+        }
+    }
+
+    /// TS `syncAdditionalShadowHomeFiles`.
+    fn sync_additional_files(&self, names: &HashSet<String>) {
+        for name in names {
+            if SHADOW_HOME_STATE_FILES.contains(&name.as_str())
+                || self.skip_sync_back(name)
+                || self.skip_sync_back_predicate(name)
+            {
+                continue;
+            }
+            let shadow_path = self.shadow_codex_home.join(name);
+            let shadow_state = capture_shadow_home_state(&shadow_path);
+            if !shadow_state.exists || shadow_state.unreadable {
+                continue;
+            }
+            let original_path = self.original_codex_home.join(name);
+            let original_snapshot = self
+                .original_file_states
+                .get(name)
+                .cloned()
+                .unwrap_or_else(ShadowFileState::missing);
+            let current_original_state = capture_shadow_home_state(&original_path);
+            if !shadow_home_state_matches(&current_original_state, &original_snapshot) {
+                continue;
+            }
+            if shadow_home_state_matches(&shadow_state, &original_snapshot) {
+                continue;
+            }
+            let _ = sync_shadow_home_state_file_best_effort(
+                &shadow_path,
+                &original_path,
+                Some(&original_snapshot),
+            );
+        }
+    }
+}
+
+/// TS `collectShadowHomeSyncFileNames` — root-level files of the shadow home
+/// beyond the known set (created during the run) so they sync back too.
+fn collect_shadow_home_sync_file_names(
+    shadow_codex_home: &Path,
+    seed: &HashSet<String>,
+) -> HashSet<String> {
+    let mut names = seed.clone();
+    let Ok(entries) = fs::read_dir(shadow_codex_home) else {
+        return names;
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if name == SHADOW_HOME_CONFIG_FILE
+            || name == SHADOW_HOME_SYNC_STATE_FILE
+            || names.contains(&name)
+        {
+            continue;
+        }
+        let shadow_path = shadow_codex_home.join(&name);
+        let file_like = match entry.file_type() {
+            Ok(ft) if ft.is_symlink() => is_file_like(&shadow_path),
+            Ok(ft) => ft.is_file(),
+            Err(_) => false,
+        };
+        if file_like {
+            names.insert(name);
+        }
+    }
+    names
+}
+
+/// TS `createShadowHomeMirror(originalCodexHome, shadowCodexHome, tighten,
+/// options)` — mirrors the real home into the shadow and returns the
+/// sync-back handle. Known state files that fail to mirror ABORT (error);
+/// optional entries fail soft.
+pub fn create_shadow_home_mirror(
+    original_codex_home: &Path,
+    shadow_codex_home: &Path,
+    options: MirrorOptions,
+) -> io::Result<ShadowHomeSyncBack> {
+    let mut sync_file_names: HashSet<String> = SHADOW_HOME_STATE_FILES
+        .iter()
+        .map(|s| s.to_string())
+        .collect();
+    let mut original_file_states: HashMap<String, ShadowFileState> = HashMap::new();
+    let mut copied_directory_names: HashSet<String> = HashSet::new();
+
+    let remember_sync_file =
+        |name: &str,
+         original_file_states: &mut HashMap<String, ShadowFileState>,
+         sync_file_names: &mut HashSet<String>| {
+            if !original_file_states.contains_key(name) {
+                original_file_states.insert(
+                    name.to_string(),
+                    capture_shadow_home_state(&original_codex_home.join(name)),
+                );
+            }
+            sync_file_names.insert(name.to_string());
+        };
+
+    for name in SHADOW_HOME_STATE_FILES {
+        remember_sync_file(name, &mut original_file_states, &mut sync_file_names);
+    }
+
+    if original_codex_home.exists() {
+        for entry in fs::read_dir(original_codex_home)?.flatten() {
+            let name = entry.file_name().to_string_lossy().into_owned();
+            if name == SHADOW_HOME_CONFIG_FILE
+                || name == SHADOW_HOME_SYNC_STATE_FILE
+                || name == SHADOW_HOME_SYNC_LOCK_DIR
+                || options
+                    .skip_mirror_predicate
+                    .as_ref()
+                    .is_some_and(|p| p(&name))
+            {
+                continue;
+            }
+            let is_known_state_file = SHADOW_HOME_STATE_FILES.contains(&name.as_str());
+            let should_materialize = should_materialize_file_into_shadow_home(&name);
+            let source_path = original_codex_home.join(&name);
+            let destination_path = shadow_codex_home.join(&name);
+            if destination_path.exists() {
+                continue;
+            }
+
+            let (directory_like, file_like) = match entry.file_type() {
+                Ok(ft) if ft.is_symlink() => {
+                    let dir = is_directory_like(&source_path);
+                    (dir, !dir && is_file_like(&source_path))
+                }
+                Ok(ft) => (ft.is_dir(), ft.is_file()),
+                Err(_) => (false, false),
+            };
+
+            let mirror_result = (|| -> io::Result<()> {
+                if is_known_state_file && !file_like {
+                    return Err(io::Error::other(format!("Expected {name} to be a file")));
+                }
+                if directory_like {
+                    if options
+                        .link_only_directory_predicate
+                        .as_ref()
+                        .is_some_and(|p| p(&name))
+                        && !should_copy_runtime_generated_dirs_fallback()
+                    {
+                        if !link_directory_into_shadow_home(&source_path, &destination_path) {
+                            warn_skipped_link_only_directory(&name);
+                        }
+                        return Ok(());
+                    }
+                    if mirror_directory_into_shadow_home(&source_path, &destination_path)?
+                        == "copied"
+                    {
+                        copied_directory_names.insert(name.clone());
+                    }
+                    return Ok(());
+                }
+                if file_like {
+                    remember_sync_file(&name, &mut original_file_states, &mut sync_file_names);
+                    if is_known_state_file {
+                        fs::copy(&source_path, &destination_path)?;
+                        tighten_file_permissions(&destination_path);
+                    } else if should_materialize {
+                        if is_sqlite_sidecar_file(&name) {
+                            return Ok(());
+                        }
+                        if materialize_file_into_shadow_home(&source_path, &destination_path)
+                            && is_sqlite_main_file(&name)
+                            && !materialize_sqlite_sidecars_into_shadow_home(
+                                &source_path,
+                                &destination_path,
+                            )
+                        {
+                            remove_sqlite_shadow_home_materialization(&destination_path);
+                        }
+                    } else {
+                        mirror_file_into_shadow_home(&source_path, &destination_path)?;
+                    }
+                }
+                Ok(())
+            })();
+            if let Err(error) = mirror_result
+                && is_known_state_file
+            {
+                return Err(error);
+            }
+            // Optional entries never block launch.
+        }
+    }
+
+    Ok(ShadowHomeSyncBack {
+        original_codex_home: original_codex_home.to_path_buf(),
+        shadow_codex_home: shadow_codex_home.to_path_buf(),
+        sync_file_names,
+        original_file_states,
+        copied_directory_names,
+        options,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Runtime-rotation shadow home creation + config.toml assembly.
+// ---------------------------------------------------------------------------
+
+/// TS `omitRuntimeRotationShadowHomeStateFiles(shadowCodexHome)`.
+pub fn omit_runtime_rotation_shadow_home_state_files(shadow_codex_home: &Path) {
+    for name in RUNTIME_ROTATION_SHADOW_HOME_OMIT_STATE_FILES {
+        let target = shadow_codex_home.join(name);
+        if !target.exists() {
+            continue;
+        }
+        if is_directory_like(&target) {
+            let _ = remove_directory_with_retry(&target);
+        } else {
+            let _ = fs::remove_file(&target);
+        }
+    }
+}
+
+/// TS `createRuntimeRotationShadowHome(originalCodexHome)` — mkdtemp under
+/// `<home>/multi-auth/runtime-shadow-homes/codex-multi-auth-runtime-home-*`.
+pub fn create_runtime_rotation_shadow_home(original_codex_home: &Path) -> io::Result<PathBuf> {
+    let shadow_root = original_codex_home
+        .join("multi-auth")
+        .join("runtime-shadow-homes");
+    fs::create_dir_all(&shadow_root)?;
+    for _ in 0..64 {
+        let candidate = shadow_root.join(format!(
+            "codex-multi-auth-runtime-home-{}",
+            random_hex(12)
+        ));
+        match fs::create_dir(&candidate) {
+            Ok(()) => return Ok(candidate),
+            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue,
+            Err(e) => return Err(e),
+        }
+    }
+    Err(io::Error::other(
+        "failed to create runtime rotation shadow home",
+    ))
+}
+
+// --- hooks.state trust mirroring (TS parseHookStateTableKey + TOML scan) ---
+
+/// TS `parseHookStateTableKey(line)`.
+pub fn parse_hook_state_table_key(line: &str) -> Option<String> {
+    let trimmed = line.trim();
+    let inner = trimmed.strip_prefix('[')?.strip_suffix(']')?.trim();
+    let rest = inner.strip_prefix("hooks.state.")?.trim();
+    if rest.len() >= 2 && rest.starts_with('"') && rest.ends_with('"') {
+        // Basic string — JSON-decode.
+        return serde_json::from_str::<String>(rest).ok();
+    }
+    if rest.len() >= 2 && rest.starts_with('\'') && rest.ends_with('\'') {
+        let inner = &rest[1..rest.len() - 1];
+        if !inner.contains('\'') {
+            return Some(inner.to_string());
+        }
+    }
+    None
+}
+
+/// TS `isTomlTableLine(line)` — heuristic table/array-of-tables header check.
+pub fn is_toml_table_line(line: &str) -> bool {
+    let trimmed = line.trim_start();
+    let Some(rest) = trimmed.strip_prefix('[') else {
+        return false;
+    };
+    let rest = rest.strip_prefix('[').unwrap_or(rest);
+    let rest = rest.trim_start();
+    if rest.starts_with('"') || rest.starts_with('\'') {
+        return true;
+    }
+    let key_len = rest
+        .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_' || c == '-'))
+        .unwrap_or(rest.len());
+    if key_len == 0 {
+        return false;
+    }
+    let after = rest[key_len..].trim_start();
+    after.starts_with('.')
+        || after.starts_with(']')
+}
+
+#[derive(Debug, Default)]
+struct TomlBlockScanState {
+    array_depth: usize,
+    multiline_string_delimiter: Option<&'static str>,
+}
+
+impl TomlBlockScanState {
+    fn is_top_level(&self) -> bool {
+        self.array_depth == 0 && self.multiline_string_delimiter.is_none()
+    }
+
+    fn update(&mut self, line: &str) {
+        let bytes = line.as_bytes();
+        let mut index = 0usize;
+        while index < bytes.len() {
+            if let Some(delim) = self.multiline_string_delimiter {
+                match line[index..].find(delim) {
+                    Some(offset) => {
+                        index += offset + delim.len();
+                        self.multiline_string_delimiter = None;
+                        continue;
+                    }
+                    None => return,
+                }
+            }
+            let ch = bytes[index];
+            if ch == b'#' {
+                return;
+            }
+            if line[index..].starts_with("\"\"\"") {
+                self.multiline_string_delimiter = Some("\"\"\"");
+                index += 3;
+                continue;
+            }
+            if line[index..].starts_with("'''") {
+                self.multiline_string_delimiter = Some("'''");
+                index += 3;
+                continue;
+            }
+            if ch == b'"' {
+                index += 1;
+                while index < bytes.len() {
+                    if bytes[index] == b'\\' {
+                        index += 2;
+                        continue;
+                    }
+                    if bytes[index] == b'"' {
+                        break;
+                    }
+                    index += 1;
+                }
+                index += 1;
+                continue;
+            }
+            if ch == b'\'' {
+                match line[index + 1..].find('\'') {
+                    Some(offset) => {
+                        index += 1 + offset + 1;
+                        continue;
+                    }
+                    None => return,
+                }
+            }
+            if ch == b'[' {
+                self.array_depth += 1;
+            } else if ch == b']' && self.array_depth > 0 {
+                self.array_depth -= 1;
+            }
+            index += 1;
+        }
+    }
+}
+
+/// TS `mirrorRuntimeShadowHookTrustState` — duplicates `hooks.state."<real
+/// hooks.json>:*"` trust blocks under the shadow hooks.json path so hook
+/// trust survives inside the shadow home.
+pub fn mirror_runtime_shadow_hook_trust_state(
+    raw_config: &str,
+    original_codex_home: &Path,
+    shadow_codex_home: &Path,
+) -> String {
+    let source_hooks_path = original_codex_home.join("hooks.json");
+    let shadow_hooks_path = shadow_codex_home.join("hooks.json");
+    if source_hooks_path == shadow_hooks_path {
+        return raw_config.to_string();
+    }
+    let source_prefix = format!("{}:", source_hooks_path.display());
+    let shadow_hooks_display = shadow_hooks_path.display().to_string();
+
+    let line_ending = if raw_config.contains("\r\n") { "\r\n" } else { "\n" };
+    let lines: Vec<&str> = if raw_config.is_empty() {
+        Vec::new()
+    } else {
+        raw_config.split("\r\n").flat_map(|s| s.split('\n')).collect()
+    };
+
+    let mut existing_hook_state_keys: HashSet<String> = HashSet::new();
+    for line in &lines {
+        if let Some(key) = parse_hook_state_table_key(line) {
+            existing_hook_state_keys.insert(key);
+        }
+    }
+
+    let mut output: Vec<String> = Vec::with_capacity(lines.len());
+    let mut changed = false;
+    let mut index = 0usize;
+    while index < lines.len() {
+        let line = lines[index];
+        let key = parse_hook_state_table_key(line);
+        output.push(line.to_string());
+        let Some(key) = key.filter(|k| k.starts_with(&source_prefix)) else {
+            index += 1;
+            continue;
+        };
+        let mut block_lines: Vec<&str> = Vec::new();
+        let mut next_index = index + 1;
+        let mut block_state = TomlBlockScanState::default();
+        while next_index < lines.len() {
+            let next_line = lines[next_index];
+            if block_state.is_top_level() && is_toml_table_line(next_line) {
+                break;
+            }
+            block_lines.push(next_line);
+            block_state.update(next_line);
+            next_index += 1;
+        }
+        output.extend(block_lines.iter().map(|s| s.to_string()));
+        index = next_index;
+        let shadow_key = format!(
+            "{shadow_hooks_display}:{}",
+            &key[source_prefix.len()..]
+        );
+        if existing_hook_state_keys.contains(&shadow_key) {
+            continue;
+        }
+        output.push(String::new());
+        output.push(format!(
+            "[hooks.state.{}]",
+            cma_runtime::config_toml::toml_string_literal(&shadow_key)
+        ));
+        output.extend(block_lines.iter().map(|s| s.to_string()));
+        existing_hook_state_keys.insert(shadow_key);
+        changed = true;
+    }
+
+    if changed {
+        output.join(line_ending)
+    } else {
+        raw_config.to_string()
+    }
+}
+
+/// The forwarded env + cleanup produced by
+/// [`create_runtime_rotation_proxy_codex_home`].
+pub struct ShadowHomeContext {
+    /// Env overrides layered onto the base environment for the spawned codex.
+    pub env: HashMap<String, String>,
+    pub shadow_codex_home: PathBuf,
+    sync_back: Option<ShadowHomeSyncBack>,
+}
+
+impl ShadowHomeContext {
+    /// Assemble a context from an already-created shadow home + sync-back
+    /// (compatibility-home path in `forward.rs`).
+    pub fn from_parts(shadow_codex_home: PathBuf, sync_back: ShadowHomeSyncBack) -> Self {
+        Self {
+            env: HashMap::new(),
+            shadow_codex_home,
+            sync_back: Some(sync_back),
+        }
+    }
+
+    /// TS: `cleanup()` — sync state back, then remove the shadow home.
+    pub fn cleanup(mut self) {
+        self.cleanup_inner();
+    }
+
+    fn cleanup_inner(&mut self) {
+        if let Some(sync_back) = self.sync_back.take() {
+            sync_back.run();
+        }
+        let _ = remove_directory_with_retry(&self.shadow_codex_home);
+    }
+}
+
+impl Drop for ShadowHomeContext {
+    fn drop(&mut self) {
+        if self.sync_back.is_some() {
+            self.cleanup_inner();
+        }
+    }
+}
+
+/// TS `resolveOriginalMultiAuthDir(env)` — explicit `CODEX_MULTI_AUTH_DIR`
+/// only.
+pub fn resolve_original_multi_auth_dir(env: &HashMap<String, String>) -> Option<String> {
+    env.get("CODEX_MULTI_AUTH_DIR")
+        .map(|v| v.trim().to_string())
+        .filter(|v| !v.is_empty())
+}
+
+/// TS `resolveRuntimeRotationOriginalMultiAuthDir(originalCodexHome, env)`.
+pub fn resolve_runtime_rotation_original_multi_auth_dir(
+    original_codex_home: &Path,
+    env: &HashMap<String, String>,
+) -> String {
+    resolve_original_multi_auth_dir(env)
+        .unwrap_or_else(|| original_codex_home.join("multi-auth").display().to_string())
+}
+
+/// TS `resolveRuntimeRotationProxyOriginalCodexHome(baseEnv)` — honors the
+/// app-helper's `CODEX_MULTI_AUTH_REAL_CODEX_HOME` override.
+pub fn resolve_runtime_rotation_proxy_original_codex_home(
+    env: &HashMap<String, String>,
+) -> PathBuf {
+    let override_value = env
+        .get("CODEX_MULTI_AUTH_REAL_CODEX_HOME")
+        .map(|v| v.trim().to_string())
+        .unwrap_or_default();
+    if !override_value.is_empty() {
+        return PathBuf::from(override_value);
+    }
+    resolve_codex_home_dir(env)
+}
+
+/// TS `resolveCodexHomeDir(env)` — `CODEX_HOME` override, then the platform
+/// home ladder (delegates to `cma_core::runtime_paths` when reading the
+/// process env; a supplied env map resolves the same keys locally).
+pub fn resolve_codex_home_dir(env: &HashMap<String, String>) -> PathBuf {
+    let override_value = env
+        .get("CODEX_HOME")
+        .map(|v| v.trim().to_string())
+        .unwrap_or_default();
+    if !override_value.is_empty() {
+        return PathBuf::from(override_value);
+    }
+    if cfg!(windows) {
+        let user_profile = env
+            .get("USERPROFILE")
+            .map(|v| v.trim().to_string())
+            .unwrap_or_default();
+        if !user_profile.is_empty() {
+            return Path::new(&user_profile).join(".codex");
+        }
+        let home_drive = env.get("HOMEDRIVE").map(|v| v.trim().to_string()).unwrap_or_default();
+        let home_path = env.get("HOMEPATH").map(|v| v.trim().to_string()).unwrap_or_default();
+        if !home_drive.is_empty() && !home_path.is_empty() {
+            return Path::new(&format!("{home_drive}{home_path}")).join(".codex");
+        }
+    }
+    if let Some(home) = env.get("HOME").map(|v| v.trim().to_string()).filter(|v| !v.is_empty()) {
+        return Path::new(&home).join(".codex");
+    }
+    home::home_dir_via_core().join(".codex")
+}
+
+/// Small shim: `home::home_dir()` lives in cma-core's dependency set; core
+/// exposes the resolved home through `get_codex_home_dir`'s ladder. For the
+/// no-env fallback we derive home from the process env ladder in core.
+mod home {
+    use std::path::PathBuf;
+
+    pub fn home_dir_via_core() -> PathBuf {
+        // core's get_codex_home_dir() returns <home>/.codex for the process
+        // env; strip the trailing component to recover the home dir.
+        let codex_home = cma_core::runtime_paths::get_codex_home_dir();
+        codex_home
+            .parent()
+            .map(std::path::Path::to_path_buf)
+            .unwrap_or(codex_home)
+    }
+}
+
+/// TS `createRuntimeRotationProxyCodexHome(baseEnv, proxyBaseUrl,
+/// clientApiKey, configTomlModule)` — build the runtime-rotation shadow home
+/// and the forwarded env (`CODEX_HOME`, `OPENAI_API_KEY`,
+/// `CODEX_MULTI_AUTH_DIR`).
+pub fn create_runtime_rotation_proxy_codex_home(
+    base_env: &HashMap<String, String>,
+    proxy_base_url: &str,
+    client_api_key: &str,
+) -> io::Result<ShadowHomeContext> {
+    let original_codex_home = resolve_runtime_rotation_proxy_original_codex_home(base_env);
+    let shadow_codex_home = create_runtime_rotation_shadow_home(&original_codex_home)?;
+
+    let result = (|| -> io::Result<ShadowHomeSyncBack> {
+        let sync_back = create_shadow_home_mirror(
+            &original_codex_home,
+            &shadow_codex_home,
+            MirrorOptions::runtime_rotation(),
+        )?;
+        omit_runtime_rotation_shadow_home_state_files(&shadow_codex_home);
+        let original_config_path = original_codex_home.join(SHADOW_HOME_CONFIG_FILE);
+        // TS parity: readFileSync throws on an unreadable-but-existing config
+        // (Windows lock, ACL, transient EBUSY) — the error propagates, the
+        // shadow home is removed below, and the caller falls back to a normal
+        // launch against the user's REAL config. Silently defaulting to an
+        // empty string would keep the proxy but drop the user's entire
+        // config (model, profiles, MCP servers, trust) for the run.
+        let raw_config = if original_config_path.exists() {
+            fs::read_to_string(&original_config_path)?
+        } else {
+            String::new()
+        };
+        let runtime_config = mirror_runtime_shadow_hook_trust_state(
+            &cma_runtime::config_toml::rewrite_config_toml_for_runtime_rotation_provider(
+                &raw_config,
+                proxy_base_url,
+                client_api_key,
+            ),
+            &original_codex_home,
+            &shadow_codex_home,
+        );
+        let runtime_config_path = shadow_codex_home.join(SHADOW_HOME_CONFIG_FILE);
+        fs::write(&runtime_config_path, runtime_config)?;
+        tighten_file_permissions(&runtime_config_path);
+        Ok(sync_back)
+    })();
+
+    let sync_back = match result {
+        Ok(sync_back) => sync_back,
+        Err(error) => {
+            let _ = remove_directory_with_retry(&shadow_codex_home);
+            return Err(error);
+        }
+    };
+
+    let mut env = HashMap::new();
+    env.insert(
+        "CODEX_HOME".to_string(),
+        shadow_codex_home.display().to_string(),
+    );
+    env.insert("OPENAI_API_KEY".to_string(), client_api_key.to_string());
+    env.insert(
+        "CODEX_MULTI_AUTH_DIR".to_string(),
+        resolve_runtime_rotation_original_multi_auth_dir(&original_codex_home, base_env),
+    );
+
+    Ok(ShadowHomeContext {
+        env,
+        shadow_codex_home,
+        sync_back: Some(sync_back),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn state_hashing_rules() {
+        assert_eq!(
+            hash_shadow_home_state(&ShadowFileState::missing()).as_deref(),
+            Some("missing")
+        );
+        assert_eq!(
+            hash_shadow_home_state(&ShadowFileState {
+                exists: true,
+                content: None,
+                unreadable: true
+            }),
+            None
+        );
+        let hashed = hash_shadow_home_state(&ShadowFileState {
+            exists: true,
+            content: Some("abc".to_string()),
+            unreadable: false,
+        })
+        .unwrap();
+        assert!(hashed.starts_with("sha256:"));
+        assert_eq!(hashed.len(), "sha256:".len() + 64);
+    }
+
+    #[test]
+    fn runtime_rotation_omit_rules() {
+        assert!(is_runtime_rotation_shadow_home_omitted_entry("multi-auth"));
+        assert!(is_runtime_rotation_shadow_home_omitted_entry("state_123.sqlite"));
+        assert!(is_runtime_rotation_shadow_home_omitted_entry("logs_9.sqlite-wal"));
+        assert!(is_runtime_rotation_shadow_home_omitted_entry("auth.json.123.abc12.tmp"));
+        assert!(is_runtime_rotation_shadow_home_omitted_entry(
+            ".codex-global-state.json.tmp-abc-123"
+        ));
+        assert!(!is_runtime_rotation_shadow_home_omitted_entry("auth.json"));
+        assert!(!is_runtime_rotation_shadow_home_omitted_entry("sessions"));
+        assert!(!is_runtime_rotation_shadow_home_omitted_entry("state_.sqlite"));
+        assert!(is_runtime_rotation_shadow_home_link_only_directory("sqlite"));
+        assert!(is_runtime_rotation_shadow_home_link_only_directory("cache"));
+        assert!(!is_runtime_rotation_shadow_home_link_only_directory("sessions"));
+    }
+
+    #[test]
+    fn sqlite_name_classification() {
+        assert!(is_sqlite_main_file("STATE.SQLITE"));
+        assert!(is_sqlite_sidecar_file("a.sqlite-wal"));
+        assert!(is_sqlite_sidecar_file("a.sqlite-shm"));
+        assert!(!is_sqlite_sidecar_file("a.sqlite"));
+        assert!(!is_sqlite_main_file("a.sqlite-wal"));
+    }
+
+    /// Node `symlinkSync(..., "junction")` parity: on win32 the dir mirror
+    /// must create an unprivileged NTFS junction (a reparse point), never
+    /// fall back to a copy just because SeCreateSymbolicLinkPrivilege is
+    /// absent (standard users / no Developer Mode). Runs fine WITH the
+    /// privilege too — a junction is created either way.
+    #[cfg(windows)]
+    #[test]
+    fn windows_dir_mirror_links_via_junction_without_symlink_privilege() {
+        let temp = tempfile::tempdir().unwrap();
+        let source = temp.path().join("sqlite");
+        fs::create_dir_all(&source).unwrap();
+        fs::write(source.join("state.sqlite"), b"db").unwrap();
+        let destination = temp.path().join("shadow-sqlite");
+
+        let how = mirror_directory_into_shadow_home(&source, &destination).unwrap();
+        assert_eq!(how, "linked", "junction, not copy");
+        // A junction is a name-surrogate reparse point: symlink_metadata
+        // reports is_symlink() on Windows and the link resolves live.
+        let meta = fs::symlink_metadata(&destination).unwrap();
+        assert!(meta.file_type().is_symlink(), "reparse point expected");
+        assert!(destination.join("state.sqlite").exists(), "link resolves");
+        fs::write(source.join("new.sqlite"), b"live").unwrap();
+        assert!(destination.join("new.sqlite").exists(), "live-linked, not a copy");
+
+        // link_directory_into_shadow_home shares the same seam.
+        let second = temp.path().join("shadow-cache");
+        assert!(link_directory_into_shadow_home(&source, &second));
+        assert!(fs::symlink_metadata(&second).unwrap().file_type().is_symlink());
+    }
+
+    /// TS parity: an EXISTING config.toml that cannot be read (lock/ACL)
+    /// must abort shadow-home creation (caller then runs Codex normally
+    /// against the real config) instead of silently proceeding with an
+    /// EMPTY shadow config — which would drop the user's model/profiles/
+    /// MCP servers for the run. The failed attempt removes the shadow dir.
+    #[cfg(windows)]
+    #[test]
+    fn unreadable_config_toml_aborts_shadow_home_creation() {
+        use std::os::windows::fs::OpenOptionsExt;
+        let temp = tempfile::tempdir().unwrap();
+        let codex_home = temp.path().join("codex-home");
+        fs::create_dir_all(&codex_home).unwrap();
+        let config_path = codex_home.join("config.toml");
+        fs::write(&config_path, "model = \"gpt-5.5\"\n").unwrap();
+        // Hold the file open with NO sharing: any other open (the mirror's
+        // read_to_string) fails with ERROR_SHARING_VIOLATION.
+        let _exclusive = fs::OpenOptions::new()
+            .read(true)
+            .write(true)
+            .share_mode(0)
+            .open(&config_path)
+            .unwrap();
+
+        let mut base_env = HashMap::new();
+        base_env.insert(
+            "CODEX_HOME".to_string(),
+            codex_home.display().to_string(),
+        );
+        let result = create_runtime_rotation_proxy_codex_home(
+            &base_env,
+            "http://127.0.0.1:9/",
+            "test-key",
+        );
+        assert!(result.is_err(), "unreadable config must propagate an error");
+
+        // The partially-built shadow home was cleaned up.
+        let shadow_root = codex_home.join("multi-auth").join("runtime-shadow-homes");
+        let leftovers: Vec<_> = fs::read_dir(&shadow_root)
+            .map(|entries| entries.flatten().collect())
+            .unwrap_or_default();
+        assert!(
+            leftovers.is_empty(),
+            "shadow dir removed on failure: {leftovers:?}"
+        );
+    }
+
+    #[test]
+    fn hook_state_key_parsing() {
+        assert_eq!(
+            parse_hook_state_table_key("[hooks.state.\"C:/h/hooks.json:my-hook\"]"),
+            Some("C:/h/hooks.json:my-hook".to_string())
+        );
+        assert_eq!(
+            parse_hook_state_table_key("  [ hooks.state.'p:x' ]  "),
+            Some("p:x".to_string())
+        );
+        assert_eq!(parse_hook_state_table_key("[other.table]"), None);
+        assert_eq!(parse_hook_state_table_key("key = 1"), None);
+    }
+
+    #[test]
+    fn toml_table_line_detection() {
+        assert!(is_toml_table_line("[table]"));
+        assert!(is_toml_table_line("[[array_of_tables]]"));
+        assert!(is_toml_table_line("[a.b]"));
+        assert!(is_toml_table_line("[\"quoted\"]"));
+        assert!(!is_toml_table_line("key = [1, 2]"));
+        assert!(!is_toml_table_line("# comment"));
+    }
+
+    #[test]
+    fn sync_state_round_trip_and_rebase() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let mut sync_state = read_shadow_home_sync_state(home);
+        assert_eq!(sync_state["version"], 1);
+
+        let base = ShadowFileState {
+            exists: true,
+            content: Some("base".to_string()),
+            unreadable: false,
+        };
+        let synced = ShadowFileState {
+            exists: true,
+            content: Some("synced".to_string()),
+            unreadable: false,
+        };
+        remember_shadow_home_sync_state(home, &mut sync_state, "auth.json", &base, &synced);
+        // Reload from disk and verify the rebase check accepts (base, synced).
+        let reloaded = read_shadow_home_sync_state(home);
+        assert!(can_rebase_shadow_home_sync_state(&reloaded, "auth.json", &base, &synced));
+        // A different current state refuses the rebase.
+        let unrelated = ShadowFileState {
+            exists: true,
+            content: Some("external edit".to_string()),
+            unreadable: false,
+        };
+        assert!(!can_rebase_shadow_home_sync_state(&reloaded, "auth.json", &base, &unrelated));
+        assert!(!can_rebase_shadow_home_sync_state(&reloaded, "other.json", &base, &synced));
+    }
+
+    #[test]
+    fn mirror_and_sync_back_round_trip() {
+        let temp = tempfile::tempdir().unwrap();
+        let original = temp.path().join("real-home");
+        let shadow = temp.path().join("shadow-home");
+        fs::create_dir_all(&original).unwrap();
+        fs::create_dir_all(&shadow).unwrap();
+        fs::write(original.join("auth.json"), "{\"a\":1}").unwrap();
+        fs::write(original.join("config.toml"), "model = \"x\"\n").unwrap();
+        fs::write(original.join("notes.txt"), "keep").unwrap();
+
+        let sync_back =
+            create_shadow_home_mirror(&original, &shadow, MirrorOptions::default()).unwrap();
+        // config.toml is never mirrored (wrapper writes its own).
+        assert!(!shadow.join("config.toml").exists());
+        assert_eq!(fs::read_to_string(shadow.join("auth.json")).unwrap(), "{\"a\":1}");
+
+        // Simulate the official CLI refreshing auth inside the shadow home.
+        fs::write(shadow.join("auth.json"), "{\"a\":2}").unwrap();
+        sync_back.run();
+        assert_eq!(
+            fs::read_to_string(original.join("auth.json")).unwrap(),
+            "{\"a\":2}"
+        );
+    }
+
+    #[test]
+    fn sync_back_refuses_external_edit() {
+        let temp = tempfile::tempdir().unwrap();
+        let original = temp.path().join("real-home");
+        let shadow = temp.path().join("shadow-home");
+        fs::create_dir_all(&original).unwrap();
+        fs::create_dir_all(&shadow).unwrap();
+        fs::write(original.join("auth.json"), "orig").unwrap();
+
+        let sync_back =
+            create_shadow_home_mirror(&original, &shadow, MirrorOptions::default()).unwrap();
+        // Shadow session refreshes...
+        fs::write(shadow.join("auth.json"), "shadow-refresh").unwrap();
+        // ...but an EXTERNAL writer also changed the original meanwhile.
+        fs::write(original.join("auth.json"), "external").unwrap();
+        sync_back.run();
+        // External edit wins; shadow refresh must NOT clobber it.
+        assert_eq!(fs::read_to_string(original.join("auth.json")).unwrap(), "external");
+    }
+
+    #[test]
+    fn runtime_rotation_mirror_omits_auth_state() {
+        let temp = tempfile::tempdir().unwrap();
+        let original = temp.path().join("real-home");
+        fs::create_dir_all(original.join("multi-auth")).unwrap();
+        fs::write(original.join("auth.json"), "secret").unwrap();
+        fs::write(original.join("accounts.json"), "accounts").unwrap();
+        fs::write(original.join(".codex-global-state.json"), "{}").unwrap();
+
+        let env = HashMap::new();
+        let mut env = env;
+        env.insert(
+            "CODEX_MULTI_AUTH_REAL_CODEX_HOME".to_string(),
+            original.display().to_string(),
+        );
+        let context =
+            create_runtime_rotation_proxy_codex_home(&env, "http://127.0.0.1:9/", "key-123")
+                .unwrap();
+        let shadow = context.shadow_codex_home.clone();
+        assert!(!shadow.join("auth.json").exists());
+        assert!(!shadow.join("accounts.json").exists());
+        assert!(shadow.join(".codex-global-state.json").exists());
+        // config.toml written with the provider block + client key.
+        let config = fs::read_to_string(shadow.join("config.toml")).unwrap();
+        assert!(config.contains("codex-multi-auth-runtime-proxy"));
+        // Forwarded env points CODEX_HOME at the shadow and pins the dir.
+        assert_eq!(
+            context.env.get("CODEX_HOME").unwrap(),
+            &shadow.display().to_string()
+        );
+        assert_eq!(context.env.get("OPENAI_API_KEY").unwrap(), "key-123");
+        assert_eq!(
+            context.env.get("CODEX_MULTI_AUTH_DIR").unwrap(),
+            &original.join("multi-auth").display().to_string()
+        );
+        context.cleanup();
+        assert!(!shadow.exists());
+        // Real auth untouched.
+        assert_eq!(fs::read_to_string(original.join("auth.json")).unwrap(), "secret");
+    }
+
+    #[test]
+    fn sync_lock_claim_and_stale_takeover() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path();
+        let lock = acquire_shadow_home_sync_lock(home).unwrap();
+        let lock_dir = home.join(SHADOW_HOME_SYNC_LOCK_DIR);
+        assert!(lock_dir.exists());
+        lock.release();
+        assert!(!lock_dir.exists());
+
+        // A dead-owner lock is stolen.
+        fs::create_dir_all(&lock_dir).unwrap();
+        fs::write(
+            lock_dir.join("owner.json"),
+            "{\"pid\": 999999999, \"createdAt\": 1}\n",
+        )
+        .unwrap();
+        let lock = acquire_shadow_home_sync_lock(home).unwrap();
+        lock.release();
+    }
+
+    #[test]
+    fn owner_only_json_writer_shape() {
+        let temp = tempfile::tempdir().unwrap();
+        let target = temp.path().join("nested").join("status.json");
+        write_owner_only_json_file_atomic_sync(&target, &serde_json::json!({"version": 1}))
+            .unwrap();
+        let raw = fs::read_to_string(&target).unwrap();
+        assert_eq!(raw, "{\n  \"version\": 1\n}\n");
+    }
+
+    #[test]
+    fn hook_trust_block_duplication() {
+        let temp = tempfile::tempdir().unwrap();
+        let original = temp.path().join("orig");
+        let shadow = temp.path().join("shadow");
+        fs::create_dir_all(&original).unwrap();
+        fs::create_dir_all(&shadow).unwrap();
+        let source_key = format!("{}:my-hook", original.join("hooks.json").display());
+        let raw = format!(
+            "[hooks.state.{}]\ntrusted = true\n",
+            cma_runtime::config_toml::toml_string_literal(&source_key)
+        );
+        let rewritten = mirror_runtime_shadow_hook_trust_state(&raw, &original, &shadow);
+        let shadow_key = format!("{}:my-hook", shadow.join("hooks.json").display());
+        assert!(rewritten.contains(&format!(
+            "[hooks.state.{}]",
+            cma_runtime::config_toml::toml_string_literal(&shadow_key)
+        )));
+        // Idempotent: running again adds nothing.
+        let again = mirror_runtime_shadow_hook_trust_state(&rewritten, &original, &shadow);
+        assert_eq!(again.matches("trusted = true").count(), 2);
+    }
+}
diff --git a/crates/wrapper/src/statusline.rs b/crates/wrapper/src/statusline.rs
new file mode 100644
index 000000000..5d1b39e6d
--- /dev/null
+++ b/crates/wrapper/src/statusline.rs
@@ -0,0 +1,957 @@
+//! Forward status line (`CODEX_MULTI_AUTH_STATUSLINE`) + the background
+//! quota-cache refresh — port of the status half of `scripts/codex.js`.
+//!
+//! The status line reads the (possibly project-scoped) accounts pool plus the
+//! GLOBAL `quota-cache.json` / `runtime-observability.json` files as raw JSON
+//! (never through the manager), formats one `|`-separated line, and prints it
+//! to stderr for TTY runs.
+
+use std::collections::HashMap;
+use std::fs;
+use std::io::IsTerminal;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+use serde_json::Value;
+
+use crate::shadow_home::{remove_directory_best_effort_detached, remove_directory_with_retry};
+
+/// TS `DEFAULT_STATUS_QUOTA_REFRESH_INTERVAL_MS` (10 min).
+pub const DEFAULT_STATUS_QUOTA_REFRESH_INTERVAL_MS: i64 = 10 * 60 * 1000;
+/// TS `STATUS_QUOTA_REFRESH_LOCK_STALE_MS` (10 min).
+pub const STATUS_QUOTA_REFRESH_LOCK_STALE_MS: i64 = 10 * 60 * 1000;
+/// TS `STATUS_QUOTA_REFRESH_LOCK_DIR`.
+pub const STATUS_QUOTA_REFRESH_LOCK_DIR: &str = "status-quota-refresh.lock";
+
+fn env_string(name: &str) -> String {
+    std::env::var(name).unwrap_or_default()
+}
+
+/// TS `readJsonFileQuiet(path)` — `null` on missing/unreadable/invalid.
+pub fn read_json_file_quiet(path: &Path) -> Option<Value> {
+    if !path.exists() {
+        return None;
+    }
+    let raw = fs::read_to_string(path).ok()?;
+    serde_json::from_str(&raw).ok()
+}
+
+/// TS `resolveMultiAuthDirFromEnv(env)` — explicit `CODEX_MULTI_AUTH_DIR` or
+/// `<codex home>/multi-auth` (wrapper-simple, no pool probing ladder).
+pub fn resolve_multi_auth_dir_from_env() -> PathBuf {
+    let configured = env_string("CODEX_MULTI_AUTH_DIR");
+    let configured = configured.trim();
+    if !configured.is_empty() {
+        return PathBuf::from(configured);
+    }
+    cma_core::runtime_paths::get_codex_home_dir().join("multi-auth")
+}
+
+/// TS `resolveAccountsPath(env, dir)`.
+pub fn resolve_accounts_path(dir: &Path) -> PathBuf {
+    dir.join("openai-codex-accounts.json")
+}
+
+/// TS `resolveQuotaCachePath(env, dir)`.
+pub fn resolve_quota_cache_path(dir: &Path) -> PathBuf {
+    dir.join("quota-cache.json")
+}
+
+/// TS `resolveRuntimeObservabilityPath(env, dir)`.
+pub fn resolve_runtime_observability_path(dir: &Path) -> PathBuf {
+    dir.join("runtime-observability.json")
+}
+
+/// TS `resolveStatusAccountsDir(env)` — mirrors the runtime's account scoping:
+/// per-project pool only when `perProjectAccounts` is on, Codex CLI sync is
+/// OFF, no explicit `CODEX_MULTI_AUTH_DIR`, and the cwd resolves to a project
+/// root. Any failure falls back to the global dir.
+pub fn resolve_status_accounts_dir() -> PathBuf {
+    let global_dir = resolve_multi_auth_dir_from_env();
+    if !env_string("CODEX_MULTI_AUTH_DIR").trim().is_empty() {
+        // Explicit dir: the TS helper reaches the same outcome because the
+        // runtime nests project pools under the configured dir; the wrapper
+        // keeps reading the explicit pool root.
+    }
+    let plugin_config = cma_config::load::load_plugin_config();
+    if !cma_config::getters::get_per_project_accounts(&plugin_config) {
+        return global_dir;
+    }
+    if cma_cli_mirror::state::is_codex_cli_sync_enabled() {
+        return global_dir;
+    }
+    let Ok(cwd) = std::env::current_dir() else {
+        return global_dir;
+    };
+    let Some(project_root) = cma_storage::paths::find_project_root(&cwd) else {
+        return global_dir;
+    };
+    let identity_root = cma_storage::paths::resolve_project_storage_identity_root(&project_root);
+    cma_storage::paths::get_project_global_config_dir(&identity_root)
+}
+
+/// TS `normalizeAccountIdentifier(value)` — full Unicode lowercasing
+/// (String.prototype.toLowerCase), so non-ASCII ids/emails match across
+/// case (same commit as the account_force normalize fix).
+pub fn normalize_account_identifier(value: Option<&str>) -> String {
+    match value {
+        Some(v) if !v.trim().is_empty() => v.trim().to_lowercase(),
+        _ => String::new(),
+    }
+}
+
+/// TS `findAccountIndexByIdOrEmail(accounts, id, email)`.
+pub fn find_account_index_by_id_or_email(
+    accounts: &[Value],
+    id: Option<&str>,
+    email: Option<&str>,
+) -> Option<usize> {
+    let normalized_id = normalize_account_identifier(id);
+    let normalized_email = normalize_account_identifier(email);
+    for (index, account) in accounts.iter().enumerate() {
+        if !account.is_object() {
+            continue;
+        }
+        if !normalized_id.is_empty()
+            && normalize_account_identifier(account.get("accountId").and_then(Value::as_str))
+                == normalized_id
+        {
+            return Some(index);
+        }
+        if !normalized_email.is_empty()
+            && normalize_account_identifier(account.get("email").and_then(Value::as_str))
+                == normalized_email
+        {
+            return Some(index);
+        }
+    }
+    None
+}
+
+/// TS `resolveModelFamilyForStatus(model)` — wrapper-local family bucketing
+/// (GPT-5.6 general tiers share the gpt-5.2 prompt family).
+pub fn resolve_model_family_for_status(model: Option<&str>) -> Option<&'static str> {
+    let normalized = model.map(|m| m.trim().to_ascii_lowercase()).unwrap_or_default();
+    if normalized.starts_with("gpt-5.6") {
+        return Some("gpt-5.2");
+    }
+    if normalized.starts_with("gpt-5.2") {
+        return Some("gpt-5.2");
+    }
+    if normalized.starts_with("gpt-5.1") {
+        return Some("gpt-5.1");
+    }
+    if normalized.contains("codex-max") {
+        return Some("codex-max");
+    }
+    if normalized.contains("codex") {
+        return Some("codex");
+    }
+    if normalized.starts_with("gpt-5") {
+        return Some("gpt-5-codex");
+    }
+    None
+}
+
+/// TS `resolveStatusAccountIndex(storage, runtime, model)` — 3-signal merge:
+/// fresh runtime observability (≤ 1 h) → family active index → activeIndex →
+/// 0. Returns `None` only for an empty pool.
+pub fn resolve_status_account_index(
+    storage: Option<&Value>,
+    runtime: Option<&Value>,
+    model: Option<&str>,
+    now_ms: i64,
+) -> Option<usize> {
+    let accounts = storage
+        .and_then(|s| s.get("accounts"))
+        .and_then(Value::as_array)?;
+    if accounts.is_empty() {
+        return None;
+    }
+
+    let runtime_updated_at = runtime
+        .and_then(|r| r.get("lastAccountUpdatedAt"))
+        .and_then(Value::as_i64)
+        .or_else(|| runtime.and_then(|r| r.get("updatedAt")).and_then(Value::as_i64))
+        .unwrap_or(0);
+    if now_ms - runtime_updated_at <= 60 * 60 * 1000 {
+        let runtime_index = find_account_index_by_id_or_email(
+            accounts,
+            runtime
+                .and_then(|r| r.get("lastAccountId"))
+                .and_then(Value::as_str),
+            runtime
+                .and_then(|r| r.get("lastAccountEmail"))
+                .and_then(Value::as_str),
+        );
+        if let Some(index) = runtime_index {
+            return Some(index);
+        }
+        if let Some(last_index) = runtime
+            .and_then(|r| r.get("lastAccountIndex"))
+            .and_then(Value::as_i64)
+            && last_index >= 0
+            && (last_index as usize) < accounts.len()
+        {
+            return Some(last_index as usize);
+        }
+    }
+
+    let family = resolve_model_family_for_status(model);
+    if let Some(family) = family
+        && let Some(family_index) = storage
+            .and_then(|s| s.get("activeIndexByFamily"))
+            .and_then(|m| m.get(family))
+            .and_then(Value::as_i64)
+        && family_index >= 0
+        && (family_index as usize) < accounts.len()
+    {
+        return Some(family_index as usize);
+    }
+    if let Some(active_index) = storage
+        .and_then(|s| s.get("activeIndex"))
+        .and_then(Value::as_i64)
+        && active_index >= 0
+        && (active_index as usize) < accounts.len()
+    {
+        return Some(active_index as usize);
+    }
+    Some(0)
+}
+
+/// TS `extractConfigAssignmentValue(rawConfig, key)` — first `key = value`
+/// line; strips one layer of quotes, drops `#` comments.
+pub fn extract_config_assignment_value(raw_config: &str, key: &str) -> Option<String> {
+    for line in raw_config.lines() {
+        let trimmed_start = line.trim_start();
+        let Some(rest) = trimmed_start.strip_prefix(key) else {
+            continue;
+        };
+        let rest = rest.trim_start();
+        let Some(rest) = rest.strip_prefix('=') else {
+            continue;
+        };
+        // value = everything before a newline or '#'
+        let value_part = rest.split('#').next().unwrap_or("");
+        let raw_value = value_part.trim();
+        let unquoted = if (raw_value.starts_with('"') && raw_value.ends_with('"')
+            || raw_value.starts_with('\'') && raw_value.ends_with('\''))
+            && raw_value.len() >= 2
+        {
+            raw_value[1..raw_value.len() - 1].trim()
+        } else {
+            raw_value
+        };
+        if unquoted.is_empty() {
+            return None;
+        }
+        return Some(unquoted.to_string());
+    }
+    None
+}
+
+/// TS `readCodexConfigValue(env, key)` — from `<codex home>/config.toml`.
+pub fn read_codex_config_value(key: &str) -> Option<String> {
+    let config_path = cma_core::runtime_paths::get_codex_home_dir().join("config.toml");
+    if !config_path.exists() {
+        return None;
+    }
+    let raw = fs::read_to_string(&config_path).ok()?;
+    extract_config_assignment_value(&raw, key)
+}
+
+/// TS `extractArgValue(args, longName, shortName)`.
+pub fn extract_arg_value(args: &[String], long_name: &str, short_name: Option<&str>) -> Option<String> {
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        if arg == long_name || short_name.is_some_and(|s| arg == s) {
+            return args.get(i + 1).cloned();
+        }
+        if let Some(value) = arg.strip_prefix(&format!("{long_name}=")) {
+            return Some(value.to_string());
+        }
+        i += 1;
+    }
+    None
+}
+
+/// TS `extractConfigOverrideValue(args, key)` — `-c key=value` /
+/// `--config key=value` / `--config=key=value` / `-c=key=value`.
+pub fn extract_config_override_value(args: &[String], key: &str) -> Option<String> {
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = args[i].as_str();
+        let assignment: Option<&str> = if arg == "-c" || arg == "--config" {
+            args.get(i + 1).map(String::as_str)
+        } else if let Some(rest) = arg.strip_prefix("-c=") {
+            Some(rest)
+        } else if let Some(rest) = arg.strip_prefix("--config=") {
+            Some(rest)
+        } else {
+            None
+        };
+        if let Some(assignment) = assignment
+            && let Some(separator) = assignment.find('=')
+            && separator > 0
+            && assignment[..separator].trim() == key
+        {
+            let value = assignment[separator + 1..].trim();
+            let value = value
+                .strip_prefix('"')
+                .or_else(|| value.strip_prefix('\''))
+                .unwrap_or(value);
+            let value = value
+                .strip_suffix('"')
+                .or_else(|| value.strip_suffix('\''))
+                .unwrap_or(value);
+            return Some(value.to_string());
+        }
+        i += 1;
+    }
+    None
+}
+
+/// TS `resolveStatusModel(args, env)`.
+pub fn resolve_status_model(args: &[String]) -> String {
+    extract_arg_value(args, "--model", Some("-m"))
+        .or_else(|| extract_config_override_value(args, "model"))
+        .or_else(|| read_codex_config_value("model"))
+        .unwrap_or_else(|| "unknown-model".to_string())
+}
+
+/// TS `resolveStatusReasoningEffort(args, env)`.
+pub fn resolve_status_reasoning_effort(args: &[String]) -> String {
+    extract_config_override_value(args, "model_reasoning_effort")
+        .or_else(|| read_codex_config_value("model_reasoning_effort"))
+        .unwrap_or_else(|| "unknown".to_string())
+}
+
+/// TS `formatStatusPath(cwd, home)` — `~` abbreviation with forward-slash
+/// normalization of the remainder.
+pub fn format_status_path(cwd: &Path, home: &Path) -> String {
+    if cwd == home {
+        return "~".to_string();
+    }
+    let cwd_str = cwd.display().to_string();
+    let home_str = home.display().to_string();
+    let sep = std::path::MAIN_SEPARATOR;
+    let prefix = format!("{home_str}{sep}");
+    if let Some(rest) = cwd_str.strip_prefix(&prefix) {
+        let normalized = rest.replace(sep, "/");
+        return format!("~/{normalized}");
+    }
+    cwd_str
+}
+
+// --- local-time formatting -------------------------------------------------
+//
+// TS uses `toLocaleTimeString`/`toLocaleDateString` (local timezone). The
+// wrapper crate has no timezone database dependency; the offset is taken from
+// the internal `CODEX_MULTI_AUTH_LOCAL_TZ_OFFSET_MIN` env var when the bin
+// main publishes it, else UTC (documented deviation).
+
+fn local_tz_offset_minutes() -> i64 {
+    std::env::var("CODEX_MULTI_AUTH_LOCAL_TZ_OFFSET_MIN")
+        .ok()
+        .and_then(|raw| raw.trim().parse::<i64>().ok())
+        .unwrap_or(0)
+}
+
+/// Civil date from days since the Unix epoch (Howard Hinnant's algorithm).
+fn civil_from_days(z: i64) -> (i64, u32, u32) {
+    let z = z + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = (z - era * 146_097) as u64;
+    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146_096) / 365;
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    (if m <= 2 { y + 1 } else { y }, m, d)
+}
+
+fn local_time_parts(epoch_ms: i64) -> (i64, u32, u32, u32, u32) {
+    let shifted = epoch_ms + local_tz_offset_minutes() * 60_000;
+    let days = shifted.div_euclid(86_400_000);
+    let ms_of_day = shifted.rem_euclid(86_400_000);
+    let (year, month, day) = civil_from_days(days);
+    let hour = (ms_of_day / 3_600_000) as u32;
+    let minute = ((ms_of_day % 3_600_000) / 60_000) as u32;
+    (year, month, day, hour, minute)
+}
+
+const MONTH_SHORT: [&str; 12] = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+
+/// TS `formatStatusResetTime(resetAtMs)` — `HH:MM` (24-hour).
+pub fn format_status_reset_time(reset_at_ms: Option<i64>) -> Option<String> {
+    let reset_at = reset_at_ms.filter(|&v| v > 0)?;
+    let (_, _, _, hour, minute) = local_time_parts(reset_at);
+    Some(format!("{hour:02}:{minute:02}"))
+}
+
+/// TS `formatStatusResetDate(resetAtMs)` — `Mon D` (e.g. `Jul 29`).
+pub fn format_status_reset_date(reset_at_ms: Option<i64>) -> Option<String> {
+    let reset_at = reset_at_ms.filter(|&v| v > 0)?;
+    let (_, month, day, _, _) = local_time_parts(reset_at);
+    Some(format!("{} {day}", MONTH_SHORT[(month - 1) as usize]))
+}
+
+/// TS `formatCacheAge(updatedAt)` — `stale` / `now` / `Nm` / `Nh`.
+pub fn format_cache_age(updated_at: Option<i64>, now_ms: i64) -> String {
+    let Some(updated_at) = updated_at.filter(|&v| v > 0) else {
+        return "stale".to_string();
+    };
+    let age_ms = (now_ms - updated_at).max(0);
+    if age_ms < 60_000 {
+        return "now".to_string();
+    }
+    if age_ms < 60 * 60_000 {
+        return format!("{}m", age_ms / 60_000);
+    }
+    format!("{}h", age_ms / (60 * 60_000))
+}
+
+/// TS `getQuotaEntryForAccount(quotaCache, account)`.
+pub fn get_quota_entry_for_account<'a>(
+    quota_cache: Option<&'a Value>,
+    account: &Value,
+) -> Option<&'a Value> {
+    let account_id = account
+        .get("accountId")
+        .and_then(Value::as_str)
+        .unwrap_or("");
+    let email = account
+        .get("email")
+        .and_then(Value::as_str)
+        .map(|e| e.to_ascii_lowercase())
+        .unwrap_or_default();
+    let by_account_id = quota_cache.and_then(|c| c.get("byAccountId"));
+    let by_email = quota_cache.and_then(|c| c.get("byEmail"));
+    by_account_id
+        .and_then(|m| m.get(account_id))
+        .filter(|v| !v.is_null())
+        .or_else(|| by_email.and_then(|m| m.get(&email)).filter(|v| !v.is_null()))
+}
+
+fn format_usage_window(
+    label: &str,
+    window: Option<&Value>,
+    reset_formatter: impl Fn(Option<i64>) -> Option<String>,
+) -> Option<String> {
+    let used = window
+        .and_then(|w| w.get("usedPercent"))
+        .and_then(Value::as_f64)
+        .filter(|v| v.is_finite())
+        .map(|v| v.round().clamp(0.0, 100.0) as i64);
+    let reset = reset_formatter(window.and_then(|w| w.get("resetAtMs")).and_then(Value::as_i64));
+    match (used, reset) {
+        (None, None) => None,
+        (None, Some(reset)) => Some(format!("{label} resets {reset}")),
+        (Some(used), None) => Some(format!("{label} {used}%")),
+        (Some(used), Some(reset)) => Some(format!("{label} {used}% {reset}")),
+    }
+}
+
+/// TS `formatUsageSegment(entry)`.
+pub fn format_usage_segment(entry: Option<&Value>) -> String {
+    let primary = format_usage_window(
+        "5h",
+        entry.and_then(|e| e.get("primary")),
+        format_status_reset_time,
+    );
+    let secondary = format_usage_window(
+        "week",
+        entry.and_then(|e| e.get("secondary")),
+        format_status_reset_date,
+    );
+    let parts: Vec<String> = [primary, secondary].into_iter().flatten().collect();
+    if parts.is_empty() {
+        "usage cached".to_string()
+    } else {
+        parts.join(" | ")
+    }
+}
+
+/// TS `formatPlan(planType)` — `Plan?` fallback, else capitalized.
+pub fn format_plan(plan_type: Option<&str>) -> String {
+    let Some(plan) = plan_type.map(str::trim).filter(|p| !p.is_empty()) else {
+        return "Plan?".to_string();
+    };
+    let mut chars = plan.chars();
+    match chars.next() {
+        Some(first) if plan.chars().count() > 1 => {
+            format!(
+                "{}{}",
+                first.to_uppercase(),
+                chars.as_str().to_lowercase()
+            )
+        }
+        Some(first) => first.to_uppercase().to_string(),
+        None => "Plan?".to_string(),
+    }
+}
+
+/// TS `shouldShowForwardStatus(args, env)` — env override wins; the refresh
+/// child never shows it; help/version runs never show it; else stderr TTY.
+pub fn should_show_forward_status(args: &[String]) -> bool {
+    let override_value = env_string("CODEX_MULTI_AUTH_STATUSLINE")
+        .trim()
+        .to_ascii_lowercase();
+    if matches!(override_value.as_str(), "0" | "false" | "no" | "off") {
+        return false;
+    }
+    if matches!(override_value.as_str(), "1" | "true" | "yes" | "on") {
+        return true;
+    }
+    if env_string("CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD").trim() == "1" {
+        return false;
+    }
+    if args
+        .iter()
+        .any(|arg| matches!(arg.as_str(), "--help" | "-h" | "--version" | "-V"))
+    {
+        return false;
+    }
+    std::io::stderr().is_terminal()
+}
+
+/// TS `formatForwardStatusLine(rawArgs, env, accountsDir)` — `None` when no
+/// accounts are configured or the selected account row is malformed.
+pub fn format_forward_status_line(raw_args: &[String], accounts_dir: &Path) -> Option<String> {
+    let storage = read_json_file_quiet(&resolve_accounts_path(accounts_dir));
+    let accounts: Vec<Value> = storage
+        .as_ref()
+        .and_then(|s| s.get("accounts"))
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+    if accounts.is_empty() {
+        return None;
+    }
+
+    let global_dir = resolve_multi_auth_dir_from_env();
+    let runtime = read_json_file_quiet(&resolve_runtime_observability_path(&global_dir));
+    let quota_cache = read_json_file_quiet(&resolve_quota_cache_path(&global_dir));
+    let model = resolve_status_model(raw_args);
+    let effort = resolve_status_reasoning_effort(raw_args);
+    let now = cma_core::utils::now_ms();
+    let account_index = resolve_status_account_index(
+        storage.as_ref(),
+        runtime.as_ref(),
+        Some(model.as_str()),
+        now,
+    )?;
+    let account = accounts.get(account_index)?;
+    if !account.is_object() {
+        return None;
+    }
+
+    let quota_entry = get_quota_entry_for_account(quota_cache.as_ref(), account);
+    let email = account
+        .get("email")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|e| !e.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| format!("Account {}", account_index + 1));
+    let plan = format_plan(
+        quota_entry
+            .and_then(|e| e.get("planType"))
+            .and_then(Value::as_str),
+    );
+    let usage = format_usage_segment(quota_entry);
+    let cache_age = format_cache_age(
+        quota_entry
+            .and_then(|e| e.get("updatedAt"))
+            .and_then(Value::as_i64),
+        now,
+    );
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let home = cma_core::runtime_paths::get_codex_home_dir()
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_default();
+    let parts = [
+        "codex-multi-auth".to_string(),
+        format!("{model} {effort}"),
+        format_status_path(&cwd, &home),
+        format!("Account {}", account_index + 1),
+        usage,
+        format!("{email}({plan})"),
+        format!("cache {cache_age}"),
+    ];
+    Some(parts.join(" | "))
+}
+
+/// TS `maybePrintForwardStatusLine(rawArgs, env)`.
+pub fn maybe_print_forward_status_line(raw_args: &[String]) {
+    if !should_show_forward_status(raw_args) {
+        return;
+    }
+    let accounts_dir = resolve_status_accounts_dir();
+    if let Some(line) = format_forward_status_line(raw_args, &accounts_dir) {
+        eprintln!("{line}");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Background quota-cache refresh.
+// ---------------------------------------------------------------------------
+
+/// TS `parseDurationMs(value, fallback)`.
+pub fn parse_duration_ms(value: Option<&str>, fallback: i64) -> i64 {
+    let trimmed = value.map(str::trim).unwrap_or("");
+    if trimmed.is_empty() {
+        return fallback;
+    }
+    // parseInt semantics: leading integer digits (optionally signed).
+    let (sign, digits) = match trimmed.strip_prefix('-') {
+        Some(rest) => (-1i64, rest),
+        None => (1i64, trimmed.strip_prefix('+').unwrap_or(trimmed)),
+    };
+    let end = digits
+        .find(|c: char| !c.is_ascii_digit())
+        .unwrap_or(digits.len());
+    if end == 0 {
+        return fallback;
+    }
+    let Ok(parsed) = digits[..end].parse::<i64>() else {
+        return fallback;
+    };
+    let parsed = sign * parsed;
+    if parsed < 0 { fallback } else { parsed }
+}
+
+/// TS `quotaCacheNeedsRefresh(env)`.
+pub fn quota_cache_needs_refresh() -> bool {
+    let interval_env = std::env::var("CODEX_MULTI_AUTH_STATUS_QUOTA_REFRESH_INTERVAL_MS").ok();
+    let interval_ms = parse_duration_ms(
+        interval_env.as_deref(),
+        DEFAULT_STATUS_QUOTA_REFRESH_INTERVAL_MS,
+    );
+    if interval_ms <= 0 {
+        return false;
+    }
+    let dir = resolve_multi_auth_dir_from_env();
+    let cache = read_json_file_quiet(&resolve_quota_cache_path(&dir));
+    let mut entries: Vec<&Value> = Vec::new();
+    for key in ["byAccountId", "byEmail"] {
+        if let Some(map) = cache
+            .as_ref()
+            .and_then(|c| c.get(key))
+            .and_then(Value::as_object)
+        {
+            entries.extend(map.values().filter(|v| v.is_object()));
+        }
+    }
+    if entries.is_empty() {
+        return true;
+    }
+    let newest = entries
+        .iter()
+        .map(|entry| {
+            entry
+                .get("updatedAt")
+                .and_then(Value::as_i64)
+                .unwrap_or(0)
+        })
+        .max()
+        .unwrap_or(0);
+    newest <= 0 || cma_core::utils::now_ms() - newest >= interval_ms
+}
+
+/// TS `acquireStatusRefreshLock(env)` — mkdir claim + owner.json, stale (10
+/// min) takeover.
+pub fn acquire_status_refresh_lock() -> (PathBuf, bool) {
+    let lock_path = resolve_multi_auth_dir_from_env().join(STATUS_QUOTA_REFRESH_LOCK_DIR);
+    let claim = |recovered: bool| -> bool {
+        if fs::create_dir(&lock_path).is_err() {
+            return false;
+        }
+        let mut payload = serde_json::json!({
+            "pid": std::process::id(),
+            "createdAt": cma_core::utils::now_ms(),
+        });
+        if recovered {
+            payload["recovered"] = Value::Bool(true);
+        }
+        let _ = fs::write(
+            lock_path.join("owner.json"),
+            format!("{}\n", cma_core::json_io::stringify_compact(&payload)),
+        );
+        true
+    };
+    if let Some(parent) = lock_path.parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+    if claim(false) {
+        return (lock_path, true);
+    }
+    // Stale takeover (bounded TOCTOU accepted — see TS comment).
+    if let Ok(meta) = fs::metadata(&lock_path) {
+        let mtime_ms = meta
+            .modified()
+            .ok()
+            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
+            .map(|d| d.as_millis() as i64)
+            .unwrap_or(0);
+        if cma_core::utils::now_ms() - mtime_ms > STATUS_QUOTA_REFRESH_LOCK_STALE_MS
+            && remove_directory_with_retry(&lock_path).is_ok()
+            && claim(true)
+        {
+            return (lock_path, true);
+        }
+    }
+    (lock_path, false)
+}
+
+/// Resolve a sibling cma binary (`codex-multi-auth`, `codex-multi-auth-codex`,
+/// …) next to the current executable, falling back to the bare name (PATH).
+pub fn resolve_sibling_cma_binary(name: &str) -> PathBuf {
+    let file_name = if cfg!(windows) {
+        format!("{name}.exe")
+    } else {
+        name.to_string()
+    };
+    if let Ok(current) = std::env::current_exe()
+        && let Some(dir) = current.parent()
+    {
+        let candidate = dir.join(&file_name);
+        if candidate.exists() {
+            return candidate;
+        }
+    }
+    PathBuf::from(name)
+}
+
+/// TS `maybeRefreshQuotaCacheInBackground(env)` — spawns a detached
+/// `codex-multi-auth forecast --live --json` child under the refresh lock.
+/// A background thread waits on the child to clean the lock; if the parent
+/// exits first, the 10-minute stale-lock recovery reclaims it.
+pub fn maybe_refresh_quota_cache_in_background(extra_env: &HashMap<String, String>) {
+    if env_string("CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD").trim() == "1" {
+        return;
+    }
+    if !quota_cache_needs_refresh() {
+        return;
+    }
+    let (lock_path, acquired) = acquire_status_refresh_lock();
+    if !acquired {
+        return;
+    }
+    let program = resolve_sibling_cma_binary("codex-multi-auth");
+    let mut command = Command::new(program);
+    command
+        .args(["forecast", "--live", "--json"])
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .envs(extra_env)
+        .env("CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD", "1")
+        .env("CODEX_MULTI_AUTH_STATUSLINE", "0")
+        // A forced-account pin is scoped to a single forwarded run; the
+        // management child must never inherit it.
+        .env_remove(crate::account_force::FORCE_ACCOUNT_INDEX_ENV);
+    match command.spawn() {
+        Ok(mut child) => {
+            std::thread::spawn(move || {
+                let _ = child.wait();
+                remove_directory_best_effort_detached(lock_path);
+            });
+        }
+        Err(_) => {
+            remove_directory_best_effort_detached(lock_path);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn model_family_bucketing() {
+        assert_eq!(resolve_model_family_for_status(Some("gpt-5.6-sol")), Some("gpt-5.2"));
+        assert_eq!(resolve_model_family_for_status(Some("GPT-5.2")), Some("gpt-5.2"));
+        assert_eq!(resolve_model_family_for_status(Some("gpt-5.1")), Some("gpt-5.1"));
+        // TS ordering: the gpt-5.1 prefix check precedes the codex-max scan.
+        assert_eq!(
+            resolve_model_family_for_status(Some("gpt-5.1-codex-max")),
+            Some("gpt-5.1")
+        );
+        assert_eq!(
+            resolve_model_family_for_status(Some("codex-max")),
+            Some("codex-max")
+        );
+        assert_eq!(resolve_model_family_for_status(Some("gpt-5.3-codex")), Some("codex"));
+        assert_eq!(resolve_model_family_for_status(Some("gpt-5.5")), Some("gpt-5-codex"));
+        assert_eq!(resolve_model_family_for_status(Some("o3")), None);
+        assert_eq!(resolve_model_family_for_status(None), None);
+    }
+
+    #[test]
+    fn account_index_resolution_ladder() {
+        let storage = json!({
+            "accounts": [
+                {"accountId": "acc_1", "email": "a@x.com"},
+                {"accountId": "acc_2", "email": "b@x.com"},
+                {"accountId": "acc_3", "email": "c@x.com"}
+            ],
+            "activeIndexByFamily": {"gpt-5.2": 2},
+            "activeIndex": 1
+        });
+        let now = 10_000_000i64;
+        // Fresh runtime signal wins.
+        let runtime = json!({"lastAccountUpdatedAt": now - 1000, "lastAccountEmail": "B@X.COM"});
+        assert_eq!(
+            resolve_status_account_index(Some(&storage), Some(&runtime), Some("gpt-5.6"), now),
+            Some(1)
+        );
+        // Stale runtime → family index.
+        let stale = json!({"lastAccountUpdatedAt": now - 2 * 60 * 60 * 1000, "lastAccountEmail": "b@x.com"});
+        assert_eq!(
+            resolve_status_account_index(Some(&storage), Some(&stale), Some("gpt-5.6"), now),
+            Some(2)
+        );
+        // No family entry → activeIndex.
+        assert_eq!(
+            resolve_status_account_index(Some(&storage), Some(&stale), Some("gpt-5.3-codex"), now),
+            Some(1)
+        );
+        // Runtime index fallback within freshness window.
+        let idx_runtime = json!({"updatedAt": now, "lastAccountIndex": 2});
+        assert_eq!(
+            resolve_status_account_index(Some(&storage), Some(&idx_runtime), None, now),
+            Some(2)
+        );
+        // Empty pool → None.
+        let empty = json!({"accounts": []});
+        assert_eq!(resolve_status_account_index(Some(&empty), None, None, now), None);
+    }
+
+    #[test]
+    fn config_assignment_extraction() {
+        let raw = "# c\nmodel = \"gpt-5.5\"\nmodel_reasoning_effort = high # inline\n";
+        assert_eq!(
+            extract_config_assignment_value(raw, "model").as_deref(),
+            Some("gpt-5.5")
+        );
+        assert_eq!(
+            extract_config_assignment_value(raw, "model_reasoning_effort").as_deref(),
+            Some("high")
+        );
+        assert_eq!(extract_config_assignment_value(raw, "missing"), None);
+    }
+
+    #[test]
+    fn arg_and_config_override_extraction() {
+        let args: Vec<String> = ["-m", "gpt-5.5", "-c", "model_reasoning_effort=\"xhigh\""]
+            .iter()
+            .map(|s| s.to_string())
+            .collect();
+        assert_eq!(
+            extract_arg_value(&args, "--model", Some("-m")).as_deref(),
+            Some("gpt-5.5")
+        );
+        assert_eq!(
+            extract_config_override_value(&args, "model_reasoning_effort").as_deref(),
+            Some("xhigh")
+        );
+        let eq_form: Vec<String> = ["--model=gpt-5.4", "--config=model=other"]
+            .iter()
+            .map(|s| s.to_string())
+            .collect();
+        assert_eq!(
+            extract_arg_value(&eq_form, "--model", Some("-m")).as_deref(),
+            Some("gpt-5.4")
+        );
+        assert_eq!(
+            extract_config_override_value(&eq_form, "model").as_deref(),
+            Some("other")
+        );
+    }
+
+    #[test]
+    fn status_path_formatting() {
+        let home = PathBuf::from(if cfg!(windows) { "C:\\Users\\me" } else { "/home/me" });
+        assert_eq!(format_status_path(&home, &home), "~");
+        let nested = home.join("proj").join("sub");
+        assert_eq!(format_status_path(&nested, &home), "~/proj/sub");
+        let outside = PathBuf::from(if cfg!(windows) { "D:\\other" } else { "/other" });
+        assert_eq!(format_status_path(&outside, &home), outside.display().to_string());
+    }
+
+    #[test]
+    fn cache_age_formatting() {
+        let now = 100 * 60 * 60_000i64;
+        assert_eq!(format_cache_age(None, now), "stale");
+        assert_eq!(format_cache_age(Some(0), now), "stale");
+        assert_eq!(format_cache_age(Some(now - 30_000), now), "now");
+        assert_eq!(format_cache_age(Some(now - 5 * 60_000), now), "5m");
+        assert_eq!(format_cache_age(Some(now - 3 * 60 * 60_000), now), "3h");
+    }
+
+    #[test]
+    fn plan_formatting() {
+        assert_eq!(format_plan(None), "Plan?");
+        assert_eq!(format_plan(Some("  ")), "Plan?");
+        assert_eq!(format_plan(Some("plus")), "Plus");
+        assert_eq!(format_plan(Some("PRO")), "Pro");
+        assert_eq!(format_plan(Some("x")), "X");
+    }
+
+    #[test]
+    fn usage_segment_formatting() {
+        assert_eq!(format_usage_segment(None), "usage cached");
+        let entry = json!({"primary": {"usedPercent": 42.4}, "secondary": {"usedPercent": 90.6}});
+        assert_eq!(format_usage_segment(Some(&entry)), "5h 42% | week 91%");
+        let entry = json!({"primary": {"usedPercent": 150.0}});
+        assert_eq!(format_usage_segment(Some(&entry)), "5h 100%");
+    }
+
+    #[test]
+    fn quota_entry_lookup_prefers_account_id() {
+        let cache = json!({
+            "byAccountId": {"acc_1": {"planType": "plus"}},
+            "byEmail": {"a@x.com": {"planType": "pro"}}
+        });
+        let account = json!({"accountId": "acc_1", "email": "A@X.com"});
+        let entry = get_quota_entry_for_account(Some(&cache), &account).unwrap();
+        assert_eq!(entry["planType"], "plus");
+        let account2 = json!({"accountId": "other", "email": "A@X.com"});
+        let entry2 = get_quota_entry_for_account(Some(&cache), &account2).unwrap();
+        assert_eq!(entry2["planType"], "pro");
+        let account3 = json!({"accountId": "nope", "email": "nope@x.com"});
+        assert!(get_quota_entry_for_account(Some(&cache), &account3).is_none());
+    }
+
+    #[test]
+    fn duration_parsing() {
+        assert_eq!(parse_duration_ms(None, 7), 7);
+        assert_eq!(parse_duration_ms(Some(""), 7), 7);
+        assert_eq!(parse_duration_ms(Some("  1200  "), 7), 1200);
+        assert_eq!(parse_duration_ms(Some("0"), 7), 0);
+        assert_eq!(parse_duration_ms(Some("-5"), 7), 7);
+        assert_eq!(parse_duration_ms(Some("abc"), 7), 7);
+        assert_eq!(parse_duration_ms(Some("120x"), 7), 120);
+    }
+
+    #[test]
+    fn reset_time_formatting_utc_fallback() {
+        // 2026-07-29T18:10:00Z
+        let ts = 1_785_348_600_000i64;
+        // Without the offset env var this formats in UTC.
+        if std::env::var("CODEX_MULTI_AUTH_LOCAL_TZ_OFFSET_MIN").is_err() {
+            assert_eq!(format_status_reset_time(Some(ts)).unwrap(), "18:10");
+            assert_eq!(format_status_reset_date(Some(ts)).unwrap(), "Jul 29");
+        }
+        assert_eq!(format_status_reset_time(None), None);
+        assert_eq!(format_status_reset_time(Some(0)), None);
+        assert_eq!(format_status_reset_time(Some(-5)), None);
+    }
+}
diff --git a/crates/wrapper/src/update_check.rs b/crates/wrapper/src/update_check.rs
new file mode 100644
index 000000000..eaa680310
--- /dev/null
+++ b/crates/wrapper/src/update_check.rs
@@ -0,0 +1,527 @@
+//! Wrapper startup update notice — port of the update-notice half of
+//! `scripts/codex.js` + the cache/semver logic of `lib/update-notice.ts`.
+//!
+//! Contract (spec 14 §6): best-effort DAILY npm check; the printed update
+//! command is ONLY `npm install -g codex-multi-auth@latest`; TTY-only unless
+//! `CODEX_MULTI_AUTH_DEBUG=1`; never runs npm itself. Startup is budgeted
+//! (default 3000 ms; fetch timeout = 80% of the budget).
+//!
+//! The wrapper crate has no HTTP client dependency, so the npm-registry fetch
+//! is an injectable seam ([`LatestVersionFetch`]); without a fetcher the check
+//! is cache-only (fresh cache still yields notices; a stale cache skips
+//! silently — the manager binary refreshes the shared cache on its own runs).
+
+use std::fs;
+use std::future::Future;
+use std::io::IsTerminal;
+use std::path::PathBuf;
+use std::pin::Pin;
+use std::time::Duration;
+
+use crate::routing::{is_pure_help_or_version_args, should_handle_multi_auth_auth};
+
+/// TS `CHECK_INTERVAL_MS` (lib/update-notice.ts) — 24 h.
+pub const CHECK_INTERVAL_MS: i64 = 24 * 60 * 60 * 1000;
+/// TS `UPDATE_CHECK_TIMEOUT_MS`.
+pub const UPDATE_CHECK_TIMEOUT_MS: u64 = 5_000;
+/// TS `DEFAULT_STARTUP_UPDATE_NOTICE_BUDGET_MS` (scripts/codex.js).
+pub const DEFAULT_STARTUP_UPDATE_NOTICE_BUDGET_MS: u64 = 3_000;
+const PACKAGE_NAME: &str = "codex-multi-auth";
+
+/// TS `UpdateCheckResult`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateCheckResult {
+    pub has_update: bool,
+    pub current_version: String,
+    pub latest_version: Option<String>,
+    pub update_command: String,
+}
+
+/// The injectable npm-registry lookup (`fetchLatestVersion` seam). The
+/// cma-bin main wires this to the manager's reqwest-backed fetcher.
+pub trait LatestVersionFetch: Send + Sync {
+    fn fetch_latest_version(
+        &self,
+        timeout_ms: u64,
+    ) -> Pin<Box<dyn Future<Output = Option<String>> + Send + '_>>;
+}
+
+/// TS `buildManualUpdateCommand()` — the ONLY update command ever printed.
+pub fn build_manual_update_command() -> String {
+    format!("npm install -g {PACKAGE_NAME}@latest")
+}
+
+/// TS `formatManualUpdateNotice(result)`.
+pub fn format_manual_update_notice(result: &UpdateCheckResult) -> String {
+    [
+        format!(
+            "codex-multi-auth update available: v{}",
+            result.latest_version.as_deref().unwrap_or("")
+        ),
+        format!("current: v{}", result.current_version),
+        format!("run: {}", result.update_command),
+    ]
+    .join("; ")
+}
+
+/// TS `getCurrentVersion()` — env `CODEX_MULTI_AUTH_CLI_VERSION` (hydrated by
+/// the launcher) then the crate version; `0.0.0` fallback.
+pub fn get_current_version() -> String {
+    let from_env = std::env::var("CODEX_MULTI_AUTH_CLI_VERSION").unwrap_or_default();
+    let from_env = from_env.trim();
+    if !from_env.is_empty() {
+        return from_env.to_string();
+    }
+    let built_in = env!("CARGO_PKG_VERSION").trim();
+    if built_in.is_empty() {
+        "0.0.0".to_string()
+    } else {
+        built_in.to_string()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Semver comparison (hand-rolled — lib/update-notice.ts parity).
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ParsedSemver {
+    core: [u64; 3],
+    prerelease: Vec<String>,
+}
+
+fn to_safe_int(value: &str) -> u64 {
+    if !value.is_empty() && value.chars().all(|c| c.is_ascii_digit()) {
+        value.parse().unwrap_or(0)
+    } else {
+        0
+    }
+}
+
+fn parse_semver(version: &str) -> ParsedSemver {
+    let normalized = version.trim();
+    let normalized = normalized
+        .strip_prefix('v')
+        .or_else(|| normalized.strip_prefix('V'))
+        .unwrap_or(normalized);
+    let without_build = normalized.split('+').next().unwrap_or("0.0.0");
+    let mut split = without_build.splitn(2, '-');
+    let core_part = split.next().unwrap_or("0.0.0");
+    let prerelease_part = split.next();
+    let mut core_iter = core_part.split('.');
+    let core = [
+        to_safe_int(core_iter.next().unwrap_or("0")),
+        to_safe_int(core_iter.next().unwrap_or("0")),
+        to_safe_int(core_iter.next().unwrap_or("0")),
+    ];
+    let prerelease = prerelease_part
+        .map(|p| {
+            p.split('.')
+                .filter(|segment| !segment.is_empty())
+                .map(str::to_string)
+                .collect()
+        })
+        .unwrap_or_default();
+    ParsedSemver { core, prerelease }
+}
+
+fn compare_prerelease(current: &[String], latest: &[String]) -> i32 {
+    let max_len = current.len().max(latest.len());
+    for i in 0..max_len {
+        let current_part = current.get(i);
+        let latest_part = latest.get(i);
+        match (current_part, latest_part) {
+            (None, None) => return 0,
+            // current ran out → latest is "greater" (newer)
+            (None, Some(_)) => return 1,
+            (Some(_), None) => return -1,
+            (Some(c), Some(l)) => {
+                if c == l {
+                    continue;
+                }
+                let c_num = c.chars().all(|ch| ch.is_ascii_digit());
+                let l_num = l.chars().all(|ch| ch.is_ascii_digit());
+                if c_num && l_num {
+                    let cn: u64 = c.parse().unwrap_or(0);
+                    let ln: u64 = l.parse().unwrap_or(0);
+                    if ln > cn {
+                        return 1;
+                    }
+                    if ln < cn {
+                        return -1;
+                    }
+                    continue;
+                }
+                if c_num && !l_num {
+                    return 1;
+                }
+                if !c_num && l_num {
+                    return -1;
+                }
+                match l.cmp(c) {
+                    std::cmp::Ordering::Greater => return 1,
+                    std::cmp::Ordering::Less => return -1,
+                    std::cmp::Ordering::Equal => continue,
+                }
+            }
+        }
+    }
+    0
+}
+
+/// TS `compareVersions(current, latest)` — returns 1 when `latest` is newer
+/// than `current`, -1 when older, 0 when equal.
+pub fn compare_versions(current: &str, latest: &str) -> i32 {
+    let parsed_current = parse_semver(current);
+    let parsed_latest = parse_semver(latest);
+    for i in 0..3 {
+        let c = parsed_current.core[i];
+        let l = parsed_latest.core[i];
+        if l > c {
+            return 1;
+        }
+        if l < c {
+            return -1;
+        }
+    }
+    let current_has = !parsed_current.prerelease.is_empty();
+    let latest_has = !parsed_latest.prerelease.is_empty();
+    if !current_has && latest_has {
+        return -1;
+    }
+    if current_has && !latest_has {
+        return 1;
+    }
+    compare_prerelease(&parsed_current.prerelease, &parsed_latest.prerelease)
+}
+
+// ---------------------------------------------------------------------------
+// Cache (`<cache dir>/update-check-cache.json` — shared with the manager).
+// ---------------------------------------------------------------------------
+
+fn cache_file_path() -> PathBuf {
+    cma_core::runtime_paths::get_codex_cache_dir().join("update-check-cache.json")
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct UpdateCheckCache {
+    last_check: i64,
+    latest_version: Option<String>,
+    current_version: String,
+}
+
+fn load_cache() -> Option<UpdateCheckCache> {
+    let path = cache_file_path();
+    if !path.exists() {
+        return None;
+    }
+    let raw = fs::read_to_string(&path).ok()?;
+    serde_json::from_str(&raw).ok()
+}
+
+/// TS `saveCache` — `JSON.stringify(cache, null, 2)` (NO trailing newline),
+/// temp+rename, EBUSY/EPERM/ENOTEMPTY ×4 with 15·2^n backoff. Best-effort.
+fn save_cache(cache: &UpdateCheckCache) {
+    let path = cache_file_path();
+    let Some(dir) = path.parent() else {
+        return;
+    };
+    if fs::create_dir_all(dir).is_err() {
+        return;
+    }
+    let serialized = cma_core::json_io::stringify_pretty2(
+        &serde_json::to_value(cache).unwrap_or(serde_json::Value::Null),
+    );
+    let temp = cma_core::temp_path::temp_path_for(&path);
+    for attempt in 0..4u32 {
+        let result = fs::write(&temp, serialized.as_bytes()).and_then(|()| fs::rename(&temp, &path));
+        match result {
+            Ok(()) => return,
+            Err(error) => {
+                let retryable = matches!(
+                    cma_core::fs_retry::code_of(&error),
+                    Some("EBUSY") | Some("EPERM") | Some("ENOTEMPTY")
+                );
+                if !retryable || attempt >= 3 {
+                    let _ = fs::remove_file(&temp);
+                    return;
+                }
+                std::thread::sleep(Duration::from_millis(15 * 2u64.pow(attempt)));
+            }
+        }
+    }
+}
+
+/// TS `checkForUpdates(force, fetchTimeoutMs)` — daily-cached npm lookup.
+/// Without a fetcher, a stale cache resolves to "no update known" (latest =
+/// cached value if fresh, else `None`) and the cache is left untouched.
+pub async fn check_for_updates(
+    force: bool,
+    fetch_timeout_ms: u64,
+    fetcher: Option<&dyn LatestVersionFetch>,
+) -> UpdateCheckResult {
+    let current_version = get_current_version();
+    let cache = load_cache();
+    let now = cma_core::utils::now_ms();
+    let update_command = build_manual_update_command();
+
+    if !force
+        && let Some(cache) = &cache
+        && cache.current_version == current_version
+        && now - cache.last_check < CHECK_INTERVAL_MS
+    {
+        let has_update = cache
+            .latest_version
+            .as_deref()
+            .is_some_and(|latest| compare_versions(&current_version, latest) > 0);
+        return UpdateCheckResult {
+            has_update,
+            current_version,
+            latest_version: cache.latest_version.clone(),
+            update_command,
+        };
+    }
+
+    let Some(fetcher) = fetcher else {
+        // No network seam: skip quietly (cache stays as-is for the manager).
+        return UpdateCheckResult {
+            has_update: false,
+            current_version,
+            latest_version: None,
+            update_command,
+        };
+    };
+
+    let latest_version = fetcher.fetch_latest_version(fetch_timeout_ms).await;
+    save_cache(&UpdateCheckCache {
+        last_check: now,
+        latest_version: latest_version.clone(),
+        current_version: current_version.clone(),
+    });
+    let has_update = latest_version
+        .as_deref()
+        .is_some_and(|latest| compare_versions(&current_version, latest) > 0);
+    UpdateCheckResult {
+        has_update,
+        current_version,
+        latest_version,
+        update_command,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Startup gating + budget (scripts/codex.js half).
+// ---------------------------------------------------------------------------
+
+fn read_boolean_env_flag(name: &str) -> Option<bool> {
+    let normalized = std::env::var(name)
+        .unwrap_or_default()
+        .trim()
+        .to_ascii_lowercase();
+    match normalized.as_str() {
+        "1" | "true" | "yes" => Some(true),
+        "0" | "false" | "no" => Some(false),
+        _ => None,
+    }
+}
+
+fn is_startup_update_notice_debug_enabled() -> bool {
+    read_boolean_env_flag("CODEX_MULTI_AUTH_DEBUG") == Some(true)
+}
+
+/// TS `shouldLogStartupUpdateNotice()` — stderr TTY or DEBUG.
+pub fn should_log_startup_update_notice() -> bool {
+    std::io::stderr().is_terminal() || is_startup_update_notice_debug_enabled()
+}
+
+/// TS `readStartupUpdateNoticeBudgetMs()`.
+pub fn read_startup_update_notice_budget_ms() -> u64 {
+    let raw = std::env::var("CODEX_MULTI_AUTH_UPDATE_NOTICE_STARTUP_BUDGET_MS")
+        .or_else(|_| std::env::var("CODEX_MULTI_AUTH_TEST_STARTUP_UPDATE_NOTICE_BUDGET_MS"))
+        .unwrap_or_default();
+    if raw.is_empty() {
+        return DEFAULT_STARTUP_UPDATE_NOTICE_BUDGET_MS;
+    }
+    match raw.trim().parse::<i64>() {
+        Ok(parsed) if parsed > 0 => parsed as u64,
+        _ => DEFAULT_STARTUP_UPDATE_NOTICE_BUDGET_MS,
+    }
+}
+
+/// TS `resolveStartupUpdateNoticeTimeoutMs(budgetMs)` — 80% of the budget,
+/// min 1 ms.
+pub fn resolve_startup_update_notice_timeout_ms(budget_ms: u64) -> u64 {
+    ((budget_ms as f64 * 0.8).floor() as u64).max(1)
+}
+
+/// TS `shouldRunStartupUpdateNotice(rawArgs, normalizedArgs)` — skipped for
+/// BYPASS=1, pure help/version, and locally-handled auth commands.
+pub fn should_run_startup_update_notice(raw_args: &[String], normalized_args: &[String]) -> bool {
+    if std::env::var("CODEX_MULTI_AUTH_BYPASS")
+        .unwrap_or_default()
+        .trim()
+        == "1"
+    {
+        return false;
+    }
+    if is_pure_help_or_version_args(raw_args) {
+        return false;
+    }
+    if should_handle_multi_auth_auth(normalized_args) {
+        return false;
+    }
+    true
+}
+
+fn log_startup_update_notice_debug(message: &str) {
+    if is_startup_update_notice_debug_enabled() {
+        eprintln!("codex-multi-auth: {message}");
+    }
+}
+
+/// TS `showUpdateNoticeIfAvailable(rawArgs, normalizedArgs)` — budget-raced
+/// check + stderr notice. Never fails the launch.
+pub async fn show_update_notice_if_available(
+    raw_args: &[String],
+    normalized_args: &[String],
+    fetcher: Option<&dyn LatestVersionFetch>,
+) {
+    if !should_run_startup_update_notice(raw_args, normalized_args) {
+        return;
+    }
+    let budget_ms = read_startup_update_notice_budget_ms();
+    let fetch_timeout_ms = resolve_startup_update_notice_timeout_ms(budget_ms);
+    let check = check_for_updates(false, fetch_timeout_ms, fetcher);
+    let result = tokio::time::timeout(Duration::from_millis(budget_ms), check).await;
+    match result {
+        Err(_) => {
+            log_startup_update_notice_debug(&format!(
+                "update notice skipped: startup budget exceeded after {budget_ms}ms"
+            ));
+        }
+        Ok(result) => {
+            if result.has_update
+                && result.latest_version.is_some()
+                && should_log_startup_update_notice()
+            {
+                eprintln!("{}", format_manual_update_notice(&result));
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn manual_update_command_is_frozen() {
+        assert_eq!(
+            build_manual_update_command(),
+            "npm install -g codex-multi-auth@latest"
+        );
+    }
+
+    #[test]
+    fn notice_format() {
+        let result = UpdateCheckResult {
+            has_update: true,
+            current_version: "6.9.0".to_string(),
+            latest_version: Some("6.10.0".to_string()),
+            update_command: build_manual_update_command(),
+        };
+        assert_eq!(
+            format_manual_update_notice(&result),
+            "codex-multi-auth update available: v6.10.0; current: v6.9.0; run: npm install -g codex-multi-auth@latest"
+        );
+    }
+
+    #[test]
+    fn version_comparison_core() {
+        assert_eq!(compare_versions("1.0.0", "1.0.1"), 1);
+        assert_eq!(compare_versions("1.2.0", "1.1.9"), -1);
+        assert_eq!(compare_versions("2.7.1", "2.7.1"), 0);
+        assert_eq!(compare_versions("v2.7.1", "2.7.2"), 1);
+        assert_eq!(compare_versions("1.0.0+build5", "1.0.0"), 0);
+    }
+
+    #[test]
+    fn version_comparison_prerelease() {
+        // Release > prerelease of the same core.
+        assert_eq!(compare_versions("3.0.0-alpha.0", "3.0.0"), 1);
+        assert_eq!(compare_versions("3.0.0", "3.0.0-alpha.0"), -1);
+        // Numeric prerelease ordering.
+        assert_eq!(compare_versions("1.0.0-alpha.1", "1.0.0-alpha.2"), 1);
+        // Numeric < alphanumeric.
+        assert_eq!(compare_versions("1.0.0-1", "1.0.0-alpha"), 1);
+        assert_eq!(compare_versions("1.0.0-alpha", "1.0.0-1"), -1);
+        // Longer prerelease wins over its prefix.
+        assert_eq!(compare_versions("1.0.0-alpha", "1.0.0-alpha.1"), 1);
+        assert_eq!(compare_versions("1.0.0-alpha.1", "1.0.0-alpha"), -1);
+        // Garbage segments parse to 0.
+        assert_eq!(compare_versions("x.y.z", "0.0.0"), 0);
+    }
+
+    #[test]
+    fn budget_and_timeout_resolution() {
+        assert_eq!(resolve_startup_update_notice_timeout_ms(3000), 2400);
+        assert_eq!(resolve_startup_update_notice_timeout_ms(1), 1);
+        assert_eq!(resolve_startup_update_notice_timeout_ms(0), 1);
+    }
+
+    #[test]
+    fn startup_gating_help_and_auth() {
+        let raw: Vec<String> = vec!["--help".to_string()];
+        assert!(!should_run_startup_update_notice(&raw, &raw));
+        let auth: Vec<String> = vec!["auth".to_string(), "status".to_string()];
+        assert!(!should_run_startup_update_notice(&auth, &auth));
+        let exec: Vec<String> = vec!["exec".to_string()];
+        // May still be suppressed by BYPASS in the ambient env; only assert the
+        // positive path when BYPASS is not set.
+        if std::env::var("CODEX_MULTI_AUTH_BYPASS").unwrap_or_default().trim() != "1" {
+            assert!(should_run_startup_update_notice(&exec, &exec));
+        }
+    }
+
+    struct FixedFetcher(Option<String>);
+
+    impl LatestVersionFetch for FixedFetcher {
+        fn fetch_latest_version(
+            &self,
+            _timeout_ms: u64,
+        ) -> Pin<Box<dyn Future<Output = Option<String>> + Send + '_>> {
+            let value = self.0.clone();
+            Box::pin(async move { value })
+        }
+    }
+
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn check_without_fetcher_and_without_cache_is_silent() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        // No cache file in the sandbox → no update.
+        let result = check_for_updates(true, 100, None).await;
+        assert!(!result.has_update);
+        assert_eq!(result.update_command, build_manual_update_command());
+    }
+
+    #[tokio::test]
+    #[serial_test::serial(env)]
+    async fn check_with_fetcher_detects_update_and_caches() {
+        let _sandbox = cma_testkit::sandbox::EnvSandbox::new();
+        let fetcher = FixedFetcher(Some("999.0.0".to_string()));
+        let result = check_for_updates(true, 100, Some(&fetcher)).await;
+        assert!(result.has_update);
+        assert_eq!(result.latest_version.as_deref(), Some("999.0.0"));
+        // Cache written with the exact TS shape (2-space indent, no newline).
+        let raw = fs::read_to_string(cache_file_path()).unwrap();
+        assert!(raw.starts_with("{\n  \"lastCheck\":"));
+        assert!(!raw.ends_with('\n'));
+        assert!(raw.contains("\"latestVersion\": \"999.0.0\""));
+        // Second (non-forced) check hits the fresh cache without a fetcher.
+        let cached = check_for_updates(false, 100, None).await;
+        assert!(cached.has_update);
+        assert_eq!(cached.latest_version.as_deref(), Some("999.0.0"));
+    }
+}
diff --git a/crates/wrapper/tests/account_force_test.rs b/crates/wrapper/tests/account_force_test.rs
new file mode 100644
index 000000000..e79933089
--- /dev/null
+++ b/crates/wrapper/tests/account_force_test.rs
@@ -0,0 +1,188 @@
+//! Integration tests for the `--account` force-pin (#623) against a real
+//! on-disk accounts pool — ports the disk-backed assertions of
+//! `test/codex-bin-wrapper.test.ts` (§ "--account" cases) that the in-file
+//! unit tests cover only in pure form.
+
+use serial_test::serial;
+
+use cma_testkit::sandbox::EnvSandbox;
+use cma_wrapper::account_force::{
+    apply_forced_account_selection, resolve_forced_account_index, ForcedAccountOutcome,
+};
+
+fn v(args: &[&str]) -> Vec<String> {
+    args.iter().map(|s| s.to_string()).collect()
+}
+
+fn write_pool(sandbox: &EnvSandbox) {
+    let dir = sandbox.codex_multi_auth_dir();
+    std::fs::create_dir_all(&dir).unwrap();
+    let storage = serde_json::json!({
+        "version": 3,
+        "activeIndex": 0,
+        "accounts": [
+            { "accountId": "acc_1", "email": "account-1@example.com",
+              "refreshToken": "r1", "addedAt": 1, "lastUsed": 1 },
+            { "accountId": "acc_2", "email": "account-2@example.com",
+              "refreshToken": "r2", "addedAt": 2, "lastUsed": 2 },
+            { "accountId": "acc_3", "email": "account-3@example.com",
+              "refreshToken": "r3", "addedAt": 3, "lastUsed": 3 }
+        ]
+    });
+    std::fs::write(
+        dir.join("openai-codex-accounts.json"),
+        serde_json::to_string_pretty(&storage).unwrap(),
+    )
+    .unwrap();
+}
+
+#[test]
+#[serial(env)]
+fn resolves_selectors_against_the_scoped_pool_on_disk() {
+    let sandbox = EnvSandbox::new();
+    write_pool(&sandbox);
+    // ALL-DIGIT = 1-based index, always.
+    assert_eq!(resolve_forced_account_index("2").unwrap(), 1);
+    // Email + account id (case-insensitive).
+    assert_eq!(
+        resolve_forced_account_index("ACCOUNT-2@EXAMPLE.COM").unwrap(),
+        1
+    );
+    assert_eq!(resolve_forced_account_index("acc_3").unwrap(), 2);
+    // Out of range lists the pool.
+    let err = resolve_forced_account_index("99").unwrap_err();
+    assert!(err.contains("--account 99 is out of range (have 3 accounts)"));
+    assert!(err.contains("  2. account-2@example.com"));
+    drop(sandbox);
+}
+
+/// TS `String.prototype.toLowerCase` parity: `--account` selectors match
+/// ids/emails with FULL Unicode lowercasing, not ASCII-only — `--account`
+/// never falls back, so an ASCII-only mismatch would fail the run hard.
+#[test]
+#[serial(env)]
+fn unicode_selectors_match_case_insensitively_in_both_directions() {
+    let sandbox = EnvSandbox::new();
+    let dir = sandbox.codex_multi_auth_dir();
+    std::fs::create_dir_all(&dir).unwrap();
+    let storage = serde_json::json!({
+        "version": 3,
+        "activeIndex": 0,
+        "accounts": [
+            { "accountId": "acc_1", "email": "ä@example.com",
+              "refreshToken": "r1", "addedAt": 1, "lastUsed": 1 },
+            { "accountId": "acc_2", "email": "Ö@EXAMPLE.COM",
+              "refreshToken": "r2", "addedAt": 2, "lastUsed": 2 }
+        ]
+    });
+    std::fs::write(
+        dir.join("openai-codex-accounts.json"),
+        serde_json::to_string_pretty(&storage).unwrap(),
+    )
+    .unwrap();
+    // Upper-case selector vs lower-case stored email…
+    assert_eq!(resolve_forced_account_index("Ä@EXAMPLE.COM").unwrap(), 0);
+    // …and the reverse (lower-case selector vs upper-case stored email).
+    assert_eq!(resolve_forced_account_index("ö@example.com").unwrap(), 1);
+    drop(sandbox);
+}
+
+#[test]
+#[serial(env)]
+fn empty_pool_fails_with_login_hint() {
+    let sandbox = EnvSandbox::new();
+    // No accounts file at all.
+    let err = resolve_forced_account_index("1").unwrap_err();
+    assert_eq!(
+        err,
+        "codex-multi-auth: --account was set but no Codex accounts are configured. Run `codex-multi-auth login` first."
+    );
+    drop(sandbox);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn flag_wins_over_env_selector_and_publishes_zero_based_index() {
+    let mut sandbox = EnvSandbox::new();
+    write_pool(&sandbox);
+    sandbox.set_var("CODEX_MULTI_AUTH_FORCE_ACCOUNT", "3");
+    // Flag `--account 1` (index 0) wins over env `…FORCE_ACCOUNT=3` (index 2).
+    let outcome = apply_forced_account_selection(
+        &v(&["exec", "--account", "1", "status"]),
+        async |_args: &[String]| true,
+    )
+    .await;
+    match outcome {
+        ForcedAccountOutcome::Forward {
+            forward_args,
+            forced_index,
+        } => {
+            assert_eq!(forward_args, v(&["exec", "status"]));
+            assert_eq!(forced_index, Some(0));
+        }
+        other => panic!("expected Forward, got {other:?}"),
+    }
+    drop(sandbox);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn env_selector_used_when_flag_absent() {
+    let mut sandbox = EnvSandbox::new();
+    write_pool(&sandbox);
+    sandbox.set_var("CODEX_MULTI_AUTH_FORCE_ACCOUNT", "account-2@example.com");
+    let outcome =
+        apply_forced_account_selection(&v(&["exec", "status"]), async |_args: &[String]| true)
+            .await;
+    match outcome {
+        ForcedAccountOutcome::Forward {
+            forward_args,
+            forced_index,
+        } => {
+            assert_eq!(forward_args, v(&["exec", "status"]));
+            assert_eq!(forced_index, Some(1));
+        }
+        other => panic!("expected Forward, got {other:?}"),
+    }
+    drop(sandbox);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn fails_hard_before_spawn_when_proxy_inactive() {
+    let mut sandbox = EnvSandbox::new();
+    write_pool(&sandbox);
+    sandbox.set_var("CODEX_MULTI_AUTH_BYPASS", "1");
+    // The proxy gate is evaluated by the caller-provided closure (forward.rs
+    // wires is_runtime_rotation_proxy_enabled, which returns false under
+    // BYPASS); mirror that wiring here.
+    let outcome = apply_forced_account_selection(
+        &v(&["exec", "--account", "1"]),
+        async |args: &[String]| cma_wrapper::forward::is_runtime_rotation_proxy_enabled(args).await,
+    )
+    .await;
+    match outcome {
+        ForcedAccountOutcome::Error(message) => {
+            assert!(message.contains("--account requires the runtime rotation proxy"));
+        }
+        other => panic!("expected Error, got {other:?}"),
+    }
+    drop(sandbox);
+}
+
+#[tokio::test]
+#[serial(env)]
+async fn no_selector_returns_no_pin() {
+    let sandbox = EnvSandbox::new();
+    write_pool(&sandbox);
+    let outcome =
+        apply_forced_account_selection(&v(&["exec"]), async |_args: &[String]| true).await;
+    assert_eq!(
+        outcome,
+        ForcedAccountOutcome::Forward {
+            forward_args: v(&["exec"]),
+            forced_index: None
+        }
+    );
+    drop(sandbox);
+}